GIT 0.99.9m aka 1.0rc5

Signed-off-by: Junio C Hamano <junkio@cox.net>

Documentation/Makefile

@@ -9,6 +9,7 @@ ARTICLES += diffcore
 ARTICLES += howto-index
 ARTICLES += repository-layout
 ARTICLES += hooks
+ARTICLES += everyday
 # with their own formatting rules.
 SP_ARTICLES = glossary howto/revert-branch-rebase
 

Documentation/cvs-migration.txt

@@ -187,7 +187,8 @@ you would use git-rev-list and git-diff-tree like this:
 
 We have already talked about the "\--stdin" form of git-diff-tree
 command that reads the list of commits and compares each commit
-with its parents.  The git-whatchanged command internally runs
+with its parents (otherwise you should go back and read the tutorial).
+The git-whatchanged command internally runs
 the equivalent of the above command, and can be used like this:
 
 	$ git-whatchanged -p -S'if (frotz) {

Documentation/everyday.txt

@@ -0,0 +1,138 @@
+Everyday GIT With 20 Commands Or So
+===================================
+
+GIT suite has over 100 commands, and the manual page for each of
+them discusses what the command does and how it is used in
+detail, but until you know what command should be used in order
+to achieve what you want to do, you cannot tell which manual
+page to look at, and if you know that already you do not need
+the manual.
+
+Does that mean you need to know all of them before you can use
+git?  Not at all.  Depending on the role you play, the set of
+commands you need to know is slightly different, but in any case
+what you need to learn is far smaller than the full set of
+commands to carry out your day-to-day work.  This document is to
+serve as a cheat-sheet and a set of pointers for people playing
+various roles.
+
+<<Basic Repository>> commands are needed by people who has a
+repository --- that is everybody, because every working tree of
+git is a repository.
+
+In addition, <<Individual Developer (Standalone)>> commands are
+essential for anybody who makes a commit, even for somebody who
+works alone.
+
+If you work with other people, you will need commands listed in
+<<Individual Developer (Participant)>> section as well.
+
+People who play <<Integrator>> role need to learn some more
+commands in addition to the above.
+
+<<Repository Administration>> commands are for system
+administrators who are responsible to care and feed git
+repositories to support developers.
+
+
+Basic Repository[[Basic Repository]]
+------------------------------------
+
+Everybody uses these commands to feed and care git repositories.
+
+  * gitlink:git-init-db[1] or gitlink:git-clone[1] to create a
+    new repository.
+
+  * gitlink:git-fsck-objects[1] to validate the repository.
+
+  * gitlink:git-prune[1] to garbage collect crufts in the
+    repository.
+
+  * gitlink:git-repack[1] to pack loose objects for efficiency.
+
+Individual Developer (Standalone)[[Individual Developer (Standalone)]]
+----------------------------------------------------------------------
+
+A standalone individual developer does not exchange patches with
+other poeple, and works alone in a single repository, using the
+following commands.
+
+  * gitlink:git-show-branch[1] to see where you are.
+
+  * gitlink:git-diff[1] and gitlink:git-status[1] to see what
+    you are in the middle of doing.
+
+  * gitlink:git-log[1] to see what happened.
+
+  * gitlink:git-whatchanged[1] to find out where things have
+    come from.
+
+  * gitlink:git-checkout[1] and gitlink:git-branch[1] to switch
+    branches.
+
+  * gitlink:git-update-index[1] to manage the index file.
+
+  * gitlink:git-commit[1] to advance the current branch.
+
+  * gitlink:git-reset[1] and gitlink:git-checkout[1] (with
+    pathname parameters) to undo changes.
+
+  * gitlink:git-pull[1] with "." as the remote to merge between
+    local branches.
+
+  * gitlink:git-rebase[1] to maintain topic branches.
+
+
+Individual Developer (Participant)[[Individual Developer (Participant)]]
+------------------------------------------------------------------------
+
+A developer working as a participant in a group project needs to
+learn how to communicate with others, and uses these commands in
+addition to the ones needed by a standalone developer.
+
+  * gitlink:git-pull[1] from "origin" to keep up-to-date with
+    the upstream.
+
+  * gitlink:git-push[1] to shared repository if you adopt CVS
+    style shared repository workflow.
+
+  * gitlink:git-format-patch[1] to prepare e-mail submission, if
+    you adopt Linux kernel-style public forum workflow.
+
+
+Integrator[[Integrator]]
+------------------------
+
+A fairly central person acting as the integrator in a group
+project receives changes made by others, reviews and integrates
+them and publishes the result for others to use, using these
+commands in addition to the ones needed by participants.
+
+  * gitlink:git-am[1] to apply patches e-mailed in from your
+    contributors.
+
+  * gitlink:git-pull[1] to merge from your trusted lieutenants.
+
+  * gitlink:git-format-patch[1] to prepare and send suggested
+    alternative to contributors.
+
+  * gitlink:git-revert[1] to undo botched commits.
+
+  * gitlink:git-push[1] to publish the bleeding edge.
+
+
+Repository Administration[[Repository Administration]]
+------------------------------------------------------
+
+A repository administrator uses the following tools to set up
+and maintain access to the repository by developers.
+
+  * gitlink:git-daemon[1] to allow anonymous download from
+    repository.
+
+  * gitlink:git-shell[1] can be used as a 'restricted login shell'
+    for shared central repository users.
+
+  * link:howto/update-hook-example.txt[update hook howto] has a
+    good example of managing a shared central repository.
+

