[PATCH 00/11] Document missing options

[PATCH 00/11] Document missing options

[Jakub Narebski]

This series of patches documents [some] options which were missing
from the documentation.

Table of contents:
==================
 [PATCH 01/11] Use tabs for indenting definition list for options in git-log.txt
 [PATCH 02/11] Document git log --full-diff
 [PATCH 03/11] Document git log --abbrev-commit, as a kind of pretty option
 [PATCH 04/11] Document that '--message=<msg>' is long version of '-m <msg>'
 [PATCH 05/11] Document that '--no-checkout' is long version of '-n' option of git-clone
 [PATCH 06/11] Document git rev-list --timestamp
 [PATCH 07/11] Document git rev-list --full-history
 [PATCH 08/11] Document git rev-parse --is-inside-git-dir
 [PATCH 09/11] Document git read-tree --trivial
 [PATCH 10/11] Document git reflog --stale-fix
 [PATCH 11/11] Document git commit --untracked-files and --verbose

What is still undocumented are:
 * git clone --no-separate-remote, which is deprecated and perhaps
   should be left undocumented.
 * git commit -o|--only, which is now default when providing files
   to be committed, and -i|--include is not present. Description
   of this option was removed in commit 6c96753d:
     "Documentation/git-commit: rewrite to make it more end-user friendly."
   Should we re-add this description?
 * git commit --reedit-message (--reedit) and --reuse-message
   (--reuse). I'm not sure what are the meaning of those options, and
   how they differ from -c (or -C --edit) and -C. I think, but I'm not
   sure, that --reedit-message is long form of -c, and --reuse-message
   is long form of -C.
 * git reflog --dry-run. The --dry-run option in other command describe
   what would be done. I think that this option does not work for this
   command.

I have checked only ling options in builtins and shell scripts; I have
not checked Perl scripts not short options, and I might have missed
some options for which the same named option but for different command
exists in the documentation.

I might have missed modifying usage strings in command source, and
in command documentation.

But I think this series of patches is a good start...
---
 Documentation/git-clone.txt      |    1 +
 Documentation/git-commit.txt     |   12 ++++++++++--
 Documentation/git-log.txt        |    9 ++++++++-
 Documentation/git-read-tree.txt  |    8 +++++++-
 Documentation/git-reflog.txt     |   13 +++++++++++++
 Documentation/git-rev-list.txt   |   13 +++++++++++++
 Documentation/git-rev-parse.txt  |    4 ++++
 Documentation/pretty-options.txt |    9 +++++++++
 builtin-read-tree.c              |    2 +-
 9 files changed, 66 insertions(+), 5 deletions(-)

--
Jakub Narebski
Poland

[PATCH 01/11] Use tabs for indenting definition list for options in git-log.txt

[Jakub Narebski]

Signed-off-by: Jakub Narebski <jnareb@gmail.com>
---
 Documentation/git-log.txt |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt
index 6157edb..c072441 100644
--- a/Documentation/git-log.txt
+++ b/Documentation/git-log.txt
@@ -52,7 +52,7 @@ include::pretty-options.txt[]
 	See also gitlink:git-reflog[1].
 
 --decorate::
-    Print out the ref names of any commits that are shown.
+	Print out the ref names of any commits that are shown.
 
 <paths>...::
 	Show only commits that affect the specified paths.
-- 
1.5.2

[PATCH 02/11] Document git log --full-diff

[Jakub Narebski]

Based on description of commit 477f2b41310c4b1040a9e7f72720b9c39d82caf9
"git log --full-diff" adding this option.

Signed-off-by: Jakub Narebski <jnareb@gmail.com>
---
 Documentation/git-log.txt |    7 +++++++
 1 files changed, 7 insertions(+), 0 deletions(-)

diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt
index c072441..7adcdef 100644
--- a/Documentation/git-log.txt
+++ b/Documentation/git-log.txt
@@ -54,6 +54,13 @@ include::pretty-options.txt[]
 --decorate::
 	Print out the ref names of any commits that are shown.
 
+--full-diff::
+	Without this flag, "git log -p <paths>..." shows commits that
+	touch the specified paths, and diffs about the same specified
+	paths.  With this, the full diff is shown for commits that touch
+	the specified paths; this means that "<paths>..." limits only
+	commits, and doesn't limit diff for those commits.
+
 <paths>...::
 	Show only commits that affect the specified paths.
 
