{"thread":{"id":"63522","subject":"[PATCH 0/9] doc: convert checkout, switch and merge to new format","startedAt":"2025-05-25T20:27:12Z","lastAt":"2025-05-25T20:27:20Z","messageCount":10,"participants":["Jean-Noël Avila via GitGitGadget"],"isPatch":true,"patchVersion":1,"patchTotal":9},"messages":[{"id":"518882","messageId":"pull.1927.git.1748204829.gitgitgadget@gmail.com","threadId":"63522","inReplyTo":null,"subject":"[PATCH 0/9] doc: convert checkout, switch and merge to new format","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-05-25T20:27:00Z","receivedAt":"2025-05-25T20:27:12Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"This is the follow-up in the conversion of the manpages to the synopsis\nstyle.\n\nThis time, we address git checkout, git switch, git merge and git mergetool.\n\nI added a small grammatical fixup in merge options.\n\nJean-Noël Avila (9):\n  doc: convert git-checkout manpage to new style\n  doc: convert git-merge manpage to new style\n  doc: convert merge options to new synopsis format\n  doc: merge-options.adoc remove a misleading double negation\n  doc: convert merge strategies to synopsis format\n  doc: switch merge config description to new synopsis format\n  doc: convert git-mergetool manpage to new synopsis style\n  doc: convert git-mergetool options to new synopsis style\n  doc: convert git-switch manpage to new synopsis style\n\n Documentation/config/checkout.adoc      |  14 +-\n Documentation/config/fmt-merge-msg.adoc |   8 +-\n Documentation/config/merge.adoc         |  84 ++++-----\n Documentation/config/mergetool.adoc     |  54 +++---\n Documentation/git-checkout.adoc         | 228 ++++++++++++------------\n Documentation/git-merge.adoc            |  51 +++---\n Documentation/git-mergetool.adoc        |  62 +++----\n Documentation/git-switch.adoc           | 114 ++++++------\n Documentation/merge-options.adoc        | 110 ++++++------\n Documentation/merge-strategies.adoc     |  58 +++---\n Documentation/mergetools/vimdiff.adoc   |  16 +-\n Documentation/rerere-options.adoc       |   4 +-\n 12 files changed, 403 insertions(+), 400 deletions(-)\n\n\nbase-commit: 845c48a16a7f7b2c44d8cb137b16a4a1f0140229\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-1927%2Fjnavila%2Fcheckout_merge-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1927/jnavila/checkout_merge-v1\nPull-Request: https://github.com/gitgitgadget/git/pull/1927\n-- \ngitgitgadget\n"},{"id":"518883","messageId":"23eef28b5a4b33219e92e1462688df1bb11e522f.1748204829.git.gitgitgadget@gmail.com","threadId":"63522","inReplyTo":"pull.1927.git.1748204829.gitgitgadget@gmail.com","subject":"[PATCH 1/9] doc: convert git-checkout manpage to new style","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-05-25T20:27:01Z","receivedAt":"2025-05-25T20:27:13Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n\n- Switch the synopsis to a synopsis block which will automatically\n  format placeholders in italics and keywords in monospace\n- Use _<placeholder>_ instead of <placeholder> in the description\n- Use `backticks` for keywords and more complex option\ndescriptions. The new rendering engine will apply synopsis rules to\nthese spans.\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\n---\n Documentation/config/checkout.adoc |  14 +-\n Documentation/git-checkout.adoc    | 228 ++++++++++++++---------------\n 2 files changed, 121 insertions(+), 121 deletions(-)\n\ndiff --git a/Documentation/config/checkout.adoc b/Documentation/config/checkout.adoc\nindex a32302299380..e35d21296978 100644\n--- a/Documentation/config/checkout.adoc\n+++ b/Documentation/config/checkout.adoc\n@@ -1,9 +1,9 @@\n-checkout.defaultRemote::\n+`checkout.defaultRemote`::\n \tWhen you run `git checkout <something>`\n \tor `git switch <something>` and only have one\n \tremote, it may implicitly fall back on checking out and\n \ttracking e.g. `origin/<something>`. This stops working as soon\n-\tas you have more than one remote with a `<something>`\n+\tas you have more than one remote with a _<something>_\n \treference. This setting allows for setting the name of a\n \tpreferred remote that should always win when it comes to\n \tdisambiguation. The typical use-case is to set this to\n@@ -12,17 +12,17 @@ checkout.defaultRemote::\n Currently this is used by linkgit:git-switch[1] and\n linkgit:git-checkout[1] when `git checkout <something>`\n or `git switch <something>`\n-will checkout the `<something>` branch on another remote,\n+will checkout the _<something>_ branch on another remote,\n and by linkgit:git-worktree[1] when `git worktree add` refers to a\n remote branch. This setting might be used for other checkout-like\n commands or functionality in the future.\n \n-checkout.guess::\n+`checkout.guess`::\n \tProvides the default value for the `--guess` or `--no-guess`\n \toption in `git checkout` and `git switch`. See\n \tlinkgit:git-switch[1] and linkgit:git-checkout[1].\n \n-checkout.workers::\n+`checkout.workers`::\n \tThe number of parallel workers to use when updating the working tree.\n \tThe default is one, i.e. sequential execution. If set to a value less\n \tthan one, Git will use as many workers as the number of logical cores\n@@ -30,13 +30,13 @@ checkout.workers::\n \tall commands that perform checkout. E.g. checkout, clone, reset,\n \tsparse-checkout, etc.\n +\n-Note: Parallel checkout usually delivers better performance for repositories\n+NOTE: Parallel checkout usually delivers better performance for repositories\n located on SSDs or over NFS. For repositories on spinning disks and/or machines\n with a small number of cores, the default sequential checkout often performs\n better. The size and compression level of a repository might also influence how\n well the parallel version performs.\n \n-checkout.thresholdForParallelism::\n+`checkout.thresholdForParallelism`::\n \tWhen running parallel checkout with a small number of files, the cost\n \tof subprocess spawning and inter-process communication might outweigh\n \tthe parallelization gains. This setting allows you to define the minimum\ndiff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc\nindex a66c53a5cd1e..ee83b6d9ba9a 100644\n--- a/Documentation/git-checkout.adoc\n+++ b/Documentation/git-checkout.adoc\n@@ -7,54 +7,54 @@ git-checkout - Switch branches or restore working tree files\n \n SYNOPSIS\n --------\n-[verse]\n-'git checkout' [-q] [-f] [-m] [<branch>]\n-'git checkout' [-q] [-f] [-m] --detach [<branch>]\n-'git checkout' [-q] [-f] [-m] [--detach] <commit>\n-'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new-branch>] [<start-point>]\n-'git checkout' [-f] <tree-ish> [--] <pathspec>...\n-'git checkout' [-f] <tree-ish> --pathspec-from-file=<file> [--pathspec-file-nul]\n-'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [--] <pathspec>...\n-'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] --pathspec-from-file=<file> [--pathspec-file-nul]\n-'git checkout' (-p|--patch) [<tree-ish>] [--] [<pathspec>...]\n+[synopsis]\n+git checkout [-q] [-f] [-m] [<branch>]\n+git checkout [-q] [-f] [-m] --detach [<branch>]\n+git checkout [-q] [-f] [-m] [--detach] <commit>\n+git checkout [-q] [-f] [-m] [[-b|-B|--orphan] <new-branch>] [<start-point>]\n+git checkout [-f] <tree-ish> [--] <pathspec>...\n+git checkout [-f] <tree-ish> --pathspec-from-file=<file> [--pathspec-file-nul]\n+git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [--] <pathspec>...\n+git checkout [-f|--ours|--theirs|-m|--conflict=<style>] --pathspec-from-file=<file> [--pathspec-file-nul]\n+git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]\n \n DESCRIPTION\n -----------\n Updates files in the working tree to match the version in the index\n-or the specified tree.  If no pathspec was given, 'git checkout' will\n+or the specified tree.  If no pathspec was given, `git checkout` will\n also update `HEAD` to set the specified branch as the current\n branch.\n \n-'git checkout' [<branch>]::\n-\tTo prepare for working on `<branch>`, switch to it by updating\n+`git checkout [<branch>]`::\n+\tTo prepare for working on _<branch>_, switch to it by updating\n \tthe index and the files in the working tree, and by pointing\n \t`HEAD` at the branch. Local modifications to the files in the\n \tworking tree are kept, so that they can be committed to the\n-\t`<branch>`.\n+\t_<branch>_.\n +\n-If `<branch>` is not found but there does exist a tracking branch in\n-exactly one remote (call it `<remote>`) with a matching name and\n+If _<branch>_ is not found but there does exist a tracking branch in\n+exactly one remote (call it _<remote>_) with a matching name and\n `--no-guess` is not specified, treat as equivalent to\n +\n ------------\n $ git checkout -b <branch> --track <remote>/<branch>\n ------------\n +\n-You could omit `<branch>`, in which case the command degenerates to\n+You could omit _<branch>_, in which case the command degenerates to\n \"check out the current branch\", which is a glorified no-op with\n rather expensive side-effects to show only the tracking information,\n if it exists, for the current branch.\n \n-'git checkout' -b|-B <new-branch> [<start-point>]::\n+`git checkout (-b|-B) <new-branch> [<start-point>]`::\n \n \tSpecifying `-b` causes a new branch to be created as if\n \tlinkgit:git-branch[1] were called and then checked out.  In\n \tthis case you can use the `--track` or `--no-track` options,\n-\twhich will be passed to 'git branch'.  As a convenience,\n+\twhich will be passed to `git branch`.  As a convenience,\n \t`--track` without `-b` implies branch creation; see the\n \tdescription of `--track` below.\n +\n-If `-B` is given, `<new-branch>` is created if it doesn't exist; otherwise, it\n+If `-B` is given, _<new-branch>_ is created if it doesn't exist; otherwise, it\n is reset. This is the transactional equivalent of\n +\n ------------\n@@ -67,30 +67,30 @@ successful (e.g., when the branch is in use in another worktree, not\n just the current branch stays the same, but the branch is not reset to\n the start-point, either).\n \n-'git checkout' --detach [<branch>]::\n-'git checkout' [--detach] <commit>::\n+`git checkout --detach [<branch>]`::\n+`git checkout [--detach] <commit>`::\n \n-\tPrepare to work on top of `<commit>`, by detaching `HEAD` at it\n+\tPrepare to work on top of _<commit>_, by detaching `HEAD` at it\n \t(see \"DETACHED HEAD\" section), and updating the index and the\n \tfiles in the working tree.  Local modifications to the files\n \tin the working tree are kept, so that the resulting working\n \ttree will be the state recorded in the commit plus the local\n \tmodifications.\n +\n-When the `<commit>` argument is a branch name, the `--detach` option can\n+When the _<commit>_ argument is a branch name, the `--detach` option can\n be used to detach `HEAD` at the tip of the branch (`git checkout\n <branch>` would check out that branch without detaching `HEAD`).\n +\n-Omitting `<branch>` detaches `HEAD` at the tip of the current branch.\n+Omitting _<branch>_ detaches `HEAD` at the tip of the current branch.\n \n-'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <pathspec>...::\n-'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] --pathspec-from-file=<file> [--pathspec-file-nul]::\n+`git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <pathspec>...`::\n+`git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] --pathspec-from-file=<file> [--pathspec-file-nul]`::\n \n \tOverwrite the contents of the files that match the pathspec.\n-\tWhen the `<tree-ish>` (most often a commit) is not given,\n+\tWhen the _<tree-ish>_ (most often a commit) is not given,\n \toverwrite working tree with the contents in the index.\n-\tWhen the `<tree-ish>` is given, overwrite both the index and\n-\tthe working tree with the contents at the `<tree-ish>`.\n+\tWhen the _<tree-ish>_ is given, overwrite both the index and\n+\tthe working tree with the contents at the _<tree-ish>_.\n +\n The index may contain unmerged entries because of a previous failed merge.\n By default, if you try to check out such an entry from the index, the\n@@ -100,7 +100,7 @@ specific side of the merge can be checked out of the index by\n using `--ours` or `--theirs`.  With `-m`, changes made to the working tree\n file can be discarded to re-create the original conflicted merge result.\n \n-'git checkout' (-p|--patch) [<tree-ish>] [--] [<pathspec>...]::\n+`git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]`::\n \tThis is similar to the previous mode, but lets you use the\n \tinteractive interface to show the \"diff\" output and choose which\n \thunks to use in the result.  See below for the description of\n@@ -108,19 +108,19 @@ file can be discarded to re-create the original conflicted merge result.\n \n OPTIONS\n -------\n--q::\n---quiet::\n+`-q`::\n+`--quiet`::\n \tQuiet, suppress feedback messages.\n \n---progress::\n---no-progress::\n+`--progress`::\n+`--no-progress`::\n \tProgress status is reported on the standard error stream\n \tby default when it is attached to a terminal, unless `--quiet`\n \tis specified. This flag enables progress reporting even if not\n \tattached to a terminal, regardless of `--quiet`.\n \n--f::\n---force::\n+`-f`::\n+`--force`::\n \tWhen switching branches, proceed even if the index or the\n \tworking tree differs from `HEAD`, and even if there are untracked\n \tfiles in the way.  This is used to throw away local changes and\n@@ -129,13 +129,13 @@ OPTIONS\n When checking out paths from the index, do not fail upon unmerged\n entries; instead, unmerged entries are ignored.\n \n---ours::\n---theirs::\n+`--ours`::\n+`--theirs`::\n \tWhen checking out paths from the index, check out stage #2\n-\t('ours') or #3 ('theirs') for unmerged paths.\n+\t(`ours`) or #3 (`theirs`) for unmerged paths.\n +\n-Note that during `git rebase` and `git pull --rebase`, 'ours' and\n-'theirs' may appear swapped; `--ours` gives the version from the\n+Note that during `git rebase` and `git pull --rebase`, `ours` and\n+`theirs` may appear swapped; `--ours` gives the version from the\n branch the changes are rebased onto, while `--theirs` gives the\n version from the branch that holds your work that is being rebased.\n +\n@@ -149,22 +149,22 @@ as `ours` (i.e. \"our shared canonical history\"), while what you did\n on your side branch as `theirs` (i.e. \"one contributor's work on top\n of it\").\n \n--b <new-branch>::\n-\tCreate a new branch named `<new-branch>`, start it at\n-\t`<start-point>`, and check the resulting branch out;\n+`-b <new-branch>`::\n+\tCreate a new branch named _<new-branch>_, start it at\n+\t_<start-point>_, and check the resulting branch out;\n \tsee linkgit:git-branch[1] for details.\n \n--B <new-branch>::\n-\tCreates the branch `<new-branch>`, start it at `<start-point>`;\n-\tif it already exists, then reset it to `<start-point>`. And then\n+`-B <new-branch>`::\n+\tCreates the branch _<new-branch>_, start it at _<start-point>_;\n+\tif it already exists, then reset it to _<start-point>_. And then\n \tcheck the resulting branch out.  This is equivalent to running\n-\t\"git branch\" with \"-f\" followed by \"git checkout\" of that branch;\n+\t`git branch` with `-f` followed by `git checkout` of that branch;\n \tsee linkgit:git-branch[1] for details.\n \n--t::\n---track[=(direct|inherit)]::\n+`-t`::\n+`--track[=(direct|inherit)]`::\n \tWhen creating a new branch, set up \"upstream\" configuration. See\n-\t\"--track\" in linkgit:git-branch[1] for details.\n+\t`--track` in linkgit:git-branch[1] for details.\n +\n If no `-b` option is given, the name of the new branch will be\n derived from the remote-tracking branch, by looking at the local part of\n@@ -176,14 +176,14 @@ off of `origin/hack` (or `remotes/origin/hack`, or even\n guessing results in an empty name, the guessing is aborted.  You can\n explicitly give a name with `-b` in such a case.\n \n---no-track::\n+`--no-track`::\n \tDo not set up \"upstream\" configuration, even if the\n \t`branch.autoSetupMerge` configuration variable is true.\n \n---guess::\n---no-guess::\n-\tIf `<branch>` is not found but there does exist a tracking\n-\tbranch in exactly one remote (call it `<remote>`) with a\n+`--guess`::\n+`--no-guess`::\n+\tIf _<branch>_ is not found but there does exist a tracking\n+\tbranch in exactly one remote (call it _<remote>_) with a\n \tmatching name, treat as equivalent to\n +\n ------------\n@@ -192,10 +192,10 @@ $ git checkout -b <branch> --track <remote>/<branch>\n +\n If the branch exists in multiple remotes and one of them is named by\n the `checkout.defaultRemote` configuration variable, we'll use that\n-one for the purposes of disambiguation, even if the `<branch>` isn't\n+one for the purposes of disambiguation, even if the _<branch>_ isn't\n unique across all remotes. Set it to\n e.g. `checkout.defaultRemote=origin` to always checkout remote\n-branches from there if `<branch>` is ambiguous but exists on the\n+branches from there if _<branch>_ is ambiguous but exists on the\n 'origin' remote. See also `checkout.defaultRemote` in\n linkgit:git-config[1].\n +\n@@ -204,28 +204,28 @@ linkgit:git-config[1].\n The default behavior can be set via the `checkout.guess` configuration\n variable.\n \n--l::\n+`-l`::\n \tCreate the new branch's reflog; see linkgit:git-branch[1] for\n \tdetails.\n \n--d::\n---detach::\n+`-d`::\n+`--detach`::\n \tRather than checking out a branch to work on it, check out a\n \tcommit for inspection and discardable experiments.\n \tThis is the default behavior of `git checkout <commit>` when\n-\t`<commit>` is not a branch name.  See the \"DETACHED HEAD\" section\n+\t_<commit>_ is not a branch name.  See the \"DETACHED HEAD\" section\n \tbelow for details.\n \n---orphan <new-branch>::\n-\tCreate a new unborn branch, named `<new-branch>`, started from\n-\t`<start-point>` and switch to it.  The first commit made on this\n+`--orphan <new-branch>`::\n+\tCreate a new unborn branch, named _<new-branch>_, started from\n+\t_<start-point>_ and switch to it.  The first commit made on this\n \tnew branch will have no parents and it will be the root of a new\n \thistory totally disconnected from all the other branches and\n \tcommits.\n +\n The index and the working tree are adjusted as if you had previously run\n `git checkout <start-point>`.  This allows you to start a new history\n-that records a set of paths similar to `<start-point>` by easily running\n+that records a set of paths similar to _<start-point>_ by easily running\n `git commit -a` to make the root commit.\n +\n This can be useful when you want to publish the tree from a commit\n@@ -235,20 +235,20 @@ whose full history contains proprietary or otherwise encumbered bits of\n code.\n +\n If you want to start a disconnected history that records a set of paths\n-that is totally different from the one of `<start-point>`, then you should\n+that is totally different from the one of _<start-point>_, then you should\n clear the index and the working tree right after creating the orphan\n branch by running `git rm -rf .` from the top level of the working tree.\n Afterwards you will be ready to prepare your new files, repopulating the\n working tree, by copying them from elsewhere, extracting a tarball, etc.\n \n---ignore-skip-worktree-bits::\n-\tIn sparse checkout mode, `git checkout -- <paths>` would\n-\tupdate only entries matched by `<paths>` and sparse patterns\n+`--ignore-skip-worktree-bits`::\n+\tIn sparse checkout mode, `git checkout -- <path>...` would\n+\tupdate only entries matched by _<paths>_ and sparse patterns\n \tin `$GIT_DIR/info/sparse-checkout`. This option ignores\n-\tthe sparse patterns and adds back any files in `<paths>`.\n+\tthe sparse patterns and adds back any files in `<path>...`.\n \n--m::\n---merge::\n+`-m`::\n+`--merge`::\n \tWhen switching branches,\n \tif you have local modifications to one or more files that\n \tare different between the current branch and the branch to\n@@ -269,40 +269,40 @@ used when checking out paths from a tree-ish.\n +\n When switching branches with `--merge`, staged changes may be lost.\n \n---conflict=<style>::\n+`--conflict=<style>`::\n \tThe same as `--merge` option above, but changes the way the\n \tconflicting hunks are presented, overriding the\n \t`merge.conflictStyle` configuration variable.  Possible values are\n-\t\"merge\" (default), \"diff3\", and \"zdiff3\".\n+\t`merge` (default), `diff3`, and `zdiff3`.\n \n--p::\n---patch::\n+`-p`::\n+`--patch`::\n \tInteractively select hunks in the difference between the\n-\t`<tree-ish>` (or the index, if unspecified) and the working\n+\t_<tree-ish>_ (or the index, if unspecified) and the working\n \ttree.  The chosen hunks are then applied in reverse to the\n-\tworking tree (and if a `<tree-ish>` was specified, the index).\n+\tworking tree (and if a _<tree-ish>_ was specified, the index).\n +\n This means that you can use `git checkout -p` to selectively discard\n-edits from your current working tree. See the ``Interactive Mode''\n+edits from your current working tree. See the \"Interactive Mode\"\n section of linkgit:git-add[1] to learn how to operate the `--patch` mode.\n +\n Note that this option uses the no overlay mode by default (see also\n `--overlay`), and currently doesn't support overlay mode.\n \n---ignore-other-worktrees::\n+`--ignore-other-worktrees`::\n \t`git checkout` refuses when the wanted branch is already checked\n \tout or otherwise in use by another worktree. This option makes\n \tit check the branch out anyway. In other words, the branch can\n \tbe in use by more than one worktree.\n \n---overwrite-ignore::\n---no-overwrite-ignore::\n+`--overwrite-ignore`::\n+`--no-overwrite-ignore`::\n \tSilently overwrite ignored files when switching branches. This\n \tis the default behavior. Use `--no-overwrite-ignore` to abort\n \tthe operation when the new branch contains ignored files.\n \n---recurse-submodules::\n---no-recurse-submodules::\n+`--recurse-submodules`::\n+`--no-recurse-submodules`::\n \tUsing `--recurse-submodules` will update the content of all active\n \tsubmodules according to the commit recorded in the superproject. If\n \tlocal modifications in a submodule would be overwritten the checkout\n@@ -311,25 +311,25 @@ Note that this option uses the no overlay mode by default (see also\n \tJust like linkgit:git-submodule[1], this will detach `HEAD` of the\n \tsubmodule.\n \n---overlay::\n---no-overlay::\n+`--overlay`::\n+`--no-overlay`::\n \tIn the default overlay mode, `git checkout` never\n \tremoves files from the index or the working tree.  When\n \tspecifying `--no-overlay`, files that appear in the index and\n-\tworking tree, but not in `<tree-ish>` are removed, to make them\n-\tmatch `<tree-ish>` exactly.\n+\tworking tree, but not in _<tree-ish>_ are removed, to make them\n+\tmatch _<tree-ish>_ exactly.\n \n---pathspec-from-file=<file>::\n-\tPathspec is passed in `<file>` instead of commandline args. If\n-\t`<file>` is exactly `-` then standard input is used. Pathspec\n-\telements are separated by LF or CR/LF. Pathspec elements can be\n+`--pathspec-from-file=<file>`::\n+\tPathspec is passed in _<file>_ instead of commandline args. If\n+\t_<file>_ is exactly `-` then standard input is used. Pathspec\n+\telements are separated by _LF_ or _CR_/_LF_. Pathspec elements can be\n \tquoted as explained for the configuration variable `core.quotePath`\n \t(see linkgit:git-config[1]). See also `--pathspec-file-nul` and\n \tglobal `--literal-pathspecs`.\n \n---pathspec-file-nul::\n+`--pathspec-file-nul`::\n \tOnly meaningful with `--pathspec-from-file`. Pathspec elements are\n-\tseparated with NUL character and all other characters are taken\n+\tseparated with _NUL_ character and all other characters are taken\n \tliterally (including newlines and quotes).\n \n <branch>::\n@@ -343,33 +343,33 @@ You can use the `@{-N}` syntax to refer to the N-th last\n branch/commit checked out using \"git checkout\" operation. You may\n also specify `-` which is synonymous to `@{-1}`.\n +\n-As a special case, you may use `A...B` as a shortcut for the\n-merge base of `A` and `B` if there is exactly one merge base. You can\n-leave out at most one of `A` and `B`, in which case it defaults to `HEAD`.\n+As a special case, you may use `<rev-a>...<rev-b>` as a shortcut for the\n+merge base of _<rev-a>_ and _<rev-b>_ if there is exactly one merge base. You can\n+leave out at most one of _<rev-a>_ and _<rev-b>_, in which case it defaults to `HEAD`.\n \n-<new-branch>::\n+_<new-branch>_::\n \tName for the new branch.\n \n-<start-point>::\n+_<start-point>_::\n \tThe name of a commit at which to start the new branch; see\n \tlinkgit:git-branch[1] for details. Defaults to `HEAD`.\n +\n-As a special case, you may use `\"A...B\"` as a shortcut for the\n-merge base of `A` and `B` if there is exactly one merge base. You can\n-leave out at most one of `A` and `B`, in which case it defaults to `HEAD`.\n+As a special case, you may use `<rev-a>...<rev-b>` as a shortcut for the\n+merge base of _<rev-a>_ and _<rev-b>_ if there is exactly one merge base. You can\n+leave out at most one of _<rev-a>_ and _<rev-b>_, in which case it defaults to `HEAD`.\n \n-<tree-ish>::\n+_<tree-ish>_::\n \tTree to checkout from (when paths are given). If not specified,\n \tthe index will be used.\n +\n-As a special case, you may use `\"A...B\"` as a shortcut for the\n-merge base of `A` and `B` if there is exactly one merge base. You can\n-leave out at most one of `A` and `B`, in which case it defaults to `HEAD`.\n+As a special case, you may use `<rev-a>...<rev-b>` as a shortcut for the\n+merge base of _<rev-a>_ and _<rev-b>_ if there is exactly one merge base. You can\n+leave out at most one of _<rev-a>_ and _<rev-b>_, in which case it defaults to `HEAD`.\n \n-\\--::\n+`--`::\n \tDo not interpret any more arguments as options.\n \n-<pathspec>...::\n+`<pathspec>...`::\n \tLimits the paths affected by the operation.\n +\n For more details, see the 'pathspec' entry in linkgit:gitglossary[7].\n@@ -391,7 +391,7 @@ a---b---c  branch 'master' (refers to commit 'c')\n ------------\n \n When a commit is created in this state, the branch is updated to refer to\n-the new commit. Specifically, 'git commit' creates a new commit `d`, whose\n+the new commit. Specifically, `git commit` creates a new commit `d`, whose\n parent is commit `c`, and then updates branch `master` to refer to new\n commit `d`. `HEAD` still refers to branch `master` and so indirectly now refers\n to commit `d`:\n@@ -510,11 +510,11 @@ ARGUMENT DISAMBIGUATION\n -----------------------\n \n When there is only one argument given and it is not `--` (e.g. `git\n-checkout abc`), and when the argument is both a valid `<tree-ish>`\n-(e.g. a branch `abc` exists) and a valid `<pathspec>` (e.g. a file\n+checkout abc`), and when the argument is both a valid _<tree-ish>_\n+(e.g. a branch `abc` exists) and a valid _<pathspec>_ (e.g. a file\n or a directory whose name is \"abc\" exists), Git would usually ask\n you to disambiguate.  Because checking out a branch is so common an\n-operation, however, `git checkout abc` takes \"abc\" as a `<tree-ish>`\n+operation, however, `git checkout abc` takes \"abc\" as a _<tree-ish>_\n in such a situation.  Use `git checkout -- <pathspec>` if you want\n to checkout these paths out of the index.\n \n-- \ngitgitgadget\n\n"},{"id":"518884","messageId":"577da2bbaa6af0dcbc0c7bf67768a7af66d421ee.1748204829.git.gitgitgadget@gmail.com","threadId":"63522","inReplyTo":"pull.1927.git.1748204829.gitgitgadget@gmail.com","subject":"[PATCH 2/9] doc: convert git-merge manpage to new style","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-05-25T20:27:02Z","receivedAt":"2025-05-25T20:27:14Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n\n- Switch the synopsis to a synopsis block which will automatically\n  format placeholders in italics and keywords in monospace\n- Use _<placeholder>_ instead of <placeholder> in the description\n- Use `backticks` for keywords and more complex option\ndescriptions. The new rendering engine will apply synopsis rules to\nthese spans.\n\nIn order to avoid breaking the format on '<<<<<<' and '>>>>>' lines\nby applying the synopsis rules to these spans, they are formatted using '+'\nsigns instead of '`' signs.\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\n---\n Documentation/git-merge.adoc | 51 ++++++++++++++++++------------------\n 1 file changed, 25 insertions(+), 26 deletions(-)\n\ndiff --git a/Documentation/git-merge.adoc b/Documentation/git-merge.adoc\nindex 64281d6d44dd..12aa859d16de 100644\n--- a/Documentation/git-merge.adoc\n+++ b/Documentation/git-merge.adoc\n@@ -8,13 +8,13 @@ git-merge - Join two or more development histories together\n \n SYNOPSIS\n --------\n-[verse]\n-'git merge' [-n] [--stat] [--no-commit] [--squash] [--[no-]edit]\n+[synopsis]\n+git merge [-n] [--stat] [--no-commit] [--squash] [--[no-]edit]\n \t[--no-verify] [-s <strategy>] [-X <strategy-option>] [-S[<keyid>]]\n \t[--[no-]allow-unrelated-histories]\n \t[--[no-]rerere-autoupdate] [-m <msg>] [-F <file>]\n \t[--into-name <branch>] [<commit>...]\n-'git merge' (--continue | --abort | --quit)\n+git merge (--continue | --abort | --quit)\n \n DESCRIPTION\n -----------\n@@ -57,7 +57,7 @@ merge started (and especially if those changes were further modified\n after the merge was started), `git merge --abort` will in some cases be\n unable to reconstruct the original (pre-merge) changes. Therefore:\n \n-*Warning*: Running `git merge` with non-trivial uncommitted changes is\n+WARNING: Running `git merge` with non-trivial uncommitted changes is\n discouraged: while possible, it may leave you in a state that is hard to\n back out of in the case of a conflict.\n \n@@ -67,7 +67,7 @@ OPTIONS\n \n include::merge-options.adoc[]\n \n--m <msg>::\n+`-m <msg>`::\n \tSet the commit message to be used for the merge commit (in\n \tcase one is created).\n +\n@@ -78,13 +78,13 @@ The `git fmt-merge-msg` command can be\n used to give a good default for automated `git merge`\n invocations. The automated message can include the branch description.\n \n---into-name <branch>::\n+`--into-name <branch>`::\n \tPrepare the default merge message as if merging to the branch\n-\t`<branch>`, instead of the name of the real branch to which\n+\t_<branch>_, instead of the name of the real branch to which\n \tthe merge is made.\n \n--F <file>::\n---file=<file>::\n+`-F <file>`::\n+`--file=<file>`::\n \tRead the commit message to be used for the merge commit (in\n \tcase one is created).\n +\n@@ -93,12 +93,12 @@ will be appended to the specified message.\n \n include::rerere-options.adoc[]\n \n---overwrite-ignore::\n---no-overwrite-ignore::\n+`--overwrite-ignore`::\n+`--no-overwrite-ignore`::\n \tSilently overwrite ignored files from the merge result. This\n \tis the default behavior. Use `--no-overwrite-ignore` to abort.\n \n---abort::\n+`--abort`::\n \tAbort the current conflict resolution process, and\n \ttry to reconstruct the pre-merge state. If an autostash entry is\n \tpresent, apply it to the worktree.\n@@ -114,17 +114,17 @@ which case `git merge --abort` applies the stash entry to the worktree\n whereas `git reset --merge` will save the stashed changes in the stash\n list.\n \n---quit::\n+`--quit`::\n \tForget about the current merge in progress. Leave the index\n \tand the working tree as-is. If `MERGE_AUTOSTASH` is present, the\n \tstash entry will be saved to the stash list.\n \n---continue::\n+`--continue`::\n \tAfter a `git merge` stops due to conflicts you can conclude the\n \tmerge by running `git merge --continue` (see \"HOW TO RESOLVE\n \tCONFLICTS\" section below).\n \n-<commit>...::\n+`<commit>...`::\n \tCommits, usually other branch heads, to merge into our branch.\n \tSpecifying more than one commit will create a merge with\n \tmore than two parents (affectionately called an Octopus merge).\n@@ -152,7 +152,7 @@ To avoid recording unrelated changes in the merge commit,\n `git pull` and `git merge` will also abort if there are any changes\n registered in the index relative to the `HEAD` commit.  (Special\n narrow exceptions to this rule may exist depending on which merge\n-strategy is in use, but generally, the index must match HEAD.)\n+strategy is in use, but generally, the index must match `HEAD`.)\n \n If all named commits are already ancestors of `HEAD`, `git merge`\n will exit early with the message \"Already up to date.\"\n@@ -195,11 +195,11 @@ happens:\n    stage 2 from `HEAD`, and stage 3 from `MERGE_HEAD` (you\n    can inspect the stages with `git ls-files -u`).  The working\n    tree files contain the result of the merge operation; i.e. 3-way\n-   merge results with familiar conflict markers `<<<` `===` `>>>`.\n+   merge results with familiar conflict markers +<<<+ `===` +>>>+.\n 5. A ref named `AUTO_MERGE` is written, pointing to a tree\n    corresponding to the current content of the working tree (including\n    conflict markers for textual conflicts).  Note that this ref is only\n-   written when the 'ort' merge strategy is used (the default).\n+   written when the `ort` merge strategy is used (the default).\n 6. No other changes are made.  In particular, the local\n    modifications you had before you started merge will stay the\n    same and the index entries for them stay as they were,\n@@ -231,7 +231,6 @@ git merge v1.2.3^0\n git merge --ff-only v1.2.3\n ----\n \n-\n HOW CONFLICTS ARE PRESENTED\n ---------------------------\n \n@@ -260,7 +259,7 @@ And here is another line that is cleanly resolved or unmodified.\n ------------\n \n The area where a pair of conflicting changes happened is marked with markers\n-`<<<<<<<`, `=======`, and `>>>>>>>`.  The part before the `=======`\n++<<<<<<<+, `=======`, and +>>>>>>>+.  The part before the `=======`\n is typically your side, and the part afterwards is typically their side.\n \n The default format does not show what the original said in the conflicting\n@@ -270,7 +269,7 @@ side wants to say it is hard and you'd prefer to go shopping, while the\n other side wants to claim it is easy.\n \n An alternative style can be used by setting the `merge.conflictStyle`\n-configuration variable to either \"diff3\" or \"zdiff3\".  In \"diff3\"\n+configuration variable to either `diff3` or `zdiff3`.  In `diff3`\n style, the above conflict may look like this:\n \n ------------\n@@ -290,7 +289,7 @@ Git makes conflict resolution easy.\n And here is another line that is cleanly resolved or unmodified.\n ------------\n \n-while in \"zdiff3\" style, it may look like this:\n+while in `zdiff3` style, it may look like this:\n \n ------------\n Here are lines that are either unchanged from the common\n@@ -308,8 +307,8 @@ Git makes conflict resolution easy.\n And here is another line that is cleanly resolved or unmodified.\n ------------\n \n-In addition to the `<<<<<<<`, `=======`, and `>>>>>>>` markers, it uses\n-another `|||||||` marker that is followed by the original text.  You can\n+In addition to the +<<<<<<<+, `=======`, and +>>>>>>>+ markers, it uses\n+another +|||||||+ marker that is followed by the original text.  You can\n tell that the original just stated a fact, and your side simply gave in to\n that statement and gave up, while the other side tried to have a more\n positive attitude.  You can sometimes come up with a better resolution by\n@@ -390,8 +389,8 @@ include::merge-strategies.adoc[]\n CONFIGURATION\n -------------\n \n-branch.<name>.mergeOptions::\n-\tSets default options for merging into branch <name>. The syntax and\n+`branch.<name>.mergeOptions`::\n+\tSets default options for merging into branch _<name>_. The syntax and\n \tsupported options are the same as those of `git merge`, but option\n \tvalues containing whitespace characters are currently not supported.\n \n-- \ngitgitgadget\n\n"},{"id":"518885","messageId":"7a2f6fafd80e79416f4f4730909c30a1ddddbd6f.1748204829.git.gitgitgadget@gmail.com","threadId":"63522","inReplyTo":"pull.1927.git.1748204829.gitgitgadget@gmail.com","subject":"[PATCH 3/9] doc: convert merge options to new synopsis format","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-05-25T20:27:03Z","receivedAt":"2025-05-25T20:27:15Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n\n- Use _<placeholder>_ instead of <placeholder> in the description\n- Use `backticks` for keywords and more complex option\ndescriptions. The new rendering engine will apply synopsis rules to\nthese spans.\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\n---\n Documentation/merge-options.adoc  | 108 +++++++++++++++---------------\n Documentation/rerere-options.adoc |   4 +-\n 2 files changed, 56 insertions(+), 56 deletions(-)\n\ndiff --git a/Documentation/merge-options.adoc b/Documentation/merge-options.adoc\nindex 0022185201fc..9b3c7d6df4ef 100644\n--- a/Documentation/merge-options.adoc\n+++ b/Documentation/merge-options.adoc\n@@ -1,23 +1,23 @@\n---commit::\n---no-commit::\n+`--commit`::\n+`--no-commit`::\n \tPerform the merge and commit the result. This option can\n-\tbe used to override --no-commit.\n+\tbe used to override `--no-commit`.\n ifdef::git-pull[]\n \tOnly useful when merging.\n endif::git-pull[]\n +\n-With --no-commit perform the merge and stop just before creating\n+With `--no-commit` perform the merge and stop just before creating\n a merge commit, to give the user a chance to inspect and further\n tweak the merge result before committing.\n +\n Note that fast-forward updates do not create a merge commit and\n-therefore there is no way to stop those merges with --no-commit.\n+therefore there is no way to stop those merges with `--no-commit`.\n Thus, if you want to ensure your branch is not changed or updated\n-by the merge command, use --no-ff with --no-commit.\n+by the merge command, use `--no-ff` with `--no-commit`.\n \n---edit::\n--e::\n---no-edit::\n+`--edit`::\n+`-e`::\n+`--no-edit`::\n \tInvoke an editor before committing successful mechanical merge to\n \tfurther edit the auto-generated merge message, so that the user\n \tcan explain and justify the merge. The `--no-edit` option can be\n@@ -35,17 +35,17 @@ they run `git merge`. To make it easier to adjust such scripts to the\n updated behaviour, the environment variable `GIT_MERGE_AUTOEDIT` can be\n set to `no` at the beginning of them.\n \n---cleanup=<mode>::\n+`--cleanup=<mode>`::\n \tThis option determines how the merge message will be cleaned up before\n \tcommitting. See linkgit:git-commit[1] for more details. In addition, if\n-\tthe '<mode>' is given a value of `scissors`, scissors will be appended\n+\tthe _<mode>_ is given a value of `scissors`, scissors will be appended\n \tto `MERGE_MSG` before being passed on to the commit machinery in the\n \tcase of a merge conflict.\n \n ifdef::git-merge[]\n---ff::\n---no-ff::\n---ff-only::\n+`--ff`::\n+`--no-ff`::\n+`--ff-only`::\n \tSpecifies how a merge is handled when the merged-in history is\n \talready a descendant of the current history.  `--ff` is the\n \tdefault unless merging an annotated (and possibly signed) tag\n@@ -53,13 +53,13 @@ ifdef::git-merge[]\n \thierarchy, in which case `--no-ff` is assumed.\n endif::git-merge[]\n ifdef::git-pull[]\n---ff-only::\n+`--ff-only`::\n \tOnly update to the new history if there is no divergent local\n \thistory.  This is the default when no method for reconciling\n \tdivergent histories is provided (via the --rebase=* flags).\n \n---ff::\n---no-ff::\n+`--ff`::\n+`--no-ff`::\n \tWhen merging rather than rebasing, specifies how a merge is\n \thandled when the merged-in history is already a descendant of\n \tthe current history.  If merging is requested, `--ff` is the\n@@ -81,40 +81,40 @@ With `--ff-only`, resolve the merge as a fast-forward when possible.\n When not possible, refuse to merge and exit with a non-zero status.\n endif::git-merge[]\n \n--S[<keyid>]::\n---gpg-sign[=<keyid>]::\n---no-gpg-sign::\n-\tGPG-sign the resulting merge commit. The `keyid` argument is\n+`-S[<key-id>]`::\n+`--gpg-sign[=<key-id>]`::\n+`--no-gpg-sign`::\n+\tGPG-sign the resulting merge commit. The _<key-id>_ argument is\n \toptional and defaults to the committer identity; if specified,\n \tit must be stuck to the option without a space. `--no-gpg-sign`\n \tis useful to countermand both `commit.gpgSign` configuration variable,\n \tand earlier `--gpg-sign`.\n \n---log[=<n>]::\n---no-log::\n+`--log[=<n>]`::\n+`--no-log`::\n \tIn addition to branch names, populate the log message with\n-\tone-line descriptions from at most <n> actual commits that are being\n+\tone-line descriptions from at most _<n>_ actual commits that are being\n \tmerged. See also linkgit:git-fmt-merge-msg[1].\n ifdef::git-pull[]\n \tOnly useful when merging.\n endif::git-pull[]\n +\n-With --no-log do not list one-line descriptions from the\n+With `--no-log` do not list one-line descriptions from the\n actual commits being merged.\n \n include::signoff-option.adoc[]\n \n---stat::\n--n::\n---no-stat::\n+`--stat`::\n+`-n`::\n+`--no-stat`::\n \tShow a diffstat at the end of the merge. The diffstat is also\n \tcontrolled by the configuration option merge.stat.\n +\n-With -n or --no-stat do not show a diffstat at the end of the\n+With `-n` or `--no-stat` do not show a diffstat at the end of the\n merge.\n \n---squash::\n---no-squash::\n+`--squash`::\n+`--no-squash`::\n \tProduce the working tree and index state as if a real merge\n \thappened (except for the merge information), but do not actually\n \tmake a commit, move the `HEAD`, or record `$GIT_DIR/MERGE_HEAD`\n@@ -123,16 +123,16 @@ merge.\n \tthe current branch whose effect is the same as merging another\n \tbranch (or more in case of an octopus).\n +\n-With --no-squash perform the merge and commit the result. This\n-option can be used to override --squash.\n+With `--no-squash` perform the merge and commit the result. This\n+option can be used to override `--squash`.\n +\n-With --squash, --commit is not allowed, and will fail.\n+With `--squash`, `--commit` is not allowed, and will fail.\n ifdef::git-pull[]\n +\n Only useful when merging.\n endif::git-pull[]\n \n---[no-]verify::\n+`--[no-]verify`::\n \tBy default, the pre-merge and commit-msg hooks are run.\n \tWhen `--no-verify` is given, these are bypassed.\n \tSee also linkgit:githooks[5].\n@@ -140,21 +140,21 @@ ifdef::git-pull[]\n \tOnly useful when merging.\n endif::git-pull[]\n \n--s <strategy>::\n---strategy=<strategy>::\n+`-s <strategy>`::\n+`--strategy=<strategy>`::\n \tUse the given merge strategy; can be supplied more than\n \tonce to specify them in the order they should be tried.\n \tIf there is no `-s` option, a built-in list of strategies\n \tis used instead (`ort` when merging a single head,\n \t`octopus` otherwise).\n \n--X <option>::\n---strategy-option=<option>::\n+`-X <option>`::\n+`--strategy-option=<option>`::\n \tPass merge strategy specific option through to the merge\n \tstrategy.\n \n---verify-signatures::\n---no-verify-signatures::\n+`--verify-signatures`::\n+`--no-verify-signatures`::\n \tVerify that the tip commit of the side branch being merged is\n \tsigned with a valid key, i.e. a key that has a valid uid: in the\n \tdefault trust model, this means the signing key has been signed by\n@@ -165,22 +165,22 @@ ifdef::git-pull[]\n Only useful when merging.\n endif::git-pull[]\n \n---summary::\n---no-summary::\n-\tSynonyms to --stat and --no-stat; these are deprecated and will be\n+`--summary`::\n+`--no-summary`::\n+\tSynonyms to `--stat` and `--no-stat`; these are deprecated and will be\n \tremoved in the future.\n \n ifndef::git-pull[]\n--q::\n---quiet::\n-\tOperate quietly. Implies --no-progress.\n+`-q`::\n+`--quiet`::\n+\tOperate quietly. Implies `--no-progress`.\n \n--v::\n---verbose::\n+`-v`::\n+`--verbose`::\n \tBe verbose.\n \n---progress::\n---no-progress::\n+`--progress`::\n+`--no-progress`::\n \tTurn progress on/off explicitly. If neither is specified,\n \tprogress is shown if standard error is connected to a terminal.\n \tNote that not all merge strategies may support progress\n@@ -188,8 +188,8 @@ ifndef::git-pull[]\n \n endif::git-pull[]\n \n---autostash::\n---no-autostash::\n+`--autostash`::\n+`--no-autostash`::\n \tAutomatically create a temporary stash entry before the operation\n \tbegins, record it in the ref `MERGE_AUTOSTASH`\n \tand apply it after the operation ends.  This means\n@@ -197,7 +197,7 @@ endif::git-pull[]\n \twith care: the final stash application after a successful\n \tmerge might result in non-trivial conflicts.\n \n---allow-unrelated-histories::\n+`--allow-unrelated-histories`::\n \tBy default, `git merge` command refuses to merge histories\n \tthat do not share a common ancestor.  This option can be\n \tused to override this safety when merging histories of two\ndiff --git a/Documentation/rerere-options.adoc b/Documentation/rerere-options.adoc\nindex c3321ddea248..b0b920144a6c 100644\n--- a/Documentation/rerere-options.adoc\n+++ b/Documentation/rerere-options.adoc\n@@ -1,5 +1,5 @@\n---rerere-autoupdate::\n---no-rerere-autoupdate::\n+`--rerere-autoupdate`::\n+`--no-rerere-autoupdate`::\n \tAfter the rerere mechanism reuses a recorded resolution on\n \tthe current conflict to update the files in the working\n \ttree, allow it to also update the index with the result of\n-- \ngitgitgadget\n\n"},{"id":"518886","messageId":"038941c5be104536a4b894abb58d014a3fe583de.1748204829.git.gitgitgadget@gmail.com","threadId":"63522","inReplyTo":"pull.1927.git.1748204829.gitgitgadget@gmail.com","subject":"[PATCH 4/9] doc: merge-options.adoc remove a misleading double negation","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-05-25T20:27:04Z","receivedAt":"2025-05-25T20:27:16Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\n---\n Documentation/merge-options.adoc | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/merge-options.adoc b/Documentation/merge-options.adoc\nindex 9b3c7d6df4ef..078f4f6157a1 100644\n--- a/Documentation/merge-options.adoc\n+++ b/Documentation/merge-options.adoc\n@@ -203,7 +203,7 @@ endif::git-pull[]\n \tused to override this safety when merging histories of two\n \tprojects that started their lives independently. As that is\n \ta very rare occasion, no configuration variable to enable\n-\tthis by default exists and will not be added.\n+\tthis by default exists or will be added.\n ifdef::git-pull[]\n +\n Only useful when merging.\n-- \ngitgitgadget\n\n"},{"id":"518887","messageId":"6aa05d92f988004d2d30d852d8c810058d6a9175.1748204829.git.gitgitgadget@gmail.com","threadId":"63522","inReplyTo":"pull.1927.git.1748204829.gitgitgadget@gmail.com","subject":"[PATCH 5/9] doc: convert merge strategies to synopsis format","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-05-25T20:27:05Z","receivedAt":"2025-05-25T20:27:17Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n\n- Switch the synopsis to a synopsis block which will automatically\n  format placeholders in italics and keywords in monospace\n- Use _<placeholder>_ instead of <placeholder> in the description\n- Use `backticks` for keywords and more complex option\ndescriptions. The new rendering engine will apply synopsis rules to\nthese spans.\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\n---\n Documentation/merge-strategies.adoc | 58 ++++++++++++++---------------\n 1 file changed, 29 insertions(+), 29 deletions(-)\n\ndiff --git a/Documentation/merge-strategies.adoc b/Documentation/merge-strategies.adoc\nindex 9e034f447e76..2ba43f84e709 100644\n--- a/Documentation/merge-strategies.adoc\n+++ b/Documentation/merge-strategies.adoc\n@@ -6,7 +6,7 @@ backend 'merge strategies' to be chosen with `-s` option.  Some strategies\n can also take their own options, which can be passed by giving `-X<option>`\n arguments to `git merge` and/or `git pull`.\n \n-ort::\n+`ort`::\n \tThis is the default merge strategy when pulling or merging one\n \tbranch.  This strategy can only resolve two heads using a\n \t3-way merge algorithm.  When there is more than one common\n@@ -29,26 +29,26 @@ descendant. Otherwise, Git will treat this case as a conflict, suggesting\n as a resolution a submodule commit that is descendant of the conflicting\n ones, if one exists.\n +\n-The 'ort' strategy can take the following options:\n+The `ort` strategy can take the following options:\n \n-ours;;\n+`ours`;;\n \tThis option forces conflicting hunks to be auto-resolved cleanly by\n \tfavoring 'our' version.  Changes from the other tree that do not\n \tconflict with our side are reflected in the merge result.\n \tFor a binary file, the entire contents are taken from our side.\n +\n-This should not be confused with the 'ours' merge strategy, which does not\n+This should not be confused with the `ours` merge strategy, which does not\n even look at what the other tree contains at all.  It discards everything\n the other tree did, declaring 'our' history contains all that happened in it.\n \n-theirs;;\n-\tThis is the opposite of 'ours'; note that, unlike 'ours', there is\n-\tno 'theirs' merge strategy to confuse this merge option with.\n+`theirs`;;\n+\tThis is the opposite of `ours`; note that, unlike `ours`, there is\n+\tno `theirs` merge strategy to confuse this merge option with.\n \n-ignore-space-change;;\n-ignore-all-space;;\n-ignore-space-at-eol;;\n-ignore-cr-at-eol;;\n+`ignore-space-change`;;\n+`ignore-all-space`;;\n+`ignore-space-at-eol`;;\n+`ignore-cr-at-eol`;;\n \tTreats lines with the indicated type of whitespace change as\n \tunchanged for the sake of a three-way merge.  Whitespace\n \tchanges mixed with other changes to a line are not ignored.\n@@ -61,7 +61,7 @@ ignore-cr-at-eol;;\n   version includes a substantial change, 'their' version is used;\n * Otherwise, the merge proceeds in the usual way.\n \n-renormalize;;\n+`renormalize`;;\n \tThis runs a virtual check-out and check-in of all three stages\n \tof any file which needs a three-way merge.  This option is\n \tmeant to be used when merging branches with different clean\n@@ -69,31 +69,31 @@ renormalize;;\n \tbranches with differing checkin/checkout attributes\" in\n \tlinkgit:gitattributes[5] for details.\n \n-no-renormalize;;\n+`no-renormalize`;;\n \tDisables the `renormalize` option.  This overrides the\n \t`merge.renormalize` configuration variable.\n \n-find-renames[=<n>];;\n+`find-renames[=<n>]`;;\n \tTurn on rename detection, optionally setting the similarity\n \tthreshold.  This is the default. This overrides the\n-\t'merge.renames' configuration variable.\n+\t`merge.renames` configuration variable.\n \tSee also linkgit:git-diff[1] `--find-renames`.\n \n-rename-threshold=<n>;;\n+`rename-threshold=<n>`;;\n \tDeprecated synonym for `find-renames=<n>`.\n \n-no-renames;;\n+`no-renames`;;\n \tTurn off rename detection. This overrides the `merge.renames`\n \tconfiguration variable.\n \tSee also linkgit:git-diff[1] `--no-renames`.\n \n-histogram;;\n+`histogram`;;\n \tDeprecated synonym for `diff-algorithm=histogram`.\n \n-patience;;\n+`patience`;;\n \tDeprecated synonym for `diff-algorithm=patience`.\n \n-diff-algorithm=[histogram|minimal|myers|patience];;\n+`diff-algorithm=(histogram|minimal|myers|patience)`;;\n \tUse a different diff algorithm while merging, which can help\n \tavoid mismerges that occur due to unimportant matching lines\n \t(such as braces from distinct functions).  See also\n@@ -101,49 +101,49 @@ diff-algorithm=[histogram|minimal|myers|patience];;\n \tdefaults to `diff-algorithm=histogram`, while regular diffs\n \tcurrently default to the `diff.algorithm` config setting.\n \n-subtree[=<path>];;\n+`subtree[=<path>]`;;\n \tThis option is a more advanced form of 'subtree' strategy, where\n \tthe strategy makes a guess on how two trees must be shifted to\n \tmatch with each other when merging.  Instead, the specified path\n \tis prefixed (or stripped from the beginning) to make the shape of\n \ttwo trees to match.\n \n-recursive::\n+`recursive`::\n \tThis is now a synonym for `ort`.  It was an alternative\n \timplementation until v2.49.0, but was redirected to mean `ort`\n \tin v2.50.0.  The previous recursive strategy was the default\n \tstrategy for resolving two heads from Git v0.99.9k until\n \tv2.33.0.\n \n-resolve::\n+`resolve`::\n \tThis can only resolve two heads (i.e. the current branch\n \tand another branch you pulled from) using a 3-way merge\n \talgorithm.  It tries to carefully detect criss-cross\n \tmerge ambiguities.  It does not handle renames.\n \n-octopus::\n+`octopus`::\n \tThis resolves cases with more than two heads, but refuses to do\n \ta complex merge that needs manual resolution.  It is\n \tprimarily meant to be used for bundling topic branch\n \theads together.  This is the default merge strategy when\n \tpulling or merging more than one branch.\n \n-ours::\n+`ours`::\n \tThis resolves any number of heads, but the resulting tree of the\n \tmerge is always that of the current branch head, effectively\n \tignoring all changes from all other branches.  It is meant to\n \tbe used to supersede old development history of side\n-\tbranches.  Note that this is different from the -Xours option to\n-\tthe 'ort' merge strategy.\n+\tbranches.  Note that this is different from the `-Xours` option to\n+\tthe `ort` merge strategy.\n \n-subtree::\n+`subtree`::\n \tThis is a modified `ort` strategy. When merging trees A and\n \tB, if B corresponds to a subtree of A, B is first adjusted to\n \tmatch the tree structure of A, instead of reading the trees at\n \tthe same level. This adjustment is also done to the common\n \tancestor tree.\n \n-With the strategies that use 3-way merge (including the default, 'ort'),\n+With the strategies that use 3-way merge (including the default, `ort`),\n if a change is made on both branches, but later reverted on one of the\n branches, that change will be present in the merged result; some people find\n this behavior confusing.  It occurs because only the heads and the merge base\n-- \ngitgitgadget\n\n"},{"id":"518888","messageId":"12b5868216e6f6f9cb5356c82f2e143af9fe4a6a.1748204829.git.gitgitgadget@gmail.com","threadId":"63522","inReplyTo":"pull.1927.git.1748204829.gitgitgadget@gmail.com","subject":"[PATCH 6/9] doc: switch merge config description to new synopsis format","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-05-25T20:27:06Z","receivedAt":"2025-05-25T20:27:17Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n\n- Use _<placeholder>_ instead of <placeholder> in the description\n- Use `backticks` for keywords and more complex option\ndescriptions. The new rendering engine will apply synopsis rules to\nthese spans.\n\nAdditionally, a list of option possible values has been reformatted as a\nstandalone definition list.\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\n---\n Documentation/config/fmt-merge-msg.adoc |  8 +--\n Documentation/config/merge.adoc         | 84 +++++++++++++------------\n 2 files changed, 48 insertions(+), 44 deletions(-)\n\ndiff --git a/Documentation/config/fmt-merge-msg.adoc b/Documentation/config/fmt-merge-msg.adoc\nindex 3fbf40e24f62..696ba0531ae1 100644\n--- a/Documentation/config/fmt-merge-msg.adoc\n+++ b/Documentation/config/fmt-merge-msg.adoc\n@@ -1,19 +1,19 @@\n-merge.branchdesc::\n+`merge.branchdesc`::\n \tIn addition to branch names, populate the log message with\n \tthe branch description text associated with them.  Defaults\n \tto false.\n \n-merge.log::\n+`merge.log`::\n \tIn addition to branch names, populate the log message with at\n \tmost the specified number of one-line descriptions from the\n \tactual commits that are being merged.  Defaults to false, and\n \ttrue is a synonym for 20.\n \n-merge.suppressDest::\n+`merge.suppressDest`::\n \tBy adding a glob that matches the names of integration\n \tbranches to this multi-valued configuration variable, the\n \tdefault merge message computed for merges into these\n-\tintegration branches will omit \"into <branch name>\" from\n+\tintegration branches will omit \"into _<branch-name>_\" from\n \tits title.\n +\n An element with an empty value can be used to clear the list\ndiff --git a/Documentation/config/merge.adoc b/Documentation/config/merge.adoc\nindex d2d0f21a712d..86359f6dd2d9 100644\n--- a/Documentation/config/merge.adoc\n+++ b/Documentation/config/merge.adoc\n@@ -1,9 +1,9 @@\n-merge.conflictStyle::\n+`merge.conflictStyle`::\n \tSpecify the style in which conflicted hunks are written out to\n \tworking tree files upon merge.  The default is \"merge\", which\n-\tshows a `<<<<<<<` conflict marker, changes made by one side,\n+\tshows a +<<<<<<<+ conflict marker, changes made by one side,\n \ta `=======` marker, changes made by the other side, and then\n-\ta `>>>>>>>` marker.  An alternate style, \"diff3\", adds a `|||||||`\n+\ta +>>>>>>>+ marker.  An alternate style, \"diff3\", adds a +|||||||+\n \tmarker and the original text before the `=======` marker.  The\n \t\"merge\" style tends to produce smaller conflict regions than diff3,\n \tboth because of the exclusion of the original text, and because\n@@ -13,17 +13,17 @@ merge.conflictStyle::\n \tthe conflict region when those matching lines appear near either\n \tthe beginning or end of a conflict region.\n \n-merge.defaultToUpstream::\n+`merge.defaultToUpstream`::\n \tIf merge is called without any commit argument, merge the upstream\n \tbranches configured for the current branch by using their last\n \tobserved values stored in their remote-tracking branches.\n \tThe values of the `branch.<current branch>.merge` that name the\n-\tbranches at the remote named by `branch.<current branch>.remote`\n+\tbranches at the remote named by `branch.<current-branch>.remote`\n \tare consulted, and then they are mapped via `remote.<remote>.fetch`\n \tto their corresponding remote-tracking branches, and the tips of\n \tthese tracking branches are merged. Defaults to true.\n \n-merge.ff::\n+`merge.ff`::\n \tBy default, Git does not create an extra merge commit when merging\n \ta commit that is a descendant of the current commit. Instead, the\n \ttip of the current branch is fast-forwarded. When set to `false`,\n@@ -33,42 +33,46 @@ merge.ff::\n \tallowed (equivalent to giving the `--ff-only` option from the\n \tcommand line).\n \n-merge.verifySignatures::\n-\tIf true, this is equivalent to the --verify-signatures command\n+`merge.verifySignatures`::\n+\tIf true, this is equivalent to the `--verify-signatures` command\n \tline option. See linkgit:git-merge[1] for details.\n \n include::fmt-merge-msg.adoc[]\n \n-merge.renameLimit::\n+`merge.renameLimit`::\n \tThe number of files to consider in the exhaustive portion of\n \trename detection during a merge.  If not specified, defaults\n-\tto the value of diff.renameLimit.  If neither\n-\tmerge.renameLimit nor diff.renameLimit are specified,\n+\tto the value of `diff.renameLimit`.  If neither\n+\t`merge.renameLimit` nor `diff.renameLimit` are specified,\n \tcurrently defaults to 7000.  This setting has no effect if\n \trename detection is turned off.\n \n-merge.renames::\n-\tWhether Git detects renames.  If set to \"false\", rename detection\n-\tis disabled. If set to \"true\", basic rename detection is enabled.\n+`merge.renames`::\n+\tWhether Git detects renames.  If set to `false`, rename detection\n+\tis disabled. If set to `true`, basic rename detection is enabled.\n \tDefaults to the value of diff.renames.\n \n-merge.directoryRenames::\n+`merge.directoryRenames`::\n \tWhether Git detects directory renames, affecting what happens at\n \tmerge time to new files added to a directory on one side of\n \thistory when that directory was renamed on the other side of\n-\thistory.  If merge.directoryRenames is set to \"false\", directory\n-\trename detection is disabled, meaning that such new files will be\n-\tleft behind in the old directory.  If set to \"true\", directory\n-\trename detection is enabled, meaning that such new files will be\n-\tmoved into the new directory.  If set to \"conflict\", a conflict\n-\twill be reported for such paths.  If merge.renames is false,\n-\tmerge.directoryRenames is ignored and treated as false.  Defaults\n-\tto \"conflict\".\n-\n-merge.renormalize::\n+\thistory. Possible values are:\n++\n+--\n+`false`;; Directory rename detection is disabled, meaning that such new files will be\n+\tleft behind in the old directory.\n+`true`;; Directory rename detection is enabled, meaning that such new files will be\n+\tmoved into the new directory.\n+`conflict`;; A conflict will be reported for such paths.\n+--\n++\n+If `merge.renames` is `false`, `merge.directoryRenames` is ignored and treated\n+as `false`. Defaults to `conflict`.\n+\n+`merge.renormalize`::\n \tTell Git that canonical representation of files in the\n \trepository has changed over time (e.g. earlier commits record\n-\ttext files with CRLF line endings, but recent ones use LF line\n+\ttext files with _CRLF_ line endings, but recent ones use _LF_ line\n \tendings).  In such a repository, for each file where a\n \tthree-way content merge is needed, Git can convert the data\n \trecorded in commits to a canonical form before performing a\n@@ -76,35 +80,35 @@ merge.renormalize::\n \tsee section \"Merging branches with differing checkin/checkout\n \tattributes\" in linkgit:gitattributes[5].\n \n-merge.stat::\n-\tWhether to print the diffstat between ORIG_HEAD and the merge result\n+`merge.stat`::\n+\tWhether to print the diffstat between `ORIG_HEAD` and the merge result\n \tat the end of the merge.  True by default.\n \n-merge.autoStash::\n-\tWhen set to true, automatically create a temporary stash entry\n+`merge.autoStash`::\n+\tWhen set to `true`, automatically create a temporary stash entry\n \tbefore the operation begins, and apply it after the operation\n \tends.  This means that you can run merge on a dirty worktree.\n \tHowever, use with care: the final stash application after a\n \tsuccessful merge might result in non-trivial conflicts.\n \tThis option can be overridden by the `--no-autostash` and\n \t`--autostash` options of linkgit:git-merge[1].\n-\tDefaults to false.\n+\tDefaults to `false`.\n \n-merge.tool::\n+`merge.tool`::\n \tControls which merge tool is used by linkgit:git-mergetool[1].\n \tThe list below shows the valid built-in values.\n \tAny other value is treated as a custom merge tool and requires\n-\tthat a corresponding mergetool.<tool>.cmd variable is defined.\n+\tthat a corresponding `mergetool.<tool>.cmd` variable is defined.\n \n-merge.guitool::\n+`merge.guitool`::\n \tControls which merge tool is used by linkgit:git-mergetool[1] when the\n-\t-g/--gui flag is specified. The list below shows the valid built-in values.\n+\t`-g`/`--gui` flag is specified. The list below shows the valid built-in values.\n \tAny other value is treated as a custom merge tool and requires that a\n-\tcorresponding mergetool.<guitool>.cmd variable is defined.\n+\tcorresponding `mergetool.<guitool>.cmd` variable is defined.\n \n include::{build_dir}/mergetools-merge.adoc[]\n \n-merge.verbosity::\n+`merge.verbosity`::\n \tControls the amount of output shown by the recursive merge\n \tstrategy.  Level 0 outputs nothing except a final error\n \tmessage if conflicts were detected. Level 1 outputs only\n@@ -112,15 +116,15 @@ merge.verbosity::\n \tabove outputs debugging information.  The default is level 2.\n \tCan be overridden by the `GIT_MERGE_VERBOSITY` environment variable.\n \n-merge.<driver>.name::\n+`merge.<driver>.name`::\n \tDefines a human-readable name for a custom low-level\n \tmerge driver.  See linkgit:gitattributes[5] for details.\n \n-merge.<driver>.driver::\n+`merge.<driver>.driver`::\n \tDefines the command that implements a custom low-level\n \tmerge driver.  See linkgit:gitattributes[5] for details.\n \n-merge.<driver>.recursive::\n+`merge.<driver>.recursive`::\n \tNames a low-level merge driver to be used when\n \tperforming an internal merge between common ancestors.\n \tSee linkgit:gitattributes[5] for details.\n-- \ngitgitgadget\n\n"},{"id":"518889","messageId":"2e3200c0f6f35c3de777c8ccf72a54b8da62dada.1748204829.git.gitgitgadget@gmail.com","threadId":"63522","inReplyTo":"pull.1927.git.1748204829.gitgitgadget@gmail.com","subject":"[PATCH 7/9] doc: convert git-mergetool manpage to new synopsis style","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-05-25T20:27:07Z","receivedAt":"2025-05-25T20:27:18Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n\n- Switch the synopsis to a synopsis block which will automatically\n  format placeholders in italics and keywords in monospace\n- Use _<placeholder>_ instead of <placeholder> in the description\n- Use `backticks` for keywords and more complex option\ndescriptions. The new rendering engine will apply synopsis rules to\nthese spans.\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\n---\n Documentation/git-mergetool.adoc | 62 ++++++++++++++++----------------\n 1 file changed, 31 insertions(+), 31 deletions(-)\n\ndiff --git a/Documentation/git-mergetool.adoc b/Documentation/git-mergetool.adoc\nindex 046c3258f050..77d0b5055057 100644\n--- a/Documentation/git-mergetool.adoc\n+++ b/Documentation/git-mergetool.adoc\n@@ -7,95 +7,95 @@ git-mergetool - Run merge conflict resolution tools to resolve merge conflicts\n \n SYNOPSIS\n --------\n-[verse]\n-'git mergetool' [--tool=<tool>] [-y | --[no-]prompt] [<file>...]\n+[synopsis]\n+git mergetool [--tool=<tool>] [-y | --[no-]prompt] [<file>...]\n \n DESCRIPTION\n -----------\n \n Use `git mergetool` to run one of several merge utilities to resolve\n-merge conflicts.  It is typically run after 'git merge'.\n+merge conflicts.  It is typically run after `git merge`.\n \n If one or more <file> parameters are given, the merge tool program will\n be run to resolve differences in each file (skipping those without\n conflicts).  Specifying a directory will include all unresolved files in\n-that path.  If no <file> names are specified, 'git mergetool' will run\n+that path.  If no _<file>_ names are specified, `git mergetool` will run\n the merge tool program on every file with merge conflicts.\n \n OPTIONS\n -------\n--t <tool>::\n---tool=<tool>::\n-\tUse the merge resolution program specified by <tool>.\n-\tValid values include emerge, gvimdiff, kdiff3,\n-\tmeld, vimdiff, and tortoisemerge. Run `git mergetool --tool-help`\n-\tfor the list of valid <tool> settings.\n+`-t <tool>`::\n+`--tool=<tool>`::\n+\tUse the merge resolution program specified by _<tool>_.\n+\tValid values include `emerge`, `gvimdiff`, `kdiff3`,\n+\t`meld`, `vimdiff`, and `tortoisemerge`. Run `git mergetool --tool-help`\n+\tfor the list of valid _<tool>_ settings.\n +\n-If a merge resolution program is not specified, 'git mergetool'\n+If a merge resolution program is not specified, `git mergetool`\n will use the configuration variable `merge.tool`.  If the\n-configuration variable `merge.tool` is not set, 'git mergetool'\n+configuration variable `merge.tool` is not set, `git mergetool`\n will pick a suitable default.\n +\n You can explicitly provide a full path to the tool by setting the\n configuration variable `mergetool.<tool>.path`. For example, you\n can configure the absolute path to kdiff3 by setting\n-`mergetool.kdiff3.path`. Otherwise, 'git mergetool' assumes the\n-tool is available in PATH.\n+`mergetool.kdiff3.path`. Otherwise, `git mergetool` assumes the\n+tool is available in `$PATH`.\n +\n Instead of running one of the known merge tool programs,\n-'git mergetool' can be customized to run an alternative program\n+`git mergetool` can be customized to run an alternative program\n by specifying the command line to invoke in a configuration\n variable `mergetool.<tool>.cmd`.\n +\n-When 'git mergetool' is invoked with this tool (either through the\n+When `git mergetool` is invoked with this tool (either through the\n `-t` or `--tool` option or the `merge.tool` configuration\n-variable), the configured command line will be invoked with `$BASE`\n+variable), the configured command line will be invoked with `BASE`\n set to the name of a temporary file containing the common base for\n-the merge, if available; `$LOCAL` set to the name of a temporary\n+the merge, if available; `LOCAL` set to the name of a temporary\n file containing the contents of the file on the current branch;\n-`$REMOTE` set to the name of a temporary file containing the\n-contents of the file to be merged, and `$MERGED` set to the name\n+`REMOTE` set to the name of a temporary file containing the\n+contents of the file to be merged, and `MERGED` set to the name\n of the file to which the merge tool should write the result of the\n merge resolution.\n +\n If the custom merge tool correctly indicates the success of a\n merge resolution with its exit code, then the configuration\n variable `mergetool.<tool>.trustExitCode` can be set to `true`.\n-Otherwise, 'git mergetool' will prompt the user to indicate the\n+Otherwise, `git mergetool` will prompt the user to indicate the\n success of the resolution after the custom tool has exited.\n \n---tool-help::\n+`--tool-help`::\n \tPrint a list of merge tools that may be used with `--tool`.\n \n--y::\n---no-prompt::\n+`-y`::\n+`--no-prompt`::\n \tDon't prompt before each invocation of the merge resolution\n \tprogram.\n \tThis is the default if the merge resolution program is\n \texplicitly specified with the `--tool` option or with the\n \t`merge.tool` configuration variable.\n \n---prompt::\n+`--prompt`::\n \tPrompt before each invocation of the merge resolution program\n \tto give the user a chance to skip the path.\n \n--g::\n---gui::\n-\tWhen 'git-mergetool' is invoked with the `-g` or `--gui` option,\n+`-g`::\n+`--gui`::\n+\tWhen `git-mergetool` is invoked with the `-g` or `--gui` option,\n \tthe default merge tool will be read from the configured\n \t`merge.guitool` variable instead of `merge.tool`. If\n \t`merge.guitool` is not set, we will fallback to the tool\n \tconfigured under `merge.tool`. This may be autoselected using\n \tthe configuration variable `mergetool.guiDefault`.\n \n---no-gui::\n+`--no-gui`::\n \tThis overrides a previous `-g` or `--gui` setting or\n \t`mergetool.guiDefault` configuration and reads the default merge\n \ttool from the configured `merge.tool` variable.\n \n--O<orderfile>::\n+`-O<orderfile>`::\n \tProcess files in the order specified in the\n-\t<orderfile>, which has one shell glob pattern per line.\n+\t_<orderfile>_, which has one shell glob pattern per line.\n \tThis overrides the `diff.orderFile` configuration variable\n \t(see linkgit:git-config[1]).  To cancel `diff.orderFile`,\n \tuse `-O/dev/null`.\n-- \ngitgitgadget\n\n"},{"id":"518890","messageId":"907bbb46c4bac448ed6666e1e95bda7df8d7e010.1748204829.git.gitgitgadget@gmail.com","threadId":"63522","inReplyTo":"pull.1927.git.1748204829.gitgitgadget@gmail.com","subject":"[PATCH 8/9] doc: convert git-mergetool options to new synopsis style","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-05-25T20:27:08Z","receivedAt":"2025-05-25T20:27:20Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n\n- Use _<placeholder>_ instead of <placeholder> in the description\n- Use `backticks` for keywords and more complex option\ndescriptions. The new rendering engine will apply synopsis rules to\nthese spans.\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\n---\n Documentation/config/mergetool.adoc   | 54 +++++++++++++--------------\n Documentation/mergetools/vimdiff.adoc | 16 ++++----\n 2 files changed, 35 insertions(+), 35 deletions(-)\n\ndiff --git a/Documentation/config/mergetool.adoc b/Documentation/config/mergetool.adoc\nindex 00bf665aa09b..6be506145c15 100644\n--- a/Documentation/config/mergetool.adoc\n+++ b/Documentation/config/mergetool.adoc\n@@ -1,24 +1,24 @@\n-mergetool.<tool>.path::\n+`mergetool.<tool>.path`::\n \tOverride the path for the given tool.  This is useful in case\n-\tyour tool is not in the PATH.\n+\tyour tool is not in the `$PATH`.\n \n-mergetool.<tool>.cmd::\n+`mergetool.<tool>.cmd`::\n \tSpecify the command to invoke the specified merge tool.  The\n \tspecified command is evaluated in shell with the following\n-\tvariables available: 'BASE' is the name of a temporary file\n+\tvariables available: `BASE` is the name of a temporary file\n \tcontaining the common base of the files to be merged, if available;\n-\t'LOCAL' is the name of a temporary file containing the contents of\n-\tthe file on the current branch; 'REMOTE' is the name of a temporary\n+\t`LOCAL` is the name of a temporary file containing the contents of\n+\tthe file on the current branch; `REMOTE` is the name of a temporary\n \tfile containing the contents of the file from the branch being\n-\tmerged; 'MERGED' contains the name of the file to which the merge\n+\tmerged; `MERGED` contains the name of the file to which the merge\n \ttool should write the results of a successful merge.\n \n-mergetool.<tool>.hideResolved::\n+`mergetool.<tool>.hideResolved`::\n \tAllows the user to override the global `mergetool.hideResolved` value\n \tfor a specific tool. See `mergetool.hideResolved` for the full\n \tdescription.\n \n-mergetool.<tool>.trustExitCode::\n+`mergetool.<tool>.trustExitCode`::\n \tFor a custom merge command, specify whether the exit code of\n \tthe merge command can be used to determine whether the merge was\n \tsuccessful.  If this is not set to true then the merge target file\n@@ -26,7 +26,7 @@ mergetool.<tool>.trustExitCode::\n \tif the file has been updated; otherwise, the user is prompted to\n \tindicate the success of the merge.\n \n-mergetool.meld.hasOutput::\n+`mergetool.meld.hasOutput`::\n \tOlder versions of `meld` do not support the `--output` option.\n \tGit will attempt to detect whether `meld` supports `--output`\n \tby inspecting the output of `meld --help`.  Configuring\n@@ -35,7 +35,7 @@ mergetool.meld.hasOutput::\n \tto `true` tells Git to unconditionally use the `--output` option,\n \tand `false` avoids using `--output`.\n \n-mergetool.meld.useAutoMerge::\n+`mergetool.meld.useAutoMerge`::\n \tWhen the `--auto-merge` is given, meld will merge all non-conflicting\n \tparts automatically, highlight the conflicting parts, and wait for\n \tuser decision.  Setting `mergetool.meld.useAutoMerge` to `true` tells\n@@ -45,15 +45,15 @@ mergetool.meld.useAutoMerge::\n \tvalue of `false` avoids using `--auto-merge` altogether, and is the\n \tdefault value.\n \n-mergetool.<vimdiff variant>.layout::\n-\tConfigure the split window layout for vimdiff's `<variant>`, which is any of `vimdiff`,\n+`mergetool.<variant>.layout`::\n+\tConfigure the split window layout for vimdiff's _<variant>_, which is any of `vimdiff`,\n \t`nvimdiff`, `gvimdiff`.\n \tUpon launching `git mergetool` with `--tool=<variant>` (or without `--tool`\n-\tif `merge.tool` is configured as `<variant>`), Git will consult\n+\tif `merge.tool` is configured as _<variant>_), Git will consult\n \t`mergetool.<variant>.layout` to determine the tool's layout. If the\n-\tvariant-specific configuration is not available, `vimdiff`'s is used as\n+\tvariant-specific configuration is not available, `vimdiff` ' s is used as\n \tfallback.  If that too is not available, a default layout with 4 windows\n-\twill be used.  To configure the layout, see the `BACKEND SPECIFIC HINTS`\n+\twill be used.  To configure the layout, see the 'BACKEND SPECIFIC HINTS'\n ifdef::git-mergetool[]\n \tsection.\n endif::[]\n@@ -61,39 +61,39 @@ ifndef::git-mergetool[]\n \tsection in linkgit:git-mergetool[1].\n endif::[]\n \n-mergetool.hideResolved::\n+`mergetool.hideResolved`::\n \tDuring a merge, Git will automatically resolve as many conflicts as\n-\tpossible and write the 'MERGED' file containing conflict markers around\n-\tany conflicts that it cannot resolve; 'LOCAL' and 'REMOTE' normally\n-\trepresent the versions of the file from before Git's conflict\n-\tresolution. This flag causes 'LOCAL' and 'REMOTE' to be overwritten so\n+\tpossible and write the `$MERGED` file containing conflict markers around\n+\tany conflicts that it cannot resolve; `$LOCAL` and `$REMOTE` normally\n+\tare the versions of the file from before Git`s conflict\n+\tresolution. This flag causes `$LOCAL` and `$REMOTE` to be overwritten so\n \tthat only the unresolved conflicts are presented to the merge tool. Can\n \tbe configured per-tool via the `mergetool.<tool>.hideResolved`\n \tconfiguration variable. Defaults to `false`.\n \n-mergetool.keepBackup::\n+`mergetool.keepBackup`::\n \tAfter performing a merge, the original file with conflict markers\n \tcan be saved as a file with a `.orig` extension.  If this variable\n \tis set to `false` then this file is not preserved.  Defaults to\n \t`true` (i.e. keep the backup files).\n \n-mergetool.keepTemporaries::\n+`mergetool.keepTemporaries`::\n \tWhen invoking a custom merge tool, Git uses a set of temporary\n \tfiles to pass to the tool. If the tool returns an error and this\n \tvariable is set to `true`, then these temporary files will be\n \tpreserved; otherwise, they will be removed after the tool has\n \texited. Defaults to `false`.\n \n-mergetool.writeToTemp::\n-\tGit writes temporary 'BASE', 'LOCAL', and 'REMOTE' versions of\n+`mergetool.writeToTemp`::\n+\tGit writes temporary `BASE`, `LOCAL`, and `REMOTE` versions of\n \tconflicting files in the worktree by default.  Git will attempt\n \tto use a temporary directory for these files when set `true`.\n \tDefaults to `false`.\n \n-mergetool.prompt::\n+`mergetool.prompt`::\n \tPrompt before each invocation of the merge resolution program.\n \n-mergetool.guiDefault::\n+`mergetool.guiDefault`::\n \tSet `true` to use the `merge.guitool` by default (equivalent to\n \tspecifying the `--gui` argument), or `auto` to select `merge.guitool`\n \tor `merge.tool` depending on the presence of a `DISPLAY` environment\ndiff --git a/Documentation/mergetools/vimdiff.adoc b/Documentation/mergetools/vimdiff.adoc\nindex ab915df408e8..abfd426f74a0 100644\n--- a/Documentation/mergetools/vimdiff.adoc\n+++ b/Documentation/mergetools/vimdiff.adoc\n@@ -183,13 +183,13 @@ latter will be used as fallback if the variant-specific one is not set).\n In addition, for backwards compatibility with previous Git versions, you can\n also append `1`, `2` or `3` to either `vimdiff` or any of the variants (ex:\n `vimdiff3`, `nvimdiff1`, etc...) to use a predefined layout.\n-In other words, using `--tool=[g,n,]vimdiffx` is the same as using\n-`--tool=[g,n,]vimdiff` and setting configuration variable\n-`mergetool.[g,n,]vimdiff.layout` to...\n+In other words, using `--tool=[g|n]vimdiff<x>` is the same as using\n+`--tool=[g|n]vimdiff` and setting configuration variable\n+`mergetool.[g|n]vimdiff.layout` to...\n \n-  * `x=1`: `\"@LOCAL, REMOTE\"`\n-  * `x=2`: `\"LOCAL, MERGED, REMOTE\"`\n-  * `x=3`: `\"MERGED\"`\n+  * `<x>=1`: `\"@LOCAL, REMOTE\"`\n+  * `<x>=2`: `\"LOCAL, MERGED, REMOTE\"`\n+  * `<x>=3`: `\"MERGED\"`\n \n-Example: using `--tool=gvimdiff2` will open `gvim` with three columns (LOCAL,\n-MERGED and REMOTE).\n+Example: using `--tool=gvimdiff2` will open `gvim` with three columns (`LOCAL`,\n+`MERGED` and `REMOTE`).\n-- \ngitgitgadget\n\n"},{"id":"518891","messageId":"088a4c9cbfcd0928f4e8e112880ccf49569c339c.1748204829.git.gitgitgadget@gmail.com","threadId":"63522","inReplyTo":"pull.1927.git.1748204829.gitgitgadget@gmail.com","subject":"[PATCH 9/9] doc: convert git-switch manpage to new synopsis style","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-05-25T20:27:09Z","receivedAt":"2025-05-25T20:27:20Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n\n- Switch the synopsis to a synopsis block which will automatically\n  format placeholders in italics and keywords in monospace\n- Use _<placeholder>_ instead of <placeholder> in the description\n- Use `backticks` for keywords and more complex option\ndescriptions. The new rendering engine will apply synopsis rules to\nthese spans.\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\n---\n Documentation/git-switch.adoc | 114 +++++++++++++++++-----------------\n 1 file changed, 57 insertions(+), 57 deletions(-)\n\ndiff --git a/Documentation/git-switch.adoc b/Documentation/git-switch.adoc\nindex f55315c51ea0..9f62abf9e2b8 100644\n--- a/Documentation/git-switch.adoc\n+++ b/Documentation/git-switch.adoc\n@@ -7,11 +7,11 @@ git-switch - Switch branches\n \n SYNOPSIS\n --------\n-[verse]\n-'git switch' [<options>] [--no-guess] <branch>\n-'git switch' [<options>] --detach [<start-point>]\n-'git switch' [<options>] (-c|-C) <new-branch> [<start-point>]\n-'git switch' [<options>] --orphan <new-branch>\n+[synopsis]\n+git switch [<options>] [--no-guess] <branch>\n+git switch [<options>] --detach [<start-point>]\n+git switch [<options>] (-c|-C) <new-branch> [<start-point>]\n+git switch [<options>] --orphan <new-branch>\n \n DESCRIPTION\n -----------\n@@ -33,33 +33,33 @@ THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE.\n \n OPTIONS\n -------\n-<branch>::\n+_<branch>_::\n \tBranch to switch to.\n \n-<new-branch>::\n+_<new-branch>_::\n \tName for the new branch.\n \n-<start-point>::\n+_<start-point>_::\n \tThe starting point for the new branch. Specifying a\n-\t`<start-point>` allows you to create a branch based on some\n-\tother point in history than where HEAD currently points. (Or,\n+\t_<start-point>_ allows you to create a branch based on some\n+\tother point in history than where `HEAD` currently points. (Or,\n \tin the case of `--detach`, allows you to inspect and detach\n \tfrom some other point.)\n +\n-You can use the `@{-N}` syntax to refer to the N-th last\n-branch/commit switched to using \"git switch\" or \"git checkout\"\n+You can use the `@{-<N>}` syntax to refer to the _<N>_-th last\n+branch/commit switched to using `git switch` or `git checkout`\n operation. You may also specify `-` which is synonymous to `@{-1}`.\n This is often used to switch quickly between two branches, or to undo\n a branch switch by mistake.\n +\n-As a special case, you may use `A...B` as a shortcut for the merge\n-base of `A` and `B` if there is exactly one merge base. You can leave\n-out at most one of `A` and `B`, in which case it defaults to `HEAD`.\n-\n--c <new-branch>::\n---create <new-branch>::\n-\tCreate a new branch named `<new-branch>` starting at\n-\t`<start-point>` before switching to the branch. This is the\n+As a special case, you may use `<rev-a>...<rev-b>` as a shortcut for the merge\n+base of _<rev-a>_ and _<rev-b>_ if there is exactly one merge base. You can leave\n+out at most one of _<rev-a>_ and _<rev-b>_, in which case it defaults to `HEAD`.\n+\n+`-c <new-branch>`::\n+`--create <new-branch>`::\n+\tCreate a new branch named _<new-branch>_ starting at\n+\t_<start-point>_ before switching to the branch. This is the\n \ttransactional equivalent of\n +\n ------------\n@@ -67,32 +67,32 @@ $ git branch <new-branch>\n $ git switch <new-branch>\n ------------\n +\n-that is to say, the branch is not reset/created unless \"git switch\" is\n+that is to say, the branch is not reset/created unless `git switch` is\n successful (e.g., when the branch is in use in another worktree, not\n just the current branch stays the same, but the branch is not reset to\n the start-point, either).\n \n--C <new-branch>::\n---force-create <new-branch>::\n-\tSimilar to `--create` except that if `<new-branch>` already\n-\texists, it will be reset to `<start-point>`. This is a\n+`-C <new-branch>`::\n+`--force-create <new-branch>`::\n+\tSimilar to `--create` except that if _<new-branch>_ already\n+\texists, it will be reset to _<start-point>_. This is a\n \tconvenient shortcut for:\n +\n ------------\n-$ git branch -f <new-branch>\n-$ git switch <new-branch>\n+$ git branch -f _<new-branch>_\n+$ git switch _<new-branch>_\n ------------\n \n--d::\n---detach::\n+`-d`::\n+`--detach`::\n \tSwitch to a commit for inspection and discardable\n \texperiments. See the \"DETACHED HEAD\" section in\n \tlinkgit:git-checkout[1] for details.\n \n---guess::\n---no-guess::\n-\tIf `<branch>` is not found but there does exist a tracking\n-\tbranch in exactly one remote (call it `<remote>`) with a\n+`--guess`::\n+`--no-guess`::\n+\tIf _<branch>_ is not found but there does exist a tracking\n+\tbranch in exactly one remote (call it _<remote>_) with a\n \tmatching name, treat as equivalent to\n +\n ------------\n@@ -101,9 +101,9 @@ $ git switch -c <branch> --track <remote>/<branch>\n +\n If the branch exists in multiple remotes and one of them is named by\n the `checkout.defaultRemote` configuration variable, we'll use that\n-one for the purposes of disambiguation, even if the `<branch>` isn't\n+one for the purposes of disambiguation, even if the _<branch>_ isn't\n unique across all remotes. Set it to e.g. `checkout.defaultRemote=origin`\n-to always checkout remote branches from there if `<branch>` is\n+to always checkout remote branches from there if _<branch>_ is\n ambiguous but exists on the 'origin' remote. See also\n `checkout.defaultRemote` in linkgit:git-config[1].\n +\n@@ -112,19 +112,19 @@ ambiguous but exists on the 'origin' remote. See also\n The default behavior can be set via the `checkout.guess` configuration\n variable.\n \n--f::\n---force::\n+`-f`::\n+`--force`::\n \tAn alias for `--discard-changes`.\n \n---discard-changes::\n+`--discard-changes`::\n \tProceed even if the index or the working tree differs from\n \t`HEAD`. Both the index and working tree are restored to match\n \tthe switching target. If `--recurse-submodules` is specified,\n \tsubmodule content is also restored to match the switching\n \ttarget. This is used to throw away local changes.\n \n--m::\n---merge::\n+`-m`::\n+`--merge`::\n \tIf you have local modifications to one or more files that are\n \tdifferent between the current branch and the branch to which\n \tyou are switching, the command refuses to switch branches in\n@@ -138,25 +138,25 @@ paths are left unmerged, and you need to resolve the conflicts\n and mark the resolved paths with `git add` (or `git rm` if the merge\n should result in deletion of the path).\n \n---conflict=<style>::\n+`--conflict=<style>`::\n \tThe same as `--merge` option above, but changes the way the\n \tconflicting hunks are presented, overriding the\n \t`merge.conflictStyle` configuration variable.  Possible values are\n-\t\"merge\" (default), \"diff3\", and \"zdiff3\".\n+\t`merge` (default), `diff3`, and `zdiff3`.\n \n--q::\n---quiet::\n+`-q`::\n+`--quiet`::\n \tQuiet, suppress feedback messages.\n \n---progress::\n---no-progress::\n+`--progress`::\n+`--no-progress`::\n \tProgress status is reported on the standard error stream\n \tby default when it is attached to a terminal, unless `--quiet`\n \tis specified. This flag enables progress reporting even if not\n \tattached to a terminal, regardless of `--quiet`.\n \n--t::\n---track [direct|inherit]::\n+`-t`::\n+`--track[ (direct|inherit)]`::\n \tWhen creating a new branch, set up \"upstream\" configuration.\n \t`-c` is implied. See `--track` in linkgit:git-branch[1] for\n \tdetails.\n@@ -171,22 +171,22 @@ given name has no slash, or the above guessing results in an empty\n name, the guessing is aborted.  You can explicitly give a name with\n `-c` in such a case.\n \n---no-track::\n+`--no-track`::\n \tDo not set up \"upstream\" configuration, even if the\n \t`branch.autoSetupMerge` configuration variable is true.\n \n---orphan <new-branch>::\n-\tCreate a new unborn branch, named `<new-branch>`. All\n+`--orphan <new-branch>`::\n+\tCreate a new unborn branch, named _<new-branch>_. All\n \ttracked files are removed.\n \n---ignore-other-worktrees::\n+`--ignore-other-worktrees`::\n \t`git switch` refuses when the wanted ref is already\n \tchecked out by another worktree. This option makes it check\n \tthe ref out anyway. In other words, the ref can be held by\n \tmore than one worktree.\n \n---recurse-submodules::\n---no-recurse-submodules::\n+`--recurse-submodules`::\n+`--no-recurse-submodules`::\n \tUsing `--recurse-submodules` will update the content of all\n \tactive submodules according to the commit recorded in the\n \tsuperproject. If nothing (or `--no-recurse-submodules`) is\n@@ -239,7 +239,7 @@ $ git switch -\n ------------\n \n You can grow a new branch from any commit. For example, switch to\n-\"HEAD~3\" and create branch \"fixup\":\n+\"`HEAD~3`\" and create branch \"`fixup`\":\n \n ------------\n $ git switch -c fixup HEAD~3\n@@ -251,8 +251,8 @@ name:\n \n ------------\n $ git switch new-topic\n-Branch 'new-topic' set up to track remote branch 'new-topic' from 'origin'\n-Switched to a new branch 'new-topic'\n+Branch `new-topic` set up to track remote branch `new-topic` from `origin`\n+Switched to a new branch `new-topic`\n ------------\n \n To check out commit `HEAD~3` for temporary inspection or experiment\n-- \ngitgitgadget\n"}]}