diff --git a/README.md b/README.md index d56576c81..17b38de6c 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? ----------