-- 
1.5.2

[PATCH 03/11] Document git log --abbrev-commit, as a kind of pretty option

[Jakub Narebski]

Documentation taken from paraphrased description of "--abbrev[=<n>]"
diff option, and from description of commit 5c51c985 introducing
this option.

Note that to change number of digits one must use "--abbrev=<n>",
which affects [also] diff output.

Signed-off-by: Jakub Narebski <jnareb@gmail.com>
---
 Documentation/pretty-options.txt |    9 +++++++++
 1 files changed, 9 insertions(+), 0 deletions(-)

diff --git a/Documentation/pretty-options.txt b/Documentation/pretty-options.txt
index 6338def..746bc5b 100644
--- a/Documentation/pretty-options.txt
+++ b/Documentation/pretty-options.txt
@@ -5,6 +5,15 @@
 	'full', 'fuller', 'email', 'raw' and 'format:<string>'.
 	When left out the format default to 'medium'.
 
+--abbrev-commit::
+	Instead of showing the full 40-byte hexadecimal commit object
+	name, show only handful hexdigits prefix.  Non default number of
+	digits can be specified with "--abbrev=<n>" (which also modifies
+	diff output, if it is displayed).
++
+This should make "--pretty=oneline" a whole lot more readable for
+people using 80-column terminals.
+
 --encoding[=<encoding>]::
 	The commit objects record the encoding used for the log message
 	in their encoding header; this option can be used to tell the
-- 
1.5.2

[PATCH 04/11] Document that '--message=<msg>' is long version of '-m <msg>'

[Jakub Narebski]

Signed-off-by: Jakub Narebski <jnareb@gmail.com>
---
 Documentation/git-commit.txt |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
index 53a7bb0..352a494 100644
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt
@@ -71,7 +71,7 @@ OPTIONS
 	Override the author name used in the commit.  Use
 	`A U Thor <author@example.com>` format.
 
--m <msg>::
+-m <msg>|--message=<msg>::
 	Use the given <msg> as the commit message.
 
 -s|--signoff::
-- 
1.5.2

[PATCH 05/11] Document that '--no-checkout' is long version of '-n' option of git-clone

[Jakub Narebski]

Signed-off-by: Jakub Narebski <jnareb@gmail.com>
---
 Documentation/git-clone.txt |    1 +
 1 files changed, 1 insertions(+), 0 deletions(-)

diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
index 4a5bab5..796cbba 100644
--- a/Documentation/git-clone.txt
+++ b/Documentation/git-clone.txt
@@ -64,6 +64,7 @@ OPTIONS
 	Operate quietly.  This flag is passed to "rsync" and
 	"git-fetch-pack" commands when given.
 
+--no-checkout::
 -n::
 	No checkout of HEAD is performed after the clone is complete.
 
-- 
1.5.2

[PATCH 06/11] Document git rev-list --timestamp

[Jakub Narebski]

Note that git log does not understand this option yet:

  $ git log --timestamp
  fatal: unrecognized argument: --timestamp

Signed-off-by: Jakub Narebski <jnareb@gmail.com>
---
 Documentation/git-rev-list.txt |    4 ++++
 1 files changed, 4 insertions(+), 0 deletions(-)

diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt
index 0dba73f..f5e5786 100644
--- a/Documentation/git-rev-list.txt
+++ b/Documentation/git-rev-list.txt
@@ -21,6 +21,7 @@ SYNOPSIS
 	     [ \--stdin ]
 	     [ \--topo-order ]
 	     [ \--parents ]
+	     [ \--timestamp ]
 	     [ \--left-right ]
 	     [ \--cherry-pick ]
 	     [ \--encoding[=<encoding>] ]
@@ -116,6 +117,9 @@ e.g. "2 hours ago".
 
 	Print the parents of the commit.
 
+--timestamp::
+	Print the raw commit timestamp.
+
 --left-right::
 
 	Mark which side of a symmetric diff a commit is reachable from.
-- 
1.5.2

[PATCH 07/11] Document git rev-list --full-history

[Jakub Narebski]

Signed-off-by: Jakub Narebski <jnareb@gmail.com>
---
 Documentation/git-rev-list.txt |    9 +++++++++
 1 files changed, 9 insertions(+), 0 deletions(-)

diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt
index f5e5786..32cb13f 100644
--- a/Documentation/git-rev-list.txt
+++ b/Documentation/git-rev-list.txt
@@ -16,6 +16,7 @@ SYNOPSIS
 	     [ \--sparse ]
 	     [ \--no-merges ]
 	     [ \--remove-empty ]
+	     [ \--full-history ]
 	     [ \--not ]
 	     [ \--all ]
 	     [ \--stdin ]
@@ -232,6 +233,14 @@ limiting may be applied.
 
 	Stop when a given path disappears from the tree.
 
+--full-history::
+
+	Show also parts of history irrelevant to current state of a given
+	path. This turns off history simplification, which removed merges
+	which didn't change anything at all at some child. It will still actually
+	simplify away merges that didn't change anything at all into either
+	child.
+
 --no-merges::
 
 	Do not print commits with more than one parent.
-- 
1.5.2

[PATCH 08/11] Document git rev-parse --is-inside-git-dir

[Jakub Narebski]

Signed-off-by: Jakub Narebski <jnareb@gmail.com>
---
 Documentation/git-rev-parse.txt |    4 ++++
 1 files changed, 4 insertions(+), 0 deletions(-)

diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
index e1cb4ef..87771b8 100644
--- a/Documentation/git-rev-parse.txt
+++ b/Documentation/git-rev-parse.txt
@@ -89,6 +89,10 @@ OPTIONS
 --git-dir::
 	Show `$GIT_DIR` if defined else show the path to the .git directory.
 
+--is-inside-git-dir::
+	Return "true" if we are in the git directory, otherwise "false".
+	Some commands require to be run in a working directory.
+
 --short, --short=number::
 	Instead of outputting the full SHA1 values of object names try to
 	abbreviate them to a shorter unique name. When no length is specified
-- 
1.5.2

[PATCH 09/11] Document git read-tree --trivial

[Jakub Narebski]

Signed-off-by: Jakub Narebski <jnareb@gmail.com>
---
 Documentation/git-read-tree.txt |    8 +++++++-
 builtin-read-tree.c             |    2 +-
 2 files changed, 8 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt
index 84184d6..74c5478 100644
--- a/Documentation/git-read-tree.txt
+++ b/Documentation/git-read-tree.txt
@@ -8,7 +8,7 @@ git-read-tree - Reads tree information into the index
 
 SYNOPSIS
 --------
-'git-read-tree' (<tree-ish> | [[-m [--aggressive] | --reset | --prefix=<prefix>] [-u | -i]] [--exclude-per-directory=<gitignore>] [--index-output=<file>] <tree-ish1> [<tree-ish2> [<tree-ish3>]])
+'git-read-tree' (<tree-ish> | [[-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>] [-u | -i]] [--exclude-per-directory=<gitignore>] [--index-output=<file>] <tree-ish1> [<tree-ish2> [<tree-ish3>]])
 
 
 DESCRIPTION
@@ -50,6 +50,12 @@ OPTIONS
 	trees that are not directly related to the current
 	working tree status into a temporary index file.
 
+--trivial::
+	Restrict three-way merge by `git-read-tree` to happen
+	only if there is no file-level merging required, instead
+	of resolving merge for trivial cases and leaving
+	conflicting files unresolved in the index.
+
 --aggressive::
 	Usually a three-way merge by `git-read-tree` resolves
 	the merge for really trivial cases and leaves other
diff --git a/builtin-read-tree.c b/builtin-read-tree.c
index 316fb0f..41f8110 100644
--- a/builtin-read-tree.c
+++ b/builtin-read-tree.c
@@ -84,7 +84,7 @@ static void prime_cache_tree(void)
 
 }
 
-static const char read_tree_usage[] = "git-read-tree (<sha> | [[-m [--aggressive] | --reset | --prefix=<prefix>] [-u | -i]] [--exclude-per-directory=<gitignore>] [--index-output=<file>] <sha1> [<sha2> [<sha3>]])";
+static const char read_tree_usage[] = "git-read-tree (<sha> | [[-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>] [-u | -i]] [--exclude-per-directory=<gitignore>] [--index-output=<file>] <sha1> [<sha2> [<sha3>]])";
 
 static struct lock_file lock_file;
 
-- 
1.5.2

