From: Junio C Hamano <gitster@pobox.com>
Date: Mon, 5 Oct 2015 19:30:26 +0000 (-0700)
Subject: Merge branch 'mm/keyid-docs'
X-Git-Tag: v2.7.0-rc0~130
X-Git-Url: https://git.lorimer.id.au/gitweb.git/diff_plain/e13d854322ad802213aea13409505c765b5c68d1?ds=inline;hp=-c

Merge branch 'mm/keyid-docs'

Very small number of options take a parameter that is optional
(which is not a great UI element as they can only appear at the end
of the command line).  Add notice to documentation of each and
every one of them.

* mm/keyid-docs:
Documentation: explain optional arguments better
Documentation/grep: fix documentation of -O
Documentation: use 'keyid' consistently, not 'key-id'
---

e13d854322ad802213aea13409505c765b5c68d1
diff --combined Documentation/git-am.txt
index dbea6e7ae9,6b09891db3..452c1feb23
--- a/Documentation/git-am.txt
+++ b/Documentation/git-am.txt
@@@ -10,7 -10,7 +10,7 @@@ SYNOPSI
  --------
  [verse]
  'git am' [--signoff] [--keep] [--[no-]keep-cr] [--[no-]utf8]
 -	 [--3way] [--interactive] [--committer-date-is-author-date]
 +	 [--[no-]3way] [--interactive] [--committer-date-is-author-date]
  	 [--ignore-date] [--ignore-space-change | --ignore-whitespace]
  	 [--whitespace=<option>] [-C<n>] [-p<n>] [--directory=<dir>]
  	 [--exclude=<path>] [--include=<path>] [--reject] [-q | --quiet]
@@@ -90,13 -90,10 +90,13 @@@ default.   You can use `--no-utf8` to o
  
  -3::
  --3way::
 +--no-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
 -	available locally.
 +	available locally. `--no-3way` can be used to override
 +	am.threeWay configuration variable. For more information,
 +	see am.threeWay in linkgit:git-config[1].
  
  --ignore-space-change::
  --ignore-whitespace::
@@@ -141,7 -138,9 +141,9 @@@
  
  -S[<keyid>]::
  --gpg-sign[=<keyid>]::
- 	GPG-sign commits.
+ 	GPG-sign commits. The `keyid` argument is optional and
+ 	defaults to the committer identity; if specified, it must be
+ 	stuck to the option without a space.
  
  --continue::
  -r::
diff --combined Documentation/git-merge.txt
index a62d6729b9,c06c4f2fb0..07f7295ec8
--- a/Documentation/git-merge.txt
+++ b/Documentation/git-merge.txt
@@@ -10,7 -10,7 +10,7 @@@ SYNOPSI
  --------
  [verse]
  'git merge' [-n] [--stat] [--no-commit] [--squash] [--[no-]edit]
- 	[-s <strategy>] [-X <strategy-option>] [-S[<key-id>]]
+ 	[-s <strategy>] [-X <strategy-option>] [-S[<keyid>]]
  	[--[no-]rerere-autoupdate] [-m <msg>] [<commit>...]
  'git merge' <msg> HEAD <commit>...
  'git merge' --abort
