[PATCH] Add policy on user-interface changes

[PATCH] Add policy on user-interface changes

[Andrew Ruder]

Documentation/SubmittingPatches: Add note that all user interface changes
should include associated documentation updates.

Signed-off-by: Andrew Ruder <andy@aeruder.net>
---
 Documentation/SubmittingPatches |    3 +++
 1 files changed, 3 insertions(+), 0 deletions(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 131bcff..2386f49 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -22,6 +22,9 @@ Checklist (and a short version for the impatient):
 	- provide additional information (which is unsuitable for
 	  the commit message) between the "---" and the diffstat
 	- send the patch to the list _and_ the maintainer
+	- if you change, add, or remove a command line option or
+	  make some other user interface change, the associated
+	  documentation should be updated as well.
 
 Long version:
 
-- 
1.5.1.1.98.gedb4f-dirty

[PATCH] Update git-am documentation

[Andrew Ruder]

Documentation/git-am.txt missing several short versions
of options.  Added documentation for --resolvemsg=<msg>
command-line option.

Signed-off-by: Andrew Ruder <andy@aeruder.net>
---
 Documentation/git-am.txt |   24 +++++++++++++++---------
 1 files changed, 15 insertions(+), 9 deletions(-)

diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt
index 148ce40..4af966a 100644
--- a/Documentation/git-am.txt
+++ b/Documentation/git-am.txt
@@ -26,18 +26,18 @@ OPTIONS
 	The list of mailbox files to read patches from. If you do not
 	supply this argument, reads from the standard input.
 
---signoff::
+-s, --signoff::
 	Add `Signed-off-by:` line to the commit message, using
 	the committer identity of yourself.
 
---dotest=<dir>::
+-d=<dir>, --dotest=<dir>::
 	Instead of `.dotest` directory, use <dir> as a working
 	area to store extracted patches.
 
---keep::
+-k, --keep::
 	Pass `-k` flag to `git-mailinfo` (see gitlink:git-mailinfo[1]).
 
---utf8::
+-u, --utf8::
 	Pass `-u` flag to `git-mailinfo` (see gitlink:git-mailinfo[1]).
 	The proposed commit log message taken from the e-mail
 	are re-coded into UTF-8 encoding (configuration variable
@@ -48,14 +48,14 @@ This was optional in prior versions of git, but now it is the
 default.   You could use `--no-utf8` to override this.
 
 --no-utf8::
-	Do not pass `-u` flag to `git-mailinfo` (see
+	Pass `-n` flag to `git-mailinfo` (see
 	gitlink:git-mailinfo[1]).
 
---binary::
+-b, --binary::
 	Pass `--allow-binary-replacement` flag to `git-apply`
 	(see gitlink:git-apply[1]).
 
---3way::
+-3, --3way::
 	When the patch does not apply cleanly, fall back on
 	3-way merge, if the patch records the identity of blobs
 	it is supposed to apply to, and we have those blobs
@@ -73,10 +73,10 @@ default.   You could use `--no-utf8` to override this.
 	These flags are passed to the `git-apply` program that applies
 	the patch.
 
---interactive::
+-i, --interactive::
 	Run interactively, just like git-applymbox.
 
---resolved::
+-r, --resolved::
 	After a patch failure (e.g. attempting to apply
 	conflicting patch), the user has applied it by hand and
 	the index file stores the result of the application.
@@ -84,6 +84,12 @@ default.   You could use `--no-utf8` to override this.
 	extracted from the e-mail message and the current index
 	file, and continue.
 
+--resolvemsg=<msg>::
+	When a patch failure occurs, <msg> will be printed
+	to the screen before exiting.  This overrides the
+	standard message informing you to use `--resolved`
+	or `--skip` to handle the failure.
+
 DISCUSSION
 ----------
 
-- 
1.5.1.1.98.gedb4f-dirty

Re: [PATCH] Update git-am documentation

[Junio C Hamano]

Andrew Ruder <andy@aeruder.net> writes:

> Documentation/git-am.txt missing several short versions

Short ones were semi deliberately left out, but I do not think
adding them would hurt.

> ...  Added documentation for --resolvemsg=<msg>
> command-line option.

On the other hand, this was purely meant as an internal
communication tool for the commands that invoke am, so I do not
think it is wise to document it without saying that, as I think
anybody reading your new documentation would end up asking "Huh?
what use is that?".

[PATCH] Update git-am documentation

[Andrew Ruder]

Documentation/git-am.txt missing several short versions
of options.  Added documentation for --resolvemsg=<msg>
command-line option.

Signed-off-by: Andrew Ruder <andy@aeruder.net>
---
 Sometimes it is a bit difficult to gauge intention by reading the code.
 :)  My initial thought was that it was just to aid in scripting git-am
 and left it at that.  But I'd still much rather have all command-line
 options in the man pages even if they are primarily for internal use as
 sometimes they still will find themself useful in atypical situations.

 Documentation/git-am.txt |   25 ++++++++++++++++---------
 1 files changed, 16 insertions(+), 9 deletions(-)

diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt
index 148ce40..2230340 100644
--- a/Documentation/git-am.txt
+++ b/Documentation/git-am.txt
@@ -26,18 +26,18 @@ OPTIONS
 	The list of mailbox files to read patches from. If you do not
 	supply this argument, reads from the standard input.
 
---signoff::
+-s, --signoff::
 	Add `Signed-off-by:` line to the commit message, using
 	the committer identity of yourself.
 
---dotest=<dir>::
+-d=<dir>, --dotest=<dir>::
 	Instead of `.dotest` directory, use <dir> as a working
 	area to store extracted patches.
 
---keep::
+-k, --keep::
 	Pass `-k` flag to `git-mailinfo` (see gitlink:git-mailinfo[1]).
 
---utf8::
+-u, --utf8::
 	Pass `-u` flag to `git-mailinfo` (see gitlink:git-mailinfo[1]).
 	The proposed commit log message taken from the e-mail
 	are re-coded into UTF-8 encoding (configuration variable
@@ -48,14 +48,14 @@ This was optional in prior versions of git, but now it is the
 default.   You could use `--no-utf8` to override this.
 
 --no-utf8::
-	Do not pass `-u` flag to `git-mailinfo` (see
+	Pass `-n` flag to `git-mailinfo` (see
 	gitlink:git-mailinfo[1]).
 
---binary::
+-b, --binary::
 	Pass `--allow-binary-replacement` flag to `git-apply`
 	(see gitlink:git-apply[1]).
 
---3way::
+-3, --3way::
 	When the patch does not apply cleanly, fall back on
 	3-way merge, if the patch records the identity of blobs
 	it is supposed to apply to, and we have those blobs
@@ -73,10 +73,10 @@ default.   You could use `--no-utf8` to override this.
 	These flags are passed to the `git-apply` program that applies
 	the patch.
 
---interactive::
+-i, --interactive::
 	Run interactively, just like git-applymbox.
 
---resolved::
+-r, --resolved::
 	After a patch failure (e.g. attempting to apply
 	conflicting patch), the user has applied it by hand and
 	the index file stores the result of the application.
@@ -84,6 +84,13 @@ default.   You could use `--no-utf8` to override this.
 	extracted from the e-mail message and the current index
 	file, and continue.
 
+--resolvemsg=<msg>::
+	When a patch failure occurs, <msg> will be printed
+	to the screen before exiting.  This overrides the
+	standard message informing you to use `--resolved`
+	or `--skip` to handle the failure.  This is primarily
+	for internal usage or scripting around git-am.
+
 DISCUSSION
 ----------
 
-- 
1.5.1.1.98.gedb4f-dirty

Re: [PATCH] Update git-am documentation

[Junio C Hamano]

Andrew Ruder <andy@aeruder.net> writes:

> Documentation/git-am.txt missing several short versions
> of options.  Added documentation for --resolvemsg=<msg>
> command-line option.
>
> Signed-off-by: Andrew Ruder <andy@aeruder.net>
> ---
>  Sometimes it is a bit difficult to gauge intention by reading the code.
>  :)  My initial thought was that it was just to aid in scripting git-am
>  and left it at that.  But I'd still much rather have all command-line
>  options in the man pages even if they are primarily for internal use as
>  sometimes they still will find themself useful in atypical situations.

It is _solely_ (not "primarily") for git-rebase and not even for
"scripting around".  In other words, it is an implementation
detail of git-rebase and I would rather reserve the right to
update that implementation detail by not setting that in stone
for users to abuse.

[PATCH] Update git-am documentation

[Andrew Ruder]

Documentation/git-am.txt missing several short versions
of options.

Signed-off-by: Andrew Ruder <andy@aeruder.net>
---
 Ah, I misunderstood your first reply.  If this is truly only for
 internal usage, it should definitely not be in the manpage as
 abuse *will* occur. :)  Let's just hope that nobody finds this thread
 via the mailing list archives.

 Documentation/git-am.txt |   18 +++++++++---------
 1 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt
index 148ce40..759e3a5 100644
--- a/Documentation/git-am.txt
+++ b/Documentation/git-am.txt
@@ -26,18 +26,18 @@ OPTIONS
 	The list of mailbox files to read patches from. If you do not
 	supply this argument, reads from the standard input.
 
---signoff::
+-s, --signoff::
 	Add `Signed-off-by:` line to the commit message, using
 	the committer identity of yourself.
 
---dotest=<dir>::
+-d=<dir>, --dotest=<dir>::
 	Instead of `.dotest` directory, use <dir> as a working
 	area to store extracted patches.
 
---keep::
+-k, --keep::
 	Pass `-k` flag to `git-mailinfo` (see gitlink:git-mailinfo[1]).
 
---utf8::
+-u, --utf8::
 	Pass `-u` flag to `git-mailinfo` (see gitlink:git-mailinfo[1]).
 	The proposed commit log message taken from the e-mail
 	are re-coded into UTF-8 encoding (configuration variable
@@ -48,14 +48,14 @@ This was optional in prior versions of git, but now it is the
 default.   You could use `--no-utf8` to override this.
 
 --no-utf8::
-	Do not pass `-u` flag to `git-mailinfo` (see
+	Pass `-n` flag to `git-mailinfo` (see
 	gitlink:git-mailinfo[1]).
 
---binary::
+-b, --binary::
 	Pass `--allow-binary-replacement` flag to `git-apply`
 	(see gitlink:git-apply[1]).
 
---3way::
+-3, --3way::
 	When the patch does not apply cleanly, fall back on
 	3-way merge, if the patch records the identity of blobs
 	it is supposed to apply to, and we have those blobs
@@ -73,10 +73,10 @@ default.   You could use `--no-utf8` to override this.
 	These flags are passed to the `git-apply` program that applies
 	the patch.
 
---interactive::
+-i, --interactive::
 	Run interactively, just like git-applymbox.
 
---resolved::
+-r, --resolved::
 	After a patch failure (e.g. attempting to apply
 	conflicting patch), the user has applied it by hand and
 	the index file stores the result of the application.
-- 
1.5.1.1.98.gedb4f-dirty

[PATCH] Update git-applymbox documentation

[Andrew Ruder]

fact that it encodes to the i18n.commitencoding setting, not just utf-8.
Added documentation of -n option to pass -n to git-mailinfo.

Signed-off-by: Andrew Ruder <andy@aeruder.net>
---
 Documentation/git-applymbox.txt |   14 ++++++++++----
 1 files changed, 10 insertions(+), 4 deletions(-)

diff --git a/Documentation/git-applymbox.txt b/Documentation/git-applymbox.txt
index 95dc65a..3bc92d8 100644
--- a/Documentation/git-applymbox.txt
+++ b/Documentation/git-applymbox.txt
@@ -42,14 +42,20 @@ OPTIONS
 	and the current tree.
 
 -u::
-	The commit log message, author name and author email are
-	taken from the e-mail, and after minimally decoding MIME
-	transfer encoding, re-coded in UTF-8 by transliterating
-	them.  This used to be optional but now it is the default.
+	Pass `-u` flag to `git-mailinfo` (see gitlink:git-mailinfo[1]).
+	The proposed commit log message taken from the e-mail
+	are re-coded into UTF-8 encoding (configuration variable
+	`i18n.commitencoding` can be used to specify project's
+	preferred encoding if it is not UTF-8).  This used to be
+	optional but now it is the default.
 +
 Note that the patch is always used as-is without charset
 conversion, even with this flag.
 
+-n::
+	Pass `-n` flag to `git-mailinfo` (see
+	gitlink:git-mailinfo[1]).
+
 -c .dotest/<num>::
 	When the patch contained in an e-mail does not cleanly
 	apply, the command exits with an error message. The
-- 
1.5.1.1.98.gedb4f-dirty

[PATCH] Update git-applymbox documentation

[Andrew Ruder]

Documentation/git-applymbox.txt: updating -u documentation to include
fact that it encodes to the i18n.commitencoding setting, not just utf-8.
Added documentation of -n option to pass -n to git-mailinfo.

Signed-off-by: Andrew Ruder <andy@aeruder.net>
---
 Resending due to my bad .git/config interacting with mutt to
 wipe out first line of commit message

 Documentation/git-applymbox.txt |   14 ++++++++++----
 1 files changed, 10 insertions(+), 4 deletions(-)

diff --git a/Documentation/git-applymbox.txt b/Documentation/git-applymbox.txt
index 95dc65a..3bc92d8 100644
--- a/Documentation/git-applymbox.txt
+++ b/Documentation/git-applymbox.txt
@@ -42,14 +42,20 @@ OPTIONS
 	and the current tree.
 
 -u::
-	The commit log message, author name and author email are
-	taken from the e-mail, and after minimally decoding MIME
-	transfer encoding, re-coded in UTF-8 by transliterating
-	them.  This used to be optional but now it is the default.
+	Pass `-u` flag to `git-mailinfo` (see gitlink:git-mailinfo[1]).
+	The proposed commit log message taken from the e-mail
+	are re-coded into UTF-8 encoding (configuration variable
+	`i18n.commitencoding` can be used to specify project's
+	preferred encoding if it is not UTF-8).  This used to be
+	optional but now it is the default.
 +
 Note that the patch is always used as-is without charset
 conversion, even with this flag.
 
+-n::
+	Pass `-n` flag to `git-mailinfo` (see
+	gitlink:git-mailinfo[1]).
+
 -c .dotest/<num>::
 	When the patch contained in an e-mail does not cleanly
 	apply, the command exits with an error message. The
-- 
1.5.1.1.98.gedb4f-dirty

[PATCH] Update git-annotate/git-blame documentation

[Andrew Ruder]

Moved options that pertained to both git-blame and git-annotate to a
common file blame-options.txt.

builtin-blame.c: Removed --compatibility, --long, --time from the
short usage as they are not handled in the code.

Documentation/git-blame.txt: Removed common options to git-annotate.
Added documentation for --score-debug.  Removed --compatibility.
Adjusted usage at top to not wrap on 80 columns.

Documentation/git-annotate.txt: Using common options blame-options.txt.

Documentation/blame-options.txt: Added -b note about associated config
option, added --root note about associated config option, added
documentation for --show-stats.  Removed --long, --time, --rev-file as
those options do not really exist.  Added documentation for -M/-C taking
an optional score argument for detection of moved lines.

Signed-off-by: Andrew Ruder <andy@aeruder.net>
---
 Documentation/blame-options.txt |   67 +++++++++++++++++++++++++++++++++++++++
 Documentation/git-annotate.txt  |   15 +--------
 Documentation/git-blame.txt     |   64 ++++++++-----------------------------
 builtin-blame.c                 |    6 ++--
 4 files changed, 85 insertions(+), 67 deletions(-)

diff --git a/Documentation/blame-options.txt b/Documentation/blame-options.txt
new file mode 100644
index 0000000..331f161
--- /dev/null
+++ b/Documentation/blame-options.txt
@@ -0,0 +1,67 @@
+-b::
+	Show blank SHA-1 for boundary commits.  This can also
+	be controlled via the `blame.blankboundary` config option.
+
+--root::
+	Do not treat root commits as boundaries.  This can also be
+	controlled via the `blame.showroot` config option.
+
+--show-stats::
+	Include additional statistics at the end of blame output.
+
+-L n,m::
+	Annotate only the specified line range (lines count from 1).
+
+-l::
+	Show long rev (Default: off).
+
+-t::
+	Show raw timestamp (Default: off).
+
+-S <revs-file>::
+	Use revs from revs-file instead of calling gitlink:git-rev-list[1].
+
+-p, --porcelain::
+	Show in a format designed for machine consumption.
+
+--incremental::
+	Show the result incrementally in a format designed for
+	machine consumption.
+
+--contents <file>::
+	When <rev> is not specified, the command annotates the
+	changes starting backwards from the working tree copy.
+	This flag makes the command pretend as if the working
+	tree copy has the contents of he named file (specify
+	`-` to make the command read from the standard input).
+
+-M|<num>|::
+	Detect moving lines in the file as well.  When a commit
+	moves a block of lines in a file (e.g. the original file
+	has A and then B, and the commit changes it to B and
+	then A), traditional 'blame' algorithm typically blames
+	the lines that were moved up (i.e. B) to the parent and
+	assigns blame to the lines that were moved down (i.e. A)
+	to the child commit.  With this option, both groups of lines
+	are blamed on the parent.
+
+	<num> is optional but it is the lower bound on the number of
+	alphanumeric characters that git must detect as moving
+	within a file for it to associate those lines with the parent
+	commit.
+
+-C|<num>|::
+	In addition to `-M`, detect lines copied from other
+	files that were modified in the same commit.  This is
+	useful when you reorganize your program and move code
+	around across files.  When this option is given twice,
+	the command looks for copies from all other files in the
+	parent for the commit that creates the file in addition.
+
+	<num> is optional but it is the lower bound on the number of
+	alphanumeric characters that git must detect as moving
+	between files for it to associate those lines with the parent
+	commit.
+
+-h, --help::
+	Show help message.
diff --git a/Documentation/git-annotate.txt b/Documentation/git-annotate.txt
index 7baf731..02dc474 100644
--- a/Documentation/git-annotate.txt
+++ b/Documentation/git-annotate.txt
@@ -16,20 +16,7 @@ which introduced the line. Optionally annotate from a given revision.
 
 OPTIONS
 -------
--l, --long::
-	Show long rev (Defaults off).
-
--t, --time::
-	Show raw timestamp (Defaults off).
-
--r, --rename::
-	Follow renames (Defaults on).
-
--S, --rev-file <revs-file>::
-	Use revs from revs-file instead of calling git-rev-list.
-
--h, --help::
-	Show help message.
+include::blame-options.txt[]
 
 SEE ALSO
 --------
diff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt
index 5c9888d..8f9439a 100644
--- a/Documentation/git-blame.txt
+++ b/Documentation/git-blame.txt
@@ -8,8 +8,9 @@ git-blame - Show what revision and author last modified each line of a file
 SYNOPSIS
 --------
 [verse]
-'git-blame' [-c] [-l] [-t] [-f] [-n] [-p] [--incremental] [-L n,m] [-S <revs-file>]
-            [-M] [-C] [-C] [--since=<date>] [<rev> | --contents <file>] [--] <file>
+'git-blame' [-c] [-l] [-t] [-f] [-n] [-p] [--incremental] [-L n,m]
+            [-S <revs-file>] [-M] [-C] [-C] [--since=<date>]
+            [<rev> | --contents <file>] [--] <file>
 
 DESCRIPTION
 -----------
@@ -37,20 +38,19 @@ ea4c7f9bf69e781dd0cd88d2bccb2bf5cc15c9a7 git-blame: Make the output
 
 OPTIONS
 -------
--c, --compatibility::
-	Use the same output mode as gitlink:git-annotate[1] (Default: off).
-
--L n,m::
-	Annotate only the specified line range (lines count from 1).
-
--l, --long::
-	Show long rev (Default: off).
+include::blame-options.txt[]
 
--t, --time::
-	Show raw timestamp (Default: off).
+-c::
+	Use the same output mode as gitlink:git-annotate[1] (Default: off).
 
--S, --rev-file <revs-file>::
-	Use revs from revs-file instead of calling gitlink:git-rev-list[1].
+--score-debug::
+	Include debugging information related to the movement of
+	lines between files (see `-C`) and lines moved within a
+	file (see `-M`).  The first number listed is the score.
+	This is the number of alphanumeric characters detected
+	to be moved between or within files.  This must be above
+	a certain threshold for git-blame to consider those lines
+	of code to have been moved.
 
 -f, --show-name::
 	Show filename in the original commit.  By default
@@ -60,42 +60,6 @@ OPTIONS
 -n, --show-number::
 	Show line number in the original commit (Default: off).
 
--p, --porcelain::
-	Show in a format designed for machine consumption.
-
---incremental::
-	Show the result incrementally in a format designed for
-	machine consumption.
-
---contents <file>::
-	When <rev> is not specified, the command annotates the
-	changes starting backwards from the working tree copy.
-	This flag makes the command pretend as if the working
-	tree copy has the contents of he named file (specify
-	`-` to make the command read from the standard input).
-
--M::
-	Detect moving lines in the file as well.  When a commit
-	moves a block of lines in a file (e.g. the original file
-	has A and then B, and the commit changes it to B and
-	then A), traditional 'blame' algorithm typically blames
-	the lines that were moved up (i.e. B) to the parent and
-	assigns blame to the lines that were moved down (i.e. A)
-	to the child commit.  With this option, both groups of
-	lines are blamed on the parent.
-
--C::
-	In addition to `-M`, detect lines copied from other
-	files that were modified in the same commit.  This is
-	useful when you reorganize your program and move code
-	around across files.  When this option is given twice,
-	the command looks for copies from all other files in the
-	parent for the commit that creates the file in addition.
-
--h, --help::
-	Show help message.
-
-
 THE PORCELAIN FORMAT
 --------------------
 
diff --git a/builtin-blame.c b/builtin-blame.c
index 60ec535..3a1a17f 100644
--- a/builtin-blame.c
+++ b/builtin-blame.c
@@ -19,11 +19,11 @@
 
 static char blame_usage[] =
 "git-blame [-c] [-l] [-t] [-f] [-n] [-p] [-L n,m] [-S <revs-file>] [-M] [-C] [-C] [--contents <filename>] [--incremental] [commit] [--] file\n"
-"  -c, --compatibility Use the same output mode as git-annotate (Default: off)\n"
+"  -c                  Use the same output mode as git-annotate (Default: off)\n"
 "  -b                  Show blank SHA-1 for boundary commits (Default: off)\n"
-"  -l, --long          Show long commit SHA1 (Default: off)\n"
+"  -l                  Show long commit SHA1 (Default: off)\n"
 "  --root              Do not treat root commits as boundaries (Default: off)\n"
-"  -t, --time          Show raw timestamp (Default: off)\n"
+"  -t                  Show raw timestamp (Default: off)\n"
 "  -f, --show-name     Show original filename (Default: auto)\n"
 "  -n, --show-number   Show original linenumber (Default: off)\n"
 "  -p, --porcelain     Show in a format designed for machine consumption\n"
-- 
1.5.1.1.98.gedb4f-dirty

Re: [PATCH] Update git-annotate/git-blame documentation

[Alex Riesen]

On 4/16/07, Andrew Ruder <andy@aeruder.net> wrote:
> +-L n,m::
> +       Annotate only the specified line range (lines count from 1).
> +
> +-l::
> +       Show long rev (Default: off).
> +
> +-t::
> +       Show raw timestamp (Default: off).

Very nice, mentioning this small details. Thanks!

Re: [PATCH] Update git-annotate/git-blame documentation

[Andrew Ruder]

On Mon, Apr 16, 2007 at 09:24:08AM +0200, Alex Riesen wrote:
> On 4/16/07, Andrew Ruder <andy@aeruder.net> wrote:
> >+-L n,m::
> >+       Annotate only the specified line range (lines count from 1).
> >+
> >+-l::
> >+       Show long rev (Default: off).
> >+
> >+-t::
> >+       Show raw timestamp (Default: off).
> 
> Very nice, mentioning this small details. Thanks!

Those particular items I didn't write, so I'm going to bounce that
thanks off to whoever did. :)

-- 
Andrew Ruder <andy@aeruder.net>
http://www.aeruder.net

Re: [PATCH] Update git-annotate/git-blame documentation

[Junio C Hamano]

Andrew Ruder <andy@aeruder.net> writes:

> On Mon, Apr 16, 2007 at 09:24:08AM +0200, Alex Riesen wrote:
>> On 4/16/07, Andrew Ruder <andy@aeruder.net> wrote:
>> >+-L n,m::
>> >+       Annotate only the specified line range (lines count from 1).
>> >+
>> >+-l::
>> >+       Show long rev (Default: off).
>> >+
>> >+-t::
>> >+       Show raw timestamp (Default: off).
>> 
>> Very nice, mentioning this small details. Thanks!
>
> Those particular items I didn't write, so I'm going to bounce that
> thanks off to whoever did. :)

I almost never give line numbers to -L, by the way.

	$ git log --grep=-L -- builtin-blame.c builtin-pickaxe.c

would give enough raw material to update the section with.

[PATCH] Update git-annotate/git-blame documentation

[Andrew Ruder]

Moved options that pertained to both git-blame and git-annotate to a
common file blame-options.txt.

builtin-blame.c: Removed --compatibility, --long, --time from the
short usage as they are not handled in the code.

Documentation/git-blame.txt: Removed common options to git-annotate.
Added documentation for --score-debug.  Removed --compatibility.
Adjusted usage at top to not wrap on 80 columns.

Documentation/git-annotate.txt: Using common options blame-options.txt.

Documentation/blame-options.txt: Added -b note about associated config
option, added --root note about associated config option, added
documentation for --show-stats.  Removed --long, --time, --rev-file as
those options do not really exist.  Added documentation for -M/-C taking
an optional score argument for detection of moved lines.

Added additional forms for -L n,m to man page (/regex/ and
+offset/-offset)

Signed-off-by: Andrew Ruder <andy@aeruder.net>
---
 Thanks for the pointers on the -L flag, those are some very useful ways
 of specifying line numbers. :)
 
 Documentation/blame-options.txt |   87 +++++++++++++++++++++++++++++++++++++++
 Documentation/git-annotate.txt  |   15 +------
 Documentation/git-blame.txt     |   64 ++++++----------------------
 builtin-blame.c                 |    6 +-
 4 files changed, 105 insertions(+), 67 deletions(-)

diff --git a/Documentation/blame-options.txt b/Documentation/blame-options.txt
new file mode 100644
index 0000000..0099bb2
--- /dev/null
+++ b/Documentation/blame-options.txt
@@ -0,0 +1,87 @@
+-b::
+	Show blank SHA-1 for boundary commits.  This can also
+	be controlled via the `blame.blankboundary` config option.
+
+--root::
+	Do not treat root commits as boundaries.  This can also be
+	controlled via the `blame.showroot` config option.
+
+--show-stats::
+	Include additional statistics at the end of blame output.
+
+-L <start>,<end>::
+	Annotate only the given line range.  <start> and <end> can take
+	one of these forms:
+
+	- number
++
+	If <start> or <end> is a number, it specifies an
+	absolute line number (lines count from 1).
++
+
+	- /regex/
++
+	This form will use the first line matching the given
+	POSIX regex.  If <end> is a regex, it will search
+	starting at the line given by <start>.
++
+
+	- +offset or -offset
++
+	This is only valid for <end> and will specify a number
+	of lines before or after the line given by <start>.
++
+
+-l::
+	Show long rev (Default: off).
+
+-t::
+	Show raw timestamp (Default: off).
+
+-S <revs-file>::
+	Use revs from revs-file instead of calling gitlink:git-rev-list[1].
+
+-p, --porcelain::
+	Show in a format designed for machine consumption.
+
+--incremental::
+	Show the result incrementally in a format designed for
+	machine consumption.
+
+--contents <file>::
+	When <rev> is not specified, the command annotates the
+	changes starting backwards from the working tree copy.
+	This flag makes the command pretend as if the working
+	tree copy has the contents of he named file (specify
+	`-` to make the command read from the standard input).
+
+-M|<num>|::
+	Detect moving lines in the file as well.  When a commit
+	moves a block of lines in a file (e.g. the original file
+	has A and then B, and the commit changes it to B and
+	then A), traditional 'blame' algorithm typically blames
+	the lines that were moved up (i.e. B) to the parent and
+	assigns blame to the lines that were moved down (i.e. A)
+	to the child commit.  With this option, both groups of lines
+	are blamed on the parent.
+
+	<num> is optional but it is the lower bound on the number of
+	alphanumeric characters that git must detect as moving
+	within a file for it to associate those lines with the parent
+	commit.
+
+-C|<num>|::
+	In addition to `-M`, detect lines copied from other
+	files that were modified in the same commit.  This is
+	useful when you reorganize your program and move code
+	around across files.  When this option is given twice,
+	the command looks for copies from all other files in the
+	parent for the commit that creates the file in addition.
+
+	<num> is optional but it is the lower bound on the number of
+	alphanumeric characters that git must detect as moving
+	between files for it to associate those lines with the parent
+	commit.
+
+-h, --help::
+	Show help message.
diff --git a/Documentation/git-annotate.txt b/Documentation/git-annotate.txt
index 7baf731..02dc474 100644
--- a/Documentation/git-annotate.txt
+++ b/Documentation/git-annotate.txt
@@ -16,20 +16,7 @@ which introduced the line. Optionally annotate from a given revision.
 
 OPTIONS
 -------
--l, --long::
-	Show long rev (Defaults off).
-
--t, --time::
-	Show raw timestamp (Defaults off).
-
--r, --rename::
-	Follow renames (Defaults on).
-
--S, --rev-file <revs-file>::
-	Use revs from revs-file instead of calling git-rev-list.
-
--h, --help::
-	Show help message.
+include::blame-options.txt[]
 
 SEE ALSO
 --------
diff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt
index 5c9888d..8f9439a 100644
--- a/Documentation/git-blame.txt
+++ b/Documentation/git-blame.txt
@@ -8,8 +8,9 @@ git-blame - Show what revision and author last modified each line of a file
 SYNOPSIS
 --------
 [verse]
-'git-blame' [-c] [-l] [-t] [-f] [-n] [-p] [--incremental] [-L n,m] [-S <revs-file>]
-            [-M] [-C] [-C] [--since=<date>] [<rev> | --contents <file>] [--] <file>
+'git-blame' [-c] [-l] [-t] [-f] [-n] [-p] [--incremental] [-L n,m]
+            [-S <revs-file>] [-M] [-C] [-C] [--since=<date>]
+            [<rev> | --contents <file>] [--] <file>
 
 DESCRIPTION
 -----------
@@ -37,20 +38,19 @@ ea4c7f9bf69e781dd0cd88d2bccb2bf5cc15c9a7 git-blame: Make the output
 
 OPTIONS
 -------
--c, --compatibility::
-	Use the same output mode as gitlink:git-annotate[1] (Default: off).
-
--L n,m::
-	Annotate only the specified line range (lines count from 1).
-
--l, --long::
-	Show long rev (Default: off).
+include::blame-options.txt[]
 
--t, --time::
-	Show raw timestamp (Default: off).
+-c::
+	Use the same output mode as gitlink:git-annotate[1] (Default: off).
 
--S, --rev-file <revs-file>::
-	Use revs from revs-file instead of calling gitlink:git-rev-list[1].
+--score-debug::
+	Include debugging information related to the movement of
+	lines between files (see `-C`) and lines moved within a
+	file (see `-M`).  The first number listed is the score.
+	This is the number of alphanumeric characters detected
+	to be moved between or within files.  This must be above
+	a certain threshold for git-blame to consider those lines
+	of code to have been moved.
 
 -f, --show-name::
 	Show filename in the original commit.  By default
@@ -60,42 +60,6 @@ OPTIONS
 -n, --show-number::
 	Show line number in the original commit (Default: off).
 
--p, --porcelain::
-	Show in a format designed for machine consumption.
-
---incremental::
-	Show the result incrementally in a format designed for
-	machine consumption.
-
---contents <file>::
-	When <rev> is not specified, the command annotates the
-	changes starting backwards from the working tree copy.
-	This flag makes the command pretend as if the working
-	tree copy has the contents of he named file (specify
-	`-` to make the command read from the standard input).
-
--M::
-	Detect moving lines in the file as well.  When a commit
-	moves a block of lines in a file (e.g. the original file
-	has A and then B, and the commit changes it to B and
-	then A), traditional 'blame' algorithm typically blames
-	the lines that were moved up (i.e. B) to the parent and
-	assigns blame to the lines that were moved down (i.e. A)
-	to the child commit.  With this option, both groups of
-	lines are blamed on the parent.
-
--C::
-	In addition to `-M`, detect lines copied from other
-	files that were modified in the same commit.  This is
-	useful when you reorganize your program and move code
-	around across files.  When this option is given twice,
-	the command looks for copies from all other files in the
-	parent for the commit that creates the file in addition.
-
--h, --help::
-	Show help message.
-
-
 THE PORCELAIN FORMAT
 --------------------
 
diff --git a/builtin-blame.c b/builtin-blame.c
index 60ec535..3a1a17f 100644
--- a/builtin-blame.c
+++ b/builtin-blame.c
@@ -19,11 +19,11 @@
 
 static char blame_usage[] =
 "git-blame [-c] [-l] [-t] [-f] [-n] [-p] [-L n,m] [-S <revs-file>] [-M] [-C] [-C] [--contents <filename>] [--incremental] [commit] [--] file\n"
-"  -c, --compatibility Use the same output mode as git-annotate (Default: off)\n"
+"  -c                  Use the same output mode as git-annotate (Default: off)\n"
 "  -b                  Show blank SHA-1 for boundary commits (Default: off)\n"
-"  -l, --long          Show long commit SHA1 (Default: off)\n"
+"  -l                  Show long commit SHA1 (Default: off)\n"
 "  --root              Do not treat root commits as boundaries (Default: off)\n"
-"  -t, --time          Show raw timestamp (Default: off)\n"
+"  -t                  Show raw timestamp (Default: off)\n"
 "  -f, --show-name     Show original filename (Default: auto)\n"
 "  -n, --show-number   Show original linenumber (Default: off)\n"
 "  -p, --porcelain     Show in a format designed for machine consumption\n"
-- 
1.5.1.1.98.gedb4f-dirty

[PATCH] Update git-apply documentation

[Andrew Ruder]

Document -v (short form of --verbose).  Redo usage
to not wrap on 80 column terminal with typical
settings.

Signed-off-by: Andrew Ruder <andy@aeruder.net>
---
 Documentation/git-apply.txt |   13 +++++++------
 1 files changed, 7 insertions(+), 6 deletions(-)

diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt
index 065ba1b..3bd2c99 100644
--- a/Documentation/git-apply.txt
+++ b/Documentation/git-apply.txt
@@ -9,11 +9,12 @@ git-apply - Apply a patch on a git index file and a working tree
 SYNOPSIS
 --------
 [verse]
-'git-apply' [--stat] [--numstat] [--summary] [--check] [--index] [--apply]
-	  [--no-add] [--index-info] [--allow-binary-replacement | --binary]
-	  [-R | --reverse] [--reject] [-z] [-pNUM] [-CNUM] [--inaccurate-eof]
-	  [--whitespace=<nowarn|warn|error|error-all|strip>] [--exclude=PATH]
-	  [--cached] [--verbose] [<patch>...]
+'git-apply' [--stat] [--numstat] [--summary] [--check] [--index]
+	  [--apply] [--no-add] [--index-info] [-R | --reverse]
+	  [--allow-binary-replacement | --binary] [--reject] [-z]
+	  [-pNUM] [-CNUM] [--inaccurate-eof] [--cached]
+	  [--whitespace=<nowarn|warn|error|error-all|strip>]
+	  [--exclude=PATH] [--verbose] [<patch>...]
 
 DESCRIPTION
 -----------
@@ -158,7 +159,7 @@ discouraged.
 	correctly. This option adds support for applying such patches by
 	working around this bug.
 
---verbose::
+-v, --verbose::
 	Report progress to stderr. By default, only a message about the
 	current patch being applied will be printed. This option will cause
 	additional information to be reported.
-- 
1.5.1.1.98.gedb4f-dirty

[PATCH] Update git-archive documentation

[Andrew Ruder]

Documentation/git-archive.txt: Document -v/--verbose option.
Add -l as short form of --list.

Signed-off-by: Andrew Ruder <andy@aeruder.net>
---
 Documentation/git-archive.txt |    5 ++++-
 1 files changed, 4 insertions(+), 1 deletions(-)

diff --git a/Documentation/git-archive.txt b/Documentation/git-archive.txt
index 8d10415..d3ca9a9 100644
--- a/Documentation/git-archive.txt
+++ b/Documentation/git-archive.txt
@@ -33,9 +33,12 @@ OPTIONS
 	Format of the resulting archive: 'tar', 'zip'...  The default
 	is 'tar'.
 
---list::
+--list, -l::
 	Show all available formats.
 
+--verbose, -v::
+	Report progress to stderr.
+
 --prefix=<prefix>/::
 	Prepend <prefix>/ to each filename in the archive.
 
-- 
1.5.1.1.116.g8c4c

[PATCH] Update git-cherry-pick documentation

[Andrew Ruder]

Documentation/git-cherry-pick.txt: Remove --replay as it is not
handled by the code (-r is however).

Signed-off-by: Andrew Ruder <andy@aeruder.net>
---
 Documentation/git-cherry-pick.txt |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt
index 3149d08..68bba98 100644
--- a/Documentation/git-cherry-pick.txt
+++ b/Documentation/git-cherry-pick.txt
@@ -38,7 +38,7 @@ OPTIONS
 	development branch), adding this information can be
 	useful.
 
