Subject: [PATCH 1/4] doc: convert git-difftool manual page to synopsis style

From: "Jean-Noël Avila via GitGitGadget" <[email-masked]>
Date: Sat, 04 Apr 2026 17:12:44 +0000

From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <[email-masked]>

     * convert commands to synopsis style
     * use _<placeholder>_ for arguments
     * fix conditional text to sentence limits

Signed-off-by: Jean-Noël Avila <[email-masked]>
---
 Documentation/config/difftool.adoc  | 24 ++++-----
 Documentation/config/mergetool.adoc |  8 +--
 Documentation/git-difftool.adoc     | 80 ++++++++++++++---------------
 3 files changed, 56 insertions(+), 56 deletions(-)

diff --git a/Documentation/config/difftool.adoc b/Documentation/config/difftool.adoc
index 4f7d40ce24..1b8d483813 100644
--- a/Documentation/config/difftool.adoc
+++ b/Documentation/config/difftool.adoc
@@ -1,43 +1,43 @@
-diff.tool::
+`diff.tool`::
 	Controls which diff tool is used by linkgit:git-difftool[1].
 	This variable overrides the value configured in `merge.tool`.
 	The list below shows the valid built-in values.
 	Any other value is treated as a custom diff tool and requires
-	that a corresponding difftool.<tool>.cmd variable is defined.
+	that a corresponding `difftool.<tool>.cmd` variable is defined.
 
-diff.guitool::
+`diff.guitool`::
 	Controls which diff tool is used by linkgit:git-difftool[1] when
-	the -g/--gui flag is specified. This variable overrides the value
+	the `-g`/`--gui` flag is specified. This variable overrides the value
 	configured in `merge.guitool`. The list below shows the valid
 	built-in values. Any other value is treated as a custom diff tool
-	and requires that a corresponding difftool.<guitool>.cmd variable
+	and requires that a corresponding `difftool.<guitool>.cmd` variable
 	is defined.
 
 include::{build_dir}/mergetools-diff.adoc[]
 
-difftool.<tool>.cmd::
+`difftool.<tool>.cmd`::
 	Specify the command to invoke the specified diff tool.
 	The specified command is evaluated in shell with the following
-	variables available:  'LOCAL' is set to the name of the temporary
-	file containing the contents of the diff pre-image and 'REMOTE'
+	variables available: `LOCAL` is set to the name of the temporary
+	file containing the contents of the diff pre-image and `REMOTE`
 	is set to the name of the temporary file containing the contents
 	of the diff post-image.
 +
 See the `--tool=<tool>` option in linkgit:git-difftool[1] for more details.
 
-difftool.<tool>.path::
+`difftool.<tool>.path`::
 	Override the path for the given tool.  This is useful in case
 	your tool is not in the PATH.
 
-difftool.trustExitCode::
+`difftool.trustExitCode`::
 	Exit difftool if the invoked diff tool returns a non-zero exit status.
 +
 See the `--trust-exit-code` option in linkgit:git-difftool[1] for more details.
 
-difftool.prompt::
+`difftool.prompt`::
 	Prompt before each invocation of the diff tool.
 
-difftool.guiDefault::
+`difftool.guiDefault`::
 	Set `true` to use the `diff.guitool` by default (equivalent to specifying
 	the `--gui` argument), or `auto` to select `diff.guitool` or `diff.tool`
 	depending on the presence of a `DISPLAY` environment variable value. The
diff --git a/Documentation/config/mergetool.adoc b/Documentation/config/mergetool.adoc
index 7064f5a462..7afdcad92b 100644
--- a/Documentation/config/mergetool.adoc
+++ b/Documentation/config/mergetool.adoc
@@ -52,13 +52,13 @@
 	if `merge.tool` is configured as _<variant>_), Git will consult
 	`mergetool.<variant>.layout` to determine the tool's layout. If the
 	variant-specific configuration is not available, `vimdiff` ' s is used as
-	fallback.  If that too is not available, a default layout with 4 windows
-	will be used.  To configure the layout, see the 'BACKEND SPECIFIC HINTS'
+	fallback. If that too is not available, a default layout with 4 windows
+	will be used.
 ifdef::git-mergetool[]
-	section.
+To configure the layout, see the 'BACKEND SPECIFIC HINTS' section.
 endif::[]
 ifndef::git-mergetool[]
-	section in linkgit:git-mergetool[1].
+To configure the layout, see the 'BACKEND SPECIFIC HINTS' section in linkgit:git-mergetool[1].
 endif::[]
 
 `mergetool.hideResolved`::
diff --git a/Documentation/git-difftool.adoc b/Documentation/git-difftool.adoc
index 064bc68347..dd7cacf95e 100644
--- a/Documentation/git-difftool.adoc
+++ b/Documentation/git-difftool.adoc
@@ -7,64 +7,64 @@ git-difftool - Show changes using common diff tools
 
 SYNOPSIS
 --------
-[verse]
-'git difftool' [<options>] [<commit> [<commit>]] [--] [<path>...]
+[synopsis]
+git difftool [<options>] [<commit> [<commit>]] [--] [<path>...]
 
 DESCRIPTION
 -----------
