doc: convert git pull to synopsis style

- Switch the synopsis to a synopsis block which will automatically
  format placeholders in italics and keywords in monospace
- Use _<placeholder>_ instead of <placeholder> in the description
- Use `backticks` for keywords and more complex option
descriptions. The new rendering engine will apply synopsis rules to
these spans.

Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/fetch-options.adoc b/Documentation/fetch-options.adoc
index 35a84a1ef276725cd6720b4619dd2da90d5de22f..fcba46ee9e5d61c90297d3563187618571ed8a12 100644 (file)
--- a/Documentation/fetch-options.adoc
+++ b/Documentation/fetch-options.adoc
@@ -71,7 +71,7 @@ configuration variables documented in linkgit:git-config[1], and the
 
 `--negotiate-only`::
        Do not fetch anything from the server, and instead print the
-       ancestors of the provided `--negotiation-tip=*` arguments,
+       ancestors of the provided `--negotiation-tip=` arguments,
        which we have in common with the server.
 +
 This is incompatible with `--recurse-submodules=(yes|on-demand)`.
@@ -126,7 +126,7 @@ ifndef::git-pull[]
 `--auto-gc`::
 `--no-auto-gc`::
        Run `git maintenance run --auto` at the end to perform automatic
-       repository maintenance if needed. (`--[no-]auto-gc` is a synonym.)
+       repository maintenance if needed.
        This is enabled by default.
 
 `--write-commit-graph`::
@@ -193,7 +193,7 @@ endif::git-pull[]
        specified refspec (can be given more than once) to map the
        refs to remote-tracking branches, instead of the values of
        `remote.<name>.fetch` configuration variables for the remote
-       repository.  Providing an empty `<refspec>` to the
+       repository.  Providing an empty _<refspec>_ to the
        `--refmap` option causes Git to ignore the configured
        refspecs and rely entirely on the refspecs supplied as
        command-line arguments. See section on "Configured Remote-tracking
@@ -204,7 +204,7 @@ endif::git-pull[]
        Fetch all tags from the remote (i.e., fetch remote tags
        `refs/tags/*` into local tags with the same name), in addition
        to whatever else would otherwise be fetched.  Using this
-       option alone does not subject tags to pruning, even if --prune
+       option alone does not subject tags to pruning, even if `--prune`
        is used (though tags may be pruned anyway if they are also the
        destination of an explicit refspec; see `--prune`).
 
@@ -306,7 +306,7 @@ endif::git-pull[]
 `-o <option>`::
 `--server-option=<option>`::
        Transmit the given string to the server when communicating using
-       protocol version 2.  The given string must not contain a NUL or LF
+       protocol version 2.  The given string must not contain a _NUL_ or _LF_
        character.  The server's handling of server options, including
        unknown ones, is server-specific.
        When multiple `--server-option=<option>` are given, they are all

diff --git a/Documentation/git-pull.adoc b/Documentation/git-pull.adoc
index cd3bbc90e3008d73f8d6bdde97da8b68e84f16a8..248f6c3f39ac7434de1f07da415b09e87aff1399 100644 (file)
--- a/Documentation/git-pull.adoc
+++ b/Documentation/git-pull.adoc
@@ -8,8 +8,8 @@ git-pull - Fetch from and integrate with another repository or a local branch
 
 SYNOPSIS
 --------
-[verse]
-'git pull' [<options>] [<repository> [<refspec>...]]
+[synopsis]
+git pull [<options>] [<repository> [<refspec>...]]
 
 
 DESCRIPTION
