Git Best Practises

Git is a flexible version-control system that is well-suited for software development, be it with a centralized server (Github, in our case), or in a completely decentralized setting.

A Git repository is a set of unique commits that form a directed acyclic graph (DAG) like this:

A---B---C---D---E---F---  master
     \     /     \
      G---H       I---J---  feature

We say that E is a child of D, and that D has two parents, C and H. The ancestors of D consists of A, B, C, G, and H. The descendants of D are E, F, I, and J.

If you know how to read this diagram, you know enough about DAGs for our purposes.¹

A commit typically represents a state of the file tree (the directory tree you get by checking out a revision), together with its complete commit ancestry. So you get different commit ids (represented as hexadecimal SHA1 hash codes) if you

• commit a change, commit the inverse of that change, and commit the original change again;
• change the commit message of your last commit (with ‘git commit --amend’);
• take some part of the commit graph and attach it somewhere else (‘git rebase’);
• make any change to a commit that is an ancestor of the commit in question.

In many respects the commit history we create with Git is a narrative that tells us (and others) how the code evolved to its current state.

Indeed, committing changes has a lot in common with telling a story, and that story can be interesting or boring, it can be presented in a logical way or totally confusing, even if the final code in both cases is the same.

And while there are different styles of telling the story well, a badly told narrative will make us all suffer. So please think about the logical order in which your changes make most sense and formulate and format your log messages appropriately.²

Git commands tend to be focused on one task.³ As a consequence, what the user perceives as one logical step may require two or three consecutive command calls. This helps in understanding what you are doing, and when something goes wrong you know where exactly the problem occurred.

However, if you prefer to combine several elementary git operations into one command call (say, committing and pushing), or don't want to type the same command-line options over and over again, you can of course create a shell script, or you can define a Git alias. For example, after running

git config --global alias.where 'rev-parse --short=12 HEAD'

you will have a new git command ‘git where’ that tells you the SHA1 hash of the current HEAD commit. Git aliases automatically inherit some niceties like command completion or a --help option.

As in other contexts, it is a virtue to not become too dependent on such helpers, lest you forget what you are doing, have a hard time communicating with others and feel lost in environments where those helpers are missing.

The Pencil Code comes with a ‘git pc’ script that provides some combined operations. Run ‘git pc -h’ to get a list of available sub-commands.

\label{Section-almost-panicking}

… for I'm afraid something got lost, although I know this is not the case because I stayed away from the commands in Table \ref{Table:How-to-lose-changes}.

\bigskip

Here is how to see almost every change⁷ that was ever⁸ known to git:

gitk --reflog --all
# or
tig --reflog --all
# or, without graphics,
git reflog --all --glob='stash*'

# If you prefer melodramatic command names, try
git pc panic

If you want to also see dropped stashes, you can use

git pc panic --full

A merge commit adds a new connection to parts of the Git graph. For example, if we have the following situation

A---B---C-----  master
     \
      F---G---  feature

and want to bring the changes from branch feature to master, we can merge feature into master and get

A---B---C---D---  master
     \     /
      F---G-----  feature

In the pure DAG sense, the two parents C and G of the merge commit D are completely equivalent, but for reasons discussed below, we want to make sure we merge feature into master (so C is the first parent and G is the second parent), not the other way around.

You remember our narrative metaphor? If you always merge your commits or groups of commits because you don't want to modify history, you are narrating in a diary or chronicler's style.

In the example above, we have a second option to bring the feature branch's changes into master, by creating new commits that contain those changes, but start from the state C, not B:

A---B---C-----------  master
         \
          F'---G'---  feature

We say that we have rebased the commits F and G from B onto C.

Rebasing modifies history, which is only permissible as long as this history is local. So don't rebase published commits. The commits that are eligible to rebasing are the ones displayed by

gitk origin/master..master
# or
tig origin/master..master
# or, without graphics,
git log origin/master..master

Even if the new commit F' may introduce the same textual difference as the original commit F, the file-tree state it represents is completely new and there is no guarantee that it will e.g. compile, even if both, C and F do.

Once you finish the rebase, you appear to have lost the original change F by pretending that you were applying a change F' in the first place.⁹ That's perfectly OK, as you will no longer be interested in the original change when the new version gets part of the Git narrative.

\bigskip

Rebasing is not an exclusive option. Even if you routinely rebase your local changes, you will want to merge longer-lived feature branches.

