doc: convert checkout, switch and merge to new format

index a32302299380..e35d21296978 100644
@@ -1,9 +1,9 @@
-checkout.defaultRemote::
+`checkout.defaultRemote`::
 	When you run `git checkout <something>`
 	or `git switch <something>` and only have one
 	remote, it may implicitly fall back on checking out and
 	tracking e.g. `origin/<something>`. This stops working as soon
-	as you have more than one remote with a `<something>`
+	as you have more than one remote with a _<something>_
 	reference. This setting allows for setting the name of a
 	preferred remote that should always win when it comes to
 	disambiguation. The typical use-case is to set this to

@@ -12,17 +12,17 @@ checkout.defaultRemote::
 Currently this is used by linkgit:git-switch[1] and
 linkgit:git-checkout[1] when `git checkout <something>`
 or `git switch <something>`
-will checkout the `<something>` branch on another remote,
+will checkout the _<something>_ branch on another remote,
 and by linkgit:git-worktree[1] when `git worktree add` refers to a
 remote branch. This setting might be used for other checkout-like
 commands or functionality in the future.
 
-checkout.guess::
+`checkout.guess`::
 	Provides the default value for the `--guess` or `--no-guess`
 	option in `git checkout` and `git switch`. See
 	linkgit:git-switch[1] and linkgit:git-checkout[1].
 
-checkout.workers::
+`checkout.workers`::
 	The number of parallel workers to use when updating the working tree.
 	The default is one, i.e. sequential execution. If set to a value less
 	than one, Git will use as many workers as the number of logical cores

@@ -30,13 +30,13 @@ checkout.workers::
 	all commands that perform checkout. E.g. checkout, clone, reset,
 	sparse-checkout, etc.
 +
-Note: Parallel checkout usually delivers better performance for repositories
+NOTE: Parallel checkout usually delivers better performance for repositories
 located on SSDs or over NFS. For repositories on spinning disks and/or machines
 with a small number of cores, the default sequential checkout often performs
 better. The size and compression level of a repository might also influence how
 well the parallel version performs.
 
-checkout.thresholdForParallelism::
+`checkout.thresholdForParallelism`::
 	When running parallel checkout with a small number of files, the cost
 	of subprocess spawning and inter-process communication might outweigh
 	the parallelization gains. This setting allows you to define the minimum

447 lines not on this page · raw message

index 64281d6d44dd..12aa859d16de 100644
@@ -8,13 +8,13 @@ git-merge - Join two or more development histories together
 
 SYNOPSIS
 --------
-[verse]
-'git merge' [-n] [--stat] [--no-commit] [--squash] [--[no-]edit]
+[synopsis]
+git merge [-n] [--stat] [--no-commit] [--squash] [--[no-]edit]
 	[--no-verify] [-s <strategy>] [-X <strategy-option>] [-S[<keyid>]]
 	[--[no-]allow-unrelated-histories]
 	[--[no-]rerere-autoupdate] [-m <msg>] [-F <file>]
 	[--into-name <branch>] [<commit>...]
-'git merge' (--continue | --abort | --quit)
+git merge (--continue | --abort | --quit)
 
 DESCRIPTION
 -----------

@@ -57,7 +57,7 @@ merge started (and especially if those changes were further modified
 after the merge was started), `git merge --abort` will in some cases be
 unable to reconstruct the original (pre-merge) changes. Therefore:
 
-*Warning*: Running `git merge` with non-trivial uncommitted changes is
+WARNING: Running `git merge` with non-trivial uncommitted changes is
 discouraged: while possible, it may leave you in a state that is hard to
 back out of in the case of a conflict.
 

@@ -67,7 +67,7 @@ OPTIONS
 
 include::merge-options.adoc[]
 
--m <msg>::
+`-m <msg>`::
 	Set the commit message to be used for the merge commit (in
 	case one is created).
 +

@@ -78,13 +78,13 @@ The `git fmt-merge-msg` command can be
 used to give a good default for automated `git merge`
 invocations. The automated message can include the branch description.
 
---into-name <branch>::
+`--into-name <branch>`::
 	Prepare the default merge message as if merging to the branch
-	`<branch>`, instead of the name of the real branch to which
+	_<branch>_, instead of the name of the real branch to which
 	the merge is made.
 
--F <file>::
---file=<file>::
+`-F <file>`::
+`--file=<file>`::
 	Read the commit message to be used for the merge commit (in
 	case one is created).
 +

@@ -93,12 +93,12 @@ will be appended to the specified message.
 
 include::rerere-options.adoc[]
 
---overwrite-ignore::
---no-overwrite-ignore::
+`--overwrite-ignore`::
+`--no-overwrite-ignore`::
 	Silently overwrite ignored files from the merge result. This
 	is the default behavior. Use `--no-overwrite-ignore` to abort.
 
---abort::
+`--abort`::
 	Abort the current conflict resolution process, and
 	try to reconstruct the pre-merge state. If an autostash entry is
 	present, apply it to the worktree.

@@ -114,17 +114,17 @@ which case `git merge --abort` applies the stash entry to the worktree
 whereas `git reset --merge` will save the stashed changes in the stash
 list.
 
---quit::
+`--quit`::
 	Forget about the current merge in progress. Leave the index
 	and the working tree as-is. If `MERGE_AUTOSTASH` is present, the
 	stash entry will be saved to the stash list.
 
---continue::
+`--continue`::
 	After a `git merge` stops due to conflicts you can conclude the
 	merge by running `git merge --continue` (see "HOW TO RESOLVE
 	CONFLICTS" section below).
 
-<commit>...::
+`<commit>...`::
 	Commits, usually other branch heads, to merge into our branch.
 	Specifying more than one commit will create a merge with
 	more than two parents (affectionately called an Octopus merge).

@@ -152,7 +152,7 @@ To avoid recording unrelated changes in the merge commit,
 `git pull` and `git merge` will also abort if there are any changes
 registered in the index relative to the `HEAD` commit.  (Special
 narrow exceptions to this rule may exist depending on which merge
-strategy is in use, but generally, the index must match HEAD.)
+strategy is in use, but generally, the index must match `HEAD`.)
 
 If all named commits are already ancestors of `HEAD`, `git merge`
 will exit early with the message "Already up to date."

