Docs: Use "-l::\n--long\n" format in OPTIONS sections

The OPTIONS section of a documentation file contains a list
of the options a git command accepts.

Currently there are several variants to describe the case that
different options (almost) do the same in the OPTIONS section.

Some are:

 -f, --foo::
 -f|--foo::
 -f | --foo::

But AsciiDoc has the special form:

 -f::
 --foo::

This patch applies this form to the documentation of the whole git suite,
and removes useless em-dash prevention, so \--foo becomes --foo.

Signed-off-by: Stephan Beyer <s-beyer@gmx.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

56 files changed, 394 insertions, 210 deletions

diff --git a/Documentation/blame-options.txt b/Documentation/blame-options.txt
index c11bb7d36c..5428111d73 100644
--- a/Documentation/blame-options.txt
+++ b/Documentation/blame-options.txt
@@ -41,7 +41,8 @@ of lines before or after the line given by <start>.
 -S <revs-file>::
 	Use revs from revs-file instead of calling linkgit:git-rev-list[1].
 
--p, --porcelain::
+-p::
+--porcelain::
 	Show in a format designed for machine consumption.
 
 --incremental::
@@ -83,5 +84,6 @@ alphanumeric characters that git must detect as moving
 between files for it to associate those lines with the parent
 commit.
 
--h, --help::
+-h::
+--help::
 	Show help message.
diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt
index b675911480..85c87180db 100644
--- a/Documentation/fetch-options.txt
+++ b/Documentation/fetch-options.txt
@@ -1,22 +1,26 @@
--q, \--quiet::
+-q::
+--quiet::
 	Pass --quiet to git-fetch-pack and silence any other internally
 	used programs.
 
--v, \--verbose::
+-v::
+--verbose::
 	Be verbose.
 
--a, \--append::
+-a::
+--append::
 	Append ref names and object names of fetched refs to the
 	existing contents of `.git/FETCH_HEAD`.  Without this
 	option old data in `.git/FETCH_HEAD` will be overwritten.
 
-\--upload-pack <upload-pack>::
+--upload-pack <upload-pack>::
 	When given, and the repository to fetch from is handled
 	by 'git-fetch-pack', '--exec=<upload-pack>' is passed to
 	the command to specify non-default path for the command
 	run on the other end.
 
--f, \--force::
+-f::
+--force::
 	When `git-fetch` is used with `<rbranch>:<lbranch>`
 	refspec, it refuses to update the local branch
 	`<lbranch>` unless the remote branch `<rbranch>` it
@@ -24,16 +28,18 @@
 	overrides that check.
 
 ifdef::git-pull[]
-\--no-tags::
+--no-tags::
 endif::git-pull[]
 ifndef::git-pull[]
--n, \--no-tags::
+-n::
+--no-tags::
 endif::git-pull[]
 	By default, tags that point at objects that are downloaded
 	from the remote repository are fetched and stored locally.
 	This option disables this automatic tag following.
 
--t, \--tags::
+-t::
+--tags::
 	Most of the tags are fetched automatically as branch
 	heads are downloaded, but tags that do not point at
 	objects reachable from the branch heads that are being
@@ -41,10 +47,12 @@ endif::git-pull[]
 	flag lets all tags and their associated objects be
 	downloaded.
 
--k, \--keep::
+-k::
+--keep::
 	Keep downloaded pack.
 
--u, \--update-head-ok::
+-u::
+--update-head-ok::
 	By default `git-fetch` refuses to update the head which
 	corresponds to the current branch.  This flag disables the
 	check.  This is purely for the internal use for `git-pull`
@@ -52,7 +60,7 @@ endif::git-pull[]
 	implementing your own Porcelain you are not supposed to
 	use it.
 
-\--depth=<depth>::
+--depth=<depth>::
 	Deepen the history of a 'shallow' repository created by
 	`git clone` with `--depth=<depth>` option (see linkgit:git-clone[1])
 	by the specified number of commits.
diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt
index 88165da38f..9c6b081e6c 100644
--- a/Documentation/git-add.txt
+++ b/Documentation/git-add.txt
@@ -50,22 +50,26 @@ OPTIONS
 	and `dir/file2`) can be given to add all files in the
 	directory, recursively.
 
--n, \--dry-run::
+-n::
+--dry-run::
         Don't actually add the file(s), just show if they exist.
 
--v, \--verbose::
+-v::
+--verbose::
         Be verbose.
 
 -f::
 	Allow adding otherwise ignored files.
 
--i, \--interactive::
+-i::
+--interactive::
 	Add modified contents in the working tree interactively to
 	the index. Optional path arguments may be supplied to limit
 	operation to a subset of the working tree. See ``Interactive
 	mode'' for details.
 
