doc: convert git-difftool manual page to synopsis style
* convert commands to synopsis style * use _<placeholder>_ for arguments * fix conditional text to sentence limits Signed-off-by: Jean-Noël Avila <jn.avila@free.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Jean-Noël Avila committed
Apr 4, 2026 at 17:12 UTC
1d980196adfd79ae0936e681e8d98c57d9900785
3 files changed
+56
-56
Documentation/config/difftool.adoc
+12
-12
@@ -1,43 +1,43 @@
1
-diff.tool::
1
+`diff.tool`::
2
Controls which diff tool is used by linkgit:git-difftool[1].
3
This variable overrides the value configured in `merge.tool`.
4
The list below shows the valid built-in values.
5
Any other value is treated as a custom diff tool and requires
6
- that a corresponding difftool.<tool>.cmd variable is defined.
6
+ that a corresponding `difftool.<tool>.cmd` variable is defined.
7
8
-diff.guitool::
8
+`diff.guitool`::
9
Controls which diff tool is used by linkgit:git-difftool[1] when
10
- the -g/--gui flag is specified. This variable overrides the value
10
+ the `-g`/`--gui` flag is specified. This variable overrides the value
11
configured in `merge.guitool`. The list below shows the valid
12
built-in values. Any other value is treated as a custom diff tool
13
- and requires that a corresponding difftool.<guitool>.cmd variable
13
+ and requires that a corresponding `difftool.<guitool>.cmd` variable
14
is defined.
15
16
include::{build_dir}/mergetools-diff.adoc[]
17
18
-difftool.<tool>.cmd::
18
+`difftool.<tool>.cmd`::
19
Specify the command to invoke the specified diff tool.
20
The specified command is evaluated in shell with the following
21
- variables available: 'LOCAL' is set to the name of the temporary
22
- file containing the contents of the diff pre-image and 'REMOTE'
21
+ variables available: `LOCAL` is set to the name of the temporary
22
+ file containing the contents of the diff pre-image and `REMOTE`
23
is set to the name of the temporary file containing the contents
24
of the diff post-image.
25
+
26
See the `--tool=<tool>` option in linkgit:git-difftool[1] for more details.
27
28
-difftool.<tool>.path::
28
+`difftool.<tool>.path`::
29
Override the path for the given tool. This is useful in case
30
your tool is not in the PATH.
31
32
-difftool.trustExitCode::
32
+`difftool.trustExitCode`::
33
Exit difftool if the invoked diff tool returns a non-zero exit status.
34
+
35
See the `--trust-exit-code` option in linkgit:git-difftool[1] for more details.
36
37
-difftool.prompt::
37
+`difftool.prompt`::
38
Prompt before each invocation of the diff tool.
39
40
-difftool.guiDefault::
40
+`difftool.guiDefault`::
41
Set `true` to use the `diff.guitool` by default (equivalent to specifying
42
the `--gui` argument), or `auto` to select `diff.guitool` or `diff.tool`
43
depending on the presence of a `DISPLAY` environment variable value. The
Documentation/config/mergetool.adoc
+4
-4
@@ -52,13 +52,13 @@
52
if `merge.tool` is configured as _<variant>_), Git will consult
53
`mergetool.<variant>.layout` to determine the tool's layout. If the
54
variant-specific configuration is not available, `vimdiff` ' s is used as
55
- fallback. If that too is not available, a default layout with 4 windows
56
- will be used. To configure the layout, see the 'BACKEND SPECIFIC HINTS'
55
+ fallback. If that too is not available, a default layout with 4 windows
56
+ will be used.
57
ifdef::git-mergetool[]
58
- section.
58
+To configure the layout, see the 'BACKEND SPECIFIC HINTS' section.
59
endif::[]
60
ifndef::git-mergetool[]
61
- section in linkgit:git-mergetool[1].
61
+To configure the layout, see the 'BACKEND SPECIFIC HINTS' section in linkgit:git-mergetool[1].
62
endif::[]
63
64
`mergetool.hideResolved`::
Documentation/git-difftool.adoc
+40
-40
@@ -7,64 +7,64 @@ git-difftool - Show changes using common diff tools
7
8
SYNOPSIS
9
--------
10
-[verse]
11
-'git difftool' [<options>] [<commit> [<commit>]] [--] [<path>...]
10
+[synopsis]
11
+git difftool [<options>] [<commit> [<commit>]] [--] [<path>...]
12
13
DESCRIPTION
14
-----------
15
-'git difftool' is a Git command that allows you to compare and edit files
16
-between revisions using common diff tools. 'git difftool' is a frontend
17
-to 'git diff' and accepts the same options and arguments. See
15
+`git difftool` is a Git command that allows you to compare and edit files
16
+between revisions using common diff tools. `git difftool` is a frontend
17
+to `git diff` and accepts the same options and arguments. See
18
linkgit:git-diff[1].
19
20
OPTIONS
21
-------
22
--d::
23
---dir-diff::
22
+`-d`::
23
+`--dir-diff`::
24
Copy the modified files to a temporary location and perform
25
a directory diff on them. This mode never prompts before
26
launching the diff tool.
27
28
--y::
29
---no-prompt::
28
+`-y`::
29
+`--no-prompt`::
30
Do not prompt before launching a diff tool.
31
32
---prompt::
32
+`--prompt`::
33
Prompt before each invocation of the diff tool.
34
This is the default behaviour; the option is provided to
35
override any configuration settings.
36
37
---rotate-to=<file>::
38
- Start showing the diff for the given path,
37
+`--rotate-to=<file>`::
38
+ Start showing the diff for _<file>_,
39
the paths before it will move to the end and output.
40
41
---skip-to=<file>::
42
- Start showing the diff for the given path, skipping all
41
+`--skip-to=<file>`::
42
+ Start showing the diff for _<file>_, skipping all
43
the paths before it.
44
45
--t <tool>::
46
---tool=<tool>::
47
- Use the diff tool specified by <tool>. Valid values include
45
+`-t <tool>`::
46
+`--tool=<tool>`::
47
+ Use the diff tool specified by _<tool>_. Valid values include
48
emerge, kompare, meld, and vimdiff. Run `git difftool --tool-help`
49
- for the list of valid <tool> settings.
49
+ for the list of valid _<tool>_ settings.
50
+
51
-If a diff tool is not specified, 'git difftool'
51
+If a diff tool is not specified, `git difftool`
52
will use the configuration variable `diff.tool`. If the
53
-configuration variable `diff.tool` is not set, 'git difftool'
53
+configuration variable `diff.tool` is not set, `git difftool`
54
will pick a suitable default.
55
+
56
You can explicitly provide a full path to the tool by setting the
57
configuration variable `difftool.<tool>.path`. For example, you
58
can configure the absolute path to kdiff3 by setting
59
-`difftool.kdiff3.path`. Otherwise, 'git difftool' assumes the
59
+`difftool.kdiff3.path`. Otherwise, `git difftool` assumes the
60
tool is available in PATH.
61
+
62
Instead of running one of the known diff tools,
63
-'git difftool' can be customized to run an alternative program
63
+`git difftool` can be customized to run an alternative program
64
by specifying the command line to invoke in a configuration
65
variable `difftool.<tool>.cmd`.
66
+
67
-When 'git difftool' is invoked with this tool (either through the
67
+When `git difftool` is invoked with this tool (either through the
68
`-t` or `--tool` option or the `diff.tool` configuration variable)
69
the configured command line will be invoked with the following
70
variables available: `$LOCAL` is set to the name of the temporary
@@ -74,30 +74,30 @@ of the diff post-image. `$MERGED` is the name of the file which is
74
being compared. `$BASE` is provided for compatibility
75
with custom merge tool commands and has the same value as `$MERGED`.
76
77
---tool-help::
77
+`--tool-help`::
78
Print a list of diff tools that may be used with `--tool`.
79
80
---symlinks::
81
---no-symlinks::
82
- 'git difftool''s default behavior is to create symlinks to the
80
+`--symlinks`::
81
+`--no-symlinks`::
82
+ `git difftool`'s default behavior is to create symlinks to the
83
working tree when run in `--dir-diff` mode and the right-hand
84
side of the comparison yields the same content as the file in
85
the working tree.
86
+
87
-Specifying `--no-symlinks` instructs 'git difftool' to create copies
87
+Specifying `--no-symlinks` instructs `git difftool` to create copies
88
instead. `--no-symlinks` is the default on Windows.
89
90
--x <command>::
91
---extcmd=<command>::
90
+`-x <command>`::
91
+`--extcmd=<command>`::
92
Specify a custom command for viewing diffs.
93
- 'git-difftool' ignores the configured defaults and runs
93
+ `git-difftool` ignores the configured defaults and runs
94
`<command> $LOCAL $REMOTE` when this option is specified.
95
Additionally, `$BASE` is set in the environment.
96
97
--g::
98
---gui::
99
---no-gui::
100
- When 'git-difftool' is invoked with the `-g` or `--gui` option
97
+`-g`::
98
+`--gui`::
99
+`--no-gui`::
100
+ When `git-difftool` is invoked with the `-g` or `--gui` option
101
the default diff tool will be read from the configured
102
`diff.guitool` variable instead of `diff.tool`. This may be
103
selected automatically using the configuration variable
@@ -106,20 +106,20 @@ instead. `--no-symlinks` is the default on Windows.
106
fallback in the order of `merge.guitool`, `diff.tool`,
107
`merge.tool` until a tool is found.
108
109
---trust-exit-code::
110
---no-trust-exit-code::
109
+`--trust-exit-code`::
110
+`--no-trust-exit-code`::
111
Errors reported by the diff tool are ignored by default.
112
- Use `--trust-exit-code` to make 'git-difftool' exit when an
112
+ Use `--trust-exit-code` to make `git-difftool` exit when an
113
invoked diff tool returns a non-zero exit code.
114
+
115
-'git-difftool' will forward the exit code of the invoked tool when
115
+`git-difftool` will forward the exit code of the invoked tool when
116
`--trust-exit-code` is used.
117
118
See linkgit:git-diff[1] for the full list of supported options.
119
120
CONFIGURATION
121
-------------
122
-'git difftool' falls back to 'git mergetool' config variables when the
122
+`git difftool` falls back to `git mergetool` config variables when the
123
difftool equivalents have not been defined.
124
125
include::includes/cmd-config-section-rest.adoc[]