From: Jakub Narebski <hidden> Date: 2016-06-15 22:43:17
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
@@ -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.
From: Jakub Narebski <hidden> Date: 2016-06-15 22:43:17
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 <redacted>
---
Documentation/pretty-options.txt | 9 +++++++++
1 files changed, 9 insertions(+), 0 deletions(-)
@@ -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
@@ -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::
@@ -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.
@@ -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.
From: Jakub Narebski <hidden> Date: 2016-06-15 22:43:17
Note that those options apply also to git-status.
Signed-off-by: Jakub Narebski <redacted>
---
Documentation/git-commit.txt | 10 +++++++++-
1 files changed, 9 insertions(+), 1 deletions(-)
@@ -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.
@@ -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
@@ -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.
@@ -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
From: Jakub Narebski <hidden> Date: 2016-06-15 22:43:17
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 <redacted>
---
Documentation/git-reflog.txt | 13 +++++++++++++
1 files changed, 13 insertions(+), 0 deletions(-)
@@ -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`,
@@ -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.