Documentation/git-am.txt

@@ -28,7 +28,7 @@ OPTIONS
 	area to store extracted patches.
 
 --utf8, --keep::
-	Pass `--utf8` and `--keep` flags to `git-mailinfo` (see
+	Pass `-u` and `-k` flags to `git-mailinfo` (see
 	gitlink:git-mailinfo[1]).
 
 --binary::

Documentation/git-bisect.txt

@@ -8,16 +8,21 @@ git-bisect - Find the change that introduced a bug
 
 SYNOPSIS
 --------
- 'git bisect' start
- 'git bisect' bad <rev>
- 'git bisect' good <rev>
- 'git bisect' reset [<branch>]
- 'git bisect' visualize
- 'git bisect' replay <logfile>
- 'git bisect' log
+'git bisect' <subcommand> <options> 
 
 DESCRIPTION
 -----------
+The command takes various subcommands, and different options
+depending on the subcommand:
+
+ git bisect start [<paths>...]
+ git bisect bad <rev>
+ git bisect good <rev>
+ git bisect reset [<branch>]
+ git bisect visualize
+ git bisect replay <logfile>
+ git bisect log
+
 This command uses 'git-rev-list --bisect' option to help drive
 the binary search process to find which change introduced a bug,
 given an old "good" commit object name and a later "bad" commit
@@ -26,10 +31,10 @@ object name.
 The way you use it is:
 
 ------------------------------------------------
-git bisect start
-git bisect bad			# Current version is bad
-git bisect good v2.6.13-rc2	# v2.6.13-rc2 was the last version
-				# tested that was good
+$ git bisect start
+$ git bisect bad			# Current version is bad
+$ git bisect good v2.6.13-rc2		# v2.6.13-rc2 was the last version
+					# tested that was good
 ------------------------------------------------
 
 When you give at least one bad and one good versions, it will
@@ -43,7 +48,7 @@ and check out the state in the middle. Now, compile that kernel, and boot
 it. Now, let's say that this booted kernel works fine, then just do
 
 ------------------------------------------------
-git bisect good			# this one is good
+$ git bisect good			# this one is good
 ------------------------------------------------
 
 which will now say
@@ -62,7 +67,7 @@ kernel rev in "refs/bisect/bad".
 Oh, and then after you want to reset to the original head, do a
 
 ------------------------------------------------
-git bisect reset
+$ git bisect reset
 ------------------------------------------------
 
 to get back to the master branch, instead of being in one of the bisection
@@ -72,19 +77,50 @@ not using some old bisection branch).
 
 During the bisection process, you can say
 
-	git bisect visualize
+------------
+$ git bisect visualize
+------------
 
 to see the currently remaining suspects in `gitk`.
 
 The good/bad input is logged, and `git bisect
 log` shows what you have done so far.  You can truncate its
 output somewhere and save it in a file, and run
 
-	git bisect replay that-file
+------------
+$ git bisect replay that-file
+------------
 
 if you find later you made a mistake telling good/bad about a
 revision.
 
