Git howto

Working with freeplane's git repository

Please read the chapter on git basics in order to get started with git. You should understand how to stage and commit changes. You can (and probably want to) use eclipse for most operations. I try to explain this in each section, but it is a good idea to read the [http://wiki.eclipse.org/EGit/User_Guide EGit documentation].

• NOTE*: These instructions cover the temporary freeplane repository on github, it will

need to be adapted to the sourceforge hosting service.

Checkout

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 [http://wiki.eclipse.org/EGit/User_Guide#Starting_from_existing_Git_Repositories using Eclipse]. This page also describes how to import a repository into eclipse.

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 which makes sure that only the current branch is pushed to its upstream branch (and NOT all configured branches):

 git config push.default tracking
 

(you can equivalently set this to upstream in recent git versions). The same thing happens when you select Team->Push To Upstream from eclipse.

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  

# 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. 
# (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>

How to merge 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>

TODO: how to make eclipse update the list of branches etc. (e.g. if a branch has been deleted from eclipse)??

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!) <-- TODO:??
git checkout -d <branchname>

# delete 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)

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)
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

# the chapter on git basics
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).