@@ -195,11 +195,11 @@ happens:
    stage 2 from `HEAD`, and stage 3 from `MERGE_HEAD` (you
    can inspect the stages with `git ls-files -u`).  The working
    tree files contain the result of the merge operation; i.e. 3-way
-   merge results with familiar conflict markers `<<<` `===` `>>>`.
+   merge results with familiar conflict markers +<<<+ `===` +>>>+.
 5. A ref named `AUTO_MERGE` is written, pointing to a tree
    corresponding to the current content of the working tree (including
    conflict markers for textual conflicts).  Note that this ref is only
-   written when the 'ort' merge strategy is used (the default).
+   written when the `ort` merge strategy is used (the default).
 6. No other changes are made.  In particular, the local
    modifications you had before you started merge will stay the
    same and the index entries for them stay as they were,

@@ -231,7 +231,6 @@ git merge v1.2.3^0
 git merge --ff-only v1.2.3
 ----
 
-
 HOW CONFLICTS ARE PRESENTED
 ---------------------------
 

@@ -260,7 +259,7 @@ And here is another line that is cleanly resolved or unmodified.
 ------------
 
 The area where a pair of conflicting changes happened is marked with markers
-`<<<<<<<`, `=======`, and `>>>>>>>`.  The part before the `=======`
++<<<<<<<+, `=======`, and +>>>>>>>+.  The part before the `=======`
 is typically your side, and the part afterwards is typically their side.
 
 The default format does not show what the original said in the conflicting

@@ -270,7 +269,7 @@ side wants to say it is hard and you'd prefer to go shopping, while the
 other side wants to claim it is easy.
 
 An alternative style can be used by setting the `merge.conflictStyle`
-configuration variable to either "diff3" or "zdiff3".  In "diff3"
+configuration variable to either `diff3` or `zdiff3`.  In `diff3`
 style, the above conflict may look like this:
 
 ------------

@@ -290,7 +289,7 @@ Git makes conflict resolution easy.
 And here is another line that is cleanly resolved or unmodified.
 ------------
 
-while in "zdiff3" style, it may look like this:
+while in `zdiff3` style, it may look like this:
 
 ------------
 Here are lines that are either unchanged from the common

@@ -308,8 +307,8 @@ Git makes conflict resolution easy.
 And here is another line that is cleanly resolved or unmodified.
 ------------
 
-In addition to the `<<<<<<<`, `=======`, and `>>>>>>>` markers, it uses
-another `|||||||` marker that is followed by the original text.  You can
+In addition to the +<<<<<<<+, `=======`, and +>>>>>>>+ markers, it uses
+another +|||||||+ marker that is followed by the original text.  You can
 tell that the original just stated a fact, and your side simply gave in to
 that statement and gave up, while the other side tried to have a more
 positive attitude.  You can sometimes come up with a better resolution by

@@ -390,8 +389,8 @@ include::merge-strategies.adoc[]
 CONFIGURATION
 -------------
 
-branch.<name>.mergeOptions::
-	Sets default options for merging into branch <name>. The syntax and
+`branch.<name>.mergeOptions`::
+	Sets default options for merging into branch _<name>_. The syntax and
 	supported options are the same as those of `git merge`, but option
 	values containing whitespace characters are currently not supported.
 

index 0022185201fc..9b3c7d6df4ef 100644
@@ -1,23 +1,23 @@
---commit::
---no-commit::
+`--commit`::
+`--no-commit`::
 	Perform the merge and commit the result. This option can
-	be used to override --no-commit.
+	be used to override `--no-commit`.
 ifdef::git-pull[]
 	Only useful when merging.
 endif::git-pull[]
 +
-With --no-commit perform the merge and stop just before creating
+With `--no-commit` perform the merge and stop just before creating
 a merge commit, to give the user a chance to inspect and further
 tweak the merge result before committing.
 +
 Note that fast-forward updates do not create a merge commit and
-therefore there is no way to stop those merges with --no-commit.
+therefore there is no way to stop those merges with `--no-commit`.
 Thus, if you want to ensure your branch is not changed or updated
-by the merge command, use --no-ff with --no-commit.
+by the merge command, use `--no-ff` with `--no-commit`.
 
---edit::
--e::
---no-edit::
+`--edit`::
+`-e`::
+`--no-edit`::
 	Invoke an editor before committing successful mechanical merge to
 	further edit the auto-generated merge message, so that the user
 	can explain and justify the merge. The `--no-edit` option can be

@@ -35,17 +35,17 @@ they run `git merge`. To make it easier to adjust such scripts to the
 updated behaviour, the environment variable `GIT_MERGE_AUTOEDIT` can be
 set to `no` at the beginning of them.
 
---cleanup=<mode>::
+`--cleanup=<mode>`::
 	This option determines how the merge message will be cleaned up before
 	committing. See linkgit:git-commit[1] for more details. In addition, if
-	the '<mode>' is given a value of `scissors`, scissors will be appended
+	the _<mode>_ is given a value of `scissors`, scissors will be appended
 	to `MERGE_MSG` before being passed on to the commit machinery in the
 	case of a merge conflict.
 
 ifdef::git-merge[]
---ff::
---no-ff::
---ff-only::
+`--ff`::
+`--no-ff`::
+`--ff-only`::
 	Specifies how a merge is handled when the merged-in history is
 	already a descendant of the current history.  `--ff` is the
 	default unless merging an annotated (and possibly signed) tag

@@ -53,13 +53,13 @@ ifdef::git-merge[]
 	hierarchy, in which case `--no-ff` is assumed.
 endif::git-merge[]
 ifdef::git-pull[]
