This document is a quick-start dive into using Git for version control, branching, and collaborative work on projects. It is intended to be a primer on core concepts. For more information, see the Git Docs.
The best way to use Git + Github (or any Git hosting) is via SSH. To do this you need an SSH Key (Mac/Linux):
ssh-keygen
Then output the contents of the public key:
cat ~/.ssh/id_rsa.pub
The output of the above command can then be given to the Git hosting service, allowing your system to authenticate.
This can be done using PuTTY on Windows
Installing Git is just a matter of following the instructions for your OS. Once installed you'll want to setup some basic configuration settings:
git --config global.email "you@youremail.com"
git --config global.username "your-username"
The above will help associate you with your actions using Git.
Inside of the root of the project (repo) you're working in, run the following:
git init
The above will create a .git directory in the root, and at this point any action inside the repo (and all sub-folders) will be tracked.
Not everything in a project should be commited to the repo. For instance, things like dependencies, or log files don't neccesarily need to be maintained in source version control. To prevent these files and directories from being included create a .gitignore file in the root of the repo:
/some/folder/
some_file.log
/**/*.log
Git uses remote origins as "destinations" for maintaining the git history. If you create a repo on Github (for example) you can find a git SSH URI which should look something like this:
git@github.com:<ORG_OR_USER>/<REPO_NAME>.git
You can then associate this as the remote origin using the following command:
git add remote origin git@github.com:<ORG_OR_USER>/<REPO_NAME>.git
With the above in place, you'll now be able to push changes to the remote and your git history will be present in the repo on Github.
The primary focus of Git is tracking code changes over time. The way to do this is to use add and commit to "save" changes.
For example, if you created a new file test.txt and wanted to track that you could do the following:
- Use
git statusto see the status of tracked/untracked files, you will see the file in red because it is not currently added - Use
git add .to add all untracked files. Alternatively you cangit add test.txtto only add the file you just created. Runninggit statusnow would show the file as tracked (green). - Use
committo make the commit. The commandgit commitalone will open your default editor so you can leave a commit message. To do this all from the command you can use the following:
git commit -m "your commit message"
Now that a commit has been made, the commit can be pushed to the remote repository using the following command:
git push origin master
The above simply pushes from the local, to the remote, on the branch master
Branching allows you to create a set of commits in a way that maintains them as a separate "thread". This means that instead of commiting directly to your main (typically master) branch, you commit to a branch that can contain a subset of changes related to a specific feature, bug fix, etc.
To create a new branch, run the following:
git checkout -b <YOUR_BRANCH>
Your branch is now whatever was entered in the last argument, following the -b flag which indicates that you are creating a new branch. All commits will be on this branch. You can push to this branch similarly to how you pushed to master in the section above:
git push origin <YOUR_BRANCH>
When work is completed on a branch, that branch should be merged into the master branch (or in some cases, another branch; you can branch off other branches as needed)
To merge all the commits on a branch back into the parent, use the following:
git merge <CHILD> <PARENT>
So, if you wanted to merge a branch called some-feature into master:
git merge some-feature master
Just like how you push to a remote, it's important to stay up to date, especially if you're working on a project with multiple contributors. You can pull the latest from a branch using the following:
git pull origin <BRANCH>
The fetch command allows you to pull all remote branches, as you don't locally "know" what branches exist on the remote. The easiest way to do this is:
git fecth --all
Once you've run the above command, you can checkout a remote branch that you fetch'd using the checkout command, similar to how you created a new branch:
git checkout <SOME-BRANCH>
This will then switch you to working on that branch, which is now local.
Tagging is typically used to mark releases. Releases often (should) use semantic versioning (semver). This looks like:
<MAJOR>.<MINOR>.<PATCH>
If you wanted to tag a first stable release, you could do the following:
git tag 1.0.0
Then subsequent patch or minor releases can use the same convention, incrementing the correct part of the tag, for example git tag 1.0.1 for a patch or bug fix, 1.1.0 if you're releasing a new feature, and finally, incrementing the major if this is a breaking change: 2.0.0.
Once you have created a tag you can push that tag using the following:
git push --tags
There is a lot more to Git, and the above commands really scratch the surface. However, a solid understanding of the above will get you very far in working both individually, and in teams, on projects using Git.