--r|--replay::
+-r::
 	It used to be that the command defaulted to do `-x`
 	described above, and `-r` was to disable it.  Now the
 	default is not to do `-x` so this option is a no-op.
-- 
1.5.1.1.116.g8c4c

[PATCH] Fix unmatched emphasis tag in git-tutorial

[Andrew Ruder]

In asciidoc 7.1.2 and prior there is no obvious way to get:

'add'ing

to emphasize only the "add", instead it treats the first apostrophe as the
beginning of an emphasis, and the second apostrophe as a regular
apostrophe and makes the rest of the line an emphasis since there is no
closing apostrophe.  In the newer asciidoc you can do it pretty easily
with __add__ing but I'm not sure it would be best to make that a prereq
for something as silly as this.

Signed-off-by: Andrew Ruder <andy@aeruder.net>
---
 Documentation/tutorial.txt |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

diff --git a/Documentation/tutorial.txt b/Documentation/tutorial.txt
index 129c5c5..e978562 100644
--- a/Documentation/tutorial.txt
+++ b/Documentation/tutorial.txt
@@ -111,7 +111,7 @@ make it real.
 Note: don't forget to 'add' a file again if you modified it after the
 first 'add' and before 'commit'. Otherwise only the previous added
 state of that file will be committed. This is because git tracks