---ff-only::
+`--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).
 
---ff::
---no-ff::
+`--ff`::
+`--no-ff`::
 	When merging rather than rebasing, specifies how a merge is
 	handled when the merged-in history is already a descendant of
 	the current history.  If merging is requested, `--ff` is the

@@ -81,40 +81,40 @@ With `--ff-only`, resolve the merge as a fast-forward when possible.
 When not possible, refuse to merge and exit with a non-zero status.
 endif::git-merge[]
 
--S[<keyid>]::
---gpg-sign[=<keyid>]::
---no-gpg-sign::
-	GPG-sign the resulting merge commit. The `keyid` argument is
+`-S[<key-id>]`::
+`--gpg-sign[=<key-id>]`::
+`--no-gpg-sign`::
+	GPG-sign the resulting merge commit. The _<key-id>_ argument is
 	optional and defaults to the committer identity; if specified,
 	it must be stuck to the option without a space. `--no-gpg-sign`
 	is useful to countermand both `commit.gpgSign` configuration variable,
 	and earlier `--gpg-sign`.
 
---log[=<n>]::
---no-log::
+`--log[=<n>]`::
+`--no-log`::
 	In addition to branch names, populate the log message with
-	one-line descriptions from at most <n> actual commits that are being
+	one-line descriptions from at most _<n>_ actual commits that are being
 	merged. See also linkgit:git-fmt-merge-msg[1].
 ifdef::git-pull[]
 	Only useful when merging.
 endif::git-pull[]
 +
-With --no-log do not list one-line descriptions from the
+With `--no-log` do not list one-line descriptions from the
 actual commits being merged.
 
 include::signoff-option.adoc[]
 
---stat::
--n::
---no-stat::
+`--stat`::
+`-n`::
+`--no-stat`::
 	Show a diffstat at the end of the merge. The diffstat is also
 	controlled by the configuration option merge.stat.
 +
-With -n or --no-stat do not show a diffstat at the end of the
+With `-n` or `--no-stat` do not show a diffstat at the end of the
 merge.
 
---squash::
---no-squash::
+`--squash`::
+`--no-squash`::
 	Produce the working tree and index state as if a real merge
 	happened (except for the merge information), but do not actually
 	make a commit, move the `HEAD`, or record `$GIT_DIR/MERGE_HEAD`

@@ -123,16 +123,16 @@ merge.
 	the current branch whose effect is the same as merging another
 	branch (or more in case of an octopus).
 +
-With --no-squash perform the merge and commit the result. This
-option can be used to override --squash.
+With `--no-squash` perform the merge and commit the result. This
+option can be used to override `--squash`.
 +
-With --squash, --commit is not allowed, and will fail.
+With `--squash`, `--commit` is not allowed, and will fail.
 ifdef::git-pull[]
 +
 Only useful when merging.
 endif::git-pull[]
 
---[no-]verify::
+`--[no-]verify`::
 	By default, the pre-merge and commit-msg hooks are run.
 	When `--no-verify` is given, these are bypassed.
 	See also linkgit:githooks[5].

@@ -140,21 +140,21 @@ ifdef::git-pull[]
 	Only useful when merging.
 endif::git-pull[]
 
--s <strategy>::
---strategy=<strategy>::
+`-s <strategy>`::
+`--strategy=<strategy>`::
 	Use the given merge strategy; can be supplied more than
 	once to specify them in the order they should be tried.
 	If there is no `-s` option, a built-in list of strategies
 	is used instead (`ort` when merging a single head,
 	`octopus` otherwise).
 
--X <option>::
---strategy-option=<option>::
+`-X <option>`::
+`--strategy-option=<option>`::
 	Pass merge strategy specific option through to the merge
 	strategy.
 
---verify-signatures::
---no-verify-signatures::
+`--verify-signatures`::
+`--no-verify-signatures`::
 	Verify that the tip commit of the side branch being merged is
 	signed with a valid key, i.e. a key that has a valid uid: in the
 	default trust model, this means the signing key has been signed by

@@ -165,22 +165,22 @@ ifdef::git-pull[]
 Only useful when merging.
 endif::git-pull[]
 
---summary::
---no-summary::
-	Synonyms to --stat and --no-stat; these are deprecated and will be
+`--summary`::
+`--no-summary`::
+	Synonyms to `--stat` and `--no-stat`; these are deprecated and will be
 	removed in the future.
 
 ifndef::git-pull[]
--q::
---quiet::
-	Operate quietly. Implies --no-progress.
+`-q`::
+`--quiet`::
+	Operate quietly. Implies `--no-progress`.
 
--v::
---verbose::
+`-v`::
+`--verbose`::
 	Be verbose.
 
---progress::
---no-progress::
+`--progress`::
+`--no-progress`::
 	Turn progress on/off explicitly. If neither is specified,
 	progress is shown if standard error is connected to a terminal.
 	Note that not all merge strategies may support progress

@@ -188,8 +188,8 @@ ifndef::git-pull[]
 
 endif::git-pull[]
 
---autostash::
---no-autostash::
+`--autostash`::
+`--no-autostash`::
 	Automatically create a temporary stash entry before the operation
 	begins, record it in the ref `MERGE_AUTOSTASH`
 	and apply it after the operation ends.  This means

@@ -197,7 +197,7 @@ endif::git-pull[]
 	with care: the final stash application after a successful
 	merge might result in non-trivial conflicts.
 
---allow-unrelated-histories::
+`--allow-unrelated-histories`::
 	By default, `git merge` command refuses to merge histories
 	that do not share a common ancestor.  This option can be
 	used to override this safety when merging histories of two

index c3321ddea248..b0b920144a6c 100644
@@ -1,5 +1,5 @@
---rerere-autoupdate::
---no-rerere-autoupdate::
+`--rerere-autoupdate`::
+`--no-rerere-autoupdate`::
 	After the rerere mechanism reuses a recorded resolution on
 	the current conflict to update the files in the working
 	tree, allow it to also update the index with the result of

index 9b3c7d6df4ef..078f4f6157a1 100644
@@ -203,7 +203,7 @@ endif::git-pull[]
 	used to override this safety when merging histories of two
 	projects that started their lives independently. As that is
 	a very rare occasion, no configuration variable to enable
-	this by default exists and will not be added.
+	this by default exists or will be added.
 ifdef::git-pull[]
 +
 Only useful when merging.

index 9e034f447e76..2ba43f84e709 100644
@@ -6,7 +6,7 @@ backend 'merge strategies' to be chosen with `-s` option.  Some strategies
 can also take their own options, which can be passed by giving `-X<option>`
 arguments to `git merge` and/or `git pull`.
 
-ort::
+`ort`::
 	This is the default merge strategy when pulling or merging one
 	branch.  This strategy can only resolve two heads using a
 	3-way merge algorithm.  When there is more than one common

@@ -29,26 +29,26 @@ descendant. Otherwise, Git will treat this case as a conflict, suggesting
 as a resolution a submodule commit that is descendant of the conflicting
 ones, if one exists.
 +
-The 'ort' strategy can take the following options:
+The `ort` strategy can take the following options:
 
-ours;;
+`ours`;;
 	This option forces conflicting hunks to be auto-resolved cleanly by
 	favoring 'our' version.  Changes from the other tree that do not
 	conflict with our side are reflected in the merge result.
 	For a binary file, the entire contents are taken from our side.
 +
-This should not be confused with the 'ours' merge strategy, which does not
+This should not be confused with the `ours` merge strategy, which does not
 even look at what the other tree contains at all.  It discards everything
 the other tree did, declaring 'our' history contains all that happened in it.
 
-theirs;;
-	This is the opposite of 'ours'; note that, unlike 'ours', there is
-	no 'theirs' merge strategy to confuse this merge option with.
+`theirs`;;
+	This is the opposite of `ours`; note that, unlike `ours`, there is
+	no `theirs` merge strategy to confuse this merge option with.
 
-ignore-space-change;;
-ignore-all-space;;
-ignore-space-at-eol;;
-ignore-cr-at-eol;;
+`ignore-space-change`;;
+`ignore-all-space`;;
+`ignore-space-at-eol`;;
+`ignore-cr-at-eol`;;
 	Treats lines with the indicated type of whitespace change as
 	unchanged for the sake of a three-way merge.  Whitespace
 	changes mixed with other changes to a line are not ignored.

@@ -61,7 +61,7 @@ ignore-cr-at-eol;;
   version includes a substantial change, 'their' version is used;
 * Otherwise, the merge proceeds in the usual way.
 
-renormalize;;
+`renormalize`;;
 	This runs a virtual check-out and check-in of all three stages
 	of any file which needs a three-way merge.  This option is
 	meant to be used when merging branches with different clean

@@ -69,31 +69,31 @@ renormalize;;
 	branches with differing checkin/checkout attributes" in
 	linkgit:gitattributes[5] for details.
 
-no-renormalize;;
+`no-renormalize`;;
 	Disables the `renormalize` option.  This overrides the
 	`merge.renormalize` configuration variable.
 
-find-renames[=<n>];;
+`find-renames[=<n>]`;;
 	Turn on rename detection, optionally setting the similarity
 	threshold.  This is the default. This overrides the
-	'merge.renames' configuration variable.
+	`merge.renames` configuration variable.
 	See also linkgit:git-diff[1] `--find-renames`.
 
-rename-threshold=<n>;;
+`rename-threshold=<n>`;;
 	Deprecated synonym for `find-renames=<n>`.
 
-no-renames;;
+`no-renames`;;
 	Turn off rename detection. This overrides the `merge.renames`
 	configuration variable.
 	See also linkgit:git-diff[1] `--no-renames`.
 
-histogram;;
+`histogram`;;
 	Deprecated synonym for `diff-algorithm=histogram`.
 
-patience;;
+`patience`;;
 	Deprecated synonym for `diff-algorithm=patience`.
 
-diff-algorithm=[histogram|minimal|myers|patience];;
+`diff-algorithm=(histogram|minimal|myers|patience)`;;
 	Use a different diff algorithm while merging, which can help
 	avoid mismerges that occur due to unimportant matching lines
 	(such as braces from distinct functions).  See also

@@ -101,49 +101,49 @@ diff-algorithm=[histogram|minimal|myers|patience];;
 	defaults to `diff-algorithm=histogram`, while regular diffs
 	currently default to the `diff.algorithm` config setting.
 
-subtree[=<path>];;
+`subtree[=<path>]`;;
 	This option is a more advanced form of 'subtree' strategy, where
 	the strategy makes a guess on how two trees must be shifted to
 	match with each other when merging.  Instead, the specified path
 	is prefixed (or stripped from the beginning) to make the shape of
 	two trees to match.
 
-recursive::
+`recursive`::
 	This is now a synonym for `ort`.  It was an alternative
 	implementation until v2.49.0, but was redirected to mean `ort`
 	in v2.50.0.  The previous recursive strategy was the default
 	strategy for resolving two heads from Git v0.99.9k until
 	v2.33.0.
 
-resolve::
+`resolve`::
 	This can only resolve two heads (i.e. the current branch
 	and another branch you pulled from) using a 3-way merge
 	algorithm.  It tries to carefully detect criss-cross
 	merge ambiguities.  It does not handle renames.
 
-octopus::
+`octopus`::
 	This resolves cases with more than two heads, but refuses to do
 	a complex merge that needs manual resolution.  It is
 	primarily meant to be used for bundling topic branch
 	heads together.  This is the default merge strategy when
 	pulling or merging more than one branch.
 
-ours::
+`ours`::
 	This resolves any number of heads, but the resulting tree of the
 	merge is always that of the current branch head, effectively
 	ignoring all changes from all other branches.  It is meant to
 	be used to supersede old development history of side
-	branches.  Note that this is different from the -Xours option to
-	the 'ort' merge strategy.
+	branches.  Note that this is different from the `-Xours` option to
+	the `ort` merge strategy.
 
-subtree::
+`subtree`::
 	This is a modified `ort` strategy. When merging trees A and
 	B, if B corresponds to a subtree of A, B is first adjusted to
 	match the tree structure of A, instead of reading the trees at
 	the same level. This adjustment is also done to the common
 	ancestor tree.
 
-With the strategies that use 3-way merge (including the default, 'ort'),
+With the strategies that use 3-way merge (including the default, `ort`),
 if a change is made on both branches, but later reverted on one of the
 branches, that change will be present in the merged result; some people find
 this behavior confusing.  It occurs because only the heads and the merge base

index 3fbf40e24f62..696ba0531ae1 100644
@@ -1,19 +1,19 @@
-merge.branchdesc::
+`merge.branchdesc`::
 	In addition to branch names, populate the log message with
 	the branch description text associated with them.  Defaults
 	to false.
 
-merge.log::
+`merge.log`::
 	In addition to branch names, populate the log message with at
 	most the specified number of one-line descriptions from the
 	actual commits that are being merged.  Defaults to false, and
 	true is a synonym for 20.
 
-merge.suppressDest::
+`merge.suppressDest`::
 	By adding a glob that matches the names of integration
 	branches to this multi-valued configuration variable, the
 	default merge message computed for merges into these
-	integration branches will omit "into <branch name>" from
+	integration branches will omit "into _<branch-name>_" from
 	its title.
 +
 An element with an empty value can be used to clear the list

162 lines not on this page · raw message

index 046c3258f050..77d0b5055057 100644
@@ -7,95 +7,95 @@ git-mergetool - Run merge conflict resolution tools to resolve merge conflicts
 
 SYNOPSIS
 --------
-[verse]
-'git mergetool' [--tool=<tool>] [-y | --[no-]prompt] [<file>...]
+[synopsis]
+git mergetool [--tool=<tool>] [-y | --[no-]prompt] [<file>...]
 
 DESCRIPTION
 -----------
 
 Use `git mergetool` to run one of several merge utilities to resolve
-merge conflicts.  It is typically run after 'git merge'.
+merge conflicts.  It is typically run after `git merge`.
 
 If one or more <file> parameters are given, the merge tool program will
 be run to resolve differences in each file (skipping those without
 conflicts).  Specifying a directory will include all unresolved files in
-that path.  If no <file> names are specified, 'git mergetool' will run
+that path.  If no _<file>_ names are specified, `git mergetool` will run
 the merge tool program on every file with merge conflicts.
 
 OPTIONS
 -------
--t <tool>::
---tool=<tool>::
-	Use the merge resolution program specified by <tool>.
-	Valid values include emerge, gvimdiff, kdiff3,
-	meld, vimdiff, and tortoisemerge. Run `git mergetool --tool-help`
-	for the list of valid <tool> settings.
+`-t <tool>`::
+`--tool=<tool>`::
+	Use the merge resolution program specified by _<tool>_.
+	Valid values include `emerge`, `gvimdiff`, `kdiff3`,
+	`meld`, `vimdiff`, and `tortoisemerge`. Run `git mergetool --tool-help`
+	for the list of valid _<tool>_ settings.
 +
-If a merge resolution program is not specified, 'git mergetool'
+If a merge resolution program is not specified, `git mergetool`
 will use the configuration variable `merge.tool`.  If the
-configuration variable `merge.tool` is not set, 'git mergetool'
+configuration variable `merge.tool` is not set, `git mergetool`
 will pick a suitable default.
 +
 You can explicitly provide a full path to the tool by setting the
 configuration variable `mergetool.<tool>.path`. For example, you
 can configure the absolute path to kdiff3 by setting
-`mergetool.kdiff3.path`. Otherwise, 'git mergetool' assumes the
-tool is available in PATH.
+`mergetool.kdiff3.path`. Otherwise, `git mergetool` assumes the
+tool is available in `$PATH`.
 +
 Instead of running one of the known merge tool programs,
-'git mergetool' can be customized to run an alternative program
+`git mergetool` can be customized to run an alternative program
 by specifying the command line to invoke in a configuration
 variable `mergetool.<tool>.cmd`.
 +
-When 'git mergetool' is invoked with this tool (either through the
+When `git mergetool` is invoked with this tool (either through the
 `-t` or `--tool` option or the `merge.tool` configuration
-variable), the configured command line will be invoked with `$BASE`
+variable), the configured command line will be invoked with `BASE`
 set to the name of a temporary file containing the common base for
-the merge, if available; `$LOCAL` set to the name of a temporary
+the merge, if available; `LOCAL` set to the name of a temporary
 file containing the contents of the file on the current branch;
-`$REMOTE` set to the name of a temporary file containing the
-contents of the file to be merged, and `$MERGED` set to the name
+`REMOTE` set to the name of a temporary file containing the
+contents of the file to be merged, and `MERGED` set to the name
 of the file to which the merge tool should write the result of the
 merge resolution.
 +
 If the custom merge tool correctly indicates the success of a
 merge resolution with its exit code, then the configuration
 variable `mergetool.<tool>.trustExitCode` can be set to `true`.
-Otherwise, 'git mergetool' will prompt the user to indicate the
+Otherwise, `git mergetool` will prompt the user to indicate the
 success of the resolution after the custom tool has exited.
 
---tool-help::
+`--tool-help`::
 	Print a list of merge tools that may be used with `--tool`.
 
--y::
---no-prompt::
+`-y`::
+`--no-prompt`::
 	Don't prompt before each invocation of the merge resolution
 	program.
 	This is the default if the merge resolution program is
 	explicitly specified with the `--tool` option or with the
 	`merge.tool` configuration variable.
 
---prompt::
+`--prompt`::
 	Prompt before each invocation of the merge resolution program
 	to give the user a chance to skip the path.
 
--g::
---gui::
-	When 'git-mergetool' is invoked with the `-g` or `--gui` option,
+`-g`::
+`--gui`::
+	When `git-mergetool` is invoked with the `-g` or `--gui` option,
 	the default merge tool will be read from the configured
 	`merge.guitool` variable instead of `merge.tool`. If
 	`merge.guitool` is not set, we will fallback to the tool
 	configured under `merge.tool`. This may be autoselected using
 	the configuration variable `mergetool.guiDefault`.
 
---no-gui::
+`--no-gui`::
 	This overrides a previous `-g` or `--gui` setting or
 	`mergetool.guiDefault` configuration and reads the default merge
 	tool from the configured `merge.tool` variable.
 
--O<orderfile>::
+`-O<orderfile>`::
 	Process files in the order specified in the
-	<orderfile>, which has one shell glob pattern per line.
+	_<orderfile>_, which has one shell glob pattern per line.
 	This overrides the `diff.orderFile` configuration variable
 	(see linkgit:git-config[1]).  To cancel `diff.orderFile`,
 	use `-O/dev/null`.

index 00bf665aa09b..6be506145c15 100644
@@ -1,24 +1,24 @@
-mergetool.<tool>.path::
+`mergetool.<tool>.path`::
 	Override the path for the given tool.  This is useful in case
-	your tool is not in the PATH.
+	your tool is not in the `$PATH`.
 
-mergetool.<tool>.cmd::
+`mergetool.<tool>.cmd`::
 	Specify the command to invoke the specified merge tool.  The
 	specified command is evaluated in shell with the following
-	variables available: 'BASE' is the name of a temporary file
+	variables available: `BASE` is the name of a temporary file
 	containing the common base of the files to be merged, if available;
-	'LOCAL' is the name of a temporary file containing the contents of
-	the file on the current branch; 'REMOTE' is the name of a temporary
+	`LOCAL` is the name of a temporary file containing the contents of
+	the file on the current branch; `REMOTE` is the name of a temporary
 	file containing the contents of the file from the branch being
-	merged; 'MERGED' contains the name of the file to which the merge
+	merged; `MERGED` contains the name of the file to which the merge
 	tool should write the results of a successful merge.
 
-mergetool.<tool>.hideResolved::
+`mergetool.<tool>.hideResolved`::
 	Allows the user to override the global `mergetool.hideResolved` value
 	for a specific tool. See `mergetool.hideResolved` for the full
 	description.
 
-mergetool.<tool>.trustExitCode::
+`mergetool.<tool>.trustExitCode`::
 	For a custom merge command, specify whether the exit code of
 	the merge command can be used to determine whether the merge was
 	successful.  If this is not set to true then the merge target file

@@ -26,7 +26,7 @@ mergetool.<tool>.trustExitCode::
 	if the file has been updated; otherwise, the user is prompted to
 	indicate the success of the merge.
 
-mergetool.meld.hasOutput::
+`mergetool.meld.hasOutput`::
 	Older versions of `meld` do not support the `--output` option.
 	Git will attempt to detect whether `meld` supports `--output`
 	by inspecting the output of `meld --help`.  Configuring

@@ -35,7 +35,7 @@ mergetool.meld.hasOutput::
 	to `true` tells Git to unconditionally use the `--output` option,
 	and `false` avoids using `--output`.
 
-mergetool.meld.useAutoMerge::
+`mergetool.meld.useAutoMerge`::
 	When the `--auto-merge` is given, meld will merge all non-conflicting
 	parts automatically, highlight the conflicting parts, and wait for
 	user decision.  Setting `mergetool.meld.useAutoMerge` to `true` tells

@@ -45,15 +45,15 @@ mergetool.meld.useAutoMerge::
 	value of `false` avoids using `--auto-merge` altogether, and is the
 	default value.
 
-mergetool.<vimdiff variant>.layout::
-	Configure the split window layout for vimdiff's `<variant>`, which is any of `vimdiff`,
+`mergetool.<variant>.layout`::
+	Configure the split window layout for vimdiff's _<variant>_, which is any of `vimdiff`,
 	`nvimdiff`, `gvimdiff`.
 	Upon launching `git mergetool` with `--tool=<variant>` (or without `--tool`
-	if `merge.tool` is configured as `<variant>`), Git will consult
+	if `merge.tool` is configured as _<variant>_), Git will consult
 	`mergetool.<variant>.layout` to determine the tool's layout. If the
-	variant-specific configuration is not available, `vimdiff`'s is used as
+	variant-specific configuration is not available, `vimdiff` ' s is used as
 	fallback.  If that too is not available, a default layout with 4 windows
-	will be used.  To configure the layout, see the `BACKEND SPECIFIC HINTS`
+	will be used.  To configure the layout, see the 'BACKEND SPECIFIC HINTS'
 ifdef::git-mergetool[]
 	section.
 endif::[]

@@ -61,39 +61,39 @@ ifndef::git-mergetool[]
 	section in linkgit:git-mergetool[1].
 endif::[]
 
-mergetool.hideResolved::
+`mergetool.hideResolved`::
 	During a merge, Git will automatically resolve as many conflicts as
-	possible and write the 'MERGED' file containing conflict markers around
-	any conflicts that it cannot resolve; 'LOCAL' and 'REMOTE' normally
-	represent the versions of the file from before Git's conflict
-	resolution. This flag causes 'LOCAL' and 'REMOTE' to be overwritten so
+	possible and write the `$MERGED` file containing conflict markers around
+	any conflicts that it cannot resolve; `$LOCAL` and `$REMOTE` normally
+	are the versions of the file from before Git`s conflict
+	resolution. This flag causes `$LOCAL` and `$REMOTE` to be overwritten so
 	that only the unresolved conflicts are presented to the merge tool. Can
 	be configured per-tool via the `mergetool.<tool>.hideResolved`
 	configuration variable. Defaults to `false`.
 
