Introduction to Git
This document is a small introduction to using the program git for version
control. One way of thinking about version control is a system which tracks
changef to a document over time, similar to how 'Track Changes' works in word
processing software. There are several programs available for version control
(such as 'mercurial', 'subversion' and 'fossil'); git is widely used and may
be considered the industry standard. There is lots of material available for
learning it, and solving simple issues is often a web search away.
This guide outlines the bare minimum amount of knowledge required to get started
with using git. There's a lot more you can do with it once you're comfortable.
We'll be using the command line to interact with git, which is the best way to
learn how it works. A range of graphical user interfaces are also available if
you're more comfortable working in that way, but do try understanding how it
works from the command line first. This guide assumes basic knowledge of how to
use the command line on your system.
Creating a git repository
To get started, create a new directory (use your file browser or command line). Navigate into that directory in the command line. To create a git repository in the directory, type:
git init
A message will be printed indicating that a git repository has been created.
Tracking a file
Create an example file (e.g. example.txt). Add some text into it (anything you
like-try copying the text from this guide). We'll track this file. First, the
file is staged. Staging is useful for collecting together files which have been
changed as part of the same update. For example, you may have 10 files which
have been updated. Maybe you would like to collect the changes to five of them
as one version 'waypoint', and log the other separately. To stage:
git add example.txt
You can check what the status of the git repository is at any point by typing:
git status
If you execute this command, you should see that example.txt has been staged.
To finish committing the version to the tracking system, run:
git commit
This will open up a text editor with space for a commit message. This is simply a short annotation describing the version. Best practice suggests keeping this message below 80 characters, and to write the message as if you are continuing the sentence 'a git commit to...'. If you want to go into detail, write a short message in the first line, make a black line below it, and write your important details. Below is an example.
add an example file
This is a longer description of the commit, which can go into lots more detail.
It's still best to keep what you write concise, though.
Now, we have our first version committed. You can check all of the previous versions committed ('commits') by using:
git log
# (press `q` to exit the log)
Try editing example.txt, and run git status. Git should notice that you have
changed the file. You can then stage and commit the changes as described above.
Running git log afterwards will show the new version you have created.
Branches
Branches are a useful concept which allow multiple versions of a project to be tracked simultaneously. An example situation could be that you and a colleague have agreed to update separate sections of a document. Each of you creates a branch to work on in isolation, and you merge your changes when the sections are finished.
To create a branch:
git branch my-branch
Running git branch will give a list of available branches. Once a branch has
been created, you 'move into' it by performing a checkout:
git checkout my-branch
If you're wondering which branch you're on, git status will tell you.
Once your in the branch, you can commit your changes as described above, add new files, etc. When you're ready, you can merge the changes with the main branch. First, move back into the main branch:
git checkout main
Then, merge the changes from the branch you just edited:
git merge my-branch
Git will then figure out how to combine the files in the main branch with the files from another. There may be conflicts which require intervention, in which case, git will let you know.