@@ -43,7 +43,7 @@ want to handle, you can safely abort it with `git merge --abort` or `git
 OPTIONS
 -------
 
-<repository>::
+_<repository>_::
        The "remote" repository to pull from.  This can be either
        a URL (see the section <<URLS,GIT URLS>> below) or the name
        of a remote (see the section <<REMOTES,REMOTES>> below).
@@ -52,29 +52,29 @@ Defaults to the configured upstream for the current branch, or `origin`.
 See <<UPSTREAM-BRANCHES,UPSTREAM BRANCHES>> below for more on how to
 configure upstreams.
 
-<refspec>::
+_<refspec>_::
        Which branch or other reference(s) to fetch and integrate into the
        current branch, for example `main` in `git pull origin main`.
        Defaults to the configured upstream for the current branch.
 +
 This can be a branch, tag, or other collection of reference(s).
-See <<fetch-refspec,<refspec>>> below under "Options related to fetching"
+See <<fetch-refspec,_<refspec>_>> below under "Options related to fetching"
 for the full syntax, and <<DEFAULT-BEHAVIOUR,DEFAULT BEHAVIOUR>> below
 for how `git pull` uses this argument to determine which remote branch
 to integrate.
 
--q::
---quiet::
+`-q`::
+`--quiet`::
        This is passed to both underlying git-fetch to squelch reporting of
        during transfer, and underlying git-merge to squelch output during
        merging.
 
--v::
---verbose::
-       Pass --verbose to git-fetch and git-merge.
+`-v`::
+`--verbose`::
+       Pass `--verbose` to git-fetch and git-merge.
 
---recurse-submodules[=(yes|on-demand|no)]::
---no-recurse-submodules::
+`--recurse-submodules[=(yes|on-demand|no)]`::
+`--no-recurse-submodules`::
        This option controls if new commits of populated submodules should
        be fetched, and if the working trees of active submodules should be
        updated, too (see linkgit:git-fetch[1], linkgit:git-config[1] and
@@ -91,21 +91,20 @@ Options related to merging
 
 include::merge-options.adoc[]
 
--r::
---rebase[=(false|true|merges|interactive)]::
-       When true, rebase the current branch on top of the upstream
+`-r`::
+`--rebase[=(true|merges|false|interactive)]`::
+`true`;; rebase the current branch on top of the upstream
        branch after fetching. If there is a remote-tracking branch
        corresponding to the upstream branch and the upstream branch
        was rebased since last fetched, the rebase uses that information
-       to avoid rebasing non-local changes.
-+
-When set to `merges`, rebase using `git rebase --rebase-merges` so that
+       to avoid rebasing non-local changes. This is the default.
+
+`merges`;; rebase using `git rebase --rebase-merges` so that
 the local merge commits are included in the rebase (see
 linkgit:git-rebase[1] for details).
-+
-When false, merge the upstream branch into the current branch.
-+
-When `interactive`, enable the interactive mode of rebase.
+`false`;; merge the upstream branch into the current branch.
+`interactive`;; enable the interactive mode of rebase.
+
 +
 See `pull.rebase`, `branch.<name>.rebase` and `branch.autoSetupRebase` in
 linkgit:git-config[1] if you want to make `git pull` always use
@@ -117,8 +116,8 @@ It rewrites history, which does not bode well when you
 published that history already.  Do *not* use this option
 unless you have read linkgit:git-rebase[1] carefully.
 
---no-rebase::
-       This is shorthand for --rebase=false.
+`--no-rebase`::
+       This is shorthand for `--rebase=false`.
 
 Options related to fetching
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -178,7 +177,7 @@ uses the refspec from the configuration or
 rules apply:
 
 . If `branch.<name>.merge` configuration for the current
-  branch `<name>` exists, that is the name of the branch at the
+  branch _<name>_ exists, that is the name of the branch at the
   remote site that is merged.
 
 . If the refspec is a globbing one, nothing is merged.
@@ -198,9 +197,9 @@ $ git pull
 $ git pull origin
 ------------------------------------------------
 +
-Normally the branch merged in is the HEAD of the remote repository,
-but the choice is determined by the branch.<name>.remote and
-branch.<name>.merge options; see linkgit:git-config[1] for details.
+Normally the branch merged in is the `HEAD` of the remote repository,
+but the choice is determined by the `branch.<name>.remote` and
+`branch.<name>.merge` options; see linkgit:git-config[1] for details.
 
 * Merge into the current branch the remote branch `next`:
 +
@@ -208,7 +207,7 @@ branch.<name>.merge options; see linkgit:git-config[1] for details.
 $ git pull origin next
 ------------------------------------------------
 +
-This leaves a copy of `next` temporarily in FETCH_HEAD, and
+This leaves a copy of `next` temporarily in `FETCH_HEAD`, and
 updates the remote-tracking branch `origin/next`.
 The same can be done by invoking fetch and merge:
 +
@@ -219,14 +218,14 @@ $ git merge origin/next
 
 
 If you tried a pull which resulted in complex conflicts and
-would want to start over, you can recover with 'git reset'.
+would want to start over, you can recover with `git reset`.
 
 
 include::transfer-data-leaks.adoc[]
 
 BUGS
 ----
-Using --recurse-submodules can only fetch new commits in already checked
+Using `--recurse-submodules` can only fetch new commits in already checked
 out submodules right now. When e.g. upstream added a new submodule in the
 just fetched commits of the superproject the submodule itself cannot be
 fetched, making it impossible to check out that submodule later without

diff --git a/Documentation/merge-options.adoc b/Documentation/merge-options.adoc
index 9d433265b2984bfc0eb97902e21ee9f5ce70ccaa..952cb85e9a4af9c2403e017a7ec71e7a8c13cd79 100644 (file)
--- a/Documentation/merge-options.adoc
+++ b/Documentation/merge-options.adoc
@@ -56,7 +56,7 @@ ifdef::git-pull[]
 `--ff-only`::
        Only update to the new history if there is no divergent local
        history.  This is the default when no method for reconciling
-       divergent histories is provided (via the --rebase=* flags).
+       divergent histories is provided (via the `--rebase` flags).
 
 `--ff`::
 `--no-ff`::

diff --git a/Documentation/urls-remotes.adoc b/Documentation/urls-remotes.adoc
index 068b3ee4a69b612eb966910a609647bf9baaacc7..6878bbe0939c7e275c4c577104187a337d0afd93 100644 (file)
--- a/Documentation/urls-remotes.adoc
+++ b/Documentation/urls-remotes.adoc
@@ -76,7 +76,7 @@ _<URL>_ is required; `#<head>` is optional.
 
 Depending on the operation, git will use one of the following
 refspecs, if you don't provide one on the command line.
-_<branch> is the name of this file in `$GIT_DIR/branches` and
+_<branch>_ is the name of this file in `$GIT_DIR/branches` and
 _<head>_ defaults to `master`.
 
 git fetch uses:
@@ -111,7 +111,7 @@ Git defaults to using the upstream branch for remote operations, for example:
   'origin/main' have diverged, and have 2 and 3 different commits each
   respectively".
 
-The upstream is stored in `.git/config`, in the "remote" and "merge"
+The upstream is stored in `.git/config`, in the "`remote`" and "`merge`"
 fields. For example, if `main`'s upstream is `origin/main`:
 
 ------------