This document is here to help NetSurf developers who are more used to
non-distributed revision control systems, or to DVCSs which are not
git. It also contains a few helpful hints for people used to
it's worth a skim even to those who think they know it all already.
Git is one of the least obvious, least intuitive distributed revision
control systems out there. However it is also very powerful and very
Git appears to have won the DVCS race for the most part, and as
such, NetSurf uses it.
Every commit you make with
git contains an identity. (Actually you can
differentiate between the identity of the author of a patch and the
person committing it to the repository if you want.) As such, you must
git who you are.
git config --global user.name "My Name"
git config --global user.email firstname.lastname@example.org
Note that if you don't specify
--global the name/email address will
only be local to the
git tree you are inside when you run the command.
The first time you make a commit, if you have not configured your
git will give you a reminder.
It's well worth running:
git config --global push.default current
Since it tells git to only push the branch you're on.
git repository is a project. As such, NetSurf has many
repositories. NetSurf's repositories reside on the NetSurf
Gitano instance. We will refer to this as
the server from now on.
You acquire a copy of a repository by asking
git to clone it.
git will create a directory named after the repository and
clone all the branches in that repository into it.
When you have a local clone of a repository, we refer to that as a
Git may also refer to it as a working tree and it is where
changes are made and commits are done.
Each repository may have many branches.
Git keeps them tucked away,
showing you only one at a time in your tree. You can list your local
By default, a fresh clone will only contain one branch called
which is the equivalent of Subversion's trunk.
You can switch between local branches with:
git checkout branchname
Different bits of
git documentation may also refer to refs. In
branches, tags, etc are all represented by their commits. To give those
commits useful-to-a-human names,
git has the concept of a ref which
is simply a name given to a commit. Refs in the namespace
are referred to as branches.
There are no traditional revision numbers in
git. Instead each commit
is given a unique identifier. It is a long (40 character) hexadecimal
string but it is also commonly shortened to its first 7 characters. For
example, at the time of writing, the tip of the
master branch in the
NetSurf repository was
git tree is also a full local copy of the repository,
git keeps track of the server's copy of the repository in a data
structure called a remote. The default name for a remote is
and you will see that crop up in various places as we continue.
You can update your local view of the server with the command:
git remote update
Or, assuming you're on
master you may find pull to be of more use:
If you pull then
git first updates its view of the remote, and then
attempts to merge in changes from the remote into your local branch. If
you've not made changes locally then this will be done by
fast-forwarding you to the server's revision.
You can see the branches available on any remotes you have registered in your tree with:
git branch -r
We recommend that everyone work on branches, merging to
when work is ready for others. In the past we've all worked on
because it was such a pain in Subversion to merge work. However one of
git's strengths is its merge functionality so this habit should end.
Before making a new branch, it's customary to ensure that you've got everything up-to-date from the server:
git remote update
Then you can create a new branch, from the server's idea of
git checkout -b username/branch origin/master
You should put your own username in for username (note it should be
the username which the server has for you. You can find that out by
ssh email@example.com whoami).
For the branch name, give it something reasonably descriptive but not
too long. For example
fandango-experiment is good, where
experiment-with-new-layout-engine-idea is probably too long.
origin/master is where you tell
git that you want to track the
master branch of the
origin remote. This not only gives you a
starting point for your branch, but also informs
git where to get
changes from if you run
git pull while you have that branch checked
To then inform the server of your new branch, run:
git push origin username/branch
When you wish to inform the server of new commits on your branch, you can subsequently just run:
To delete a branch from the server when it is no longer required:
git push origin :username/branch
You can make any amount of local changes before you commit, although we
recommend each commit be a reasonable self-contained "patch". Obviously
it is better to commit early and often; and
git does contain a variety
of tools for helping you to turn a long line of small commits into a
neater set of commits ready for merging. We're not too bothered about
that with NetSurf for now; but if you want further reading on the
subject, go and search the web for git rebase.
You can ask
git about your working tree any time you like with:
You can see changes in your working tree which you've not told
about yet, with:
When you have edited the code and you are ready to commit, you should run:
git add filename another/filename etc/etc/etc
You can run
git add as many times as you like. Each time you do,
you're saying to
git I want you to remember this file just like it is
If you need to remove files then run:
git rm filename
You can see the diff which
git has prepared for committing, with
git diff --cached
Once you're happy you've told git about any edited, new or deleted files, you can run:
This will pop up an editor, telling you what will be committed and
encouraging you to write a change comment. The first line of the change
comment should be short (60 or so chars or less) and pithy. It will be
shown on the IRC channel as the commit message and also forms what
refers to as the short log message. The rest of the message (ideally
separated from the first line by a blank) should explain what you did
and why. Normal good commit message etiquette applies here.
You can see the log with:
Don't forget to
git push your commits to the server if you want anyone
else to see them.
Since we're encouraging work on branches, we also need to know how to
merge those into the
master branch. In order to keep things neat and
tidy, we ask that branches be merged in the following way:
# Switch to the master branch
git checkout master
# Ensure we're up-to-date relative to the server
# Merge the local branch in
git merge --no-commit --no-ff username/branch
# Review the changes here (git diff --cached)
# Commit the changes
Note that the commit will default to a message about the merge. That is
sufficient, although obviously any more useful message would be
appreciated. If the branch is not a local one, but one retrieved from
the server, then simply insert
origin/ in front of the branch name (so
origin/username/branch) to tell
git the location of the
Once the commit is done on
master you can
git push it to the server.
The options to
git merge are important. The
to leave the tree at the point that it has done the merge but hasn't
committed it to the branch. By default,
git will commit merges which
had no conflicts. Since our code base is complex this is not always
sufficient, hence the review step above. The
prepare a merge commit. Without it, if the
master has not moved on
from where the branch was created,
git will instead simply shunt the
commits onto the
master branch. While not a bad thing in and of
itself, this would mean that when you did
git push the
would announce every single commit from the branch.
To merge from the "foo" branch of Somebody's github clone of the NetSurf repo we can do this:
git remote add somebody
git remote update somebody
git merge --no-ff --no-commit somebody/foo
git diff --cached
Check that the diff shows what we want to merge. If so, commit it.
If you don't want to keep the remote around:
git remote rm somebody