The more I collaborate with friends and colleagues, the more I appreciate the tools provided by git. It is particularly useful for working on tex files in parallel. There is, however, a bit of a learning curve to git. It is not easy to pick up, but I think the benefits far outweigh the time it takes to learn the basics. Specifically with editing tex files, git helps me:
And that is only a few of the benefits; well, the ones I can think of in this moment!
There are many places to learn how to use git and the underlying structure of it. If you are interested and want to find some places to start, I recommend using YouTube. The video below is the first in a number of videos introducing a lot of the basics of git. It is definitely a good starting point, and if you want to learn more about a particular topic, you should have the tools at your disposal to find more information.
I have a file I use and have shared with my collaborators to help me remember key functions in git. You can view my Git Cheat Sheet below. It is a self-contained html file, so you can download the link and refer to it later if you ever need it.
Creating a new branch from current location.
$ git checkout -b <branchName>
Deleting a branch and its remote. In the last line, do not include prefixes like origin/<branchName>. Warning: do not delete the branch you have checked out!
$ git checkout master
$ git branch -d <branchName>
$ git push origin --delete <branchName>
To add (or track the changes of) files. You can do it individually, but this will add all the files that have been changed.
$ git add -A
The backbone of git. Be descriptive and succinct.
$ git commit -m "<myTitle>"
If a one-line title is not enough, then one can open vim (git’s default terminal editor).
$ git commit
This will likely open vim. If you do not know the hotkeys, you should hit insert which will let you start typing like normal. It should be formatted like the following.
Title for my commit
My description that gives a bit more detail, or lots more!
To save your message and quit first hit esc then type :wq! and hit enter.
There are two fundamental ways to combine branches: merge and rebase. Warning: there are warnings about rebase on the internet, but they seem… rare. Be careful.
Ideal merging situation is a fast-forward merge. Essentially there is a well-defined set of steps for git to update one branch to another. The other is recursive, which requires examining three commits on the tree. This has the potential to create merge conflicts. Merge conflicts need to be dealt with and will be displayed in status.
A merge conflict changes the files conflicted. In particular, the lines of code that are affected have the following structure.
<<<<<<< HEAD
Other code
=======
Your code
>>>>>>> <branchName>
Suppose you want to merge branch myBranch onto some other branch mainBranch. You may have to resolve merge conflicts. Afterwards, you will need to commit the resolutions.
$ git checkout mainBranch
$ git fetch
$ git merge myBranch
To verify you merged everything, you should see myBranch listed.
$ git checkout mainBranch
$ git branch --merged
Suppose the branch movedBranch has moved ahead of your branch myBranch. To rebase your branch from where the other one ends.
$ git checkout myBranch
$ git fetch
$ git rebase movedBranch myBranch
A handy tool to determine where you are located on the repo tree. Hands down most useful command here.
$ git log --graph --oneline
Made changes to files on a branch you didn’t want to make changes to? Use stash. Suppose you want to take file changes from branch wrongBranch to correctBranch.
$ git stash
$ git checkout correctBranch
$ git stash pop
A handy tool to see the status of your location, e.g. files staged for commit and how far ahead from origin/<branchName> you are.
$ git status
To just download all updates to your repo.
$ git fetch
Downloading all updates and merge to your current branch. This runs fetch and merge. The default is origin <branchName>.
$ git pull
To push all your commits to your current branch.
$ git push origin <branchName>