-'git difftool' is a Git command that allows you to compare and edit files
-between revisions using common diff tools.  'git difftool' is a frontend
-to 'git diff' and accepts the same options and arguments. See
+`git difftool` is a Git command that allows you to compare and edit files
+between revisions using common diff tools. `git difftool` is a frontend
+to `git diff` and accepts the same options and arguments. See
 linkgit:git-diff[1].
 
 OPTIONS
 -------
--d::
---dir-diff::
+`-d`::
+`--dir-diff`::
 	Copy the modified files to a temporary location and perform
 	a directory diff on them. This mode never prompts before
 	launching the diff tool.
 
--y::
---no-prompt::
+`-y`::
+`--no-prompt`::
 	Do not prompt before launching a diff tool.
 
---prompt::
+`--prompt`::
 	Prompt before each invocation of the diff tool.
 	This is the default behaviour; the option is provided to
 	override any configuration settings.
 
---rotate-to=<file>::
-	Start showing the diff for the given path,
+`--rotate-to=<file>`::
+	Start showing the diff for _<file>_,
 	the paths before it will move to the end and output.
 
---skip-to=<file>::
-	Start showing the diff for the given path, skipping all
+`--skip-to=<file>`::
+	Start showing the diff for _<file>_, skipping all
 	the paths before it.
 
--t <tool>::
---tool=<tool>::
-	Use the diff tool specified by <tool>.  Valid values include
+`-t <tool>`::
+`--tool=<tool>`::
+	Use the diff tool specified by _<tool>_. Valid values include
 	emerge, kompare, meld, and vimdiff. Run `git difftool --tool-help`
-	for the list of valid <tool> settings.
+	for the list of valid _<tool>_ settings.
 +
-If a diff tool is not specified, 'git difftool'
+If a diff tool is not specified, `git difftool`
 will use the configuration variable `diff.tool`.  If the
-configuration variable `diff.tool` is not set, 'git difftool'
+configuration variable `diff.tool` is not set, `git difftool`
 will pick a suitable default.
 +
 You can explicitly provide a full path to the tool by setting the
 configuration variable `difftool.<tool>.path`. For example, you
 can configure the absolute path to kdiff3 by setting
-`difftool.kdiff3.path`. Otherwise, 'git difftool' assumes the
+`difftool.kdiff3.path`. Otherwise, `git difftool` assumes the
 tool is available in PATH.
 +
 Instead of running one of the known diff tools,
-'git difftool' can be customized to run an alternative program
+`git difftool` can be customized to run an alternative program
 by specifying the command line to invoke in a configuration
 variable `difftool.<tool>.cmd`.
 +
-When 'git difftool' is invoked with this tool (either through the
+When `git difftool` is invoked with this tool (either through the
 `-t` or `--tool` option or the `diff.tool` configuration variable)
 the configured command line will be invoked with the following
 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
 being compared. `$BASE` is provided for compatibility
 with custom merge tool commands and has the same value as `$MERGED`.
 
---tool-help::
+`--tool-help`::
 	Print a list of diff tools that may be used with `--tool`.
 
---symlinks::
---no-symlinks::
-	'git difftool''s default behavior is to create symlinks to the
+`--symlinks`::
+`--no-symlinks`::
+	`git difftool`'s default behavior is to create symlinks to the
 	working tree when run in `--dir-diff` mode and the right-hand
 	side of the comparison yields the same content as the file in
 	the working tree.
 +
-Specifying `--no-symlinks` instructs 'git difftool' to create copies
+Specifying `--no-symlinks` instructs `git difftool` to create copies
 instead.  `--no-symlinks` is the default on Windows.
 
--x <command>::
---extcmd=<command>::
+`-x <command>`::
+`--extcmd=<command>`::
 	Specify a custom command for viewing diffs.
-	'git-difftool' ignores the configured defaults and runs
+	`git-difftool` ignores the configured defaults and runs
 	`<command> $LOCAL $REMOTE` when this option is specified.
 	Additionally, `$BASE` is set in the environment.
 
--g::
---gui::
---no-gui::
-	When 'git-difftool' is invoked with the `-g` or `--gui` option
+`-g`::
+`--gui`::
+`--no-gui`::
+	When `git-difftool` is invoked with the `-g` or `--gui` option
 	the default diff tool will be read from the configured
 	`diff.guitool` variable instead of `diff.tool`. This may be
 	selected automatically using the configuration variable
@@ -106,20 +106,20 @@ instead.  `--no-symlinks` is the default on Windows.
 	fallback in the order of `merge.guitool`, `diff.tool`,
 	`merge.tool` until a tool is found.
 
---trust-exit-code::
---no-trust-exit-code::
+`--trust-exit-code`::
+`--no-trust-exit-code`::
 	Errors reported by the diff tool are ignored by default.
-	Use `--trust-exit-code` to make 'git-difftool' exit when an
+	Use `--trust-exit-code` to make `git-difftool` exit when an
 	invoked diff tool returns a non-zero exit code.
 +
-'git-difftool' will forward the exit code of the invoked tool when
+`git-difftool` will forward the exit code of the invoked tool when
 `--trust-exit-code` is used.
 
 See linkgit:git-diff[1] for the full list of supported options.
 
 CONFIGURATION
 -------------
-'git difftool' falls back to 'git mergetool' config variables when the
+`git difftool` falls back to `git mergetool` config variables when the
 difftool equivalents have not been defined.
 
 include::includes/cmd-config-section-rest.adoc[]
-- 
gitgitgadget