From 5dde3eb44169c3cdc8517aee693fe8f4d783d715 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Carl=20F=C3=BCrstenberg?= <azatoth@gmail.com>
Date: Fri, 8 Apr 2011 20:56:56 +0200
Subject: [PATCH] Git for dummies

Per request, here is an simple git for dummies quick sheet, with some
useful commands.
---
 README.md | 83 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 83 insertions(+)

diff --git a/README.md b/README.md
index d56576c8..17b38de6 100644
--- a/README.md
+++ b/README.md
@@ -56,6 +56,89 @@ Sometimes, the various git repositories get into an inconsistent state where bui
 (usually this results in the jquery.js or jquery.min.js being 0 bytes). If this happens, run `make clean`, then
 run `make` again.
 
+Git for dummies
+---------------
+
+As the source code is handled by the version control system Git, it's useful to know some features used.
+
+### Submodules ###
+
+The repository uses submodules, which normally are handles directly by the Makefile, but sometimes you want to
+be able to work with them manually.
+
+Following are the steps to manually get the submodules:
+
+1. `git clone https://github.com/jquery/jquery.git`
+2. `git submodule init`
+3. `git submodule update`
+
+Or:
+
+1. `git clone https://github.com/jquery/jquery.git`
+2. `git submodule update --init`
+
+Or:
+
+1. `git clone --recursive https://github.com/jquery/jquery.git`
+
+If you want to work inside a submodule, it is possible, but first you need to checkout a branch:
+
+1. `cd src/sizzle`
+2. `git checkout master`
+
+After you've commited your changes to the submodule, you'll update the jquery project to point to the new commit,
+but remember to push the submodule changes before pushing the new jquery commit:
+
+1. `cd src/sizzle`
+2. `git push origin master`
+3. `cd ..`
+4. `git add src/sizzle`
+5. `git commit`
+
+The makefile has some targets to simplify submodule handling:
+
+#### `make update_submodules` ####
+
+checks out the commit pointed to byu jquery, but merges your local changes, if any. This target is executed 
+when you are doing a normal `make`.
+
+#### `make pull_submodules` ####
+
+updates the content of the submoduels to what is probably the latest upstream code
+
+#### `make pull` ####
+
+make a `make pull_submodules` and after that a `git pull`. if you have no remote tracking in your master branch, you can
+execute this command as `make pull REMOTE=origin BRANCH=master` instead.
+
+### cleaning ###
+
+If you want to purge your working directory back to the status of upstream, following commands can be used (remember everything you've worked on is gone after these):
+
+1. `git reset --hard upstream/master`
+2. `git clean -fdx`
+
+### rebasing ###
+
+For feature/topic branches, you should always used the `--rebase` flag to `git pull`, or if you are usually handling many temporary "to be in a github pull request" branches, run following to automate this:
+
+* `git config branch.autosetuprebase local` (see `man git-config` for more information)
+
+### handling merge conflicts ###
+
+If you're getting merge conflicts when merging, instead of editing the conflicted files manually, you can use the feature
+`git mergetool`. Even though the default tool `xxdiff` looks awful/old, it's rather useful.
+
+Following are some commands that can be used there:
+
+* `Ctrl + Alt + M` - automerge as much as possible
+* `b` - jump to next merge conflict
+* `s` - change the order of the conflicted lines
+* `u` - undo an merge
+* `left mouse button` - mark a block to be the winner
+* `middle mouse button` - mark a line to be the winner
+* `Ctrl + S` - save
+* `Ctrl + Q` - quit
 
 Questions?
 ----------