In terms of narrating, rebasing allows you to use letter style, where you bring facts into logical frames and order them accordingly (because nobody would want to read your stream-of-consciousness letters).

Here is the decision matrix for merging vs. rebasing

In short, use merging when you are afraid – but you know from Sec. \ref{Section-dont-panic} that you needn't be afraid.

\label{S-developing-on-master}

Suppose you just started developing code on master. Your branches look like this (A and B are commits, the `o' is just a visual connector):

--A---B-----  origin/master (remote branch)
       \
        o---  master (local tracking branch)

\bigskip

Despite its name, the remote branch exists only on your computer. It represents what is known about a branch called master on the server and serves for synchronization with the server. You cannot directly commit to this branch.

The tracking branch reflects how you would like the server branch to look like.¹²

\bigskip

Now you commit some changes X, Y to your local tracking branch:

--A---B----------  origin/master
       \
        X---Y----  master

and want to push them to the server. If the server is still at commit B, this will result in

--A---B---X---Y-----  origin/master
               \
                o---  master

and you are done.

However, if somebody has committed changes to the server before you push, you will get an error message¹³:

To [...]
 ! [rejected]        master -> master (fetch first)
error: failed to push some refs to [...]
hint: Updates were rejected because the remote contains work that you do
hint: not have locally. This is usually caused by another repository pushing
hint: to the same ref. You may want to first integrate the remote changes
hint: (e.g., 'git pull ...') before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.

Before you can fix the problem, you need to ‘git fetch’ to update the remote branch:

--A---B---C---D---E---  origin/master
       \
        X---Y---------  master

Now your task is to bring the two lines of development together, and you can either do this using rebase, or using merge.

• When you are working on one topic and expect more than a handful¹⁶ of changes, consider using a feature branch.
• When you are collaborating on a topic with somebody else and your changes are not yet ready for the others, use a feature branch.

To work with a feature branch, just go to the latest commit of master (the later you start the branch, the fewer conflicts you will create),

git checkout master
git pull --rebase

and create the branch

git checkout -b cool-new-feature

\bigskip

If that branch is long-lived, you will want to occasionally merge master into it.¹⁷ Say, you have this situation

--A---B---C---D---E---  master
   \
    N---O---P---Q-----  feature

Run

git fetch origin  #  update origin/master from the server
git stash         # if you have uncommitted local changes

Then do

git checkout master            # check out your local tracking branch ...
git pull --rebase              # ... and bring it up to date

git checkout cool-new-feature  # go back to your feature branch
git merge master               # do the actual merge

to obtain

--A---B---C---D---E-----  master
   \               \
    N---O---P---Q---R---  feature

There are some shorter variants to this procedure. You can use our ‘git pc’ script like this:

git fetch origin  #  update origin/master from the server
git pc ff-update master  # update master without checking it out
git merge master         # do the actual merge

or you could directly merge the remote branch

git merge origin/master

although this is less common than merging the local tracking branch.

After merging, don't forget to

git stash pop

if you have stashed changes before you merged.

\bigskip

When your branch is ready for merging back, you do

git checkout master
git pull --rebase           # bring master up-to-date
git merge cool-new-feature
[test]
git push

The topology now looks like this:

--A---B---C---D---E---F---G---H---I--- master
   \               \             /
    N---O---P---Q---R---S---T---U      feature

\bigskip

What if that push failed due to somebody committing new changes upstream?

No problem. We tag the first merge attempt and merge that tag to the updated upstream branch:

# remember, we are on master
git push   # fails: "! [rejected] master -> master (fetch first)"

git tag previous-merge-of-cool-new-feature
git fetch                       # update origin/master
git reset --hard origin/master  # update local master branch
git merge previous-merge-of-cool-new-feature
[test]
git push

The narrative now says: We have tried to merge cool-new-feature into master, but failed to push that, so we then merged that first merge into master and pushed. That may be more detail than we wanted (and more steps than we anticipated), but describes exactly what happened:

--A---B---C---D---E----F-----G----H---X---Y--- master
   \               \               \     /
    \               \               I---o
     \               \             /
      N---O---P---Q---R---S---T---U            feature

\bigskip

Using feature branches with appropriate granularity, you tell the story in a kind of novelist style. Actually, the metaphor falls short in this case, as your audience has the choice to read just a synopsis (by looking at the main branch only) or go into small details (reading the commits inside the feature branches).