--p, \--patch::
+-p::
+--patch::
 	Similar to Interactive mode but the initial command loop is
 	bypassed and the 'patch' subcommand is invoked using each of
 	the specified filepatterns before exiting.
@@ -79,11 +83,11 @@ OPTIONS
 	command line. If no paths are specified, all tracked files in the
 	current directory and its subdirectories are updated.
 
-\--refresh::
+--refresh::
 	Don't add the file(s), but only refresh their stat()
 	information in the index.
 
-\--ignore-errors::
+--ignore-errors::
 	If some files could not be added because of errors indexing
 	them, do not abort the operation, but continue adding the
 	others. The command shall still exit with non-zero status.
diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt
index 7f6f5b472a..46544a0769 100644
--- a/Documentation/git-am.txt
+++ b/Documentation/git-am.txt
@@ -28,14 +28,17 @@ OPTIONS
 	supply this argument, reads from the standard input. If you supply
 	directories, they'll be treated as Maildirs.
 
--s, --signoff::
+-s::
+--signoff::
 	Add `Signed-off-by:` line to the commit message, using
 	the committer identity of yourself.
 
--k, --keep::
+-k::
+--keep::
 	Pass `-k` flag to `git-mailinfo` (see linkgit:git-mailinfo[1]).
 
--u, --utf8::
+-u::
+--utf8::
 	Pass `-u` flag to `git-mailinfo` (see linkgit:git-mailinfo[1]).
 	The proposed commit log message taken from the e-mail
 	is re-coded into UTF-8 encoding (configuration variable
@@ -49,13 +52,15 @@ default.   You could use `--no-utf8` to override this.
 	Pass `-n` flag to `git-mailinfo` (see
 	linkgit:git-mailinfo[1]).
 
--3, --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
 	available locally.
 
--b, --binary::
+-b::
+--binary::
 	Pass `--allow-binary-replacement` flag to `git-apply`
 	(see linkgit:git-apply[1]).
 
@@ -64,19 +69,22 @@ default.   You could use `--no-utf8` to override this.
 	program that applies
 	the patch.
 
--C<n>, -p<n>::
+-C<n>::
+-p<n>::
 	These flags are passed to the `git-apply` (see linkgit:git-apply[1])
 	program that applies
 	the patch.
 
--i, --interactive::
+-i::
+--interactive::
 	Run interactively.
 
 --skip::
 	Skip the current patch.  This is only meaningful when
 	restarting an aborted patch.
 
--r, --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.
diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt
index 76277bd178..c8347637da 100644
--- a/Documentation/git-apply.txt
+++ b/Documentation/git-apply.txt
@@ -73,7 +73,8 @@ OPTIONS
 When a pure mode change is encountered (which has no index information),
 the information is read from the current index instead.
 
--R, --reverse::
+-R::
+--reverse::
 	Apply the patch in reverse.
 
 --reject::
@@ -124,7 +125,8 @@ discouraged.
 	the result with this option, which would apply the
 	deletion part but not addition part.
 
---allow-binary-replacement, --binary::
+--allow-binary-replacement::
+--binary::
 	Historically we did not allow binary patch applied
 	without an explicit permission from the user, and this
 	flag was the way to do so.  Currently we always allow binary
@@ -169,7 +171,8 @@ behavior:
 	correctly. This option adds support for applying such patches by
 	working around this bug.
 
--v, --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.
diff --git a/Documentation/git-archive.txt b/Documentation/git-archive.txt
index a3e36dbb0d..9b5f3ae5ed 100644
--- a/Documentation/git-archive.txt
+++ b/Documentation/git-archive.txt
@@ -36,10 +36,12 @@ OPTIONS
 	Format of the resulting archive: 'tar' or 'zip'.  The default
 	is 'tar'.
 
---list, -l::
+-l::
+--list::
 	Show all available formats.
 
---verbose, -v::
+-v::
+--verbose::
 	Report progress to stderr.
 
 --prefix=<prefix>/::
diff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt
index 7900f33d4b..8f4fb46685 100644
--- a/Documentation/git-blame.txt
+++ b/Documentation/git-blame.txt
@@ -52,12 +52,14 @@ include::blame-options.txt[]
 	a certain threshold for git-blame to consider those lines
 	of code to have been moved.
 
--f, --show-name::
+-f::
+--show-name::
 	Show filename in the original commit.  By default
 	filename is shown if there is any line that came from a
 	file with different name, due to rename detection.
 
--n, --show-number::
+-n::
+--show-number::
 	Show line number in the original commit (Default: off).
 
 -s::
diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
index a70fa76f31..0fd58083eb 100644
--- a/Documentation/git-branch.txt
+++ b/Documentation/git-branch.txt
@@ -95,7 +95,8 @@ OPTIONS
 -a::
 	List both remote-tracking branches and local branches.
 
--v, --verbose::
+-v::
+--verbose::
 	Show sha1 and commit subject line for each head.
 
 --abbrev=<length>::
diff --git a/Documentation/git-checkout-index.txt b/Documentation/git-checkout-index.txt
index a8cad9c21f..676203b2eb 100644
--- a/Documentation/git-checkout-index.txt
+++ b/Documentation/git-checkout-index.txt
@@ -22,21 +22,26 @@ Will copy all files listed from the index to the working directory
 
 OPTIONS
 -------
--u|--index::
+-u::
+--index::
 	update stat information for the checked out entries in
 	the index file.
 
--q|--quiet::
+-q::
+--quiet::
 	be quiet if files exist or are not in the index
 
--f|--force::
+-f::
+--force::
 	forces overwrite of existing files
 
--a|--all::
+-a::
+--all::
 	checks out all files in the index.  Cannot be used
 	together with explicit filenames.
 
--n|--no-create::
+-n::
+--no-create::
 	Don't checkout new files, only refresh files already checked
 	out.
 
diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index a5bf9d6f89..3ad9760a4d 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -47,7 +47,8 @@ OPTIONS
 	by linkgit:git-check-ref-format[1].  Some of these checks
 	may restrict the characters allowed in a branch name.
 
--t, --track::
+-t::
+--track::
 	When creating a new branch, set up configuration so that git-pull
 	will automatically retrieve data from the start point, which must be
 	a branch. Use this if you always pull from the same upstream branch
diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt
index 3762272b88..5ac9cfb0ef 100644
--- a/Documentation/git-cherry-pick.txt
+++ b/Documentation/git-cherry-pick.txt
@@ -22,7 +22,8 @@ OPTIONS
 	For a more complete list of ways to spell commits, see
 	"SPECIFYING REVISIONS" section in linkgit:git-rev-parse[1].
 
--e|--edit::
+-e::
+--edit::
 	With this option, `git-cherry-pick` will let you edit the commit
 	message prior to committing.
 
@@ -44,14 +45,16 @@ OPTIONS
 	described above, and `-r` was to disable it.  Now the
 	default is not to do `-x` so this option is a no-op.
 
--m parent-number|--mainline parent-number::
+-m parent-number::
+--mainline parent-number::
 	Usually you cannot cherry-pick a merge because you do not know which
 	side of the merge should be considered the mainline.  This
 	option specifies the parent number (starting from 1) of
 	the mainline and allows cherry-pick to replay the change
 	relative to the specified parent.
 
--n|--no-commit::
+-n::
+--no-commit::
 	Usually the command automatically creates a commit with
 	a commit log message stating which commit was
 	cherry-picked.  This flag applies the change necessary
@@ -64,7 +67,8 @@ OPTIONS
 This is useful when cherry-picking more than one commits'
 effect to your working tree in a row.
 
--s|--signoff::
+-s::
+--signoff::
 	Add Signed-off-by line at the end of the commit message.
 
 
diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
index af52728943..7e8b4ff72c 100644
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt
@@ -52,21 +52,25 @@ that, you can recover from it with linkgit:git-reset[1].
 
 OPTIONS
 -------
--a|--all::
+-a::
+--all::
 	Tell the command to automatically stage files that have
 	been modified and deleted, but new files you have not
 	told git about are not affected.
 
--C <commit>|--reuse-message=<commit>::
+-C <commit>::
+--reuse-message=<commit>::
 	Take an existing commit object, and reuse the log message
 	and the authorship information (including the timestamp)
 	when creating the commit.
 
--c <commit>|--reedit-message=<commit>::
+-c <commit>::
+--reedit-message=<commit>::
 	Like '-C', but with '-c' the editor is invoked, so that
 	the user can further edit the commit message.
 
--F <file>|--file=<file>::
+-F <file>::
+--file=<file>::
 	Take the commit message from the given file.  Use '-' to
 	read the message from the standard input.
 
@@ -74,20 +78,24 @@ OPTIONS
 	Override the author name used in the commit.  Use
 	`A U Thor <author@example.com>` format.
 
--m <msg>|--message=<msg>::
+-m <msg>::
+--message=<msg>::
 	Use the given <msg> as the commit message.
 
--t <file>|--template=<file>::
+-t <file>::
+--template=<file>::
 	Use the contents of the given file as the initial version
 	of the commit message. The editor is invoked and you can
 	make subsequent changes. If a message is specified using
 	the `-m` or `-F` options, this option has no effect. This
 	overrides the `commit.template` configuration variable.
 
--s|--signoff::
+-s::
+--signoff::
 	Add Signed-off-by line at the end of the commit message.
 
--n|--no-verify::
+-n::
+--no-verify::
 	This option bypasses the pre-commit and commit-msg hooks.
 	See also linkgit:githooks[5][hooks].
 
@@ -107,7 +115,8 @@ OPTIONS
 	'whitespace' removes just leading/trailing whitespace lines
 	and 'strip' removes both whitespace and commentary.
 
--e|--edit::
+-e::
+--edit::
 	The message taken from file with `-F`, command line with
 	`-m`, and from file with `-C` are usually used as the
 	commit log message unmodified.  This option lets you
@@ -134,13 +143,15 @@ It is a rough equivalent for:
 but can be used to amend a merge commit.
 --
 
--i|--include::
+-i::
+--include::
 	Before making a commit out of staged contents so far,
 	stage the contents of paths given on the command line
 	as well.  This is usually not what you want unless you
 	are concluding a conflicted merge.
 
--o|--only::
+-o::
+--only::
 	Make a commit only from the paths specified on the
 	command line, disregarding any contents that have been
 	staged so far. This is the default mode of operation of
@@ -151,20 +162,23 @@ but can be used to amend a merge commit.
 	the last commit without committing changes that have
 	already been staged.
 
--u|--untracked-files::
+-u::
+--untracked-files::
 	Show all untracked files, also those in uninteresting
 	directories, in the "Untracked files:" section of commit
 	message template.  Without this option only its name and
 	a trailing slash are displayed for each untracked
 	directory.
 
--v|--verbose::
+-v::
+--verbose::
 	Show unified diff between the HEAD commit and what
 	would be committed at the bottom of the commit message
 	template.  Note that this diff output doesn't have its
 	lines prefixed with '#'.
 
--q|--quiet::
+-q::
+--quiet::
 	Suppress commit summary message.
 
 \--::
diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt
index 84b754f8d0..c90421ee7f 100644
--- a/Documentation/git-config.txt
+++ b/Documentation/git-config.txt
@@ -101,7 +101,8 @@ rather than from all available files.
 +
 See also <<FILES>>.
 
--f config-file, --file config-file::
+-f config-file::
+--file config-file::
 	Use the given config file instead of the one specified by GIT_CONFIG.
 
 --remove-section::
@@ -116,7 +117,8 @@ See also <<FILES>>.
 --unset-all::
 	Remove all lines matching the key from config file.
 
--l, --list::
+-l::
+--list::
 	List all variables set in config file.
 
 --bool::
@@ -128,7 +130,8 @@ See also <<FILES>>.
 	in the config file will cause the value to be multiplied
 	by 1024, 1048576, or 1073741824 prior to output.
 
--z, --null::
+-z::
+--null::
 	For all options that output values and/or keys, always
 	end values with the null character (instead of a
 	newline). Use newline instead as a delimiter between
diff --git a/Documentation/git-cvsserver.txt b/Documentation/git-cvsserver.txt
index b7721131dd..3310ae25ff 100644
--- a/Documentation/git-cvsserver.txt
+++ b/Documentation/git-cvsserver.txt
@@ -41,10 +41,13 @@ Don't allow recursing into subdirectories
 Don't check for `gitcvs.enabled` in config. You also have to specify a list
 of allowed directories (see below) if you want to use this option.
 
---version, -V::
+-V::
+--version::
 Print version information and exit
 
---help, -h, -H::
+-h::
+-H::
+--help::
 Print usage information and exit
 
 <directory>::
diff --git a/Documentation/git-daemon.txt b/Documentation/git-daemon.txt
index 3fb71d683e..344f24ea59 100644
--- a/Documentation/git-daemon.txt
+++ b/Documentation/git-daemon.txt
@@ -103,7 +103,8 @@ OPTIONS
 	Log to syslog instead of stderr. Note that this option does not imply
 	--verbose, thus by default only error conditions will be logged.
 
---user-path, --user-path=path::
+--user-path::
+--user-path=path::
 	Allow ~user notation to be used in requests.  When
 	specified with no parameter, requests to
 	git://host/~alice/foo is taken as a request to access
@@ -127,7 +128,8 @@ OPTIONS
 	Save the process id in 'file'.  Ignored when the daemon
 	is run under `--inetd`.
 
---user=user, --group=group::
+--user=user::
+--group=group::
 	Change daemon's uid and gid before entering the service loop.
 	When only `--user` is given without `--group`, the
 	primary group ID for the user is used.  The values of
@@ -138,14 +140,16 @@ Giving these options is an error when used with `--inetd`; use
 the facility of inet daemon to achieve the same before spawning
 `git-daemon` if needed.
 
---enable=service, --disable=service::
+--enable=service::
+--disable=service::
 	Enable/disable the service site-wide per default.  Note
 	that a service disabled site-wide can still be enabled
 	per repository if it is marked overridable and the
 	repository enables the service with an configuration
 	item.
 
---allow-override=service, --forbid-override=service::
+--allow-override=service::
+--forbid-override=service::
 	Allow/forbid overriding the site-wide default with per
 	repository configuration.  By default, all the services
 	are overridable.