Here are some notes about using git for the typical situations conkeror hackers are likely to encounter.

== General Advice ==

If you are developing conkeror, i.e. you have unpushed commits or uncommitted changes, forget that `git pull` even exists.  Read on to learn how to use the proper tools and avoid creating merge commits.

== Obtaining Conkeror with Git ==
=== Anonymous ===

{{{git clone git://repo.or.cz/conkeror.git}}}

=== With a repo.or.cz Account ===

{{{git clone git+ssh://USERNAME@repo.or.cz/srv/git/conkeror.git}}}


== Want to pull, have unpushed commits ==

{{{
git fetch
git rebase origin/master
}}}

If `git rebase` resulted in a conflict, see below, "Conflict in Rebase Attempt".

== Want to pull, have uncommitted changes ==

{{{
git stash
git pull
git stash apply
}}}

== Making a Topic Branch ==

Note: once you start working with branches other than `master`, you should always use the ''full form'' of `git push` to prevent pushing more branches than you intend.  The full form of `git push` is like `git push DESTINATION BRANCH`.  For example, to push commits in your `master` branch to the `origin` repository:
{{{
git push origin master
}}}

That said, here is how you make a new topic branch.  You can do this even if you have uncommitted changes in your working tree.
{{{
git checkout -b my-new-branch
}}}

== Checking out a Topic Branch ==

Suppose someone else pushed a topic branch to the main repository, and you want to check it out.  First, to make git know that the branch exists:
{{{
git fetch
#or
git remote update
}}}
Confirm that the branch exists:
{{{
git branch -r
}}}
Then make a local branch which ''tracks'' the topic branch in question:
{{{
git checkout --track -b the-topic-branch origin/the-topic-branch
}}}

== See What Changed in Recent Commits ==
{{{
git log -p
}}}

== Conflict in Rebase Attempt ==

You tried to use `git rebase` but got an error message about a conflict.

{{{
error: patch failed: <FILENAME>:<LINE-NUMBER>
error: <FILENAME>: patch does not apply
Using index info to reconstruct a base tree...
Falling back to patching base and 3-way merge...
Auto-merged <FILENAME>
CONFLICT (content): Merge conflict in <FILENAME>
Failed to merge in the changes.
Patch failed at 0001.

When you have resolved this problem run "git rebase --continue".
If you would prefer to skip this patch, instead run "git rebase --skip".
To restore the original branch and stop rebasing run "git rebase --abort".
}}}

Don't panic.  Open the file(s) indicated by the error, and look for conflict markers.  The conflict will be marked with lines containing a long sequence of `>>>>>>>`, `======`, and `<<<<<<<`.  Manually edit the file to resolve the conflicts, i.e. remove the markers and edit the file so that it is in its "correct" state.  After correcting the file, run:
{{{
git rebase --continue
}}}

== Keep a Topic Branch Synced With Master ==

You are working on a topic branch, and there are new commits in `origin/master`.  You want to bring those commits into your branch in order to keep your branch up to date with the master repository.

First, commit any uncommitted changes.

{{{
git checkout master
git pull
git checkout your-topic-branch
git rebase origin/master
}}}

If there was a conflict during rebase, refer to `Conflict in Rebase Attempt` above.

An important note about using `git rebase`.  Never rebase commits which you have shared with other people.  Never rebase commits that have already been pushed to a branch in conkeror's main repository.  If you find yourself in that situation, you will have to make a merge commit.