From: Junio C Hamano <gitster@pobox.com>
Date: Fri, 16 Oct 2015 21:32:33 +0000 (-0700)
Subject: Merge branch 'mm/keyid-docs' into maint
X-Git-Tag: v2.6.2~21
X-Git-Url: https://git.lorimer.id.au/gitweb.git/diff_plain/be4d6f4c7f94541fac1a06e4c04acc2d60de1f8c?hp=-c

Merge branch 'mm/keyid-docs' into maint

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'
---

be4d6f4c7f94541fac1a06e4c04acc2d60de1f8c
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 ca039546a4,6d72945814..bccfdf7fde
--- 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::
@@@ -527,9 -516,6 +529,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 84f6496bf2,e95a3364bb..08b4dfbf1b
--- a/Documentation/git-tag.txt
+++ b/Documentation/git-tag.txt
@@@ -9,11 -9,11 +9,11 @@@ 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] [<pattern>...]
  'git tag' -v <tagname>...
  
  DESCRIPTION
@@@ -24,19 -24,19 +24,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.
@@@ -63,8 -63,8 +63,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::
@@@ -125,14 -125,14 +125,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>::
@@@ -142,9 -142,6 +142,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
@@@ -166,7 -163,7 +166,7 @@@ it in the repository configuration as f
  
  -------------------------------------
  [user]
-     signingKey = <gpg-key-id>
+     signingKey = <gpg-keyid>
  -------------------------------------