Source Control

Almost every open source project today is available on GitHub. GIT is an open source distributed version control system. My decision to use GIT for my source control was a logical and easy choice on my part.

I am not going to detail the installation and configuration of GIT here. There are lots of tutorials out there. I installed both GIT (command line version) and GitHub Desktop (a nice GUI interface) on both of my computers. An interesting side note is that the newest version of GitHub Desktop is also hosted in Electron. (Beginning to see a pattern here?)

What I am going to talk about is my choice to use GitHub Desktop to control my source code locally instead of pushing it to GitHub on the internet.

Again, my decision was centered around finding something that I could use on both my Windows and Mac machine that would give me a consistent user experience so I don't have to remember "how to do things differently" when switching between computers. I also wanted the ability to keep my source code locally ... I'm not saying I don't trust GitHub ... I do and I use it to host this project which I call The Smoke House Project (because of my love of smoking meats in my wood smoker). I just feel more comfortable with my source code residing on my local NAS under my roof ... it's an old school thing!

Creating Your Repository

Getting GIT to work is relatively simple once you understand how it works. It can be frustrating if you just dive in and try to force it to work ... believe me ... I know! So I am going to walk you through the process ... step by step. I am doing this exercise on my Windows machine but you can do this on a Mac as well. You enter the exact same commands in a terminal window.

1. Create a directory where you want to store your collection of local code repositories. It can be on your local computer or on a NAS. I use a NAS because I want to be able to contribute to my projects using both of my computers.
2. Map a network drive to your new folder. This is not required but it just makes life a little easier.
3. Open a command prompt in your new directory.
4. Create your first repository by entering the following command:

   

   
   

5. This creates a bare repository that is ready to use.

NOTE: This creates the GIT repository or data store that holds all your source files and tracks changes.It is NOT a directory to be used for development! We will get to that in the step next.

NOTE: You can create as many project repositories as you like by simply running this command and specifying a new repository name as the last parameter.

There are some good resources here if you want to explore the git init command in detail.

Cloning Your Repository

Now that we have our repository and an empty first project created it is time to open the GIT Desktop and clone our repository to our computer so that we can start contributing.

1. Open the GIT Desktop app and select FILE then CLONE REPOSITORY.
2. Select URL in the top selection bar.
3. Enter the path to the new project directory you just created. In my case it is Z:\GIT\test-project.git
4. Enter a path to a directory on your local computer where you want the development or working code for your project to reside. This is where you will be doing code changes and making contribution to the project.

   

   
   
5. Click the CLONE button.

NOTE: A red warning box may appear in this dialog telling you the destination directory already exists. You must enter a path to a non-existing directory because the wizard will create a new folder for the project to reside in.

NOTE: Our example project is currently empty so the resulting new working folder will only contain a hidden .git folder. If the project in the repository contains existing source code, it would all be copied into this new working folder. The hidden .git directory contains all the information required by GIT to link the working folder to the repository.

Congratulations, you now have a registered working folder so that you can contribute to your new project!

Using Your Repository

Open Visual Studio Code and then select FILE / OPEN FOLDER and select your new working folder. The code editor will open your project and automatically link it to your new repository using the hidden .git directory information. You can now safely begin contributing and editing code in your project!

Now if you want to contribute to the project on a different computer you must install GitHub Desktop on that computer, then follow the instructions to CLONE the project. This process is the same as cloning a project from GitHub over the internet.

Your new GIT repository is now working and managing version control on your project on your local network instead of the internet!

Cloning The Smoke House Project into your Private Repository

OK, now you have a private repository set up with a test-project in it. Now it is time to get The Smoke House Project from GitHub and save it as a base project in your private repository. You would do this every time you wanted to use The Smoke House Project as a base or template for a new project on your local machine.

Note: The Smoke House Project is a collection of repositories and we are interested in the "Applewood" repository here.

NOTE: You must create a new empty project in your local repository before doing this! 

1. Create a temp directory to hold the clone from GitHub.
2. Open a command prompt in your new temp directory.
3. Run command :> git clone --bare https://github.com/SmokeHouseProject/applewood.git

   

   
   
4. CD (Change Directory) into applewood.git
5. Run command :> git push --mirror Z:\GIT\test-project.git

   

   
   
6. Delete the temp directory and it's contents

We now have a local copy of The Smoke House Project saved in our new repository!

Now follow the instructions above to Clone your new repository to a working directory.

NOTE: Certain folders like the "node_modules" contain content that intentionally is not included in the source code repository. This means that when you clone a project from the repository into your working folder you must populate the folders like "node_modules" before you can use the project. This is done by opening a command prompt in the working folder and running a command to fetch and populate the folder with the required packages. For our project do the following:

1. Open command prompt in root of the project folder
2. Run command 'nvm use 10.14.0'
3. Run command 'npm install'

There are also some specific instructions in the README file of the project. Please follow those instructions before using the project! You must do this every time you clone a project form the repository to a working directory!

There are some good resources here if you want to learn more about mirroring or copying repositories.


NOTE: There are two scenarios for creating a new local repository.

1. You want to clone the existing Applewood repository from GitHub and work with the completed project. (You may want it to copy snippets from or use in it's entirety.)
• Create new empty local repository
• Clone The Smoke House Project from GitHub to a temp folder
• Push the download from temp to your new local repository
• Clone your new local repository to a working folder
2. You may want to create an empty repository so you can follow along with this tutorial.
• Create new empty local repository
• Clone it to a working project folder

Ideally you will have two new repositories. One containing the original Smoke House Project and an empty one that you can use to follow along step by step. This also means you will have two working project folders, one for each project.