@@@ -67,7 -67,9 +67,9 @@@ include::merge-options.txt[
  
  -S[<keyid>]::
  --gpg-sign[=<keyid>]::
- 	GPG-sign the resulting merge commit.
+ 	GPG-sign the resulting merge commit. The `keyid` argument is
+ 	optional and defaults to the committer identity; if specified,
+ 	it must be stuck to the option without a space.
  
  -m <msg>::
  	Set the commit message to be used for the merge commit (in
@@@ -78,7 -80,7 +80,7 @@@ will be appended to the specified messa
  +
  The 'git fmt-merge-msg' command can be
  used to give a good default for automated 'git merge'
 -invocations.
 +invocations. The automated message can include the branch description.
  
  --[no-]rerere-autoupdate::
  	Allow the rerere mechanism to update the index with the
diff --combined Documentation/git-rebase.txt
index 72e69fc165,6d72945814..6cca8bb51d
--- a/Documentation/git-rebase.txt
+++ b/Documentation/git-rebase.txt
@@@ -213,15 -213,6 +213,15 @@@ rebase.autoSquash:
  rebase.autoStash::
  	If set to true enable '--autostash' option by default.
  
 +rebase.missingCommitsCheck::
 +	If set to "warn", print warnings about removed commits in
 +	interactive mode. If set to "error", print the warnings and
 +	stop the rebase. If set to "ignore", no checking is
 +	done. "ignore" by default.
 +
 +rebase.instructionFormat::
 +	Custom commit list format to use during an '--interactive' rebase.
 +
  OPTIONS
  -------
  --onto <newbase>::
@@@ -294,7 -285,9 +294,9 @@@ which makes little sense
  
  -S[<keyid>]::
  --gpg-sign[=<keyid>]::
- 	GPG-sign commits.
+ 	GPG-sign commits. The `keyid` argument is optional and
+ 	defaults to the committer identity; if specified, it must be
+ 	stuck to the option without a space.
  
  -q::
  --quiet::
@@@ -368,10 -361,6 +370,10 @@@ default is `--no-fork-point`, otherwis
  	Make a list of the commits which are about to be rebased.  Let the
  	user edit that list before rebasing.  This mode can also be used to
  	split commits (see SPLITTING COMMITS below).
 ++
 +The commit list format can be changed by setting the configuration option
 +rebase.instructionFormat.  A customized instruction format will automatically
 +have the long commit hash prepended to the format.
  
  -p::
  --preserve-merges::
@@@ -432,8 -421,7 +434,8 @@@ If the '--autosquash' option is enable
  configuration variable `rebase.autoSquash`, this option can be
  used to override and disable this setting.
  
 ---[no-]autostash::
 +--autostash::
 +--no-autostash::
  	Automatically create a temporary stash before the operation
  	begins, and apply it after the operation ends.  This means
  	that you can run rebase on a dirty worktree.  However, use
@@@ -528,9 -516,6 +530,9 @@@ rebasing
  If you just want to edit the commit message for a commit, replace the
  command "pick" with the command "reword".
  
 +To drop a commit, replace the command "pick" with "drop", or just
 +delete the matching line.
 +
  If you want to fold two or more commits into one, replace the command
  "pick" for the second and subsequent commits with "squash" or "fixup".
  If the commits had different authors, the folded commit will be
diff --combined Documentation/git-tag.txt
index 3803bf7fb9,e95a3364bb..7220e5eca1
--- a/Documentation/git-tag.txt
+++ b/Documentation/git-tag.txt
@@@ -9,12 -9,11 +9,12 @@@ git-tag - Create, list, delete or verif
  SYNOPSIS
  --------
  [verse]
- 'git tag' [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>]
+ 'git tag' [-a | -s | -u <keyid>] [-f] [-m <msg> | -F <file>]
  	<tagname> [<commit> | <object>]
  'git tag' -d <tagname>...
  'git tag' [-n[<num>]] -l [--contains <commit>] [--points-at <object>]
 -	[--column[=<options>] | --no-column] [<pattern>...]
 +	[--column[=<options>] | --no-column] [--create-reflog] [--sort=<key>]
 +	[--format=<format>] [--[no-]merged [<commit>]] [<pattern>...]
  'git tag' -v <tagname>...
  
  DESCRIPTION
@@@ -25,19 -24,19 +25,19 @@@ to delete, list or verify tags
  
  Unless `-f` is given, the named tag must not yet exist.
  
- If one of `-a`, `-s`, or `-u <key-id>` is passed, the command
+ If one of `-a`, `-s`, or `-u <keyid>` is passed, the command
  creates a 'tag' object, and requires a tag message.  Unless
  `-m <msg>` or `-F <file>` is given, an editor is started for the user to type
  in the tag message.
  
- If `-m <msg>` or `-F <file>` is given and `-a`, `-s`, and `-u <key-id>`
+ If `-m <msg>` or `-F <file>` is given and `-a`, `-s`, and `-u <keyid>`
  are absent, `-a` is implied.
  
  Otherwise just a tag reference for the SHA-1 object name of the commit object is
  created (i.e. a lightweight tag).
  
  A GnuPG signed tag object will be created when `-s` or `-u
- <key-id>` is used.  When `-u <key-id>` is not used, the
+ <keyid>` is used.  When `-u <keyid>` is not used, the
  committer identity for the current user is used to find the
  GnuPG key for signing. 	The configuration variable `gpg.program`
  is used to specify custom GnuPG binary.
@@@ -64,8 -63,8 +64,8 @@@ OPTION
  --sign::
  	Make a GPG-signed tag, using the default e-mail address's key.
  
- -u <key-id>::
- --local-user=<key-id>::
+ -u <keyid>::
+ --local-user=<keyid>::
  	Make a GPG-signed tag, using the given key.
  
  -f::
@@@ -95,16 -94,14 +95,16 @@@
  	using fnmatch(3)).  Multiple patterns may be given; if any of
  	them matches, the tag is shown.
  
 ---sort=<type>::
 -	Sort in a specific order. Supported type is "refname"
 -	(lexicographic order), "version:refname" or "v:refname" (tag
 +--sort=<key>::
 +	Sort based on the key given.  Prefix `-` to sort in
 +	descending order of the value. You may use the --sort=<key> option
 +	multiple times, in which case the last key becomes the primary
 +	key. Also supports "version:refname" or "v:refname" (tag
  	names are treated as versions). The "version:refname" sort
  	order can also be affected by the
 -	"versionsort.prereleaseSuffix" configuration variable. Prepend
 -	"-" to reverse sort order. When this option is not given, the
 -	sort order defaults to the value configured for the 'tag.sort'
 +	"versionsort.prereleaseSuffix" configuration variable.
 +	The keys supported are the same as those in `git for-each-ref`.
 +	Sort order defaults to the value configured for the 'tag.sort'
  	variable if it exists, or lexicographic order otherwise. See
  	linkgit:git-config[1].
  
@@@ -128,14 -125,14 +128,14 @@@ This option is only applicable when lis
  	Use the given tag message (instead of prompting).
  	If multiple `-m` options are given, their values are
  	concatenated as separate paragraphs.
- 	Implies `-a` if none of `-a`, `-s`, or `-u <key-id>`
+ 	Implies `-a` if none of `-a`, `-s`, or `-u <keyid>`
  	is given.
  
  -F <file>::
  --file=<file>::
  	Take the tag message from the given file.  Use '-' to
  	read the message from the standard input.
- 	Implies `-a` if none of `-a`, `-s`, or `-u <key-id>`
+ 	Implies `-a` if none of `-a`, `-s`, or `-u <keyid>`
  	is given.
  
  --cleanup=<mode>::
@@@ -145,9 -142,6 +145,9 @@@
  	all, 'whitespace' removes just leading/trailing whitespace lines and
  	'strip' removes both whitespace and commentary.
  
 +--create-reflog::
 +	Create a reflog for the tag.
 +
  <tagname>::
  	The name of the tag to create, delete, or describe.
  	The new tag name must pass all checks defined by
@@@ -159,16 -153,6 +159,16 @@@
  	The object that the new tag will refer to, usually a commit.
  	Defaults to HEAD.
  
 +<format>::
 +	A string that interpolates `%(fieldname)` from the object
 +	pointed at by a ref being shown.  The format is the same as
 +	that of linkgit:git-for-each-ref[1].  When unspecified,
 +	defaults to `%(refname:short)`.
 +
 +--[no-]merged [<commit>]::
 +	Only list tags whose tips are reachable, or not reachable
 +	if '--no-merged' is used, from the specified commit ('HEAD'
 +	if not specified).
  
  CONFIGURATION
  -------------
@@@ -179,7 -163,7 +179,7 @@@ it in the repository configuration as f
  
  -------------------------------------
  [user]
-     signingKey = <gpg-key-id>
+     signingKey = <gpg-keyid>
  -------------------------------------