-mergetool.keepBackup::
+`mergetool.keepBackup`::
 	After performing a merge, the original file with conflict markers
 	can be saved as a file with a `.orig` extension.  If this variable
 	is set to `false` then this file is not preserved.  Defaults to
 	`true` (i.e. keep the backup files).
 
-mergetool.keepTemporaries::
+`mergetool.keepTemporaries`::
 	When invoking a custom merge tool, Git uses a set of temporary
 	files to pass to the tool. If the tool returns an error and this
 	variable is set to `true`, then these temporary files will be
 	preserved; otherwise, they will be removed after the tool has
 	exited. Defaults to `false`.
 
-mergetool.writeToTemp::
-	Git writes temporary 'BASE', 'LOCAL', and 'REMOTE' versions of
+`mergetool.writeToTemp`::
+	Git writes temporary `BASE`, `LOCAL`, and `REMOTE` versions of
 	conflicting files in the worktree by default.  Git will attempt
 	to use a temporary directory for these files when set `true`.
 	Defaults to `false`.
 
-mergetool.prompt::
+`mergetool.prompt`::
 	Prompt before each invocation of the merge resolution program.
 
-mergetool.guiDefault::
+`mergetool.guiDefault`::
 	Set `true` to use the `merge.guitool` by default (equivalent to
 	specifying the `--gui` argument), or `auto` to select `merge.guitool`
 	or `merge.tool` depending on the presence of a `DISPLAY` environment

