This is the continuation of the editing of the manpages to reflect the new formatting rules. Changes since V1: * restate the formatting rules in the message of the first commit * fix typos * convert more parts to backticked * filter out most annoying self-referencing links * propose to separate with 'or' the -1 --ours options and the likes Jean-Noël Avila (5): doc: git-diff: apply new documentation guidelines doc: git-diff: apply format changes to diff-options doc: git-diff: apply format changes to diff-format doc: git-diff: apply format changes to diff-generate-patch doc: git-diff: apply format changes to config part Documentation/config/diff.txt | 204 +++++++------ Documentation/diff-format.txt | 42 +-- Documentation/diff-generate-patch.txt | 44 +-- Documentation/diff-options.txt | 423 +++++++++++++------------- Documentation/git-diff.txt | 108 +++---- 5 files changed, 424 insertions(+), 397 deletions(-) base-commit: facbe4f633e4ad31e641f64617bc88074c659959 Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1769%2Fjnavila%2Fgit_diff_new-v3 Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1769/jnavila/git_diff_new-v3 Pull-Request: https://github.com/gitgitgadget/git/pull/1769 Range-diff vs v2: 1: c104bd50b64 ! 1: 6841bd5825b doc: git-diff: apply new documentation guidelines @@ Metadata ## Commit message ## doc: git-diff: apply new documentation guidelines + The documentation for git-diff has been updated to follow the new + documentation guidelines. The following changes have been applied to + the series of patches: + + - switching the synopsis to a synopsis block which will automatically + format placeholders in italics and keywords in monospace + - use _<placeholder>_ instead of <placeholder> in the description + - use `backticks for keywords and more complex option + descriptions`. The new rendering engine will apply synopsis rules to + these spans. + - prevent git-diff from self-referencing itself via gitlink macro when + the generated link would point to the same page. + Signed-off-by: Jean-Noël Avila <jn.avila@xxxxxxx> ## Documentation/git-diff.txt ## @@ Documentation/git-diff.txt: OPTIONS --1 --base:: --2 --ours:: --3 --theirs:: -+`-1` `--base`:: -+`-2` `--ours`:: -+`-3` `--theirs`:: ++`-1`:: ++`--base`:: ++ ++or `-2`:: ++`--ours`:: ++ ++or `-3`:: ++`--theirs`:: Compare the working tree with the "base" version (stage #1), "our branch" (stage #2) or "their branch" (stage #3). The index contains these stages only for unmerged entries i.e. @@ Documentation/git-diff.txt: OPTIONS -<path>...:: - The <paths> parameters, when given, are used to limit -+_<path>_...:: ++`<path>...`:: + The _<path>_ parameters, when given, are used to limit the diff to the named paths (you can give directory names and get diff for all files under them). 2: 129763c2aae = 2: 07df397741b doc: git-diff: apply format changes to diff-options 3: 8fec37ee174 = 3: 698628e076b doc: git-diff: apply format changes to diff-format 4: daed146639d = 4: 1154462f8be doc: git-diff: apply format changes to diff-generate-patch 5: 17a2f028d59 ! 5: 4ec2fd9c3c6 doc: git-diff: apply format changes to config part @@ Metadata ## Commit message ## doc: git-diff: apply format changes to config part + By the way, we also change the sentences where git-diff would refer to + itself, so that no link is created in the HTML output. + Signed-off-by: Jean-Noël Avila <jn.avila@xxxxxxx> ## Documentation/config/diff.txt ## @@ Documentation/config/diff.txt Instead, silently run `git update-index --refresh` to update the cached stat information for paths whose contents in the work tree match the contents in the - index. This option defaults to true. Note that this +- index. This option defaults to true. Note that this - affects only 'git diff' Porcelain, and not lower level - 'diff' commands such as 'git diff-files'. ++ index. This option defaults to `true`. Note that this + affects only `git diff` Porcelain, and not lower level -+ `diff` commands such as '`git diff-files`. ++ `diff` commands such as `git diff-files`. -diff.dirstat:: +`diff.dirstat`:: ++ifdef::git-diff[] ++ A comma separated list of `--dirstat` parameters specifying the ++ default behavior of the `--dirstat` option to `git diff` and friends. ++endif::git-diff[] ++ifndef::git-diff[] A comma separated list of `--dirstat` parameters specifying the default behavior of the `--dirstat` option to linkgit:git-diff[1] - and friends. The defaults can be overridden on the command line +- and friends. The defaults can be overridden on the command line - (using `--dirstat=<param1,param2,...>`). The fallback defaults ++ and friends. ++endif::git-diff[] ++ The defaults can be overridden on the command line + (using `--dirstat=<param>,...`). The fallback defaults (when not changed by `diff.dirstat`) are `changes,noncumulative,3`. The following parameters are available: @@ Documentation/config/diff.txt: directories with less than 10% of the total amoun -diff.mnemonicPrefix:: - If set, 'git diff' uses a prefix pair that is different from the +- standard "a/" and "b/" depending on what is being compared. When +`diff.mnemonicPrefix`:: + If set, `git diff` uses a prefix pair that is different from the - standard "a/" and "b/" depending on what is being compared. When ++ standard `a/` and `b/` depending on what is being compared. When this configuration is in effect, reverse diff output also swaps the order of the prefixes: + `git diff`;; @@ Documentation/config/diff.txt: diff.mnemonicPrefix:: compares a (c)ommit and the (w)ork tree; `git diff --cached`;; @@ Documentation/config/diff.txt: diff.mnemonicPrefix:: -`git diff HEAD:file1 file2`;; +`git diff HEAD:<file1> <file2>`;; compares an (o)bject and a (w)ork tree entity; - `git diff --no-index a b`;; - compares two non-git things (1) and (2). +-`git diff --no-index a b`;; +- compares two non-git things (1) and (2). ++`git diff --no-index <a> <b>`;; ++ compares two non-git things _<a>_ and _<b>_. -diff.noPrefix:: - If set, 'git diff' does not show any source or destination prefix. @@ Documentation/config/diff.txt: diff.mnemonicPrefix:: -diff.srcPrefix:: - If set, 'git diff' uses this source prefix. Defaults to "a/". +`diff.srcPrefix`:: -+ If set, `git diff` uses this source prefix. Defaults to "a/". ++ If set, `git diff` uses this source prefix. Defaults to `a/`. -diff.dstPrefix:: - If set, 'git diff' uses this destination prefix. Defaults to "b/". +`diff.dstPrefix`:: -+ If set, `git diff` uses this destination prefix. Defaults to "b/". ++ If set, `git diff` uses this destination prefix. Defaults to `b/`. -diff.relative:: - If set to 'true', 'git diff' does not show changes outside of the directory @@ Documentation/config/diff.txt: diff.mnemonicPrefix:: +`diff.orderFile`:: File indicating how to order files within a diff. - See the '-O' option to linkgit:git-diff[1] for details. ++ifdef::git-diff[] ++ See the `-O` option for details. ++endif::git-diff[] ++ifndef::git-diff[] + See the `-O` option to linkgit:git-diff[1] for details. ++endif::git-diff[] If `diff.orderFile` is a relative pathname, it is treated as relative to the top of the working tree. @@ Documentation/config/diff.txt: diff.mnemonicPrefix:: - Whether and how Git detects renames. If set to "false", - rename detection is disabled. If set to "true", basic rename - detection is enabled. If set to "copies" or "copy", Git will +- detect copies, as well. Defaults to true. Note that this +- affects only 'git diff' Porcelain like linkgit:git-diff[1] and +`diff.renames`:: + Whether and how Git detects renames. If set to `false`, + rename detection is disabled. If set to `true`, basic rename + detection is enabled. If set to `copies` or `copy`, Git will - detect copies, as well. Defaults to true. Note that this -- affects only 'git diff' Porcelain like linkgit:git-diff[1] and ++ detect copies, as well. Defaults to `true`. Note that this + affects only `git diff` Porcelain like linkgit:git-diff[1] and linkgit:git-log[1], and not lower level commands such as linkgit:git-diff-files[1]. @@ Documentation/config/diff.txt: diff.mnemonicPrefix:: for details. -diff.<driver>.trustExitCode:: +- If this boolean value is set to true then the +`diff.<driver>.trustExitCode`:: - If this boolean value is set to true then the ++ If this boolean value is set to `true` then the `diff.<driver>.command` command is expected to return exit code 0 if it considers the input files to be equal or 1 if it - considers them to be different, like `diff(1)`. +- If it is set to false, which is the default, then the command + considers them to be different, like `diff`(1). - If it is set to false, which is the default, then the command ++ If it is set to `false`, which is the default, then the command is expected to return exit code 0 regardless of equality. Any other exit code causes Git to report a fatal error. @@ Documentation/config/diff.txt: diff.mnemonicPrefix:: details. -diff.<driver>.cachetextconv:: +- Set this option to true to make the diff driver cache the text +`diff.<driver>.cachetextconv`:: - Set this option to true to make the diff driver cache the text ++ Set this option to `true` to make the diff driver cache the text conversion outputs. See linkgit:gitattributes[5] for details. include::../mergetools-diff.txt[] @@ Documentation/config/diff.txt: diff.wsErrorHighlight:: -diff.colorMoved:: - If set to either a valid `<mode>` or a true value, moved lines -+`diff.colorMoved`:: -+ If set to either a valid _<mode>_ or a true value, moved lines - in a diff are colored differently, for details of valid modes +- in a diff are colored differently, for details of valid modes - see '--color-moved' in linkgit:git-diff[1]. If simply set to - true the default color mode will be used. When set to false, -+ see `--color-moved` in linkgit:git-diff[1]. If simply set to -+ `true` the default color mode will be used. When set to `false`, - moved lines are not colored. - +- moved lines are not colored. +- -diff.colorMovedWS:: ++`diff.colorMoved`:: ++ If set to either a valid _<mode>_ or a `true` value, moved lines ++ in a diff are colored differently. ++ifdef::git-diff[] ++ For details of valid modes see `--color-moved`. ++endif::git-diff[] ++ifndef::git-diff[] ++ For details of valid modes see `--color-moved` in linkgit:git-diff[1]. ++endif::git-diff[] ++ If simply set to `true` the default color mode will be used. When ++ set to `false`, moved lines are not colored. ++ +`diff.colorMovedWS`:: When moved lines are colored using e.g. the `diff.colorMoved` setting, - this option controls the `<mode>` how spaces are treated. -- gitgitgadget