[PATCH 10/11] Document git reflog --stale-fix

[Jakub Narebski]

Document --stale-fix, used in "git reflog expire --stale-fix --all"
to remove invalid reflog entries, to fix situation after running
non reflog-aware git-prune from an older git in the presence of
reflogs (see RelNotes-1.5.0.txt).

Based on description of commit 1389d9ddaa68a4cbf5018d88f971b9bbb7aaa3c9
  "reflog expire --fix-stale"
which introduced this option.

Signed-off-by: Jakub Narebski <jnareb@gmail.com>
---
 Documentation/git-reflog.txt |   13 +++++++++++++
 1 files changed, 13 insertions(+), 0 deletions(-)

diff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt
index f717e1e..89bc9c5 100644
--- a/Documentation/git-reflog.txt
+++ b/Documentation/git-reflog.txt
@@ -39,6 +39,19 @@ the current branch. It is basically an alias for 'git log -g --abbrev-commit
 OPTIONS
 -------
 
+--stale-fix::
+	This revamps the logic -- the definition of "broken commit"
+	becomes: a commit that is not reachable from any of the refs and
+	there is a missing object among the commit, tree, or blob
+	objects reachable from it that is not reachable from any of the
+	refs.
++
+This computation involves traversing all the reachable objects, i.e. it
+has the same cost as 'git prune'.  Fortunately, once this is run, we
+should not have to ever worry about missing objects, because the current
+prune and pack-objects know about reflogs and protect objects referred by
+them.
+
 --expire=<time>::
 	Entries older than this time are pruned.  Without the
 	option it is taken from configuration `gc.reflogExpire`,
-- 
1.5.2

[PATCH 11/11] Document git commit --untracked-files and --verbose

[Jakub Narebski]

Note that those options apply also to git-status.

Signed-off-by: Jakub Narebski <jnareb@gmail.com>
---
 Documentation/git-commit.txt |   10 +++++++++-
 1 files changed, 9 insertions(+), 1 deletions(-)

diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
index 352a494..cd2d4c7 100644
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt
@@ -8,7 +8,7 @@ git-commit - Record changes to the repository
 SYNOPSIS
 --------
 [verse]
-'git-commit' [-a | --interactive] [-s] [-v]
+'git-commit' [-a | --interactive] [-s] [-v] [-u]
 	   [(-c | -C) <commit> | -F <file> | -m <msg> | --amend]
 	   [--no-verify] [-e] [--author <author>]
 	   [--] [[-i | -o ]<file>...]
@@ -115,6 +115,14 @@ but can be used to amend a merge commit.
 	as well.  This is usually not what you want unless you
 	are concluding a conflicted merge.
 
+-u|--untracked-files::
+	Show all untracked files, also those in uninteresting
+	directories.
+
+-v|--verbose::
+	Show the diff output between the HEAD commit and what
+	would be committed.
+
 -q|--quiet::
 	Suppress commit summary message.
 
-- 
1.5.2

Re: [PATCH 11/11] Document git commit --untracked-files and --verbose

[Junio C Hamano]

Jakub Narebski <jnareb@gmail.com> writes:

> +-u|--untracked-files::
> +	Show all untracked files, also those in uninteresting
> +	directories.
> +
> +-v|--verbose::
> +	Show the diff output between the HEAD commit and what
> +	would be committed.
> +

Thanks -- "show" sounds a bit funny, though, don't you think?

Re: [PATCH 11/11] Document git commit --untracked-files and --verbose

[Jakub Narebski]

Junio C Hamano wrote:
> Jakub Narebski <jnareb@gmail.com> writes:
> 
>> +-u|--untracked-files::
>> +	Show all untracked files, also those in uninteresting
>> +	directories.
>> +
>> +-v|--verbose::
>> +	Show the diff output between the HEAD commit and what
>> +	would be committed.
>> +
> 
> Thanks -- "show" sounds a bit funny, though, don't you think?

First, the description above has to be suitable both for git-commit and 
for git-status, as both commands share options. Nevertheless those 
options have slight different meaning: git-status print what is 
"shown", in git-commit what is "shown" appears in the editor as/in 
prepared commit message (printed using git-[run]status).

Second, this is last patch in the series... ;-)


Feel free to correct it if you have better idea for description of those 
options.

-- 
Jakub Narebski
Poland