-content, so what you're really 'add'ing to the commit is the *content*
+content, so what you're really 'adding' to the commit is the *content*
 of the file in the state it is in when you 'add' it.
 
 2) By using 'git commit -a' directly
-- 
1.5.1.1.116.g8c4c

[PATCH] Update git-config documentation

[Andrew Ruder]

Documentation/git-config.txt: Added documentation for --system
Documentation/builtin-config.c: Added --system to the short usage

Signed-off-by: Andrew Ruder <andy@aeruder.net>
---
 Documentation/git-config.txt |   24 ++++++++++++++----------
 builtin-config.c             |    2 +-
 2 files changed, 15 insertions(+), 11 deletions(-)

diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt
index c759efb..280ef20 100644
--- a/Documentation/git-config.txt
+++ b/Documentation/git-config.txt
@@ -9,16 +9,16 @@ git-config - Get and set repository or global options
 SYNOPSIS
 --------
 [verse]
-'git-config' [--global] [type] name [value [value_regex]]
-'git-config' [--global] [type] --add name value
-'git-config' [--global] [type] --replace-all name [value [value_regex]]
-'git-config' [--global] [type] --get name [value_regex]
-'git-config' [--global] [type] --get-all name [value_regex]
-'git-config' [--global] [type] --unset name [value_regex]
-'git-config' [--global] [type] --unset-all name [value_regex]
-'git-config' [--global] [type] --rename-section old_name new_name
-'git-config' [--global] [type] --remove-section name
-'git-config' [--global] -l | --list
+'git-config' [--system | --global] [type] name [value [value_regex]]
+'git-config' [--system | --global] [type] --add name value
+'git-config' [--system | --global] [type] --replace-all name [value [value_regex]]
+'git-config' [--system | --global] [type] --get name [value_regex]
+'git-config' [--system | --global] [type] --get-all name [value_regex]
+'git-config' [--system | --global] [type] --unset name [value_regex]
+'git-config' [--system | --global] [type] --unset-all name [value_regex]
+'git-config' [--system | --global] [type] --rename-section old_name new_name
+'git-config' [--system | --global] [type] --remove-section name
+'git-config' [--system | --global] -l | --list
 
 DESCRIPTION
 -----------
@@ -76,6 +76,10 @@ OPTIONS
 --global::
 	Use global ~/.gitconfig file rather than the repository .git/config.
 
+--system::
+	Use system-wide $(prefix)/etc/gitconfig rather than the repository
+	.git/config.
+
 --remove-section::
 	Remove the given section from the configuration file.
 
diff --git a/builtin-config.c b/builtin-config.c
index dfa403b..b2515f7 100644
--- a/builtin-config.c
+++ b/builtin-config.c
@@ -2,7 +2,7 @@
 #include "cache.h"
 
 static const char git_config_set_usage[] =
-"git-config [ --global ] [ --bool | --int ] [--get | --get-all | --get-regexp | --replace-all | --add | --unset | --unset-all] name [value [value_regex]] | --rename-section old_name new_name | --remove-section name | --list";
+"git-config [ --global | --system ] [ --bool | --int ] [--get | --get-all | --get-regexp | --replace-all | --add | --unset | --unset-all] name [value [value_regex]] | --rename-section old_name new_name | --remove-section name | --list";
 
 static char *key;
 static regex_t *key_regexp;
-- 
1.5.1.1.116.g8c4c