Git howto

This is a guide to Working with freeplane's git repository. The first part covers the commands you need the most, while the second part ("Knowledge Base") adds some commands for special tasks such as undoing commits or reverting files (currently there is some redundancy between the two which we will remove soon).

I learned to use git with the help of an excellent German Open Source Press book on git.

You can (and probably want to) use eclipse for most operations. We try to explain this in each section, but it is a good idea to read the EGit documentation. Some operations, such as creating remote branches should be applied with the command line only (in order to make sure that tracking branches are setup correctly).

NOTE: Some instructions cover only the temporary freeplane repository on github, it will need to be adapted to the sourceforge hosting service.

There is a fun Google Tech Talk by Linus Torvalds on git.

Quickstart Guide

This section is meant to be as brief as possible while still explaining the necessary commands a bit so that you understand what you are doing.

Installation / Configuration

Install git as [http://git-scm.com/book/en/Getting-Started-Installing-Git described here].

You probably want to use the latest Eclipse (use Eclipse for RCP and RAP Developers) with EGit (Eclipse-git) plugin (integrated by default into recent eclipse builds). Although EGit comes with its own git implementation JGit, we rely on a native git for some commands, so please install the native git as described above, too.

The author details (which will be recorded for each changeset) can be set globally:

$ git config --global user.name "<Firstname> <Lastname>"
$ git config --global user.email "<email address>"

Initial checkout ("clone")

Create directory for git repositories:

$ cd $HOME
$ mkdir git
$ cd git

Create a local copy of the (whole!) git repository by cloning (git-speak for "checking out"):

$ git clone https://github.com/fnatter/freeplane-git.git freeplane
$ cd freeplane

This will take 5-20 minutes depending on your network connection.

This will create a local copy of the complete history and all branches. Therefore it is possible to develop and make commits offline and only connect for the purpose of getting changes from other devs ("pull") or sending your commits to a remote branch ("push").

In Eclipse/EGit you have to select the clone option in the Git Repositories View on a repository with the above URL, then enter credentials, choose all branches (!), then accept the defaults or choose a different location (for the local copy of the repo) check import all existing projects after clone finishes and be patient (should take <10 minutes). Afterwards, delete the freeplane_mac project unless you're on Mac, and close the freeplane_ant project. Finally, run the ant-build in freeplane_framework.

Working with branches

Freeplane follows the general git convention to have prefixes separated from the name by a '/', i.e. 'docear/trunk'. The main branch ("trunk") is termed master in git. However, for the docear main branch, we use 'docear/trunk'.

Here are the basic steps for working with branches:

Step 1: checkout parent branch

Find and checkout original source branch 'branchname (the branch you want to base your work on, usually master) to the local work space:

• Using command line git:

# fetches the remote (tracking) branch (not necessary if you just cloned the repo)
$ git pull 
# switch to branchname
$ git checkout <branchname>

• Using Eclipse/EGit:
  • Team->Pull fetches the remote (tracking) branch (may not be necessary)
  • Team->Switch To->New branch..., select Source ref = refs/remotes/origin/<branchname>

Step 2: create your local branch

Create + check out your own local branch based on the original branch: Since branches are really really cheap in git, it makes sense to create a branch for most development tasks (especially if you want a review before you integrate into master!). The following command creates a new local branch <devbranch> and switches to it:

$ git checkout -b <devbranch>

In EGit you can do Team->Switch To->New Branch..., then make sure you use the right Source ref (should be refs/heads/master if the parent branch is master).

Step 3: Work locally with your branch

Please read chapter 2.2 of the official git book in order to get started with working with git locally. You should understand how to stage and commit changes. Here are some basic steps:

• modify files...
• add the modifications to the index:

$ git add foo.java # (Team->Add to index in eclipse)

• create a commit from the changes in the index:

$ git commit [-m message] # (Team->Commit in eclipse)

(if you omit -m then you will be prompted for a commit message)

• create more commits, this is all done locally!
• look at the commit graph:

$ git log # might want to use gitk

Step 4: Push your changes to the repository

Setup git so that only the current "upstream" branch gets pulled/pushed (instead of pushing all branches that have an upstream tracking branch which can be confusing!):

$ git config push.default tracking

Note: this option is ignored by current EGit. On EGit you get the same behavior by selecting Team->Push To Upstream.

Publish ("push") your branch (including the commits you made) so that others can see (and review!) it. Currently it's best to do this on the command line, because -u sets up the tracking branch properly (make sure you use the same name!):

$ git push -u origin <devbranch>

You should see a message like:

Branch user/dev1 set up to track remote branch user/dev1 from origin.

(When pushing from eclipse you have to configure the remote tracking branch manually!). In any case (tracking branch configured automatically or manually), Team->Push to Upstream will push the current branch to its (configured) remote branch on origin.

Step 5: Development cycles

Follow the cycle:

$ git checkout <devbranch>

• pull other people's changes on your devbranch:

$ git pull
# you might have to resolve conflicts: (might want to use 'git mergetool'
# or Eclipse/EGit)
# git will place <<<<<<<<<< and >>>>>>>>>> comments to show the locations of the conflict(s)
for each conflict x:
  1. resolve conflict in x, remove markers
  2. git add x # mark x as resolved

• you can use:

$ git reset --hard

to undo the merge but this will throw away all uncommitted changes(!)

• commit the conflict resolution(s):

$ git commit [-m message]

• create local commits

  # in short: git add file; git add file2; git commit

• merge changes from master (necessary to test your feature and to make Step 6 easier)

$ git pull origin master

• push the result of the merge with master to your dev branch (always run git push with --dry-run first!)

$ git push [--dry-run] # same as git push origin <devbranch> because tracking is set up

Step 6: Merge your development into master

1. When you are done with your branch, and you have completed a code review of your dev branch, it should be merged into master (!) As a new developer, you must let a more experienced developer do this!

$ git checkout master
$ git pull
$ git merge <devbranch>
$ git push [--dry-run]  # same as git push origin master because tracking is set up

Overview of the steps

1. The remote repository is cloned from origin (sourceforge). You now have a complete local copy of the repository including all branches and the complete history.
2. A new local branch user/newdev is created and checked out.
3. This branch is created on the remote side too (pushed, with -u to setup the tracking correctly).
4. After some development on that branch, you want to integrate this with changes in master. This is done by pulling from the remote master branch on origin.
5. After having checked the merge (pull = fetch + merge), you push the integrated user/newdev1 branch to its remote counterpart.
6. You are done with development on user/newdev1. In order to merge your changes into master, you switch to the master branch (git checkout master) and update it (git pull).
7. The local user/newdev branch is merged into the local master branch.
8. After having checked the result of the merge, it is pushed to the remote master branch.

Knowledge Base

This section contains useful information for working with git, including stuff like checking that tracking branches are set up correctly, details about working with branches, undoing commits/reverting files, and a bit more.

Checkout in more detail

Checking out is termed cloning in git speak:

$ cd ~
$ mkdir git
$ cd git
$ git clone https://github.com/fnatter/freeplane-git.git freeplane

If you want/have read-only access, use this as the last command:

$ git clone git://github.com/fnatter/freeplane-git.git freeplane

However, this will only configure the master branch (named trunk in other VCS's such as svn) locally:

$ git branch -a
* master
  remotes/origin/HEAD -> origin/master
  remotes/origin/docear_trunk
  remotes/origin/master

In order to check out a branch (which is simply a reference to a commit) that currently only exists remotely (the remotes/origin/* references are called remote tracking branches), simply switch to that branch:

$ git checkout docear_trunk

This can be done more easily using Eclipse. This page also describes how to import a repository into eclipse.

Using Tags

Show all tags:

$ git tag

Search for a tag:

$ git tag -l "release-1.1*"

Show information about a tag:

$ git show release-1.1.2

Define a tag locally:

$ git tag -a <tagname>
# (an editor opens for you to add a description)

Tags are not automatically transferred when doing a git push, you have to push individually:

$ git push origin <tagname>

or push all tags:

$ git push --tags origin

You might need a

$ git pull --tags

to get all tags. See git-fetch(1) for situations when you will need this (rarely).

TODO: sign tags?

Working with branches

Branches are very central to git. Do not hesitate to create feature, team and (of course) maintenance branches.

You probably want set push.default to tracking or upstream which makes sure that only the current branch is pushed to its upstream branch (and NOT all configured branches): Note: this option is ignored by current EGit. On EGit you get the same behavior by selecting Team->Push To Upstream.

$ git config push.default tracking

(you can equivalently set this to upstream in recent git versions).

Switch to another branch

$ git checkout <branchname>

(Team->Switch To->... in Eclipse)

How to create a new branch

New (feature) branches should be named <user>/<feature> or (if several devs work on a feature): <feature>.

# commit everything that should go into the new branch
$ git status
$ git add <file>
[...]
$ git commit -m "my changes"

# create new branch locally
$ git checkout -b <newbranch>

# check commit log to see that above commit is in there
$ git log

# new branch must be visible and selected:
$ git branch -a  

# (make sure that the name of the new branch is correct! it is diffcult/impossible
#  to rename published branches!)

# create branch remotely, use -u to automatically configure upstream location
$ git push -u origin <newbranch>
# this should output something like this:
  Branch <newbranch> set up to track remote branch <newbranch> from origin.
# (Note: -u is important if you want to use git pull/push without
  specifying a remote/refspec)

# remote branch of <newbranch> must be visible:
$ git branch -a

So the short story is:

$ git checkout -b <newbranch>
$ git push -u origin <newbranch>

Rename a local branch

$ git branch -m <old-branch-name> <new-branch-name>

TODO: how to rename the remote tracking branch => difficult!!

How to merge local branches

$ git checkout <destination_branch>
$ git merge <source_branch>

If you want to abort a merge (revert the working directory to the state before the merge command), do this:

$ git reset --hard

(WARNING: this will remove all uncommitted changes!!)

In eclipse, this can be achieved by:

• Team->Switch To and choose <destination_branch>
• Team->Merge... and choose <source_branch>

In Eclipse, you may have to refresh all projects (F5) if a branch has been added/modified/deleted via the command line.

Fast-Forward Merges (merge-nodes)

Often the creation of a merge commit (merge node) is not necessary, and git merge uses a fast-forward merge, omitting the merge node:

$ git merge foo
Updating 9e9a63a..732b657
Fast-forward
 testfoo.txt |    1 +
 1 file changed, 1 insertion(+)
 create mode 100644 testfoo.txt

results in:

* 732b657 commit in branch foo
* [...]

Using the option --no-ff you can force git to create a merge node even if isn't absolutely necessary (non-fast-forward merge):

$ git merge --no-ff foo2
Merge made by the 'recursive' strategy.
 testfoo2.txt |    1 +
 1 file changed, 1 insertion(+)
 create mode 100644 testfoo2.txt

which will result in:

*   3890bc8 (HEAD, master) Merge branch 'foo2'
|\  
| * 6bc24c5 (foo2) commit on foo2
|/  
* 
* [...]

This is useful when merging feature branches because it clearly shows the integration of a new feature. On the other hand, many merge nodes make the commit graph less readable.

Merge master->dev-branch

$ git checkout <devbranch>
$ git merge master

Merge dev-branch->master

$ git checkout master
$ git merge <devbranch>

How to remove a branch

# remove branch locally
# (use -D instead if you want to delete a branch that is not fully merged into HEAD!)
$ git branch -d <branchname>

You can do this with EGit using Team->Advanced->Delete Branch....

If you accidentally deleted a (local) branch, you can recover it by starting a new branch from the location that git branch -d <branchname> echoed (or by searching for the last commit on that branch in git reflog):

$ git branch -D foo
Deleted branch foo (was 732b657).
$ git branch foo 732b657

(remember that branches are simply pointers to commits)

Warning: this only works if the delete was quite recent as orphaned commits will be deleted after some time!

Delete a remote branch(!):

$ git push origin --delete <branchname>

Now the local and the remote tracking branch should be gone:

$ git branch -a
  docear_trunk
* master
  remotes/origin/docear_trunk
  remotes/origin/master

NOTE: The stale branch will still exist in other checkouts, until you do a:

$ git remote prune origin

in that other checkout. TODO: but it still exists there as a local branch!

Check whether your branches are set up correctly

Make sure your branches are set up correctly for push/pull:

$ git remote show origin
* remote origin
  Fetch URL: https://github.com/fnatter/freeplane-git.git
  Push  URL: https://github.com/fnatter/freeplane-git.git
  HEAD branch: master
  Remote branches:
    docear_trunk tracked
    master       tracked
  Local branches configured for 'git pull':
    docear_trunk merges with remote docear_trunk
    master       merges with remote master
  Local refs configured for 'git push':
    docear_trunk pushes to docear_trunk (up to date)
    master       pushes to master       (up to date)

Importing a remote branch

Using command line git:

$ git pull # fetches the remote (tracking) branch
$ git checkout <branchname>

Using Eclipse/EGit:

• Team->Pull fetches the remote (tracking) branch
• Team->Switch To->New branch..., select Source ref = refs/remotes/origin/<name>

General workflow

Create a dev branch (see section on creating branches above).

Work on your feature branch

# switch to feature branch
$ git checkout <feature>

# fetch and merge changes (in case another dev works on this)
$ git pull

# you might have to resolve conflicts: (might want to use 'git mergetool'
# or Eclipse/EGit)
for each conflict x:
  1. resolve conflict in x, remove markers
  2. git add x # mark as resolved
# commit the conflict resolution(s)
$ git commit

$ git add ...
$ git commit
[...]

# This will push commits to the remote branch that is tracked
# make sure that push.default=tracking|upstream (see above),
# otherwise other branches will be pushed as well!
$ git push [--dry-run]

Merging

Merge master -> <devbranch> (see section on merging above) every once-in-a-while.

After a final code review (on your dev branch), merge <devbranch> -> master (see section on merging above).

Miscellaneous

Revert (reset) files

git checkout <filename>

Revert all files in working copy (!):

git reset --hard

Undoing/editing commits

TODO: how to remove/edit a commit locally using rebase.

Undoing a commit that is already pushed

Use git revert <commit-hash>, like this:

$ git revert b1e9b4c9755b091f95aaa3035aca04dcb02ec1fd

This will generate an inverse commit, it will not remove the original commit:

* 171881e (HEAD, master) Revert "a simple commit"
* b1e9b4c a simple commit