+If in a middle of bisect session, you know what the bisect
+suggested to try next is not a good one to test (e.g. the change
+the commit introduces is known not to work in your environment
+and you know it does not have anything to do with the bug you
+are chasing), you may want to find a near-by commit and try that
+instead.  It goes something like this:
+
+------------
+$ git bisect good/bad			# previous round was good/bad.
+Bisecting: 337 revisions left to test after this
+$ git bisect visualize			# oops, that is uninteresting.
+$ git reset --hard HEAD~3		# try 3 revs before what
+					# was suggested
+------------
+
+Then compile and test the one you chose to try.  After that,
+tell bisect what the result was as usual.
+
+You can further cut down the number of trials if you know what
+part of the tree is involved in the problem you are tracking
+down, by giving paths parameters when you say `bisect start`,
+like this:
+
+------------
+$ git bisect start arch/i386 include/asm-i386
+------------
+
 
 Author
 ------

Documentation/git-checkout-index.txt

@@ -9,7 +9,7 @@ git-checkout-index - Copy files from the index to the working directory
 SYNOPSIS
 --------
 'git-checkout-index' [-u] [-q] [-a] [-f] [-n] [--prefix=<string>]
-	           [--] <file>...
+	[--stage=<number>] [--] <file>...
 
 DESCRIPTION
 -----------
@@ -40,58 +40,80 @@ OPTIONS
 	When creating files, prepend <string> (usually a directory
 	including a trailing /)
 
+--stage=<number>::
+	Instead of checking out unmerged entries, copy out the
+	files from named stage.  <number> must be between 1 and 3.
+
 --::
 	Do not interpret any more arguments as options.
 
 The order of the flags used to matter, but not anymore.
 
-Just doing "git-checkout-index" does nothing. You probably meant
-"git-checkout-index -a". And if you want to force it, you want
-"git-checkout-index -f -a".
+Just doing `git-checkout-index` does nothing. You probably meant
+`git-checkout-index -a`. And if you want to force it, you want
+`git-checkout-index -f -a`.
 
 Intuitiveness is not the goal here. Repeatability is. The reason for
-the "no arguments means no work" thing is that from scripts you are
-supposed to be able to do things like:
+the "no arguments means no work" behavior is that from scripts you are
+supposed to be able to do:
 
-	find . -name '*.h' -print0 | xargs -0 git-checkout-index -f --
+----------------
+$ find . -name '*.h' -print0 | xargs -0 git-checkout-index -f --
+----------------
 
 which will force all existing `*.h` files to be replaced with their
 cached copies. If an empty command line implied "all", then this would
 force-refresh everything in the index, which was not the point.
 
-To update and refresh only the files already checked out:
-
-        git-checkout-index -n -f -a && git-update-index --ignore-missing --refresh
-
-Oh, and the "--" is just a good idea when you know the rest will be
-filenames. Just so that you wouldn't have a filename of "-a" causing
-problems (not possible in the above example, but get used to it in
-scripting!).
-
-The prefix ability basically makes it trivial to use
-git-checkout-index as an "export as tree" function. Just read the
-desired tree into the index, and do a
+The `--` is just a good idea when you know the rest will be filenames;
+it will prevent problems with a filename of, for example,  `-a`.
+Using `--` is probably a good policy in scripts.
 
-        git-checkout-index --prefix=git-export-dir/ -a
 
-and git-checkout-index will "export" the index into the specified
+EXAMPLES
+--------
+To update and refresh only the files already checked out::
++
+----------------
+$ git-checkout-index -n -f -a && git-update-index --ignore-missing --refresh
+----------------
+
+Using `git-checkout-index` to "export an entire tree"::
+	The prefix ability basically makes it trivial to use
+	`git-checkout-index` as an "export as tree" function.
+	Just read the desired tree into the index, and do:
++
+----------------
+$ git-checkout-index --prefix=git-export-dir/ -a
+----------------
++
+`git-checkout-index` will "export" the index into the specified
 directory.
++
+The final "/" is important. The exported name is literally just
+prefixed with the specified string.  Contrast this with the
+following example.
 
-NOTE The final "/" is important. The exported name is literally just
-prefixed with the specified string, so you can also do something like
-
-    git-checkout-index --prefix=.merged- Makefile
+Export files with a prefix::
++
+----------------
+$ git-checkout-index --prefix=.merged- Makefile
+----------------
++
+This will check out the currently cached copy of `Makefile`
+into the file `.merged-Makefile`.
 
-to check out the currently cached copy of `Makefile` into the file
-`.merged-Makefile`
 
 Author
 ------
 Written by Linus Torvalds <torvalds@osdl.org>
 
+
 Documentation
 --------------
-Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
+Documentation by David Greaves,
+Junio C Hamano and the git-list <git@vger.kernel.org>.
+
 
 GIT
 ---