{"thread":{"id":"61899","subject":"[PATCH 0/5] doc: git diff reformatting","startedAt":"2024-08-04T20:05:40Z","lastAt":"2025-04-07T15:11:33Z","messageCount":65,"participants":["Jean-Noël Avila via GitGitGadget","Johannes Sixt","Patrick Steinhardt","Junio C Hamano","Jean-Noël AVILA","Jean-Noël Avila","SZEDER Gábor"],"isPatch":true,"patchVersion":1,"patchTotal":5},"messages":[{"id":"500035","messageId":"pull.1769.git.1722801936.gitgitgadget@gmail.com","threadId":"61899","inReplyTo":null,"subject":"[PATCH 0/5] doc: git diff reformatting","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-08-04T20:05:31Z","receivedAt":"2024-08-04T20:05:40Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"This is the continuation of the editing of the manpages to reflect the new\nformatting rules.\n\nNote that this patch makes use of the synopsis paragraph styling and needs\nto be applied above ja/doc-synopsis-markup. As the dots can be primarily\ninterpreted as a grammar sign for repetition, here the dots which are part\nof the synopsis are manually forced to verbatim.\n\nJean-Noël Avila (5):\n  doc: git-diff: apply new documentation guidelines\n  doc: git-diff: apply format changes to diff-options\n  doc: git-diff: apply format changes to diff-format\n  doc: git-diff: apply format changes to diff-generate-patch\n  doc: git-diff: apply format changes to config part\n\n Documentation/config/diff.txt         | 160 ++++-----\n Documentation/diff-format.txt         |  38 +--\n Documentation/diff-generate-patch.txt |  48 +--\n Documentation/diff-options.txt        | 451 +++++++++++++-------------\n Documentation/git-diff.txt            | 101 +++---\n 5 files changed, 404 insertions(+), 394 deletions(-)\n\n\nbase-commit: 406f326d271e0bacecdb00425422c5fa3f314930\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-1769%2Fjnavila%2Fgit_diff_new-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1769/jnavila/git_diff_new-v1\nPull-Request: https://github.com/gitgitgadget/git/pull/1769\n-- \ngitgitgadget\n"},{"id":"500036","messageId":"515ddbf1dceacc0c186e3d31c13e76a5afc6c45f.1722801936.git.gitgitgadget@gmail.com","threadId":"61899","inReplyTo":"pull.1769.git.1722801936.gitgitgadget@gmail.com","subject":"[PATCH 1/5] doc: git-diff: apply new documentation guidelines","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-08-04T20:05:32Z","receivedAt":"2024-08-04T20:05:41Z","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/git-diff.txt | 101 +++++++++++++++++++------------------\n 1 file changed, 51 insertions(+), 50 deletions(-)\n\ndiff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt\nindex c065f023eca..7db497ec48d 100644\n--- a/Documentation/git-diff.txt\n+++ b/Documentation/git-diff.txt\n@@ -8,13 +8,13 @@ git-diff - Show changes between commits, commit and working tree, etc\n \n SYNOPSIS\n --------\n-[verse]\n-'git diff' [<options>] [<commit>] [--] [<path>...]\n-'git diff' [<options>] --cached [--merge-base] [<commit>] [--] [<path>...]\n-'git diff' [<options>] [--merge-base] <commit> [<commit>...] <commit> [--] [<path>...]\n-'git diff' [<options>] <commit>...<commit> [--] [<path>...]\n-'git diff' [<options>] <blob> <blob>\n-'git diff' [<options>] --no-index [--] <path> <path>\n+[synopsis]\n+git diff [<options>] [<commit>] [--] [<path>...]\n+git diff [<options>] --cached [--merge-base] [<commit>] [--] [<path>...]\n+git diff [<options>] [--merge-base] <commit> [<commit>...] <commit> [--] [<path>...]\n+git diff [<options>] <commit>`...`<commit> [--] [<path>...]\n+git diff [<options>] <blob> <blob>\n+git diff [<options>] --no-index [--] <path> <path>\n \n DESCRIPTION\n -----------\n@@ -23,7 +23,7 @@ between the index and a tree, changes between two trees, changes resulting\n from a merge, changes between two blob objects, or changes between two\n files on disk.\n \n-'git diff' [<options>] [--] [<path>...]::\n+`git diff` [_<options>_] [`--`] [_<path>_...]::\n \n \tThis form is to view the changes you made relative to\n \tthe index (staging area for the next commit).  In other\n@@ -31,7 +31,7 @@ files on disk.\n \tfurther add to the index but you still haven't.  You can\n \tstage these changes by using linkgit:git-add[1].\n \n-'git diff' [<options>] --no-index [--] <path> <path>::\n+`git diff` [_<options>_] `--no-index` [`--`] _<path>_ _<path>_::\n \n \tThis form is to compare the given two paths on the\n \tfilesystem.  You can omit the `--no-index` option when\n@@ -40,82 +40,82 @@ files on disk.\n \tor when running the command outside a working tree\n \tcontrolled by Git. This form implies `--exit-code`.\n \n-'git diff' [<options>] --cached [--merge-base] [<commit>] [--] [<path>...]::\n+`git diff` [_<options>_] `--cached` [`--merge-base`] [_<commit>_] [`--`] [_<path>_...]::\n \n \tThis form is to view the changes you staged for the next\n-\tcommit relative to the named <commit>.  Typically you\n+\tcommit relative to the named _<commit>_.  Typically you\n \twould want comparison with the latest commit, so if you\n-\tdo not give <commit>, it defaults to HEAD.\n-\tIf HEAD does not exist (e.g. unborn branches) and\n-\t<commit> is not given, it shows all staged changes.\n-\t--staged is a synonym of --cached.\n+\tdo not give _<commit>_, it defaults to `HEAD`.\n+\tIf `HEAD` does not exist (e.g. unborn branches) and\n+\t_<commit>_ is not given, it shows all staged changes.\n+\t`--staged` is a synonym of `--cached`.\n +\n-If --merge-base is given, instead of using <commit>, use the merge base\n-of <commit> and HEAD.  `git diff --cached --merge-base A` is equivalent to\n+If `--merge-base` is given, instead of using _<commit>_, use the merge base\n+of _<commit>_ and `HEAD`.  `git diff --cached --merge-base A` is equivalent to\n `git diff --cached $(git merge-base A HEAD)`.\n \n-'git diff' [<options>] [--merge-base] <commit> [--] [<path>...]::\n+`git diff` [_<options>_] [`--merge-base`] _<commit>_ [`--`] [_<path>_...]::\n \n \tThis form is to view the changes you have in your\n-\tworking tree relative to the named <commit>.  You can\n-\tuse HEAD to compare it with the latest commit, or a\n+\tworking tree relative to the named _<commit>_.  You can\n+\tuse `HEAD` to compare it with the latest commit, or a\n \tbranch name to compare with the tip of a different\n \tbranch.\n +\n-If --merge-base is given, instead of using <commit>, use the merge base\n-of <commit> and HEAD.  `git diff --merge-base A` is equivalent to\n+If `--merge-base` is given, instead of using _<commit>_, use the merge base\n+of _<commit>_ and `HEAD`.  `git diff --merge-base A` is equivalent to\n `git diff $(git merge-base A HEAD)`.\n \n-'git diff' [<options>] [--merge-base] <commit> <commit> [--] [<path>...]::\n+`git diff` [_<options>_] [`--merge-base`] _<commit>_ _<commit>_ [`--`] [_<path>_...]::\n \n \tThis is to view the changes between two arbitrary\n-\t<commit>.\n+\t_<commit>_.\n +\n-If --merge-base is given, use the merge base of the two commits for the\n+If `--merge-base` is given, use the merge base of the two commits for the\n \"before\" side.  `git diff --merge-base A B` is equivalent to\n `git diff $(git merge-base A B) B`.\n \n-'git diff' [<options>] <commit> <commit>... <commit> [--] [<path>...]::\n+`git diff` [_<options>_] _<commit>_ __<commit>__++...++__<commit>__ [`--`] [_<path>_...]::\n \n \tThis form is to view the results of a merge commit.  The first\n-\tlisted <commit> must be the merge itself; the remaining two or\n+\tlisted _<commit>_ must be the merge itself; the remaining two or\n \tmore commits should be its parents.  Convenient ways to produce\n \tthe desired set of revisions are to use the suffixes `^@` and\n-\t`^!`.  If A is a merge commit, then `git diff A A^@`,\n+\t`^!`.  If `A` is a merge commit, then `git diff A A^@`,\n \t`git diff A^!` and `git show A` all give the same combined diff.\n \n-'git diff' [<options>] <commit>..<commit> [--] [<path>...]::\n+`git diff` [_<options>_] __<commit>__++..++__<commit>__ [`--`] [_<path>_...]::\n \n \tThis is synonymous to the earlier form (without the `..`) for\n-\tviewing the changes between two arbitrary <commit>.  If <commit> on\n+\tviewing the changes between two arbitrary _<commit>_.  If _<commit>_ on\n \tone side is omitted, it will have the same effect as\n-\tusing HEAD instead.\n+\tusing `HEAD` instead.\n \n-'git diff' [<options>] <commit>\\...<commit> [--] [<path>...]::\n+`git diff` [_<options>_] __<commit>__++...++__<commit>__ [`--`] [_<path>_...]::\n \n \tThis form is to view the changes on the branch containing\n-\tand up to the second <commit>, starting at a common ancestor\n-\tof both <commit>.  `git diff A...B` is equivalent to\n+\tand up to the second _<commit>_, starting at a common ancestor\n+\tof both _<commit>_.  `git diff A...B` is equivalent to\n \t`git diff $(git merge-base A B) B`.  You can omit any one\n-\tof <commit>, which has the same effect as using HEAD instead.\n+\tof _<commit>_, which has the same effect as using `HEAD` instead.\n \n Just in case you are doing something exotic, it should be\n-noted that all of the <commit> in the above description, except\n+noted that all of the _<commit>_ in the above description, except\n in the `--merge-base` case and in the last two forms that use `..`\n-notations, can be any <tree>. A tree of interest is the one pointed to\n-by the ref named `AUTO_MERGE`, which is written by the 'ort' merge\n+notations, can be any _<tree>_. A tree of interest is the one pointed to\n+by the ref named `AUTO_MERGE`, which is written by the `ort` merge\n strategy upon hitting merge conflicts (see linkgit:git-merge[1]).\n Comparing the working tree with `AUTO_MERGE` shows changes you've made\n so far to resolve textual conflicts (see the examples below).\n \n-For a more complete list of ways to spell <commit>, see\n+For a more complete list of ways to spell _<commit>_, see\n \"SPECIFYING REVISIONS\" section in linkgit:gitrevisions[7].\n-However, \"diff\" is about comparing two _endpoints_, not ranges,\n-and the range notations (`<commit>..<commit>` and\n-`<commit>...<commit>`) do not mean a range as defined in the\n+However, `diff` is about comparing two _endpoints_, not ranges,\n+and the range notations (__<commit>__++..++__<commit>__ and\n+__<commit>__++...++__<commit>__) do not mean a range as defined in the\n \"SPECIFYING RANGES\" section in linkgit:gitrevisions[7].\n \n-'git diff' [<options>] <blob> <blob>::\n+`git diff` [_<options>_] _<blob>_ _<blob>_::\n \n \tThis form is to view the differences between the raw\n \tcontents of two blob objects.\n@@ -125,22 +125,22 @@ OPTIONS\n :git-diff: 1\n include::diff-options.txt[]\n \n--1 --base::\n--2 --ours::\n--3 --theirs::\n+`-1` `--base`::\n+`-2` `--ours`::\n+`-3` `--theirs`::\n \tCompare the working tree with the \"base\" version (stage #1),\n \t\"our branch\" (stage #2) or \"their branch\" (stage #3).  The\n \tindex contains these stages only for unmerged entries i.e.\n \twhile resolving conflicts.  See linkgit:git-read-tree[1]\n \tsection \"3-Way Merge\" for detailed information.\n \n--0::\n+`-0`::\n \tOmit diff output for unmerged entries and just show\n \t\"Unmerged\".  Can be used only when comparing the working tree\n \twith the index.\n \n-<path>...::\n-\tThe <paths> parameters, when given, are used to limit\n+_<path>_...::\n+\tThe _<path>_ parameters, when given, are used to limit\n \tthe diff to the named paths (you can give directory\n \tnames and get diff for all files under them).\n \n@@ -225,11 +225,12 @@ CONFIGURATION\n \n include::includes/cmd-config-section-all.txt[]\n \n+:git-diff: 1\n include::config/diff.txt[]\n \n SEE ALSO\n --------\n-diff(1),\n+`diff`(1),\n linkgit:git-difftool[1],\n linkgit:git-log[1],\n linkgit:gitdiffcore[7],\n-- \ngitgitgadget\n\n"},{"id":"500037","messageId":"81b5782d152d87a695e9a2dc685bb2006dbf5190.1722801936.git.gitgitgadget@gmail.com","threadId":"61899","inReplyTo":"pull.1769.git.1722801936.gitgitgadget@gmail.com","subject":"[PATCH 3/5] doc: git-diff: apply format changes to diff-format","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-08-04T20:05:34Z","receivedAt":"2024-08-04T20:05:42Z","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/diff-format.txt | 38 +++++++++++++++++------------------\n 1 file changed, 19 insertions(+), 19 deletions(-)\n\ndiff --git a/Documentation/diff-format.txt b/Documentation/diff-format.txt\nindex a3ae8747a22..34e703d58c4 100644\n--- a/Documentation/diff-format.txt\n+++ b/Documentation/diff-format.txt\n@@ -1,25 +1,25 @@\n Raw output format\n -----------------\n \n-The raw output format from \"git-diff-index\", \"git-diff-tree\",\n-\"git-diff-files\" and \"git diff --raw\" are very similar.\n+The raw output format from `git-diff-index`, `git-diff-tree`,\n+`git-diff-files` and `git diff --raw` are very similar.\n \n These commands all compare two sets of things; what is\n compared differs:\n \n-git-diff-index <tree-ish>::\n+`git-diff-index` _<tree-ish>_::\n         compares the <tree-ish> and the files on the filesystem.\n \n-git-diff-index --cached <tree-ish>::\n+`git-diff-index --cached` _<tree-ish>_::\n         compares the <tree-ish> and the index.\n \n-git-diff-tree [-r] <tree-ish-1> <tree-ish-2> [<pattern>...]::\n+`git-diff-tree` [`-r`] _<tree-ish-1>_ _<tree-ish-2>_ [_<pattern>_...]::\n         compares the trees named by the two arguments.\n \n-git-diff-files [<pattern>...]::\n+`git-diff-files` [_<pattern>_...]::\n         compares the index and the files on the filesystem.\n \n-The \"git-diff-tree\" command begins its output by printing the hash of\n+The `git-diff-tree` command begins its output by printing the hash of\n what is being compared. After that, all the commands print one output\n line per changed file.\n \n@@ -54,19 +54,19 @@ That is, from the left to the right:\n \n Possible status letters are:\n \n-- A: addition of a file\n-- C: copy of a file into a new one\n-- D: deletion of a file\n-- M: modification of the contents or mode of a file\n-- R: renaming of a file\n-- T: change in the type of the file (regular file, symbolic link or submodule)\n-- U: file is unmerged (you must complete the merge before it can\n+- `A`: addition of a file\n+- `C`: copy of a file into a new one\n+- `D`: deletion of a file\n+- `M`: modification of the contents or mode of a file\n+- `R`: renaming of a file\n+- `T`: change in the type of the file (regular file, symbolic link or submodule)\n+- `U`: file is unmerged (you must complete the merge before it can\n   be committed)\n-- X: \"unknown\" change type (most probably a bug, please report it)\n+- `X`: \"unknown\" change type (most probably a bug, please report it)\n \n-Status letters C and R are always followed by a score (denoting the\n+Status letters `C` and `R` are always followed by a score (denoting the\n percentage of similarity between the source and target of the move or\n-copy).  Status letter M may be followed by a score (denoting the\n+copy).  Status letter `M` may be followed by a score (denoting the\n percentage of dissimilarity) for file rewrites.\n \n The sha1 for \"dst\" is shown as all 0's if a file on the filesystem\n@@ -86,7 +86,7 @@ verbatim and the line is terminated by a NUL byte.\n diff format for merges\n ----------------------\n \n-\"git-diff-tree\", \"git-diff-files\" and \"git-diff --raw\"\n+`git-diff-tree`, `git-diff-files` and `git-diff --raw`\n can take `-c` or `--cc` option\n to generate diff output also for merge commits.  The output differs\n from the format described above in the following way:\n@@ -128,7 +128,7 @@ other diff formats\n ------------------\n \n The `--summary` option describes newly added, deleted, renamed and\n-copied files.  The `--stat` option adds diffstat(1) graph to the\n+copied files.  The `--stat` option adds `diffstat`(1) graph to the\n output.  These options can be combined with other options, such as\n `-p`, and are meant for human consumption.\n \n-- \ngitgitgadget\n\n"},{"id":"500038","messageId":"c1e7d6afb5099ecd533275ce228aae1c405654bd.1722801936.git.gitgitgadget@gmail.com","threadId":"61899","inReplyTo":"pull.1769.git.1722801936.gitgitgadget@gmail.com","subject":"[PATCH 2/5] doc: git-diff: apply format changes to diff-options","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-08-04T20:05:33Z","receivedAt":"2024-08-04T20:05:42Z","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\nThe format change is only applied to the sections of the file that are\nfiltered in git-diff.\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\n---\n Documentation/diff-options.txt | 451 +++++++++++++++++----------------\n 1 file changed, 229 insertions(+), 222 deletions(-)\n\ndiff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt\nindex cd0b81adbb6..76050af6995 100644\n--- a/Documentation/diff-options.txt\n+++ b/Documentation/diff-options.txt\n@@ -19,16 +19,16 @@ ifdef::git-format-patch[]\n endif::git-format-patch[]\n \n ifndef::git-format-patch[]\n--p::\n--u::\n---patch::\n+`-p`::\n+`-u`::\n+`--patch`::\n \tGenerate patch (see <<generate_patch_text_with_p>>).\n ifdef::git-diff[]\n \tThis is the default.\n endif::git-diff[]\n \n--s::\n---no-patch::\n+`-s`::\n+`--no-patch`::\n \tSuppress all output from the diff machinery.  Useful for\n \tcommands like `git show` that show the patch by default to\n \tsquelch their output, or to cancel the effect of options like\n@@ -39,28 +39,28 @@ endif::git-format-patch[]\n ifdef::git-log[]\n -m::\n \tShow diffs for merge commits in the default format. This is\n-\tsimilar to '--diff-merges=on', except `-m` will\n+\tsimilar to `--diff-merges=on`, except `-m` will\n \tproduce no output unless `-p` is given as well.\n \n -c::\n \tProduce combined diff output for merge commits.\n-\tShortcut for '--diff-merges=combined -p'.\n+\tShortcut for `--diff-merges=combined -p`.\n \n --cc::\n \tProduce dense combined diff output for merge commits.\n-\tShortcut for '--diff-merges=dense-combined -p'.\n+\tShortcut for `--diff-merges=dense-combined -p`.\n \n --dd::\n \tProduce diff with respect to first parent for both merge and\n \tregular commits.\n-\tShortcut for '--diff-merges=first-parent -p'.\n+\tShortcut for `--diff-merges=first-parent -p`.\n \n --remerge-diff::\n \tProduce remerge-diff output for merge commits.\n-\tShortcut for '--diff-merges=remerge -p'.\n+\tShortcut for `--diff-merges=remerge -p`.\n \n --no-diff-merges::\n-\tSynonym for '--diff-merges=off'.\n+\tSynonym for `--diff-merges=off`.\n \n --diff-merges=<format>::\n \tSpecify diff format to be used for merge commits. Default is\n@@ -70,37 +70,43 @@ ifdef::git-log[]\n The following formats are supported:\n +\n --\n-off, none::\n+off::\n+none::\n \tDisable output of diffs for merge commits. Useful to override\n \timplied value.\n-+\n-on, m::\n+\n+on::\n+m::\n \tMake diff output for merge commits to be shown in the default\n \tformat. The default format can be changed using\n \t`log.diffMerges` configuration variable, whose default value\n \tis `separate`.\n-+\n-first-parent, 1::\n+\n+first-parent::\n+1::\n \tShow full diff with respect to first parent. This is the same\n \tformat as `--patch` produces for non-merge commits.\n-+\n+\n separate::\n \tShow full diff with respect to each of parents.\n \tSeparate log entry and diff is generated for each parent.\n-+\n-combined, c::\n+\n+combined::\n+c::\n \tShow differences from each of the parents to the merge\n \tresult simultaneously instead of showing pairwise diff between\n \ta parent and the result one at a time. Furthermore, it lists\n \tonly files which were modified from all parents.\n-+\n-dense-combined, cc::\n+\n+dense-combined::\n+cc::\n \tFurther compress output produced by `--diff-merges=combined`\n \tby omitting uninteresting hunks whose contents in the parents\n \thave only two variants and the merge result picks one of them\n \twithout modification.\n-+\n-remerge, r::\n+\n+remerge::\n+r::\n \tRemerge two-parent merge commits to create a temporary tree\n \tobject--potentially containing files with conflict markers\n \tand such.  A diff is then shown between that temporary tree\n@@ -112,33 +118,33 @@ documented).\n --\n \n --combined-all-paths::\n-\tThis flag causes combined diffs (used for merge commits) to\n+\tcause combined diffs (used for merge commits) to\n \tlist the name of the file from all parents.  It thus only has\n \teffect when `--diff-merges=[dense-]combined` is in use, and\n \tis likely only useful if filename changes are detected (i.e.\n \twhen either rename or copy detection have been requested).\n endif::git-log[]\n \n--U<n>::\n---unified=<n>::\n-\tGenerate diffs with <n> lines of context instead of\n+++-U++__<n>__::\n+++--unified=++__<n>__::\n+\tGenerate diffs with _<n>_ lines of context instead of\n \tthe usual three.\n ifndef::git-format-patch[]\n \tImplies `--patch`.\n endif::git-format-patch[]\n \n---output=<file>::\n-\tOutput to a specific file instead of stdout.\n+++--output=++__<file>__::\n+\tOutput to _<file>_ instead of stdout.\n \n---output-indicator-new=<char>::\n---output-indicator-old=<char>::\n---output-indicator-context=<char>::\n+++--output-indicator-new=++__<char>__::\n+++--output-indicator-old=++__<char>__::\n+++--output-indicator-context=++__<char>__::\n \tSpecify the character used to indicate new, old or context\n-\tlines in the generated patch. Normally they are '+', '-' and\n+\tlines in the generated patch. Normally they are `+`, `-` and\n \t' ' respectively.\n \n ifndef::git-format-patch[]\n---raw::\n+`--raw`::\n ifndef::git-log[]\n \tGenerate the diff in raw format.\n ifdef::git-diff-core[]\n@@ -155,103 +161,104 @@ endif::git-log[]\n endif::git-format-patch[]\n \n ifndef::git-format-patch[]\n---patch-with-raw::\n+`--patch-with-raw`::\n \tSynonym for `-p --raw`.\n endif::git-format-patch[]\n \n ifdef::git-log[]\n--t::\n+`-t`::\n \tShow the tree objects in the diff output.\n endif::git-log[]\n \n---indent-heuristic::\n+`--indent-heuristic`::\n \tEnable the heuristic that shifts diff hunk boundaries to make patches\n \teasier to read. This is the default.\n \n---no-indent-heuristic::\n+`--no-indent-heuristic`::\n \tDisable the indent heuristic.\n \n---minimal::\n+`--minimal`::\n \tSpend extra time to make sure the smallest possible\n \tdiff is produced.\n \n---patience::\n+`--patience`::\n \tGenerate a diff using the \"patience diff\" algorithm.\n \n---histogram::\n+`--histogram`::\n \tGenerate a diff using the \"histogram diff\" algorithm.\n \n---anchored=<text>::\n+++--anchored=++__<text>__::\n \tGenerate a diff using the \"anchored diff\" algorithm.\n +\n This option may be specified more than once.\n +\n If a line exists in both the source and destination, exists only once,\n-and starts with this text, this algorithm attempts to prevent it from\n+and starts with _<text>_, this algorithm attempts to prevent it from\n appearing as a deletion or addition in the output. It uses the \"patience\n diff\" algorithm internally.\n \n---diff-algorithm={patience|minimal|histogram|myers}::\n+`--diff-algorithm=`(`patience`|`minimal`|`histogram`|`myers`)::\n \tChoose a diff algorithm. The variants are as follows:\n +\n --\n-`default`, `myers`;;\n+   `default`;;\n+   `myers`;;\n \tThe basic greedy diff algorithm. Currently, this is the default.\n-`minimal`;;\n+   `minimal`;;\n \tSpend extra time to make sure the smallest possible diff is\n \tproduced.\n-`patience`;;\n+   `patience`;;\n \tUse \"patience diff\" algorithm when generating patches.\n-`histogram`;;\n+   `histogram`;;\n \tThis algorithm extends the patience algorithm to \"support\n \tlow-occurrence common elements\".\n---\n-+\n+\n For instance, if you configured the `diff.algorithm` variable to a\n non-default value and want to use the default one, then you\n have to use `--diff-algorithm=default` option.\n+--\n \n---stat[=<width>[,<name-width>[,<count>]]]::\n+`--stat`[++=++__<width>__[++,++__<name-width>__[++,++__<count>__]]]::\n \tGenerate a diffstat. By default, as much space as necessary\n \twill be used for the filename part, and the rest for the graph\n \tpart. Maximum width defaults to terminal width, or 80 columns\n \tif not connected to a terminal, and can be overridden by\n-\t`<width>`. The width of the filename part can be limited by\n-\tgiving another width `<name-width>` after a comma or by setting\n-\t`diff.statNameWidth=<width>`. The width of the graph part can be\n-\tlimited by using `--stat-graph-width=<width>` or by setting\n-\t`diff.statGraphWidth=<width>`. Using `--stat` or\n+\t_<width>_. The width of the filename part can be limited by\n+\tgiving another width _<name-width>_ after a comma or by setting\n+\t++diff.statNameWidth=++__<name-width>__. The width of the graph part can be\n+\tlimited by using ++--stat-graph-width=++__<graph-width>__ or by setting\n+\t++diff.statGraphWidth=++__<graph-width>__. Using `--stat` or\n \t`--stat-graph-width` affects all commands generating a stat graph,\n \twhile setting `diff.statNameWidth` or `diff.statGraphWidth`\n \tdoes not affect `git format-patch`.\n-\tBy giving a third parameter `<count>`, you can limit the output to\n-\tthe first `<count>` lines, followed by `...` if there are more.\n+\tBy giving a third parameter _<count>_, you can limit the output to\n+\tthe first _<count>_ lines, followed by `...` if there are more.\n +\n-These parameters can also be set individually with `--stat-width=<width>`,\n-`--stat-name-width=<name-width>` and `--stat-count=<count>`.\n+These parameters can also be set individually with ++--stat-width=++__<width>__,\n+++--stat-name-width=++__<name-width>__ and ++--stat-count=++__<count>__.\n \n---compact-summary::\n+`--compact-summary`::\n \tOutput a condensed summary of extended header information such\n-\tas file creations or deletions (\"new\" or \"gone\", optionally \"+l\"\n-\tif it's a symlink) and mode changes (\"+x\" or \"-x\" for adding\n+\tas file creations or deletions (\"new\" or \"gone\", optionally `+l`\n+\tif it's a symlink) and mode changes (`+x` or `-x` for adding\n \tor removing executable bit respectively) in diffstat. The\n \tinformation is put between the filename part and the graph\n \tpart. Implies `--stat`.\n \n---numstat::\n+`--numstat`::\n \tSimilar to `--stat`, but shows number of added and\n \tdeleted lines in decimal notation and pathname without\n \tabbreviation, to make it more machine friendly.  For\n \tbinary files, outputs two `-` instead of saying\n \t`0 0`.\n \n---shortstat::\n+`--shortstat`::\n \tOutput only the last line of the `--stat` format containing total\n \tnumber of modified files, as well as number of added and deleted\n \tlines.\n \n--X[<param1,param2,...>]::\n---dirstat[=<param1,param2,...>]::\n+`-X`[__<param>__++,++...]::\n+`--dirstat`[++=++__<param>__++,++...]::\n \tOutput the distribution of relative amount of changes for each\n \tsub-directory. The behavior of `--dirstat` can be customized by\n \tpassing it a comma separated list of parameters.\n@@ -284,7 +291,7 @@ These parameters can also be set individually with `--stat-width=<width>`,\n \tNote that when using `cumulative`, the sum of the percentages\n \treported may exceed 100%. The default (non-cumulative) behavior can\n \tbe specified with the `noncumulative` parameter.\n-<limit>;;\n+_<limit>_;;\n \tAn integer parameter specifies a cut-off percent (3% by default).\n \tDirectories contributing less than this percentage of the changes\n \tare not shown in the output.\n@@ -295,29 +302,29 @@ directories with less than 10% of the total amount of changed files,\n and accumulating child directory counts in the parent directories:\n `--dirstat=files,10,cumulative`.\n \n---cumulative::\n-\tSynonym for --dirstat=cumulative\n+`--cumulative`::\n+\tSynonym for `--dirstat=cumulative`.\n \n---dirstat-by-file[=<param1,param2>...]::\n-\tSynonym for --dirstat=files,<param1>,<param2>...\n+`--dirstat-by-file`[++=++__<param>__++,++...]::\n+\tSynonym for ++--dirstat=files,++__<param>__++,++... .\n \n---summary::\n+`--summary`::\n \tOutput a condensed summary of extended header information\n \tsuch as creations, renames and mode changes.\n \n ifndef::git-format-patch[]\n---patch-with-stat::\n+`--patch-with-stat`::\n \tSynonym for `-p --stat`.\n endif::git-format-patch[]\n \n ifndef::git-format-patch[]\n \n--z::\n+`-z`::\n ifdef::git-log[]\n-\tSeparate the commits with NULs instead of newlines.\n+\tSeparate the commits with __NUL__s instead of newlines.\n +\n Also, when `--raw` or `--numstat` has been given, do not munge\n-pathnames and use NULs as output field terminators.\n+pathnames and use __NUL__s as output field terminators.\n endif::git-log[]\n ifndef::git-log[]\n \tWhen `--raw`, `--numstat`, `--name-only` or `--name-status` has been\n@@ -328,89 +335,89 @@ Without this option, pathnames with \"unusual\" characters are quoted as\n explained for the configuration variable `core.quotePath` (see\n linkgit:git-config[1]).\n \n---name-only::\n+`--name-only`::\n \tShow only the name of each changed file in the post-image tree.\n \tThe file names are often encoded in UTF-8.\n \tFor more information see the discussion about encoding in the linkgit:git-log[1]\n \tmanual page.\n \n---name-status::\n+`--name-status`::\n \tShow only the name(s) and status of each changed file. See the description\n \tof the `--diff-filter` option on what the status letters mean.\n \tJust like `--name-only` the file names are often encoded in UTF-8.\n \n---submodule[=<format>]::\n+`--submodule`[++=++__<format>__]::\n \tSpecify how differences in submodules are shown.  When specifying\n-\t`--submodule=short` the 'short' format is used.  This format just\n+\t`--submodule=short` the `short` format is used.  This format just\n \tshows the names of the commits at the beginning and end of the range.\n-\tWhen `--submodule` or `--submodule=log` is specified, the 'log'\n+\tWhen `--submodule` or `--submodule=log` is specified, the `log`\n \tformat is used.  This format lists the commits in the range like\n \tlinkgit:git-submodule[1] `summary` does.  When `--submodule=diff`\n-\tis specified, the 'diff' format is used.  This format shows an\n+\tis specified, the `diff` format is used.  This format shows an\n \tinline diff of the changes in the submodule contents between the\n-\tcommit range.  Defaults to `diff.submodule` or the 'short' format\n+\tcommit range.  Defaults to `diff.submodule` or the `short` format\n \tif the config option is unset.\n \n---color[=<when>]::\n+`--color`[++=++__<when>__]::\n \tShow colored diff.\n-\t`--color` (i.e. without '=<when>') is the same as `--color=always`.\n-\t'<when>' can be one of `always`, `never`, or `auto`.\n+\t`--color` (i.e. without ++=++__<when>__) is the same as `--color=always`.\n+\t_<when>_ can be one of `always`, `never`, or `auto`.\n ifdef::git-diff[]\n \tIt can be changed by the `color.ui` and `color.diff`\n \tconfiguration settings.\n endif::git-diff[]\n \n---no-color::\n+`--no-color`::\n \tTurn off colored diff.\n ifdef::git-diff[]\n \tThis can be used to override configuration settings.\n endif::git-diff[]\n \tIt is the same as `--color=never`.\n \n---color-moved[=<mode>]::\n+`--color-moved`[++=++__<mode>__]::\n \tMoved lines of code are colored differently.\n ifdef::git-diff[]\n \tIt can be changed by the `diff.colorMoved` configuration setting.\n endif::git-diff[]\n-\tThe <mode> defaults to 'no' if the option is not given\n-\tand to 'zebra' if the option with no mode is given.\n+\tThe _<mode>_ defaults to `no` if the option is not given\n+\tand to `zebra` if the option with no mode is given.\n \tThe mode must be one of:\n +\n --\n-no::\n+`no`::\n \tMoved lines are not highlighted.\n-default::\n+`default`::\n \tIs a synonym for `zebra`. This may change to a more sensible mode\n \tin the future.\n-plain::\n+`plain`::\n \tAny line that is added in one location and was removed\n-\tin another location will be colored with 'color.diff.newMoved'.\n-\tSimilarly 'color.diff.oldMoved' will be used for removed lines\n+\tin another location will be colored with `color.diff.newMoved`.\n+\tSimilarly `color.diff.oldMoved` will be used for removed lines\n \tthat are added somewhere else in the diff. This mode picks up any\n \tmoved line, but it is not very useful in a review to determine\n \tif a block of code was moved without permutation.\n-blocks::\n+`blocks`::\n \tBlocks of moved text of at least 20 alphanumeric characters\n \tare detected greedily. The detected blocks are\n-\tpainted using either the 'color.diff.{old,new}Moved' color.\n+\tpainted using either the `color.diff.(old|new)Moved` color.\n \tAdjacent blocks cannot be told apart.\n-zebra::\n-\tBlocks of moved text are detected as in 'blocks' mode. The blocks\n-\tare painted using either the 'color.diff.{old,new}Moved' color or\n-\t'color.diff.{old,new}MovedAlternative'. The change between\n+`zebra`::\n+\tBlocks of moved text are detected as in `blocks` mode. The blocks\n+\tare painted using either the `color.diff.(old|new)Moved` color or\n+\t`color.diff.(old|new)MovedAlternative`. The change between\n \tthe two colors indicates that a new block was detected.\n-dimmed-zebra::\n-\tSimilar to 'zebra', but additional dimming of uninteresting parts\n+`dimmed-zebra`::\n+\tSimilar to `zebra`, but additional dimming of uninteresting parts\n \tof moved code is performed. The bordering lines of two adjacent\n \tblocks are considered interesting, the rest is uninteresting.\n \t`dimmed_zebra` is a deprecated synonym.\n --\n \n---no-color-moved::\n+`--no-color-moved`::\n \tTurn off move detection. This can be used to override configuration\n \tsettings. It is the same as `--color-moved=no`.\n \n---color-moved-ws=<modes>::\n+++--color-moved-ws=++__<mode>__++,++...::\n \tThis configures how whitespace is ignored when performing the\n \tmove detection for `--color-moved`.\n ifdef::git-diff[]\n@@ -419,63 +426,63 @@ endif::git-diff[]\n \tThese modes can be given as a comma separated list:\n +\n --\n-no::\n+`no`::\n \tDo not ignore whitespace when performing move detection.\n-ignore-space-at-eol::\n+`ignore-space-at-eol`::\n \tIgnore changes in whitespace at EOL.\n-ignore-space-change::\n+`ignore-space-change`::\n \tIgnore changes in amount of whitespace.  This ignores whitespace\n \tat line end, and considers all other sequences of one or\n \tmore whitespace characters to be equivalent.\n-ignore-all-space::\n+`ignore-all-space`::\n \tIgnore whitespace when comparing lines. This ignores differences\n \teven if one line has whitespace where the other line has none.\n-allow-indentation-change::\n+`allow-indentation-change`::\n \tInitially ignore any whitespace in the move detection, then\n \tgroup the moved code blocks only into a block if the change in\n \twhitespace is the same per line. This is incompatible with the\n \tother modes.\n --\n \n---no-color-moved-ws::\n+`--no-color-moved-ws`::\n \tDo not ignore whitespace when performing move detection. This can be\n \tused to override configuration settings. It is the same as\n \t`--color-moved-ws=no`.\n \n---word-diff[=<mode>]::\n-\tShow a word diff, using the <mode> to delimit changed words.\n+`--word-diff`[++=++__<mode>__]::\n+\tShow a word diff, using the _<mode>_ to delimit changed words.\n \tBy default, words are delimited by whitespace; see\n-\t`--word-diff-regex` below.  The <mode> defaults to 'plain', and\n+\t`--word-diff-regex` below.  The _<mode>_ defaults to `plain`, and\n \tmust be one of:\n +\n --\n-color::\n+`color`::\n \tHighlight changed words using only colors.  Implies `--color`.\n-plain::\n+`plain`::\n \tShow words as `[-removed-]` and `{+added+}`.  Makes no\n \tattempts to escape the delimiters if they appear in the input,\n \tso the output may be ambiguous.\n-porcelain::\n+`porcelain`::\n \tUse a special line-based format intended for script\n \tconsumption.  Added/removed/unchanged runs are printed in the\n \tusual unified diff format, starting with a `+`/`-`/` `\n \tcharacter at the beginning of the line and extending to the\n \tend of the line.  Newlines in the input are represented by a\n \ttilde `~` on a line of its own.\n-none::\n+`none`::\n \tDisable word diff again.\n --\n +\n Note that despite the name of the first mode, color is used to\n highlight the changed parts in all modes if enabled.\n \n---word-diff-regex=<regex>::\n-\tUse <regex> to decide what a word is, instead of considering\n+++--word-diff-regex=++__<regex>__::\n+\tUse _<regex>_ to decide what a word is, instead of considering\n \truns of non-whitespace to be a word.  Also implies\n \t`--word-diff` unless it was already enabled.\n +\n Every non-overlapping match of the\n-<regex> is considered a word.  Anything between these matches is\n+_<regex>_ is considered a word.  Anything between these matches is\n considered whitespace and ignored(!) for the purposes of finding\n differences.  You may want to append `|[^[:space:]]` to your regular\n expression to make sure that it matches all non-whitespace characters.\n@@ -490,20 +497,20 @@ linkgit:gitattributes[5] or linkgit:git-config[1].  Giving it explicitly\n overrides any diff driver or configuration setting.  Diff drivers\n override configuration settings.\n \n---color-words[=<regex>]::\n+`--color-words`[++=++__<regex>__]::\n \tEquivalent to `--word-diff=color` plus (if a regex was\n-\tspecified) `--word-diff-regex=<regex>`.\n+\tspecified) ++--word-diff-regex=++__<regex>__.\n endif::git-format-patch[]\n \n---no-renames::\n+`--no-renames`::\n \tTurn off rename detection, even when the configuration\n \tfile gives the default to do so.\n \n---[no-]rename-empty::\n+`--`[`no-`]`rename-empty`::\n \tWhether to use empty blobs as rename source.\n \n ifndef::git-format-patch[]\n---check::\n+`--check`::\n \tWarn if changes introduce conflict markers or whitespace errors.\n \tWhat are considered whitespace errors is controlled by `core.whitespace`\n \tconfiguration.  By default, trailing whitespaces (including\n@@ -511,9 +518,9 @@ ifndef::git-format-patch[]\n \tthat is immediately followed by a tab character inside the\n \tinitial indent of the line are considered whitespace errors.\n \tExits with non-zero status if problems are found. Not compatible\n-\twith --exit-code.\n+\twith `--exit-code`.\n \n---ws-error-highlight=<kind>::\n+++--ws-error-highlight=++__<kind>__::\n \tHighlight whitespace errors in the `context`, `old` or `new`\n \tlines of the diff.  Multiple values are separated by comma,\n \t`none` resets previous values, `default` reset the list to\n@@ -525,30 +532,30 @@ ifndef::git-format-patch[]\n \n endif::git-format-patch[]\n \n---full-index::\n+`--full-index`::\n \tInstead of the first handful of characters, show the full\n \tpre- and post-image blob object names on the \"index\"\n \tline when generating patch format output.\n \n---binary::\n+`--binary`::\n \tIn addition to `--full-index`, output a binary diff that\n \tcan be applied with `git-apply`.\n ifndef::git-format-patch[]\n \tImplies `--patch`.\n endif::git-format-patch[]\n \n---abbrev[=<n>]::\n+`--abbrev`[++=++__<n>__]::\n \tInstead of showing the full 40-byte hexadecimal object\n \tname in diff-raw format output and diff-tree header\n-\tlines, show the shortest prefix that is at least '<n>'\n+\tlines, show the shortest prefix that is at least _<n>_\n \thexdigits long that uniquely refers the object.\n \tIn diff-patch output format, `--full-index` takes higher\n \tprecedence, i.e. if `--full-index` is specified, full blob\n \tnames will be shown regardless of `--abbrev`.\n-\tNon default number of digits can be specified with `--abbrev=<n>`.\n+\tNon default number of digits can be specified with ++--abbrev=++__<n>__.\n \n--B[<n>][/<m>]::\n---break-rewrites[=[<n>][/<m>]]::\n+`-B`[_<n>_][++/++__<m>__]::\n+`--break-rewrites`[`=`[_<n>_][++/++__<m>__]]::\n \tBreak complete rewrite changes into pairs of delete and\n \tcreate. This serves two purposes:\n +\n@@ -556,22 +563,22 @@ It affects the way a change that amounts to a total rewrite of a file\n not as a series of deletion and insertion mixed together with a very\n few lines that happen to match textually as the context, but as a\n single deletion of everything old followed by a single insertion of\n-everything new, and the number `m` controls this aspect of the -B\n+everything new, and the number _<m>_ controls this aspect of the -B\n option (defaults to 60%). `-B/70%` specifies that less than 30% of the\n original should remain in the result for Git to consider it a total\n rewrite (i.e. otherwise the resulting patch will be a series of\n deletion and insertion mixed together with context lines).\n +\n-When used with -M, a totally-rewritten file is also considered as the\n-source of a rename (usually -M only considers a file that disappeared\n-as the source of a rename), and the number `n` controls this aspect of\n-the -B option (defaults to 50%). `-B20%` specifies that a change with\n+When used with `-M`, a totally-rewritten file is also considered as the\n+source of a rename (usually `-M` only considers a file that disappeared\n+as the source of a rename), and the number _<n>_ controls this aspect of\n+the `-B` option (defaults to 50%). `-B20%` specifies that a change with\n addition and deletion compared to 20% or more of the file's size are\n eligible for being picked up as a possible source of a rename to\n another file.\n \n--M[<n>]::\n---find-renames[=<n>]::\n+`-M`[_<n>_]::\n+`--find-renames`[++=++__<n>__]::\n ifndef::git-log[]\n \tDetect renames.\n endif::git-log[]\n@@ -580,7 +587,7 @@ ifdef::git-log[]\n \tFor following files across renames while traversing history, see\n \t`--follow`.\n endif::git-log[]\n-\tIf `n` is specified, it is a threshold on the similarity\n+\tIf _<n>_ is specified, it is a threshold on the similarity\n \tindex (i.e. amount of addition/deletions compared to the\n \tfile's size). For example, `-M90%` means Git should consider a\n \tdelete/add pair to be a rename if more than 90% of the file\n@@ -590,12 +597,12 @@ endif::git-log[]\n \tthe same as `-M5%`.  To limit detection to exact renames, use\n \t`-M100%`.  The default similarity index is 50%.\n \n--C[<n>]::\n---find-copies[=<n>]::\n+`-C`[_<n>_]::\n+`--find-copies`[++=++__<n>__]::\n \tDetect copies as well as renames.  See also `--find-copies-harder`.\n-\tIf `n` is specified, it has the same meaning as for `-M<n>`.\n+\tIf _<n>_ is specified, it has the same meaning as for ++-M++__<n>__.\n \n---find-copies-harder::\n+`--find-copies-harder`::\n \tFor performance reasons, by default, `-C` option finds copies only\n \tif the original file of the copy was modified in the same\n \tchangeset.  This flag makes the command\n@@ -604,8 +611,8 @@ endif::git-log[]\n \tprojects, so use it with caution.  Giving more than one\n \t`-C` option has the same effect.\n \n--D::\n---irreversible-delete::\n+`-D`::\n+`--irreversible-delete`::\n \tOmit the preimage for deletes, i.e. print only the header but not\n \tthe diff between the preimage and `/dev/null`. The resulting patch\n \tis not meant to be applied with `patch` or `git apply`; this is\n@@ -617,7 +624,7 @@ endif::git-log[]\n When used together with `-B`, omit also the preimage in the deletion part\n of a delete/create pair.\n \n--l<num>::\n+++-l++__<num>__::\n \tThe `-M` and `-C` options involve some preliminary steps that\n \tcan detect subsets of renames/copies cheaply, followed by an\n \texhaustive fallback portion that compares all remaining\n@@ -627,11 +634,11 @@ of a delete/create pair.\n \tdestinations, this exhaustive check is O(N^2).  This option\n \tprevents the exhaustive portion of rename/copy detection from\n \trunning if the number of source/destination files involved\n-\texceeds the specified number.  Defaults to diff.renameLimit.\n+\texceeds the specified number.  Defaults to `diff.renameLimit`.\n \tNote that a value of 0 is treated as unlimited.\n \n ifndef::git-format-patch[]\n---diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]::\n+`--diff-filter=`[(`A`|`C`|`D`|`M`|`R`|`T`|`U`|`X`|`B`)...[_*_]]::\n \tSelect only files that are Added (`A`), Copied (`C`),\n \tDeleted (`D`), Modified (`M`), Renamed (`R`), have their\n \ttype (i.e. regular file, symlink, submodule, ...) changed (`T`),\n@@ -649,9 +656,9 @@ Also, these upper-case letters can be downcased to exclude.  E.g.\n Note that not all diffs can feature all types. For instance, copied and\n renamed entries cannot appear if detection for those types is disabled.\n \n--S<string>::\n+++-S++__<string>__::\n \tLook for differences that change the number of occurrences of\n-\tthe specified string (i.e. addition/deletion) in a file.\n+\tthe specified _<string>_ (i.e. addition/deletion) in a file.\n \tIntended for the scripter's use.\n +\n It is useful when you're looking for an exact block of code (like a\n@@ -662,12 +669,12 @@ very first version of the block.\n +\n Binary files are searched as well.\n \n--G<regex>::\n+++-G++__<regex>__::\n \tLook for differences whose patch text contains added/removed\n-\tlines that match <regex>.\n+\tlines that match _<regex>_.\n +\n-To illustrate the difference between `-S<regex> --pickaxe-regex` and\n-`-G<regex>`, consider a commit with the following diff in the same\n+To illustrate the difference between ++-S++__<regex>__ `--pickaxe-regex` and\n+++-G++__<regex>__, consider a commit with the following diff in the same\n file:\n +\n ----\n@@ -686,7 +693,7 @@ filter will be ignored.\n See the 'pickaxe' entry in linkgit:gitdiffcore[7] for more\n information.\n \n---find-object=<object-id>::\n+++--find-object=++__<object-id>__::\n \tLook for differences that change the number of occurrences of\n \tthe specified object. Similar to `-S`, just the argument is different\n \tin that it doesn't search for a specific string but for a specific\n@@ -695,25 +702,25 @@ information.\n The object can be a blob or a submodule commit. It implies the `-t` option in\n `git-log` to also find trees.\n \n---pickaxe-all::\n+`--pickaxe-all`::\n \tWhen `-S` or `-G` finds a change, show all the changes in that\n \tchangeset, not just the files that contain the change\n-\tin <string>.\n+\tin _<string>_.\n \n---pickaxe-regex::\n-\tTreat the <string> given to `-S` as an extended POSIX regular\n+`--pickaxe-regex`::\n+\tTreat the _<string>_ given to `-S` as an extended POSIX regular\n \texpression to match.\n \n endif::git-format-patch[]\n \n--O<orderfile>::\n+++-O++__<orderfile>__::\n \tControl the order in which files appear in the output.\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 +\n The output order is determined by the order of glob patterns in\n-<orderfile>.\n+_<orderfile>_.\n All files with pathnames that match the first pattern are output\n first, all files with pathnames that match the second pattern (but not\n the first) are output next, and so on.\n@@ -724,7 +731,7 @@ If multiple pathnames have the same rank (they match the same pattern\n but no earlier patterns), their output order relative to each other is\n the normal order.\n +\n-<orderfile> is parsed as follows:\n+_<orderfile>_ is parsed as follows:\n +\n --\n  - Blank lines are ignored, so they can be used as separators for\n@@ -738,106 +745,106 @@ the normal order.\n --\n +\n Patterns have the same syntax and semantics as patterns used for\n-fnmatch(3) without the FNM_PATHNAME flag, except a pathname also\n+`fnmatch`(3) without the `FNM_PATHNAME` flag, except a pathname also\n matches a pattern if removing any number of the final pathname\n components matches the pattern.  For example, the pattern \"`foo*bar`\"\n matches \"`fooasdfbar`\" and \"`foo/bar/baz/asdf`\" but not \"`foobarx`\".\n \n---skip-to=<file>::\n---rotate-to=<file>::\n-\tDiscard the files before the named <file> from the output\n+++--skip-to=++__<file>__::\n+++--rotate-to=++__<file>__::\n+\tDiscard the files before the named _<file>_ from the output\n \t(i.e. 'skip to'), or move them to the end of the output\n \t(i.e. 'rotate to').  These options were invented primarily for the use\n \tof the `git difftool` command, and may not be very useful\n \totherwise.\n \n ifndef::git-format-patch[]\n--R::\n+`-R`::\n \tSwap two inputs; that is, show differences from index or\n \ton-disk file to tree contents.\n endif::git-format-patch[]\n \n---relative[=<path>]::\n---no-relative::\n+`--relative`[++=++__<path>__]::\n+`--no-relative`::\n \tWhen run from a subdirectory of the project, it can be\n \ttold to exclude changes outside the directory and show\n \tpathnames relative to it with this option.  When you are\n \tnot in a subdirectory (e.g. in a bare repository), you\n \tcan name which subdirectory to make the output relative\n-\tto by giving a <path> as an argument.\n+\tto by giving a _<path>_ as an argument.\n \t`--no-relative` can be used to countermand both `diff.relative` config\n \toption and previous `--relative`.\n \n--a::\n---text::\n+`-a`::\n+`--text`::\n \tTreat all files as text.\n \n---ignore-cr-at-eol::\n+`--ignore-cr-at-eol`::\n \tIgnore carriage-return at the end of line when doing a comparison.\n \n---ignore-space-at-eol::\n+`--ignore-space-at-eol`::\n \tIgnore changes in whitespace at EOL.\n \n--b::\n---ignore-space-change::\n+`-b`::\n+`--ignore-space-change`::\n \tIgnore changes in amount of whitespace.  This ignores whitespace\n \tat line end, and considers all other sequences of one or\n \tmore whitespace characters to be equivalent.\n \n--w::\n---ignore-all-space::\n+`-w`::\n+`--ignore-all-space`::\n \tIgnore whitespace when comparing lines.  This ignores\n \tdifferences even if one line has whitespace where the other\n \tline has none.\n \n---ignore-blank-lines::\n+`--ignore-blank-lines`::\n \tIgnore changes whose lines are all blank.\n \n--I<regex>::\n---ignore-matching-lines=<regex>::\n-\tIgnore changes whose all lines match <regex>.  This option may\n+++-I++__<regex>__::\n+++--ignore-matching-lines=++__<regex>__::\n+\tIgnore changes whose all lines match _<regex>_.  This option may\n \tbe specified more than once.\n \n---inter-hunk-context=<lines>::\n-\tShow the context between diff hunks, up to the specified number\n+++--inter-hunk-context=++__<number>__::\n+\tShow the context between diff hunks, up to the specified _<number>_\n \tof lines, thereby fusing hunks that are close to each other.\n \tDefaults to `diff.interHunkContext` or 0 if the config option\n \tis unset.\n \n--W::\n---function-context::\n+`-W`::\n+`--function-context`::\n \tShow whole function as context lines for each change.\n \tThe function names are determined in the same way as\n-\t`git diff` works out patch hunk headers (see 'Defining a\n-\tcustom hunk-header' in linkgit:gitattributes[5]).\n+\t`git diff` works out patch hunk headers (see \"Defining a\n+\tcustom hunk-header\" in linkgit:gitattributes[5]).\n \n ifndef::git-format-patch[]\n ifndef::git-log[]\n---exit-code::\n-\tMake the program exit with codes similar to diff(1).\n+`--exit-code`::\n+\tMake the program exit with codes similar to `diff`(1).\n \tThat is, it exits with 1 if there were differences and\n \t0 means no differences.\n \n---quiet::\n+`--quiet`::\n \tDisable all output of the program. Implies `--exit-code`.\n \tDisables execution of external diff helpers whose exit code\n \tis not trusted, i.e. their respective configuration option\n-\t`diff.trustExitCode` or `diff.<driver>.trustExitCode` or\n+\t`diff.trustExitCode` or ++diff.++__<driver>__++.trustExitCode++ or\n \tenvironment variable `GIT_EXTERNAL_DIFF_TRUST_EXIT_CODE` is\n \tfalse.\n endif::git-log[]\n endif::git-format-patch[]\n \n---ext-diff::\n+`--ext-diff`::\n \tAllow an external diff helper to be executed. If you set an\n \texternal diff driver with linkgit:gitattributes[5], you need\n \tto use this option with linkgit:git-log[1] and friends.\n \n---no-ext-diff::\n+`--no-ext-diff`::\n \tDisallow external diff drivers.\n \n---textconv::\n---no-textconv::\n+`--textconv`::\n+`--no-textconv`::\n \tAllow (or disallow) external text conversion filters to be run\n \twhen comparing binary files. See linkgit:gitattributes[5] for\n \tdetails. Because textconv filters are typically a one-way\n@@ -847,42 +854,42 @@ endif::git-format-patch[]\n \tlinkgit:git-log[1], but not for linkgit:git-format-patch[1] or\n \tdiff plumbing commands.\n \n---ignore-submodules[=<when>]::\n-\tIgnore changes to submodules in the diff generation. <when> can be\n-\teither \"none\", \"untracked\", \"dirty\" or \"all\", which is the default.\n-\tUsing \"none\" will consider the submodule modified when it either contains\n+`--ignore-submodules`[++=++__<when>__]::\n+\tIgnore changes to submodules in the diff generation. _<when>_ can be\n+\teither `none`, `untracked`, `dirty` or `all`, which is the default.\n+\tUsing `none` will consider the submodule modified when it either contains\n \tuntracked or modified files or its HEAD differs from the commit recorded\n \tin the superproject and can be used to override any settings of the\n-\t'ignore' option in linkgit:git-config[1] or linkgit:gitmodules[5]. When\n-\t\"untracked\" is used submodules are not considered dirty when they only\n+\t`ignore` option in linkgit:git-config[1] or linkgit:gitmodules[5]. When\n+\t`untracked` is used submodules are not considered dirty when they only\n \tcontain untracked content (but they are still scanned for modified\n-\tcontent). Using \"dirty\" ignores all changes to the work tree of submodules,\n+\tcontent). Using `dirty` ignores all changes to the work tree of submodules,\n \tonly changes to the commits stored in the superproject are shown (this was\n-\tthe behavior until 1.7.0). Using \"all\" hides all changes to submodules.\n+\tthe behavior until 1.7.0). Using `all` hides all changes to submodules.\n \n---src-prefix=<prefix>::\n-\tShow the given source prefix instead of \"a/\".\n+++--src-prefix=++__<prefix>__::\n+\tShow the given source _<prefix>_ instead of \"a/\".\n \n---dst-prefix=<prefix>::\n-\tShow the given destination prefix instead of \"b/\".\n+++--dst-prefix=++__<prefix>__::\n+\tShow the given destination _<prefix>_ instead of \"b/\".\n \n---no-prefix::\n+`--no-prefix`::\n \tDo not show any source or destination prefix.\n \n---default-prefix::\n+`--default-prefix`::\n \tUse the default source and destination prefixes (\"a/\" and \"b/\").\n \tThis overrides configuration variables such as `diff.noprefix`,\n \t`diff.srcPrefix`, `diff.dstPrefix`, and `diff.mnemonicPrefix`\n \t(see `git-config`(1)).\n \n---line-prefix=<prefix>::\n-\tPrepend an additional prefix to every line of output.\n+++--line-prefix=++__<prefix>__::\n+\tPrepend an additional _<prefix>_ to every line of output.\n \n---ita-invisible-in-index::\n-\tBy default entries added by \"git add -N\" appear as an existing\n-\tempty file in \"git diff\" and a new file in \"git diff --cached\".\n-\tThis option makes the entry appear as a new file in \"git diff\"\n-\tand non-existent in \"git diff --cached\". This option could be\n+`--ita-invisible-in-index`::\n+\tBy default entries added by `git add -N` appear as an existing\n+\tempty file in `git diff` and a new file in `git diff --cached`.\n+\tThis option makes the entry appear as a new file in `git diff`\n+\tand non-existent in `git diff --cached`. This option could be\n \treverted with `--ita-visible-in-index`. Both options are\n \texperimental and could be removed in future.\n \n-- \ngitgitgadget\n\n"},{"id":"500039","messageId":"3c475a2ee4ecfb79a1174fa693b592ebafdbf5f9.1722801936.git.gitgitgadget@gmail.com","threadId":"61899","inReplyTo":"pull.1769.git.1722801936.gitgitgadget@gmail.com","subject":"[PATCH 4/5] doc: git-diff: apply format changes to diff-generate-patch","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-08-04T20:05:35Z","receivedAt":"2024-08-04T20:05:44Z","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/diff-generate-patch.txt | 48 ++++++++++++++-------------\n 1 file changed, 25 insertions(+), 23 deletions(-)\n\ndiff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-generate-patch.txt\nindex 4b5aa5c2e04..0a4dc761e64 100644\n--- a/Documentation/diff-generate-patch.txt\n+++ b/Documentation/diff-generate-patch.txt\n@@ -14,7 +14,7 @@ You can customize the creation of patch text via the\n `GIT_EXTERNAL_DIFF` and the `GIT_DIFF_OPTS` environment variables\n (see linkgit:git[1]), and the `diff` attribute (see linkgit:gitattributes[5]).\n \n-What the -p option produces is slightly different from the traditional\n+What the `-p` option produces is slightly different from the traditional\n diff format:\n \n 1.   It is preceded by a \"git diff\" header that looks like this:\n@@ -30,20 +30,21 @@ name of the source file of the rename/copy and the name of\n the file that the rename/copy produces, respectively.\n \n 2.   It is followed by one or more extended header lines:\n-\n-       old mode <mode>\n-       new mode <mode>\n-       deleted file mode <mode>\n-       new file mode <mode>\n-       copy from <path>\n-       copy to <path>\n-       rename from <path>\n-       rename to <path>\n-       similarity index <number>\n-       dissimilarity index <number>\n-       index <hash>..<hash> <mode>\n +\n-File modes are printed as 6-digit octal numbers including the file type\n+[synopsis]\n+old mode <mode>\n+new mode <mode>\n+deleted file mode <mode>\n+new file mode <mode>\n+copy from <path>\n+copy to <path>\n+rename from <path>\n+rename to <path>\n+similarity index <number>\n+dissimilarity index <number>\n+index <hash>..<hash> <mode>\n++\n+File modes _<mode>_ are printed as 6-digit octal numbers including the file type\n and file permission bits.\n +\n Path names in extended headers do not include the `a/` and `b/` prefixes.\n@@ -56,7 +57,7 @@ files, while 100% dissimilarity means that no line from the old\n file made it into the new one.\n +\n The index line includes the blob object names before and after the change.\n-The <mode> is included if the file mode does not change; otherwise,\n+The _<mode>_ is included if the file mode does not change; otherwise,\n separate lines indicate the old and the new mode.\n \n 3.  Pathnames with \"unusual\" characters are quoted as explained for\n@@ -134,17 +135,18 @@ or like this (when the `--cc` option is used):\n \n 2.   It is followed by one or more extended header lines\n      (this example shows a merge with two parents):\n-\n-       index <hash>,<hash>..<hash>\n-       mode <mode>,<mode>..<mode>\n-       new file mode <mode>\n-       deleted file mode <mode>,<mode>\n +\n-The `mode <mode>,<mode>..<mode>` line appears only if at least one of\n-the <mode> is different from the rest. Extended headers with\n+[synopsis]\n+index <hash>,<hash>`..`<hash>\n+mode <mode>,<mode>`..`<mode>\n+new file mode <mode>\n+deleted file mode <mode>,<mode>\n++\n+The `mode` __<mode>__++,++__<mode>__++..++__<mode>__ line appears only if at least one of\n+the _<mode>_ is different from the rest. Extended headers with\n information about detected content movement (renames and\n copying detection) are designed to work with the diff of two\n-<tree-ish> and are not used by combined diff format.\n+_<tree-ish>_ and are not used by combined diff format.\n \n 3.   It is followed by a two-line from-file/to-file header:\n \n-- \ngitgitgadget\n\n"},{"id":"500040","messageId":"acb5bdda9046c5a49c6bb29bd822d8a09356a7ab.1722801936.git.gitgitgadget@gmail.com","threadId":"61899","inReplyTo":"pull.1769.git.1722801936.gitgitgadget@gmail.com","subject":"[PATCH 5/5] doc: git-diff: apply format changes to config part","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-08-04T20:05:36Z","receivedAt":"2024-08-04T20:05:44Z","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/config/diff.txt | 160 +++++++++++++++++-----------------\n 1 file changed, 80 insertions(+), 80 deletions(-)\n\ndiff --git a/Documentation/config/diff.txt b/Documentation/config/diff.txt\nindex 190bda17e51..bdfc9e3c79a 100644\n--- a/Documentation/config/diff.txt\n+++ b/Documentation/config/diff.txt\n@@ -1,18 +1,18 @@\n-diff.autoRefreshIndex::\n-\tWhen using 'git diff' to compare with work tree\n+`diff.autoRefreshIndex`::\n+\tWhen using `git diff` to compare with work tree\n \tfiles, do not consider stat-only changes as changed.\n \tInstead, silently run `git update-index --refresh` to\n \tupdate the cached stat information for paths whose\n \tcontents in the work tree match the contents in the\n \tindex.  This option defaults to true.  Note that this\n-\taffects only 'git diff' Porcelain, and not lower level\n-\t'diff' commands such as 'git diff-files'.\n+\taffects only `git diff` Porcelain, and not lower level\n+\t`diff` commands such as '`git diff-files`.\n \n-diff.dirstat::\n+`diff.dirstat`::\n \tA comma separated list of `--dirstat` parameters specifying the\n \tdefault behavior of the `--dirstat` option to linkgit:git-diff[1]\n \tand friends. The defaults can be overridden on the command line\n-\t(using `--dirstat=<param1,param2,...>`). The fallback defaults\n+\t(using ++--dirstat=++__<param1>__++,++__<param2>__...). The fallback defaults\n \t(when not changed by `diff.dirstat`) are `changes,noncumulative,3`.\n \tThe following parameters are available:\n +\n@@ -41,7 +41,7 @@ diff.dirstat::\n \tNote that when using `cumulative`, the sum of the percentages\n \treported may exceed 100%. The default (non-cumulative) behavior can\n \tbe specified with the `noncumulative` parameter.\n-<limit>;;\n+_<limit>_;;\n \tAn integer parameter specifies a cut-off percent (3% by default).\n \tDirectories contributing less than this percentage of the changes\n \tare not shown in the output.\n@@ -52,57 +52,57 @@ directories with less than 10% of the total amount of changed files,\n and accumulating child directory counts in the parent directories:\n `files,10,cumulative`.\n \n-diff.statNameWidth::\n-\tLimit the width of the filename part in --stat output. If set, applies\n-\tto all commands generating --stat output except format-patch.\n+`diff.statNameWidth`::\n+\tLimit the width of the filename part in `--stat` output. If set, applies\n+\tto all commands generating `--stat` output except `format-patch`.\n \n-diff.statGraphWidth::\n-\tLimit the width of the graph part in --stat output. If set, applies\n-\tto all commands generating --stat output except format-patch.\n+`diff.statGraphWidth`::\n+\tLimit the width of the graph part in `--stat` output. If set, applies\n+\tto all commands generating `--stat` output except `format-patch`.\n \n-diff.context::\n-\tGenerate diffs with <n> lines of context instead of the default\n-\tof 3. This value is overridden by the -U option.\n+`diff.context`::\n+\tGenerate diffs with _<n>_ lines of context instead of the default\n+\tof 3. This value is overridden by the `-U` option.\n \n-diff.interHunkContext::\n+`diff.interHunkContext`::\n \tShow the context between diff hunks, up to the specified number\n \tof lines, thereby fusing the hunks that are close to each other.\n \tThis value serves as the default for the `--inter-hunk-context`\n \tcommand line option.\n \n-diff.external::\n+`diff.external`::\n \tIf this config variable is set, diff generation is not\n \tperformed using the internal diff machinery, but using the\n-\tgiven command.  Can be overridden with the `GIT_EXTERNAL_DIFF'\n+\tgiven command.  Can be overridden with the `GIT_EXTERNAL_DIFF`\n \tenvironment variable.  The command is called with parameters\n \tas described under \"git Diffs\" in linkgit:git[1].  Note: if\n \tyou want to use an external diff program only on a subset of\n \tyour files, you might want to use linkgit:gitattributes[5] instead.\n \n-diff.trustExitCode::\n+`diff.trustExitCode`::\n \tIf this boolean value is set to true then the\n \t`diff.external` command is expected to return exit code\n \t0 if it considers the input files to be equal or 1 if it\n-\tconsiders them to be different, like `diff(1)`.\n-\tIf it is set to false, which is the default, then the command\n-\tis expected to return exit code 0 regardless of equality.\n+\tconsiders them to be different, like `diff`(1).\n+\tIf it is set to `false`, which is the default, then the command\n+\tis expected to return exit code `0` regardless of equality.\n \tAny other exit code causes Git to report a fatal error.\n \n-diff.ignoreSubmodules::\n-\tSets the default value of --ignore-submodules. Note that this\n-\taffects only 'git diff' Porcelain, and not lower level 'diff'\n-\tcommands such as 'git diff-files'. 'git checkout'\n-\tand 'git switch' also honor\n+`diff.ignoreSubmodules`::\n+\tSets the default value of `--ignore-submodules`. Note that this\n+\taffects only `git diff` Porcelain, and not lower level `diff`\n+\tcommands such as `git diff-files`. `git checkout`\n+\tand `git switch` also honor\n \tthis setting when reporting uncommitted changes. Setting it to\n-\t'all' disables the submodule summary normally shown by 'git commit'\n-\tand 'git status' when `status.submoduleSummary` is set unless it is\n-\toverridden by using the --ignore-submodules command-line option.\n-\tThe 'git submodule' commands are not affected by this setting.\n+\t`all` disables the submodule summary normally shown by `git commit`\n+\tand `git status` when `status.submoduleSummary` is set unless it is\n+\toverridden by using the `--ignore-submodules` command-line option.\n+\tThe `git submodule` commands are not affected by this setting.\n \tBy default this is set to untracked so that any untracked\n \tsubmodules are ignored.\n \n-diff.mnemonicPrefix::\n-\tIf set, 'git diff' uses a prefix pair that is different from the\n+`diff.mnemonicPrefix`::\n+\tIf set, `git diff` uses a prefix pair that is different from the\n \tstandard \"a/\" and \"b/\" depending on what is being compared.  When\n \tthis configuration is in effect, reverse diff output also swaps\n \tthe order of the prefixes:\n@@ -117,102 +117,102 @@ diff.mnemonicPrefix::\n `git diff --no-index a b`;;\n \tcompares two non-git things (1) and (2).\n \n-diff.noPrefix::\n-\tIf set, 'git diff' does not show any source or destination prefix.\n+`diff.noPrefix`::\n+\tIf set, `git diff` does not show any source or destination prefix.\n \n-diff.srcPrefix::\n-\tIf set, 'git diff' uses this source prefix. Defaults to \"a/\".\n+`diff.srcPrefix`::\n+\tIf set, `git diff` uses this source prefix. Defaults to \"a/\".\n \n-diff.dstPrefix::\n-\tIf set, 'git diff' uses this destination prefix. Defaults to \"b/\".\n+`diff.dstPrefix`::\n+\tIf set, `git diff` uses this destination prefix. Defaults to \"b/\".\n \n-diff.relative::\n-\tIf set to 'true', 'git diff' does not show changes outside of the directory\n+`diff.relative`::\n+\tIf set to `true`, `git diff` does not show changes outside of the directory\n \tand show pathnames relative to the current directory.\n \n-diff.orderFile::\n+`diff.orderFile`::\n \tFile indicating how to order files within a diff.\n-\tSee the '-O' option to linkgit:git-diff[1] for details.\n+\tSee the `-O` option to linkgit:git-diff[1] for details.\n \tIf `diff.orderFile` is a relative pathname, it is treated as\n \trelative to the top of the working tree.\n \n-diff.renameLimit::\n+`diff.renameLimit`::\n \tThe number of files to consider in the exhaustive portion of\n-\tcopy/rename detection; equivalent to the 'git diff' option\n+\tcopy/rename detection; equivalent to the `git diff` option\n \t`-l`.  If not set, the default value is currently 1000.  This\n \tsetting has no effect if rename detection is turned off.\n \n-diff.renames::\n-\tWhether and how Git detects renames.  If set to \"false\",\n-\trename detection is disabled. If set to \"true\", basic rename\n-\tdetection is enabled.  If set to \"copies\" or \"copy\", Git will\n+`diff.renames`::\n+\tWhether and how Git detects renames.  If set to `false`,\n+\trename detection is disabled. If set to `true`, basic rename\n+\tdetection is enabled.  If set to `copies` or `copy`, Git will\n \tdetect copies, as well.  Defaults to true.  Note that this\n-\taffects only 'git diff' Porcelain like linkgit:git-diff[1] and\n+\taffects only `git diff` Porcelain like linkgit:git-diff[1] and\n \tlinkgit:git-log[1], and not lower level commands such as\n \tlinkgit:git-diff-files[1].\n \n-diff.suppressBlankEmpty::\n+`diff.suppressBlankEmpty`::\n \tA boolean to inhibit the standard behavior of printing a space\n-\tbefore each empty output line. Defaults to false.\n+\tbefore each empty output line. Defaults to `false`.\n \n-diff.submodule::\n+`diff.submodule`::\n \tSpecify the format in which differences in submodules are\n-\tshown.  The \"short\" format just shows the names of the commits\n-\tat the beginning and end of the range. The \"log\" format lists\n+\tshown.  The `short` format just shows the names of the commits\n+\tat the beginning and end of the range. The `log` format lists\n \tthe commits in the range like linkgit:git-submodule[1] `summary`\n-\tdoes. The \"diff\" format shows an inline diff of the changed\n-\tcontents of the submodule. Defaults to \"short\".\n+\tdoes. The `diff` format shows an inline diff of the changed\n+\tcontents of the submodule. Defaults to `short`.\n \n-diff.wordRegex::\n+`diff.wordRegex`::\n \tA POSIX Extended Regular Expression used to determine what is a \"word\"\n \twhen performing word-by-word difference calculations.  Character\n \tsequences that match the regular expression are \"words\", all other\n \tcharacters are *ignorable* whitespace.\n \n-diff.<driver>.command::\n+++diff.++__<driver>__++.command++::\n \tThe custom diff driver command.  See linkgit:gitattributes[5]\n \tfor details.\n \n-diff.<driver>.trustExitCode::\n+++diff.++__<driver>__++.trustExitCode++::\n \tIf this boolean value is set to true then the\n-\t`diff.<driver>.command` command is expected to return exit code\n+\t++diff.++__<driver>__++.command++ command is expected to return exit code\n \t0 if it considers the input files to be equal or 1 if it\n-\tconsiders them to be different, like `diff(1)`.\n+\tconsiders them to be different, like `diff`(1).\n \tIf it is set to false, which is the default, then the command\n \tis expected to return exit code 0 regardless of equality.\n \tAny other exit code causes Git to report a fatal error.\n \n-diff.<driver>.xfuncname::\n+++diff.++__<driver>__++.xfuncname++::\n \tThe regular expression that the diff driver should use to\n \trecognize the hunk header.  A built-in pattern may also be used.\n \tSee linkgit:gitattributes[5] for details.\n \n-diff.<driver>.binary::\n-\tSet this option to true to make the diff driver treat files as\n+++diff.++__<driver>__++.binary++::\n+\tSet this option to `true` to make the diff driver treat files as\n \tbinary.  See linkgit:gitattributes[5] for details.\n \n-diff.<driver>.textconv::\n+++diff.++__<driver>__++.textconv++::\n \tThe command that the diff driver should call to generate the\n \ttext-converted version of a file.  The result of the\n \tconversion is used to generate a human-readable diff.  See\n \tlinkgit:gitattributes[5] for details.\n \n-diff.<driver>.wordRegex::\n+++diff.++__<driver>__++.wordRegex++::\n \tThe regular expression that the diff driver should use to\n \tsplit words in a line.  See linkgit:gitattributes[5] for\n \tdetails.\n \n-diff.<driver>.cachetextconv::\n+++diff.++__<driver>__++.cachetextconv++::\n \tSet this option to true to make the diff driver cache the text\n \tconversion outputs.  See linkgit:gitattributes[5] for details.\n \n include::../mergetools-diff.txt[]\n \n-diff.indentHeuristic::\n+`diff.indentHeuristic`::\n \tSet this option to `false` to disable the default heuristics\n \tthat shift diff hunk boundaries to make patches easier to read.\n \n-diff.algorithm::\n+`diff.algorithm`::\n \tChoose a diff algorithm.  The variants are as follows:\n +\n --\n@@ -229,23 +229,23 @@ diff.algorithm::\n --\n +\n \n-diff.wsErrorHighlight::\n+`diff.wsErrorHighlight`::\n \tHighlight whitespace errors in the `context`, `old` or `new`\n \tlines of the diff.  Multiple values are separated by comma,\n \t`none` resets previous values, `default` reset the list to\n \t`new` and `all` is a shorthand for `old,new,context`.  The\n \twhitespace errors are colored with `color.diff.whitespace`.\n-\tThe command line option `--ws-error-highlight=<kind>`\n+\tThe command line option ++--ws-error-highlight=++__<kind>__\n \toverrides this setting.\n \n-diff.colorMoved::\n-\tIf set to either a valid `<mode>` or a true value, moved lines\n+`diff.colorMoved`::\n+\tIf set to either a valid _<mode>_ or a true value, moved lines\n \tin a diff are colored differently, for details of valid modes\n-\tsee '--color-moved' in linkgit:git-diff[1]. If simply set to\n-\ttrue the default color mode will be used. When set to false,\n+\tsee `--color-moved` in linkgit:git-diff[1]. If simply set to\n+\t`true` the default color mode will be used. When set to `false`,\n \tmoved lines are not colored.\n \n-diff.colorMovedWS::\n+`diff.colorMovedWS`::\n \tWhen moved lines are colored using e.g. the `diff.colorMoved` setting,\n-\tthis option controls the `<mode>` how spaces are treated.\n-\tFor details of valid modes see '--color-moved-ws' in linkgit:git-diff[1].\n+\tthis option controls the _<mode>_ how spaces are treated.\n+\tFor details of valid modes see `--color-moved-ws` in linkgit:git-diff[1].\n-- \ngitgitgadget\n"},{"id":"500044","messageId":"5ef4a7bd-3b9f-4e71-9a22-e22012f815ce@kdbg.org","threadId":"61899","inReplyTo":"3c475a2ee4ecfb79a1174fa693b592ebafdbf5f9.1722801936.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 4/5] doc: git-diff: apply format changes to diff-generate-patch","fromName":"Johannes Sixt","fromEmail":"j6t@kdbg.org","sentAt":"2024-08-05T05:53:19Z","receivedAt":"2024-08-05T05:53:35Z","isPatch":true,"sender":{"key":"j6t@kdbg.org","avatar":"https://avatars.githubusercontent.com/u/14810926?v=4"},"body":"Am 04.08.24 um 22:05 schrieb Jean-Noël Avila via GitGitGadget:\n> @@ -134,17 +135,18 @@ or like this (when the `--cc` option is used):\n>  \n>  2.   It is followed by one or more extended header lines\n>       (this example shows a merge with two parents):\n> -\n> -       index <hash>,<hash>..<hash>\n> -       mode <mode>,<mode>..<mode>\n> -       new file mode <mode>\n> -       deleted file mode <mode>,<mode>\n>  +\n> -The `mode <mode>,<mode>..<mode>` line appears only if at least one of\n> -the <mode> is different from the rest. Extended headers with\n> +[synopsis]\n> +index <hash>,<hash>`..`<hash>\n> +mode <mode>,<mode>`..`<mode>\n> +new file mode <mode>\n> +deleted file mode <mode>,<mode>\n> ++\n> +The `mode` __<mode>__++,++__<mode>__++..++__<mode>__ line appears only if at least one of\n> +the _<mode>_ is different from the rest. Extended headers with\n\nI've a strong aversion to the formatting that this series applies,\nbecause it introduces many (IMHO) unnecessary punctuation that\nvandalizes the perfectly readable plain text. And this hunk now shows\nwhere it goes too far. These lines under the new [synopsis] header just\naren't syopsis; they are comamnd output. The updated version abuses a\nsemantic token to achieve syntactic highlighting.\n\nTo me this series looks too much like \"we must adapt to the tool\" when\nthe correct stance should be \"the tool must adapt to us\". If the tool\n(one of asciidoc and asciidoctor, I presume) does not cooperate well\nwith out documents, then it is the tool that must be changed, not our\ndocuments.\n\nI understand that some compromises are needed, but with this extent of\nchanges we give in to a sub-par tool too far.\n\nJust my 2c.\n\n-- Hannes\n\n"},{"id":"500047","messageId":"ZrCXK8AmGSFwyqI4@tanuki","threadId":"61899","inReplyTo":"515ddbf1dceacc0c186e3d31c13e76a5afc6c45f.1722801936.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 1/5] doc: git-diff: apply new documentation guidelines","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-08-05T09:11:07Z","receivedAt":"2024-08-05T09:11:12Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Sun, Aug 04, 2024 at 08:05:32PM +0000, Jean-Noël Avila via GitGitGadget wrote:\n> From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n> \n\nNit: please provide a summary of what adaptations you made. It would\ncertainly help the reviewer to learn about the recently-introduced\n`[synopsis]` style and why/since when we use backticks and underscores\nfor formatting.\n\nThe same also applies to subsequent commits, providing some pointers\nwould certainly help an unknowing reviewer such as myself.\n\n> @@ -225,11 +225,12 @@ CONFIGURATION\n>  \n>  include::includes/cmd-config-section-all.txt[]\n>  \n> +:git-diff: 1\n>  include::config/diff.txt[]\n>  \n>  SEE ALSO\n>  --------\n> -diff(1),\n> +`diff`(1),\n\nThis one looks curious to me. Why is this item formatted differently\nthan the next three? I would have expected it to be formatted as\nsomething like linkgit:git-diff[1] instead of `diff`(1)`.\n\nPatrick\n\n>  linkgit:git-difftool[1],\n>  linkgit:git-log[1],\n>  linkgit:gitdiffcore[7],\n> -- \n> gitgitgadget\n> \n> \n"},{"id":"500096","messageId":"xmqqcymn3qc8.fsf@gitster.g","threadId":"61899","inReplyTo":"5ef4a7bd-3b9f-4e71-9a22-e22012f815ce@kdbg.org","subject":"Re: [PATCH 4/5] doc: git-diff: apply format changes to diff-generate-patch","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-08-05T16:08:07Z","receivedAt":"2024-08-05T16:08:10Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Johannes Sixt <j6t@kdbg.org> writes:\n\n> I've a strong aversion to the formatting that this series applies,\n> because it introduces many (IMHO) unnecessary punctuation that\n> vandalizes the perfectly readable plain text. And this hunk now shows\n> where it goes too far. These lines under the new [synopsis] header just\n> aren't syopsis; they are comamnd output. The updated version abuses a\n> semantic token to achieve syntactic highlighting.\n>\n> To me this series looks too much like \"we must adapt to the tool\" when\n> the correct stance should be \"the tool must adapt to us\". If the tool\n> (one of asciidoc and asciidoctor, I presume) does not cooperate well\n> with out documents, then it is the tool that must be changed, not our\n> documents.\n>\n> I understand that some compromises are needed, but with this extent of\n> changes we give in to a sub-par tool too far.\n\nThanks for placing this into words a lot better than how I could\nhave done.  I share the same feeling.\n"},{"id":"500119","messageId":"5803739.DvuYhMxLoT@cayenne","threadId":"61899","inReplyTo":"ZrCXK8AmGSFwyqI4@tanuki","subject":"Re: [PATCH 1/5] doc: git-diff: apply new documentation guidelines","fromName":"Jean-Noël AVILA","fromEmail":"jn.avila@free.fr","sentAt":"2024-08-05T18:51:21Z","receivedAt":"2024-08-05T19:02:58Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"On Monday, 5 August 2024 11:11:07 CEST Patrick Steinhardt wrote:\n> On Sun, Aug 04, 2024 at 08:05:32PM +0000, Jean-Noël Avila via GitGitGadget \nwrote:\n> > From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n> > \n> \n> Nit: please provide a summary of what adaptations you made. It would\n> certainly help the reviewer to learn about the recently-introduced\n> `[synopsis]` style and why/since when we use backticks and underscores\n> for formatting.\n> \n> The same also applies to subsequent commits, providing some pointers\n> would certainly help an unknowing reviewer such as myself.\n> \n\nThanks for the remark. The context is effectively missing, so I'll restate it.\n\n> > @@ -225,11 +225,12 @@ CONFIGURATION\n> >  \n> >  include::includes/cmd-config-section-all.txt[]\n> >  \n> > +:git-diff: 1\n> >  include::config/diff.txt[]\n> >  \n> >  SEE ALSO\n> >  --------\n> > -diff(1),\n> > +`diff`(1),\n> \n> This one looks curious to me. Why is this item formatted differently\n> than the next three? I would have expected it to be formatted as\n> something like linkgit:git-diff[1] instead of `diff`(1)`.\n> \n\nHere we are referring to the 'diff' command, not git-diff. That is why we don't \nuse the linkgit macro (which is used to generate cross links for html output).\n\nStill, the general format of a reference to a man-page is to put the command \nname in bold, which our filters get by backquoting. \n\n> Patrick\n> \n> >  linkgit:git-difftool[1],\n> >  linkgit:git-log[1],\n> >  linkgit:gitdiffcore[7],\n> \n\nThanks\n\n\n"},{"id":"500123","messageId":"8448316.NyiUUSuA9g@cayenne","threadId":"61899","inReplyTo":"5ef4a7bd-3b9f-4e71-9a22-e22012f815ce@kdbg.org","subject":"Re: [PATCH 4/5] doc: git-diff: apply format changes to diff-generate-patch","fromName":"Jean-Noël AVILA","fromEmail":"jn.avila@free.fr","sentAt":"2024-08-05T20:12:08Z","receivedAt":"2024-08-05T20:12:12Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"On Monday, 5 August 2024 07:53:19 CEST Johannes Sixt wrote:\n> Am 04.08.24 um 22:05 schrieb Jean-Noël Avila via GitGitGadget:\n> > @@ -134,17 +135,18 @@ or like this (when the `--cc` option is used):\n> >  \n> >  2.   It is followed by one or more extended header lines\n> >       (this example shows a merge with two parents):\n> > -\n> > -       index <hash>,<hash>..<hash>\n> > -       mode <mode>,<mode>..<mode>\n> > -       new file mode <mode>\n> > -       deleted file mode <mode>,<mode>\n> >  +\n> > -The `mode <mode>,<mode>..<mode>` line appears only if at least one of\n> > -the <mode> is different from the rest. Extended headers with\n> > +[synopsis]\n> > +index <hash>,<hash>`..`<hash>\n> > +mode <mode>,<mode>`..`<mode>\n> > +new file mode <mode>\n> > +deleted file mode <mode>,<mode>\n> > ++\n> > +The `mode` __<mode>__++,++__<mode>__++..++__<mode>__ line appears only if \nat least one of\n> > +the _<mode>_ is different from the rest. Extended headers with\n> \n> I've a strong aversion to the formatting that this series applies,\n> because it introduces many (IMHO) unnecessary punctuation that\n> vandalizes the perfectly readable plain text. And this hunk now shows\n> where it goes too far. These lines under the new [synopsis] header just\n> aren't syopsis; they are comamnd output. The updated version abuses a\n> semantic token to achieve syntactic highlighting.\n> \n> To me this series looks too much like \"we must adapt to the tool\" when\n> the correct stance should be \"the tool must adapt to us\". If the tool\n> (one of asciidoc and asciidoctor, I presume) does not cooperate well\n> with out documents, then it is the tool that must be changed, not our\n> documents.\n> \n> I understand that some compromises are needed, but with this extent of\n> changes we give in to a sub-par tool too far.\n> \n> Just my 2c.\n> \n> -- Hannes\n> \n> \n\nHello,\n\nI was half expecting this kind of reactions. First there are some remarks on \nyour remarks.\n \n * You think the markup is unnecessary. To me, it is critical in order to make \nthe documentation output a little more meaningful. My experience as a \ntranslator is that there's a great lack of consistency in the vocabulary, the \ngrammar styles, the typesetting and the cross-references of the pages. On top \nof that, they are clearly not user-oriented. Overall, the joke about how \ncryptic the man-pages of Git are is not coming from nowhere. There's no one to \nblame: we are all developers doing our best, but we are not technical writers \ndedicated to this project.\n * The fact that the source of the pages should be \"perfectly readable\" is a \nmoot argument. Fair enough, it is not the objective to make it impossible to \nunderstand, but in the end, this is not what is consumed: these pages are \ncompiled into other formats where the markup has been translated into styling. \nI suspect some writers are not thinking when quoting text, that this is not a \nquotation but an inline formatting command. But this is markup, and sometimes, \nit cannot  be removed of the way.\n * I converted the lines to synopsis because there are placeholders in them. \nThese lines are presented as an example but they are neither. This is another \nexample of communication impedance,  where the presented text is not what it \nis described as, and requires from the reader to interpret what the writer was \nthinking and forgot to make clear to a newcomer.\n\n\nAs for the \"need to adapt to the tool\", for block formatting, I tried to get \nsomething bearable (the synopis style); I'd really like something similar for \ninline formatting but my asciidoc/asciidoctor Fu requires an upgrade in order \nto make it happen. As it seems to be too epidermic, I'll try to cook something \nanyway and keep being open to any proposition.\n\nIn the mean time, a proper editor setup (syntax highlighting and fontification \n, two panels with one showing the compiled output) can alleviate your pain. \n\nJN\n\n\n"},{"id":"500157","messageId":"ZrHCVmQvVH9MzpJ0@tanuki","threadId":"61899","inReplyTo":"5803739.DvuYhMxLoT@cayenne","subject":"Re: [PATCH 1/5] doc: git-diff: apply new documentation guidelines","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-08-06T06:27:34Z","receivedAt":"2024-08-06T06:27:38Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Mon, Aug 05, 2024 at 08:51:21PM +0200, Jean-Noël AVILA wrote:\n> On Monday, 5 August 2024 11:11:07 CEST Patrick Steinhardt wrote:\n> > On Sun, Aug 04, 2024 at 08:05:32PM +0000, Jean-Noël Avila via GitGitGadget \n> wrote:\n> > > @@ -225,11 +225,12 @@ CONFIGURATION\n> > >  \n> > >  include::includes/cmd-config-section-all.txt[]\n> > >  \n> > > +:git-diff: 1\n> > >  include::config/diff.txt[]\n> > >  \n> > >  SEE ALSO\n> > >  --------\n> > > -diff(1),\n> > > +`diff`(1),\n> > \n> > This one looks curious to me. Why is this item formatted differently\n> > than the next three? I would have expected it to be formatted as\n> > something like linkgit:git-diff[1] instead of `diff`(1)`.\n> > \n> \n> Here we are referring to the 'diff' command, not git-diff. That is why we don't \n> use the linkgit macro (which is used to generate cross links for html output).\n> \n> Still, the general format of a reference to a man-page is to put the command \n> name in bold, which our filters get by backquoting. \n\nOh, that makes sense of course. I totally forgot that there's a world\noutside of Git. Thanks for the clarification!\n\nPatrick\n"},{"id":"500351","messageId":"4617471.LvFx2qVVIh@cayenne","threadId":"61899","inReplyTo":"xmqqcymn3qc8.fsf@gitster.g","subject":"Re: [RFC] formatting macro","fromName":"Jean-Noël AVILA","fromEmail":"jn.avila@free.fr","sentAt":"2024-08-07T20:43:28Z","receivedAt":"2024-08-07T20:51:20Z","isPatch":false,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"On Monday, 5 August 2024 18:08:07 CEST Junio C Hamano wrote:\n> Johannes Sixt <j6t@kdbg.org> writes:\n> \n> > I've a strong aversion to the formatting that this series applies,\n> > because it introduces many (IMHO) unnecessary punctuation that\n> > vandalizes the perfectly readable plain text. And this hunk now shows\n> > where it goes too far. These lines under the new [synopsis] header just\n> > aren't syopsis; they are comamnd output. The updated version abuses a\n> > semantic token to achieve syntactic highlighting.\n> >\n> > To me this series looks too much like \"we must adapt to the tool\" when\n> > the correct stance should be \"the tool must adapt to us\". If the tool\n> > (one of asciidoc and asciidoctor, I presume) does not cooperate well\n> > with out documents, then it is the tool that must be changed, not our\n> > documents.\n> >\n> > I understand that some compromises are needed, but with this extent of\n> > changes we give in to a sub-par tool too far.\n> \n> Thanks for placing this into words a lot better than how I could\n> have done.  I share the same feeling.\n> \n\nI'm working on a form of macro that would work almost the same way as the \nsynopsis paragraph. You would have some markup, but it would be surrounding \nthe text to typeset: \n\ns:[\"--ignore-matching-lines=<regex>\"]\n\nIn this snippet the macro part (which is recognized by a regex) is  s:[ ]\nThe inside part is managed the same. If you need additional markup, it is \npossible:\n\ns:[\"<commit1>`...`<commit2>\"] to have the three dots rendered as <code>, \nbecause they are part of the tokens.\n\nSquare brackets are possible inside the double-quotes:\ns:[\"--ignore-submodules[=<when>]\"]\n\nIs this something that wouldn't repel you?\n\nBest regards,\n\nJN\n\n\n"},{"id":"500615","messageId":"f44c253d-9b37-451d-902d-486adb8e3d72@kdbg.org","threadId":"61899","inReplyTo":"4617471.LvFx2qVVIh@cayenne","subject":"Re: [RFC] formatting macro","fromName":"Johannes Sixt","fromEmail":"j6t@kdbg.org","sentAt":"2024-08-12T06:35:39Z","receivedAt":"2024-08-12T06:35:56Z","isPatch":false,"sender":{"key":"j6t@kdbg.org","avatar":"https://avatars.githubusercontent.com/u/14810926?v=4"},"body":"Am 07.08.24 um 22:43 schrieb Jean-Noël AVILA:\n> On Monday, 5 August 2024 18:08:07 CEST Junio C Hamano wrote:\n>> Johannes Sixt <j6t@kdbg.org> writes:\n>>\n>>> I've a strong aversion to the formatting that this series applies,\n>>> because it introduces many (IMHO) unnecessary punctuation that\n>>> vandalizes the perfectly readable plain text. And this hunk now shows\n>>> where it goes too far. These lines under the new [synopsis] header just\n>>> aren't syopsis; they are comamnd output. The updated version abuses a\n>>> semantic token to achieve syntactic highlighting.\n>>>\n>>> To me this series looks too much like \"we must adapt to the tool\" when\n>>> the correct stance should be \"the tool must adapt to us\". If the tool\n>>> (one of asciidoc and asciidoctor, I presume) does not cooperate well\n>>> with out documents, then it is the tool that must be changed, not our\n>>> documents.\n>>>\n>>> I understand that some compromises are needed, but with this extent of\n>>> changes we give in to a sub-par tool too far.\n>>\n>> Thanks for placing this into words a lot better than how I could\n>> have done.  I share the same feeling.\n>>\n> \n> I'm working on a form of macro that would work almost the same way as the \n> synopsis paragraph. You would have some markup, but it would be surrounding \n> the text to typeset: \n> \n> s:[\"--ignore-matching-lines=<regex>\"]\n> \n> In this snippet the macro part (which is recognized by a regex) is  s:[ ]\n> The inside part is managed the same. If you need additional markup, it is \n> possible:\n> \n> s:[\"<commit1>`...`<commit2>\"] to have the three dots rendered as <code>, \n> because they are part of the tokens.\n> \n> Square brackets are possible inside the double-quotes:\n> s:[\"--ignore-submodules[=<when>]\"]\n> \n> Is this something that wouldn't repel you?\n\nYou argued elsewhere in this thread:\n\n>  * The fact that the source of the pages should be \"perfectly readable\" is a \n> moot argument. Fair enough, it is not the objective to make it impossible to \n> understand, but in the end, this is not what is consumed: these pages are \n> compiled into other formats where the markup has been translated into styling. \n\nI buy this argument, in particular, since not even I read the plain text\nfiles, but use the rendered version.\n\nI would like tone down my harsh opposition to mild opposition. IMO, it\nshould still be easy to *write* the documentation. It should not be\nnecessary that authors remember to use macros all over the place.\n\nAnd I still think that we should not introduce macros just to please all\nrenderers. Let's just pick the one renderer that can do the job best. If\nit means that some distribution cannot render the documentation\nperfectly themselves (Debian? I don't know), they can always use the\npre-rendered version that Junio kindly produces.\n\n-- Hannes\n"},{"id":"500641","messageId":"xmqqwmkl7ol4.fsf@gitster.g","threadId":"61899","inReplyTo":"f44c253d-9b37-451d-902d-486adb8e3d72@kdbg.org","subject":"Re: [RFC] formatting macro","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-08-12T15:22:47Z","receivedAt":"2024-08-12T15:22:58Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Johannes Sixt <j6t@kdbg.org> writes:\n\n>> Square brackets are possible inside the double-quotes:\n>> s:[\"--ignore-submodules[=<when>]\"]\n>> \n>> Is this something that wouldn't repel you?\n>\n> You argued elsewhere in this thread:\n>\n>>  * The fact that the source of the pages should be \"perfectly readable\" is a \n>> moot argument. Fair enough, it is not the objective to make it impossible to \n>> understand, but in the end, this is not what is consumed: these pages are \n>> compiled into other formats where the markup has been translated into styling. \n>\n> I buy this argument, in particular, since not even I read the plain text\n> files, but use the rendered version.\n\nFWIW, I do read the plain text files, and rarely if ever use the\nHTML version, except when checking the effect of changes to the\nmark-up.\n\n> I would like tone down my harsh opposition to mild opposition. IMO, it\n> should still be easy to *write* the documentation. It should not be\n> necessary that authors remember to use macros all over the place.\n\nYeah, s:[...] does repel me, but also I do not think it is sensible\nto claim that we confortably edit the \"source\" form that we find it\nhard to read.\n\n> And I still think that we should not introduce macros just to please all\n> renderers. Let's just pick the one renderer that can do the job best. If\n> it means that some distribution cannot render the documentation\n> perfectly themselves (Debian? I don't know), they can always use the\n> pre-rendered version that Junio kindly produces.\n\nWhat Junio uses \"Debian? I don't know\" that cannot render the\ndocumentation ;-)?\n"},{"id":"500820","messageId":"3596897.iIbC2pHGDl@cayenne","threadId":"61899","inReplyTo":"f44c253d-9b37-451d-902d-486adb8e3d72@kdbg.org","subject":"Re: [RFC] formatting macro","fromName":"Jean-Noël AVILA","fromEmail":"jn.avila@free.fr","sentAt":"2024-08-13T20:42:26Z","receivedAt":"2024-08-13T20:42:44Z","isPatch":false,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"On Monday, 12 August 2024 08:35:39 CEST Johannes Sixt wrote:\n> Am 07.08.24 um 22:43 schrieb Jean-Noël AVILA:\n> \n> I would like tone down my harsh opposition to mild opposition. IMO, it\n> should still be easy to *write* the documentation. It should not be\n> necessary that authors remember to use macros all over the place.\n\nThe purpose of this series is to clarify the formatting rules for keywords and \nplaceholders, and to uniformly apply them, so that the readers can relate the \nmeaning of what they are reading with the visual cues in the text.  The more \nuniform the typesetting, the less surprised the reader, the smaller the \ncommunication impedance.\n\nThis requirement makes the documentation *less* easy to write, for sure.\nIt is no question of forcing authors to use the formatting macro everywhere. \nAs explained in the Guildelines V3 of the series, the macro is introduced in \norder to remove the most hairy forms where manually doing the formatting would \nlead to difficult to read/write sequences. I bet most writers will remember and \nuse the s macro when they want to typeset something like \n--ignore-submodules[=<when>]\n\nAs an added benefit, we can also simplify some existing parts, for instance see \nthe ones in urls.txt.\n\n> \n> And I still think that we should not introduce macros just to please all\n> renderers. Let's just pick the one renderer that can do the job best. If\n> it means that some distribution cannot render the documentation\n> perfectly themselves (Debian? I don't know), they can always use the\n> pre-rendered version that Junio kindly produces.\n\nI do not understand how the renderer could solve the issue of typesetting the \n\"good part\" in the place of the writers. The macro is there to mechanize the \ntypesetting of selected parts, but it is up to the writers to define what is a \nkeyword and what is a placeholder in their prose. Please note also that using \nproper placeholder differentiating and typesetting should have the side-effect \nof making the prose lighter, by removing the need to express which placeholder \nwe are talking about.\n\nTo me, Asciidoc strikes a good balance for a tool that makes it easy to write \nsimple things and not too complicated to write more complex ones. It is also \ncustomizable for specific needs, which is handy for our use case.  I am not \naware of an existing renderer that would do the job really best. What do you \nhave in mind?\n\nJN\n\n\n\n\n\n\n"},{"id":"507059","messageId":"pull.1769.v2.git.1731343985.gitgitgadget@gmail.com","threadId":"61899","inReplyTo":"pull.1769.git.1722801936.gitgitgadget@gmail.com","subject":"[PATCH v2 0/5] doc: git diff reformatting","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-11-11T16:53:00Z","receivedAt":"2024-11-11T16:53:09Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"This is the continuation of the editing of the manpages to reflect the new\nformatting rules.\n\nNote that this patch makes use of the synopsis paragraph styling and needs\nto be applied above ja/doc-synopsis-markup. As the dots can be primarily\ninterpreted as a grammar sign for repetition, here the dots which are part\nof the synopsis are manually forced to verbatim.\n\nJean-Noël Avila (5):\n  doc: git-diff: apply new documentation guidelines\n  doc: git-diff: apply format changes to diff-options\n  doc: git-diff: apply format changes to diff-format\n  doc: git-diff: apply format changes to diff-generate-patch\n  doc: git-diff: apply format changes to config part\n\n Documentation/config/diff.txt         | 163 +++++-----\n Documentation/diff-format.txt         |  42 +--\n Documentation/diff-generate-patch.txt |  44 +--\n Documentation/diff-options.txt        | 423 +++++++++++++-------------\n Documentation/git-diff.txt            | 103 +++----\n 5 files changed, 390 insertions(+), 385 deletions(-)\n\n\nbase-commit: facbe4f633e4ad31e641f64617bc88074c659959\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-1769%2Fjnavila%2Fgit_diff_new-v2\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1769/jnavila/git_diff_new-v2\nPull-Request: https://github.com/gitgitgadget/git/pull/1769\n\nRange-diff vs v1:\n\n 1:  515ddbf1dce ! 1:  c104bd50b64 doc: git-diff: apply new documentation guidelines\n     @@ Documentation/git-diff.txt: git-diff - Show changes between commits, commit and\n      +git diff [<options>] [<commit>] [--] [<path>...]\n      +git diff [<options>] --cached [--merge-base] [<commit>] [--] [<path>...]\n      +git diff [<options>] [--merge-base] <commit> [<commit>...] <commit> [--] [<path>...]\n     -+git diff [<options>] <commit>`...`<commit> [--] [<path>...]\n     ++git diff [<options>] <commit>...<commit> [--] [<path>...]\n      +git diff [<options>] <blob> <blob>\n      +git diff [<options>] --no-index [--] <path> <path>\n       \n     @@ Documentation/git-diff.txt: between the index and a tree, changes between two tr\n       files on disk.\n       \n      -'git diff' [<options>] [--] [<path>...]::\n     -+`git diff` [_<options>_] [`--`] [_<path>_...]::\n     ++`git diff [<options>] [--] [<path>...]`::\n       \n       \tThis form is to view the changes you made relative to\n       \tthe index (staging area for the next commit).  In other\n     @@ Documentation/git-diff.txt: files on disk.\n       \tstage these changes by using linkgit:git-add[1].\n       \n      -'git diff' [<options>] --no-index [--] <path> <path>::\n     -+`git diff` [_<options>_] `--no-index` [`--`] _<path>_ _<path>_::\n     ++`git diff [<options>] --no-index [--] <path> <path>`::\n       \n       \tThis form is to compare the given two paths on the\n       \tfilesystem.  You can omit the `--no-index` option when\n     @@ Documentation/git-diff.txt: files on disk.\n       \tcontrolled by Git. This form implies `--exit-code`.\n       \n      -'git diff' [<options>] --cached [--merge-base] [<commit>] [--] [<path>...]::\n     -+`git diff` [_<options>_] `--cached` [`--merge-base`] [_<commit>_] [`--`] [_<path>_...]::\n     ++`git diff [<options>] --cached [--merge-base] [<commit>] [--] [<path>...]`::\n       \n       \tThis form is to view the changes you staged for the next\n      -\tcommit relative to the named <commit>.  Typically you\n     @@ Documentation/git-diff.txt: files on disk.\n       `git diff --cached $(git merge-base A HEAD)`.\n       \n      -'git diff' [<options>] [--merge-base] <commit> [--] [<path>...]::\n     -+`git diff` [_<options>_] [`--merge-base`] _<commit>_ [`--`] [_<path>_...]::\n     ++`git diff [<options>] [--merge-base] <commit> [--] [<path>...]`::\n       \n       \tThis form is to view the changes you have in your\n      -\tworking tree relative to the named <commit>.  You can\n     @@ Documentation/git-diff.txt: files on disk.\n       `git diff $(git merge-base A HEAD)`.\n       \n      -'git diff' [<options>] [--merge-base] <commit> <commit> [--] [<path>...]::\n     -+`git diff` [_<options>_] [`--merge-base`] _<commit>_ _<commit>_ [`--`] [_<path>_...]::\n     ++`git diff [<options>] [--merge-base] <commit> <commit> [--] [<path>...]`::\n       \n       \tThis is to view the changes between two arbitrary\n      -\t<commit>.\n     @@ Documentation/git-diff.txt: files on disk.\n       `git diff $(git merge-base A B) B`.\n       \n      -'git diff' [<options>] <commit> <commit>... <commit> [--] [<path>...]::\n     -+`git diff` [_<options>_] _<commit>_ __<commit>__++...++__<commit>__ [`--`] [_<path>_...]::\n     ++`git diff [<options>] <commit> <commit>...<commit> [--] [<path>...]`::\n       \n       \tThis form is to view the results of a merge commit.  The first\n      -\tlisted <commit> must be the merge itself; the remaining two or\n      +\tlisted _<commit>_ must be the merge itself; the remaining two or\n       \tmore commits should be its parents.  Convenient ways to produce\n     - \tthe desired set of revisions are to use the suffixes `^@` and\n     +-\tthe desired set of revisions are to use the suffixes `^@` and\n      -\t`^!`.  If A is a merge commit, then `git diff A A^@`,\n     ++\tthe desired set of revisions are to use the suffixes `@` and\n      +\t`^!`.  If `A` is a merge commit, then `git diff A A^@`,\n       \t`git diff A^!` and `git show A` all give the same combined diff.\n       \n      -'git diff' [<options>] <commit>..<commit> [--] [<path>...]::\n     -+`git diff` [_<options>_] __<commit>__++..++__<commit>__ [`--`] [_<path>_...]::\n     ++`git diff [<options>] <commit>..<commit> [--] [<path>...]`::\n       \n       \tThis is synonymous to the earlier form (without the `..`) for\n      -\tviewing the changes between two arbitrary <commit>.  If <commit> on\n     @@ Documentation/git-diff.txt: files on disk.\n      +\tusing `HEAD` instead.\n       \n      -'git diff' [<options>] <commit>\\...<commit> [--] [<path>...]::\n     -+`git diff` [_<options>_] __<commit>__++...++__<commit>__ [`--`] [_<path>_...]::\n     ++`git diff [<options>] <commit>...<commit> [--] [<path>...]`::\n       \n       \tThis form is to view the changes on the branch containing\n      -\tand up to the second <commit>, starting at a common ancestor\n     @@ Documentation/git-diff.txt: files on disk.\n      -and the range notations (`<commit>..<commit>` and\n      -`<commit>...<commit>`) do not mean a range as defined in the\n      +However, `diff` is about comparing two _endpoints_, not ranges,\n     -+and the range notations (__<commit>__++..++__<commit>__ and\n     -+__<commit>__++...++__<commit>__) do not mean a range as defined in the\n     ++and the range notations (`<commit>..<commit>` and `<commit>...<commit>`)\n     ++do not mean a range as defined in the\n       \"SPECIFYING RANGES\" section in linkgit:gitrevisions[7].\n       \n      -'git diff' [<options>] <blob> <blob>::\n     -+`git diff` [_<options>_] _<blob>_ _<blob>_::\n     ++`git diff [<options>] <blob> <blob>`::\n       \n       \tThis form is to view the differences between the raw\n       \tcontents of two blob objects.\n 2:  c1e7d6afb50 ! 2:  129763c2aae doc: git-diff: apply format changes to diff-options\n     @@ Documentation/diff-options.txt: endif::git-format-patch[]\n       \n       --diff-merges=<format>::\n       \tSpecify diff format to be used for merge commits. Default is\n     -@@ Documentation/diff-options.txt: ifdef::git-log[]\n     - The following formats are supported:\n     - +\n     - --\n     --off, none::\n     -+off::\n     -+none::\n     +@@ Documentation/diff-options.txt: The following formats are supported:\n     + off, none::\n       \tDisable output of diffs for merge commits. Useful to override\n       \timplied value.\n      -+\n     --on, m::\n      +\n     -+on::\n     -+m::\n     + on, m::\n       \tMake diff output for merge commits to be shown in the default\n       \tformat. The default format can be changed using\n       \t`log.diffMerges` configuration variable, whose default value\n       \tis `separate`.\n      -+\n     --first-parent, 1::\n      +\n     -+first-parent::\n     -+1::\n     + first-parent, 1::\n       \tShow full diff with respect to first parent. This is the same\n       \tformat as `--patch` produces for non-merge commits.\n      -+\n     @@ Documentation/diff-options.txt: ifdef::git-log[]\n       \tShow full diff with respect to each of parents.\n       \tSeparate log entry and diff is generated for each parent.\n      -+\n     --combined, c::\n      +\n     -+combined::\n     -+c::\n     + combined, c::\n       \tShow differences from each of the parents to the merge\n       \tresult simultaneously instead of showing pairwise diff between\n       \ta parent and the result one at a time. Furthermore, it lists\n       \tonly files which were modified from all parents.\n      -+\n     --dense-combined, cc::\n      +\n     -+dense-combined::\n     -+cc::\n     + dense-combined, cc::\n       \tFurther compress output produced by `--diff-merges=combined`\n       \tby omitting uninteresting hunks whose contents in the parents\n       \thave only two variants and the merge result picks one of them\n       \twithout modification.\n      -+\n     --remerge, r::\n      +\n     -+remerge::\n     -+r::\n     + remerge, r::\n       \tRemerge two-parent merge commits to create a temporary tree\n       \tobject--potentially containing files with conflict markers\n     - \tand such.  A diff is then shown between that temporary tree\n      @@ Documentation/diff-options.txt: documented).\n       --\n       \n       --combined-all-paths::\n      -\tThis flag causes combined diffs (used for merge commits) to\n     -+\tcause combined diffs (used for merge commits) to\n     ++\tCause combined diffs (used for merge commits) to\n       \tlist the name of the file from all parents.  It thus only has\n       \teffect when `--diff-merges=[dense-]combined` is in use, and\n       \tis likely only useful if filename changes are detected (i.e.\n     @@ Documentation/diff-options.txt: documented).\n      --U<n>::\n      ---unified=<n>::\n      -\tGenerate diffs with <n> lines of context instead of\n     -+++-U++__<n>__::\n     -+++--unified=++__<n>__::\n     ++`-U<n>`::\n     ++`--unified=<n>`::\n      +\tGenerate diffs with _<n>_ lines of context instead of\n       \tthe usual three.\n       ifndef::git-format-patch[]\n     @@ Documentation/diff-options.txt: documented).\n       endif::git-format-patch[]\n       \n      ---output=<file>::\n     --\tOutput to a specific file instead of stdout.\n     -+++--output=++__<file>__::\n     -+\tOutput to _<file>_ instead of stdout.\n     ++`--output=<file>`::\n     + \tOutput to a specific file instead of stdout.\n       \n      ---output-indicator-new=<char>::\n      ---output-indicator-old=<char>::\n      ---output-indicator-context=<char>::\n     -+++--output-indicator-new=++__<char>__::\n     -+++--output-indicator-old=++__<char>__::\n     -+++--output-indicator-context=++__<char>__::\n     ++`--output-indicator-new=<char>`::\n     ++`--output-indicator-old=<char>`::\n     ++`--output-indicator-context=<char>`::\n       \tSpecify the character used to indicate new, old or context\n      -\tlines in the generated patch. Normally they are '+', '-' and\n      +\tlines in the generated patch. Normally they are `+`, `-` and\n     @@ Documentation/diff-options.txt: endif::git-log[]\n       \tGenerate a diff using the \"histogram diff\" algorithm.\n       \n      ---anchored=<text>::\n     -+++--anchored=++__<text>__::\n     ++`--anchored=<text>`::\n       \tGenerate a diff using the \"anchored diff\" algorithm.\n       +\n       This option may be specified more than once.\n     @@ Documentation/diff-options.txt: endif::git-log[]\n       diff\" algorithm internally.\n       \n      ---diff-algorithm={patience|minimal|histogram|myers}::\n     -+`--diff-algorithm=`(`patience`|`minimal`|`histogram`|`myers`)::\n     ++`--diff-algorithm=(patience|minimal|histogram|myers)`::\n       \tChoose a diff algorithm. The variants are as follows:\n       +\n       --\n     @@ Documentation/diff-options.txt: endif::git-log[]\n      +   `histogram`;;\n       \tThis algorithm extends the patience algorithm to \"support\n       \tlow-occurrence common elements\".\n     ----\n     --+\n     -+\n     - For instance, if you configured the `diff.algorithm` variable to a\n     + --\n     +@@ Documentation/diff-options.txt: For instance, if you configured the `diff.algorithm` variable to a\n       non-default value and want to use the default one, then you\n       have to use `--diff-algorithm=default` option.\n     -+--\n       \n      ---stat[=<width>[,<name-width>[,<count>]]]::\n     -+`--stat`[++=++__<width>__[++,++__<name-width>__[++,++__<count>__]]]::\n     ++`--stat[=<width>[,<name-width>[,<count>]]]`::\n       \tGenerate a diffstat. By default, as much space as necessary\n       \twill be used for the filename part, and the rest for the graph\n       \tpart. Maximum width defaults to terminal width, or 80 columns\n     @@ Documentation/diff-options.txt: endif::git-log[]\n      -\t`diff.statGraphWidth=<width>`. Using `--stat` or\n      +\t_<width>_. The width of the filename part can be limited by\n      +\tgiving another width _<name-width>_ after a comma or by setting\n     -+\t++diff.statNameWidth=++__<name-width>__. The width of the graph part can be\n     -+\tlimited by using ++--stat-graph-width=++__<graph-width>__ or by setting\n     -+\t++diff.statGraphWidth=++__<graph-width>__. Using `--stat` or\n     ++\t`diff.statNameWidth=<name-width>`. The width of the graph part can be\n     ++\tlimited by using `--stat-graph-width=<graph-width>` or by setting\n     ++\t`diff.statGraphWidth=<graph-width>`. Using `--stat` or\n       \t`--stat-graph-width` affects all commands generating a stat graph,\n       \twhile setting `diff.statNameWidth` or `diff.statGraphWidth`\n       \tdoes not affect `git format-patch`.\n     @@ Documentation/diff-options.txt: endif::git-log[]\n      +\tBy giving a third parameter _<count>_, you can limit the output to\n      +\tthe first _<count>_ lines, followed by `...` if there are more.\n       +\n     --These parameters can also be set individually with `--stat-width=<width>`,\n     --`--stat-name-width=<name-width>` and `--stat-count=<count>`.\n     -+These parameters can also be set individually with ++--stat-width=++__<width>__,\n     -+++--stat-name-width=++__<name-width>__ and ++--stat-count=++__<count>__.\n     + These parameters can also be set individually with `--stat-width=<width>`,\n     + `--stat-name-width=<name-width>` and `--stat-count=<count>`.\n       \n      ---compact-summary::\n      +`--compact-summary`::\n     @@ Documentation/diff-options.txt: endif::git-log[]\n       \n      --X[<param1,param2,...>]::\n      ---dirstat[=<param1,param2,...>]::\n     -+`-X`[__<param>__++,++...]::\n     -+`--dirstat`[++=++__<param>__++,++...]::\n     ++`-X [<param>,...]`::\n     ++`--dirstat[=<param>,...]`::\n       \tOutput the distribution of relative amount of changes for each\n       \tsub-directory. The behavior of `--dirstat` can be customized by\n       \tpassing it a comma separated list of parameters.\n     @@ Documentation/diff-options.txt: directories with less than 10% of the total amou\n       \n      ---dirstat-by-file[=<param1,param2>...]::\n      -\tSynonym for --dirstat=files,<param1>,<param2>...\n     -+`--dirstat-by-file`[++=++__<param>__++,++...]::\n     -+\tSynonym for ++--dirstat=files,++__<param>__++,++... .\n     ++`--dirstat-by-file[=<param>,...]`::\n     ++\tSynonym for `--dirstat=files,<param>,...`.\n       \n      ---summary::\n      +`--summary`::\n     @@ Documentation/diff-options.txt: Without this option, pathnames with \"unusual\" ch\n       \tJust like `--name-only` the file names are often encoded in UTF-8.\n       \n      ---submodule[=<format>]::\n     -+`--submodule`[++=++__<format>__]::\n     ++`--submodule[=<format>]`::\n       \tSpecify how differences in submodules are shown.  When specifying\n      -\t`--submodule=short` the 'short' format is used.  This format just\n      +\t`--submodule=short` the `short` format is used.  This format just\n     @@ Documentation/diff-options.txt: Without this option, pathnames with \"unusual\" ch\n       \tif the config option is unset.\n       \n      ---color[=<when>]::\n     -+`--color`[++=++__<when>__]::\n     ++`--color[=<when>]`::\n       \tShow colored diff.\n      -\t`--color` (i.e. without '=<when>') is the same as `--color=always`.\n      -\t'<when>' can be one of `always`, `never`, or `auto`.\n     -+\t`--color` (i.e. without ++=++__<when>__) is the same as `--color=always`.\n     ++\t`--color` (i.e. without `=<when>`) is the same as `--color=always`.\n      +\t_<when>_ can be one of `always`, `never`, or `auto`.\n       ifdef::git-diff[]\n       \tIt can be changed by the `color.ui` and `color.diff`\n     @@ Documentation/diff-options.txt: Without this option, pathnames with \"unusual\" ch\n       \tIt is the same as `--color=never`.\n       \n      ---color-moved[=<mode>]::\n     -+`--color-moved`[++=++__<mode>__]::\n     ++`--color-moved[=<mode>]`::\n       \tMoved lines of code are colored differently.\n       ifdef::git-diff[]\n       \tIt can be changed by the `diff.colorMoved` configuration setting.\n     @@ Documentation/diff-options.txt: Without this option, pathnames with \"unusual\" ch\n       \tsettings. It is the same as `--color-moved=no`.\n       \n      ---color-moved-ws=<modes>::\n     -+++--color-moved-ws=++__<mode>__++,++...::\n     ++`--color-moved-ws=<mode>,...`::\n       \tThis configures how whitespace is ignored when performing the\n       \tmove detection for `--color-moved`.\n       ifdef::git-diff[]\n     @@ Documentation/diff-options.txt: endif::git-diff[]\n       \n      ---word-diff[=<mode>]::\n      -\tShow a word diff, using the <mode> to delimit changed words.\n     -+`--word-diff`[++=++__<mode>__]::\n     -+\tShow a word diff, using the _<mode>_ to delimit changed words.\n     ++`--word-diff[=<mode>]`::\n       \tBy default, words are delimited by whitespace; see\n      -\t`--word-diff-regex` below.  The <mode> defaults to 'plain', and\n      +\t`--word-diff-regex` below.  The _<mode>_ defaults to `plain`, and\n     @@ Documentation/diff-options.txt: endif::git-diff[]\n      +`color`::\n       \tHighlight changed words using only colors.  Implies `--color`.\n      -plain::\n     +-\tShow words as `[-removed-]` and `{+added+}`.  Makes no\n      +`plain`::\n     - \tShow words as `[-removed-]` and `{+added+}`.  Makes no\n     ++\tShow words as ++[-removed-]++ and ++{+added+}++.  Makes no\n       \tattempts to escape the delimiters if they appear in the input,\n       \tso the output may be ambiguous.\n      -porcelain::\n     @@ Documentation/diff-options.txt: endif::git-diff[]\n       \n      ---word-diff-regex=<regex>::\n      -\tUse <regex> to decide what a word is, instead of considering\n     -+++--word-diff-regex=++__<regex>__::\n     ++`--word-diff-regex=<regex>`::\n      +\tUse _<regex>_ to decide what a word is, instead of considering\n       \truns of non-whitespace to be a word.  Also implies\n       \t`--word-diff` unless it was already enabled.\n     @@ Documentation/diff-options.txt: linkgit:gitattributes[5] or linkgit:git-config[1\n       override configuration settings.\n       \n      ---color-words[=<regex>]::\n     -+`--color-words`[++=++__<regex>__]::\n     ++`--color-words[=<regex>]`::\n       \tEquivalent to `--word-diff=color` plus (if a regex was\n     --\tspecified) `--word-diff-regex=<regex>`.\n     -+\tspecified) ++--word-diff-regex=++__<regex>__.\n     + \tspecified) `--word-diff-regex=<regex>`.\n       endif::git-format-patch[]\n       \n      ---no-renames::\n     @@ Documentation/diff-options.txt: linkgit:gitattributes[5] or linkgit:git-config[1\n       \tfile gives the default to do so.\n       \n      ---[no-]rename-empty::\n     -+`--`[`no-`]`rename-empty`::\n     ++`--[no-]rename-empty`::\n       \tWhether to use empty blobs as rename source.\n       \n       ifndef::git-format-patch[]\n     @@ Documentation/diff-options.txt: ifndef::git-format-patch[]\n      +\twith `--exit-code`.\n       \n      ---ws-error-highlight=<kind>::\n     -+++--ws-error-highlight=++__<kind>__::\n     ++`--ws-error-highlight=<kind>`::\n       \tHighlight whitespace errors in the `context`, `old` or `new`\n       \tlines of the diff.  Multiple values are separated by comma,\n       \t`none` resets previous values, `default` reset the list to\n     @@ Documentation/diff-options.txt: ifndef::git-format-patch[]\n       endif::git-format-patch[]\n       \n      ---abbrev[=<n>]::\n     -+`--abbrev`[++=++__<n>__]::\n     ++`--abbrev[=<n>]`::\n       \tInstead of showing the full 40-byte hexadecimal object\n       \tname in diff-raw format output and diff-tree header\n      -\tlines, show the shortest prefix that is at least '<n>'\n     @@ Documentation/diff-options.txt: ifndef::git-format-patch[]\n       \tIn diff-patch output format, `--full-index` takes higher\n       \tprecedence, i.e. if `--full-index` is specified, full blob\n       \tnames will be shown regardless of `--abbrev`.\n     --\tNon default number of digits can be specified with `--abbrev=<n>`.\n     -+\tNon default number of digits can be specified with ++--abbrev=++__<n>__.\n     + \tNon default number of digits can be specified with `--abbrev=<n>`.\n       \n      --B[<n>][/<m>]::\n      ---break-rewrites[=[<n>][/<m>]]::\n     -+`-B`[_<n>_][++/++__<m>__]::\n     -+`--break-rewrites`[`=`[_<n>_][++/++__<m>__]]::\n     ++`-B[<n>][/<m>]`::\n     ++`--break-rewrites[=[<n>][/<m>]]`::\n       \tBreak complete rewrite changes into pairs of delete and\n       \tcreate. This serves two purposes:\n       +\n     @@ Documentation/diff-options.txt: It affects the way a change that amounts to a to\n       few lines that happen to match textually as the context, but as a\n       single deletion of everything old followed by a single insertion of\n      -everything new, and the number `m` controls this aspect of the -B\n     -+everything new, and the number _<m>_ controls this aspect of the -B\n     ++everything new, and the number _<m>_ controls this aspect of the `-B`\n       option (defaults to 60%). `-B/70%` specifies that less than 30% of the\n       original should remain in the result for Git to consider it a total\n       rewrite (i.e. otherwise the resulting patch will be a series of\n     @@ Documentation/diff-options.txt: It affects the way a change that amounts to a to\n       \n      --M[<n>]::\n      ---find-renames[=<n>]::\n     -+`-M`[_<n>_]::\n     -+`--find-renames`[++=++__<n>__]::\n     ++`-M[<n>]`::\n     ++`--find-renames[=<n>]`::\n       ifndef::git-log[]\n       \tDetect renames.\n       endif::git-log[]\n     @@ Documentation/diff-options.txt: endif::git-log[]\n       \n      --C[<n>]::\n      ---find-copies[=<n>]::\n     -+`-C`[_<n>_]::\n     -+`--find-copies`[++=++__<n>__]::\n     ++`-C[<n>]`::\n     ++`--find-copies[=<n>]`::\n       \tDetect copies as well as renames.  See also `--find-copies-harder`.\n      -\tIf `n` is specified, it has the same meaning as for `-M<n>`.\n     -+\tIf _<n>_ is specified, it has the same meaning as for ++-M++__<n>__.\n     ++\tIf _<n>_ is specified, it has the same meaning as for `-M<n>`.\n       \n      ---find-copies-harder::\n      +`--find-copies-harder`::\n     @@ Documentation/diff-options.txt: endif::git-log[]\n       of a delete/create pair.\n       \n      --l<num>::\n     -+++-l++__<num>__::\n     ++`-l<num>`::\n       \tThe `-M` and `-C` options involve some preliminary steps that\n       \tcan detect subsets of renames/copies cheaply, followed by an\n       \texhaustive fallback portion that compares all remaining\n     @@ Documentation/diff-options.txt: of a delete/create pair.\n       \n       ifndef::git-format-patch[]\n      ---diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]::\n     -+`--diff-filter=`[(`A`|`C`|`D`|`M`|`R`|`T`|`U`|`X`|`B`)...[_*_]]::\n     ++`--diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]`::\n       \tSelect only files that are Added (`A`), Copied (`C`),\n       \tDeleted (`D`), Modified (`M`), Renamed (`R`), have their\n       \ttype (i.e. regular file, symlink, submodule, ...) changed (`T`),\n     @@ Documentation/diff-options.txt: Also, these upper-case letters can be downcased\n       renamed entries cannot appear if detection for those types is disabled.\n       \n      --S<string>::\n     -+++-S++__<string>__::\n     ++`-S<string>`::\n       \tLook for differences that change the number of occurrences of\n      -\tthe specified string (i.e. addition/deletion) in a file.\n      +\tthe specified _<string>_ (i.e. addition/deletion) in a file.\n     @@ Documentation/diff-options.txt: very first version of the block.\n       Binary files are searched as well.\n       \n      --G<regex>::\n     -+++-G++__<regex>__::\n     ++`-G<regex>`::\n       \tLook for differences whose patch text contains added/removed\n      -\tlines that match <regex>.\n      +\tlines that match _<regex>_.\n       +\n      -To illustrate the difference between `-S<regex> --pickaxe-regex` and\n     --`-G<regex>`, consider a commit with the following diff in the same\n     -+To illustrate the difference between ++-S++__<regex>__ `--pickaxe-regex` and\n     -+++-G++__<regex>__, consider a commit with the following diff in the same\n     ++To illustrate the difference between `-S<regex>` `--pickaxe-regex` and\n     + `-G<regex>`, consider a commit with the following diff in the same\n       file:\n       +\n     - ----\n      @@ Documentation/diff-options.txt: filter will be ignored.\n       See the 'pickaxe' entry in linkgit:gitdiffcore[7] for more\n       information.\n       \n      ---find-object=<object-id>::\n     -+++--find-object=++__<object-id>__::\n     ++`--find-object=<object-id>`::\n       \tLook for differences that change the number of occurrences of\n       \tthe specified object. Similar to `-S`, just the argument is different\n       \tin that it doesn't search for a specific string but for a specific\n     @@ Documentation/diff-options.txt: information.\n       endif::git-format-patch[]\n       \n      --O<orderfile>::\n     -+++-O++__<orderfile>__::\n     ++`-O<orderfile>`::\n       \tControl the order in which files appear in the output.\n       \tThis overrides the `diff.orderFile` configuration variable\n       \t(see linkgit:git-config[1]).  To cancel `diff.orderFile`,\n     @@ Documentation/diff-options.txt: the normal order.\n      ---skip-to=<file>::\n      ---rotate-to=<file>::\n      -\tDiscard the files before the named <file> from the output\n     -+++--skip-to=++__<file>__::\n     -+++--rotate-to=++__<file>__::\n     ++`--skip-to=<file>`::\n     ++`--rotate-to=<file>`::\n      +\tDiscard the files before the named _<file>_ from the output\n       \t(i.e. 'skip to'), or move them to the end of the output\n       \t(i.e. 'rotate to').  These options were invented primarily for the use\n     @@ Documentation/diff-options.txt: the normal order.\n       \n      ---relative[=<path>]::\n      ---no-relative::\n     -+`--relative`[++=++__<path>__]::\n     ++`--relative[=<path>]`::\n      +`--no-relative`::\n       \tWhen run from a subdirectory of the project, it can be\n       \ttold to exclude changes outside the directory and show\n     @@ Documentation/diff-options.txt: the normal order.\n      --I<regex>::\n      ---ignore-matching-lines=<regex>::\n      -\tIgnore changes whose all lines match <regex>.  This option may\n     -+++-I++__<regex>__::\n     -+++--ignore-matching-lines=++__<regex>__::\n     ++\n     ++`-I<regex>`::\n     ++`--ignore-matching-lines=<regex>`::\n      +\tIgnore changes whose all lines match _<regex>_.  This option may\n       \tbe specified more than once.\n       \n      ---inter-hunk-context=<lines>::\n      -\tShow the context between diff hunks, up to the specified number\n     -+++--inter-hunk-context=++__<number>__::\n     ++`--inter-hunk-context=<number>`::\n      +\tShow the context between diff hunks, up to the specified _<number>_\n       \tof lines, thereby fusing hunks that are close to each other.\n       \tDefaults to `diff.interHunkContext` or 0 if the config option\n     @@ Documentation/diff-options.txt: endif::git-format-patch[]\n      -\tIgnore changes to submodules in the diff generation. <when> can be\n      -\teither \"none\", \"untracked\", \"dirty\" or \"all\", which is the default.\n      -\tUsing \"none\" will consider the submodule modified when it either contains\n     -+`--ignore-submodules`[++=++__<when>__]::\n     -+\tIgnore changes to submodules in the diff generation. _<when>_ can be\n     -+\teither `none`, `untracked`, `dirty` or `all`, which is the default.\n     +-\tuntracked or modified files or its HEAD differs from the commit recorded\n     ++\n     ++`--ignore-submodules[=(none|untracked|dirty|all)]`::\n     ++\tIgnore changes to submodules in the diff generation. `all` is the default.\n      +\tUsing `none` will consider the submodule modified when it either contains\n     - \tuntracked or modified files or its HEAD differs from the commit recorded\n     ++\tuntracked or modified files or its `HEAD` differs from the commit recorded\n       \tin the superproject and can be used to override any settings of the\n      -\t'ignore' option in linkgit:git-config[1] or linkgit:gitmodules[5]. When\n      -\t\"untracked\" is used submodules are not considered dirty when they only\n     @@ Documentation/diff-options.txt: endif::git-format-patch[]\n       \n      ---src-prefix=<prefix>::\n      -\tShow the given source prefix instead of \"a/\".\n     -+++--src-prefix=++__<prefix>__::\n     ++`--src-prefix=<prefix>`::\n      +\tShow the given source _<prefix>_ instead of \"a/\".\n       \n      ---dst-prefix=<prefix>::\n      -\tShow the given destination prefix instead of \"b/\".\n     -+++--dst-prefix=++__<prefix>__::\n     ++`--dst-prefix=<prefix>`::\n      +\tShow the given destination _<prefix>_ instead of \"b/\".\n       \n      ---no-prefix::\n     @@ Documentation/diff-options.txt: endif::git-format-patch[]\n       \tUse the default source and destination prefixes (\"a/\" and \"b/\").\n       \tThis overrides configuration variables such as `diff.noprefix`,\n       \t`diff.srcPrefix`, `diff.dstPrefix`, and `diff.mnemonicPrefix`\n     - \t(see `git-config`(1)).\n     +-\t(see `git-config`(1)).\n     ++\t(see linkgit:git-config[1]).\n       \n      ---line-prefix=<prefix>::\n      -\tPrepend an additional prefix to every line of output.\n     -+++--line-prefix=++__<prefix>__::\n     ++`--line-prefix=<prefix>`::\n      +\tPrepend an additional _<prefix>_ to every line of output.\n       \n      ---ita-invisible-in-index::\n 3:  81b5782d152 ! 3:  8fec37ee174  doc: git-diff: apply format changes to diff-format\n     @@ Metadata\n      Author: Jean-Noël Avila <jn.avila@free.fr>\n      \n       ## Commit message ##\n     -     doc: git-diff: apply format changes to diff-format\n     +    doc: git-diff: apply format changes to diff-format\n      \n          Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>\n      \n     @@ Documentation/diff-format.txt\n       compared differs:\n       \n      -git-diff-index <tree-ish>::\n     -+`git-diff-index` _<tree-ish>_::\n     -         compares the <tree-ish> and the files on the filesystem.\n     +-        compares the <tree-ish> and the files on the filesystem.\n     ++`git-diff-index <tree-ish>`::\n     ++\tcompares the _<tree-ish>_ and the files on the filesystem.\n       \n      -git-diff-index --cached <tree-ish>::\n     -+`git-diff-index --cached` _<tree-ish>_::\n     -         compares the <tree-ish> and the index.\n     +-        compares the <tree-ish> and the index.\n     ++`git-diff-index --cached <tree-ish>`::\n     ++\tcompares the _<tree-ish>_ and the index.\n       \n      -git-diff-tree [-r] <tree-ish-1> <tree-ish-2> [<pattern>...]::\n     -+`git-diff-tree` [`-r`] _<tree-ish-1>_ _<tree-ish-2>_ [_<pattern>_...]::\n     ++`git-diff-tree [-r] <tree-ish-1> <tree-ish-2> [<pattern>...]`::\n               compares the trees named by the two arguments.\n       \n      -git-diff-files [<pattern>...]::\n     -+`git-diff-files` [_<pattern>_...]::\n     ++`git-diff-files [<pattern>...]`::\n               compares the index and the files on the filesystem.\n       \n      -The \"git-diff-tree\" command begins its output by printing the hash of\n 4:  3c475a2ee4e ! 4:  daed146639d  doc: git-diff: apply format changes to diff-generate-patch\n     @@ Metadata\n      Author: Jean-Noël Avila <jn.avila@free.fr>\n      \n       ## Commit message ##\n     -     doc: git-diff: apply format changes to diff-generate-patch\n     +    doc: git-diff: apply format changes to diff-generate-patch\n      \n          Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>\n      \n     @@ Documentation/diff-generate-patch.txt: or like this (when the `--cc` option is u\n      -       mode <mode>,<mode>..<mode>\n      -       new file mode <mode>\n      -       deleted file mode <mode>,<mode>\n     - +\n     --The `mode <mode>,<mode>..<mode>` line appears only if at least one of\n     --the <mode> is different from the rest. Extended headers with\n     +++\n      +[synopsis]\n     -+index <hash>,<hash>`..`<hash>\n     ++index <hash>,<hash>..<hash>\n      +mode <mode>,<mode>`..`<mode>\n      +new file mode <mode>\n      +deleted file mode <mode>,<mode>\n     -++\n     -+The `mode` __<mode>__++,++__<mode>__++..++__<mode>__ line appears only if at least one of\n     -+the _<mode>_ is different from the rest. Extended headers with\n     + +\n     + The `mode <mode>,<mode>..<mode>` line appears only if at least one of\n     + the <mode> is different from the rest. Extended headers with\n       information about detected content movement (renames and\n       copying detection) are designed to work with the diff of two\n      -<tree-ish> and are not used by combined diff format.\n 5:  acb5bdda904 ! 5:  17a2f028d59  doc: git-diff: apply format changes to config part\n     @@ Metadata\n      Author: Jean-Noël Avila <jn.avila@free.fr>\n      \n       ## Commit message ##\n     -     doc: git-diff: apply format changes to config part\n     +    doc: git-diff: apply format changes to config part\n      \n          Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>\n      \n     @@ Documentation/config/diff.txt\n       \tdefault behavior of the `--dirstat` option to linkgit:git-diff[1]\n       \tand friends. The defaults can be overridden on the command line\n      -\t(using `--dirstat=<param1,param2,...>`). The fallback defaults\n     -+\t(using ++--dirstat=++__<param1>__++,++__<param2>__...). The fallback defaults\n     ++\t(using `--dirstat=<param>,...`). The fallback defaults\n       \t(when not changed by `diff.dirstat`) are `changes,noncumulative,3`.\n       \tThe following parameters are available:\n       +\n     @@ Documentation/config/diff.txt: directories with less than 10% of the total amoun\n       \tyour files, you might want to use linkgit:gitattributes[5] instead.\n       \n      -diff.trustExitCode::\n     +-\tIf this boolean value is set to true then the\n      +`diff.trustExitCode`::\n     - \tIf this boolean value is set to true then the\n     ++\tIf this boolean value is set to `true` then the\n       \t`diff.external` command is expected to return exit code\n       \t0 if it considers the input files to be equal or 1 if it\n      -\tconsiders them to be different, like `diff(1)`.\n     @@ Documentation/config/diff.txt: directories with less than 10% of the total amoun\n       \tthis configuration is in effect, reverse diff output also swaps\n       \tthe order of the prefixes:\n      @@ Documentation/config/diff.txt: diff.mnemonicPrefix::\n     + \t compares a (c)ommit and the (w)ork tree;\n     + `git diff --cached`;;\n     + \tcompares a (c)ommit and the (i)ndex;\n     +-`git diff HEAD:file1 file2`;;\n     ++`git diff HEAD:<file1> <file2>`;;\n     + \tcompares an (o)bject and a (w)ork tree entity;\n       `git diff --no-index a b`;;\n       \tcompares two non-git things (1) and (2).\n       \n     @@ Documentation/config/diff.txt: diff.mnemonicPrefix::\n       \tcharacters are *ignorable* whitespace.\n       \n      -diff.<driver>.command::\n     -+++diff.++__<driver>__++.command++::\n     ++`diff.<driver>.command`::\n       \tThe custom diff driver command.  See linkgit:gitattributes[5]\n       \tfor details.\n       \n      -diff.<driver>.trustExitCode::\n     -+++diff.++__<driver>__++.trustExitCode++::\n     ++`diff.<driver>.trustExitCode`::\n       \tIf this boolean value is set to true then the\n     --\t`diff.<driver>.command` command is expected to return exit code\n     -+\t++diff.++__<driver>__++.command++ command is expected to return exit code\n     + \t`diff.<driver>.command` command is expected to return exit code\n       \t0 if it considers the input files to be equal or 1 if it\n      -\tconsiders them to be different, like `diff(1)`.\n      +\tconsiders them to be different, like `diff`(1).\n     @@ Documentation/config/diff.txt: diff.mnemonicPrefix::\n       \tAny other exit code causes Git to report a fatal error.\n       \n      -diff.<driver>.xfuncname::\n     -+++diff.++__<driver>__++.xfuncname++::\n     ++`diff.<driver>.xfuncname`::\n       \tThe regular expression that the diff driver should use to\n       \trecognize the hunk header.  A built-in pattern may also be used.\n       \tSee linkgit:gitattributes[5] for details.\n       \n      -diff.<driver>.binary::\n      -\tSet this option to true to make the diff driver treat files as\n     -+++diff.++__<driver>__++.binary++::\n     ++`diff.<driver>.binary`::\n      +\tSet this option to `true` to make the diff driver treat files as\n       \tbinary.  See linkgit:gitattributes[5] for details.\n       \n      -diff.<driver>.textconv::\n     -+++diff.++__<driver>__++.textconv++::\n     ++`diff.<driver>.textconv`::\n       \tThe command that the diff driver should call to generate the\n       \ttext-converted version of a file.  The result of the\n       \tconversion is used to generate a human-readable diff.  See\n       \tlinkgit:gitattributes[5] for details.\n       \n      -diff.<driver>.wordRegex::\n     -+++diff.++__<driver>__++.wordRegex++::\n     ++`diff.<driver>.wordRegex`::\n       \tThe regular expression that the diff driver should use to\n       \tsplit words in a line.  See linkgit:gitattributes[5] for\n       \tdetails.\n       \n      -diff.<driver>.cachetextconv::\n     -+++diff.++__<driver>__++.cachetextconv++::\n     ++`diff.<driver>.cachetextconv`::\n       \tSet this option to true to make the diff driver cache the text\n       \tconversion outputs.  See linkgit:gitattributes[5] for details.\n       \n     @@ Documentation/config/diff.txt: diff.mnemonicPrefix::\n       \tChoose a diff algorithm.  The variants are as follows:\n       +\n       --\n     +-`default`, `myers`;;\n     ++`default`;;\n     ++`myers`;;\n     + \tThe basic greedy diff algorithm. Currently, this is the default.\n     + `minimal`;;\n     + \tSpend extra time to make sure the smallest possible diff is\n      @@ Documentation/config/diff.txt: diff.algorithm::\n       --\n       +\n     @@ Documentation/config/diff.txt: diff.algorithm::\n       \tHighlight whitespace errors in the `context`, `old` or `new`\n       \tlines of the diff.  Multiple values are separated by comma,\n       \t`none` resets previous values, `default` reset the list to\n     - \t`new` and `all` is a shorthand for `old,new,context`.  The\n     - \twhitespace errors are colored with `color.diff.whitespace`.\n     --\tThe command line option `--ws-error-highlight=<kind>`\n     -+\tThe command line option ++--ws-error-highlight=++__<kind>__\n     +@@ Documentation/config/diff.txt: diff.wsErrorHighlight::\n     + \tThe command line option `--ws-error-highlight=<kind>`\n       \toverrides this setting.\n       \n      -diff.colorMoved::\n     @@ Documentation/config/diff.txt: diff.algorithm::\n       \tWhen moved lines are colored using e.g. the `diff.colorMoved` setting,\n      -\tthis option controls the `<mode>` how spaces are treated.\n      -\tFor details of valid modes see '--color-moved-ws' in linkgit:git-diff[1].\n     -+\tthis option controls the _<mode>_ how spaces are treated.\n     ++\tthis option controls the mode how spaces are treated.\n      +\tFor details of valid modes see `--color-moved-ws` in linkgit:git-diff[1].\n\n-- \ngitgitgadget\n"},{"id":"507058","messageId":"c104bd50b646646e980905a9294209f381b9e61c.1731343985.git.gitgitgadget@gmail.com","threadId":"61899","inReplyTo":"pull.1769.v2.git.1731343985.gitgitgadget@gmail.com","subject":"[PATCH v2 1/5] doc: git-diff: apply new documentation guidelines","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-11-11T16:53:01Z","receivedAt":"2024-11-11T16:53:10Z","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/git-diff.txt | 103 +++++++++++++++++++------------------\n 1 file changed, 52 insertions(+), 51 deletions(-)\n\ndiff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt\nindex c065f023eca..fc8c577c3ce 100644\n--- a/Documentation/git-diff.txt\n+++ b/Documentation/git-diff.txt\n@@ -8,13 +8,13 @@ git-diff - Show changes between commits, commit and working tree, etc\n \n SYNOPSIS\n --------\n-[verse]\n-'git diff' [<options>] [<commit>] [--] [<path>...]\n-'git diff' [<options>] --cached [--merge-base] [<commit>] [--] [<path>...]\n-'git diff' [<options>] [--merge-base] <commit> [<commit>...] <commit> [--] [<path>...]\n-'git diff' [<options>] <commit>...<commit> [--] [<path>...]\n-'git diff' [<options>] <blob> <blob>\n-'git diff' [<options>] --no-index [--] <path> <path>\n+[synopsis]\n+git diff [<options>] [<commit>] [--] [<path>...]\n+git diff [<options>] --cached [--merge-base] [<commit>] [--] [<path>...]\n+git diff [<options>] [--merge-base] <commit> [<commit>...] <commit> [--] [<path>...]\n+git diff [<options>] <commit>...<commit> [--] [<path>...]\n+git diff [<options>] <blob> <blob>\n+git diff [<options>] --no-index [--] <path> <path>\n \n DESCRIPTION\n -----------\n@@ -23,7 +23,7 @@ between the index and a tree, changes between two trees, changes resulting\n from a merge, changes between two blob objects, or changes between two\n files on disk.\n \n-'git diff' [<options>] [--] [<path>...]::\n+`git diff [<options>] [--] [<path>...]`::\n \n \tThis form is to view the changes you made relative to\n \tthe index (staging area for the next commit).  In other\n@@ -31,7 +31,7 @@ files on disk.\n \tfurther add to the index but you still haven't.  You can\n \tstage these changes by using linkgit:git-add[1].\n \n-'git diff' [<options>] --no-index [--] <path> <path>::\n+`git diff [<options>] --no-index [--] <path> <path>`::\n \n \tThis form is to compare the given two paths on the\n \tfilesystem.  You can omit the `--no-index` option when\n@@ -40,82 +40,82 @@ files on disk.\n \tor when running the command outside a working tree\n \tcontrolled by Git. This form implies `--exit-code`.\n \n-'git diff' [<options>] --cached [--merge-base] [<commit>] [--] [<path>...]::\n+`git diff [<options>] --cached [--merge-base] [<commit>] [--] [<path>...]`::\n \n \tThis form is to view the changes you staged for the next\n-\tcommit relative to the named <commit>.  Typically you\n+\tcommit relative to the named _<commit>_.  Typically you\n \twould want comparison with the latest commit, so if you\n-\tdo not give <commit>, it defaults to HEAD.\n-\tIf HEAD does not exist (e.g. unborn branches) and\n-\t<commit> is not given, it shows all staged changes.\n-\t--staged is a synonym of --cached.\n+\tdo not give _<commit>_, it defaults to `HEAD`.\n+\tIf `HEAD` does not exist (e.g. unborn branches) and\n+\t_<commit>_ is not given, it shows all staged changes.\n+\t`--staged` is a synonym of `--cached`.\n +\n-If --merge-base is given, instead of using <commit>, use the merge base\n-of <commit> and HEAD.  `git diff --cached --merge-base A` is equivalent to\n+If `--merge-base` is given, instead of using _<commit>_, use the merge base\n+of _<commit>_ and `HEAD`.  `git diff --cached --merge-base A` is equivalent to\n `git diff --cached $(git merge-base A HEAD)`.\n \n-'git diff' [<options>] [--merge-base] <commit> [--] [<path>...]::\n+`git diff [<options>] [--merge-base] <commit> [--] [<path>...]`::\n \n \tThis form is to view the changes you have in your\n-\tworking tree relative to the named <commit>.  You can\n-\tuse HEAD to compare it with the latest commit, or a\n+\tworking tree relative to the named _<commit>_.  You can\n+\tuse `HEAD` to compare it with the latest commit, or a\n \tbranch name to compare with the tip of a different\n \tbranch.\n +\n-If --merge-base is given, instead of using <commit>, use the merge base\n-of <commit> and HEAD.  `git diff --merge-base A` is equivalent to\n+If `--merge-base` is given, instead of using _<commit>_, use the merge base\n+of _<commit>_ and `HEAD`.  `git diff --merge-base A` is equivalent to\n `git diff $(git merge-base A HEAD)`.\n \n-'git diff' [<options>] [--merge-base] <commit> <commit> [--] [<path>...]::\n+`git diff [<options>] [--merge-base] <commit> <commit> [--] [<path>...]`::\n \n \tThis is to view the changes between two arbitrary\n-\t<commit>.\n+\t_<commit>_.\n +\n-If --merge-base is given, use the merge base of the two commits for the\n+If `--merge-base` is given, use the merge base of the two commits for the\n \"before\" side.  `git diff --merge-base A B` is equivalent to\n `git diff $(git merge-base A B) B`.\n \n-'git diff' [<options>] <commit> <commit>... <commit> [--] [<path>...]::\n+`git diff [<options>] <commit> <commit>...<commit> [--] [<path>...]`::\n \n \tThis form is to view the results of a merge commit.  The first\n-\tlisted <commit> must be the merge itself; the remaining two or\n+\tlisted _<commit>_ must be the merge itself; the remaining two or\n \tmore commits should be its parents.  Convenient ways to produce\n-\tthe desired set of revisions are to use the suffixes `^@` and\n-\t`^!`.  If A is a merge commit, then `git diff A A^@`,\n+\tthe desired set of revisions are to use the suffixes `@` and\n+\t`^!`.  If `A` is a merge commit, then `git diff A A^@`,\n \t`git diff A^!` and `git show A` all give the same combined diff.\n \n-'git diff' [<options>] <commit>..<commit> [--] [<path>...]::\n+`git diff [<options>] <commit>..<commit> [--] [<path>...]`::\n \n \tThis is synonymous to the earlier form (without the `..`) for\n-\tviewing the changes between two arbitrary <commit>.  If <commit> on\n+\tviewing the changes between two arbitrary _<commit>_.  If _<commit>_ on\n \tone side is omitted, it will have the same effect as\n-\tusing HEAD instead.\n+\tusing `HEAD` instead.\n \n-'git diff' [<options>] <commit>\\...<commit> [--] [<path>...]::\n+`git diff [<options>] <commit>...<commit> [--] [<path>...]`::\n \n \tThis form is to view the changes on the branch containing\n-\tand up to the second <commit>, starting at a common ancestor\n-\tof both <commit>.  `git diff A...B` is equivalent to\n+\tand up to the second _<commit>_, starting at a common ancestor\n+\tof both _<commit>_.  `git diff A...B` is equivalent to\n \t`git diff $(git merge-base A B) B`.  You can omit any one\n-\tof <commit>, which has the same effect as using HEAD instead.\n+\tof _<commit>_, which has the same effect as using `HEAD` instead.\n \n Just in case you are doing something exotic, it should be\n-noted that all of the <commit> in the above description, except\n+noted that all of the _<commit>_ in the above description, except\n in the `--merge-base` case and in the last two forms that use `..`\n-notations, can be any <tree>. A tree of interest is the one pointed to\n-by the ref named `AUTO_MERGE`, which is written by the 'ort' merge\n+notations, can be any _<tree>_. A tree of interest is the one pointed to\n+by the ref named `AUTO_MERGE`, which is written by the `ort` merge\n strategy upon hitting merge conflicts (see linkgit:git-merge[1]).\n Comparing the working tree with `AUTO_MERGE` shows changes you've made\n so far to resolve textual conflicts (see the examples below).\n \n-For a more complete list of ways to spell <commit>, see\n+For a more complete list of ways to spell _<commit>_, see\n \"SPECIFYING REVISIONS\" section in linkgit:gitrevisions[7].\n-However, \"diff\" is about comparing two _endpoints_, not ranges,\n-and the range notations (`<commit>..<commit>` and\n-`<commit>...<commit>`) do not mean a range as defined in the\n+However, `diff` is about comparing two _endpoints_, not ranges,\n+and the range notations (`<commit>..<commit>` and `<commit>...<commit>`)\n+do not mean a range as defined in the\n \"SPECIFYING RANGES\" section in linkgit:gitrevisions[7].\n \n-'git diff' [<options>] <blob> <blob>::\n+`git diff [<options>] <blob> <blob>`::\n \n \tThis form is to view the differences between the raw\n \tcontents of two blob objects.\n@@ -125,22 +125,22 @@ OPTIONS\n :git-diff: 1\n include::diff-options.txt[]\n \n--1 --base::\n--2 --ours::\n--3 --theirs::\n+`-1` `--base`::\n+`-2` `--ours`::\n+`-3` `--theirs`::\n \tCompare the working tree with the \"base\" version (stage #1),\n \t\"our branch\" (stage #2) or \"their branch\" (stage #3).  The\n \tindex contains these stages only for unmerged entries i.e.\n \twhile resolving conflicts.  See linkgit:git-read-tree[1]\n \tsection \"3-Way Merge\" for detailed information.\n \n--0::\n+`-0`::\n \tOmit diff output for unmerged entries and just show\n \t\"Unmerged\".  Can be used only when comparing the working tree\n \twith the index.\n \n-<path>...::\n-\tThe <paths> parameters, when given, are used to limit\n+_<path>_...::\n+\tThe _<path>_ parameters, when given, are used to limit\n \tthe diff to the named paths (you can give directory\n \tnames and get diff for all files under them).\n \n@@ -225,11 +225,12 @@ CONFIGURATION\n \n include::includes/cmd-config-section-all.txt[]\n \n+:git-diff: 1\n include::config/diff.txt[]\n \n SEE ALSO\n --------\n-diff(1),\n+`diff`(1),\n linkgit:git-difftool[1],\n linkgit:git-log[1],\n linkgit:gitdiffcore[7],\n-- \ngitgitgadget\n\n"},{"id":"507063","messageId":"129763c2aaefd92bddaa59601c5a3275b9defa36.1731343985.git.gitgitgadget@gmail.com","threadId":"61899","inReplyTo":"pull.1769.v2.git.1731343985.gitgitgadget@gmail.com","subject":"[PATCH v2 2/5] doc: git-diff: apply format changes to diff-options","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-11-11T16:53:02Z","receivedAt":"2024-11-11T16:53:11Z","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\nThe format change is only applied to the sections of the file that are\nfiltered in git-diff.\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\n---\n Documentation/diff-options.txt | 423 +++++++++++++++++----------------\n 1 file changed, 212 insertions(+), 211 deletions(-)\n\ndiff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt\nindex cd0b81adbb6..640eb6e7db5 100644\n--- a/Documentation/diff-options.txt\n+++ b/Documentation/diff-options.txt\n@@ -19,16 +19,16 @@ ifdef::git-format-patch[]\n endif::git-format-patch[]\n \n ifndef::git-format-patch[]\n--p::\n--u::\n---patch::\n+`-p`::\n+`-u`::\n+`--patch`::\n \tGenerate patch (see <<generate_patch_text_with_p>>).\n ifdef::git-diff[]\n \tThis is the default.\n endif::git-diff[]\n \n--s::\n---no-patch::\n+`-s`::\n+`--no-patch`::\n \tSuppress all output from the diff machinery.  Useful for\n \tcommands like `git show` that show the patch by default to\n \tsquelch their output, or to cancel the effect of options like\n@@ -39,28 +39,28 @@ endif::git-format-patch[]\n ifdef::git-log[]\n -m::\n \tShow diffs for merge commits in the default format. This is\n-\tsimilar to '--diff-merges=on', except `-m` will\n+\tsimilar to `--diff-merges=on`, except `-m` will\n \tproduce no output unless `-p` is given as well.\n \n -c::\n \tProduce combined diff output for merge commits.\n-\tShortcut for '--diff-merges=combined -p'.\n+\tShortcut for `--diff-merges=combined -p`.\n \n --cc::\n \tProduce dense combined diff output for merge commits.\n-\tShortcut for '--diff-merges=dense-combined -p'.\n+\tShortcut for `--diff-merges=dense-combined -p`.\n \n --dd::\n \tProduce diff with respect to first parent for both merge and\n \tregular commits.\n-\tShortcut for '--diff-merges=first-parent -p'.\n+\tShortcut for `--diff-merges=first-parent -p`.\n \n --remerge-diff::\n \tProduce remerge-diff output for merge commits.\n-\tShortcut for '--diff-merges=remerge -p'.\n+\tShortcut for `--diff-merges=remerge -p`.\n \n --no-diff-merges::\n-\tSynonym for '--diff-merges=off'.\n+\tSynonym for `--diff-merges=off`.\n \n --diff-merges=<format>::\n \tSpecify diff format to be used for merge commits. Default is\n@@ -73,33 +73,33 @@ The following formats are supported:\n off, none::\n \tDisable output of diffs for merge commits. Useful to override\n \timplied value.\n-+\n+\n on, m::\n \tMake diff output for merge commits to be shown in the default\n \tformat. The default format can be changed using\n \t`log.diffMerges` configuration variable, whose default value\n \tis `separate`.\n-+\n+\n first-parent, 1::\n \tShow full diff with respect to first parent. This is the same\n \tformat as `--patch` produces for non-merge commits.\n-+\n+\n separate::\n \tShow full diff with respect to each of parents.\n \tSeparate log entry and diff is generated for each parent.\n-+\n+\n combined, c::\n \tShow differences from each of the parents to the merge\n \tresult simultaneously instead of showing pairwise diff between\n \ta parent and the result one at a time. Furthermore, it lists\n \tonly files which were modified from all parents.\n-+\n+\n dense-combined, cc::\n \tFurther compress output produced by `--diff-merges=combined`\n \tby omitting uninteresting hunks whose contents in the parents\n \thave only two variants and the merge result picks one of them\n \twithout modification.\n-+\n+\n remerge, r::\n \tRemerge two-parent merge commits to create a temporary tree\n \tobject--potentially containing files with conflict markers\n@@ -112,33 +112,33 @@ documented).\n --\n \n --combined-all-paths::\n-\tThis flag causes combined diffs (used for merge commits) to\n+\tCause combined diffs (used for merge commits) to\n \tlist the name of the file from all parents.  It thus only has\n \teffect when `--diff-merges=[dense-]combined` is in use, and\n \tis likely only useful if filename changes are detected (i.e.\n \twhen either rename or copy detection have been requested).\n endif::git-log[]\n \n--U<n>::\n---unified=<n>::\n-\tGenerate diffs with <n> lines of context instead of\n+`-U<n>`::\n+`--unified=<n>`::\n+\tGenerate diffs with _<n>_ lines of context instead of\n \tthe usual three.\n ifndef::git-format-patch[]\n \tImplies `--patch`.\n endif::git-format-patch[]\n \n---output=<file>::\n+`--output=<file>`::\n \tOutput to a specific file instead of stdout.\n \n---output-indicator-new=<char>::\n---output-indicator-old=<char>::\n---output-indicator-context=<char>::\n+`--output-indicator-new=<char>`::\n+`--output-indicator-old=<char>`::\n+`--output-indicator-context=<char>`::\n \tSpecify the character used to indicate new, old or context\n-\tlines in the generated patch. Normally they are '+', '-' and\n+\tlines in the generated patch. Normally they are `+`, `-` and\n \t' ' respectively.\n \n ifndef::git-format-patch[]\n---raw::\n+`--raw`::\n ifndef::git-log[]\n \tGenerate the diff in raw format.\n ifdef::git-diff-core[]\n@@ -155,54 +155,55 @@ endif::git-log[]\n endif::git-format-patch[]\n \n ifndef::git-format-patch[]\n---patch-with-raw::\n+`--patch-with-raw`::\n \tSynonym for `-p --raw`.\n endif::git-format-patch[]\n \n ifdef::git-log[]\n--t::\n+`-t`::\n \tShow the tree objects in the diff output.\n endif::git-log[]\n \n---indent-heuristic::\n+`--indent-heuristic`::\n \tEnable the heuristic that shifts diff hunk boundaries to make patches\n \teasier to read. This is the default.\n \n---no-indent-heuristic::\n+`--no-indent-heuristic`::\n \tDisable the indent heuristic.\n \n---minimal::\n+`--minimal`::\n \tSpend extra time to make sure the smallest possible\n \tdiff is produced.\n \n---patience::\n+`--patience`::\n \tGenerate a diff using the \"patience diff\" algorithm.\n \n---histogram::\n+`--histogram`::\n \tGenerate a diff using the \"histogram diff\" algorithm.\n \n---anchored=<text>::\n+`--anchored=<text>`::\n \tGenerate a diff using the \"anchored diff\" algorithm.\n +\n This option may be specified more than once.\n +\n If a line exists in both the source and destination, exists only once,\n-and starts with this text, this algorithm attempts to prevent it from\n+and starts with _<text>_, this algorithm attempts to prevent it from\n appearing as a deletion or addition in the output. It uses the \"patience\n diff\" algorithm internally.\n \n---diff-algorithm={patience|minimal|histogram|myers}::\n+`--diff-algorithm=(patience|minimal|histogram|myers)`::\n \tChoose a diff algorithm. The variants are as follows:\n +\n --\n-`default`, `myers`;;\n+   `default`;;\n+   `myers`;;\n \tThe basic greedy diff algorithm. Currently, this is the default.\n-`minimal`;;\n+   `minimal`;;\n \tSpend extra time to make sure the smallest possible diff is\n \tproduced.\n-`patience`;;\n+   `patience`;;\n \tUse \"patience diff\" algorithm when generating patches.\n-`histogram`;;\n+   `histogram`;;\n \tThis algorithm extends the patience algorithm to \"support\n \tlow-occurrence common elements\".\n --\n@@ -211,47 +212,47 @@ For instance, if you configured the `diff.algorithm` variable to a\n non-default value and want to use the default one, then you\n have to use `--diff-algorithm=default` option.\n \n---stat[=<width>[,<name-width>[,<count>]]]::\n+`--stat[=<width>[,<name-width>[,<count>]]]`::\n \tGenerate a diffstat. By default, as much space as necessary\n \twill be used for the filename part, and the rest for the graph\n \tpart. Maximum width defaults to terminal width, or 80 columns\n \tif not connected to a terminal, and can be overridden by\n-\t`<width>`. The width of the filename part can be limited by\n-\tgiving another width `<name-width>` after a comma or by setting\n-\t`diff.statNameWidth=<width>`. The width of the graph part can be\n-\tlimited by using `--stat-graph-width=<width>` or by setting\n-\t`diff.statGraphWidth=<width>`. Using `--stat` or\n+\t_<width>_. The width of the filename part can be limited by\n+\tgiving another width _<name-width>_ after a comma or by setting\n+\t`diff.statNameWidth=<name-width>`. The width of the graph part can be\n+\tlimited by using `--stat-graph-width=<graph-width>` or by setting\n+\t`diff.statGraphWidth=<graph-width>`. Using `--stat` or\n \t`--stat-graph-width` affects all commands generating a stat graph,\n \twhile setting `diff.statNameWidth` or `diff.statGraphWidth`\n \tdoes not affect `git format-patch`.\n-\tBy giving a third parameter `<count>`, you can limit the output to\n-\tthe first `<count>` lines, followed by `...` if there are more.\n+\tBy giving a third parameter _<count>_, you can limit the output to\n+\tthe first _<count>_ lines, followed by `...` if there are more.\n +\n These parameters can also be set individually with `--stat-width=<width>`,\n `--stat-name-width=<name-width>` and `--stat-count=<count>`.\n \n---compact-summary::\n+`--compact-summary`::\n \tOutput a condensed summary of extended header information such\n-\tas file creations or deletions (\"new\" or \"gone\", optionally \"+l\"\n-\tif it's a symlink) and mode changes (\"+x\" or \"-x\" for adding\n+\tas file creations or deletions (\"new\" or \"gone\", optionally `+l`\n+\tif it's a symlink) and mode changes (`+x` or `-x` for adding\n \tor removing executable bit respectively) in diffstat. The\n \tinformation is put between the filename part and the graph\n \tpart. Implies `--stat`.\n \n---numstat::\n+`--numstat`::\n \tSimilar to `--stat`, but shows number of added and\n \tdeleted lines in decimal notation and pathname without\n \tabbreviation, to make it more machine friendly.  For\n \tbinary files, outputs two `-` instead of saying\n \t`0 0`.\n \n---shortstat::\n+`--shortstat`::\n \tOutput only the last line of the `--stat` format containing total\n \tnumber of modified files, as well as number of added and deleted\n \tlines.\n \n--X[<param1,param2,...>]::\n---dirstat[=<param1,param2,...>]::\n+`-X [<param>,...]`::\n+`--dirstat[=<param>,...]`::\n \tOutput the distribution of relative amount of changes for each\n \tsub-directory. The behavior of `--dirstat` can be customized by\n \tpassing it a comma separated list of parameters.\n@@ -284,7 +285,7 @@ These parameters can also be set individually with `--stat-width=<width>`,\n \tNote that when using `cumulative`, the sum of the percentages\n \treported may exceed 100%. The default (non-cumulative) behavior can\n \tbe specified with the `noncumulative` parameter.\n-<limit>;;\n+_<limit>_;;\n \tAn integer parameter specifies a cut-off percent (3% by default).\n \tDirectories contributing less than this percentage of the changes\n \tare not shown in the output.\n@@ -295,29 +296,29 @@ directories with less than 10% of the total amount of changed files,\n and accumulating child directory counts in the parent directories:\n `--dirstat=files,10,cumulative`.\n \n---cumulative::\n-\tSynonym for --dirstat=cumulative\n+`--cumulative`::\n+\tSynonym for `--dirstat=cumulative`.\n \n---dirstat-by-file[=<param1,param2>...]::\n-\tSynonym for --dirstat=files,<param1>,<param2>...\n+`--dirstat-by-file[=<param>,...]`::\n+\tSynonym for `--dirstat=files,<param>,...`.\n \n---summary::\n+`--summary`::\n \tOutput a condensed summary of extended header information\n \tsuch as creations, renames and mode changes.\n \n ifndef::git-format-patch[]\n---patch-with-stat::\n+`--patch-with-stat`::\n \tSynonym for `-p --stat`.\n endif::git-format-patch[]\n \n ifndef::git-format-patch[]\n \n--z::\n+`-z`::\n ifdef::git-log[]\n-\tSeparate the commits with NULs instead of newlines.\n+\tSeparate the commits with __NUL__s instead of newlines.\n +\n Also, when `--raw` or `--numstat` has been given, do not munge\n-pathnames and use NULs as output field terminators.\n+pathnames and use __NUL__s as output field terminators.\n endif::git-log[]\n ifndef::git-log[]\n \tWhen `--raw`, `--numstat`, `--name-only` or `--name-status` has been\n@@ -328,89 +329,89 @@ Without this option, pathnames with \"unusual\" characters are quoted as\n explained for the configuration variable `core.quotePath` (see\n linkgit:git-config[1]).\n \n---name-only::\n+`--name-only`::\n \tShow only the name of each changed file in the post-image tree.\n \tThe file names are often encoded in UTF-8.\n \tFor more information see the discussion about encoding in the linkgit:git-log[1]\n \tmanual page.\n \n---name-status::\n+`--name-status`::\n \tShow only the name(s) and status of each changed file. See the description\n \tof the `--diff-filter` option on what the status letters mean.\n \tJust like `--name-only` the file names are often encoded in UTF-8.\n \n---submodule[=<format>]::\n+`--submodule[=<format>]`::\n \tSpecify how differences in submodules are shown.  When specifying\n-\t`--submodule=short` the 'short' format is used.  This format just\n+\t`--submodule=short` the `short` format is used.  This format just\n \tshows the names of the commits at the beginning and end of the range.\n-\tWhen `--submodule` or `--submodule=log` is specified, the 'log'\n+\tWhen `--submodule` or `--submodule=log` is specified, the `log`\n \tformat is used.  This format lists the commits in the range like\n \tlinkgit:git-submodule[1] `summary` does.  When `--submodule=diff`\n-\tis specified, the 'diff' format is used.  This format shows an\n+\tis specified, the `diff` format is used.  This format shows an\n \tinline diff of the changes in the submodule contents between the\n-\tcommit range.  Defaults to `diff.submodule` or the 'short' format\n+\tcommit range.  Defaults to `diff.submodule` or the `short` format\n \tif the config option is unset.\n \n---color[=<when>]::\n+`--color[=<when>]`::\n \tShow colored diff.\n-\t`--color` (i.e. without '=<when>') is the same as `--color=always`.\n-\t'<when>' can be one of `always`, `never`, or `auto`.\n+\t`--color` (i.e. without `=<when>`) is the same as `--color=always`.\n+\t_<when>_ can be one of `always`, `never`, or `auto`.\n ifdef::git-diff[]\n \tIt can be changed by the `color.ui` and `color.diff`\n \tconfiguration settings.\n endif::git-diff[]\n \n---no-color::\n+`--no-color`::\n \tTurn off colored diff.\n ifdef::git-diff[]\n \tThis can be used to override configuration settings.\n endif::git-diff[]\n \tIt is the same as `--color=never`.\n \n---color-moved[=<mode>]::\n+`--color-moved[=<mode>]`::\n \tMoved lines of code are colored differently.\n ifdef::git-diff[]\n \tIt can be changed by the `diff.colorMoved` configuration setting.\n endif::git-diff[]\n-\tThe <mode> defaults to 'no' if the option is not given\n-\tand to 'zebra' if the option with no mode is given.\n+\tThe _<mode>_ defaults to `no` if the option is not given\n+\tand to `zebra` if the option with no mode is given.\n \tThe mode must be one of:\n +\n --\n-no::\n+`no`::\n \tMoved lines are not highlighted.\n-default::\n+`default`::\n \tIs a synonym for `zebra`. This may change to a more sensible mode\n \tin the future.\n-plain::\n+`plain`::\n \tAny line that is added in one location and was removed\n-\tin another location will be colored with 'color.diff.newMoved'.\n-\tSimilarly 'color.diff.oldMoved' will be used for removed lines\n+\tin another location will be colored with `color.diff.newMoved`.\n+\tSimilarly `color.diff.oldMoved` will be used for removed lines\n \tthat are added somewhere else in the diff. This mode picks up any\n \tmoved line, but it is not very useful in a review to determine\n \tif a block of code was moved without permutation.\n-blocks::\n+`blocks`::\n \tBlocks of moved text of at least 20 alphanumeric characters\n \tare detected greedily. The detected blocks are\n-\tpainted using either the 'color.diff.{old,new}Moved' color.\n+\tpainted using either the `color.diff.(old|new)Moved` color.\n \tAdjacent blocks cannot be told apart.\n-zebra::\n-\tBlocks of moved text are detected as in 'blocks' mode. The blocks\n-\tare painted using either the 'color.diff.{old,new}Moved' color or\n-\t'color.diff.{old,new}MovedAlternative'. The change between\n+`zebra`::\n+\tBlocks of moved text are detected as in `blocks` mode. The blocks\n+\tare painted using either the `color.diff.(old|new)Moved` color or\n+\t`color.diff.(old|new)MovedAlternative`. The change between\n \tthe two colors indicates that a new block was detected.\n-dimmed-zebra::\n-\tSimilar to 'zebra', but additional dimming of uninteresting parts\n+`dimmed-zebra`::\n+\tSimilar to `zebra`, but additional dimming of uninteresting parts\n \tof moved code is performed. The bordering lines of two adjacent\n \tblocks are considered interesting, the rest is uninteresting.\n \t`dimmed_zebra` is a deprecated synonym.\n --\n \n---no-color-moved::\n+`--no-color-moved`::\n \tTurn off move detection. This can be used to override configuration\n \tsettings. It is the same as `--color-moved=no`.\n \n---color-moved-ws=<modes>::\n+`--color-moved-ws=<mode>,...`::\n \tThis configures how whitespace is ignored when performing the\n \tmove detection for `--color-moved`.\n ifdef::git-diff[]\n@@ -419,63 +420,62 @@ endif::git-diff[]\n \tThese modes can be given as a comma separated list:\n +\n --\n-no::\n+`no`::\n \tDo not ignore whitespace when performing move detection.\n-ignore-space-at-eol::\n+`ignore-space-at-eol`::\n \tIgnore changes in whitespace at EOL.\n-ignore-space-change::\n+`ignore-space-change`::\n \tIgnore changes in amount of whitespace.  This ignores whitespace\n \tat line end, and considers all other sequences of one or\n \tmore whitespace characters to be equivalent.\n-ignore-all-space::\n+`ignore-all-space`::\n \tIgnore whitespace when comparing lines. This ignores differences\n \teven if one line has whitespace where the other line has none.\n-allow-indentation-change::\n+`allow-indentation-change`::\n \tInitially ignore any whitespace in the move detection, then\n \tgroup the moved code blocks only into a block if the change in\n \twhitespace is the same per line. This is incompatible with the\n \tother modes.\n --\n \n---no-color-moved-ws::\n+`--no-color-moved-ws`::\n \tDo not ignore whitespace when performing move detection. This can be\n \tused to override configuration settings. It is the same as\n \t`--color-moved-ws=no`.\n \n---word-diff[=<mode>]::\n-\tShow a word diff, using the <mode> to delimit changed words.\n+`--word-diff[=<mode>]`::\n \tBy default, words are delimited by whitespace; see\n-\t`--word-diff-regex` below.  The <mode> defaults to 'plain', and\n+\t`--word-diff-regex` below.  The _<mode>_ defaults to `plain`, and\n \tmust be one of:\n +\n --\n-color::\n+`color`::\n \tHighlight changed words using only colors.  Implies `--color`.\n-plain::\n-\tShow words as `[-removed-]` and `{+added+}`.  Makes no\n+`plain`::\n+\tShow words as ++[-removed-]++ and ++{+added+}++.  Makes no\n \tattempts to escape the delimiters if they appear in the input,\n \tso the output may be ambiguous.\n-porcelain::\n+`porcelain`::\n \tUse a special line-based format intended for script\n \tconsumption.  Added/removed/unchanged runs are printed in the\n \tusual unified diff format, starting with a `+`/`-`/` `\n \tcharacter at the beginning of the line and extending to the\n \tend of the line.  Newlines in the input are represented by a\n \ttilde `~` on a line of its own.\n-none::\n+`none`::\n \tDisable word diff again.\n --\n +\n Note that despite the name of the first mode, color is used to\n highlight the changed parts in all modes if enabled.\n \n---word-diff-regex=<regex>::\n-\tUse <regex> to decide what a word is, instead of considering\n+`--word-diff-regex=<regex>`::\n+\tUse _<regex>_ to decide what a word is, instead of considering\n \truns of non-whitespace to be a word.  Also implies\n \t`--word-diff` unless it was already enabled.\n +\n Every non-overlapping match of the\n-<regex> is considered a word.  Anything between these matches is\n+_<regex>_ is considered a word.  Anything between these matches is\n considered whitespace and ignored(!) for the purposes of finding\n differences.  You may want to append `|[^[:space:]]` to your regular\n expression to make sure that it matches all non-whitespace characters.\n@@ -490,20 +490,20 @@ linkgit:gitattributes[5] or linkgit:git-config[1].  Giving it explicitly\n overrides any diff driver or configuration setting.  Diff drivers\n override configuration settings.\n \n---color-words[=<regex>]::\n+`--color-words[=<regex>]`::\n \tEquivalent to `--word-diff=color` plus (if a regex was\n \tspecified) `--word-diff-regex=<regex>`.\n endif::git-format-patch[]\n \n---no-renames::\n+`--no-renames`::\n \tTurn off rename detection, even when the configuration\n \tfile gives the default to do so.\n \n---[no-]rename-empty::\n+`--[no-]rename-empty`::\n \tWhether to use empty blobs as rename source.\n \n ifndef::git-format-patch[]\n---check::\n+`--check`::\n \tWarn if changes introduce conflict markers or whitespace errors.\n \tWhat are considered whitespace errors is controlled by `core.whitespace`\n \tconfiguration.  By default, trailing whitespaces (including\n@@ -511,9 +511,9 @@ ifndef::git-format-patch[]\n \tthat is immediately followed by a tab character inside the\n \tinitial indent of the line are considered whitespace errors.\n \tExits with non-zero status if problems are found. Not compatible\n-\twith --exit-code.\n+\twith `--exit-code`.\n \n---ws-error-highlight=<kind>::\n+`--ws-error-highlight=<kind>`::\n \tHighlight whitespace errors in the `context`, `old` or `new`\n \tlines of the diff.  Multiple values are separated by comma,\n \t`none` resets previous values, `default` reset the list to\n@@ -525,30 +525,30 @@ ifndef::git-format-patch[]\n \n endif::git-format-patch[]\n \n---full-index::\n+`--full-index`::\n \tInstead of the first handful of characters, show the full\n \tpre- and post-image blob object names on the \"index\"\n \tline when generating patch format output.\n \n---binary::\n+`--binary`::\n \tIn addition to `--full-index`, output a binary diff that\n \tcan be applied with `git-apply`.\n ifndef::git-format-patch[]\n \tImplies `--patch`.\n endif::git-format-patch[]\n \n---abbrev[=<n>]::\n+`--abbrev[=<n>]`::\n \tInstead of showing the full 40-byte hexadecimal object\n \tname in diff-raw format output and diff-tree header\n-\tlines, show the shortest prefix that is at least '<n>'\n+\tlines, show the shortest prefix that is at least _<n>_\n \thexdigits long that uniquely refers the object.\n \tIn diff-patch output format, `--full-index` takes higher\n \tprecedence, i.e. if `--full-index` is specified, full blob\n \tnames will be shown regardless of `--abbrev`.\n \tNon default number of digits can be specified with `--abbrev=<n>`.\n \n--B[<n>][/<m>]::\n---break-rewrites[=[<n>][/<m>]]::\n+`-B[<n>][/<m>]`::\n+`--break-rewrites[=[<n>][/<m>]]`::\n \tBreak complete rewrite changes into pairs of delete and\n \tcreate. This serves two purposes:\n +\n@@ -556,22 +556,22 @@ It affects the way a change that amounts to a total rewrite of a file\n not as a series of deletion and insertion mixed together with a very\n few lines that happen to match textually as the context, but as a\n single deletion of everything old followed by a single insertion of\n-everything new, and the number `m` controls this aspect of the -B\n+everything new, and the number _<m>_ controls this aspect of the `-B`\n option (defaults to 60%). `-B/70%` specifies that less than 30% of the\n original should remain in the result for Git to consider it a total\n rewrite (i.e. otherwise the resulting patch will be a series of\n deletion and insertion mixed together with context lines).\n +\n-When used with -M, a totally-rewritten file is also considered as the\n-source of a rename (usually -M only considers a file that disappeared\n-as the source of a rename), and the number `n` controls this aspect of\n-the -B option (defaults to 50%). `-B20%` specifies that a change with\n+When used with `-M`, a totally-rewritten file is also considered as the\n+source of a rename (usually `-M` only considers a file that disappeared\n+as the source of a rename), and the number _<n>_ controls this aspect of\n+the `-B` option (defaults to 50%). `-B20%` specifies that a change with\n addition and deletion compared to 20% or more of the file's size are\n eligible for being picked up as a possible source of a rename to\n another file.\n \n--M[<n>]::\n---find-renames[=<n>]::\n+`-M[<n>]`::\n+`--find-renames[=<n>]`::\n ifndef::git-log[]\n \tDetect renames.\n endif::git-log[]\n@@ -580,7 +580,7 @@ ifdef::git-log[]\n \tFor following files across renames while traversing history, see\n \t`--follow`.\n endif::git-log[]\n-\tIf `n` is specified, it is a threshold on the similarity\n+\tIf _<n>_ is specified, it is a threshold on the similarity\n \tindex (i.e. amount of addition/deletions compared to the\n \tfile's size). For example, `-M90%` means Git should consider a\n \tdelete/add pair to be a rename if more than 90% of the file\n@@ -590,12 +590,12 @@ endif::git-log[]\n \tthe same as `-M5%`.  To limit detection to exact renames, use\n \t`-M100%`.  The default similarity index is 50%.\n \n--C[<n>]::\n---find-copies[=<n>]::\n+`-C[<n>]`::\n+`--find-copies[=<n>]`::\n \tDetect copies as well as renames.  See also `--find-copies-harder`.\n-\tIf `n` is specified, it has the same meaning as for `-M<n>`.\n+\tIf _<n>_ is specified, it has the same meaning as for `-M<n>`.\n \n---find-copies-harder::\n+`--find-copies-harder`::\n \tFor performance reasons, by default, `-C` option finds copies only\n \tif the original file of the copy was modified in the same\n \tchangeset.  This flag makes the command\n@@ -604,8 +604,8 @@ endif::git-log[]\n \tprojects, so use it with caution.  Giving more than one\n \t`-C` option has the same effect.\n \n--D::\n---irreversible-delete::\n+`-D`::\n+`--irreversible-delete`::\n \tOmit the preimage for deletes, i.e. print only the header but not\n \tthe diff between the preimage and `/dev/null`. The resulting patch\n \tis not meant to be applied with `patch` or `git apply`; this is\n@@ -617,7 +617,7 @@ endif::git-log[]\n When used together with `-B`, omit also the preimage in the deletion part\n of a delete/create pair.\n \n--l<num>::\n+`-l<num>`::\n \tThe `-M` and `-C` options involve some preliminary steps that\n \tcan detect subsets of renames/copies cheaply, followed by an\n \texhaustive fallback portion that compares all remaining\n@@ -627,11 +627,11 @@ of a delete/create pair.\n \tdestinations, this exhaustive check is O(N^2).  This option\n \tprevents the exhaustive portion of rename/copy detection from\n \trunning if the number of source/destination files involved\n-\texceeds the specified number.  Defaults to diff.renameLimit.\n+\texceeds the specified number.  Defaults to `diff.renameLimit`.\n \tNote that a value of 0 is treated as unlimited.\n \n ifndef::git-format-patch[]\n---diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]::\n+`--diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]`::\n \tSelect only files that are Added (`A`), Copied (`C`),\n \tDeleted (`D`), Modified (`M`), Renamed (`R`), have their\n \ttype (i.e. regular file, symlink, submodule, ...) changed (`T`),\n@@ -649,9 +649,9 @@ Also, these upper-case letters can be downcased to exclude.  E.g.\n Note that not all diffs can feature all types. For instance, copied and\n renamed entries cannot appear if detection for those types is disabled.\n \n--S<string>::\n+`-S<string>`::\n \tLook for differences that change the number of occurrences of\n-\tthe specified string (i.e. addition/deletion) in a file.\n+\tthe specified _<string>_ (i.e. addition/deletion) in a file.\n \tIntended for the scripter's use.\n +\n It is useful when you're looking for an exact block of code (like a\n@@ -662,11 +662,11 @@ very first version of the block.\n +\n Binary files are searched as well.\n \n--G<regex>::\n+`-G<regex>`::\n \tLook for differences whose patch text contains added/removed\n-\tlines that match <regex>.\n+\tlines that match _<regex>_.\n +\n-To illustrate the difference between `-S<regex> --pickaxe-regex` and\n+To illustrate the difference between `-S<regex>` `--pickaxe-regex` and\n `-G<regex>`, consider a commit with the following diff in the same\n file:\n +\n@@ -686,7 +686,7 @@ filter will be ignored.\n See the 'pickaxe' entry in linkgit:gitdiffcore[7] for more\n information.\n \n---find-object=<object-id>::\n+`--find-object=<object-id>`::\n \tLook for differences that change the number of occurrences of\n \tthe specified object. Similar to `-S`, just the argument is different\n \tin that it doesn't search for a specific string but for a specific\n@@ -695,25 +695,25 @@ information.\n The object can be a blob or a submodule commit. It implies the `-t` option in\n `git-log` to also find trees.\n \n---pickaxe-all::\n+`--pickaxe-all`::\n \tWhen `-S` or `-G` finds a change, show all the changes in that\n \tchangeset, not just the files that contain the change\n-\tin <string>.\n+\tin _<string>_.\n \n---pickaxe-regex::\n-\tTreat the <string> given to `-S` as an extended POSIX regular\n+`--pickaxe-regex`::\n+\tTreat the _<string>_ given to `-S` as an extended POSIX regular\n \texpression to match.\n \n endif::git-format-patch[]\n \n--O<orderfile>::\n+`-O<orderfile>`::\n \tControl the order in which files appear in the output.\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 +\n The output order is determined by the order of glob patterns in\n-<orderfile>.\n+_<orderfile>_.\n All files with pathnames that match the first pattern are output\n first, all files with pathnames that match the second pattern (but not\n the first) are output next, and so on.\n@@ -724,7 +724,7 @@ If multiple pathnames have the same rank (they match the same pattern\n but no earlier patterns), their output order relative to each other is\n the normal order.\n +\n-<orderfile> is parsed as follows:\n+_<orderfile>_ is parsed as follows:\n +\n --\n  - Blank lines are ignored, so they can be used as separators for\n@@ -738,106 +738,107 @@ the normal order.\n --\n +\n Patterns have the same syntax and semantics as patterns used for\n-fnmatch(3) without the FNM_PATHNAME flag, except a pathname also\n+`fnmatch`(3) without the `FNM_PATHNAME` flag, except a pathname also\n matches a pattern if removing any number of the final pathname\n components matches the pattern.  For example, the pattern \"`foo*bar`\"\n matches \"`fooasdfbar`\" and \"`foo/bar/baz/asdf`\" but not \"`foobarx`\".\n \n---skip-to=<file>::\n---rotate-to=<file>::\n-\tDiscard the files before the named <file> from the output\n+`--skip-to=<file>`::\n+`--rotate-to=<file>`::\n+\tDiscard the files before the named _<file>_ from the output\n \t(i.e. 'skip to'), or move them to the end of the output\n \t(i.e. 'rotate to').  These options were invented primarily for the use\n \tof the `git difftool` command, and may not be very useful\n \totherwise.\n \n ifndef::git-format-patch[]\n--R::\n+`-R`::\n \tSwap two inputs; that is, show differences from index or\n \ton-disk file to tree contents.\n endif::git-format-patch[]\n \n---relative[=<path>]::\n---no-relative::\n+`--relative[=<path>]`::\n+`--no-relative`::\n \tWhen run from a subdirectory of the project, it can be\n \ttold to exclude changes outside the directory and show\n \tpathnames relative to it with this option.  When you are\n \tnot in a subdirectory (e.g. in a bare repository), you\n \tcan name which subdirectory to make the output relative\n-\tto by giving a <path> as an argument.\n+\tto by giving a _<path>_ as an argument.\n \t`--no-relative` can be used to countermand both `diff.relative` config\n \toption and previous `--relative`.\n \n--a::\n---text::\n+`-a`::\n+`--text`::\n \tTreat all files as text.\n \n---ignore-cr-at-eol::\n+`--ignore-cr-at-eol`::\n \tIgnore carriage-return at the end of line when doing a comparison.\n \n---ignore-space-at-eol::\n+`--ignore-space-at-eol`::\n \tIgnore changes in whitespace at EOL.\n \n--b::\n---ignore-space-change::\n+`-b`::\n+`--ignore-space-change`::\n \tIgnore changes in amount of whitespace.  This ignores whitespace\n \tat line end, and considers all other sequences of one or\n \tmore whitespace characters to be equivalent.\n \n--w::\n---ignore-all-space::\n+`-w`::\n+`--ignore-all-space`::\n \tIgnore whitespace when comparing lines.  This ignores\n \tdifferences even if one line has whitespace where the other\n \tline has none.\n \n---ignore-blank-lines::\n+`--ignore-blank-lines`::\n \tIgnore changes whose lines are all blank.\n \n--I<regex>::\n---ignore-matching-lines=<regex>::\n-\tIgnore changes whose all lines match <regex>.  This option may\n+\n+`-I<regex>`::\n+`--ignore-matching-lines=<regex>`::\n+\tIgnore changes whose all lines match _<regex>_.  This option may\n \tbe specified more than once.\n \n---inter-hunk-context=<lines>::\n-\tShow the context between diff hunks, up to the specified number\n+`--inter-hunk-context=<number>`::\n+\tShow the context between diff hunks, up to the specified _<number>_\n \tof lines, thereby fusing hunks that are close to each other.\n \tDefaults to `diff.interHunkContext` or 0 if the config option\n \tis unset.\n \n--W::\n---function-context::\n+`-W`::\n+`--function-context`::\n \tShow whole function as context lines for each change.\n \tThe function names are determined in the same way as\n-\t`git diff` works out patch hunk headers (see 'Defining a\n-\tcustom hunk-header' in linkgit:gitattributes[5]).\n+\t`git diff` works out patch hunk headers (see \"Defining a\n+\tcustom hunk-header\" in linkgit:gitattributes[5]).\n \n ifndef::git-format-patch[]\n ifndef::git-log[]\n---exit-code::\n-\tMake the program exit with codes similar to diff(1).\n+`--exit-code`::\n+\tMake the program exit with codes similar to `diff`(1).\n \tThat is, it exits with 1 if there were differences and\n \t0 means no differences.\n \n---quiet::\n+`--quiet`::\n \tDisable all output of the program. Implies `--exit-code`.\n \tDisables execution of external diff helpers whose exit code\n \tis not trusted, i.e. their respective configuration option\n-\t`diff.trustExitCode` or `diff.<driver>.trustExitCode` or\n+\t`diff.trustExitCode` or ++diff.++__<driver>__++.trustExitCode++ or\n \tenvironment variable `GIT_EXTERNAL_DIFF_TRUST_EXIT_CODE` is\n \tfalse.\n endif::git-log[]\n endif::git-format-patch[]\n \n---ext-diff::\n+`--ext-diff`::\n \tAllow an external diff helper to be executed. If you set an\n \texternal diff driver with linkgit:gitattributes[5], you need\n \tto use this option with linkgit:git-log[1] and friends.\n \n---no-ext-diff::\n+`--no-ext-diff`::\n \tDisallow external diff drivers.\n \n---textconv::\n---no-textconv::\n+`--textconv`::\n+`--no-textconv`::\n \tAllow (or disallow) external text conversion filters to be run\n \twhen comparing binary files. See linkgit:gitattributes[5] for\n \tdetails. Because textconv filters are typically a one-way\n@@ -847,42 +848,42 @@ endif::git-format-patch[]\n \tlinkgit:git-log[1], but not for linkgit:git-format-patch[1] or\n \tdiff plumbing commands.\n \n---ignore-submodules[=<when>]::\n-\tIgnore changes to submodules in the diff generation. <when> can be\n-\teither \"none\", \"untracked\", \"dirty\" or \"all\", which is the default.\n-\tUsing \"none\" will consider the submodule modified when it either contains\n-\tuntracked or modified files or its HEAD differs from the commit recorded\n+\n+`--ignore-submodules[=(none|untracked|dirty|all)]`::\n+\tIgnore changes to submodules in the diff generation. `all` is the default.\n+\tUsing `none` will consider the submodule modified when it either contains\n+\tuntracked or modified files or its `HEAD` differs from the commit recorded\n \tin the superproject and can be used to override any settings of the\n-\t'ignore' option in linkgit:git-config[1] or linkgit:gitmodules[5]. When\n-\t\"untracked\" is used submodules are not considered dirty when they only\n+\t`ignore` option in linkgit:git-config[1] or linkgit:gitmodules[5]. When\n+\t`untracked` is used submodules are not considered dirty when they only\n \tcontain untracked content (but they are still scanned for modified\n-\tcontent). Using \"dirty\" ignores all changes to the work tree of submodules,\n+\tcontent). Using `dirty` ignores all changes to the work tree of submodules,\n \tonly changes to the commits stored in the superproject are shown (this was\n-\tthe behavior until 1.7.0). Using \"all\" hides all changes to submodules.\n+\tthe behavior until 1.7.0). Using `all` hides all changes to submodules.\n \n---src-prefix=<prefix>::\n-\tShow the given source prefix instead of \"a/\".\n+`--src-prefix=<prefix>`::\n+\tShow the given source _<prefix>_ instead of \"a/\".\n \n---dst-prefix=<prefix>::\n-\tShow the given destination prefix instead of \"b/\".\n+`--dst-prefix=<prefix>`::\n+\tShow the given destination _<prefix>_ instead of \"b/\".\n \n---no-prefix::\n+`--no-prefix`::\n \tDo not show any source or destination prefix.\n \n---default-prefix::\n+`--default-prefix`::\n \tUse the default source and destination prefixes (\"a/\" and \"b/\").\n \tThis overrides configuration variables such as `diff.noprefix`,\n \t`diff.srcPrefix`, `diff.dstPrefix`, and `diff.mnemonicPrefix`\n-\t(see `git-config`(1)).\n+\t(see linkgit:git-config[1]).\n \n---line-prefix=<prefix>::\n-\tPrepend an additional prefix to every line of output.\n+`--line-prefix=<prefix>`::\n+\tPrepend an additional _<prefix>_ to every line of output.\n \n---ita-invisible-in-index::\n-\tBy default entries added by \"git add -N\" appear as an existing\n-\tempty file in \"git diff\" and a new file in \"git diff --cached\".\n-\tThis option makes the entry appear as a new file in \"git diff\"\n-\tand non-existent in \"git diff --cached\". This option could be\n+`--ita-invisible-in-index`::\n+\tBy default entries added by `git add -N` appear as an existing\n+\tempty file in `git diff` and a new file in `git diff --cached`.\n+\tThis option makes the entry appear as a new file in `git diff`\n+\tand non-existent in `git diff --cached`. This option could be\n \treverted with `--ita-visible-in-index`. Both options are\n \texperimental and could be removed in future.\n \n-- \ngitgitgadget\n\n"},{"id":"507060","messageId":"daed146639dee800531a477bbb8d4b6f7f5bf0d8.1731343985.git.gitgitgadget@gmail.com","threadId":"61899","inReplyTo":"pull.1769.v2.git.1731343985.gitgitgadget@gmail.com","subject":"[PATCH v2 4/5] doc: git-diff: apply format changes to diff-generate-patch","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-11-11T16:53:04Z","receivedAt":"2024-11-11T16:53:12Z","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/diff-generate-patch.txt | 44 ++++++++++++++-------------\n 1 file changed, 23 insertions(+), 21 deletions(-)\n\ndiff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-generate-patch.txt\nindex 4b5aa5c2e04..e5c813c96f3 100644\n--- a/Documentation/diff-generate-patch.txt\n+++ b/Documentation/diff-generate-patch.txt\n@@ -14,7 +14,7 @@ You can customize the creation of patch text via the\n `GIT_EXTERNAL_DIFF` and the `GIT_DIFF_OPTS` environment variables\n (see linkgit:git[1]), and the `diff` attribute (see linkgit:gitattributes[5]).\n \n-What the -p option produces is slightly different from the traditional\n+What the `-p` option produces is slightly different from the traditional\n diff format:\n \n 1.   It is preceded by a \"git diff\" header that looks like this:\n@@ -30,20 +30,21 @@ name of the source file of the rename/copy and the name of\n the file that the rename/copy produces, respectively.\n \n 2.   It is followed by one or more extended header lines:\n-\n-       old mode <mode>\n-       new mode <mode>\n-       deleted file mode <mode>\n-       new file mode <mode>\n-       copy from <path>\n-       copy to <path>\n-       rename from <path>\n-       rename to <path>\n-       similarity index <number>\n-       dissimilarity index <number>\n-       index <hash>..<hash> <mode>\n +\n-File modes are printed as 6-digit octal numbers including the file type\n+[synopsis]\n+old mode <mode>\n+new mode <mode>\n+deleted file mode <mode>\n+new file mode <mode>\n+copy from <path>\n+copy to <path>\n+rename from <path>\n+rename to <path>\n+similarity index <number>\n+dissimilarity index <number>\n+index <hash>..<hash> <mode>\n++\n+File modes _<mode>_ are printed as 6-digit octal numbers including the file type\n and file permission bits.\n +\n Path names in extended headers do not include the `a/` and `b/` prefixes.\n@@ -56,7 +57,7 @@ files, while 100% dissimilarity means that no line from the old\n file made it into the new one.\n +\n The index line includes the blob object names before and after the change.\n-The <mode> is included if the file mode does not change; otherwise,\n+The _<mode>_ is included if the file mode does not change; otherwise,\n separate lines indicate the old and the new mode.\n \n 3.  Pathnames with \"unusual\" characters are quoted as explained for\n@@ -134,17 +135,18 @@ or like this (when the `--cc` option is used):\n \n 2.   It is followed by one or more extended header lines\n      (this example shows a merge with two parents):\n-\n-       index <hash>,<hash>..<hash>\n-       mode <mode>,<mode>..<mode>\n-       new file mode <mode>\n-       deleted file mode <mode>,<mode>\n++\n+[synopsis]\n+index <hash>,<hash>..<hash>\n+mode <mode>,<mode>`..`<mode>\n+new file mode <mode>\n+deleted file mode <mode>,<mode>\n +\n The `mode <mode>,<mode>..<mode>` line appears only if at least one of\n the <mode> is different from the rest. Extended headers with\n information about detected content movement (renames and\n copying detection) are designed to work with the diff of two\n-<tree-ish> and are not used by combined diff format.\n+_<tree-ish>_ and are not used by combined diff format.\n \n 3.   It is followed by a two-line from-file/to-file header:\n \n-- \ngitgitgadget\n\n"},{"id":"507061","messageId":"8fec37ee17481039998af65ce1abec753cf30897.1731343985.git.gitgitgadget@gmail.com","threadId":"61899","inReplyTo":"pull.1769.v2.git.1731343985.gitgitgadget@gmail.com","subject":"[PATCH v2 3/5] doc: git-diff: apply format changes to diff-format","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-11-11T16:53:03Z","receivedAt":"2024-11-11T16:53: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\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\n---\n Documentation/diff-format.txt | 42 +++++++++++++++++------------------\n 1 file changed, 21 insertions(+), 21 deletions(-)\n\ndiff --git a/Documentation/diff-format.txt b/Documentation/diff-format.txt\nindex a3ae8747a22..c72fb379867 100644\n--- a/Documentation/diff-format.txt\n+++ b/Documentation/diff-format.txt\n@@ -1,25 +1,25 @@\n Raw output format\n -----------------\n \n-The raw output format from \"git-diff-index\", \"git-diff-tree\",\n-\"git-diff-files\" and \"git diff --raw\" are very similar.\n+The raw output format from `git-diff-index`, `git-diff-tree`,\n+`git-diff-files` and `git diff --raw` are very similar.\n \n These commands all compare two sets of things; what is\n compared differs:\n \n-git-diff-index <tree-ish>::\n-        compares the <tree-ish> and the files on the filesystem.\n+`git-diff-index <tree-ish>`::\n+\tcompares the _<tree-ish>_ and the files on the filesystem.\n \n-git-diff-index --cached <tree-ish>::\n-        compares the <tree-ish> and the index.\n+`git-diff-index --cached <tree-ish>`::\n+\tcompares the _<tree-ish>_ and the index.\n \n-git-diff-tree [-r] <tree-ish-1> <tree-ish-2> [<pattern>...]::\n+`git-diff-tree [-r] <tree-ish-1> <tree-ish-2> [<pattern>...]`::\n         compares the trees named by the two arguments.\n \n-git-diff-files [<pattern>...]::\n+`git-diff-files [<pattern>...]`::\n         compares the index and the files on the filesystem.\n \n-The \"git-diff-tree\" command begins its output by printing the hash of\n+The `git-diff-tree` command begins its output by printing the hash of\n what is being compared. After that, all the commands print one output\n line per changed file.\n \n@@ -54,19 +54,19 @@ That is, from the left to the right:\n \n Possible status letters are:\n \n-- A: addition of a file\n-- C: copy of a file into a new one\n-- D: deletion of a file\n-- M: modification of the contents or mode of a file\n-- R: renaming of a file\n-- T: change in the type of the file (regular file, symbolic link or submodule)\n-- U: file is unmerged (you must complete the merge before it can\n+- `A`: addition of a file\n+- `C`: copy of a file into a new one\n+- `D`: deletion of a file\n+- `M`: modification of the contents or mode of a file\n+- `R`: renaming of a file\n+- `T`: change in the type of the file (regular file, symbolic link or submodule)\n+- `U`: file is unmerged (you must complete the merge before it can\n   be committed)\n-- X: \"unknown\" change type (most probably a bug, please report it)\n+- `X`: \"unknown\" change type (most probably a bug, please report it)\n \n-Status letters C and R are always followed by a score (denoting the\n+Status letters `C` and `R` are always followed by a score (denoting the\n percentage of similarity between the source and target of the move or\n-copy).  Status letter M may be followed by a score (denoting the\n+copy).  Status letter `M` may be followed by a score (denoting the\n percentage of dissimilarity) for file rewrites.\n \n The sha1 for \"dst\" is shown as all 0's if a file on the filesystem\n@@ -86,7 +86,7 @@ verbatim and the line is terminated by a NUL byte.\n diff format for merges\n ----------------------\n \n-\"git-diff-tree\", \"git-diff-files\" and \"git-diff --raw\"\n+`git-diff-tree`, `git-diff-files` and `git-diff --raw`\n can take `-c` or `--cc` option\n to generate diff output also for merge commits.  The output differs\n from the format described above in the following way:\n@@ -128,7 +128,7 @@ other diff formats\n ------------------\n \n The `--summary` option describes newly added, deleted, renamed and\n-copied files.  The `--stat` option adds diffstat(1) graph to the\n+copied files.  The `--stat` option adds `diffstat`(1) graph to the\n output.  These options can be combined with other options, such as\n `-p`, and are meant for human consumption.\n \n-- \ngitgitgadget\n\n"},{"id":"507062","messageId":"17a2f028d59a0097e92229c2b934a69974691e79.1731343985.git.gitgitgadget@gmail.com","threadId":"61899","inReplyTo":"pull.1769.v2.git.1731343985.gitgitgadget@gmail.com","subject":"[PATCH v2 5/5] doc: git-diff: apply format changes to config part","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-11-11T16:53:05Z","receivedAt":"2024-11-11T16:53: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\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\n---\n Documentation/config/diff.txt | 163 +++++++++++++++++-----------------\n 1 file changed, 82 insertions(+), 81 deletions(-)\n\ndiff --git a/Documentation/config/diff.txt b/Documentation/config/diff.txt\nindex 190bda17e51..e60c19292da 100644\n--- a/Documentation/config/diff.txt\n+++ b/Documentation/config/diff.txt\n@@ -1,18 +1,18 @@\n-diff.autoRefreshIndex::\n-\tWhen using 'git diff' to compare with work tree\n+`diff.autoRefreshIndex`::\n+\tWhen using `git diff` to compare with work tree\n \tfiles, do not consider stat-only changes as changed.\n \tInstead, silently run `git update-index --refresh` to\n \tupdate the cached stat information for paths whose\n \tcontents in the work tree match the contents in the\n \tindex.  This option defaults to true.  Note that this\n-\taffects only 'git diff' Porcelain, and not lower level\n-\t'diff' commands such as 'git diff-files'.\n+\taffects only `git diff` Porcelain, and not lower level\n+\t`diff` commands such as '`git diff-files`.\n \n-diff.dirstat::\n+`diff.dirstat`::\n \tA comma separated list of `--dirstat` parameters specifying the\n \tdefault behavior of the `--dirstat` option to linkgit:git-diff[1]\n \tand friends. The defaults can be overridden on the command line\n-\t(using `--dirstat=<param1,param2,...>`). The fallback defaults\n+\t(using `--dirstat=<param>,...`). The fallback defaults\n \t(when not changed by `diff.dirstat`) are `changes,noncumulative,3`.\n \tThe following parameters are available:\n +\n@@ -41,7 +41,7 @@ diff.dirstat::\n \tNote that when using `cumulative`, the sum of the percentages\n \treported may exceed 100%. The default (non-cumulative) behavior can\n \tbe specified with the `noncumulative` parameter.\n-<limit>;;\n+_<limit>_;;\n \tAn integer parameter specifies a cut-off percent (3% by default).\n \tDirectories contributing less than this percentage of the changes\n \tare not shown in the output.\n@@ -52,57 +52,57 @@ directories with less than 10% of the total amount of changed files,\n and accumulating child directory counts in the parent directories:\n `files,10,cumulative`.\n \n-diff.statNameWidth::\n-\tLimit the width of the filename part in --stat output. If set, applies\n-\tto all commands generating --stat output except format-patch.\n+`diff.statNameWidth`::\n+\tLimit the width of the filename part in `--stat` output. If set, applies\n+\tto all commands generating `--stat` output except `format-patch`.\n \n-diff.statGraphWidth::\n-\tLimit the width of the graph part in --stat output. If set, applies\n-\tto all commands generating --stat output except format-patch.\n+`diff.statGraphWidth`::\n+\tLimit the width of the graph part in `--stat` output. If set, applies\n+\tto all commands generating `--stat` output except `format-patch`.\n \n-diff.context::\n-\tGenerate diffs with <n> lines of context instead of the default\n-\tof 3. This value is overridden by the -U option.\n+`diff.context`::\n+\tGenerate diffs with _<n>_ lines of context instead of the default\n+\tof 3. This value is overridden by the `-U` option.\n \n-diff.interHunkContext::\n+`diff.interHunkContext`::\n \tShow the context between diff hunks, up to the specified number\n \tof lines, thereby fusing the hunks that are close to each other.\n \tThis value serves as the default for the `--inter-hunk-context`\n \tcommand line option.\n \n-diff.external::\n+`diff.external`::\n \tIf this config variable is set, diff generation is not\n \tperformed using the internal diff machinery, but using the\n-\tgiven command.  Can be overridden with the `GIT_EXTERNAL_DIFF'\n+\tgiven command.  Can be overridden with the `GIT_EXTERNAL_DIFF`\n \tenvironment variable.  The command is called with parameters\n \tas described under \"git Diffs\" in linkgit:git[1].  Note: if\n \tyou want to use an external diff program only on a subset of\n \tyour files, you might want to use linkgit:gitattributes[5] instead.\n \n-diff.trustExitCode::\n-\tIf this boolean value is set to true then the\n+`diff.trustExitCode`::\n+\tIf this boolean value is set to `true` then the\n \t`diff.external` command is expected to return exit code\n \t0 if it considers the input files to be equal or 1 if it\n-\tconsiders them to be different, like `diff(1)`.\n-\tIf it is set to false, which is the default, then the command\n-\tis expected to return exit code 0 regardless of equality.\n+\tconsiders them to be different, like `diff`(1).\n+\tIf it is set to `false`, which is the default, then the command\n+\tis expected to return exit code `0` regardless of equality.\n \tAny other exit code causes Git to report a fatal error.\n \n-diff.ignoreSubmodules::\n-\tSets the default value of --ignore-submodules. Note that this\n-\taffects only 'git diff' Porcelain, and not lower level 'diff'\n-\tcommands such as 'git diff-files'. 'git checkout'\n-\tand 'git switch' also honor\n+`diff.ignoreSubmodules`::\n+\tSets the default value of `--ignore-submodules`. Note that this\n+\taffects only `git diff` Porcelain, and not lower level `diff`\n+\tcommands such as `git diff-files`. `git checkout`\n+\tand `git switch` also honor\n \tthis setting when reporting uncommitted changes. Setting it to\n-\t'all' disables the submodule summary normally shown by 'git commit'\n-\tand 'git status' when `status.submoduleSummary` is set unless it is\n-\toverridden by using the --ignore-submodules command-line option.\n-\tThe 'git submodule' commands are not affected by this setting.\n+\t`all` disables the submodule summary normally shown by `git commit`\n+\tand `git status` when `status.submoduleSummary` is set unless it is\n+\toverridden by using the `--ignore-submodules` command-line option.\n+\tThe `git submodule` commands are not affected by this setting.\n \tBy default this is set to untracked so that any untracked\n \tsubmodules are ignored.\n \n-diff.mnemonicPrefix::\n-\tIf set, 'git diff' uses a prefix pair that is different from the\n+`diff.mnemonicPrefix`::\n+\tIf set, `git diff` uses a prefix pair that is different from the\n \tstandard \"a/\" and \"b/\" depending on what is being compared.  When\n \tthis configuration is in effect, reverse diff output also swaps\n \tthe order of the prefixes:\n@@ -112,111 +112,112 @@ diff.mnemonicPrefix::\n \t compares a (c)ommit and the (w)ork tree;\n `git diff --cached`;;\n \tcompares a (c)ommit and the (i)ndex;\n-`git diff HEAD:file1 file2`;;\n+`git diff HEAD:<file1> <file2>`;;\n \tcompares an (o)bject and a (w)ork tree entity;\n `git diff --no-index a b`;;\n \tcompares two non-git things (1) and (2).\n \n-diff.noPrefix::\n-\tIf set, 'git diff' does not show any source or destination prefix.\n+`diff.noPrefix`::\n+\tIf set, `git diff` does not show any source or destination prefix.\n \n-diff.srcPrefix::\n-\tIf set, 'git diff' uses this source prefix. Defaults to \"a/\".\n+`diff.srcPrefix`::\n+\tIf set, `git diff` uses this source prefix. Defaults to \"a/\".\n \n-diff.dstPrefix::\n-\tIf set, 'git diff' uses this destination prefix. Defaults to \"b/\".\n+`diff.dstPrefix`::\n+\tIf set, `git diff` uses this destination prefix. Defaults to \"b/\".\n \n-diff.relative::\n-\tIf set to 'true', 'git diff' does not show changes outside of the directory\n+`diff.relative`::\n+\tIf set to `true`, `git diff` does not show changes outside of the directory\n \tand show pathnames relative to the current directory.\n \n-diff.orderFile::\n+`diff.orderFile`::\n \tFile indicating how to order files within a diff.\n-\tSee the '-O' option to linkgit:git-diff[1] for details.\n+\tSee the `-O` option to linkgit:git-diff[1] for details.\n \tIf `diff.orderFile` is a relative pathname, it is treated as\n \trelative to the top of the working tree.\n \n-diff.renameLimit::\n+`diff.renameLimit`::\n \tThe number of files to consider in the exhaustive portion of\n-\tcopy/rename detection; equivalent to the 'git diff' option\n+\tcopy/rename detection; equivalent to the `git diff` option\n \t`-l`.  If not set, the default value is currently 1000.  This\n \tsetting has no effect if rename detection is turned off.\n \n-diff.renames::\n-\tWhether and how Git detects renames.  If set to \"false\",\n-\trename detection is disabled. If set to \"true\", basic rename\n-\tdetection is enabled.  If set to \"copies\" or \"copy\", Git will\n+`diff.renames`::\n+\tWhether and how Git detects renames.  If set to `false`,\n+\trename detection is disabled. If set to `true`, basic rename\n+\tdetection is enabled.  If set to `copies` or `copy`, Git will\n \tdetect copies, as well.  Defaults to true.  Note that this\n-\taffects only 'git diff' Porcelain like linkgit:git-diff[1] and\n+\taffects only `git diff` Porcelain like linkgit:git-diff[1] and\n \tlinkgit:git-log[1], and not lower level commands such as\n \tlinkgit:git-diff-files[1].\n \n-diff.suppressBlankEmpty::\n+`diff.suppressBlankEmpty`::\n \tA boolean to inhibit the standard behavior of printing a space\n-\tbefore each empty output line. Defaults to false.\n+\tbefore each empty output line. Defaults to `false`.\n \n-diff.submodule::\n+`diff.submodule`::\n \tSpecify the format in which differences in submodules are\n-\tshown.  The \"short\" format just shows the names of the commits\n-\tat the beginning and end of the range. The \"log\" format lists\n+\tshown.  The `short` format just shows the names of the commits\n+\tat the beginning and end of the range. The `log` format lists\n \tthe commits in the range like linkgit:git-submodule[1] `summary`\n-\tdoes. The \"diff\" format shows an inline diff of the changed\n-\tcontents of the submodule. Defaults to \"short\".\n+\tdoes. The `diff` format shows an inline diff of the changed\n+\tcontents of the submodule. Defaults to `short`.\n \n-diff.wordRegex::\n+`diff.wordRegex`::\n \tA POSIX Extended Regular Expression used to determine what is a \"word\"\n \twhen performing word-by-word difference calculations.  Character\n \tsequences that match the regular expression are \"words\", all other\n \tcharacters are *ignorable* whitespace.\n \n-diff.<driver>.command::\n+`diff.<driver>.command`::\n \tThe custom diff driver command.  See linkgit:gitattributes[5]\n \tfor details.\n \n-diff.<driver>.trustExitCode::\n+`diff.<driver>.trustExitCode`::\n \tIf this boolean value is set to true then the\n \t`diff.<driver>.command` command is expected to return exit code\n \t0 if it considers the input files to be equal or 1 if it\n-\tconsiders them to be different, like `diff(1)`.\n+\tconsiders them to be different, like `diff`(1).\n \tIf it is set to false, which is the default, then the command\n \tis expected to return exit code 0 regardless of equality.\n \tAny other exit code causes Git to report a fatal error.\n \n-diff.<driver>.xfuncname::\n+`diff.<driver>.xfuncname`::\n \tThe regular expression that the diff driver should use to\n \trecognize the hunk header.  A built-in pattern may also be used.\n \tSee linkgit:gitattributes[5] for details.\n \n-diff.<driver>.binary::\n-\tSet this option to true to make the diff driver treat files as\n+`diff.<driver>.binary`::\n+\tSet this option to `true` to make the diff driver treat files as\n \tbinary.  See linkgit:gitattributes[5] for details.\n \n-diff.<driver>.textconv::\n+`diff.<driver>.textconv`::\n \tThe command that the diff driver should call to generate the\n \ttext-converted version of a file.  The result of the\n \tconversion is used to generate a human-readable diff.  See\n \tlinkgit:gitattributes[5] for details.\n \n-diff.<driver>.wordRegex::\n+`diff.<driver>.wordRegex`::\n \tThe regular expression that the diff driver should use to\n \tsplit words in a line.  See linkgit:gitattributes[5] for\n \tdetails.\n \n-diff.<driver>.cachetextconv::\n+`diff.<driver>.cachetextconv`::\n \tSet this option to true to make the diff driver cache the text\n \tconversion outputs.  See linkgit:gitattributes[5] for details.\n \n include::../mergetools-diff.txt[]\n \n-diff.indentHeuristic::\n+`diff.indentHeuristic`::\n \tSet this option to `false` to disable the default heuristics\n \tthat shift diff hunk boundaries to make patches easier to read.\n \n-diff.algorithm::\n+`diff.algorithm`::\n \tChoose a diff algorithm.  The variants are as follows:\n +\n --\n-`default`, `myers`;;\n+`default`;;\n+`myers`;;\n \tThe basic greedy diff algorithm. Currently, this is the default.\n `minimal`;;\n \tSpend extra time to make sure the smallest possible diff is\n@@ -229,7 +230,7 @@ diff.algorithm::\n --\n +\n \n-diff.wsErrorHighlight::\n+`diff.wsErrorHighlight`::\n \tHighlight whitespace errors in the `context`, `old` or `new`\n \tlines of the diff.  Multiple values are separated by comma,\n \t`none` resets previous values, `default` reset the list to\n@@ -238,14 +239,14 @@ diff.wsErrorHighlight::\n \tThe command line option `--ws-error-highlight=<kind>`\n \toverrides this setting.\n \n-diff.colorMoved::\n-\tIf set to either a valid `<mode>` or a true value, moved lines\n+`diff.colorMoved`::\n+\tIf set to either a valid _<mode>_ or a true value, moved lines\n \tin a diff are colored differently, for details of valid modes\n-\tsee '--color-moved' in linkgit:git-diff[1]. If simply set to\n-\ttrue the default color mode will be used. When set to false,\n+\tsee `--color-moved` in linkgit:git-diff[1]. If simply set to\n+\t`true` the default color mode will be used. When set to `false`,\n \tmoved lines are not colored.\n \n-diff.colorMovedWS::\n+`diff.colorMovedWS`::\n \tWhen moved lines are colored using e.g. the `diff.colorMoved` setting,\n-\tthis option controls the `<mode>` how spaces are treated.\n-\tFor details of valid modes see '--color-moved-ws' in linkgit:git-diff[1].\n+\tthis option controls the mode how spaces are treated.\n+\tFor details of valid modes see `--color-moved-ws` in linkgit:git-diff[1].\n-- \ngitgitgadget\n"},{"id":"507094","messageId":"xmqqo72l8egu.fsf@gitster.g","threadId":"61899","inReplyTo":"c104bd50b646646e980905a9294209f381b9e61c.1731343985.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 1/5] doc: git-diff: apply new documentation guidelines","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-11-12T00:48:01Z","receivedAt":"2024-11-12T00:48:04Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Jean-Noël Avila via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n\n> +[synopsis]\n> +git diff [<options>] [<commit>] [--] [<path>...]\n> +git diff [<options>] --cached [--merge-base] [<commit>] [--] [<path>...]\n> +git diff [<options>] [--merge-base] <commit> [<commit>...] <commit> [--] [<path>...]\n> +git diff [<options>] <commit>...<commit> [--] [<path>...]\n> +git diff [<options>] <blob> <blob>\n> +git diff [<options>] --no-index [--] <path> <path>\n\nAgain, not having to worry about `mark-up` _<rules>_ in SYNOPSIS section\nis very nice.\n\nYou may already have explained the rules elsewhere, but please\nhelp me refresh my memory with some explanation.\n\n> -'git diff' [<options>] [--] [<path>...]::\n> +`git diff [<options>] [--] [<path>...]`::\n\nHere, we just say `everything in literal, including placeholders`,\nwhich is very pleasant for us writers.\n\n> --1 --base::\n> --2 --ours::\n> --3 --theirs::\n> +`-1` `--base`::\n> +`-2` `--ours`::\n> +`-3` `--theirs`::\n\nWhy aren't these `-1 --base` and instead mark up individual tokens?\n\n> -<path>...::\n> -\tThe <paths> parameters, when given, are used to limit\n> +_<path>_...::\n\nThis has to do the _italics_ for placeholders, unlike the full\ncommand line examples we saw earlier?\n\nWhere does this difference come from?\n\nThanks.\n"},{"id":"507095","messageId":"xmqqh68d8e9h.fsf@gitster.g","threadId":"61899","inReplyTo":"129763c2aaefd92bddaa59601c5a3275b9defa36.1731343985.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 2/5] doc: git-diff: apply format changes to diff-options","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-11-12T00:52:26Z","receivedAt":"2024-11-12T00:52:29Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Jean-Noël Avila via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n\n> --s::\n> ---no-patch::\n> +`-s`::\n> +`--no-patch`::\n\nThese are understandable.  These dashed options that are to be given\nliterally are shown as `literal`.\n\n> @@ -39,28 +39,28 @@ endif::git-format-patch[]\n>  ifdef::git-log[]\n>  -m::\n\nShouldn't this and all others like -c/--cc be also quoted as\n`literal` options?\n\n> @@ -73,33 +73,33 @@ The following formats are supported:\n>  off, none::\n\nShouldn't this and other option values like on, first-parent, etc.,\nthat are literals be marked-up specially?\n\n> --U<n>::\n> ---unified=<n>::\n> -\tGenerate diffs with <n> lines of context instead of\n> +`-U<n>`::\n> +`--unified=<n>`::\n> +\tGenerate diffs with _<n>_ lines of context instead of\n\nUnderstandable.  Shouldn't <n> part be italicised?\n\n> ---output=<file>::\n> +`--output=<file>`::\n\nLikewise.\n\nThanks.\n"},{"id":"507118","messageId":"7b42828a-2cbe-47c6-b21e-b8c1e3a2ad01@free.fr","threadId":"61899","inReplyTo":"xmqqo72l8egu.fsf@gitster.g","subject":"Re: [PATCH v2 1/5] doc: git-diff: apply new documentation guidelines","fromName":"Jean-Noël Avila","fromEmail":"jn.avila@free.fr","sentAt":"2024-11-12T08:40:13Z","receivedAt":"2024-11-12T08:49:48Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"Le 12/11/2024 à 01:48, Junio C Hamano a écrit :\n> \"Jean-Noël Avila via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n\n> \n> You may already have explained the rules elsewhere, but please\n> help me refresh my memory with some explanation.\n> \n>> -'git diff' [<options>] [--] [<path>...]::\n>> +`git diff [<options>] [--] [<path>...]`::\n> \n> Here, we just say `everything in literal, including placeholders`,\n> which is very pleasant for us writers.\n\n\nWith the new document processor extension, the back tick quotes have\nbecome smarter and they behave basically like an inline synopsis\nsection. Here, this means that the line will be formatted roughly as\nfollows:\n\n`git diff` [_<options>_] [`--`] [_<path>_...]\n\nAll the keywords are literal, the placeholders are emphasized, and the\nsyntactic signs ('[', ']', '...') are left without formatting.\n\nThe general rule of thumb for the writer is: if it's a singled\nplaceholder then quote it with underscores, otherwise use back ticks\nelsewhere.\n\n> \n>> --1 --base::\n>> --2 --ours::\n>> --3 --theirs::\n>> +`-1` `--base`::\n>> +`-2` `--ours`::\n>> +`-3` `--theirs`::\n> \n> Why aren't these `-1 --base` and instead mark up individual tokens?\n> \n\nHere, it is quite awkward, because we are mixing alternate spellings of\nthe same option (`-1` and `--base` have the same meaning) with the fact\nthat these options are meant to be alternatives. The latter meaning is\nnot what is usually conveyed in the lists of options, which blurs the\nfollowing explanation.\n\nTo clarify, from what I understand, it would be better to fully spell\nout the way these options are used by using the synopsis syntax:\n\n`(-1|--base) | (-2|--ours) | (-3|--theirs)`::\n\nIs it how it works?\n\n>> -<path>...::\n>> -\tThe <paths> parameters, when given, are used to limit\n>> +_<path>_...::\n> \n> This has to do the _italics_ for placeholders, unlike the full\n> command line examples we saw earlier?\n> \n> Where does this difference come from?\n\nWell, according to the rule of thumb above, the whole segment should\nhave been quoted in back ticks. This is a mistake and must be fixed for\nconsistency.\n\n\n"},{"id":"507121","messageId":"b0a894fc-911d-49f5-a10c-19d441dc7133@free.fr","threadId":"61899","inReplyTo":"xmqqh68d8e9h.fsf@gitster.g","subject":"Re: [PATCH v2 2/5] doc: git-diff: apply format changes to diff-options","fromName":"Jean-Noël Avila","fromEmail":"jn.avila@free.fr","sentAt":"2024-11-12T09:04:50Z","receivedAt":"2024-11-12T09:04:56Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"Le 12/11/2024 à 01:52, Junio C Hamano a écrit :\n> \"Jean-Noël Avila via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n>  \n>> @@ -39,28 +39,28 @@ endif::git-format-patch[]\n>>  ifdef::git-log[]\n>>  -m::\n> \n> Shouldn't this and all others like -c/--cc be also quoted as\n> `literal` options?\n\nAs stated in the commit message, only the parts of the files which\nappear in git-diff man page are converted (like was done for git-clone\nand git-init)\n\nThinking again about it, I don't find it wise, because other man pages\nwill be half-converted anyway, at least for the common parts of the\nincluded files, and we are going to introduce several commits for the\nsame file.\n\nSo, better convert all the file in on run.\n\n> \n>> @@ -73,33 +73,33 @@ The following formats are supported:\n>>  off, none::\n> \n> Shouldn't this and other option values like on, first-parent, etc.,\n> that are literals be marked-up specially?\n\nThis is to be converted, and will be with the conversion of the full file.\n\n> \n>> --U<n>::\n>> ---unified=<n>::\n>> -\tGenerate diffs with <n> lines of context instead of\n>> +`-U<n>`::\n>> +`--unified=<n>`::\n>> +\tGenerate diffs with _<n>_ lines of context instead of\n> \n> Understandable.  Shouldn't <n> part be italicised?\n\nNo need: the processing of back tick quotes already treats each part\naccording to its semantics and applies the corresponding format.\n\n\n\n"},{"id":"507124","messageId":"xmqq34jw6ci7.fsf@gitster.g","threadId":"61899","inReplyTo":"7b42828a-2cbe-47c6-b21e-b8c1e3a2ad01@free.fr","subject":"Re: [PATCH v2 1/5] doc: git-diff: apply new documentation guidelines","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-11-12T09:13:20Z","receivedAt":"2024-11-12T09:13:23Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jean-Noël Avila <jn.avila@free.fr> writes:\n\n> With the new document processor extension, the back tick quotes have\n> become smarter and they behave basically like an inline synopsis\n> section. Here, this means that the line will be formatted roughly as\n> follows:\n>\n> `git diff` [_<options>_] [`--`] [_<path>_...]\n\nAhh, yes, it is the key magic how your \"enclosing the whole line\"\nworks.  It's been so long since we adopted the topic that laid the\ngroundwork that I forgot ;-)\n\nAgain, it is very pleasant for us writers to be able to just do so.\n\n>>> +`-1` `--base`::\n>>> +`-2` `--ours`::\n>>> +`-3` `--theirs`::\n>> \n>> Why aren't these `-1 --base` and instead mark up individual tokens?\n>> \n>\n> Here, it is quite awkward, because we are mixing alternate spellings of\n> the same option (`-1` and `--base` have the same meaning) with the fact\n> that these options are meant to be alternatives. The latter meaning is\n> not what is usually conveyed in the lists of options, which blurs the\n> following explanation.\n>\n> To clarify, from what I understand, it would be better to fully spell\n> out the way these options are used by using the synopsis syntax:\n>\n> `(-1|--base) | (-2|--ours) | (-3|--theirs)`::\n>\n> Is it how it works?\n\nYeah, that may be a more sensible rewrite (regardless of this\n\"better mark-up\" topic).\n\nThanks.\n"},{"id":"507125","messageId":"xmqqy11o4xve.fsf@gitster.g","threadId":"61899","inReplyTo":"b0a894fc-911d-49f5-a10c-19d441dc7133@free.fr","subject":"Re: [PATCH v2 2/5] doc: git-diff: apply format changes to diff-options","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-11-12T09:14:45Z","receivedAt":"2024-11-12T09:14:48Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jean-Noël Avila <jn.avila@free.fr> writes:\n\n>>> +`-U<n>`::\n>>> +`--unified=<n>`::\n>>> +\tGenerate diffs with _<n>_ lines of context instead of\n>> \n>> Understandable.  Shouldn't <n> part be italicised?\n>\n> No need: the processing of back tick quotes already treats each part\n> according to its semantics and applies the corresponding format.\n\nYup, you reminded me of how `the backticks are much more clever\nthese days` thing works.  Thanks.\n"},{"id":"507160","messageId":"45211c3c-e077-4de3-a167-0fc973a78dba@kdbg.org","threadId":"61899","inReplyTo":"xmqq34jw6ci7.fsf@gitster.g","subject":"Re: [PATCH v2 1/5] doc: git-diff: apply new documentation guidelines","fromName":"Johannes Sixt","fromEmail":"j6t@kdbg.org","sentAt":"2024-11-12T18:28:34Z","receivedAt":"2024-11-12T18:28:48Z","isPatch":true,"sender":{"key":"j6t@kdbg.org","avatar":"https://avatars.githubusercontent.com/u/14810926?v=4"},"body":"Am 12.11.24 um 10:13 schrieb Junio C Hamano:\n> Jean-Noël Avila <jn.avila@free.fr> writes:\n>> To clarify, from what I understand, it would be better to fully spell\n>> out the way these options are used by using the synopsis syntax:\n>>\n>> `(-1|--base) | (-2|--ours) | (-3|--theirs)`::\n>>\n>> Is it how it works?\n> \n> Yeah, that may be a more sensible rewrite (regardless of this\n> \"better mark-up\" topic).\n\nI would disagree. IMHO, it is not necessary to copy this sort of\nnerdfulness (the syntax annotations) from the synopsis to the\ndescription section.\n\nDoes\n\n`-1`, `--base`::\n`-2`, `--ours`::\n`-3`, `--theirs`::\n\nnot work? (I think we agree that grouping synonyms should be done and\nnot all tokens moved onto a flat line.)\n\n-- Hannes\n\n"},{"id":"507161","messageId":"6c1c1ae2-f38a-4458-a9ad-2fad3e56fc32@kdbg.org","threadId":"61899","inReplyTo":"8fec37ee17481039998af65ce1abec753cf30897.1731343985.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 3/5] doc: git-diff: apply format changes to diff-format","fromName":"Johannes Sixt","fromEmail":"j6t@kdbg.org","sentAt":"2024-11-12T18:51:37Z","receivedAt":"2024-11-12T18:51:43Z","isPatch":true,"sender":{"key":"j6t@kdbg.org","avatar":"https://avatars.githubusercontent.com/u/14810926?v=4"},"body":"Am 11.11.24 um 17:53 schrieb Jean-Noël Avila via GitGitGadget:\n> -The raw output format from \"git-diff-index\", \"git-diff-tree\",\n> -\"git-diff-files\" and \"git diff --raw\" are very similar.\n> +The raw output format from `git-diff-index`, `git-diff-tree`,\n> +`git-diff-files` and `git diff --raw` are very similar.\n\nThroughout this document we see a lot of commands with dashes `git-foo`.\nDoes this have any significance, or should they be corrected to the\ndashless form `git foo`? It could even be a \"while at it\"-change as you\nare touching every instance anyway.\n\n>  \n>  These commands all compare two sets of things; what is\n>  compared differs:\n>  \n> -git-diff-index <tree-ish>::\n> -        compares the <tree-ish> and the files on the filesystem.\n> +`git-diff-index <tree-ish>`::\n> +\tcompares the _<tree-ish>_ and the files on the filesystem.\n\nNow that the backtick formats the content as in the synopsis, why is it\nwritten _<tree-ish>_ and not `<tree-ish>` in the running text?\n\n-- Hannes\n\n"},{"id":"507162","messageId":"baeb6c64-eb6f-45ab-ac11-0896dd0adcae@kdbg.org","threadId":"61899","inReplyTo":"17a2f028d59a0097e92229c2b934a69974691e79.1731343985.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 5/5] doc: git-diff: apply format changes to config part","fromName":"Johannes Sixt","fromEmail":"j6t@kdbg.org","sentAt":"2024-11-12T18:51:54Z","receivedAt":"2024-11-12T18:52:00Z","isPatch":true,"sender":{"key":"j6t@kdbg.org","avatar":"https://avatars.githubusercontent.com/u/14810926?v=4"},"body":"Am 11.11.24 um 17:53 schrieb Jean-Noël Avila via GitGitGadget:\n> @@ -1,18 +1,18 @@\n> -diff.autoRefreshIndex::\n> -\tWhen using 'git diff' to compare with work tree\n> +`diff.autoRefreshIndex`::\n> +\tWhen using `git diff` to compare with work tree\n>  \tfiles, do not consider stat-only changes as changed.\n>  \tInstead, silently run `git update-index --refresh` to\n>  \tupdate the cached stat information for paths whose\n>  \tcontents in the work tree match the contents in the\n>  \tindex.  This option defaults to true.  Note that this\n> -\taffects only 'git diff' Porcelain, and not lower level\n> -\t'diff' commands such as 'git diff-files'.\n> +\taffects only `git diff` Porcelain, and not lower level\n> +\t`diff` commands such as '`git diff-files`.\n\nA stray ' remained on this line.\n\n> -diff.srcPrefix::\n> -\tIf set, 'git diff' uses this source prefix. Defaults to \"a/\".\n> +`diff.srcPrefix`::\n> +\tIf set, `git diff` uses this source prefix. Defaults to \"a/\".\n>  \n> -diff.dstPrefix::\n> -\tIf set, 'git diff' uses this destination prefix. Defaults to \"b/\".\n> +`diff.dstPrefix`::\n> +\tIf set, `git diff` uses this destination prefix. Defaults to \"b/\".\n\nYou are applying `backticks` to possible values such as `true` and\n`false` later. Then these `a/` and `b/` should also be set in this way.\n\n-- Hannes\n\n"},{"id":"507165","messageId":"xmqqcyj03vlk.fsf@gitster.g","threadId":"61899","inReplyTo":"45211c3c-e077-4de3-a167-0fc973a78dba@kdbg.org","subject":"Re: [PATCH v2 1/5] doc: git-diff: apply new documentation guidelines","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-11-12T23:01:27Z","receivedAt":"2024-11-12T23:01:30Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Johannes Sixt <j6t@kdbg.org> writes:\n\n> Does\n>\n> `-1`, `--base`::\n> `-2`, `--ours`::\n> `-3`, `--theirs`::\n>\n> not work? (I think we agree that grouping synonyms should be done and\n> not all tokens moved onto a flat line.)\n\nWith the current\n\n    -1 --base::\n    -2 --ours::\n    -3 --theirs::\n\tbody text\n\nthese are coalesced into a single header and get rendered as\n\n    -1 --base, -2 --ours, -3 --theirs\n\tbody text\n\nwhich reasonably shows that 1 and base belong to the same family\nthat is different from 2 and ours, etc.  With an explicit comma\nin between 1 and base, would we end up with\n\n    -1, --base, -2, --ours, -3, --theirs\n\nwhich may be worse than what we have currently?\n\nThanks.\n"},{"id":"507166","messageId":"xmqq8qto3vhy.fsf@gitster.g","threadId":"61899","inReplyTo":"6c1c1ae2-f38a-4458-a9ad-2fad3e56fc32@kdbg.org","subject":"Re: [PATCH v2 3/5] doc: git-diff: apply format changes to diff-format","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-11-12T23:03:37Z","receivedAt":"2024-11-12T23:03:40Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Johannes Sixt <j6t@kdbg.org> writes:\n\n> Am 11.11.24 um 17:53 schrieb Jean-Noël Avila via GitGitGadget:\n>> -The raw output format from \"git-diff-index\", \"git-diff-tree\",\n>> -\"git-diff-files\" and \"git diff --raw\" are very similar.\n>> +The raw output format from `git-diff-index`, `git-diff-tree`,\n>> +`git-diff-files` and `git diff --raw` are very similar.\n>\n> Throughout this document we see a lot of commands with dashes `git-foo`.\n> Does this have any significance, or should they be corrected to the\n> dashless form `git foo`? It could even be a \"while at it\"-change as you\n> are touching every instance anyway.\n\nYup, these \"git-foo\" are historical wart from pre Git 1.6 days.\n\n>>  These commands all compare two sets of things; what is\n>>  compared differs:\n>>  \n>> -git-diff-index <tree-ish>::\n>> -        compares the <tree-ish> and the files on the filesystem.\n>> +`git-diff-index <tree-ish>`::\n>> +\tcompares the _<tree-ish>_ and the files on the filesystem.\n>\n> Now that the backtick formats the content as in the synopsis, why is it\n> written _<tree-ish>_ and not `<tree-ish>` in the running text?\n\nPerhaps that is because the body text does want to show the\nplaceholder in _italics_ but not as a `literal` string?\n"},{"id":"507187","messageId":"1fe03d8f-89dd-4a93-b623-4b0838146bbe@kdbg.org","threadId":"61899","inReplyTo":"xmqqcyj03vlk.fsf@gitster.g","subject":"Re: [PATCH v2 1/5] doc: git-diff: apply new documentation guidelines","fromName":"Johannes Sixt","fromEmail":"j6t@kdbg.org","sentAt":"2024-11-13T07:31:03Z","receivedAt":"2024-11-13T07:31:16Z","isPatch":true,"sender":{"key":"j6t@kdbg.org","avatar":"https://avatars.githubusercontent.com/u/14810926?v=4"},"body":"Am 13.11.24 um 00:01 schrieb Junio C Hamano:\n> With an explicit comma\n> in between 1 and base, would we end up with\n> \n>     -1, --base, -2, --ours, -3, --theirs\n> \n> which may be worse than what we have currently?\n\nAgreed, that would indeed be worse.\n\n-- Hannes\n\n"},{"id":"507194","messageId":"277d6532-fbf8-4015-979e-40bb58702b57@kdbg.org","threadId":"61899","inReplyTo":"xmqq8qto3vhy.fsf@gitster.g","subject":"Re: [PATCH v2 3/5] doc: git-diff: apply format changes to diff-format","fromName":"Johannes Sixt","fromEmail":"j6t@kdbg.org","sentAt":"2024-11-13T07:39:22Z","receivedAt":"2024-11-13T07:39:30Z","isPatch":true,"sender":{"key":"j6t@kdbg.org","avatar":"https://avatars.githubusercontent.com/u/14810926?v=4"},"body":"Am 13.11.24 um 00:03 schrieb Junio C Hamano:\n> Johannes Sixt <j6t@kdbg.org> writes:\n>> Now that the backtick formats the content as in the synopsis, why is it\n>> written _<tree-ish>_ and not `<tree-ish>` in the running text?\n> \n> Perhaps that is because the body text does want to show the\n> placeholder in _italics_ but not as a `literal` string?\n\nOK, I can agree with that.\n\n-- Hannes\n\n"},{"id":"507197","messageId":"c9653435-d884-4aa3-8ee1-cabe19a2c552@free.fr","threadId":"61899","inReplyTo":"6c1c1ae2-f38a-4458-a9ad-2fad3e56fc32@kdbg.org","subject":"Re: [PATCH v2 3/5] doc: git-diff: apply format changes to diff-format","fromName":"Jean-Noël Avila","fromEmail":"jn.avila@free.fr","sentAt":"2024-11-13T08:10:43Z","receivedAt":"2024-11-13T08:10:49Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"Le 12/11/2024 à 19:51, Johannes Sixt a écrit :\n> Am 11.11.24 um 17:53 schrieb Jean-Noël Avila via GitGitGadget:\n>> -The raw output format from \"git-diff-index\", \"git-diff-tree\",\n>> -\"git-diff-files\" and \"git diff --raw\" are very similar.\n>> +The raw output format from `git-diff-index`, `git-diff-tree`,\n>> +`git-diff-files` and `git diff --raw` are very similar.\n> \n> Throughout this document we see a lot of commands with dashes `git-foo`.\n> Does this have any significance, or should they be corrected to the\n> dashless form `git foo`? It could even be a \"while at it\"-change as you\n> are touching every instance anyway.\n> \n\nOK. I didn't pay attention to these points until now.\n\n>>  \n>>  These commands all compare two sets of things; what is\n>>  compared differs:\n>>  \n>> -git-diff-index <tree-ish>::\n>> -        compares the <tree-ish> and the files on the filesystem.\n>> +`git-diff-index <tree-ish>`::\n>> +\tcompares the _<tree-ish>_ and the files on the filesystem.\n> \n> Now that the backtick formats the content as in the synopsis, why is it\n> written _<tree-ish>_ and not `<tree-ish>` in the running text?\n> \n\nWith the new processing in place, this is identical in the result. But\nfor the writers, I would still push so that the form _<placeholder>_ be\nused to remind them that keywords and placeholders need to be\ndifferentiated.\n\nMoreover, in case the special processing macro is not applied, the\nmarkup is still correct pure asciidoc, while generating a \"not so bad\"\noutput.\n"},{"id":"507198","messageId":"56d27d4d-d1d1-4341-92c0-f12e60ee083e@free.fr","threadId":"61899","inReplyTo":"baeb6c64-eb6f-45ab-ac11-0896dd0adcae@kdbg.org","subject":"Re: [PATCH v2 5/5] doc: git-diff: apply format changes to config part","fromName":"Jean-Noël Avila","fromEmail":"jn.avila@free.fr","sentAt":"2024-11-13T08:12:20Z","receivedAt":"2024-11-13T08:12:26Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"Le 12/11/2024 à 19:51, Johannes Sixt a écrit :\n> Am 11.11.24 um 17:53 schrieb Jean-Noël Avila via GitGitGadget:\n>> @@ -1,18 +1,18 @@\n>> -diff.autoRefreshIndex::\n>> -\tWhen using 'git diff' to compare with work tree\n>> +`diff.autoRefreshIndex`::\n>> +\tWhen using `git diff` to compare with work tree\n>>  \tfiles, do not consider stat-only changes as changed.\n>>  \tInstead, silently run `git update-index --refresh` to\n>>  \tupdate the cached stat information for paths whose\n>>  \tcontents in the work tree match the contents in the\n>>  \tindex.  This option defaults to true.  Note that this\n>> -\taffects only 'git diff' Porcelain, and not lower level\n>> -\t'diff' commands such as 'git diff-files'.\n>> +\taffects only `git diff` Porcelain, and not lower level\n>> +\t`diff` commands such as '`git diff-files`.\n> \n> A stray ' remained on this line.\n> \n>> -diff.srcPrefix::\n>> -\tIf set, 'git diff' uses this source prefix. Defaults to \"a/\".\n>> +`diff.srcPrefix`::\n>> +\tIf set, `git diff` uses this source prefix. Defaults to \"a/\".\n>>  \n>> -diff.dstPrefix::\n>> -\tIf set, 'git diff' uses this destination prefix. Defaults to \"b/\".\n>> +`diff.dstPrefix`::\n>> +\tIf set, `git diff` uses this destination prefix. Defaults to \"b/\".\n> \n> You are applying `backticks` to possible values such as `true` and\n> `false` later. Then these `a/` and `b/` should also be set in this way.\n> \n> -- Hannes\n> \n\nThank you for your review. Will fix.\n"},{"id":"507199","messageId":"4ad6b044-5eec-4d46-a862-20f374ede527@free.fr","threadId":"61899","inReplyTo":"xmqqcyj03vlk.fsf@gitster.g","subject":"Re: [PATCH v2 1/5] doc: git-diff: apply new documentation guidelines","fromName":"Jean-Noël Avila","fromEmail":"jn.avila@free.fr","sentAt":"2024-11-13T08:59:07Z","receivedAt":"2024-11-13T08:59:19Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"Le 13/11/2024 à 00:01, Junio C Hamano a écrit :\n> Johannes Sixt <j6t@kdbg.org> writes:\n> \n>> Does\n>>\n>> `-1`, `--base`::\n>> `-2`, `--ours`::\n>> `-3`, `--theirs`::\n>>\n>> not work? (I think we agree that grouping synonyms should be done and\n>> not all tokens moved onto a flat line.)\n> \n> With the current\n> \n>     -1 --base::\n>     -2 --ours::\n>     -3 --theirs::\n> \tbody text\n> \n> these are coalesced into a single header and get rendered as\n> \n>     -1 --base, -2 --ours, -3 --theirs\n> \tbody text\n> \n\nWhen I first reviewed this part, I interpreted it as \"there are 3 forms,\nmade of pairs of options used together\", which did not make sense. That\nis only after reading git-read-tree, that this explanation made sense.\n\n> which reasonably shows that 1 and base belong to the same family\n> that is different from 2 and ours, etc.  With an explicit comma\n> in between 1 and base, would we end up with\n> \n>     -1, --base, -2, --ours, -3, --theirs\n> \n> which may be worse than what we have currently?\n> \n> Thanks.\n\nTo be consistant with description of option, I think the 3 alternatives\nshould be split into their own items.\n"},{"id":"507413","messageId":"pull.1769.v3.git.1731785768.gitgitgadget@gmail.com","threadId":"61899","inReplyTo":"pull.1769.v2.git.1731343985.gitgitgadget@gmail.com","subject":"[PATCH v3 0/5] doc: git diff reformatting","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-11-16T19:36:03Z","receivedAt":"2024-11-16T19:36:12Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"This is the continuation of the editing of the manpages to reflect the new\nformatting rules.\n\nChanges since V1:\n\n * restate the formatting rules in the message of the first commit\n * fix typos\n * convert more parts to backticked\n * filter out most annoying self-referencing links\n * propose to separate with 'or' the -1 --ours options and the likes\n\nJean-Noël Avila (5):\n  doc: git-diff: apply new documentation guidelines\n  doc: git-diff: apply format changes to diff-options\n  doc: git-diff: apply format changes to diff-format\n  doc: git-diff: apply format changes to diff-generate-patch\n  doc: git-diff: apply format changes to config part\n\n Documentation/config/diff.txt         | 204 +++++++------\n Documentation/diff-format.txt         |  42 +--\n Documentation/diff-generate-patch.txt |  44 +--\n Documentation/diff-options.txt        | 423 +++++++++++++-------------\n Documentation/git-diff.txt            | 108 +++----\n 5 files changed, 424 insertions(+), 397 deletions(-)\n\n\nbase-commit: facbe4f633e4ad31e641f64617bc88074c659959\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-1769%2Fjnavila%2Fgit_diff_new-v3\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1769/jnavila/git_diff_new-v3\nPull-Request: https://github.com/gitgitgadget/git/pull/1769\n\nRange-diff vs v2:\n\n 1:  c104bd50b64 ! 1:  6841bd5825b doc: git-diff: apply new documentation guidelines\n     @@ Metadata\n       ## Commit message ##\n          doc: git-diff: apply new documentation guidelines\n      \n     +    The documentation for git-diff has been updated to follow the new\n     +    documentation guidelines. The following changes have been applied to\n     +    the series of patches:\n     +\n     +    - switching 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\n     +    descriptions`. The new rendering engine will apply synopsis rules to\n     +    these spans.\n     +    - prevent git-diff from self-referencing itself via gitlink macro when\n     +    the generated link would point to the same page.\n     +\n          Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>\n      \n       ## Documentation/git-diff.txt ##\n     @@ Documentation/git-diff.txt: OPTIONS\n      --1 --base::\n      --2 --ours::\n      --3 --theirs::\n     -+`-1` `--base`::\n     -+`-2` `--ours`::\n     -+`-3` `--theirs`::\n     ++`-1`::\n     ++`--base`::\n     ++\n     ++or `-2`::\n     ++`--ours`::\n     ++\n     ++or `-3`::\n     ++`--theirs`::\n       \tCompare the working tree with the \"base\" version (stage #1),\n       \t\"our branch\" (stage #2) or \"their branch\" (stage #3).  The\n       \tindex contains these stages only for unmerged entries i.e.\n     @@ Documentation/git-diff.txt: OPTIONS\n       \n      -<path>...::\n      -\tThe <paths> parameters, when given, are used to limit\n     -+_<path>_...::\n     ++`<path>...`::\n      +\tThe _<path>_ parameters, when given, are used to limit\n       \tthe diff to the named paths (you can give directory\n       \tnames and get diff for all files under them).\n 2:  129763c2aae = 2:  07df397741b doc: git-diff: apply format changes to diff-options\n 3:  8fec37ee174 = 3:  698628e076b doc: git-diff: apply format changes to diff-format\n 4:  daed146639d = 4:  1154462f8be doc: git-diff: apply format changes to diff-generate-patch\n 5:  17a2f028d59 ! 5:  4ec2fd9c3c6 doc: git-diff: apply format changes to config part\n     @@ Metadata\n       ## Commit message ##\n          doc: git-diff: apply format changes to config part\n      \n     +    By the way, we also change the sentences where git-diff would refer to\n     +    itself, so that no link is created in the HTML output.\n     +\n          Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>\n      \n       ## Documentation/config/diff.txt ##\n     @@ Documentation/config/diff.txt\n       \tInstead, silently run `git update-index --refresh` to\n       \tupdate the cached stat information for paths whose\n       \tcontents in the work tree match the contents in the\n     - \tindex.  This option defaults to true.  Note that this\n     +-\tindex.  This option defaults to true.  Note that this\n      -\taffects only 'git diff' Porcelain, and not lower level\n      -\t'diff' commands such as 'git diff-files'.\n     ++\tindex.  This option defaults to `true`.  Note that this\n      +\taffects only `git diff` Porcelain, and not lower level\n     -+\t`diff` commands such as '`git diff-files`.\n     ++\t`diff` commands such as `git diff-files`.\n       \n      -diff.dirstat::\n      +`diff.dirstat`::\n     ++ifdef::git-diff[]\n     ++\tA comma separated list of `--dirstat` parameters specifying the\n     ++\tdefault behavior of the `--dirstat` option to `git diff` and friends.\n     ++endif::git-diff[]\n     ++ifndef::git-diff[]\n       \tA comma separated list of `--dirstat` parameters specifying the\n       \tdefault behavior of the `--dirstat` option to linkgit:git-diff[1]\n     - \tand friends. The defaults can be overridden on the command line\n     +-\tand friends. The defaults can be overridden on the command line\n      -\t(using `--dirstat=<param1,param2,...>`). The fallback defaults\n     ++\tand friends.\n     ++endif::git-diff[]\n     ++\tThe defaults can be overridden on the command line\n      +\t(using `--dirstat=<param>,...`). The fallback defaults\n       \t(when not changed by `diff.dirstat`) are `changes,noncumulative,3`.\n       \tThe following parameters are available:\n     @@ Documentation/config/diff.txt: directories with less than 10% of the total amoun\n       \n      -diff.mnemonicPrefix::\n      -\tIf set, 'git diff' uses a prefix pair that is different from the\n     +-\tstandard \"a/\" and \"b/\" depending on what is being compared.  When\n      +`diff.mnemonicPrefix`::\n      +\tIf set, `git diff` uses a prefix pair that is different from the\n     - \tstandard \"a/\" and \"b/\" depending on what is being compared.  When\n     ++\tstandard `a/` and `b/` depending on what is being compared.  When\n       \tthis configuration is in effect, reverse diff output also swaps\n       \tthe order of the prefixes:\n     + `git diff`;;\n      @@ Documentation/config/diff.txt: diff.mnemonicPrefix::\n       \t compares a (c)ommit and the (w)ork tree;\n       `git diff --cached`;;\n     @@ Documentation/config/diff.txt: diff.mnemonicPrefix::\n      -`git diff HEAD:file1 file2`;;\n      +`git diff HEAD:<file1> <file2>`;;\n       \tcompares an (o)bject and a (w)ork tree entity;\n     - `git diff --no-index a b`;;\n     - \tcompares two non-git things (1) and (2).\n     +-`git diff --no-index a b`;;\n     +-\tcompares two non-git things (1) and (2).\n     ++`git diff --no-index <a> <b>`;;\n     ++\tcompares two non-git things _<a>_ and _<b>_.\n       \n      -diff.noPrefix::\n      -\tIf set, 'git diff' does not show any source or destination prefix.\n     @@ Documentation/config/diff.txt: diff.mnemonicPrefix::\n      -diff.srcPrefix::\n      -\tIf set, 'git diff' uses this source prefix. Defaults to \"a/\".\n      +`diff.srcPrefix`::\n     -+\tIf set, `git diff` uses this source prefix. Defaults to \"a/\".\n     ++\tIf set, `git diff` uses this source prefix. Defaults to `a/`.\n       \n      -diff.dstPrefix::\n      -\tIf set, 'git diff' uses this destination prefix. Defaults to \"b/\".\n      +`diff.dstPrefix`::\n     -+\tIf set, `git diff` uses this destination prefix. Defaults to \"b/\".\n     ++\tIf set, `git diff` uses this destination prefix. Defaults to `b/`.\n       \n      -diff.relative::\n      -\tIf set to 'true', 'git diff' does not show changes outside of the directory\n     @@ Documentation/config/diff.txt: diff.mnemonicPrefix::\n      +`diff.orderFile`::\n       \tFile indicating how to order files within a diff.\n      -\tSee the '-O' option to linkgit:git-diff[1] for details.\n     ++ifdef::git-diff[]\n     ++\tSee the `-O` option for details.\n     ++endif::git-diff[]\n     ++ifndef::git-diff[]\n      +\tSee the `-O` option to linkgit:git-diff[1] for details.\n     ++endif::git-diff[]\n       \tIf `diff.orderFile` is a relative pathname, it is treated as\n       \trelative to the top of the working tree.\n       \n     @@ Documentation/config/diff.txt: diff.mnemonicPrefix::\n      -\tWhether and how Git detects renames.  If set to \"false\",\n      -\trename detection is disabled. If set to \"true\", basic rename\n      -\tdetection is enabled.  If set to \"copies\" or \"copy\", Git will\n     +-\tdetect copies, as well.  Defaults to true.  Note that this\n     +-\taffects only 'git diff' Porcelain like linkgit:git-diff[1] and\n      +`diff.renames`::\n      +\tWhether and how Git detects renames.  If set to `false`,\n      +\trename detection is disabled. If set to `true`, basic rename\n      +\tdetection is enabled.  If set to `copies` or `copy`, Git will\n     - \tdetect copies, as well.  Defaults to true.  Note that this\n     --\taffects only 'git diff' Porcelain like linkgit:git-diff[1] and\n     ++\tdetect copies, as well.  Defaults to `true`.  Note that this\n      +\taffects only `git diff` Porcelain like linkgit:git-diff[1] and\n       \tlinkgit:git-log[1], and not lower level commands such as\n       \tlinkgit:git-diff-files[1].\n     @@ Documentation/config/diff.txt: diff.mnemonicPrefix::\n       \tfor details.\n       \n      -diff.<driver>.trustExitCode::\n     +-\tIf this boolean value is set to true then the\n      +`diff.<driver>.trustExitCode`::\n     - \tIf this boolean value is set to true then the\n     ++\tIf this boolean value is set to `true` then the\n       \t`diff.<driver>.command` command is expected to return exit code\n       \t0 if it considers the input files to be equal or 1 if it\n      -\tconsiders them to be different, like `diff(1)`.\n     +-\tIf it is set to false, which is the default, then the command\n      +\tconsiders them to be different, like `diff`(1).\n     - \tIf it is set to false, which is the default, then the command\n     ++\tIf it is set to `false`, which is the default, then the command\n       \tis expected to return exit code 0 regardless of equality.\n       \tAny other exit code causes Git to report a fatal error.\n       \n     @@ Documentation/config/diff.txt: diff.mnemonicPrefix::\n       \tdetails.\n       \n      -diff.<driver>.cachetextconv::\n     +-\tSet this option to true to make the diff driver cache the text\n      +`diff.<driver>.cachetextconv`::\n     - \tSet this option to true to make the diff driver cache the text\n     ++\tSet this option to `true` to make the diff driver cache the text\n       \tconversion outputs.  See linkgit:gitattributes[5] for details.\n       \n       include::../mergetools-diff.txt[]\n     @@ Documentation/config/diff.txt: diff.wsErrorHighlight::\n       \n      -diff.colorMoved::\n      -\tIf set to either a valid `<mode>` or a true value, moved lines\n     -+`diff.colorMoved`::\n     -+\tIf set to either a valid _<mode>_ or a true value, moved lines\n     - \tin a diff are colored differently, for details of valid modes\n     +-\tin a diff are colored differently, for details of valid modes\n      -\tsee '--color-moved' in linkgit:git-diff[1]. If simply set to\n      -\ttrue the default color mode will be used. When set to false,\n     -+\tsee `--color-moved` in linkgit:git-diff[1]. If simply set to\n     -+\t`true` the default color mode will be used. When set to `false`,\n     - \tmoved lines are not colored.\n     - \n     +-\tmoved lines are not colored.\n     +-\n      -diff.colorMovedWS::\n     ++`diff.colorMoved`::\n     ++\tIf set to either a valid _<mode>_ or a `true` value, moved lines\n     ++\tin a diff are colored differently.\n     ++ifdef::git-diff[]\n     ++\tFor details of valid modes see `--color-moved`.\n     ++endif::git-diff[]\n     ++ifndef::git-diff[]\n     ++\tFor details of valid modes see `--color-moved` in linkgit:git-diff[1].\n     ++endif::git-diff[]\n     ++\tIf simply set to `true` the default color mode will be used. When\n     ++\tset to `false`, moved lines are not colored.\n     ++\n      +`diff.colorMovedWS`::\n       \tWhen moved lines are colored using e.g. the `diff.colorMoved` setting,\n      -\tthis option controls the `<mode>` how spaces are treated.\n\n-- \ngitgitgadget\n"},{"id":"507414","messageId":"6841bd5825be8e7b17c2f9c3a997de29ffa3a540.1731785769.git.gitgitgadget@gmail.com","threadId":"61899","inReplyTo":"pull.1769.v3.git.1731785768.gitgitgadget@gmail.com","subject":"[PATCH v3 1/5] doc: git-diff: apply new documentation guidelines","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-11-16T19:36:04Z","receivedAt":"2024-11-16T19:36: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\nThe documentation for git-diff has been updated to follow the new\ndocumentation guidelines. The following changes have been applied to\nthe series of patches:\n\n- switching 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- prevent git-diff from self-referencing itself via gitlink macro when\nthe generated link would point to the same page.\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\n---\n Documentation/git-diff.txt | 108 +++++++++++++++++++------------------\n 1 file changed, 57 insertions(+), 51 deletions(-)\n\ndiff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt\nindex c065f023eca..dfa031d7386 100644\n--- a/Documentation/git-diff.txt\n+++ b/Documentation/git-diff.txt\n@@ -8,13 +8,13 @@ git-diff - Show changes between commits, commit and working tree, etc\n \n SYNOPSIS\n --------\n-[verse]\n-'git diff' [<options>] [<commit>] [--] [<path>...]\n-'git diff' [<options>] --cached [--merge-base] [<commit>] [--] [<path>...]\n-'git diff' [<options>] [--merge-base] <commit> [<commit>...] <commit> [--] [<path>...]\n-'git diff' [<options>] <commit>...<commit> [--] [<path>...]\n-'git diff' [<options>] <blob> <blob>\n-'git diff' [<options>] --no-index [--] <path> <path>\n+[synopsis]\n+git diff [<options>] [<commit>] [--] [<path>...]\n+git diff [<options>] --cached [--merge-base] [<commit>] [--] [<path>...]\n+git diff [<options>] [--merge-base] <commit> [<commit>...] <commit> [--] [<path>...]\n+git diff [<options>] <commit>...<commit> [--] [<path>...]\n+git diff [<options>] <blob> <blob>\n+git diff [<options>] --no-index [--] <path> <path>\n \n DESCRIPTION\n -----------\n@@ -23,7 +23,7 @@ between the index and a tree, changes between two trees, changes resulting\n from a merge, changes between two blob objects, or changes between two\n files on disk.\n \n-'git diff' [<options>] [--] [<path>...]::\n+`git diff [<options>] [--] [<path>...]`::\n \n \tThis form is to view the changes you made relative to\n \tthe index (staging area for the next commit).  In other\n@@ -31,7 +31,7 @@ files on disk.\n \tfurther add to the index but you still haven't.  You can\n \tstage these changes by using linkgit:git-add[1].\n \n-'git diff' [<options>] --no-index [--] <path> <path>::\n+`git diff [<options>] --no-index [--] <path> <path>`::\n \n \tThis form is to compare the given two paths on the\n \tfilesystem.  You can omit the `--no-index` option when\n@@ -40,82 +40,82 @@ files on disk.\n \tor when running the command outside a working tree\n \tcontrolled by Git. This form implies `--exit-code`.\n \n-'git diff' [<options>] --cached [--merge-base] [<commit>] [--] [<path>...]::\n+`git diff [<options>] --cached [--merge-base] [<commit>] [--] [<path>...]`::\n \n \tThis form is to view the changes you staged for the next\n-\tcommit relative to the named <commit>.  Typically you\n+\tcommit relative to the named _<commit>_.  Typically you\n \twould want comparison with the latest commit, so if you\n-\tdo not give <commit>, it defaults to HEAD.\n-\tIf HEAD does not exist (e.g. unborn branches) and\n-\t<commit> is not given, it shows all staged changes.\n-\t--staged is a synonym of --cached.\n+\tdo not give _<commit>_, it defaults to `HEAD`.\n+\tIf `HEAD` does not exist (e.g. unborn branches) and\n+\t_<commit>_ is not given, it shows all staged changes.\n+\t`--staged` is a synonym of `--cached`.\n +\n-If --merge-base is given, instead of using <commit>, use the merge base\n-of <commit> and HEAD.  `git diff --cached --merge-base A` is equivalent to\n+If `--merge-base` is given, instead of using _<commit>_, use the merge base\n+of _<commit>_ and `HEAD`.  `git diff --cached --merge-base A` is equivalent to\n `git diff --cached $(git merge-base A HEAD)`.\n \n-'git diff' [<options>] [--merge-base] <commit> [--] [<path>...]::\n+`git diff [<options>] [--merge-base] <commit> [--] [<path>...]`::\n \n \tThis form is to view the changes you have in your\n-\tworking tree relative to the named <commit>.  You can\n-\tuse HEAD to compare it with the latest commit, or a\n+\tworking tree relative to the named _<commit>_.  You can\n+\tuse `HEAD` to compare it with the latest commit, or a\n \tbranch name to compare with the tip of a different\n \tbranch.\n +\n-If --merge-base is given, instead of using <commit>, use the merge base\n-of <commit> and HEAD.  `git diff --merge-base A` is equivalent to\n+If `--merge-base` is given, instead of using _<commit>_, use the merge base\n+of _<commit>_ and `HEAD`.  `git diff --merge-base A` is equivalent to\n `git diff $(git merge-base A HEAD)`.\n \n-'git diff' [<options>] [--merge-base] <commit> <commit> [--] [<path>...]::\n+`git diff [<options>] [--merge-base] <commit> <commit> [--] [<path>...]`::\n \n \tThis is to view the changes between two arbitrary\n-\t<commit>.\n+\t_<commit>_.\n +\n-If --merge-base is given, use the merge base of the two commits for the\n+If `--merge-base` is given, use the merge base of the two commits for the\n \"before\" side.  `git diff --merge-base A B` is equivalent to\n `git diff $(git merge-base A B) B`.\n \n-'git diff' [<options>] <commit> <commit>... <commit> [--] [<path>...]::\n+`git diff [<options>] <commit> <commit>...<commit> [--] [<path>...]`::\n \n \tThis form is to view the results of a merge commit.  The first\n-\tlisted <commit> must be the merge itself; the remaining two or\n+\tlisted _<commit>_ must be the merge itself; the remaining two or\n \tmore commits should be its parents.  Convenient ways to produce\n-\tthe desired set of revisions are to use the suffixes `^@` and\n-\t`^!`.  If A is a merge commit, then `git diff A A^@`,\n+\tthe desired set of revisions are to use the suffixes `@` and\n+\t`^!`.  If `A` is a merge commit, then `git diff A A^@`,\n \t`git diff A^!` and `git show A` all give the same combined diff.\n \n-'git diff' [<options>] <commit>..<commit> [--] [<path>...]::\n+`git diff [<options>] <commit>..<commit> [--] [<path>...]`::\n \n \tThis is synonymous to the earlier form (without the `..`) for\n-\tviewing the changes between two arbitrary <commit>.  If <commit> on\n+\tviewing the changes between two arbitrary _<commit>_.  If _<commit>_ on\n \tone side is omitted, it will have the same effect as\n-\tusing HEAD instead.\n+\tusing `HEAD` instead.\n \n-'git diff' [<options>] <commit>\\...<commit> [--] [<path>...]::\n+`git diff [<options>] <commit>...<commit> [--] [<path>...]`::\n \n \tThis form is to view the changes on the branch containing\n-\tand up to the second <commit>, starting at a common ancestor\n-\tof both <commit>.  `git diff A...B` is equivalent to\n+\tand up to the second _<commit>_, starting at a common ancestor\n+\tof both _<commit>_.  `git diff A...B` is equivalent to\n \t`git diff $(git merge-base A B) B`.  You can omit any one\n-\tof <commit>, which has the same effect as using HEAD instead.\n+\tof _<commit>_, which has the same effect as using `HEAD` instead.\n \n Just in case you are doing something exotic, it should be\n-noted that all of the <commit> in the above description, except\n+noted that all of the _<commit>_ in the above description, except\n in the `--merge-base` case and in the last two forms that use `..`\n-notations, can be any <tree>. A tree of interest is the one pointed to\n-by the ref named `AUTO_MERGE`, which is written by the 'ort' merge\n+notations, can be any _<tree>_. A tree of interest is the one pointed to\n+by the ref named `AUTO_MERGE`, which is written by the `ort` merge\n strategy upon hitting merge conflicts (see linkgit:git-merge[1]).\n Comparing the working tree with `AUTO_MERGE` shows changes you've made\n so far to resolve textual conflicts (see the examples below).\n \n-For a more complete list of ways to spell <commit>, see\n+For a more complete list of ways to spell _<commit>_, see\n \"SPECIFYING REVISIONS\" section in linkgit:gitrevisions[7].\n-However, \"diff\" is about comparing two _endpoints_, not ranges,\n-and the range notations (`<commit>..<commit>` and\n-`<commit>...<commit>`) do not mean a range as defined in the\n+However, `diff` is about comparing two _endpoints_, not ranges,\n+and the range notations (`<commit>..<commit>` and `<commit>...<commit>`)\n+do not mean a range as defined in the\n \"SPECIFYING RANGES\" section in linkgit:gitrevisions[7].\n \n-'git diff' [<options>] <blob> <blob>::\n+`git diff [<options>] <blob> <blob>`::\n \n \tThis form is to view the differences between the raw\n \tcontents of two blob objects.\n@@ -125,22 +125,27 @@ OPTIONS\n :git-diff: 1\n include::diff-options.txt[]\n \n--1 --base::\n--2 --ours::\n--3 --theirs::\n+`-1`::\n+`--base`::\n+\n+or `-2`::\n+`--ours`::\n+\n+or `-3`::\n+`--theirs`::\n \tCompare the working tree with the \"base\" version (stage #1),\n \t\"our branch\" (stage #2) or \"their branch\" (stage #3).  The\n \tindex contains these stages only for unmerged entries i.e.\n \twhile resolving conflicts.  See linkgit:git-read-tree[1]\n \tsection \"3-Way Merge\" for detailed information.\n \n--0::\n+`-0`::\n \tOmit diff output for unmerged entries and just show\n \t\"Unmerged\".  Can be used only when comparing the working tree\n \twith the index.\n \n-<path>...::\n-\tThe <paths> parameters, when given, are used to limit\n+`<path>...`::\n+\tThe _<path>_ parameters, when given, are used to limit\n \tthe diff to the named paths (you can give directory\n \tnames and get diff for all files under them).\n \n@@ -225,11 +230,12 @@ CONFIGURATION\n \n include::includes/cmd-config-section-all.txt[]\n \n+:git-diff: 1\n include::config/diff.txt[]\n \n SEE ALSO\n --------\n-diff(1),\n+`diff`(1),\n linkgit:git-difftool[1],\n linkgit:git-log[1],\n linkgit:gitdiffcore[7],\n-- \ngitgitgadget\n\n"},{"id":"507415","messageId":"698628e076bcbba2e0c5ec2758c2a31adf9c91b8.1731785769.git.gitgitgadget@gmail.com","threadId":"61899","inReplyTo":"pull.1769.v3.git.1731785768.gitgitgadget@gmail.com","subject":"[PATCH v3 3/5] doc: git-diff: apply format changes to diff-format","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-11-16T19:36:06Z","receivedAt":"2024-11-16T19:36: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/diff-format.txt | 42 +++++++++++++++++------------------\n 1 file changed, 21 insertions(+), 21 deletions(-)\n\ndiff --git a/Documentation/diff-format.txt b/Documentation/diff-format.txt\nindex a3ae8747a22..c72fb379867 100644\n--- a/Documentation/diff-format.txt\n+++ b/Documentation/diff-format.txt\n@@ -1,25 +1,25 @@\n Raw output format\n -----------------\n \n-The raw output format from \"git-diff-index\", \"git-diff-tree\",\n-\"git-diff-files\" and \"git diff --raw\" are very similar.\n+The raw output format from `git-diff-index`, `git-diff-tree`,\n+`git-diff-files` and `git diff --raw` are very similar.\n \n These commands all compare two sets of things; what is\n compared differs:\n \n-git-diff-index <tree-ish>::\n-        compares the <tree-ish> and the files on the filesystem.\n+`git-diff-index <tree-ish>`::\n+\tcompares the _<tree-ish>_ and the files on the filesystem.\n \n-git-diff-index --cached <tree-ish>::\n-        compares the <tree-ish> and the index.\n+`git-diff-index --cached <tree-ish>`::\n+\tcompares the _<tree-ish>_ and the index.\n \n-git-diff-tree [-r] <tree-ish-1> <tree-ish-2> [<pattern>...]::\n+`git-diff-tree [-r] <tree-ish-1> <tree-ish-2> [<pattern>...]`::\n         compares the trees named by the two arguments.\n \n-git-diff-files [<pattern>...]::\n+`git-diff-files [<pattern>...]`::\n         compares the index and the files on the filesystem.\n \n-The \"git-diff-tree\" command begins its output by printing the hash of\n+The `git-diff-tree` command begins its output by printing the hash of\n what is being compared. After that, all the commands print one output\n line per changed file.\n \n@@ -54,19 +54,19 @@ That is, from the left to the right:\n \n Possible status letters are:\n \n-- A: addition of a file\n-- C: copy of a file into a new one\n-- D: deletion of a file\n-- M: modification of the contents or mode of a file\n-- R: renaming of a file\n-- T: change in the type of the file (regular file, symbolic link or submodule)\n-- U: file is unmerged (you must complete the merge before it can\n+- `A`: addition of a file\n+- `C`: copy of a file into a new one\n+- `D`: deletion of a file\n+- `M`: modification of the contents or mode of a file\n+- `R`: renaming of a file\n+- `T`: change in the type of the file (regular file, symbolic link or submodule)\n+- `U`: file is unmerged (you must complete the merge before it can\n   be committed)\n-- X: \"unknown\" change type (most probably a bug, please report it)\n+- `X`: \"unknown\" change type (most probably a bug, please report it)\n \n-Status letters C and R are always followed by a score (denoting the\n+Status letters `C` and `R` are always followed by a score (denoting the\n percentage of similarity between the source and target of the move or\n-copy).  Status letter M may be followed by a score (denoting the\n+copy).  Status letter `M` may be followed by a score (denoting the\n percentage of dissimilarity) for file rewrites.\n \n The sha1 for \"dst\" is shown as all 0's if a file on the filesystem\n@@ -86,7 +86,7 @@ verbatim and the line is terminated by a NUL byte.\n diff format for merges\n ----------------------\n \n-\"git-diff-tree\", \"git-diff-files\" and \"git-diff --raw\"\n+`git-diff-tree`, `git-diff-files` and `git-diff --raw`\n can take `-c` or `--cc` option\n to generate diff output also for merge commits.  The output differs\n from the format described above in the following way:\n@@ -128,7 +128,7 @@ other diff formats\n ------------------\n \n The `--summary` option describes newly added, deleted, renamed and\n-copied files.  The `--stat` option adds diffstat(1) graph to the\n+copied files.  The `--stat` option adds `diffstat`(1) graph to the\n output.  These options can be combined with other options, such as\n `-p`, and are meant for human consumption.\n \n-- \ngitgitgadget\n\n"},{"id":"507416","messageId":"07df397741be815b64383fdd6755f57ece6af5fa.1731785769.git.gitgitgadget@gmail.com","threadId":"61899","inReplyTo":"pull.1769.v3.git.1731785768.gitgitgadget@gmail.com","subject":"[PATCH v3 2/5] doc: git-diff: apply format changes to diff-options","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-11-16T19:36:05Z","receivedAt":"2024-11-16T19:36: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\nThe format change is only applied to the sections of the file that are\nfiltered in git-diff.\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\n---\n Documentation/diff-options.txt | 423 +++++++++++++++++----------------\n 1 file changed, 212 insertions(+), 211 deletions(-)\n\ndiff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt\nindex cd0b81adbb6..640eb6e7db5 100644\n--- a/Documentation/diff-options.txt\n+++ b/Documentation/diff-options.txt\n@@ -19,16 +19,16 @@ ifdef::git-format-patch[]\n endif::git-format-patch[]\n \n ifndef::git-format-patch[]\n--p::\n--u::\n---patch::\n+`-p`::\n+`-u`::\n+`--patch`::\n \tGenerate patch (see <<generate_patch_text_with_p>>).\n ifdef::git-diff[]\n \tThis is the default.\n endif::git-diff[]\n \n--s::\n---no-patch::\n+`-s`::\n+`--no-patch`::\n \tSuppress all output from the diff machinery.  Useful for\n \tcommands like `git show` that show the patch by default to\n \tsquelch their output, or to cancel the effect of options like\n@@ -39,28 +39,28 @@ endif::git-format-patch[]\n ifdef::git-log[]\n -m::\n \tShow diffs for merge commits in the default format. This is\n-\tsimilar to '--diff-merges=on', except `-m` will\n+\tsimilar to `--diff-merges=on`, except `-m` will\n \tproduce no output unless `-p` is given as well.\n \n -c::\n \tProduce combined diff output for merge commits.\n-\tShortcut for '--diff-merges=combined -p'.\n+\tShortcut for `--diff-merges=combined -p`.\n \n --cc::\n \tProduce dense combined diff output for merge commits.\n-\tShortcut for '--diff-merges=dense-combined -p'.\n+\tShortcut for `--diff-merges=dense-combined -p`.\n \n --dd::\n \tProduce diff with respect to first parent for both merge and\n \tregular commits.\n-\tShortcut for '--diff-merges=first-parent -p'.\n+\tShortcut for `--diff-merges=first-parent -p`.\n \n --remerge-diff::\n \tProduce remerge-diff output for merge commits.\n-\tShortcut for '--diff-merges=remerge -p'.\n+\tShortcut for `--diff-merges=remerge -p`.\n \n --no-diff-merges::\n-\tSynonym for '--diff-merges=off'.\n+\tSynonym for `--diff-merges=off`.\n \n --diff-merges=<format>::\n \tSpecify diff format to be used for merge commits. Default is\n@@ -73,33 +73,33 @@ The following formats are supported:\n off, none::\n \tDisable output of diffs for merge commits. Useful to override\n \timplied value.\n-+\n+\n on, m::\n \tMake diff output for merge commits to be shown in the default\n \tformat. The default format can be changed using\n \t`log.diffMerges` configuration variable, whose default value\n \tis `separate`.\n-+\n+\n first-parent, 1::\n \tShow full diff with respect to first parent. This is the same\n \tformat as `--patch` produces for non-merge commits.\n-+\n+\n separate::\n \tShow full diff with respect to each of parents.\n \tSeparate log entry and diff is generated for each parent.\n-+\n+\n combined, c::\n \tShow differences from each of the parents to the merge\n \tresult simultaneously instead of showing pairwise diff between\n \ta parent and the result one at a time. Furthermore, it lists\n \tonly files which were modified from all parents.\n-+\n+\n dense-combined, cc::\n \tFurther compress output produced by `--diff-merges=combined`\n \tby omitting uninteresting hunks whose contents in the parents\n \thave only two variants and the merge result picks one of them\n \twithout modification.\n-+\n+\n remerge, r::\n \tRemerge two-parent merge commits to create a temporary tree\n \tobject--potentially containing files with conflict markers\n@@ -112,33 +112,33 @@ documented).\n --\n \n --combined-all-paths::\n-\tThis flag causes combined diffs (used for merge commits) to\n+\tCause combined diffs (used for merge commits) to\n \tlist the name of the file from all parents.  It thus only has\n \teffect when `--diff-merges=[dense-]combined` is in use, and\n \tis likely only useful if filename changes are detected (i.e.\n \twhen either rename or copy detection have been requested).\n endif::git-log[]\n \n--U<n>::\n---unified=<n>::\n-\tGenerate diffs with <n> lines of context instead of\n+`-U<n>`::\n+`--unified=<n>`::\n+\tGenerate diffs with _<n>_ lines of context instead of\n \tthe usual three.\n ifndef::git-format-patch[]\n \tImplies `--patch`.\n endif::git-format-patch[]\n \n---output=<file>::\n+`--output=<file>`::\n \tOutput to a specific file instead of stdout.\n \n---output-indicator-new=<char>::\n---output-indicator-old=<char>::\n---output-indicator-context=<char>::\n+`--output-indicator-new=<char>`::\n+`--output-indicator-old=<char>`::\n+`--output-indicator-context=<char>`::\n \tSpecify the character used to indicate new, old or context\n-\tlines in the generated patch. Normally they are '+', '-' and\n+\tlines in the generated patch. Normally they are `+`, `-` and\n \t' ' respectively.\n \n ifndef::git-format-patch[]\n---raw::\n+`--raw`::\n ifndef::git-log[]\n \tGenerate the diff in raw format.\n ifdef::git-diff-core[]\n@@ -155,54 +155,55 @@ endif::git-log[]\n endif::git-format-patch[]\n \n ifndef::git-format-patch[]\n---patch-with-raw::\n+`--patch-with-raw`::\n \tSynonym for `-p --raw`.\n endif::git-format-patch[]\n \n ifdef::git-log[]\n--t::\n+`-t`::\n \tShow the tree objects in the diff output.\n endif::git-log[]\n \n---indent-heuristic::\n+`--indent-heuristic`::\n \tEnable the heuristic that shifts diff hunk boundaries to make patches\n \teasier to read. This is the default.\n \n---no-indent-heuristic::\n+`--no-indent-heuristic`::\n \tDisable the indent heuristic.\n \n---minimal::\n+`--minimal`::\n \tSpend extra time to make sure the smallest possible\n \tdiff is produced.\n \n---patience::\n+`--patience`::\n \tGenerate a diff using the \"patience diff\" algorithm.\n \n---histogram::\n+`--histogram`::\n \tGenerate a diff using the \"histogram diff\" algorithm.\n \n---anchored=<text>::\n+`--anchored=<text>`::\n \tGenerate a diff using the \"anchored diff\" algorithm.\n +\n This option may be specified more than once.\n +\n If a line exists in both the source and destination, exists only once,\n-and starts with this text, this algorithm attempts to prevent it from\n+and starts with _<text>_, this algorithm attempts to prevent it from\n appearing as a deletion or addition in the output. It uses the \"patience\n diff\" algorithm internally.\n \n---diff-algorithm={patience|minimal|histogram|myers}::\n+`--diff-algorithm=(patience|minimal|histogram|myers)`::\n \tChoose a diff algorithm. The variants are as follows:\n +\n --\n-`default`, `myers`;;\n+   `default`;;\n+   `myers`;;\n \tThe basic greedy diff algorithm. Currently, this is the default.\n-`minimal`;;\n+   `minimal`;;\n \tSpend extra time to make sure the smallest possible diff is\n \tproduced.\n-`patience`;;\n+   `patience`;;\n \tUse \"patience diff\" algorithm when generating patches.\n-`histogram`;;\n+   `histogram`;;\n \tThis algorithm extends the patience algorithm to \"support\n \tlow-occurrence common elements\".\n --\n@@ -211,47 +212,47 @@ For instance, if you configured the `diff.algorithm` variable to a\n non-default value and want to use the default one, then you\n have to use `--diff-algorithm=default` option.\n \n---stat[=<width>[,<name-width>[,<count>]]]::\n+`--stat[=<width>[,<name-width>[,<count>]]]`::\n \tGenerate a diffstat. By default, as much space as necessary\n \twill be used for the filename part, and the rest for the graph\n \tpart. Maximum width defaults to terminal width, or 80 columns\n \tif not connected to a terminal, and can be overridden by\n-\t`<width>`. The width of the filename part can be limited by\n-\tgiving another width `<name-width>` after a comma or by setting\n-\t`diff.statNameWidth=<width>`. The width of the graph part can be\n-\tlimited by using `--stat-graph-width=<width>` or by setting\n-\t`diff.statGraphWidth=<width>`. Using `--stat` or\n+\t_<width>_. The width of the filename part can be limited by\n+\tgiving another width _<name-width>_ after a comma or by setting\n+\t`diff.statNameWidth=<name-width>`. The width of the graph part can be\n+\tlimited by using `--stat-graph-width=<graph-width>` or by setting\n+\t`diff.statGraphWidth=<graph-width>`. Using `--stat` or\n \t`--stat-graph-width` affects all commands generating a stat graph,\n \twhile setting `diff.statNameWidth` or `diff.statGraphWidth`\n \tdoes not affect `git format-patch`.\n-\tBy giving a third parameter `<count>`, you can limit the output to\n-\tthe first `<count>` lines, followed by `...` if there are more.\n+\tBy giving a third parameter _<count>_, you can limit the output to\n+\tthe first _<count>_ lines, followed by `...` if there are more.\n +\n These parameters can also be set individually with `--stat-width=<width>`,\n `--stat-name-width=<name-width>` and `--stat-count=<count>`.\n \n---compact-summary::\n+`--compact-summary`::\n \tOutput a condensed summary of extended header information such\n-\tas file creations or deletions (\"new\" or \"gone\", optionally \"+l\"\n-\tif it's a symlink) and mode changes (\"+x\" or \"-x\" for adding\n+\tas file creations or deletions (\"new\" or \"gone\", optionally `+l`\n+\tif it's a symlink) and mode changes (`+x` or `-x` for adding\n \tor removing executable bit respectively) in diffstat. The\n \tinformation is put between the filename part and the graph\n \tpart. Implies `--stat`.\n \n---numstat::\n+`--numstat`::\n \tSimilar to `--stat`, but shows number of added and\n \tdeleted lines in decimal notation and pathname without\n \tabbreviation, to make it more machine friendly.  For\n \tbinary files, outputs two `-` instead of saying\n \t`0 0`.\n \n---shortstat::\n+`--shortstat`::\n \tOutput only the last line of the `--stat` format containing total\n \tnumber of modified files, as well as number of added and deleted\n \tlines.\n \n--X[<param1,param2,...>]::\n---dirstat[=<param1,param2,...>]::\n+`-X [<param>,...]`::\n+`--dirstat[=<param>,...]`::\n \tOutput the distribution of relative amount of changes for each\n \tsub-directory. The behavior of `--dirstat` can be customized by\n \tpassing it a comma separated list of parameters.\n@@ -284,7 +285,7 @@ These parameters can also be set individually with `--stat-width=<width>`,\n \tNote that when using `cumulative`, the sum of the percentages\n \treported may exceed 100%. The default (non-cumulative) behavior can\n \tbe specified with the `noncumulative` parameter.\n-<limit>;;\n+_<limit>_;;\n \tAn integer parameter specifies a cut-off percent (3% by default).\n \tDirectories contributing less than this percentage of the changes\n \tare not shown in the output.\n@@ -295,29 +296,29 @@ directories with less than 10% of the total amount of changed files,\n and accumulating child directory counts in the parent directories:\n `--dirstat=files,10,cumulative`.\n \n---cumulative::\n-\tSynonym for --dirstat=cumulative\n+`--cumulative`::\n+\tSynonym for `--dirstat=cumulative`.\n \n---dirstat-by-file[=<param1,param2>...]::\n-\tSynonym for --dirstat=files,<param1>,<param2>...\n+`--dirstat-by-file[=<param>,...]`::\n+\tSynonym for `--dirstat=files,<param>,...`.\n \n---summary::\n+`--summary`::\n \tOutput a condensed summary of extended header information\n \tsuch as creations, renames and mode changes.\n \n ifndef::git-format-patch[]\n---patch-with-stat::\n+`--patch-with-stat`::\n \tSynonym for `-p --stat`.\n endif::git-format-patch[]\n \n ifndef::git-format-patch[]\n \n--z::\n+`-z`::\n ifdef::git-log[]\n-\tSeparate the commits with NULs instead of newlines.\n+\tSeparate the commits with __NUL__s instead of newlines.\n +\n Also, when `--raw` or `--numstat` has been given, do not munge\n-pathnames and use NULs as output field terminators.\n+pathnames and use __NUL__s as output field terminators.\n endif::git-log[]\n ifndef::git-log[]\n \tWhen `--raw`, `--numstat`, `--name-only` or `--name-status` has been\n@@ -328,89 +329,89 @@ Without this option, pathnames with \"unusual\" characters are quoted as\n explained for the configuration variable `core.quotePath` (see\n linkgit:git-config[1]).\n \n---name-only::\n+`--name-only`::\n \tShow only the name of each changed file in the post-image tree.\n \tThe file names are often encoded in UTF-8.\n \tFor more information see the discussion about encoding in the linkgit:git-log[1]\n \tmanual page.\n \n---name-status::\n+`--name-status`::\n \tShow only the name(s) and status of each changed file. See the description\n \tof the `--diff-filter` option on what the status letters mean.\n \tJust like `--name-only` the file names are often encoded in UTF-8.\n \n---submodule[=<format>]::\n+`--submodule[=<format>]`::\n \tSpecify how differences in submodules are shown.  When specifying\n-\t`--submodule=short` the 'short' format is used.  This format just\n+\t`--submodule=short` the `short` format is used.  This format just\n \tshows the names of the commits at the beginning and end of the range.\n-\tWhen `--submodule` or `--submodule=log` is specified, the 'log'\n+\tWhen `--submodule` or `--submodule=log` is specified, the `log`\n \tformat is used.  This format lists the commits in the range like\n \tlinkgit:git-submodule[1] `summary` does.  When `--submodule=diff`\n-\tis specified, the 'diff' format is used.  This format shows an\n+\tis specified, the `diff` format is used.  This format shows an\n \tinline diff of the changes in the submodule contents between the\n-\tcommit range.  Defaults to `diff.submodule` or the 'short' format\n+\tcommit range.  Defaults to `diff.submodule` or the `short` format\n \tif the config option is unset.\n \n---color[=<when>]::\n+`--color[=<when>]`::\n \tShow colored diff.\n-\t`--color` (i.e. without '=<when>') is the same as `--color=always`.\n-\t'<when>' can be one of `always`, `never`, or `auto`.\n+\t`--color` (i.e. without `=<when>`) is the same as `--color=always`.\n+\t_<when>_ can be one of `always`, `never`, or `auto`.\n ifdef::git-diff[]\n \tIt can be changed by the `color.ui` and `color.diff`\n \tconfiguration settings.\n endif::git-diff[]\n \n---no-color::\n+`--no-color`::\n \tTurn off colored diff.\n ifdef::git-diff[]\n \tThis can be used to override configuration settings.\n endif::git-diff[]\n \tIt is the same as `--color=never`.\n \n---color-moved[=<mode>]::\n+`--color-moved[=<mode>]`::\n \tMoved lines of code are colored differently.\n ifdef::git-diff[]\n \tIt can be changed by the `diff.colorMoved` configuration setting.\n endif::git-diff[]\n-\tThe <mode> defaults to 'no' if the option is not given\n-\tand to 'zebra' if the option with no mode is given.\n+\tThe _<mode>_ defaults to `no` if the option is not given\n+\tand to `zebra` if the option with no mode is given.\n \tThe mode must be one of:\n +\n --\n-no::\n+`no`::\n \tMoved lines are not highlighted.\n-default::\n+`default`::\n \tIs a synonym for `zebra`. This may change to a more sensible mode\n \tin the future.\n-plain::\n+`plain`::\n \tAny line that is added in one location and was removed\n-\tin another location will be colored with 'color.diff.newMoved'.\n-\tSimilarly 'color.diff.oldMoved' will be used for removed lines\n+\tin another location will be colored with `color.diff.newMoved`.\n+\tSimilarly `color.diff.oldMoved` will be used for removed lines\n \tthat are added somewhere else in the diff. This mode picks up any\n \tmoved line, but it is not very useful in a review to determine\n \tif a block of code was moved without permutation.\n-blocks::\n+`blocks`::\n \tBlocks of moved text of at least 20 alphanumeric characters\n \tare detected greedily. The detected blocks are\n-\tpainted using either the 'color.diff.{old,new}Moved' color.\n+\tpainted using either the `color.diff.(old|new)Moved` color.\n \tAdjacent blocks cannot be told apart.\n-zebra::\n-\tBlocks of moved text are detected as in 'blocks' mode. The blocks\n-\tare painted using either the 'color.diff.{old,new}Moved' color or\n-\t'color.diff.{old,new}MovedAlternative'. The change between\n+`zebra`::\n+\tBlocks of moved text are detected as in `blocks` mode. The blocks\n+\tare painted using either the `color.diff.(old|new)Moved` color or\n+\t`color.diff.(old|new)MovedAlternative`. The change between\n \tthe two colors indicates that a new block was detected.\n-dimmed-zebra::\n-\tSimilar to 'zebra', but additional dimming of uninteresting parts\n+`dimmed-zebra`::\n+\tSimilar to `zebra`, but additional dimming of uninteresting parts\n \tof moved code is performed. The bordering lines of two adjacent\n \tblocks are considered interesting, the rest is uninteresting.\n \t`dimmed_zebra` is a deprecated synonym.\n --\n \n---no-color-moved::\n+`--no-color-moved`::\n \tTurn off move detection. This can be used to override configuration\n \tsettings. It is the same as `--color-moved=no`.\n \n---color-moved-ws=<modes>::\n+`--color-moved-ws=<mode>,...`::\n \tThis configures how whitespace is ignored when performing the\n \tmove detection for `--color-moved`.\n ifdef::git-diff[]\n@@ -419,63 +420,62 @@ endif::git-diff[]\n \tThese modes can be given as a comma separated list:\n +\n --\n-no::\n+`no`::\n \tDo not ignore whitespace when performing move detection.\n-ignore-space-at-eol::\n+`ignore-space-at-eol`::\n \tIgnore changes in whitespace at EOL.\n-ignore-space-change::\n+`ignore-space-change`::\n \tIgnore changes in amount of whitespace.  This ignores whitespace\n \tat line end, and considers all other sequences of one or\n \tmore whitespace characters to be equivalent.\n-ignore-all-space::\n+`ignore-all-space`::\n \tIgnore whitespace when comparing lines. This ignores differences\n \teven if one line has whitespace where the other line has none.\n-allow-indentation-change::\n+`allow-indentation-change`::\n \tInitially ignore any whitespace in the move detection, then\n \tgroup the moved code blocks only into a block if the change in\n \twhitespace is the same per line. This is incompatible with the\n \tother modes.\n --\n \n---no-color-moved-ws::\n+`--no-color-moved-ws`::\n \tDo not ignore whitespace when performing move detection. This can be\n \tused to override configuration settings. It is the same as\n \t`--color-moved-ws=no`.\n \n---word-diff[=<mode>]::\n-\tShow a word diff, using the <mode> to delimit changed words.\n+`--word-diff[=<mode>]`::\n \tBy default, words are delimited by whitespace; see\n-\t`--word-diff-regex` below.  The <mode> defaults to 'plain', and\n+\t`--word-diff-regex` below.  The _<mode>_ defaults to `plain`, and\n \tmust be one of:\n +\n --\n-color::\n+`color`::\n \tHighlight changed words using only colors.  Implies `--color`.\n-plain::\n-\tShow words as `[-removed-]` and `{+added+}`.  Makes no\n+`plain`::\n+\tShow words as ++[-removed-]++ and ++{+added+}++.  Makes no\n \tattempts to escape the delimiters if they appear in the input,\n \tso the output may be ambiguous.\n-porcelain::\n+`porcelain`::\n \tUse a special line-based format intended for script\n \tconsumption.  Added/removed/unchanged runs are printed in the\n \tusual unified diff format, starting with a `+`/`-`/` `\n \tcharacter at the beginning of the line and extending to the\n \tend of the line.  Newlines in the input are represented by a\n \ttilde `~` on a line of its own.\n-none::\n+`none`::\n \tDisable word diff again.\n --\n +\n Note that despite the name of the first mode, color is used to\n highlight the changed parts in all modes if enabled.\n \n---word-diff-regex=<regex>::\n-\tUse <regex> to decide what a word is, instead of considering\n+`--word-diff-regex=<regex>`::\n+\tUse _<regex>_ to decide what a word is, instead of considering\n \truns of non-whitespace to be a word.  Also implies\n \t`--word-diff` unless it was already enabled.\n +\n Every non-overlapping match of the\n-<regex> is considered a word.  Anything between these matches is\n+_<regex>_ is considered a word.  Anything between these matches is\n considered whitespace and ignored(!) for the purposes of finding\n differences.  You may want to append `|[^[:space:]]` to your regular\n expression to make sure that it matches all non-whitespace characters.\n@@ -490,20 +490,20 @@ linkgit:gitattributes[5] or linkgit:git-config[1].  Giving it explicitly\n overrides any diff driver or configuration setting.  Diff drivers\n override configuration settings.\n \n---color-words[=<regex>]::\n+`--color-words[=<regex>]`::\n \tEquivalent to `--word-diff=color` plus (if a regex was\n \tspecified) `--word-diff-regex=<regex>`.\n endif::git-format-patch[]\n \n---no-renames::\n+`--no-renames`::\n \tTurn off rename detection, even when the configuration\n \tfile gives the default to do so.\n \n---[no-]rename-empty::\n+`--[no-]rename-empty`::\n \tWhether to use empty blobs as rename source.\n \n ifndef::git-format-patch[]\n---check::\n+`--check`::\n \tWarn if changes introduce conflict markers or whitespace errors.\n \tWhat are considered whitespace errors is controlled by `core.whitespace`\n \tconfiguration.  By default, trailing whitespaces (including\n@@ -511,9 +511,9 @@ ifndef::git-format-patch[]\n \tthat is immediately followed by a tab character inside the\n \tinitial indent of the line are considered whitespace errors.\n \tExits with non-zero status if problems are found. Not compatible\n-\twith --exit-code.\n+\twith `--exit-code`.\n \n---ws-error-highlight=<kind>::\n+`--ws-error-highlight=<kind>`::\n \tHighlight whitespace errors in the `context`, `old` or `new`\n \tlines of the diff.  Multiple values are separated by comma,\n \t`none` resets previous values, `default` reset the list to\n@@ -525,30 +525,30 @@ ifndef::git-format-patch[]\n \n endif::git-format-patch[]\n \n---full-index::\n+`--full-index`::\n \tInstead of the first handful of characters, show the full\n \tpre- and post-image blob object names on the \"index\"\n \tline when generating patch format output.\n \n---binary::\n+`--binary`::\n \tIn addition to `--full-index`, output a binary diff that\n \tcan be applied with `git-apply`.\n ifndef::git-format-patch[]\n \tImplies `--patch`.\n endif::git-format-patch[]\n \n---abbrev[=<n>]::\n+`--abbrev[=<n>]`::\n \tInstead of showing the full 40-byte hexadecimal object\n \tname in diff-raw format output and diff-tree header\n-\tlines, show the shortest prefix that is at least '<n>'\n+\tlines, show the shortest prefix that is at least _<n>_\n \thexdigits long that uniquely refers the object.\n \tIn diff-patch output format, `--full-index` takes higher\n \tprecedence, i.e. if `--full-index` is specified, full blob\n \tnames will be shown regardless of `--abbrev`.\n \tNon default number of digits can be specified with `--abbrev=<n>`.\n \n--B[<n>][/<m>]::\n---break-rewrites[=[<n>][/<m>]]::\n+`-B[<n>][/<m>]`::\n+`--break-rewrites[=[<n>][/<m>]]`::\n \tBreak complete rewrite changes into pairs of delete and\n \tcreate. This serves two purposes:\n +\n@@ -556,22 +556,22 @@ It affects the way a change that amounts to a total rewrite of a file\n not as a series of deletion and insertion mixed together with a very\n few lines that happen to match textually as the context, but as a\n single deletion of everything old followed by a single insertion of\n-everything new, and the number `m` controls this aspect of the -B\n+everything new, and the number _<m>_ controls this aspect of the `-B`\n option (defaults to 60%). `-B/70%` specifies that less than 30% of the\n original should remain in the result for Git to consider it a total\n rewrite (i.e. otherwise the resulting patch will be a series of\n deletion and insertion mixed together with context lines).\n +\n-When used with -M, a totally-rewritten file is also considered as the\n-source of a rename (usually -M only considers a file that disappeared\n-as the source of a rename), and the number `n` controls this aspect of\n-the -B option (defaults to 50%). `-B20%` specifies that a change with\n+When used with `-M`, a totally-rewritten file is also considered as the\n+source of a rename (usually `-M` only considers a file that disappeared\n+as the source of a rename), and the number _<n>_ controls this aspect of\n+the `-B` option (defaults to 50%). `-B20%` specifies that a change with\n addition and deletion compared to 20% or more of the file's size are\n eligible for being picked up as a possible source of a rename to\n another file.\n \n--M[<n>]::\n---find-renames[=<n>]::\n+`-M[<n>]`::\n+`--find-renames[=<n>]`::\n ifndef::git-log[]\n \tDetect renames.\n endif::git-log[]\n@@ -580,7 +580,7 @@ ifdef::git-log[]\n \tFor following files across renames while traversing history, see\n \t`--follow`.\n endif::git-log[]\n-\tIf `n` is specified, it is a threshold on the similarity\n+\tIf _<n>_ is specified, it is a threshold on the similarity\n \tindex (i.e. amount of addition/deletions compared to the\n \tfile's size). For example, `-M90%` means Git should consider a\n \tdelete/add pair to be a rename if more than 90% of the file\n@@ -590,12 +590,12 @@ endif::git-log[]\n \tthe same as `-M5%`.  To limit detection to exact renames, use\n \t`-M100%`.  The default similarity index is 50%.\n \n--C[<n>]::\n---find-copies[=<n>]::\n+`-C[<n>]`::\n+`--find-copies[=<n>]`::\n \tDetect copies as well as renames.  See also `--find-copies-harder`.\n-\tIf `n` is specified, it has the same meaning as for `-M<n>`.\n+\tIf _<n>_ is specified, it has the same meaning as for `-M<n>`.\n \n---find-copies-harder::\n+`--find-copies-harder`::\n \tFor performance reasons, by default, `-C` option finds copies only\n \tif the original file of the copy was modified in the same\n \tchangeset.  This flag makes the command\n@@ -604,8 +604,8 @@ endif::git-log[]\n \tprojects, so use it with caution.  Giving more than one\n \t`-C` option has the same effect.\n \n--D::\n---irreversible-delete::\n+`-D`::\n+`--irreversible-delete`::\n \tOmit the preimage for deletes, i.e. print only the header but not\n \tthe diff between the preimage and `/dev/null`. The resulting patch\n \tis not meant to be applied with `patch` or `git apply`; this is\n@@ -617,7 +617,7 @@ endif::git-log[]\n When used together with `-B`, omit also the preimage in the deletion part\n of a delete/create pair.\n \n--l<num>::\n+`-l<num>`::\n \tThe `-M` and `-C` options involve some preliminary steps that\n \tcan detect subsets of renames/copies cheaply, followed by an\n \texhaustive fallback portion that compares all remaining\n@@ -627,11 +627,11 @@ of a delete/create pair.\n \tdestinations, this exhaustive check is O(N^2).  This option\n \tprevents the exhaustive portion of rename/copy detection from\n \trunning if the number of source/destination files involved\n-\texceeds the specified number.  Defaults to diff.renameLimit.\n+\texceeds the specified number.  Defaults to `diff.renameLimit`.\n \tNote that a value of 0 is treated as unlimited.\n \n ifndef::git-format-patch[]\n---diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]::\n+`--diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]`::\n \tSelect only files that are Added (`A`), Copied (`C`),\n \tDeleted (`D`), Modified (`M`), Renamed (`R`), have their\n \ttype (i.e. regular file, symlink, submodule, ...) changed (`T`),\n@@ -649,9 +649,9 @@ Also, these upper-case letters can be downcased to exclude.  E.g.\n Note that not all diffs can feature all types. For instance, copied and\n renamed entries cannot appear if detection for those types is disabled.\n \n--S<string>::\n+`-S<string>`::\n \tLook for differences that change the number of occurrences of\n-\tthe specified string (i.e. addition/deletion) in a file.\n+\tthe specified _<string>_ (i.e. addition/deletion) in a file.\n \tIntended for the scripter's use.\n +\n It is useful when you're looking for an exact block of code (like a\n@@ -662,11 +662,11 @@ very first version of the block.\n +\n Binary files are searched as well.\n \n--G<regex>::\n+`-G<regex>`::\n \tLook for differences whose patch text contains added/removed\n-\tlines that match <regex>.\n+\tlines that match _<regex>_.\n +\n-To illustrate the difference between `-S<regex> --pickaxe-regex` and\n+To illustrate the difference between `-S<regex>` `--pickaxe-regex` and\n `-G<regex>`, consider a commit with the following diff in the same\n file:\n +\n@@ -686,7 +686,7 @@ filter will be ignored.\n See the 'pickaxe' entry in linkgit:gitdiffcore[7] for more\n information.\n \n---find-object=<object-id>::\n+`--find-object=<object-id>`::\n \tLook for differences that change the number of occurrences of\n \tthe specified object. Similar to `-S`, just the argument is different\n \tin that it doesn't search for a specific string but for a specific\n@@ -695,25 +695,25 @@ information.\n The object can be a blob or a submodule commit. It implies the `-t` option in\n `git-log` to also find trees.\n \n---pickaxe-all::\n+`--pickaxe-all`::\n \tWhen `-S` or `-G` finds a change, show all the changes in that\n \tchangeset, not just the files that contain the change\n-\tin <string>.\n+\tin _<string>_.\n \n---pickaxe-regex::\n-\tTreat the <string> given to `-S` as an extended POSIX regular\n+`--pickaxe-regex`::\n+\tTreat the _<string>_ given to `-S` as an extended POSIX regular\n \texpression to match.\n \n endif::git-format-patch[]\n \n--O<orderfile>::\n+`-O<orderfile>`::\n \tControl the order in which files appear in the output.\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 +\n The output order is determined by the order of glob patterns in\n-<orderfile>.\n+_<orderfile>_.\n All files with pathnames that match the first pattern are output\n first, all files with pathnames that match the second pattern (but not\n the first) are output next, and so on.\n@@ -724,7 +724,7 @@ If multiple pathnames have the same rank (they match the same pattern\n but no earlier patterns), their output order relative to each other is\n the normal order.\n +\n-<orderfile> is parsed as follows:\n+_<orderfile>_ is parsed as follows:\n +\n --\n  - Blank lines are ignored, so they can be used as separators for\n@@ -738,106 +738,107 @@ the normal order.\n --\n +\n Patterns have the same syntax and semantics as patterns used for\n-fnmatch(3) without the FNM_PATHNAME flag, except a pathname also\n+`fnmatch`(3) without the `FNM_PATHNAME` flag, except a pathname also\n matches a pattern if removing any number of the final pathname\n components matches the pattern.  For example, the pattern \"`foo*bar`\"\n matches \"`fooasdfbar`\" and \"`foo/bar/baz/asdf`\" but not \"`foobarx`\".\n \n---skip-to=<file>::\n---rotate-to=<file>::\n-\tDiscard the files before the named <file> from the output\n+`--skip-to=<file>`::\n+`--rotate-to=<file>`::\n+\tDiscard the files before the named _<file>_ from the output\n \t(i.e. 'skip to'), or move them to the end of the output\n \t(i.e. 'rotate to').  These options were invented primarily for the use\n \tof the `git difftool` command, and may not be very useful\n \totherwise.\n \n ifndef::git-format-patch[]\n--R::\n+`-R`::\n \tSwap two inputs; that is, show differences from index or\n \ton-disk file to tree contents.\n endif::git-format-patch[]\n \n---relative[=<path>]::\n---no-relative::\n+`--relative[=<path>]`::\n+`--no-relative`::\n \tWhen run from a subdirectory of the project, it can be\n \ttold to exclude changes outside the directory and show\n \tpathnames relative to it with this option.  When you are\n \tnot in a subdirectory (e.g. in a bare repository), you\n \tcan name which subdirectory to make the output relative\n-\tto by giving a <path> as an argument.\n+\tto by giving a _<path>_ as an argument.\n \t`--no-relative` can be used to countermand both `diff.relative` config\n \toption and previous `--relative`.\n \n--a::\n---text::\n+`-a`::\n+`--text`::\n \tTreat all files as text.\n \n---ignore-cr-at-eol::\n+`--ignore-cr-at-eol`::\n \tIgnore carriage-return at the end of line when doing a comparison.\n \n---ignore-space-at-eol::\n+`--ignore-space-at-eol`::\n \tIgnore changes in whitespace at EOL.\n \n--b::\n---ignore-space-change::\n+`-b`::\n+`--ignore-space-change`::\n \tIgnore changes in amount of whitespace.  This ignores whitespace\n \tat line end, and considers all other sequences of one or\n \tmore whitespace characters to be equivalent.\n \n--w::\n---ignore-all-space::\n+`-w`::\n+`--ignore-all-space`::\n \tIgnore whitespace when comparing lines.  This ignores\n \tdifferences even if one line has whitespace where the other\n \tline has none.\n \n---ignore-blank-lines::\n+`--ignore-blank-lines`::\n \tIgnore changes whose lines are all blank.\n \n--I<regex>::\n---ignore-matching-lines=<regex>::\n-\tIgnore changes whose all lines match <regex>.  This option may\n+\n+`-I<regex>`::\n+`--ignore-matching-lines=<regex>`::\n+\tIgnore changes whose all lines match _<regex>_.  This option may\n \tbe specified more than once.\n \n---inter-hunk-context=<lines>::\n-\tShow the context between diff hunks, up to the specified number\n+`--inter-hunk-context=<number>`::\n+\tShow the context between diff hunks, up to the specified _<number>_\n \tof lines, thereby fusing hunks that are close to each other.\n \tDefaults to `diff.interHunkContext` or 0 if the config option\n \tis unset.\n \n--W::\n---function-context::\n+`-W`::\n+`--function-context`::\n \tShow whole function as context lines for each change.\n \tThe function names are determined in the same way as\n-\t`git diff` works out patch hunk headers (see 'Defining a\n-\tcustom hunk-header' in linkgit:gitattributes[5]).\n+\t`git diff` works out patch hunk headers (see \"Defining a\n+\tcustom hunk-header\" in linkgit:gitattributes[5]).\n \n ifndef::git-format-patch[]\n ifndef::git-log[]\n---exit-code::\n-\tMake the program exit with codes similar to diff(1).\n+`--exit-code`::\n+\tMake the program exit with codes similar to `diff`(1).\n \tThat is, it exits with 1 if there were differences and\n \t0 means no differences.\n \n---quiet::\n+`--quiet`::\n \tDisable all output of the program. Implies `--exit-code`.\n \tDisables execution of external diff helpers whose exit code\n \tis not trusted, i.e. their respective configuration option\n-\t`diff.trustExitCode` or `diff.<driver>.trustExitCode` or\n+\t`diff.trustExitCode` or ++diff.++__<driver>__++.trustExitCode++ or\n \tenvironment variable `GIT_EXTERNAL_DIFF_TRUST_EXIT_CODE` is\n \tfalse.\n endif::git-log[]\n endif::git-format-patch[]\n \n---ext-diff::\n+`--ext-diff`::\n \tAllow an external diff helper to be executed. If you set an\n \texternal diff driver with linkgit:gitattributes[5], you need\n \tto use this option with linkgit:git-log[1] and friends.\n \n---no-ext-diff::\n+`--no-ext-diff`::\n \tDisallow external diff drivers.\n \n---textconv::\n---no-textconv::\n+`--textconv`::\n+`--no-textconv`::\n \tAllow (or disallow) external text conversion filters to be run\n \twhen comparing binary files. See linkgit:gitattributes[5] for\n \tdetails. Because textconv filters are typically a one-way\n@@ -847,42 +848,42 @@ endif::git-format-patch[]\n \tlinkgit:git-log[1], but not for linkgit:git-format-patch[1] or\n \tdiff plumbing commands.\n \n---ignore-submodules[=<when>]::\n-\tIgnore changes to submodules in the diff generation. <when> can be\n-\teither \"none\", \"untracked\", \"dirty\" or \"all\", which is the default.\n-\tUsing \"none\" will consider the submodule modified when it either contains\n-\tuntracked or modified files or its HEAD differs from the commit recorded\n+\n+`--ignore-submodules[=(none|untracked|dirty|all)]`::\n+\tIgnore changes to submodules in the diff generation. `all` is the default.\n+\tUsing `none` will consider the submodule modified when it either contains\n+\tuntracked or modified files or its `HEAD` differs from the commit recorded\n \tin the superproject and can be used to override any settings of the\n-\t'ignore' option in linkgit:git-config[1] or linkgit:gitmodules[5]. When\n-\t\"untracked\" is used submodules are not considered dirty when they only\n+\t`ignore` option in linkgit:git-config[1] or linkgit:gitmodules[5]. When\n+\t`untracked` is used submodules are not considered dirty when they only\n \tcontain untracked content (but they are still scanned for modified\n-\tcontent). Using \"dirty\" ignores all changes to the work tree of submodules,\n+\tcontent). Using `dirty` ignores all changes to the work tree of submodules,\n \tonly changes to the commits stored in the superproject are shown (this was\n-\tthe behavior until 1.7.0). Using \"all\" hides all changes to submodules.\n+\tthe behavior until 1.7.0). Using `all` hides all changes to submodules.\n \n---src-prefix=<prefix>::\n-\tShow the given source prefix instead of \"a/\".\n+`--src-prefix=<prefix>`::\n+\tShow the given source _<prefix>_ instead of \"a/\".\n \n---dst-prefix=<prefix>::\n-\tShow the given destination prefix instead of \"b/\".\n+`--dst-prefix=<prefix>`::\n+\tShow the given destination _<prefix>_ instead of \"b/\".\n \n---no-prefix::\n+`--no-prefix`::\n \tDo not show any source or destination prefix.\n \n---default-prefix::\n+`--default-prefix`::\n \tUse the default source and destination prefixes (\"a/\" and \"b/\").\n \tThis overrides configuration variables such as `diff.noprefix`,\n \t`diff.srcPrefix`, `diff.dstPrefix`, and `diff.mnemonicPrefix`\n-\t(see `git-config`(1)).\n+\t(see linkgit:git-config[1]).\n \n---line-prefix=<prefix>::\n-\tPrepend an additional prefix to every line of output.\n+`--line-prefix=<prefix>`::\n+\tPrepend an additional _<prefix>_ to every line of output.\n \n---ita-invisible-in-index::\n-\tBy default entries added by \"git add -N\" appear as an existing\n-\tempty file in \"git diff\" and a new file in \"git diff --cached\".\n-\tThis option makes the entry appear as a new file in \"git diff\"\n-\tand non-existent in \"git diff --cached\". This option could be\n+`--ita-invisible-in-index`::\n+\tBy default entries added by `git add -N` appear as an existing\n+\tempty file in `git diff` and a new file in `git diff --cached`.\n+\tThis option makes the entry appear as a new file in `git diff`\n+\tand non-existent in `git diff --cached`. This option could be\n \treverted with `--ita-visible-in-index`. Both options are\n \texperimental and could be removed in future.\n \n-- \ngitgitgadget\n\n"},{"id":"507417","messageId":"1154462f8bea8110afcf8a71bb5cdb3d040eb1ab.1731785769.git.gitgitgadget@gmail.com","threadId":"61899","inReplyTo":"pull.1769.v3.git.1731785768.gitgitgadget@gmail.com","subject":"[PATCH v3 4/5] doc: git-diff: apply format changes to diff-generate-patch","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-11-16T19:36:07Z","receivedAt":"2024-11-16T19:36: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\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\n---\n Documentation/diff-generate-patch.txt | 44 ++++++++++++++-------------\n 1 file changed, 23 insertions(+), 21 deletions(-)\n\ndiff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-generate-patch.txt\nindex 4b5aa5c2e04..e5c813c96f3 100644\n--- a/Documentation/diff-generate-patch.txt\n+++ b/Documentation/diff-generate-patch.txt\n@@ -14,7 +14,7 @@ You can customize the creation of patch text via the\n `GIT_EXTERNAL_DIFF` and the `GIT_DIFF_OPTS` environment variables\n (see linkgit:git[1]), and the `diff` attribute (see linkgit:gitattributes[5]).\n \n-What the -p option produces is slightly different from the traditional\n+What the `-p` option produces is slightly different from the traditional\n diff format:\n \n 1.   It is preceded by a \"git diff\" header that looks like this:\n@@ -30,20 +30,21 @@ name of the source file of the rename/copy and the name of\n the file that the rename/copy produces, respectively.\n \n 2.   It is followed by one or more extended header lines:\n-\n-       old mode <mode>\n-       new mode <mode>\n-       deleted file mode <mode>\n-       new file mode <mode>\n-       copy from <path>\n-       copy to <path>\n-       rename from <path>\n-       rename to <path>\n-       similarity index <number>\n-       dissimilarity index <number>\n-       index <hash>..<hash> <mode>\n +\n-File modes are printed as 6-digit octal numbers including the file type\n+[synopsis]\n+old mode <mode>\n+new mode <mode>\n+deleted file mode <mode>\n+new file mode <mode>\n+copy from <path>\n+copy to <path>\n+rename from <path>\n+rename to <path>\n+similarity index <number>\n+dissimilarity index <number>\n+index <hash>..<hash> <mode>\n++\n+File modes _<mode>_ are printed as 6-digit octal numbers including the file type\n and file permission bits.\n +\n Path names in extended headers do not include the `a/` and `b/` prefixes.\n@@ -56,7 +57,7 @@ files, while 100% dissimilarity means that no line from the old\n file made it into the new one.\n +\n The index line includes the blob object names before and after the change.\n-The <mode> is included if the file mode does not change; otherwise,\n+The _<mode>_ is included if the file mode does not change; otherwise,\n separate lines indicate the old and the new mode.\n \n 3.  Pathnames with \"unusual\" characters are quoted as explained for\n@@ -134,17 +135,18 @@ or like this (when the `--cc` option is used):\n \n 2.   It is followed by one or more extended header lines\n      (this example shows a merge with two parents):\n-\n-       index <hash>,<hash>..<hash>\n-       mode <mode>,<mode>..<mode>\n-       new file mode <mode>\n-       deleted file mode <mode>,<mode>\n++\n+[synopsis]\n+index <hash>,<hash>..<hash>\n+mode <mode>,<mode>`..`<mode>\n+new file mode <mode>\n+deleted file mode <mode>,<mode>\n +\n The `mode <mode>,<mode>..<mode>` line appears only if at least one of\n the <mode> is different from the rest. Extended headers with\n information about detected content movement (renames and\n copying detection) are designed to work with the diff of two\n-<tree-ish> and are not used by combined diff format.\n+_<tree-ish>_ and are not used by combined diff format.\n \n 3.   It is followed by a two-line from-file/to-file header:\n \n-- \ngitgitgadget\n\n"},{"id":"507418","messageId":"4ec2fd9c3c68163a358937498b523292c3d38465.1731785769.git.gitgitgadget@gmail.com","threadId":"61899","inReplyTo":"pull.1769.v3.git.1731785768.gitgitgadget@gmail.com","subject":"[PATCH v3 5/5] doc: git-diff: apply format changes to config part","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-11-16T19:36:08Z","receivedAt":"2024-11-16T19:36:19Z","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\nBy the way, we also change the sentences where git-diff would refer to\nitself, so that no link is created in the HTML output.\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\n---\n Documentation/config/diff.txt | 204 ++++++++++++++++++----------------\n 1 file changed, 111 insertions(+), 93 deletions(-)\n\ndiff --git a/Documentation/config/diff.txt b/Documentation/config/diff.txt\nindex 190bda17e51..45f3fe855c5 100644\n--- a/Documentation/config/diff.txt\n+++ b/Documentation/config/diff.txt\n@@ -1,18 +1,25 @@\n-diff.autoRefreshIndex::\n-\tWhen using 'git diff' to compare with work tree\n+`diff.autoRefreshIndex`::\n+\tWhen using `git diff` to compare with work tree\n \tfiles, do not consider stat-only changes as changed.\n \tInstead, silently run `git update-index --refresh` to\n \tupdate the cached stat information for paths whose\n \tcontents in the work tree match the contents in the\n-\tindex.  This option defaults to true.  Note that this\n-\taffects only 'git diff' Porcelain, and not lower level\n-\t'diff' commands such as 'git diff-files'.\n+\tindex.  This option defaults to `true`.  Note that this\n+\taffects only `git diff` Porcelain, and not lower level\n+\t`diff` commands such as `git diff-files`.\n \n-diff.dirstat::\n+`diff.dirstat`::\n+ifdef::git-diff[]\n+\tA comma separated list of `--dirstat` parameters specifying the\n+\tdefault behavior of the `--dirstat` option to `git diff` and friends.\n+endif::git-diff[]\n+ifndef::git-diff[]\n \tA comma separated list of `--dirstat` parameters specifying the\n \tdefault behavior of the `--dirstat` option to linkgit:git-diff[1]\n-\tand friends. The defaults can be overridden on the command line\n-\t(using `--dirstat=<param1,param2,...>`). The fallback defaults\n+\tand friends.\n+endif::git-diff[]\n+\tThe defaults can be overridden on the command line\n+\t(using `--dirstat=<param>,...`). The fallback defaults\n \t(when not changed by `diff.dirstat`) are `changes,noncumulative,3`.\n \tThe following parameters are available:\n +\n@@ -41,7 +48,7 @@ diff.dirstat::\n \tNote that when using `cumulative`, the sum of the percentages\n \treported may exceed 100%. The default (non-cumulative) behavior can\n \tbe specified with the `noncumulative` parameter.\n-<limit>;;\n+_<limit>_;;\n \tAn integer parameter specifies a cut-off percent (3% by default).\n \tDirectories contributing less than this percentage of the changes\n \tare not shown in the output.\n@@ -52,58 +59,58 @@ directories with less than 10% of the total amount of changed files,\n and accumulating child directory counts in the parent directories:\n `files,10,cumulative`.\n \n-diff.statNameWidth::\n-\tLimit the width of the filename part in --stat output. If set, applies\n-\tto all commands generating --stat output except format-patch.\n+`diff.statNameWidth`::\n+\tLimit the width of the filename part in `--stat` output. If set, applies\n+\tto all commands generating `--stat` output except `format-patch`.\n \n-diff.statGraphWidth::\n-\tLimit the width of the graph part in --stat output. If set, applies\n-\tto all commands generating --stat output except format-patch.\n+`diff.statGraphWidth`::\n+\tLimit the width of the graph part in `--stat` output. If set, applies\n+\tto all commands generating `--stat` output except `format-patch`.\n \n-diff.context::\n-\tGenerate diffs with <n> lines of context instead of the default\n-\tof 3. This value is overridden by the -U option.\n+`diff.context`::\n+\tGenerate diffs with _<n>_ lines of context instead of the default\n+\tof 3. This value is overridden by the `-U` option.\n \n-diff.interHunkContext::\n+`diff.interHunkContext`::\n \tShow the context between diff hunks, up to the specified number\n \tof lines, thereby fusing the hunks that are close to each other.\n \tThis value serves as the default for the `--inter-hunk-context`\n \tcommand line option.\n \n-diff.external::\n+`diff.external`::\n \tIf this config variable is set, diff generation is not\n \tperformed using the internal diff machinery, but using the\n-\tgiven command.  Can be overridden with the `GIT_EXTERNAL_DIFF'\n+\tgiven command.  Can be overridden with the `GIT_EXTERNAL_DIFF`\n \tenvironment variable.  The command is called with parameters\n \tas described under \"git Diffs\" in linkgit:git[1].  Note: if\n \tyou want to use an external diff program only on a subset of\n \tyour files, you might want to use linkgit:gitattributes[5] instead.\n \n-diff.trustExitCode::\n-\tIf this boolean value is set to true then the\n+`diff.trustExitCode`::\n+\tIf this boolean value is set to `true` then the\n \t`diff.external` command is expected to return exit code\n \t0 if it considers the input files to be equal or 1 if it\n-\tconsiders them to be different, like `diff(1)`.\n-\tIf it is set to false, which is the default, then the command\n-\tis expected to return exit code 0 regardless of equality.\n+\tconsiders them to be different, like `diff`(1).\n+\tIf it is set to `false`, which is the default, then the command\n+\tis expected to return exit code `0` regardless of equality.\n \tAny other exit code causes Git to report a fatal error.\n \n-diff.ignoreSubmodules::\n-\tSets the default value of --ignore-submodules. Note that this\n-\taffects only 'git diff' Porcelain, and not lower level 'diff'\n-\tcommands such as 'git diff-files'. 'git checkout'\n-\tand 'git switch' also honor\n+`diff.ignoreSubmodules`::\n+\tSets the default value of `--ignore-submodules`. Note that this\n+\taffects only `git diff` Porcelain, and not lower level `diff`\n+\tcommands such as `git diff-files`. `git checkout`\n+\tand `git switch` also honor\n \tthis setting when reporting uncommitted changes. Setting it to\n-\t'all' disables the submodule summary normally shown by 'git commit'\n-\tand 'git status' when `status.submoduleSummary` is set unless it is\n-\toverridden by using the --ignore-submodules command-line option.\n-\tThe 'git submodule' commands are not affected by this setting.\n+\t`all` disables the submodule summary normally shown by `git commit`\n+\tand `git status` when `status.submoduleSummary` is set unless it is\n+\toverridden by using the `--ignore-submodules` command-line option.\n+\tThe `git submodule` commands are not affected by this setting.\n \tBy default this is set to untracked so that any untracked\n \tsubmodules are ignored.\n \n-diff.mnemonicPrefix::\n-\tIf set, 'git diff' uses a prefix pair that is different from the\n-\tstandard \"a/\" and \"b/\" depending on what is being compared.  When\n+`diff.mnemonicPrefix`::\n+\tIf set, `git diff` uses a prefix pair that is different from the\n+\tstandard `a/` and `b/` depending on what is being compared.  When\n \tthis configuration is in effect, reverse diff output also swaps\n \tthe order of the prefixes:\n `git diff`;;\n@@ -112,111 +119,117 @@ diff.mnemonicPrefix::\n \t compares a (c)ommit and the (w)ork tree;\n `git diff --cached`;;\n \tcompares a (c)ommit and the (i)ndex;\n-`git diff HEAD:file1 file2`;;\n+`git diff HEAD:<file1> <file2>`;;\n \tcompares an (o)bject and a (w)ork tree entity;\n-`git diff --no-index a b`;;\n-\tcompares two non-git things (1) and (2).\n+`git diff --no-index <a> <b>`;;\n+\tcompares two non-git things _<a>_ and _<b>_.\n \n-diff.noPrefix::\n-\tIf set, 'git diff' does not show any source or destination prefix.\n+`diff.noPrefix`::\n+\tIf set, `git diff` does not show any source or destination prefix.\n \n-diff.srcPrefix::\n-\tIf set, 'git diff' uses this source prefix. Defaults to \"a/\".\n+`diff.srcPrefix`::\n+\tIf set, `git diff` uses this source prefix. Defaults to `a/`.\n \n-diff.dstPrefix::\n-\tIf set, 'git diff' uses this destination prefix. Defaults to \"b/\".\n+`diff.dstPrefix`::\n+\tIf set, `git diff` uses this destination prefix. Defaults to `b/`.\n \n-diff.relative::\n-\tIf set to 'true', 'git diff' does not show changes outside of the directory\n+`diff.relative`::\n+\tIf set to `true`, `git diff` does not show changes outside of the directory\n \tand show pathnames relative to the current directory.\n \n-diff.orderFile::\n+`diff.orderFile`::\n \tFile indicating how to order files within a diff.\n-\tSee the '-O' option to linkgit:git-diff[1] for details.\n+ifdef::git-diff[]\n+\tSee the `-O` option for details.\n+endif::git-diff[]\n+ifndef::git-diff[]\n+\tSee the `-O` option to linkgit:git-diff[1] for details.\n+endif::git-diff[]\n \tIf `diff.orderFile` is a relative pathname, it is treated as\n \trelative to the top of the working tree.\n \n-diff.renameLimit::\n+`diff.renameLimit`::\n \tThe number of files to consider in the exhaustive portion of\n-\tcopy/rename detection; equivalent to the 'git diff' option\n+\tcopy/rename detection; equivalent to the `git diff` option\n \t`-l`.  If not set, the default value is currently 1000.  This\n \tsetting has no effect if rename detection is turned off.\n \n-diff.renames::\n-\tWhether and how Git detects renames.  If set to \"false\",\n-\trename detection is disabled. If set to \"true\", basic rename\n-\tdetection is enabled.  If set to \"copies\" or \"copy\", Git will\n-\tdetect copies, as well.  Defaults to true.  Note that this\n-\taffects only 'git diff' Porcelain like linkgit:git-diff[1] and\n+`diff.renames`::\n+\tWhether and how Git detects renames.  If set to `false`,\n+\trename detection is disabled. If set to `true`, basic rename\n+\tdetection is enabled.  If set to `copies` or `copy`, Git will\n+\tdetect copies, as well.  Defaults to `true`.  Note that this\n+\taffects only `git diff` Porcelain like linkgit:git-diff[1] and\n \tlinkgit:git-log[1], and not lower level commands such as\n \tlinkgit:git-diff-files[1].\n \n-diff.suppressBlankEmpty::\n+`diff.suppressBlankEmpty`::\n \tA boolean to inhibit the standard behavior of printing a space\n-\tbefore each empty output line. Defaults to false.\n+\tbefore each empty output line. Defaults to `false`.\n \n-diff.submodule::\n+`diff.submodule`::\n \tSpecify the format in which differences in submodules are\n-\tshown.  The \"short\" format just shows the names of the commits\n-\tat the beginning and end of the range. The \"log\" format lists\n+\tshown.  The `short` format just shows the names of the commits\n+\tat the beginning and end of the range. The `log` format lists\n \tthe commits in the range like linkgit:git-submodule[1] `summary`\n-\tdoes. The \"diff\" format shows an inline diff of the changed\n-\tcontents of the submodule. Defaults to \"short\".\n+\tdoes. The `diff` format shows an inline diff of the changed\n+\tcontents of the submodule. Defaults to `short`.\n \n-diff.wordRegex::\n+`diff.wordRegex`::\n \tA POSIX Extended Regular Expression used to determine what is a \"word\"\n \twhen performing word-by-word difference calculations.  Character\n \tsequences that match the regular expression are \"words\", all other\n \tcharacters are *ignorable* whitespace.\n \n-diff.<driver>.command::\n+`diff.<driver>.command`::\n \tThe custom diff driver command.  See linkgit:gitattributes[5]\n \tfor details.\n \n-diff.<driver>.trustExitCode::\n-\tIf this boolean value is set to true then the\n+`diff.<driver>.trustExitCode`::\n+\tIf this boolean value is set to `true` then the\n \t`diff.<driver>.command` command is expected to return exit code\n \t0 if it considers the input files to be equal or 1 if it\n-\tconsiders them to be different, like `diff(1)`.\n-\tIf it is set to false, which is the default, then the command\n+\tconsiders them to be different, like `diff`(1).\n+\tIf it is set to `false`, which is the default, then the command\n \tis expected to return exit code 0 regardless of equality.\n \tAny other exit code causes Git to report a fatal error.\n \n-diff.<driver>.xfuncname::\n+`diff.<driver>.xfuncname`::\n \tThe regular expression that the diff driver should use to\n \trecognize the hunk header.  A built-in pattern may also be used.\n \tSee linkgit:gitattributes[5] for details.\n \n-diff.<driver>.binary::\n-\tSet this option to true to make the diff driver treat files as\n+`diff.<driver>.binary`::\n+\tSet this option to `true` to make the diff driver treat files as\n \tbinary.  See linkgit:gitattributes[5] for details.\n \n-diff.<driver>.textconv::\n+`diff.<driver>.textconv`::\n \tThe command that the diff driver should call to generate the\n \ttext-converted version of a file.  The result of the\n \tconversion is used to generate a human-readable diff.  See\n \tlinkgit:gitattributes[5] for details.\n \n-diff.<driver>.wordRegex::\n+`diff.<driver>.wordRegex`::\n \tThe regular expression that the diff driver should use to\n \tsplit words in a line.  See linkgit:gitattributes[5] for\n \tdetails.\n \n-diff.<driver>.cachetextconv::\n-\tSet this option to true to make the diff driver cache the text\n+`diff.<driver>.cachetextconv`::\n+\tSet this option to `true` to make the diff driver cache the text\n \tconversion outputs.  See linkgit:gitattributes[5] for details.\n \n include::../mergetools-diff.txt[]\n \n-diff.indentHeuristic::\n+`diff.indentHeuristic`::\n \tSet this option to `false` to disable the default heuristics\n \tthat shift diff hunk boundaries to make patches easier to read.\n \n-diff.algorithm::\n+`diff.algorithm`::\n \tChoose a diff algorithm.  The variants are as follows:\n +\n --\n-`default`, `myers`;;\n+`default`;;\n+`myers`;;\n \tThe basic greedy diff algorithm. Currently, this is the default.\n `minimal`;;\n \tSpend extra time to make sure the smallest possible diff is\n@@ -229,7 +242,7 @@ diff.algorithm::\n --\n +\n \n-diff.wsErrorHighlight::\n+`diff.wsErrorHighlight`::\n \tHighlight whitespace errors in the `context`, `old` or `new`\n \tlines of the diff.  Multiple values are separated by comma,\n \t`none` resets previous values, `default` reset the list to\n@@ -238,14 +251,19 @@ diff.wsErrorHighlight::\n \tThe command line option `--ws-error-highlight=<kind>`\n \toverrides this setting.\n \n-diff.colorMoved::\n-\tIf set to either a valid `<mode>` or a true value, moved lines\n-\tin a diff are colored differently, for details of valid modes\n-\tsee '--color-moved' in linkgit:git-diff[1]. If simply set to\n-\ttrue the default color mode will be used. When set to false,\n-\tmoved lines are not colored.\n-\n-diff.colorMovedWS::\n+`diff.colorMoved`::\n+\tIf set to either a valid _<mode>_ or a `true` value, moved lines\n+\tin a diff are colored differently.\n+ifdef::git-diff[]\n+\tFor details of valid modes see `--color-moved`.\n+endif::git-diff[]\n+ifndef::git-diff[]\n+\tFor details of valid modes see `--color-moved` in linkgit:git-diff[1].\n+endif::git-diff[]\n+\tIf simply set to `true` the default color mode will be used. When\n+\tset to `false`, moved lines are not colored.\n+\n+`diff.colorMovedWS`::\n \tWhen moved lines are colored using e.g. the `diff.colorMoved` setting,\n-\tthis option controls the `<mode>` how spaces are treated.\n-\tFor details of valid modes see '--color-moved-ws' in linkgit:git-diff[1].\n+\tthis option controls the mode how spaces are treated.\n+\tFor details of valid modes see `--color-moved-ws` in linkgit:git-diff[1].\n-- \ngitgitgadget\n"},{"id":"507440","messageId":"7f24a030-bae2-4712-8593-61a9d4089cfb@kdbg.org","threadId":"61899","inReplyTo":"6841bd5825be8e7b17c2f9c3a997de29ffa3a540.1731785769.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v3 1/5] doc: git-diff: apply new documentation guidelines","fromName":"Johannes Sixt","fromEmail":"j6t@kdbg.org","sentAt":"2024-11-17T14:04:13Z","receivedAt":"2024-11-17T14:49:00Z","isPatch":true,"sender":{"key":"j6t@kdbg.org","avatar":"https://avatars.githubusercontent.com/u/14810926?v=4"},"body":"Am 16.11.24 um 20:36 schrieb Jean-Noël Avila via GitGitGadget:\n> --1 --base::\n> --2 --ours::\n> --3 --theirs::\n> +`-1`::\n> +`--base`::\n> +\n> +or `-2`::\n> +`--ours`::\n> +\n> +or `-3`::\n> +`--theirs`::\n>  \tCompare the working tree with the \"base\" version (stage #1),\n>  \t\"our branch\" (stage #2) or \"their branch\" (stage #3).  The\n>  \tindex contains these stages only for unmerged entries i.e.\n>  \twhile resolving conflicts.  See linkgit:git-read-tree[1]\n>  \tsection \"3-Way Merge\" for detailed information.\n\nHaving seen this new proposal (which I am not a fan of), I reconsidered\nmy take on how this could be formatted.\n\nFirst, I wonder why the pre-image is not\n\n-1::\n--base::\n-2::\n--ours::\n-3::\n--theirs::\n\nlike we write in other cases where multiple options are described by the\nsame paragraph (e.g.: -p -u --patch; -W --function-context; --textconv\n--no-textconv).\n\nNext, since with such a scheme all options are treated equally, we have\nto ask whether the description in the body text makes sufficiently clear\nthat they not all do the same thing (it does), that there are actually 3\ndistinct groups (it does), and which options mean the same thing. The\nlatter is rather meh, but it is the fault of the text and can be\nremedied easily.\n\nFinally, with all this considered, I think it is not so bad at all that\nall options are lumped together in a single line (or remain on six\nseparate header lines, depending on the processor). So, I would no\nlonger mind seeing this transformed into\n\n`-1`::\n`--base`::\n`-2`::\n`--ours`::\n`-3`::\n`--theirs`::\n\nfor consistency, or\n\n`-1`, `--base`::\n`-2`, `--ours`::\n`-3`, `--theirs`::\n\nfor brevity.\n\n-- Hannes\n\n"},{"id":"507444","messageId":"2365334.irdbgypaU6@cayenne","threadId":"61899","inReplyTo":"7f24a030-bae2-4712-8593-61a9d4089cfb@kdbg.org","subject":"Re: [PATCH v3 1/5] doc: git-diff: apply new documentation guidelines","fromName":"Jean-Noël AVILA","fromEmail":"jn.avila@free.fr","sentAt":"2024-11-17T16:44:10Z","receivedAt":"2024-11-17T16:44:29Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"On Sunday, 17 November 2024 15:04:13 CET Johannes Sixt wrote:\n> Am 16.11.24 um 20:36 schrieb Jean-Noël Avila via GitGitGadget:\n> > --1 --base::\n> > --2 --ours::\n> > --3 --theirs::\n> > +`-1`::\n> > +`--base`::\n> > +\n> > +or `-2`::\n> > +`--ours`::\n> > +\n> > +or `-3`::\n> > +`--theirs`::\n> >  \tCompare the working tree with the \"base\" version (stage #1),\n> >  \t\"our branch\" (stage #2) or \"their branch\" (stage #3).  The\n> >  \tindex contains these stages only for unmerged entries i.e.\n> >  \twhile resolving conflicts.  See linkgit:git-read-tree[1]\n> >  \tsection \"3-Way Merge\" for detailed information.\n> \n> Having seen this new proposal (which I am not a fan of), I reconsidered\n> my take on how this could be formatted.\n> \n> First, I wonder why the pre-image is not\n> \n> -1::\n> --base::\n> -2::\n> --ours::\n> -3::\n> --theirs::\n> \n> like we write in other cases where multiple options are described by the\n> same paragraph (e.g.: -p -u --patch; -W --function-context; --textconv\n> --no-textconv).\n> \n> Next, since with such a scheme all options are treated equally, we have\n> to ask whether the description in the body text makes sufficiently clear\n> that they not all do the same thing (it does), that there are actually 3\n> distinct groups (it does), and which options mean the same thing. The\n> latter is rather meh, but it is the fault of the text and can be\n> remedied easily.\n> \n\nOK, I'm not fond of my solution either, but I strongly dislike mixing synonyms \n(which is the usual meaning of putting several options in the same \ndescription) with incompatible behavioral alternatives. But, for this one, \nlet's consider that the alternatives are just like `--[no-]bla` option \ndescriptions, for the sake of ending this PR.\n\nI would still rephrase the description to make it clear, how the alternatives \nare  working:\n\n`-1`::\n`--base`::\n`-2`::\n`--ours`::\n`-3`::\n`--theirs`::\n\tCompare the working tree with\n+\n--\n * the \"base\" version (stage #1) when using `-1` or `--base`,\n * \"our branch\" (stage #2) when using `-2` or `--ours`, or\n * \"their branch\" (stage #3) when using `-3` or `--theirs`.\n--\n+\nThe index contains these stages only for unmerged entries i.e.\nwhile resolving conflicts.  See linkgit:git-read-tree[1]\nsection \"3-Way Merge\" for detailed information.\n\n> Finally, with all this considered, I think it is not so bad at all that\n> all options are lumped together in a single line (or remain on six\n> separate header lines, depending on the processor). So, I would no\n> longer mind seeing this transformed into\n> \n> `-1`::\n> `--base`::\n> `-2`::\n> `--ours`::\n> `-3`::\n> `--theirs`::\n> \n> for consistency, or\n\nTo be honest, this is the form I would prefer because it can be automatically \nprocessed for translation as \"do not translate\". Any addition involving human \nlanguage to a segment requires translation.\n\n\n\nThanks,\n\nJN\n\n\n"},{"id":"507449","messageId":"xmqq34jpz8ru.fsf@gitster.g","threadId":"61899","inReplyTo":"7f24a030-bae2-4712-8593-61a9d4089cfb@kdbg.org","subject":"Re: [PATCH v3 1/5] doc: git-diff: apply new documentation guidelines","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-11-18T00:27:01Z","receivedAt":"2024-11-18T00:27:05Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Johannes Sixt <j6t@kdbg.org> writes:\n\n> -1::\n> --base::\n> -2::\n> --ours::\n> -3::\n> --theirs::\n> ...\n> Next, since with such a scheme all options are treated equally, we have\n> to ask whether the description in the body text makes sufficiently clear\n> that they not all do the same thing (it does), that there are actually 3\n> distinct groups (it does), and which options mean the same thing. The\n> latter is rather meh, but it is the fault of the text and can be\n> remedied easily.\n\nOK, with that, making the 6 as the heading at the same level becomes\nfeasible and the most simple.\n\n> Finally, with all this considered, I think it is not so bad at all that\n> all options are lumped together in a single line (or remain on six\n> separate header lines, depending on the processor).\n\nYup.  Sounds good.\n"},{"id":"507451","messageId":"xmqqldxhxttb.fsf@gitster.g","threadId":"61899","inReplyTo":"2365334.irdbgypaU6@cayenne","subject":"Re: [PATCH v3 1/5] doc: git-diff: apply new documentation guidelines","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-11-18T00:35:28Z","receivedAt":"2024-11-18T00:35:31Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jean-Noël AVILA <jn.avila@free.fr> writes:\n\n> OK, I'm not fond of my solution either, but I strongly dislike mixing synonyms \n> (which is the usual meaning of putting several options in the same \n> description) with incompatible behavioral alternatives. But, for this one, \n> let's consider that the alternatives are just like `--[no-]bla` option \n> descriptions, for the sake of ending this PR.\n\nMakes sense.  In this case, not like \"--[no-]blah\" whose description\nhas to discuss two options with opposite meaning, we need to\ndescribe three choices.\n\n> I would still rephrase the description to make it clear, how the alternatives \n> are  working:\n\nAbsolutely.\n\n>\n> `-1`::\n> `--base`::\n> `-2`::\n> `--ours`::\n> `-3`::\n> `--theirs`::\n> \tCompare the working tree with\n> +\n> --\n>  * the \"base\" version (stage #1) when using `-1` or `--base`,\n>  * \"our branch\" (stage #2) when using `-2` or `--ours`, or\n>  * \"their branch\" (stage #3) when using `-3` or `--theirs`.\n> --\n> +\n> The index contains these stages only for unmerged entries i.e.\n> while resolving conflicts.  See linkgit:git-read-tree[1]\n> section \"3-Way Merge\" for detailed information.\n\nOK.\n\nThanks.\n"},{"id":"507539","messageId":"pull.1769.v4.git.1731967553.gitgitgadget@gmail.com","threadId":"61899","inReplyTo":"pull.1769.v3.git.1731785768.gitgitgadget@gmail.com","subject":"[PATCH v4 0/5] doc: git diff reformatting","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-11-18T22:05:48Z","receivedAt":"2024-11-18T22:05:57Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"This is the continuation of the editing of the manpages to reflect the new\nformatting rules.\n\nChanges since V3:\n\n * rework the description about -1, --base,...\n\nJean-Noël Avila (5):\n  doc: git-diff: apply new documentation guidelines\n  doc: git-diff: apply format changes to diff-options\n  doc: git-diff: apply format changes to diff-format\n  doc: git-diff: apply format changes to diff-generate-patch\n  doc: git-diff: apply format changes to config part\n\n Documentation/config/diff.txt         | 204 +++++++------\n Documentation/diff-format.txt         |  42 +--\n Documentation/diff-generate-patch.txt |  44 +--\n Documentation/diff-options.txt        | 423 +++++++++++++-------------\n Documentation/git-diff.txt            | 122 ++++----\n 5 files changed, 433 insertions(+), 402 deletions(-)\n\n\nbase-commit: facbe4f633e4ad31e641f64617bc88074c659959\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-1769%2Fjnavila%2Fgit_diff_new-v4\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1769/jnavila/git_diff_new-v4\nPull-Request: https://github.com/gitgitgadget/git/pull/1769\n\nRange-diff vs v3:\n\n 1:  6841bd5825b ! 1:  fd3ee137fe4 doc: git-diff: apply new documentation guidelines\n     @@ Documentation/git-diff.txt: OPTIONS\n      --1 --base::\n      --2 --ours::\n      --3 --theirs::\n     +-\tCompare the working tree with the \"base\" version (stage #1),\n     +-\t\"our branch\" (stage #2) or \"their branch\" (stage #3).  The\n     +-\tindex contains these stages only for unmerged entries i.e.\n     +-\twhile resolving conflicts.  See linkgit:git-read-tree[1]\n     +-\tsection \"3-Way Merge\" for detailed information.\n      +`-1`::\n      +`--base`::\n     -+\n     -+or `-2`::\n     ++`-2`::\n      +`--ours`::\n     -+\n     -+or `-3`::\n     ++`-3`::\n      +`--theirs`::\n     - \tCompare the working tree with the \"base\" version (stage #1),\n     - \t\"our branch\" (stage #2) or \"their branch\" (stage #3).  The\n     - \tindex contains these stages only for unmerged entries i.e.\n     - \twhile resolving conflicts.  See linkgit:git-read-tree[1]\n     - \tsection \"3-Way Merge\" for detailed information.\n     ++\tCompare the working tree with\n     +++\n     ++--\n     ++ * the \"base\" version (stage #1) when using `-1` or `--base`,\n     ++ * \"our branch\" (stage #2) when using `-2` or `--ours`, or\n     ++ * \"their branch\" (stage #3) when using `-3` or `--theirs`.\n     ++--\n     +++\n     ++The index contains these stages only for unmerged entries i.e.\n     ++while resolving conflicts.  See linkgit:git-read-tree[1]\n     ++section \"3-Way Merge\" for detailed information.\n       \n      --0::\n      +`-0`::\n 2:  07df397741b = 2:  a0a3986ea86 doc: git-diff: apply format changes to diff-options\n 3:  698628e076b = 3:  aca3573cd95 doc: git-diff: apply format changes to diff-format\n 4:  1154462f8be = 4:  0e6162d02d1 doc: git-diff: apply format changes to diff-generate-patch\n 5:  4ec2fd9c3c6 = 5:  d350237eddb doc: git-diff: apply format changes to config part\n\n-- \ngitgitgadget\n"},{"id":"507540","messageId":"fd3ee137fe4f22eb864f1f972c216b7a7f05d0f9.1731967553.git.gitgitgadget@gmail.com","threadId":"61899","inReplyTo":"pull.1769.v4.git.1731967553.gitgitgadget@gmail.com","subject":"[PATCH v4 1/5] doc: git-diff: apply new documentation guidelines","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-11-18T22:05:49Z","receivedAt":"2024-11-18T22:05:58Z","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\nThe documentation for git-diff has been updated to follow the new\ndocumentation guidelines. The following changes have been applied to\nthe series of patches:\n\n- switching 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- prevent git-diff from self-referencing itself via gitlink macro when\nthe generated link would point to the same page.\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\n---\n Documentation/git-diff.txt | 122 ++++++++++++++++++++-----------------\n 1 file changed, 66 insertions(+), 56 deletions(-)\n\ndiff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt\nindex c065f023eca..e19f31e8b9d 100644\n--- a/Documentation/git-diff.txt\n+++ b/Documentation/git-diff.txt\n@@ -8,13 +8,13 @@ git-diff - Show changes between commits, commit and working tree, etc\n \n SYNOPSIS\n --------\n-[verse]\n-'git diff' [<options>] [<commit>] [--] [<path>...]\n-'git diff' [<options>] --cached [--merge-base] [<commit>] [--] [<path>...]\n-'git diff' [<options>] [--merge-base] <commit> [<commit>...] <commit> [--] [<path>...]\n-'git diff' [<options>] <commit>...<commit> [--] [<path>...]\n-'git diff' [<options>] <blob> <blob>\n-'git diff' [<options>] --no-index [--] <path> <path>\n+[synopsis]\n+git diff [<options>] [<commit>] [--] [<path>...]\n+git diff [<options>] --cached [--merge-base] [<commit>] [--] [<path>...]\n+git diff [<options>] [--merge-base] <commit> [<commit>...] <commit> [--] [<path>...]\n+git diff [<options>] <commit>...<commit> [--] [<path>...]\n+git diff [<options>] <blob> <blob>\n+git diff [<options>] --no-index [--] <path> <path>\n \n DESCRIPTION\n -----------\n@@ -23,7 +23,7 @@ between the index and a tree, changes between two trees, changes resulting\n from a merge, changes between two blob objects, or changes between two\n files on disk.\n \n-'git diff' [<options>] [--] [<path>...]::\n+`git diff [<options>] [--] [<path>...]`::\n \n \tThis form is to view the changes you made relative to\n \tthe index (staging area for the next commit).  In other\n@@ -31,7 +31,7 @@ files on disk.\n \tfurther add to the index but you still haven't.  You can\n \tstage these changes by using linkgit:git-add[1].\n \n-'git diff' [<options>] --no-index [--] <path> <path>::\n+`git diff [<options>] --no-index [--] <path> <path>`::\n \n \tThis form is to compare the given two paths on the\n \tfilesystem.  You can omit the `--no-index` option when\n@@ -40,82 +40,82 @@ files on disk.\n \tor when running the command outside a working tree\n \tcontrolled by Git. This form implies `--exit-code`.\n \n-'git diff' [<options>] --cached [--merge-base] [<commit>] [--] [<path>...]::\n+`git diff [<options>] --cached [--merge-base] [<commit>] [--] [<path>...]`::\n \n \tThis form is to view the changes you staged for the next\n-\tcommit relative to the named <commit>.  Typically you\n+\tcommit relative to the named _<commit>_.  Typically you\n \twould want comparison with the latest commit, so if you\n-\tdo not give <commit>, it defaults to HEAD.\n-\tIf HEAD does not exist (e.g. unborn branches) and\n-\t<commit> is not given, it shows all staged changes.\n-\t--staged is a synonym of --cached.\n+\tdo not give _<commit>_, it defaults to `HEAD`.\n+\tIf `HEAD` does not exist (e.g. unborn branches) and\n+\t_<commit>_ is not given, it shows all staged changes.\n+\t`--staged` is a synonym of `--cached`.\n +\n-If --merge-base is given, instead of using <commit>, use the merge base\n-of <commit> and HEAD.  `git diff --cached --merge-base A` is equivalent to\n+If `--merge-base` is given, instead of using _<commit>_, use the merge base\n+of _<commit>_ and `HEAD`.  `git diff --cached --merge-base A` is equivalent to\n `git diff --cached $(git merge-base A HEAD)`.\n \n-'git diff' [<options>] [--merge-base] <commit> [--] [<path>...]::\n+`git diff [<options>] [--merge-base] <commit> [--] [<path>...]`::\n \n \tThis form is to view the changes you have in your\n-\tworking tree relative to the named <commit>.  You can\n-\tuse HEAD to compare it with the latest commit, or a\n+\tworking tree relative to the named _<commit>_.  You can\n+\tuse `HEAD` to compare it with the latest commit, or a\n \tbranch name to compare with the tip of a different\n \tbranch.\n +\n-If --merge-base is given, instead of using <commit>, use the merge base\n-of <commit> and HEAD.  `git diff --merge-base A` is equivalent to\n+If `--merge-base` is given, instead of using _<commit>_, use the merge base\n+of _<commit>_ and `HEAD`.  `git diff --merge-base A` is equivalent to\n `git diff $(git merge-base A HEAD)`.\n \n-'git diff' [<options>] [--merge-base] <commit> <commit> [--] [<path>...]::\n+`git diff [<options>] [--merge-base] <commit> <commit> [--] [<path>...]`::\n \n \tThis is to view the changes between two arbitrary\n-\t<commit>.\n+\t_<commit>_.\n +\n-If --merge-base is given, use the merge base of the two commits for the\n+If `--merge-base` is given, use the merge base of the two commits for the\n \"before\" side.  `git diff --merge-base A B` is equivalent to\n `git diff $(git merge-base A B) B`.\n \n-'git diff' [<options>] <commit> <commit>... <commit> [--] [<path>...]::\n+`git diff [<options>] <commit> <commit>...<commit> [--] [<path>...]`::\n \n \tThis form is to view the results of a merge commit.  The first\n-\tlisted <commit> must be the merge itself; the remaining two or\n+\tlisted _<commit>_ must be the merge itself; the remaining two or\n \tmore commits should be its parents.  Convenient ways to produce\n-\tthe desired set of revisions are to use the suffixes `^@` and\n-\t`^!`.  If A is a merge commit, then `git diff A A^@`,\n+\tthe desired set of revisions are to use the suffixes `@` and\n+\t`^!`.  If `A` is a merge commit, then `git diff A A^@`,\n \t`git diff A^!` and `git show A` all give the same combined diff.\n \n-'git diff' [<options>] <commit>..<commit> [--] [<path>...]::\n+`git diff [<options>] <commit>..<commit> [--] [<path>...]`::\n \n \tThis is synonymous to the earlier form (without the `..`) for\n-\tviewing the changes between two arbitrary <commit>.  If <commit> on\n+\tviewing the changes between two arbitrary _<commit>_.  If _<commit>_ on\n \tone side is omitted, it will have the same effect as\n-\tusing HEAD instead.\n+\tusing `HEAD` instead.\n \n-'git diff' [<options>] <commit>\\...<commit> [--] [<path>...]::\n+`git diff [<options>] <commit>...<commit> [--] [<path>...]`::\n \n \tThis form is to view the changes on the branch containing\n-\tand up to the second <commit>, starting at a common ancestor\n-\tof both <commit>.  `git diff A...B` is equivalent to\n+\tand up to the second _<commit>_, starting at a common ancestor\n+\tof both _<commit>_.  `git diff A...B` is equivalent to\n \t`git diff $(git merge-base A B) B`.  You can omit any one\n-\tof <commit>, which has the same effect as using HEAD instead.\n+\tof _<commit>_, which has the same effect as using `HEAD` instead.\n \n Just in case you are doing something exotic, it should be\n-noted that all of the <commit> in the above description, except\n+noted that all of the _<commit>_ in the above description, except\n in the `--merge-base` case and in the last two forms that use `..`\n-notations, can be any <tree>. A tree of interest is the one pointed to\n-by the ref named `AUTO_MERGE`, which is written by the 'ort' merge\n+notations, can be any _<tree>_. A tree of interest is the one pointed to\n+by the ref named `AUTO_MERGE`, which is written by the `ort` merge\n strategy upon hitting merge conflicts (see linkgit:git-merge[1]).\n Comparing the working tree with `AUTO_MERGE` shows changes you've made\n so far to resolve textual conflicts (see the examples below).\n \n-For a more complete list of ways to spell <commit>, see\n+For a more complete list of ways to spell _<commit>_, see\n \"SPECIFYING REVISIONS\" section in linkgit:gitrevisions[7].\n-However, \"diff\" is about comparing two _endpoints_, not ranges,\n-and the range notations (`<commit>..<commit>` and\n-`<commit>...<commit>`) do not mean a range as defined in the\n+However, `diff` is about comparing two _endpoints_, not ranges,\n+and the range notations (`<commit>..<commit>` and `<commit>...<commit>`)\n+do not mean a range as defined in the\n \"SPECIFYING RANGES\" section in linkgit:gitrevisions[7].\n \n-'git diff' [<options>] <blob> <blob>::\n+`git diff [<options>] <blob> <blob>`::\n \n \tThis form is to view the differences between the raw\n \tcontents of two blob objects.\n@@ -125,22 +125,31 @@ OPTIONS\n :git-diff: 1\n include::diff-options.txt[]\n \n--1 --base::\n--2 --ours::\n--3 --theirs::\n-\tCompare the working tree with the \"base\" version (stage #1),\n-\t\"our branch\" (stage #2) or \"their branch\" (stage #3).  The\n-\tindex contains these stages only for unmerged entries i.e.\n-\twhile resolving conflicts.  See linkgit:git-read-tree[1]\n-\tsection \"3-Way Merge\" for detailed information.\n+`-1`::\n+`--base`::\n+`-2`::\n+`--ours`::\n+`-3`::\n+`--theirs`::\n+\tCompare the working tree with\n++\n+--\n+ * the \"base\" version (stage #1) when using `-1` or `--base`,\n+ * \"our branch\" (stage #2) when using `-2` or `--ours`, or\n+ * \"their branch\" (stage #3) when using `-3` or `--theirs`.\n+--\n++\n+The index contains these stages only for unmerged entries i.e.\n+while resolving conflicts.  See linkgit:git-read-tree[1]\n+section \"3-Way Merge\" for detailed information.\n \n--0::\n+`-0`::\n \tOmit diff output for unmerged entries and just show\n \t\"Unmerged\".  Can be used only when comparing the working tree\n \twith the index.\n \n-<path>...::\n-\tThe <paths> parameters, when given, are used to limit\n+`<path>...`::\n+\tThe _<path>_ parameters, when given, are used to limit\n \tthe diff to the named paths (you can give directory\n \tnames and get diff for all files under them).\n \n@@ -225,11 +234,12 @@ CONFIGURATION\n \n include::includes/cmd-config-section-all.txt[]\n \n+:git-diff: 1\n include::config/diff.txt[]\n \n SEE ALSO\n --------\n-diff(1),\n+`diff`(1),\n linkgit:git-difftool[1],\n linkgit:git-log[1],\n linkgit:gitdiffcore[7],\n-- \ngitgitgadget\n\n"},{"id":"507541","messageId":"aca3573cd95f0a9eb27e36914a27614d23eb9a0d.1731967553.git.gitgitgadget@gmail.com","threadId":"61899","inReplyTo":"pull.1769.v4.git.1731967553.gitgitgadget@gmail.com","subject":"[PATCH v4 3/5] doc: git-diff: apply format changes to diff-format","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-11-18T22:05:51Z","receivedAt":"2024-11-18T22:06:00Z","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/diff-format.txt | 42 +++++++++++++++++------------------\n 1 file changed, 21 insertions(+), 21 deletions(-)\n\ndiff --git a/Documentation/diff-format.txt b/Documentation/diff-format.txt\nindex a3ae8747a22..c72fb379867 100644\n--- a/Documentation/diff-format.txt\n+++ b/Documentation/diff-format.txt\n@@ -1,25 +1,25 @@\n Raw output format\n -----------------\n \n-The raw output format from \"git-diff-index\", \"git-diff-tree\",\n-\"git-diff-files\" and \"git diff --raw\" are very similar.\n+The raw output format from `git-diff-index`, `git-diff-tree`,\n+`git-diff-files` and `git diff --raw` are very similar.\n \n These commands all compare two sets of things; what is\n compared differs:\n \n-git-diff-index <tree-ish>::\n-        compares the <tree-ish> and the files on the filesystem.\n+`git-diff-index <tree-ish>`::\n+\tcompares the _<tree-ish>_ and the files on the filesystem.\n \n-git-diff-index --cached <tree-ish>::\n-        compares the <tree-ish> and the index.\n+`git-diff-index --cached <tree-ish>`::\n+\tcompares the _<tree-ish>_ and the index.\n \n-git-diff-tree [-r] <tree-ish-1> <tree-ish-2> [<pattern>...]::\n+`git-diff-tree [-r] <tree-ish-1> <tree-ish-2> [<pattern>...]`::\n         compares the trees named by the two arguments.\n \n-git-diff-files [<pattern>...]::\n+`git-diff-files [<pattern>...]`::\n         compares the index and the files on the filesystem.\n \n-The \"git-diff-tree\" command begins its output by printing the hash of\n+The `git-diff-tree` command begins its output by printing the hash of\n what is being compared. After that, all the commands print one output\n line per changed file.\n \n@@ -54,19 +54,19 @@ That is, from the left to the right:\n \n Possible status letters are:\n \n-- A: addition of a file\n-- C: copy of a file into a new one\n-- D: deletion of a file\n-- M: modification of the contents or mode of a file\n-- R: renaming of a file\n-- T: change in the type of the file (regular file, symbolic link or submodule)\n-- U: file is unmerged (you must complete the merge before it can\n+- `A`: addition of a file\n+- `C`: copy of a file into a new one\n+- `D`: deletion of a file\n+- `M`: modification of the contents or mode of a file\n+- `R`: renaming of a file\n+- `T`: change in the type of the file (regular file, symbolic link or submodule)\n+- `U`: file is unmerged (you must complete the merge before it can\n   be committed)\n-- X: \"unknown\" change type (most probably a bug, please report it)\n+- `X`: \"unknown\" change type (most probably a bug, please report it)\n \n-Status letters C and R are always followed by a score (denoting the\n+Status letters `C` and `R` are always followed by a score (denoting the\n percentage of similarity between the source and target of the move or\n-copy).  Status letter M may be followed by a score (denoting the\n+copy).  Status letter `M` may be followed by a score (denoting the\n percentage of dissimilarity) for file rewrites.\n \n The sha1 for \"dst\" is shown as all 0's if a file on the filesystem\n@@ -86,7 +86,7 @@ verbatim and the line is terminated by a NUL byte.\n diff format for merges\n ----------------------\n \n-\"git-diff-tree\", \"git-diff-files\" and \"git-diff --raw\"\n+`git-diff-tree`, `git-diff-files` and `git-diff --raw`\n can take `-c` or `--cc` option\n to generate diff output also for merge commits.  The output differs\n from the format described above in the following way:\n@@ -128,7 +128,7 @@ other diff formats\n ------------------\n \n The `--summary` option describes newly added, deleted, renamed and\n-copied files.  The `--stat` option adds diffstat(1) graph to the\n+copied files.  The `--stat` option adds `diffstat`(1) graph to the\n output.  These options can be combined with other options, such as\n `-p`, and are meant for human consumption.\n \n-- \ngitgitgadget\n\n"},{"id":"507542","messageId":"0e6162d02d102531dd07673845d02fe2385d61df.1731967553.git.gitgitgadget@gmail.com","threadId":"61899","inReplyTo":"pull.1769.v4.git.1731967553.gitgitgadget@gmail.com","subject":"[PATCH v4 4/5] doc: git-diff: apply format changes to diff-generate-patch","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-11-18T22:05:52Z","receivedAt":"2024-11-18T22:06:00Z","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/diff-generate-patch.txt | 44 ++++++++++++++-------------\n 1 file changed, 23 insertions(+), 21 deletions(-)\n\ndiff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-generate-patch.txt\nindex 4b5aa5c2e04..e5c813c96f3 100644\n--- a/Documentation/diff-generate-patch.txt\n+++ b/Documentation/diff-generate-patch.txt\n@@ -14,7 +14,7 @@ You can customize the creation of patch text via the\n `GIT_EXTERNAL_DIFF` and the `GIT_DIFF_OPTS` environment variables\n (see linkgit:git[1]), and the `diff` attribute (see linkgit:gitattributes[5]).\n \n-What the -p option produces is slightly different from the traditional\n+What the `-p` option produces is slightly different from the traditional\n diff format:\n \n 1.   It is preceded by a \"git diff\" header that looks like this:\n@@ -30,20 +30,21 @@ name of the source file of the rename/copy and the name of\n the file that the rename/copy produces, respectively.\n \n 2.   It is followed by one or more extended header lines:\n-\n-       old mode <mode>\n-       new mode <mode>\n-       deleted file mode <mode>\n-       new file mode <mode>\n-       copy from <path>\n-       copy to <path>\n-       rename from <path>\n-       rename to <path>\n-       similarity index <number>\n-       dissimilarity index <number>\n-       index <hash>..<hash> <mode>\n +\n-File modes are printed as 6-digit octal numbers including the file type\n+[synopsis]\n+old mode <mode>\n+new mode <mode>\n+deleted file mode <mode>\n+new file mode <mode>\n+copy from <path>\n+copy to <path>\n+rename from <path>\n+rename to <path>\n+similarity index <number>\n+dissimilarity index <number>\n+index <hash>..<hash> <mode>\n++\n+File modes _<mode>_ are printed as 6-digit octal numbers including the file type\n and file permission bits.\n +\n Path names in extended headers do not include the `a/` and `b/` prefixes.\n@@ -56,7 +57,7 @@ files, while 100% dissimilarity means that no line from the old\n file made it into the new one.\n +\n The index line includes the blob object names before and after the change.\n-The <mode> is included if the file mode does not change; otherwise,\n+The _<mode>_ is included if the file mode does not change; otherwise,\n separate lines indicate the old and the new mode.\n \n 3.  Pathnames with \"unusual\" characters are quoted as explained for\n@@ -134,17 +135,18 @@ or like this (when the `--cc` option is used):\n \n 2.   It is followed by one or more extended header lines\n      (this example shows a merge with two parents):\n-\n-       index <hash>,<hash>..<hash>\n-       mode <mode>,<mode>..<mode>\n-       new file mode <mode>\n-       deleted file mode <mode>,<mode>\n++\n+[synopsis]\n+index <hash>,<hash>..<hash>\n+mode <mode>,<mode>`..`<mode>\n+new file mode <mode>\n+deleted file mode <mode>,<mode>\n +\n The `mode <mode>,<mode>..<mode>` line appears only if at least one of\n the <mode> is different from the rest. Extended headers with\n information about detected content movement (renames and\n copying detection) are designed to work with the diff of two\n-<tree-ish> and are not used by combined diff format.\n+_<tree-ish>_ and are not used by combined diff format.\n \n 3.   It is followed by a two-line from-file/to-file header:\n \n-- \ngitgitgadget\n\n"},{"id":"507543","messageId":"a0a3986ea860c0380e24ebae392512ef1081162a.1731967553.git.gitgitgadget@gmail.com","threadId":"61899","inReplyTo":"pull.1769.v4.git.1731967553.gitgitgadget@gmail.com","subject":"[PATCH v4 2/5] doc: git-diff: apply format changes to diff-options","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-11-18T22:05:50Z","receivedAt":"2024-11-18T22:06:00Z","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\nThe format change is only applied to the sections of the file that are\nfiltered in git-diff.\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\n---\n Documentation/diff-options.txt | 423 +++++++++++++++++----------------\n 1 file changed, 212 insertions(+), 211 deletions(-)\n\ndiff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt\nindex cd0b81adbb6..640eb6e7db5 100644\n--- a/Documentation/diff-options.txt\n+++ b/Documentation/diff-options.txt\n@@ -19,16 +19,16 @@ ifdef::git-format-patch[]\n endif::git-format-patch[]\n \n ifndef::git-format-patch[]\n--p::\n--u::\n---patch::\n+`-p`::\n+`-u`::\n+`--patch`::\n \tGenerate patch (see <<generate_patch_text_with_p>>).\n ifdef::git-diff[]\n \tThis is the default.\n endif::git-diff[]\n \n--s::\n---no-patch::\n+`-s`::\n+`--no-patch`::\n \tSuppress all output from the diff machinery.  Useful for\n \tcommands like `git show` that show the patch by default to\n \tsquelch their output, or to cancel the effect of options like\n@@ -39,28 +39,28 @@ endif::git-format-patch[]\n ifdef::git-log[]\n -m::\n \tShow diffs for merge commits in the default format. This is\n-\tsimilar to '--diff-merges=on', except `-m` will\n+\tsimilar to `--diff-merges=on`, except `-m` will\n \tproduce no output unless `-p` is given as well.\n \n -c::\n \tProduce combined diff output for merge commits.\n-\tShortcut for '--diff-merges=combined -p'.\n+\tShortcut for `--diff-merges=combined -p`.\n \n --cc::\n \tProduce dense combined diff output for merge commits.\n-\tShortcut for '--diff-merges=dense-combined -p'.\n+\tShortcut for `--diff-merges=dense-combined -p`.\n \n --dd::\n \tProduce diff with respect to first parent for both merge and\n \tregular commits.\n-\tShortcut for '--diff-merges=first-parent -p'.\n+\tShortcut for `--diff-merges=first-parent -p`.\n \n --remerge-diff::\n \tProduce remerge-diff output for merge commits.\n-\tShortcut for '--diff-merges=remerge -p'.\n+\tShortcut for `--diff-merges=remerge -p`.\n \n --no-diff-merges::\n-\tSynonym for '--diff-merges=off'.\n+\tSynonym for `--diff-merges=off`.\n \n --diff-merges=<format>::\n \tSpecify diff format to be used for merge commits. Default is\n@@ -73,33 +73,33 @@ The following formats are supported:\n off, none::\n \tDisable output of diffs for merge commits. Useful to override\n \timplied value.\n-+\n+\n on, m::\n \tMake diff output for merge commits to be shown in the default\n \tformat. The default format can be changed using\n \t`log.diffMerges` configuration variable, whose default value\n \tis `separate`.\n-+\n+\n first-parent, 1::\n \tShow full diff with respect to first parent. This is the same\n \tformat as `--patch` produces for non-merge commits.\n-+\n+\n separate::\n \tShow full diff with respect to each of parents.\n \tSeparate log entry and diff is generated for each parent.\n-+\n+\n combined, c::\n \tShow differences from each of the parents to the merge\n \tresult simultaneously instead of showing pairwise diff between\n \ta parent and the result one at a time. Furthermore, it lists\n \tonly files which were modified from all parents.\n-+\n+\n dense-combined, cc::\n \tFurther compress output produced by `--diff-merges=combined`\n \tby omitting uninteresting hunks whose contents in the parents\n \thave only two variants and the merge result picks one of them\n \twithout modification.\n-+\n+\n remerge, r::\n \tRemerge two-parent merge commits to create a temporary tree\n \tobject--potentially containing files with conflict markers\n@@ -112,33 +112,33 @@ documented).\n --\n \n --combined-all-paths::\n-\tThis flag causes combined diffs (used for merge commits) to\n+\tCause combined diffs (used for merge commits) to\n \tlist the name of the file from all parents.  It thus only has\n \teffect when `--diff-merges=[dense-]combined` is in use, and\n \tis likely only useful if filename changes are detected (i.e.\n \twhen either rename or copy detection have been requested).\n endif::git-log[]\n \n--U<n>::\n---unified=<n>::\n-\tGenerate diffs with <n> lines of context instead of\n+`-U<n>`::\n+`--unified=<n>`::\n+\tGenerate diffs with _<n>_ lines of context instead of\n \tthe usual three.\n ifndef::git-format-patch[]\n \tImplies `--patch`.\n endif::git-format-patch[]\n \n---output=<file>::\n+`--output=<file>`::\n \tOutput to a specific file instead of stdout.\n \n---output-indicator-new=<char>::\n---output-indicator-old=<char>::\n---output-indicator-context=<char>::\n+`--output-indicator-new=<char>`::\n+`--output-indicator-old=<char>`::\n+`--output-indicator-context=<char>`::\n \tSpecify the character used to indicate new, old or context\n-\tlines in the generated patch. Normally they are '+', '-' and\n+\tlines in the generated patch. Normally they are `+`, `-` and\n \t' ' respectively.\n \n ifndef::git-format-patch[]\n---raw::\n+`--raw`::\n ifndef::git-log[]\n \tGenerate the diff in raw format.\n ifdef::git-diff-core[]\n@@ -155,54 +155,55 @@ endif::git-log[]\n endif::git-format-patch[]\n \n ifndef::git-format-patch[]\n---patch-with-raw::\n+`--patch-with-raw`::\n \tSynonym for `-p --raw`.\n endif::git-format-patch[]\n \n ifdef::git-log[]\n--t::\n+`-t`::\n \tShow the tree objects in the diff output.\n endif::git-log[]\n \n---indent-heuristic::\n+`--indent-heuristic`::\n \tEnable the heuristic that shifts diff hunk boundaries to make patches\n \teasier to read. This is the default.\n \n---no-indent-heuristic::\n+`--no-indent-heuristic`::\n \tDisable the indent heuristic.\n \n---minimal::\n+`--minimal`::\n \tSpend extra time to make sure the smallest possible\n \tdiff is produced.\n \n---patience::\n+`--patience`::\n \tGenerate a diff using the \"patience diff\" algorithm.\n \n---histogram::\n+`--histogram`::\n \tGenerate a diff using the \"histogram diff\" algorithm.\n \n---anchored=<text>::\n+`--anchored=<text>`::\n \tGenerate a diff using the \"anchored diff\" algorithm.\n +\n This option may be specified more than once.\n +\n If a line exists in both the source and destination, exists only once,\n-and starts with this text, this algorithm attempts to prevent it from\n+and starts with _<text>_, this algorithm attempts to prevent it from\n appearing as a deletion or addition in the output. It uses the \"patience\n diff\" algorithm internally.\n \n---diff-algorithm={patience|minimal|histogram|myers}::\n+`--diff-algorithm=(patience|minimal|histogram|myers)`::\n \tChoose a diff algorithm. The variants are as follows:\n +\n --\n-`default`, `myers`;;\n+   `default`;;\n+   `myers`;;\n \tThe basic greedy diff algorithm. Currently, this is the default.\n-`minimal`;;\n+   `minimal`;;\n \tSpend extra time to make sure the smallest possible diff is\n \tproduced.\n-`patience`;;\n+   `patience`;;\n \tUse \"patience diff\" algorithm when generating patches.\n-`histogram`;;\n+   `histogram`;;\n \tThis algorithm extends the patience algorithm to \"support\n \tlow-occurrence common elements\".\n --\n@@ -211,47 +212,47 @@ For instance, if you configured the `diff.algorithm` variable to a\n non-default value and want to use the default one, then you\n have to use `--diff-algorithm=default` option.\n \n---stat[=<width>[,<name-width>[,<count>]]]::\n+`--stat[=<width>[,<name-width>[,<count>]]]`::\n \tGenerate a diffstat. By default, as much space as necessary\n \twill be used for the filename part, and the rest for the graph\n \tpart. Maximum width defaults to terminal width, or 80 columns\n \tif not connected to a terminal, and can be overridden by\n-\t`<width>`. The width of the filename part can be limited by\n-\tgiving another width `<name-width>` after a comma or by setting\n-\t`diff.statNameWidth=<width>`. The width of the graph part can be\n-\tlimited by using `--stat-graph-width=<width>` or by setting\n-\t`diff.statGraphWidth=<width>`. Using `--stat` or\n+\t_<width>_. The width of the filename part can be limited by\n+\tgiving another width _<name-width>_ after a comma or by setting\n+\t`diff.statNameWidth=<name-width>`. The width of the graph part can be\n+\tlimited by using `--stat-graph-width=<graph-width>` or by setting\n+\t`diff.statGraphWidth=<graph-width>`. Using `--stat` or\n \t`--stat-graph-width` affects all commands generating a stat graph,\n \twhile setting `diff.statNameWidth` or `diff.statGraphWidth`\n \tdoes not affect `git format-patch`.\n-\tBy giving a third parameter `<count>`, you can limit the output to\n-\tthe first `<count>` lines, followed by `...` if there are more.\n+\tBy giving a third parameter _<count>_, you can limit the output to\n+\tthe first _<count>_ lines, followed by `...` if there are more.\n +\n These parameters can also be set individually with `--stat-width=<width>`,\n `--stat-name-width=<name-width>` and `--stat-count=<count>`.\n \n---compact-summary::\n+`--compact-summary`::\n \tOutput a condensed summary of extended header information such\n-\tas file creations or deletions (\"new\" or \"gone\", optionally \"+l\"\n-\tif it's a symlink) and mode changes (\"+x\" or \"-x\" for adding\n+\tas file creations or deletions (\"new\" or \"gone\", optionally `+l`\n+\tif it's a symlink) and mode changes (`+x` or `-x` for adding\n \tor removing executable bit respectively) in diffstat. The\n \tinformation is put between the filename part and the graph\n \tpart. Implies `--stat`.\n \n---numstat::\n+`--numstat`::\n \tSimilar to `--stat`, but shows number of added and\n \tdeleted lines in decimal notation and pathname without\n \tabbreviation, to make it more machine friendly.  For\n \tbinary files, outputs two `-` instead of saying\n \t`0 0`.\n \n---shortstat::\n+`--shortstat`::\n \tOutput only the last line of the `--stat` format containing total\n \tnumber of modified files, as well as number of added and deleted\n \tlines.\n \n--X[<param1,param2,...>]::\n---dirstat[=<param1,param2,...>]::\n+`-X [<param>,...]`::\n+`--dirstat[=<param>,...]`::\n \tOutput the distribution of relative amount of changes for each\n \tsub-directory. The behavior of `--dirstat` can be customized by\n \tpassing it a comma separated list of parameters.\n@@ -284,7 +285,7 @@ These parameters can also be set individually with `--stat-width=<width>`,\n \tNote that when using `cumulative`, the sum of the percentages\n \treported may exceed 100%. The default (non-cumulative) behavior can\n \tbe specified with the `noncumulative` parameter.\n-<limit>;;\n+_<limit>_;;\n \tAn integer parameter specifies a cut-off percent (3% by default).\n \tDirectories contributing less than this percentage of the changes\n \tare not shown in the output.\n@@ -295,29 +296,29 @@ directories with less than 10% of the total amount of changed files,\n and accumulating child directory counts in the parent directories:\n `--dirstat=files,10,cumulative`.\n \n---cumulative::\n-\tSynonym for --dirstat=cumulative\n+`--cumulative`::\n+\tSynonym for `--dirstat=cumulative`.\n \n---dirstat-by-file[=<param1,param2>...]::\n-\tSynonym for --dirstat=files,<param1>,<param2>...\n+`--dirstat-by-file[=<param>,...]`::\n+\tSynonym for `--dirstat=files,<param>,...`.\n \n---summary::\n+`--summary`::\n \tOutput a condensed summary of extended header information\n \tsuch as creations, renames and mode changes.\n \n ifndef::git-format-patch[]\n---patch-with-stat::\n+`--patch-with-stat`::\n \tSynonym for `-p --stat`.\n endif::git-format-patch[]\n \n ifndef::git-format-patch[]\n \n--z::\n+`-z`::\n ifdef::git-log[]\n-\tSeparate the commits with NULs instead of newlines.\n+\tSeparate the commits with __NUL__s instead of newlines.\n +\n Also, when `--raw` or `--numstat` has been given, do not munge\n-pathnames and use NULs as output field terminators.\n+pathnames and use __NUL__s as output field terminators.\n endif::git-log[]\n ifndef::git-log[]\n \tWhen `--raw`, `--numstat`, `--name-only` or `--name-status` has been\n@@ -328,89 +329,89 @@ Without this option, pathnames with \"unusual\" characters are quoted as\n explained for the configuration variable `core.quotePath` (see\n linkgit:git-config[1]).\n \n---name-only::\n+`--name-only`::\n \tShow only the name of each changed file in the post-image tree.\n \tThe file names are often encoded in UTF-8.\n \tFor more information see the discussion about encoding in the linkgit:git-log[1]\n \tmanual page.\n \n---name-status::\n+`--name-status`::\n \tShow only the name(s) and status of each changed file. See the description\n \tof the `--diff-filter` option on what the status letters mean.\n \tJust like `--name-only` the file names are often encoded in UTF-8.\n \n---submodule[=<format>]::\n+`--submodule[=<format>]`::\n \tSpecify how differences in submodules are shown.  When specifying\n-\t`--submodule=short` the 'short' format is used.  This format just\n+\t`--submodule=short` the `short` format is used.  This format just\n \tshows the names of the commits at the beginning and end of the range.\n-\tWhen `--submodule` or `--submodule=log` is specified, the 'log'\n+\tWhen `--submodule` or `--submodule=log` is specified, the `log`\n \tformat is used.  This format lists the commits in the range like\n \tlinkgit:git-submodule[1] `summary` does.  When `--submodule=diff`\n-\tis specified, the 'diff' format is used.  This format shows an\n+\tis specified, the `diff` format is used.  This format shows an\n \tinline diff of the changes in the submodule contents between the\n-\tcommit range.  Defaults to `diff.submodule` or the 'short' format\n+\tcommit range.  Defaults to `diff.submodule` or the `short` format\n \tif the config option is unset.\n \n---color[=<when>]::\n+`--color[=<when>]`::\n \tShow colored diff.\n-\t`--color` (i.e. without '=<when>') is the same as `--color=always`.\n-\t'<when>' can be one of `always`, `never`, or `auto`.\n+\t`--color` (i.e. without `=<when>`) is the same as `--color=always`.\n+\t_<when>_ can be one of `always`, `never`, or `auto`.\n ifdef::git-diff[]\n \tIt can be changed by the `color.ui` and `color.diff`\n \tconfiguration settings.\n endif::git-diff[]\n \n---no-color::\n+`--no-color`::\n \tTurn off colored diff.\n ifdef::git-diff[]\n \tThis can be used to override configuration settings.\n endif::git-diff[]\n \tIt is the same as `--color=never`.\n \n---color-moved[=<mode>]::\n+`--color-moved[=<mode>]`::\n \tMoved lines of code are colored differently.\n ifdef::git-diff[]\n \tIt can be changed by the `diff.colorMoved` configuration setting.\n endif::git-diff[]\n-\tThe <mode> defaults to 'no' if the option is not given\n-\tand to 'zebra' if the option with no mode is given.\n+\tThe _<mode>_ defaults to `no` if the option is not given\n+\tand to `zebra` if the option with no mode is given.\n \tThe mode must be one of:\n +\n --\n-no::\n+`no`::\n \tMoved lines are not highlighted.\n-default::\n+`default`::\n \tIs a synonym for `zebra`. This may change to a more sensible mode\n \tin the future.\n-plain::\n+`plain`::\n \tAny line that is added in one location and was removed\n-\tin another location will be colored with 'color.diff.newMoved'.\n-\tSimilarly 'color.diff.oldMoved' will be used for removed lines\n+\tin another location will be colored with `color.diff.newMoved`.\n+\tSimilarly `color.diff.oldMoved` will be used for removed lines\n \tthat are added somewhere else in the diff. This mode picks up any\n \tmoved line, but it is not very useful in a review to determine\n \tif a block of code was moved without permutation.\n-blocks::\n+`blocks`::\n \tBlocks of moved text of at least 20 alphanumeric characters\n \tare detected greedily. The detected blocks are\n-\tpainted using either the 'color.diff.{old,new}Moved' color.\n+\tpainted using either the `color.diff.(old|new)Moved` color.\n \tAdjacent blocks cannot be told apart.\n-zebra::\n-\tBlocks of moved text are detected as in 'blocks' mode. The blocks\n-\tare painted using either the 'color.diff.{old,new}Moved' color or\n-\t'color.diff.{old,new}MovedAlternative'. The change between\n+`zebra`::\n+\tBlocks of moved text are detected as in `blocks` mode. The blocks\n+\tare painted using either the `color.diff.(old|new)Moved` color or\n+\t`color.diff.(old|new)MovedAlternative`. The change between\n \tthe two colors indicates that a new block was detected.\n-dimmed-zebra::\n-\tSimilar to 'zebra', but additional dimming of uninteresting parts\n+`dimmed-zebra`::\n+\tSimilar to `zebra`, but additional dimming of uninteresting parts\n \tof moved code is performed. The bordering lines of two adjacent\n \tblocks are considered interesting, the rest is uninteresting.\n \t`dimmed_zebra` is a deprecated synonym.\n --\n \n---no-color-moved::\n+`--no-color-moved`::\n \tTurn off move detection. This can be used to override configuration\n \tsettings. It is the same as `--color-moved=no`.\n \n---color-moved-ws=<modes>::\n+`--color-moved-ws=<mode>,...`::\n \tThis configures how whitespace is ignored when performing the\n \tmove detection for `--color-moved`.\n ifdef::git-diff[]\n@@ -419,63 +420,62 @@ endif::git-diff[]\n \tThese modes can be given as a comma separated list:\n +\n --\n-no::\n+`no`::\n \tDo not ignore whitespace when performing move detection.\n-ignore-space-at-eol::\n+`ignore-space-at-eol`::\n \tIgnore changes in whitespace at EOL.\n-ignore-space-change::\n+`ignore-space-change`::\n \tIgnore changes in amount of whitespace.  This ignores whitespace\n \tat line end, and considers all other sequences of one or\n \tmore whitespace characters to be equivalent.\n-ignore-all-space::\n+`ignore-all-space`::\n \tIgnore whitespace when comparing lines. This ignores differences\n \teven if one line has whitespace where the other line has none.\n-allow-indentation-change::\n+`allow-indentation-change`::\n \tInitially ignore any whitespace in the move detection, then\n \tgroup the moved code blocks only into a block if the change in\n \twhitespace is the same per line. This is incompatible with the\n \tother modes.\n --\n \n---no-color-moved-ws::\n+`--no-color-moved-ws`::\n \tDo not ignore whitespace when performing move detection. This can be\n \tused to override configuration settings. It is the same as\n \t`--color-moved-ws=no`.\n \n---word-diff[=<mode>]::\n-\tShow a word diff, using the <mode> to delimit changed words.\n+`--word-diff[=<mode>]`::\n \tBy default, words are delimited by whitespace; see\n-\t`--word-diff-regex` below.  The <mode> defaults to 'plain', and\n+\t`--word-diff-regex` below.  The _<mode>_ defaults to `plain`, and\n \tmust be one of:\n +\n --\n-color::\n+`color`::\n \tHighlight changed words using only colors.  Implies `--color`.\n-plain::\n-\tShow words as `[-removed-]` and `{+added+}`.  Makes no\n+`plain`::\n+\tShow words as ++[-removed-]++ and ++{+added+}++.  Makes no\n \tattempts to escape the delimiters if they appear in the input,\n \tso the output may be ambiguous.\n-porcelain::\n+`porcelain`::\n \tUse a special line-based format intended for script\n \tconsumption.  Added/removed/unchanged runs are printed in the\n \tusual unified diff format, starting with a `+`/`-`/` `\n \tcharacter at the beginning of the line and extending to the\n \tend of the line.  Newlines in the input are represented by a\n \ttilde `~` on a line of its own.\n-none::\n+`none`::\n \tDisable word diff again.\n --\n +\n Note that despite the name of the first mode, color is used to\n highlight the changed parts in all modes if enabled.\n \n---word-diff-regex=<regex>::\n-\tUse <regex> to decide what a word is, instead of considering\n+`--word-diff-regex=<regex>`::\n+\tUse _<regex>_ to decide what a word is, instead of considering\n \truns of non-whitespace to be a word.  Also implies\n \t`--word-diff` unless it was already enabled.\n +\n Every non-overlapping match of the\n-<regex> is considered a word.  Anything between these matches is\n+_<regex>_ is considered a word.  Anything between these matches is\n considered whitespace and ignored(!) for the purposes of finding\n differences.  You may want to append `|[^[:space:]]` to your regular\n expression to make sure that it matches all non-whitespace characters.\n@@ -490,20 +490,20 @@ linkgit:gitattributes[5] or linkgit:git-config[1].  Giving it explicitly\n overrides any diff driver or configuration setting.  Diff drivers\n override configuration settings.\n \n---color-words[=<regex>]::\n+`--color-words[=<regex>]`::\n \tEquivalent to `--word-diff=color` plus (if a regex was\n \tspecified) `--word-diff-regex=<regex>`.\n endif::git-format-patch[]\n \n---no-renames::\n+`--no-renames`::\n \tTurn off rename detection, even when the configuration\n \tfile gives the default to do so.\n \n---[no-]rename-empty::\n+`--[no-]rename-empty`::\n \tWhether to use empty blobs as rename source.\n \n ifndef::git-format-patch[]\n---check::\n+`--check`::\n \tWarn if changes introduce conflict markers or whitespace errors.\n \tWhat are considered whitespace errors is controlled by `core.whitespace`\n \tconfiguration.  By default, trailing whitespaces (including\n@@ -511,9 +511,9 @@ ifndef::git-format-patch[]\n \tthat is immediately followed by a tab character inside the\n \tinitial indent of the line are considered whitespace errors.\n \tExits with non-zero status if problems are found. Not compatible\n-\twith --exit-code.\n+\twith `--exit-code`.\n \n---ws-error-highlight=<kind>::\n+`--ws-error-highlight=<kind>`::\n \tHighlight whitespace errors in the `context`, `old` or `new`\n \tlines of the diff.  Multiple values are separated by comma,\n \t`none` resets previous values, `default` reset the list to\n@@ -525,30 +525,30 @@ ifndef::git-format-patch[]\n \n endif::git-format-patch[]\n \n---full-index::\n+`--full-index`::\n \tInstead of the first handful of characters, show the full\n \tpre- and post-image blob object names on the \"index\"\n \tline when generating patch format output.\n \n---binary::\n+`--binary`::\n \tIn addition to `--full-index`, output a binary diff that\n \tcan be applied with `git-apply`.\n ifndef::git-format-patch[]\n \tImplies `--patch`.\n endif::git-format-patch[]\n \n---abbrev[=<n>]::\n+`--abbrev[=<n>]`::\n \tInstead of showing the full 40-byte hexadecimal object\n \tname in diff-raw format output and diff-tree header\n-\tlines, show the shortest prefix that is at least '<n>'\n+\tlines, show the shortest prefix that is at least _<n>_\n \thexdigits long that uniquely refers the object.\n \tIn diff-patch output format, `--full-index` takes higher\n \tprecedence, i.e. if `--full-index` is specified, full blob\n \tnames will be shown regardless of `--abbrev`.\n \tNon default number of digits can be specified with `--abbrev=<n>`.\n \n--B[<n>][/<m>]::\n---break-rewrites[=[<n>][/<m>]]::\n+`-B[<n>][/<m>]`::\n+`--break-rewrites[=[<n>][/<m>]]`::\n \tBreak complete rewrite changes into pairs of delete and\n \tcreate. This serves two purposes:\n +\n@@ -556,22 +556,22 @@ It affects the way a change that amounts to a total rewrite of a file\n not as a series of deletion and insertion mixed together with a very\n few lines that happen to match textually as the context, but as a\n single deletion of everything old followed by a single insertion of\n-everything new, and the number `m` controls this aspect of the -B\n+everything new, and the number _<m>_ controls this aspect of the `-B`\n option (defaults to 60%). `-B/70%` specifies that less than 30% of the\n original should remain in the result for Git to consider it a total\n rewrite (i.e. otherwise the resulting patch will be a series of\n deletion and insertion mixed together with context lines).\n +\n-When used with -M, a totally-rewritten file is also considered as the\n-source of a rename (usually -M only considers a file that disappeared\n-as the source of a rename), and the number `n` controls this aspect of\n-the -B option (defaults to 50%). `-B20%` specifies that a change with\n+When used with `-M`, a totally-rewritten file is also considered as the\n+source of a rename (usually `-M` only considers a file that disappeared\n+as the source of a rename), and the number _<n>_ controls this aspect of\n+the `-B` option (defaults to 50%). `-B20%` specifies that a change with\n addition and deletion compared to 20% or more of the file's size are\n eligible for being picked up as a possible source of a rename to\n another file.\n \n--M[<n>]::\n---find-renames[=<n>]::\n+`-M[<n>]`::\n+`--find-renames[=<n>]`::\n ifndef::git-log[]\n \tDetect renames.\n endif::git-log[]\n@@ -580,7 +580,7 @@ ifdef::git-log[]\n \tFor following files across renames while traversing history, see\n \t`--follow`.\n endif::git-log[]\n-\tIf `n` is specified, it is a threshold on the similarity\n+\tIf _<n>_ is specified, it is a threshold on the similarity\n \tindex (i.e. amount of addition/deletions compared to the\n \tfile's size). For example, `-M90%` means Git should consider a\n \tdelete/add pair to be a rename if more than 90% of the file\n@@ -590,12 +590,12 @@ endif::git-log[]\n \tthe same as `-M5%`.  To limit detection to exact renames, use\n \t`-M100%`.  The default similarity index is 50%.\n \n--C[<n>]::\n---find-copies[=<n>]::\n+`-C[<n>]`::\n+`--find-copies[=<n>]`::\n \tDetect copies as well as renames.  See also `--find-copies-harder`.\n-\tIf `n` is specified, it has the same meaning as for `-M<n>`.\n+\tIf _<n>_ is specified, it has the same meaning as for `-M<n>`.\n \n---find-copies-harder::\n+`--find-copies-harder`::\n \tFor performance reasons, by default, `-C` option finds copies only\n \tif the original file of the copy was modified in the same\n \tchangeset.  This flag makes the command\n@@ -604,8 +604,8 @@ endif::git-log[]\n \tprojects, so use it with caution.  Giving more than one\n \t`-C` option has the same effect.\n \n--D::\n---irreversible-delete::\n+`-D`::\n+`--irreversible-delete`::\n \tOmit the preimage for deletes, i.e. print only the header but not\n \tthe diff between the preimage and `/dev/null`. The resulting patch\n \tis not meant to be applied with `patch` or `git apply`; this is\n@@ -617,7 +617,7 @@ endif::git-log[]\n When used together with `-B`, omit also the preimage in the deletion part\n of a delete/create pair.\n \n--l<num>::\n+`-l<num>`::\n \tThe `-M` and `-C` options involve some preliminary steps that\n \tcan detect subsets of renames/copies cheaply, followed by an\n \texhaustive fallback portion that compares all remaining\n@@ -627,11 +627,11 @@ of a delete/create pair.\n \tdestinations, this exhaustive check is O(N^2).  This option\n \tprevents the exhaustive portion of rename/copy detection from\n \trunning if the number of source/destination files involved\n-\texceeds the specified number.  Defaults to diff.renameLimit.\n+\texceeds the specified number.  Defaults to `diff.renameLimit`.\n \tNote that a value of 0 is treated as unlimited.\n \n ifndef::git-format-patch[]\n---diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]::\n+`--diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]`::\n \tSelect only files that are Added (`A`), Copied (`C`),\n \tDeleted (`D`), Modified (`M`), Renamed (`R`), have their\n \ttype (i.e. regular file, symlink, submodule, ...) changed (`T`),\n@@ -649,9 +649,9 @@ Also, these upper-case letters can be downcased to exclude.  E.g.\n Note that not all diffs can feature all types. For instance, copied and\n renamed entries cannot appear if detection for those types is disabled.\n \n--S<string>::\n+`-S<string>`::\n \tLook for differences that change the number of occurrences of\n-\tthe specified string (i.e. addition/deletion) in a file.\n+\tthe specified _<string>_ (i.e. addition/deletion) in a file.\n \tIntended for the scripter's use.\n +\n It is useful when you're looking for an exact block of code (like a\n@@ -662,11 +662,11 @@ very first version of the block.\n +\n Binary files are searched as well.\n \n--G<regex>::\n+`-G<regex>`::\n \tLook for differences whose patch text contains added/removed\n-\tlines that match <regex>.\n+\tlines that match _<regex>_.\n +\n-To illustrate the difference between `-S<regex> --pickaxe-regex` and\n+To illustrate the difference between `-S<regex>` `--pickaxe-regex` and\n `-G<regex>`, consider a commit with the following diff in the same\n file:\n +\n@@ -686,7 +686,7 @@ filter will be ignored.\n See the 'pickaxe' entry in linkgit:gitdiffcore[7] for more\n information.\n \n---find-object=<object-id>::\n+`--find-object=<object-id>`::\n \tLook for differences that change the number of occurrences of\n \tthe specified object. Similar to `-S`, just the argument is different\n \tin that it doesn't search for a specific string but for a specific\n@@ -695,25 +695,25 @@ information.\n The object can be a blob or a submodule commit. It implies the `-t` option in\n `git-log` to also find trees.\n \n---pickaxe-all::\n+`--pickaxe-all`::\n \tWhen `-S` or `-G` finds a change, show all the changes in that\n \tchangeset, not just the files that contain the change\n-\tin <string>.\n+\tin _<string>_.\n \n---pickaxe-regex::\n-\tTreat the <string> given to `-S` as an extended POSIX regular\n+`--pickaxe-regex`::\n+\tTreat the _<string>_ given to `-S` as an extended POSIX regular\n \texpression to match.\n \n endif::git-format-patch[]\n \n--O<orderfile>::\n+`-O<orderfile>`::\n \tControl the order in which files appear in the output.\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 +\n The output order is determined by the order of glob patterns in\n-<orderfile>.\n+_<orderfile>_.\n All files with pathnames that match the first pattern are output\n first, all files with pathnames that match the second pattern (but not\n the first) are output next, and so on.\n@@ -724,7 +724,7 @@ If multiple pathnames have the same rank (they match the same pattern\n but no earlier patterns), their output order relative to each other is\n the normal order.\n +\n-<orderfile> is parsed as follows:\n+_<orderfile>_ is parsed as follows:\n +\n --\n  - Blank lines are ignored, so they can be used as separators for\n@@ -738,106 +738,107 @@ the normal order.\n --\n +\n Patterns have the same syntax and semantics as patterns used for\n-fnmatch(3) without the FNM_PATHNAME flag, except a pathname also\n+`fnmatch`(3) without the `FNM_PATHNAME` flag, except a pathname also\n matches a pattern if removing any number of the final pathname\n components matches the pattern.  For example, the pattern \"`foo*bar`\"\n matches \"`fooasdfbar`\" and \"`foo/bar/baz/asdf`\" but not \"`foobarx`\".\n \n---skip-to=<file>::\n---rotate-to=<file>::\n-\tDiscard the files before the named <file> from the output\n+`--skip-to=<file>`::\n+`--rotate-to=<file>`::\n+\tDiscard the files before the named _<file>_ from the output\n \t(i.e. 'skip to'), or move them to the end of the output\n \t(i.e. 'rotate to').  These options were invented primarily for the use\n \tof the `git difftool` command, and may not be very useful\n \totherwise.\n \n ifndef::git-format-patch[]\n--R::\n+`-R`::\n \tSwap two inputs; that is, show differences from index or\n \ton-disk file to tree contents.\n endif::git-format-patch[]\n \n---relative[=<path>]::\n---no-relative::\n+`--relative[=<path>]`::\n+`--no-relative`::\n \tWhen run from a subdirectory of the project, it can be\n \ttold to exclude changes outside the directory and show\n \tpathnames relative to it with this option.  When you are\n \tnot in a subdirectory (e.g. in a bare repository), you\n \tcan name which subdirectory to make the output relative\n-\tto by giving a <path> as an argument.\n+\tto by giving a _<path>_ as an argument.\n \t`--no-relative` can be used to countermand both `diff.relative` config\n \toption and previous `--relative`.\n \n--a::\n---text::\n+`-a`::\n+`--text`::\n \tTreat all files as text.\n \n---ignore-cr-at-eol::\n+`--ignore-cr-at-eol`::\n \tIgnore carriage-return at the end of line when doing a comparison.\n \n---ignore-space-at-eol::\n+`--ignore-space-at-eol`::\n \tIgnore changes in whitespace at EOL.\n \n--b::\n---ignore-space-change::\n+`-b`::\n+`--ignore-space-change`::\n \tIgnore changes in amount of whitespace.  This ignores whitespace\n \tat line end, and considers all other sequences of one or\n \tmore whitespace characters to be equivalent.\n \n--w::\n---ignore-all-space::\n+`-w`::\n+`--ignore-all-space`::\n \tIgnore whitespace when comparing lines.  This ignores\n \tdifferences even if one line has whitespace where the other\n \tline has none.\n \n---ignore-blank-lines::\n+`--ignore-blank-lines`::\n \tIgnore changes whose lines are all blank.\n \n--I<regex>::\n---ignore-matching-lines=<regex>::\n-\tIgnore changes whose all lines match <regex>.  This option may\n+\n+`-I<regex>`::\n+`--ignore-matching-lines=<regex>`::\n+\tIgnore changes whose all lines match _<regex>_.  This option may\n \tbe specified more than once.\n \n---inter-hunk-context=<lines>::\n-\tShow the context between diff hunks, up to the specified number\n+`--inter-hunk-context=<number>`::\n+\tShow the context between diff hunks, up to the specified _<number>_\n \tof lines, thereby fusing hunks that are close to each other.\n \tDefaults to `diff.interHunkContext` or 0 if the config option\n \tis unset.\n \n--W::\n---function-context::\n+`-W`::\n+`--function-context`::\n \tShow whole function as context lines for each change.\n \tThe function names are determined in the same way as\n-\t`git diff` works out patch hunk headers (see 'Defining a\n-\tcustom hunk-header' in linkgit:gitattributes[5]).\n+\t`git diff` works out patch hunk headers (see \"Defining a\n+\tcustom hunk-header\" in linkgit:gitattributes[5]).\n \n ifndef::git-format-patch[]\n ifndef::git-log[]\n---exit-code::\n-\tMake the program exit with codes similar to diff(1).\n+`--exit-code`::\n+\tMake the program exit with codes similar to `diff`(1).\n \tThat is, it exits with 1 if there were differences and\n \t0 means no differences.\n \n---quiet::\n+`--quiet`::\n \tDisable all output of the program. Implies `--exit-code`.\n \tDisables execution of external diff helpers whose exit code\n \tis not trusted, i.e. their respective configuration option\n-\t`diff.trustExitCode` or `diff.<driver>.trustExitCode` or\n+\t`diff.trustExitCode` or ++diff.++__<driver>__++.trustExitCode++ or\n \tenvironment variable `GIT_EXTERNAL_DIFF_TRUST_EXIT_CODE` is\n \tfalse.\n endif::git-log[]\n endif::git-format-patch[]\n \n---ext-diff::\n+`--ext-diff`::\n \tAllow an external diff helper to be executed. If you set an\n \texternal diff driver with linkgit:gitattributes[5], you need\n \tto use this option with linkgit:git-log[1] and friends.\n \n---no-ext-diff::\n+`--no-ext-diff`::\n \tDisallow external diff drivers.\n \n---textconv::\n---no-textconv::\n+`--textconv`::\n+`--no-textconv`::\n \tAllow (or disallow) external text conversion filters to be run\n \twhen comparing binary files. See linkgit:gitattributes[5] for\n \tdetails. Because textconv filters are typically a one-way\n@@ -847,42 +848,42 @@ endif::git-format-patch[]\n \tlinkgit:git-log[1], but not for linkgit:git-format-patch[1] or\n \tdiff plumbing commands.\n \n---ignore-submodules[=<when>]::\n-\tIgnore changes to submodules in the diff generation. <when> can be\n-\teither \"none\", \"untracked\", \"dirty\" or \"all\", which is the default.\n-\tUsing \"none\" will consider the submodule modified when it either contains\n-\tuntracked or modified files or its HEAD differs from the commit recorded\n+\n+`--ignore-submodules[=(none|untracked|dirty|all)]`::\n+\tIgnore changes to submodules in the diff generation. `all` is the default.\n+\tUsing `none` will consider the submodule modified when it either contains\n+\tuntracked or modified files or its `HEAD` differs from the commit recorded\n \tin the superproject and can be used to override any settings of the\n-\t'ignore' option in linkgit:git-config[1] or linkgit:gitmodules[5]. When\n-\t\"untracked\" is used submodules are not considered dirty when they only\n+\t`ignore` option in linkgit:git-config[1] or linkgit:gitmodules[5]. When\n+\t`untracked` is used submodules are not considered dirty when they only\n \tcontain untracked content (but they are still scanned for modified\n-\tcontent). Using \"dirty\" ignores all changes to the work tree of submodules,\n+\tcontent). Using `dirty` ignores all changes to the work tree of submodules,\n \tonly changes to the commits stored in the superproject are shown (this was\n-\tthe behavior until 1.7.0). Using \"all\" hides all changes to submodules.\n+\tthe behavior until 1.7.0). Using `all` hides all changes to submodules.\n \n---src-prefix=<prefix>::\n-\tShow the given source prefix instead of \"a/\".\n+`--src-prefix=<prefix>`::\n+\tShow the given source _<prefix>_ instead of \"a/\".\n \n---dst-prefix=<prefix>::\n-\tShow the given destination prefix instead of \"b/\".\n+`--dst-prefix=<prefix>`::\n+\tShow the given destination _<prefix>_ instead of \"b/\".\n \n---no-prefix::\n+`--no-prefix`::\n \tDo not show any source or destination prefix.\n \n---default-prefix::\n+`--default-prefix`::\n \tUse the default source and destination prefixes (\"a/\" and \"b/\").\n \tThis overrides configuration variables such as `diff.noprefix`,\n \t`diff.srcPrefix`, `diff.dstPrefix`, and `diff.mnemonicPrefix`\n-\t(see `git-config`(1)).\n+\t(see linkgit:git-config[1]).\n \n---line-prefix=<prefix>::\n-\tPrepend an additional prefix to every line of output.\n+`--line-prefix=<prefix>`::\n+\tPrepend an additional _<prefix>_ to every line of output.\n \n---ita-invisible-in-index::\n-\tBy default entries added by \"git add -N\" appear as an existing\n-\tempty file in \"git diff\" and a new file in \"git diff --cached\".\n-\tThis option makes the entry appear as a new file in \"git diff\"\n-\tand non-existent in \"git diff --cached\". This option could be\n+`--ita-invisible-in-index`::\n+\tBy default entries added by `git add -N` appear as an existing\n+\tempty file in `git diff` and a new file in `git diff --cached`.\n+\tThis option makes the entry appear as a new file in `git diff`\n+\tand non-existent in `git diff --cached`. This option could be\n \treverted with `--ita-visible-in-index`. Both options are\n \texperimental and could be removed in future.\n \n-- \ngitgitgadget\n\n"},{"id":"507544","messageId":"d350237eddbb19ee40395c2f59e0048b14ba223f.1731967553.git.gitgitgadget@gmail.com","threadId":"61899","inReplyTo":"pull.1769.v4.git.1731967553.gitgitgadget@gmail.com","subject":"[PATCH v4 5/5] doc: git-diff: apply format changes to config part","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-11-18T22:05:53Z","receivedAt":"2024-11-18T22:06:01Z","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\nBy the way, we also change the sentences where git-diff would refer to\nitself, so that no link is created in the HTML output.\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\n---\n Documentation/config/diff.txt | 204 ++++++++++++++++++----------------\n 1 file changed, 111 insertions(+), 93 deletions(-)\n\ndiff --git a/Documentation/config/diff.txt b/Documentation/config/diff.txt\nindex 190bda17e51..45f3fe855c5 100644\n--- a/Documentation/config/diff.txt\n+++ b/Documentation/config/diff.txt\n@@ -1,18 +1,25 @@\n-diff.autoRefreshIndex::\n-\tWhen using 'git diff' to compare with work tree\n+`diff.autoRefreshIndex`::\n+\tWhen using `git diff` to compare with work tree\n \tfiles, do not consider stat-only changes as changed.\n \tInstead, silently run `git update-index --refresh` to\n \tupdate the cached stat information for paths whose\n \tcontents in the work tree match the contents in the\n-\tindex.  This option defaults to true.  Note that this\n-\taffects only 'git diff' Porcelain, and not lower level\n-\t'diff' commands such as 'git diff-files'.\n+\tindex.  This option defaults to `true`.  Note that this\n+\taffects only `git diff` Porcelain, and not lower level\n+\t`diff` commands such as `git diff-files`.\n \n-diff.dirstat::\n+`diff.dirstat`::\n+ifdef::git-diff[]\n+\tA comma separated list of `--dirstat` parameters specifying the\n+\tdefault behavior of the `--dirstat` option to `git diff` and friends.\n+endif::git-diff[]\n+ifndef::git-diff[]\n \tA comma separated list of `--dirstat` parameters specifying the\n \tdefault behavior of the `--dirstat` option to linkgit:git-diff[1]\n-\tand friends. The defaults can be overridden on the command line\n-\t(using `--dirstat=<param1,param2,...>`). The fallback defaults\n+\tand friends.\n+endif::git-diff[]\n+\tThe defaults can be overridden on the command line\n+\t(using `--dirstat=<param>,...`). The fallback defaults\n \t(when not changed by `diff.dirstat`) are `changes,noncumulative,3`.\n \tThe following parameters are available:\n +\n@@ -41,7 +48,7 @@ diff.dirstat::\n \tNote that when using `cumulative`, the sum of the percentages\n \treported may exceed 100%. The default (non-cumulative) behavior can\n \tbe specified with the `noncumulative` parameter.\n-<limit>;;\n+_<limit>_;;\n \tAn integer parameter specifies a cut-off percent (3% by default).\n \tDirectories contributing less than this percentage of the changes\n \tare not shown in the output.\n@@ -52,58 +59,58 @@ directories with less than 10% of the total amount of changed files,\n and accumulating child directory counts in the parent directories:\n `files,10,cumulative`.\n \n-diff.statNameWidth::\n-\tLimit the width of the filename part in --stat output. If set, applies\n-\tto all commands generating --stat output except format-patch.\n+`diff.statNameWidth`::\n+\tLimit the width of the filename part in `--stat` output. If set, applies\n+\tto all commands generating `--stat` output except `format-patch`.\n \n-diff.statGraphWidth::\n-\tLimit the width of the graph part in --stat output. If set, applies\n-\tto all commands generating --stat output except format-patch.\n+`diff.statGraphWidth`::\n+\tLimit the width of the graph part in `--stat` output. If set, applies\n+\tto all commands generating `--stat` output except `format-patch`.\n \n-diff.context::\n-\tGenerate diffs with <n> lines of context instead of the default\n-\tof 3. This value is overridden by the -U option.\n+`diff.context`::\n+\tGenerate diffs with _<n>_ lines of context instead of the default\n+\tof 3. This value is overridden by the `-U` option.\n \n-diff.interHunkContext::\n+`diff.interHunkContext`::\n \tShow the context between diff hunks, up to the specified number\n \tof lines, thereby fusing the hunks that are close to each other.\n \tThis value serves as the default for the `--inter-hunk-context`\n \tcommand line option.\n \n-diff.external::\n+`diff.external`::\n \tIf this config variable is set, diff generation is not\n \tperformed using the internal diff machinery, but using the\n-\tgiven command.  Can be overridden with the `GIT_EXTERNAL_DIFF'\n+\tgiven command.  Can be overridden with the `GIT_EXTERNAL_DIFF`\n \tenvironment variable.  The command is called with parameters\n \tas described under \"git Diffs\" in linkgit:git[1].  Note: if\n \tyou want to use an external diff program only on a subset of\n \tyour files, you might want to use linkgit:gitattributes[5] instead.\n \n-diff.trustExitCode::\n-\tIf this boolean value is set to true then the\n+`diff.trustExitCode`::\n+\tIf this boolean value is set to `true` then the\n \t`diff.external` command is expected to return exit code\n \t0 if it considers the input files to be equal or 1 if it\n-\tconsiders them to be different, like `diff(1)`.\n-\tIf it is set to false, which is the default, then the command\n-\tis expected to return exit code 0 regardless of equality.\n+\tconsiders them to be different, like `diff`(1).\n+\tIf it is set to `false`, which is the default, then the command\n+\tis expected to return exit code `0` regardless of equality.\n \tAny other exit code causes Git to report a fatal error.\n \n-diff.ignoreSubmodules::\n-\tSets the default value of --ignore-submodules. Note that this\n-\taffects only 'git diff' Porcelain, and not lower level 'diff'\n-\tcommands such as 'git diff-files'. 'git checkout'\n-\tand 'git switch' also honor\n+`diff.ignoreSubmodules`::\n+\tSets the default value of `--ignore-submodules`. Note that this\n+\taffects only `git diff` Porcelain, and not lower level `diff`\n+\tcommands such as `git diff-files`. `git checkout`\n+\tand `git switch` also honor\n \tthis setting when reporting uncommitted changes. Setting it to\n-\t'all' disables the submodule summary normally shown by 'git commit'\n-\tand 'git status' when `status.submoduleSummary` is set unless it is\n-\toverridden by using the --ignore-submodules command-line option.\n-\tThe 'git submodule' commands are not affected by this setting.\n+\t`all` disables the submodule summary normally shown by `git commit`\n+\tand `git status` when `status.submoduleSummary` is set unless it is\n+\toverridden by using the `--ignore-submodules` command-line option.\n+\tThe `git submodule` commands are not affected by this setting.\n \tBy default this is set to untracked so that any untracked\n \tsubmodules are ignored.\n \n-diff.mnemonicPrefix::\n-\tIf set, 'git diff' uses a prefix pair that is different from the\n-\tstandard \"a/\" and \"b/\" depending on what is being compared.  When\n+`diff.mnemonicPrefix`::\n+\tIf set, `git diff` uses a prefix pair that is different from the\n+\tstandard `a/` and `b/` depending on what is being compared.  When\n \tthis configuration is in effect, reverse diff output also swaps\n \tthe order of the prefixes:\n `git diff`;;\n@@ -112,111 +119,117 @@ diff.mnemonicPrefix::\n \t compares a (c)ommit and the (w)ork tree;\n `git diff --cached`;;\n \tcompares a (c)ommit and the (i)ndex;\n-`git diff HEAD:file1 file2`;;\n+`git diff HEAD:<file1> <file2>`;;\n \tcompares an (o)bject and a (w)ork tree entity;\n-`git diff --no-index a b`;;\n-\tcompares two non-git things (1) and (2).\n+`git diff --no-index <a> <b>`;;\n+\tcompares two non-git things _<a>_ and _<b>_.\n \n-diff.noPrefix::\n-\tIf set, 'git diff' does not show any source or destination prefix.\n+`diff.noPrefix`::\n+\tIf set, `git diff` does not show any source or destination prefix.\n \n-diff.srcPrefix::\n-\tIf set, 'git diff' uses this source prefix. Defaults to \"a/\".\n+`diff.srcPrefix`::\n+\tIf set, `git diff` uses this source prefix. Defaults to `a/`.\n \n-diff.dstPrefix::\n-\tIf set, 'git diff' uses this destination prefix. Defaults to \"b/\".\n+`diff.dstPrefix`::\n+\tIf set, `git diff` uses this destination prefix. Defaults to `b/`.\n \n-diff.relative::\n-\tIf set to 'true', 'git diff' does not show changes outside of the directory\n+`diff.relative`::\n+\tIf set to `true`, `git diff` does not show changes outside of the directory\n \tand show pathnames relative to the current directory.\n \n-diff.orderFile::\n+`diff.orderFile`::\n \tFile indicating how to order files within a diff.\n-\tSee the '-O' option to linkgit:git-diff[1] for details.\n+ifdef::git-diff[]\n+\tSee the `-O` option for details.\n+endif::git-diff[]\n+ifndef::git-diff[]\n+\tSee the `-O` option to linkgit:git-diff[1] for details.\n+endif::git-diff[]\n \tIf `diff.orderFile` is a relative pathname, it is treated as\n \trelative to the top of the working tree.\n \n-diff.renameLimit::\n+`diff.renameLimit`::\n \tThe number of files to consider in the exhaustive portion of\n-\tcopy/rename detection; equivalent to the 'git diff' option\n+\tcopy/rename detection; equivalent to the `git diff` option\n \t`-l`.  If not set, the default value is currently 1000.  This\n \tsetting has no effect if rename detection is turned off.\n \n-diff.renames::\n-\tWhether and how Git detects renames.  If set to \"false\",\n-\trename detection is disabled. If set to \"true\", basic rename\n-\tdetection is enabled.  If set to \"copies\" or \"copy\", Git will\n-\tdetect copies, as well.  Defaults to true.  Note that this\n-\taffects only 'git diff' Porcelain like linkgit:git-diff[1] and\n+`diff.renames`::\n+\tWhether and how Git detects renames.  If set to `false`,\n+\trename detection is disabled. If set to `true`, basic rename\n+\tdetection is enabled.  If set to `copies` or `copy`, Git will\n+\tdetect copies, as well.  Defaults to `true`.  Note that this\n+\taffects only `git diff` Porcelain like linkgit:git-diff[1] and\n \tlinkgit:git-log[1], and not lower level commands such as\n \tlinkgit:git-diff-files[1].\n \n-diff.suppressBlankEmpty::\n+`diff.suppressBlankEmpty`::\n \tA boolean to inhibit the standard behavior of printing a space\n-\tbefore each empty output line. Defaults to false.\n+\tbefore each empty output line. Defaults to `false`.\n \n-diff.submodule::\n+`diff.submodule`::\n \tSpecify the format in which differences in submodules are\n-\tshown.  The \"short\" format just shows the names of the commits\n-\tat the beginning and end of the range. The \"log\" format lists\n+\tshown.  The `short` format just shows the names of the commits\n+\tat the beginning and end of the range. The `log` format lists\n \tthe commits in the range like linkgit:git-submodule[1] `summary`\n-\tdoes. The \"diff\" format shows an inline diff of the changed\n-\tcontents of the submodule. Defaults to \"short\".\n+\tdoes. The `diff` format shows an inline diff of the changed\n+\tcontents of the submodule. Defaults to `short`.\n \n-diff.wordRegex::\n+`diff.wordRegex`::\n \tA POSIX Extended Regular Expression used to determine what is a \"word\"\n \twhen performing word-by-word difference calculations.  Character\n \tsequences that match the regular expression are \"words\", all other\n \tcharacters are *ignorable* whitespace.\n \n-diff.<driver>.command::\n+`diff.<driver>.command`::\n \tThe custom diff driver command.  See linkgit:gitattributes[5]\n \tfor details.\n \n-diff.<driver>.trustExitCode::\n-\tIf this boolean value is set to true then the\n+`diff.<driver>.trustExitCode`::\n+\tIf this boolean value is set to `true` then the\n \t`diff.<driver>.command` command is expected to return exit code\n \t0 if it considers the input files to be equal or 1 if it\n-\tconsiders them to be different, like `diff(1)`.\n-\tIf it is set to false, which is the default, then the command\n+\tconsiders them to be different, like `diff`(1).\n+\tIf it is set to `false`, which is the default, then the command\n \tis expected to return exit code 0 regardless of equality.\n \tAny other exit code causes Git to report a fatal error.\n \n-diff.<driver>.xfuncname::\n+`diff.<driver>.xfuncname`::\n \tThe regular expression that the diff driver should use to\n \trecognize the hunk header.  A built-in pattern may also be used.\n \tSee linkgit:gitattributes[5] for details.\n \n-diff.<driver>.binary::\n-\tSet this option to true to make the diff driver treat files as\n+`diff.<driver>.binary`::\n+\tSet this option to `true` to make the diff driver treat files as\n \tbinary.  See linkgit:gitattributes[5] for details.\n \n-diff.<driver>.textconv::\n+`diff.<driver>.textconv`::\n \tThe command that the diff driver should call to generate the\n \ttext-converted version of a file.  The result of the\n \tconversion is used to generate a human-readable diff.  See\n \tlinkgit:gitattributes[5] for details.\n \n-diff.<driver>.wordRegex::\n+`diff.<driver>.wordRegex`::\n \tThe regular expression that the diff driver should use to\n \tsplit words in a line.  See linkgit:gitattributes[5] for\n \tdetails.\n \n-diff.<driver>.cachetextconv::\n-\tSet this option to true to make the diff driver cache the text\n+`diff.<driver>.cachetextconv`::\n+\tSet this option to `true` to make the diff driver cache the text\n \tconversion outputs.  See linkgit:gitattributes[5] for details.\n \n include::../mergetools-diff.txt[]\n \n-diff.indentHeuristic::\n+`diff.indentHeuristic`::\n \tSet this option to `false` to disable the default heuristics\n \tthat shift diff hunk boundaries to make patches easier to read.\n \n-diff.algorithm::\n+`diff.algorithm`::\n \tChoose a diff algorithm.  The variants are as follows:\n +\n --\n-`default`, `myers`;;\n+`default`;;\n+`myers`;;\n \tThe basic greedy diff algorithm. Currently, this is the default.\n `minimal`;;\n \tSpend extra time to make sure the smallest possible diff is\n@@ -229,7 +242,7 @@ diff.algorithm::\n --\n +\n \n-diff.wsErrorHighlight::\n+`diff.wsErrorHighlight`::\n \tHighlight whitespace errors in the `context`, `old` or `new`\n \tlines of the diff.  Multiple values are separated by comma,\n \t`none` resets previous values, `default` reset the list to\n@@ -238,14 +251,19 @@ diff.wsErrorHighlight::\n \tThe command line option `--ws-error-highlight=<kind>`\n \toverrides this setting.\n \n-diff.colorMoved::\n-\tIf set to either a valid `<mode>` or a true value, moved lines\n-\tin a diff are colored differently, for details of valid modes\n-\tsee '--color-moved' in linkgit:git-diff[1]. If simply set to\n-\ttrue the default color mode will be used. When set to false,\n-\tmoved lines are not colored.\n-\n-diff.colorMovedWS::\n+`diff.colorMoved`::\n+\tIf set to either a valid _<mode>_ or a `true` value, moved lines\n+\tin a diff are colored differently.\n+ifdef::git-diff[]\n+\tFor details of valid modes see `--color-moved`.\n+endif::git-diff[]\n+ifndef::git-diff[]\n+\tFor details of valid modes see `--color-moved` in linkgit:git-diff[1].\n+endif::git-diff[]\n+\tIf simply set to `true` the default color mode will be used. When\n+\tset to `false`, moved lines are not colored.\n+\n+`diff.colorMovedWS`::\n \tWhen moved lines are colored using e.g. the `diff.colorMoved` setting,\n-\tthis option controls the `<mode>` how spaces are treated.\n-\tFor details of valid modes see '--color-moved-ws' in linkgit:git-diff[1].\n+\tthis option controls the mode how spaces are treated.\n+\tFor details of valid modes see `--color-moved-ws` in linkgit:git-diff[1].\n-- \ngitgitgadget\n"},{"id":"508133","messageId":"xmqqv7wa1up7.fsf@gitster.g","threadId":"61899","inReplyTo":"pull.1769.v4.git.1731967553.gitgitgadget@gmail.com","subject":"Re: [PATCH v4 0/5] doc: git diff reformatting","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-11-26T04:32:20Z","receivedAt":"2024-11-26T04:32:23Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Jean-Noël Avila via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n\n> This is the continuation of the editing of the manpages to reflect the new\n> formatting rules.\n>\n> Changes since V3:\n>\n>  * rework the description about -1, --base,...\n>\n\nThis latest round did not see any feedback, but I re-read the\nchanges again, and did not find anything suspicious.  So unless\nthere are things I missed that others point out quickly, let's\nmerge this down to 'next'.\n\nThanks.\n"},{"id":"508149","messageId":"96157f25-655d-4d3e-ba56-d76a8f12ced7@kdbg.org","threadId":"61899","inReplyTo":"xmqqv7wa1up7.fsf@gitster.g","subject":"Re: [PATCH v4 0/5] doc: git diff reformatting","fromName":"Johannes Sixt","fromEmail":"j6t@kdbg.org","sentAt":"2024-11-26T06:55:49Z","receivedAt":"2024-11-26T06:56:03Z","isPatch":true,"sender":{"key":"j6t@kdbg.org","avatar":"https://avatars.githubusercontent.com/u/14810926?v=4"},"body":"Am 26.11.24 um 05:32 schrieb Junio C Hamano:\n> \"Jean-Noël Avila via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n> \n>> This is the continuation of the editing of the manpages to reflect the new\n>> formatting rules.\n>>\n>> Changes since V3:\n>>\n>>  * rework the description about -1, --base,...\n>>\n> \n> This latest round did not see any feedback, but I re-read the\n> changes again, and did not find anything suspicious.  So unless\n> there are things I missed that others point out quickly, let's\n> merge this down to 'next'.\n\nYes, this round looks good to me, too.\n\nMy comment about dashed vs. non-dashed commands in 3/5 hasn't been\naddressed, but this is OK since such a change is outside the topic of\nthis series.\n\n-- Hannes\n\n"},{"id":"508151","messageId":"xmqqo722zcra.fsf@gitster.g","threadId":"61899","inReplyTo":"96157f25-655d-4d3e-ba56-d76a8f12ced7@kdbg.org","subject":"Re: [PATCH v4 0/5] doc: git diff reformatting","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-11-26T07:15:53Z","receivedAt":"2024-11-26T07:15:56Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Johannes Sixt <j6t@kdbg.org> writes:\n\n> Yes, this round looks good to me, too.\n>\n> My comment about dashed vs. non-dashed commands in 3/5 hasn't been\n> addressed, but this is OK since such a change is outside the topic of\n> this series.\n\nThanks, let's do that.\n"},{"id":"515356","messageId":"Z+piTsfJdx4BG2oI@szeder.dev","threadId":"61899","inReplyTo":"fd3ee137fe4f22eb864f1f972c216b7a7f05d0f9.1731967553.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v4 1/5] doc: git-diff: apply new documentation guidelines","fromName":"SZEDER Gábor","fromEmail":"szeder.dev@gmail.com","sentAt":"2025-03-31T09:37:18Z","receivedAt":"2025-03-31T09:37:22Z","isPatch":true,"sender":{"key":"szeder.dev@gmail.com","avatar":"https://avatars.githubusercontent.com/u/116324?v=4"},"body":"On Mon, Nov 18, 2024 at 10:05:49PM +0000, Jean-Noël Avila via GitGitGadget wrote:\n> From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n> \n> The documentation for git-diff has been updated to follow the new\n> documentation guidelines. The following changes have been applied to\n> the series of patches:\n> \n> - switching 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\n> descriptions`. The new rendering engine will apply synopsis rules to\n> these spans.\n> - prevent git-diff from self-referencing itself via gitlink macro when\n> the generated link would point to the same page.\n> \n> Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>\n> ---\n>  Documentation/git-diff.txt | 122 ++++++++++++++++++++-----------------\n>  1 file changed, 66 insertions(+), 56 deletions(-)\n> \n> diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt\n> index c065f023eca..e19f31e8b9d 100644\n> --- a/Documentation/git-diff.txt\n> +++ b/Documentation/git-diff.txt\n> @@ -8,13 +8,13 @@ git-diff - Show changes between commits, commit and working tree, etc\n>  \n>  SYNOPSIS\n>  --------\n> -[verse]\n> -'git diff' [<options>] [<commit>] [--] [<path>...]\n> -'git diff' [<options>] --cached [--merge-base] [<commit>] [--] [<path>...]\n> -'git diff' [<options>] [--merge-base] <commit> [<commit>...] <commit> [--] [<path>...]\n> -'git diff' [<options>] <commit>...<commit> [--] [<path>...]\n> -'git diff' [<options>] <blob> <blob>\n> -'git diff' [<options>] --no-index [--] <path> <path>\n> +[synopsis]\n> +git diff [<options>] [<commit>] [--] [<path>...]\n> +git diff [<options>] --cached [--merge-base] [<commit>] [--] [<path>...]\n> +git diff [<options>] [--merge-base] <commit> [<commit>...] <commit> [--] [<path>...]\n> +git diff [<options>] <commit>...<commit> [--] [<path>...]\n> +git diff [<options>] <blob> <blob>\n> +git diff [<options>] --no-index [--] <path> <path>\n\nSince this patch the synopsis in the man page looks like this when the\ndocumentation is built with Asciidoctor:\n\n    SYNOPSIS\n           git diff [<options>] [<commit>] [--] [<path>...]\n           git diff [<options>] --cached [--merge-base] [<commit>] [--] [<path>...]\n           git diff [<options>] [--merge-base] <commit> [<commit>...] <commit> [--] [<path>...]\n           git diff [<options>] <commit>`...__<commit>__ [{empty}--{empty}]{empty} [__<path>__...]{empty}\n           {empty}`git diff [<options>] <blob> <blob>\n           git diff [<options>] --no-index [--] <path> <path>\n\nI'm not sure what those '{empty}' strings are supposed to be, but they\nshouldn't be there.\n\nA similar issue is caused by 0b080a70ab (doc: git-diff: apply format\nchanges to diff-generate-patch, 2024-11-18) later in this series,\naffecting all man pages that include 'diff-generate-patch.adoc':\n\n        2. It is followed by one or more extended header lines (this example shows a merge with two parents):\n\n               index <hash>,<hash>`..__<hash>__\n               {empty}`mode <mode>,<mode>``..``<mode>\n               new file mode <mode>\n               deleted file mode <mode>,<mode>\n\nI use the distro packaged version of Asciidoctor:\n\n  $ asciidoctor --version\n  Asciidoctor 2.0.16 [https://asciidoctor.org]\n  Runtime Environment (ruby 3.0.2p107 (2021-07-07 revision 0db68f0233) [x86_64-linux-gnu]) (lc:UTF-8 fs:UTF-8 in:UTF-8 ex:UTF-8)\n\nWhen the documentation is built with AsciiDoc (10.1.2) these all look\nfine.\n\n"},{"id":"515362","messageId":"20250331125608.92419-1-jn.avila@free.fr","threadId":"61899","inReplyTo":"Z+piTsfJdx4BG2oI@szeder.dev","subject":"[PATCH] doc: fix asciidoctor synopsis processing of triple-dots","fromName":"Jean-Noël Avila","fromEmail":"jn.avila@free.fr","sentAt":"2025-03-31T12:55:51Z","receivedAt":"2025-03-31T12:56:26Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"The processing of triple dot notation is tricky because it can be\nmis-interpreted as an ellipsis. The special processing of the ellipsis\nis now complete and takes into account the case of\n`git-mv <source>... <dest>`\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\n---\n Documentation/asciidoctor-extensions.rb.in | 4 +++-\n 1 file changed, 3 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/asciidoctor-extensions.rb.in b/Documentation/asciidoctor-extensions.rb.in\nindex 2494f17a51..f2be66c4ad 100644\n--- a/Documentation/asciidoctor-extensions.rb.in\n+++ b/Documentation/asciidoctor-extensions.rb.in\n@@ -49,7 +49,7 @@ module Git\n \n       def process parent, reader, attrs\n         outlines = reader.lines.map do |l|\n-          l.gsub(/(\\.\\.\\.?)([^\\]$.])/, '`\\1`\\2')\n+          l.gsub(/(\\.\\.\\.?)([^\\]$\\. ])/, '{empty}`\\1`{empty}\\2')\n            .gsub(%r{([\\[\\] |()>]|^)([-a-zA-Z0-9:+=~@,/_^\\$]+)}, '\\1{empty}`\\2`{empty}')\n            .gsub(/(<[-a-zA-Z0-9.]+>)/, '__\\\\1__')\n            .gsub(']', ']{empty}')\n@@ -72,6 +72,7 @@ module Git\n           %(<inlineequation><alt><![CDATA[#{equation = node.text}]]></alt><mathphrase><![CDATA[#{equation}]]></mathphrase></inlineequation>)\n         elsif type == :monospaced\n           node.text.gsub(/(\\.\\.\\.?)([^\\]$.])/, '<literal>\\1</literal>\\2')\n+                        .gsub(/^\\.\\.\\.?$/, '<literal>\\0</literal>\\2')\n               .gsub(%r{([\\[\\s|()>.]|^|\\]|&gt;)(\\.?([-a-zA-Z0-9:+=~@,/_^\\$]+\\.{0,2})+)}, '\\1<literal>\\2</literal>')\n               .gsub(/(&lt;[-a-zA-Z0-9.]+&gt;)/, '<emphasis>\\1</emphasis>')\n         else\n@@ -100,6 +101,7 @@ module Git\n       def convert_inline_quoted node\n         if node.type == :monospaced\n           node.text.gsub(/(\\.\\.\\.?)([^\\]$.])/, '<code>\\1</code>\\2')\n+            .gsub(/^\\.\\.\\.?$/, '<code>\\0</code>')\n               .gsub(%r{([\\[\\s|()>.]|^|\\]|&gt;)(\\.?([-a-zA-Z0-9:+=~@,/_^\\$]+\\.{0,2})+)}, '\\1<code>\\2</code>')\n               .gsub(/(&lt;[-a-zA-Z0-9.]+&gt;)/, '<em>\\1</em>')\n \n-- \n2.49.0\n\n"},{"id":"515391","messageId":"Z+rUsCW0zEb8kAK8@szeder.dev","threadId":"61899","inReplyTo":"20250331125608.92419-1-jn.avila@free.fr","subject":"Re: [PATCH] doc: fix asciidoctor synopsis processing of triple-dots","fromName":"SZEDER Gábor","fromEmail":"szeder.dev@gmail.com","sentAt":"2025-03-31T17:45:20Z","receivedAt":"2025-03-31T17:45:23Z","isPatch":true,"sender":{"key":"szeder.dev@gmail.com","avatar":"https://avatars.githubusercontent.com/u/116324?v=4"},"body":"On Mon, Mar 31, 2025 at 02:55:51PM +0200, Jean-Noël Avila wrote:\n> The processing of triple dot notation is tricky because it can be\n> mis-interpreted as an ellipsis. The special processing of the ellipsis\n> is now complete and takes into account the case of\n> `git-mv <source>... <dest>`\n> \n> Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>\n> ---\n>  Documentation/asciidoctor-extensions.rb.in | 4 +++-\n>  1 file changed, 3 insertions(+), 1 deletion(-)\n> \n> diff --git a/Documentation/asciidoctor-extensions.rb.in b/Documentation/asciidoctor-extensions.rb.in\n> index 2494f17a51..f2be66c4ad 100644\n> --- a/Documentation/asciidoctor-extensions.rb.in\n> +++ b/Documentation/asciidoctor-extensions.rb.in\n> @@ -49,7 +49,7 @@ module Git\n>  \n>        def process parent, reader, attrs\n>          outlines = reader.lines.map do |l|\n> -          l.gsub(/(\\.\\.\\.?)([^\\]$.])/, '`\\1`\\2')\n> +          l.gsub(/(\\.\\.\\.?)([^\\]$\\. ])/, '{empty}`\\1`{empty}\\2')\n>             .gsub(%r{([\\[\\] |()>]|^)([-a-zA-Z0-9:+=~@,/_^\\$]+)}, '\\1{empty}`\\2`{empty}')\n>             .gsub(/(<[-a-zA-Z0-9.]+>)/, '__\\\\1__')\n>             .gsub(']', ']{empty}')\n> @@ -72,6 +72,7 @@ module Git\n>            %(<inlineequation><alt><![CDATA[#{equation = node.text}]]></alt><mathphrase><![CDATA[#{equation}]]></mathphrase></inlineequation>)\n>          elsif type == :monospaced\n>            node.text.gsub(/(\\.\\.\\.?)([^\\]$.])/, '<literal>\\1</literal>\\2')\n> +                        .gsub(/^\\.\\.\\.?$/, '<literal>\\0</literal>\\2')\n>                .gsub(%r{([\\[\\s|()>.]|^|\\]|&gt;)(\\.?([-a-zA-Z0-9:+=~@,/_^\\$]+\\.{0,2})+)}, '\\1<literal>\\2</literal>')\n>                .gsub(/(&lt;[-a-zA-Z0-9.]+&gt;)/, '<emphasis>\\1</emphasis>')\n>          else\n> @@ -100,6 +101,7 @@ module Git\n>        def convert_inline_quoted node\n>          if node.type == :monospaced\n>            node.text.gsub(/(\\.\\.\\.?)([^\\]$.])/, '<code>\\1</code>\\2')\n> +            .gsub(/^\\.\\.\\.?$/, '<code>\\0</code>')\n>                .gsub(%r{([\\[\\s|()>.]|^|\\]|&gt;)(\\.?([-a-zA-Z0-9:+=~@,/_^\\$]+\\.{0,2})+)}, '\\1<code>\\2</code>')\n>                .gsub(/(&lt;[-a-zA-Z0-9.]+&gt;)/, '<em>\\1</em>')\n>  \n\nThanks.  I can confirm that this patch addresses the issue I reported\nwith the manpage of 'git diff' (though I think the commit message\ncould go into a bit more detail as to what problem this patch attempts\nto solve and how).\n\nAlas, the issue caused by 'diff-generate-patch.adoc' in the manpages\nof diff-files, diff-index, log, etc. is still present.\n"},{"id":"515399","messageId":"5873733.DvuYhMxLoT@cayenne","threadId":"61899","inReplyTo":"Z+rUsCW0zEb8kAK8@szeder.dev","subject":"Re: [PATCH] doc: fix asciidoctor synopsis processing of triple-dots","fromName":"Jean-Noël AVILA","fromEmail":"jn.avila@free.fr","sentAt":"2025-03-31T20:30:57Z","receivedAt":"2025-03-31T20:31:15Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"Le lundi 31 mars 2025, 19:45:20 heure d’été d’Europe centrale SZEDER Gábor a \nécrit :\n> On Mon, Mar 31, 2025 at 02:55:51PM +0200, Jean-Noël Avila wrote:\n> > The processing of triple dot notation is tricky because it can be\n> > mis-interpreted as an ellipsis. The special processing of the ellipsis\n> > is now complete and takes into account the case of\n> > `git-mv <source>... <dest>`\n> > \n> > Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>\n> > ---\n> > \n> >  Documentation/asciidoctor-extensions.rb.in | 4 +++-\n> >  1 file changed, 3 insertions(+), 1 deletion(-)\n> > \n> > diff --git a/Documentation/asciidoctor-extensions.rb.in\n> > b/Documentation/asciidoctor-extensions.rb.in index 2494f17a51..f2be66c4ad\n> > 100644\n> > --- a/Documentation/asciidoctor-extensions.rb.in\n> > +++ b/Documentation/asciidoctor-extensions.rb.in\n> > @@ -49,7 +49,7 @@ module Git\n> > \n> >        def process parent, reader, attrs\n> >        \n> >          outlines = reader.lines.map do |l|\n> > \n> > -          l.gsub(/(\\.\\.\\.?)([^\\]$.])/, '`\\1`\\2')\n> > +          l.gsub(/(\\.\\.\\.?)([^\\]$\\. ])/, '{empty}`\\1`{empty}\\2')\n> > \n> >             .gsub(%r{([\\[\\] |()>]|^)([-a-zA-Z0-9:+=~@,/_^\\$]+)},\n> >             '\\1{empty}`\\2`{empty}')\n> >             .gsub(/(<[-a-zA-Z0-9.]+>)/, '__\\\\1__')\n> >             .gsub(']', ']{empty}')\n> > \n> > @@ -72,6 +72,7 @@ module Git\n> > \n> >            %(<inlineequation><alt><![CDATA[#{equation =\n> >            node.text}]]></alt><mathphrase><![CDATA[#{equation}]]></\nmathphra\n> >            se></inlineequation>)>          \n> >          elsif type == :monospaced\n> >          \n> >            node.text.gsub(/(\\.\\.\\.?)([^\\]$.])/, '<literal>\\1</literal>\\2')\n> > \n> > +                        .gsub(/^\\.\\.\\.?$/, '<literal>\\0</literal>\\2')\n> > \n> >                .gsub(%r{([\\[\\s|()>.]|^|\\]|&gt;)(\\.?([-a-zA-Z0-9:+=~@,/_^\\\n$]+\n> >                \\.{0,2})+)}, '\\1<literal>\\2</literal>')\n> >                .gsub(/(&lt;[-a-zA-Z0-9.]+&gt;)/, '<emphasis>\\1</\nemphasis>')\n> >          \n> >          else\n> > \n> > @@ -100,6 +101,7 @@ module Git\n> > \n> >        def convert_inline_quoted node\n> >        \n> >          if node.type == :monospaced\n> >          \n> >            node.text.gsub(/(\\.\\.\\.?)([^\\]$.])/, '<code>\\1</code>\\2')\n> > \n> > +            .gsub(/^\\.\\.\\.?$/, '<code>\\0</code>')\n> > \n> >                .gsub(%r{([\\[\\s|()>.]|^|\\]|&gt;)(\\.?([-a-zA-Z0-9:+=~@,/_^\\\n$]+\n> >                \\.{0,2})+)}, '\\1<code>\\2</code>')\n> >                .gsub(/(&lt;[-a-zA-Z0-9.]+&gt;)/, '<em>\\1</em>')\n> \n> Thanks.  I can confirm that this patch addresses the issue I reported\n> with the manpage of 'git diff' (though I think the commit message\n> could go into a bit more detail as to what problem this patch attempts\n> to solve and how).\n\nThese regex are getting a bit too hairy now. I'm working on using a parser \ngenerator to clarify how it works (at least for asciidoctor).\n\n> \n> Alas, the issue caused by 'diff-generate-patch.adoc' in the manpages\n> of diff-files, diff-index, log, etc. is still present.\n\nSorry to ready that, but I cannot reproduce on my setup (using asciidoctor \n2.0.23):\n\n        2. It is followed by one or more extended header lines (this example \nshows a merge with two parents):\n\n               index <hash>,<hash>..<hash>\n               mode <mode>,<mode>..<mode>\n               new file mode <mode>\n               deleted file mode <mode>,<mode>\n\nHas the format failure changed with this patch?\n\nThanks\n\nJN\n\n\n\n"},{"id":"515422","messageId":"20250401110811.117851-1-jn.avila@free.fr","threadId":"61899","inReplyTo":"Z+rUsCW0zEb8kAK8@szeder.dev","subject":"[PATCH] doc: fix asciidoctor synopsis processing of triple-dots","fromName":"Jean-Noël Avila","fromEmail":"jn.avila@free.fr","sentAt":"2025-04-01T11:08:11Z","receivedAt":"2025-04-01T11:26:55Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"The processing of triple dot notation is tricky because it can be\nmis-interpreted as an ellipsis.\n\nAnother issue is that the formatting of synopsis paragraph in\nAsciidoctor spits out another asciidoc formatted text where verbatim\ntext formatted with backquotes must have surrounding separators in\norder to be properly detected, even if they are sticking to another\ntext.\n\nThe special processing of the ellipsis is now complete and takes into\naccount the case of `git-mv <source>... <dest>`\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\n---\n Documentation/asciidoctor-extensions.rb.in | 8 +++++---\n Documentation/diff-generate-patch.adoc     | 2 +-\n 2 files changed, 6 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/asciidoctor-extensions.rb.in b/Documentation/asciidoctor-extensions.rb.in\nindex 2494f17a51..0ded90c28b 100644\n--- a/Documentation/asciidoctor-extensions.rb.in\n+++ b/Documentation/asciidoctor-extensions.rb.in\n@@ -49,7 +49,7 @@ module Git\n \n       def process parent, reader, attrs\n         outlines = reader.lines.map do |l|\n-          l.gsub(/(\\.\\.\\.?)([^\\]$.])/, '`\\1`\\2')\n+          l.gsub(/(\\.\\.\\.?)([^\\]$\\. ])/, '{empty}`\\1`{empty}\\2')\n            .gsub(%r{([\\[\\] |()>]|^)([-a-zA-Z0-9:+=~@,/_^\\$]+)}, '\\1{empty}`\\2`{empty}')\n            .gsub(/(<[-a-zA-Z0-9.]+>)/, '__\\\\1__')\n            .gsub(']', ']{empty}')\n@@ -72,6 +72,7 @@ module Git\n           %(<inlineequation><alt><![CDATA[#{equation = node.text}]]></alt><mathphrase><![CDATA[#{equation}]]></mathphrase></inlineequation>)\n         elsif type == :monospaced\n           node.text.gsub(/(\\.\\.\\.?)([^\\]$.])/, '<literal>\\1</literal>\\2')\n+              .gsub(/^\\.\\.\\.?$/, '<literal>\\0</literal>\\2')\n               .gsub(%r{([\\[\\s|()>.]|^|\\]|&gt;)(\\.?([-a-zA-Z0-9:+=~@,/_^\\$]+\\.{0,2})+)}, '\\1<literal>\\2</literal>')\n               .gsub(/(&lt;[-a-zA-Z0-9.]+&gt;)/, '<emphasis>\\1</emphasis>')\n         else\n@@ -100,8 +101,9 @@ module Git\n       def convert_inline_quoted node\n         if node.type == :monospaced\n           node.text.gsub(/(\\.\\.\\.?)([^\\]$.])/, '<code>\\1</code>\\2')\n-              .gsub(%r{([\\[\\s|()>.]|^|\\]|&gt;)(\\.?([-a-zA-Z0-9:+=~@,/_^\\$]+\\.{0,2})+)}, '\\1<code>\\2</code>')\n-              .gsub(/(&lt;[-a-zA-Z0-9.]+&gt;)/, '<em>\\1</em>')\n+            .gsub(/^\\.\\.\\.?$/, '<code>\\0</code>')\n+            .gsub(%r{([\\[\\s|()>.]|^|\\]|&gt;)(\\.?([-a-zA-Z0-9:+=~@,/_^\\$]+\\.{0,2})+)}, '\\1<code>\\2</code>')\n+            .gsub(/(&lt;[-a-zA-Z0-9.]+&gt;)/, '<em>\\1</em>')\n \n         else\n           open, close, tag = QUOTE_TAGS[node.type]\ndiff --git a/Documentation/diff-generate-patch.adoc b/Documentation/diff-generate-patch.adoc\nindex e5c813c96f..7b6cdd1980 100644\n--- a/Documentation/diff-generate-patch.adoc\n+++ b/Documentation/diff-generate-patch.adoc\n@@ -138,7 +138,7 @@ or like this (when the `--cc` option is used):\n +\n [synopsis]\n index <hash>,<hash>..<hash>\n-mode <mode>,<mode>`..`<mode>\n+mode <mode>,<mode>..<mode>\n new file mode <mode>\n deleted file mode <mode>,<mode>\n +\n-- \n2.49.0\n\n"},{"id":"515470","messageId":"xmqqecyba6zz.fsf@gitster.g","threadId":"61899","inReplyTo":"20250401110811.117851-1-jn.avila@free.fr","subject":"Re: [PATCH] doc: fix asciidoctor synopsis processing of triple-dots","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-04-01T21:48:00Z","receivedAt":"2025-04-01T21:48:03Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jean-Noël Avila <jn.avila@free.fr> writes:\n\n> The processing of triple dot notation is tricky because it can be\n> mis-interpreted as an ellipsis.\n>\n> Another issue is that the formatting of synopsis paragraph in\n> Asciidoctor spits out another asciidoc formatted text where verbatim\n> text formatted with backquotes must have surrounding separators in\n> order to be properly detected, even if they are sticking to another\n> text.\n>\n> The special processing of the ellipsis is now complete and takes into\n> account the case of `git-mv <source>... <dest>`\n>\n> Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>\n> ---\n>  Documentation/asciidoctor-extensions.rb.in | 8 +++++---\n>  Documentation/diff-generate-patch.adoc     | 2 +-\n>  2 files changed, 6 insertions(+), 4 deletions(-)\n\nThe .gsub() changes seem to interact with your \"doc: fix synopsis\nanalysis logic\" in the series that updates reset/mv/rm documentation\nmark-up.\n\n\n\n> diff --git a/Documentation/asciidoctor-extensions.rb.in b/Documentation/asciidoctor-extensions.rb.in\n> index 2494f17a51..0ded90c28b 100644\n> --- a/Documentation/asciidoctor-extensions.rb.in\n> +++ b/Documentation/asciidoctor-extensions.rb.in\n> @@ -49,7 +49,7 @@ module Git\n>  \n>        def process parent, reader, attrs\n>          outlines = reader.lines.map do |l|\n> -          l.gsub(/(\\.\\.\\.?)([^\\]$.])/, '`\\1`\\2')\n> +          l.gsub(/(\\.\\.\\.?)([^\\]$\\. ])/, '{empty}`\\1`{empty}\\2')\n>             .gsub(%r{([\\[\\] |()>]|^)([-a-zA-Z0-9:+=~@,/_^\\$]+)}, '\\1{empty}`\\2`{empty}')\n>             .gsub(/(<[-a-zA-Z0-9.]+>)/, '__\\\\1__')\n>             .gsub(']', ']{empty}')\n> @@ -72,6 +72,7 @@ module Git\n>            %(<inlineequation><alt><![CDATA[#{equation = node.text}]]></alt><mathphrase><![CDATA[#{equation}]]></mathphrase></inlineequation>)\n>          elsif type == :monospaced\n>            node.text.gsub(/(\\.\\.\\.?)([^\\]$.])/, '<literal>\\1</literal>\\2')\n> +              .gsub(/^\\.\\.\\.?$/, '<literal>\\0</literal>\\2')\n>                .gsub(%r{([\\[\\s|()>.]|^|\\]|&gt;)(\\.?([-a-zA-Z0-9:+=~@,/_^\\$]+\\.{0,2})+)}, '\\1<literal>\\2</literal>')\n>                .gsub(/(&lt;[-a-zA-Z0-9.]+&gt;)/, '<emphasis>\\1</emphasis>')\n>          else\n> @@ -100,8 +101,9 @@ module Git\n>        def convert_inline_quoted node\n>          if node.type == :monospaced\n>            node.text.gsub(/(\\.\\.\\.?)([^\\]$.])/, '<code>\\1</code>\\2')\n> -              .gsub(%r{([\\[\\s|()>.]|^|\\]|&gt;)(\\.?([-a-zA-Z0-9:+=~@,/_^\\$]+\\.{0,2})+)}, '\\1<code>\\2</code>')\n> -              .gsub(/(&lt;[-a-zA-Z0-9.]+&gt;)/, '<em>\\1</em>')\n> +            .gsub(/^\\.\\.\\.?$/, '<code>\\0</code>')\n> +            .gsub(%r{([\\[\\s|()>.]|^|\\]|&gt;)(\\.?([-a-zA-Z0-9:+=~@,/_^\\$]+\\.{0,2})+)}, '\\1<code>\\2</code>')\n> +            .gsub(/(&lt;[-a-zA-Z0-9.]+&gt;)/, '<em>\\1</em>')\n>  \n>          else\n>            open, close, tag = QUOTE_TAGS[node.type]\n> diff --git a/Documentation/diff-generate-patch.adoc b/Documentation/diff-generate-patch.adoc\n> index e5c813c96f..7b6cdd1980 100644\n> --- a/Documentation/diff-generate-patch.adoc\n> +++ b/Documentation/diff-generate-patch.adoc\n> @@ -138,7 +138,7 @@ or like this (when the `--cc` option is used):\n>  +\n>  [synopsis]\n>  index <hash>,<hash>..<hash>\n> -mode <mode>,<mode>`..`<mode>\n> +mode <mode>,<mode>..<mode>\n>  new file mode <mode>\n>  deleted file mode <mode>,<mode>\n>  +\n"},{"id":"515477","messageId":"dfe21538-e70c-4d19-a90f-2c3cf8d3d377@free.fr","threadId":"61899","inReplyTo":"xmqqecyba6zz.fsf@gitster.g","subject":"Re: [PATCH] doc: fix asciidoctor synopsis processing of triple-dots","fromName":"Jean-Noël Avila","fromEmail":"jn.avila@free.fr","sentAt":"2025-04-02T06:49:40Z","receivedAt":"2025-04-02T06:49:59Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"Le 01/04/2025 à 23:48, Junio C Hamano a écrit :\n> Jean-Noël Avila <jn.avila@free.fr> writes:\n> \n>> The processing of triple dot notation is tricky because it can be\n>> mis-interpreted as an ellipsis.\n>>\n>> Another issue is that the formatting of synopsis paragraph in\n>> Asciidoctor spits out another asciidoc formatted text where verbatim\n>> text formatted with backquotes must have surrounding separators in\n>> order to be properly detected, even if they are sticking to another\n>> text.\n>>\n>> The special processing of the ellipsis is now complete and takes into\n>> account the case of `git-mv <source>... <dest>`\n>>\n>> Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>\n>> ---\n>>  Documentation/asciidoctor-extensions.rb.in | 8 +++++---\n>>  Documentation/diff-generate-patch.adoc     | 2 +-\n>>  2 files changed, 6 insertions(+), 4 deletions(-)\n> \n> The .gsub() changes seem to interact with your \"doc: fix synopsis\n> analysis logic\" in the series that updates reset/mv/rm documentation\n> mark-up.\n> \n> \n\nI will incorporate this patch in the reset/mv/rm series.\n\n\n"},{"id":"515780","messageId":"xmqqfriknh0d.fsf@gitster.g","threadId":"61899","inReplyTo":"dfe21538-e70c-4d19-a90f-2c3cf8d3d377@free.fr","subject":"Re: [PATCH] doc: fix asciidoctor synopsis processing of triple-dots","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-04-07T15:11:30Z","receivedAt":"2025-04-07T15:11:33Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jean-Noël Avila <jn.avila@free.fr> writes:\n\n>> The .gsub() changes seem to interact with your \"doc: fix synopsis\n>> analysis logic\" in the series that updates reset/mv/rm documentation\n>> mark-up.\n>> \n>> \n>\n> I will incorporate this patch in the reset/mv/rm series.\n\nThanks.\n"}]}