Git howto

Working with freeplane's git repository

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 EGit documentation.

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

Installation

This chapter of the git book has some info about installing git from source or binary on Linux/Mac OS X/Windows.

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

$ git config --global user.name "Felix Natter"
$ git config --global user.email "fnatter@gmx.net"

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 using Eclipse. This page also describes how to import a repository into eclipse.

Basic workflow with one branch

Please read the chapter on git basics in order to get started with git. You should understand how to stage and commit changes.

In the following there is a simplified list of steps for working with git. Please read the following sections!

• clone repo (see above)
• switch to the desired branch (see next section for more about branches!)

$ git checkout <branch> # Eclipse: Team->Switch to

• make sure you have the latest version of the branch (pull = fetch + merge)

$ git pull

(resolve and commit any merge conflicts)

• 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]

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

• create more commits, this is all done locally!
• push changesets (commits) to sourceforge:

$ git push

(you might have to pull before the push if someone has pushed to the branch after you pulled!)

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

$ 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.
# (Note: this 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>

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 the command line)??

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