index ab915df408e8..abfd426f74a0 100644
@@ -183,13 +183,13 @@ latter will be used as fallback if the variant-specific one is not set).
 In addition, for backwards compatibility with previous Git versions, you can
 also append `1`, `2` or `3` to either `vimdiff` or any of the variants (ex:
 `vimdiff3`, `nvimdiff1`, etc...) to use a predefined layout.
-In other words, using `--tool=[g,n,]vimdiffx` is the same as using
-`--tool=[g,n,]vimdiff` and setting configuration variable
-`mergetool.[g,n,]vimdiff.layout` to...
+In other words, using `--tool=[g|n]vimdiff<x>` is the same as using
+`--tool=[g|n]vimdiff` and setting configuration variable
+`mergetool.[g|n]vimdiff.layout` to...
 
-  * `x=1`: `"@LOCAL, REMOTE"`
-  * `x=2`: `"LOCAL, MERGED, REMOTE"`
-  * `x=3`: `"MERGED"`
+  * `<x>=1`: `"@LOCAL, REMOTE"`
+  * `<x>=2`: `"LOCAL, MERGED, REMOTE"`
+  * `<x>=3`: `"MERGED"`
 
-Example: using `--tool=gvimdiff2` will open `gvim` with three columns (LOCAL,
-MERGED and REMOTE).
+Example: using `--tool=gvimdiff2` will open `gvim` with three columns (`LOCAL`,
+`MERGED` and `REMOTE`).

index f55315c51ea0..9f62abf9e2b8 100644
@@ -7,11 +7,11 @@ git-switch - Switch branches
 
 SYNOPSIS
 --------
-[verse]
-'git switch' [<options>] [--no-guess] <branch>
-'git switch' [<options>] --detach [<start-point>]
-'git switch' [<options>] (-c|-C) <new-branch> [<start-point>]
-'git switch' [<options>] --orphan <new-branch>
+[synopsis]
+git switch [<options>] [--no-guess] <branch>
+git switch [<options>] --detach [<start-point>]
+git switch [<options>] (-c|-C) <new-branch> [<start-point>]
+git switch [<options>] --orphan <new-branch>
 
 DESCRIPTION
 -----------

@@ -33,33 +33,33 @@ THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE.
 
 OPTIONS
 -------
-<branch>::
+_<branch>_::
 	Branch to switch to.
 
-<new-branch>::
+_<new-branch>_::
 	Name for the new branch.
 
-<start-point>::
+_<start-point>_::
 	The starting point for the new branch. Specifying a
-	`<start-point>` allows you to create a branch based on some
-	other point in history than where HEAD currently points. (Or,
+	_<start-point>_ allows you to create a branch based on some
+	other point in history than where `HEAD` currently points. (Or,
 	in the case of `--detach`, allows you to inspect and detach
 	from some other point.)
 +
-You can use the `@{-N}` syntax to refer to the N-th last
-branch/commit switched to using "git switch" or "git checkout"
+You can use the `@{-<N>}` syntax to refer to the _<N>_-th last
+branch/commit switched to using `git switch` or `git checkout`
 operation. You may also specify `-` which is synonymous to `@{-1}`.
 This is often used to switch quickly between two branches, or to undo
 a branch switch by mistake.
 +
-As a special case, you may use `A...B` as a shortcut for the merge
-base of `A` and `B` if there is exactly one merge base. You can leave
-out at most one of `A` and `B`, in which case it defaults to `HEAD`.
-
--c <new-branch>::
---create <new-branch>::
-	Create a new branch named `<new-branch>` starting at
-	`<start-point>` before switching to the branch. This is the
+As a special case, you may use `<rev-a>...<rev-b>` as a shortcut for the merge
+base of _<rev-a>_ and _<rev-b>_ if there is exactly one merge base. You can leave
+out at most one of _<rev-a>_ and _<rev-b>_, in which case it defaults to `HEAD`.
+
+`-c <new-branch>`::
+`--create <new-branch>`::
+	Create a new branch named _<new-branch>_ starting at
+	_<start-point>_ before switching to the branch. This is the
 	transactional equivalent of
 +
 ------------

@@ -67,32 +67,32 @@ $ git branch <new-branch>
 $ git switch <new-branch>
 ------------
 +
-that is to say, the branch is not reset/created unless "git switch" is
+that is to say, the branch is not reset/created unless `git switch` is
 successful (e.g., when the branch is in use in another worktree, not
 just the current branch stays the same, but the branch is not reset to
 the start-point, either).
 
--C <new-branch>::
---force-create <new-branch>::
-	Similar to `--create` except that if `<new-branch>` already
-	exists, it will be reset to `<start-point>`. This is a
+`-C <new-branch>`::
+`--force-create <new-branch>`::
+	Similar to `--create` except that if _<new-branch>_ already
+	exists, it will be reset to _<start-point>_. This is a
 	convenient shortcut for:
 +
 ------------
-$ git branch -f <new-branch>
-$ git switch <new-branch>
+$ git branch -f _<new-branch>_
+$ git switch _<new-branch>_
 ------------
 
--d::
---detach::
+`-d`::
+`--detach`::
 	Switch to a commit for inspection and discardable
 	experiments. See the "DETACHED HEAD" section in
 	linkgit:git-checkout[1] for details.
 
---guess::
---no-guess::
-	If `<branch>` is not found but there does exist a tracking
-	branch in exactly one remote (call it `<remote>`) with a
+`--guess`::
+`--no-guess`::
+	If _<branch>_ is not found but there does exist a tracking
+	branch in exactly one remote (call it _<remote>_) with a
 	matching name, treat as equivalent to
 +
 ------------

@@ -101,9 +101,9 @@ $ git switch -c <branch> --track <remote>/<branch>
 +
 If the branch exists in multiple remotes and one of them is named by
 the `checkout.defaultRemote` configuration variable, we'll use that
-one for the purposes of disambiguation, even if the `<branch>` isn't
+one for the purposes of disambiguation, even if the _<branch>_ isn't
 unique across all remotes. Set it to e.g. `checkout.defaultRemote=origin`
-to always checkout remote branches from there if `<branch>` is
+to always checkout remote branches from there if _<branch>_ is
 ambiguous but exists on the 'origin' remote. See also
 `checkout.defaultRemote` in linkgit:git-config[1].
 +

@@ -112,19 +112,19 @@ ambiguous but exists on the 'origin' remote. See also
 The default behavior can be set via the `checkout.guess` configuration
 variable.
 
--f::
---force::
+`-f`::
+`--force`::
 	An alias for `--discard-changes`.
 
---discard-changes::
+`--discard-changes`::
 	Proceed even if the index or the working tree differs from
 	`HEAD`. Both the index and working tree are restored to match
 	the switching target. If `--recurse-submodules` is specified,
 	submodule content is also restored to match the switching
 	target. This is used to throw away local changes.
 
--m::
---merge::
+`-m`::
+`--merge`::
 	If you have local modifications to one or more files that are
 	different between the current branch and the branch to which
 	you are switching, the command refuses to switch branches in

@@ -138,25 +138,25 @@ paths are left unmerged, and you need to resolve the conflicts
 and mark the resolved paths with `git add` (or `git rm` if the merge
 should result in deletion of the path).
 
---conflict=<style>::
+`--conflict=<style>`::
 	The same as `--merge` option above, but changes the way the
 	conflicting hunks are presented, overriding the
 	`merge.conflictStyle` configuration variable.  Possible values are
-	"merge" (default), "diff3", and "zdiff3".
+	`merge` (default), `diff3`, and `zdiff3`.
 
--q::
---quiet::
+`-q`::
+`--quiet`::
 	Quiet, suppress feedback messages.
 
---progress::
---no-progress::
+`--progress`::
+`--no-progress`::
 	Progress status is reported on the standard error stream
 	by default when it is attached to a terminal, unless `--quiet`
 	is specified. This flag enables progress reporting even if not
 	attached to a terminal, regardless of `--quiet`.
 
--t::
---track [direct|inherit]::
+`-t`::
+`--track[ (direct|inherit)]`::
 	When creating a new branch, set up "upstream" configuration.
 	`-c` is implied. See `--track` in linkgit:git-branch[1] for
 	details.

@@ -171,22 +171,22 @@ given name has no slash, or the above guessing results in an empty
 name, the guessing is aborted.  You can explicitly give a name with
 `-c` in such a case.
 
---no-track::
+`--no-track`::
 	Do not set up "upstream" configuration, even if the
 	`branch.autoSetupMerge` configuration variable is true.
 
---orphan <new-branch>::
-	Create a new unborn branch, named `<new-branch>`. All
+`--orphan <new-branch>`::
+	Create a new unborn branch, named _<new-branch>_. All
 	tracked files are removed.
 
---ignore-other-worktrees::
+`--ignore-other-worktrees`::
 	`git switch` refuses when the wanted ref is already
 	checked out by another worktree. This option makes it check
 	the ref out anyway. In other words, the ref can be held by
 	more than one worktree.
 
---recurse-submodules::
---no-recurse-submodules::
+`--recurse-submodules`::
+`--no-recurse-submodules`::
 	Using `--recurse-submodules` will update the content of all
 	active submodules according to the commit recorded in the
 	superproject. If nothing (or `--no-recurse-submodules`) is

@@ -239,7 +239,7 @@ $ git switch -
 ------------
 
 You can grow a new branch from any commit. For example, switch to
-"HEAD~3" and create branch "fixup":
+"`HEAD~3`" and create branch "`fixup`":
 
 ------------
 $ git switch -c fixup HEAD~3

@@ -251,8 +251,8 @@ name:
 
 ------------
 $ git switch new-topic
-Branch 'new-topic' set up to track remote branch 'new-topic' from 'origin'
-Switched to a new branch 'new-topic'
+Branch `new-topic` set up to track remote branch `new-topic` from `origin`
+Switched to a new branch `new-topic`
 ------------
 
 To check out commit `HEAD~3` for temporary inspection or experiment