Subject: Re: [PATCH v3 18/36] doc txt & -h consistency: fix mismatching labels

From: Junio C Hamano <[email-masked]>
Date: Fri, 30 Sep 2022 15:04:11 -0700

Ævar Arnfjörð Bjarmason  <[email-masked]> writes:

> -'git clean' [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <path>...
> +'git clean' [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <pathspec>...
>  
>  DESCRIPTION
>  -----------
> @@ -20,13 +20,13 @@ Normally, only files unknown to Git are removed, but if the `-x`
>  option is specified, ignored files are also removed. This can, for
>  example, be useful to remove all build products.
>  
> -If any optional `<path>...` arguments are given, only those paths
> +If any optional `<pathspec>...` arguments are given, only those paths
>  are affected.

If you replace <path> with <pathspec>, then "only those paths are"
must be replaced with "only those paths that match the pathspec
are", because you are losing "those paths" from the sentence.

> diff --git a/Documentation/git-credential-cache--daemon.txt b/Documentation/git-credential-cache--daemon.txt
> index 01e1c214dd8..74832d06806 100644
> --- a/Documentation/git-credential-cache--daemon.txt
> +++ b/Documentation/git-credential-cache--daemon.txt
> @@ -8,7 +8,7 @@ git-credential-cache--daemon - Temporarily store user credentials in memory
>  SYNOPSIS
>  --------
>  [verse]
> -'git credential-cache{litdd}daemon' [--debug] <socket>
> +'git credential-cache{litdd}daemon' [--debug] <socket-path>
>  
>  DESCRIPTION
>  -----------

The description text (outside the context of this hunk) still refers
to <socket>.

> diff --git a/Documentation/git-mv.txt b/Documentation/git-mv.txt
> index 972a055fbd8..c612a5fd5b9 100644
> --- a/Documentation/git-mv.txt
> +++ b/Documentation/git-mv.txt
> @@ -9,7 +9,7 @@ git-mv - Move or rename a file, a directory, or a symlink
>  SYNOPSIS
>  --------
>  [verse]
> -'git mv' [<options>] <args>...
> +'git mv' [<options>] <source>... <destination>

This one is good, as the rest of the document is written in terms of
the source and the destination.  The description of --force may need
to rephrase "target" -> "destination", though.

> diff --git a/Documentation/git-receive-pack.txt b/Documentation/git-receive-pack.txt
> index 014a78409b9..eec1268b10f 100644
> --- a/Documentation/git-receive-pack.txt
> +++ b/Documentation/git-receive-pack.txt
> @@ -9,7 +9,7 @@ git-receive-pack - Receive what is pushed into the repository
>  SYNOPSIS
>  --------
>  [verse]
> -'git-receive-pack' <directory>
> +'git-receive-pack' <git-dir>

`upload-archive` below is updated to call this <repository>, and
that might be a better update, but the goal of this step is to use
the same word in both code and text, so changing to <git-dir> is OK.

But "OPTIONS" part of the document (outside the context of this
hunk) still says <directory>, which should be corrected.

> diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt
> index 31a97a1b6c5..c15ec895720 100644
> --- a/Documentation/git-tag.txt
> +++ b/Documentation/git-tag.txt
> @@ -9,7 +9,7 @@ git-tag - Create, list, delete or verify a tag object signed with GPG
>  SYNOPSIS
>  --------
>  [verse]
> -'git tag' [-a | -s | -u <keyid>] [-f] [-m <msg> | -F <file>] [-e]
> +'git tag' [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>] [-e]
>  	<tagname> [<commit> | <object>]
>  'git tag' -d <tagname>...
>  'git tag' [-n[<num>]] -l [--contains <commit>] [--no-contains <commit>]

If you want to do "keyid" -> "key-id", then you'd need to update the
one in the DESCRIPTION part.

> diff --git a/Documentation/git-upload-archive.txt b/Documentation/git-upload-archive.txt
> index fba0f1c1b27..e8eb10baad7 100644
> --- a/Documentation/git-upload-archive.txt
> +++ b/Documentation/git-upload-archive.txt
> @@ -9,7 +9,7 @@ git-upload-archive - Send archive back to git-archive
>  SYNOPSIS
>  --------
>  [verse]
> -'git upload-archive' <directory>
> +'git upload-archive' <repository>
>  
>  DESCRIPTION
>  -----------
> @@ -54,7 +54,7 @@ access via non-smart-http.
>  
>  OPTIONS
>  -------
> -<directory>::
> +<repository>::
>  	The repository to get a tar archive from.

This is good.

> diff --git a/builtin/bugreport.c b/builtin/bugreport.c
> index 61d93383f51..96052541cbf 100644
> --- a/builtin/bugreport.c
> +++ b/builtin/bugreport.c
> @@ -60,7 +60,7 @@ static void get_populated_hooks(struct strbuf *hook_info, int nongit)
>  }
>  
>  static const char * const bugreport_usage[] = {
> -	N_("git bugreport [(-o | --output-directory) <file>] [(-s | --suffix) <format>]\n"
> +	N_("git bugreport [(-o | --output-directory) <path>] [(-s | --suffix) <format>]\n"
>  	   "              [--diagnose[=<mode>]]"),
>  	NULL
>  };
> diff --git a/builtin/clean.c b/builtin/clean.c
> index 5466636e666..6f039f555b2 100644
> --- a/builtin/clean.c
> +++ b/builtin/clean.c
> @@ -26,7 +26,7 @@ static struct string_list del_list = STRING_LIST_INIT_DUP;
>  static unsigned int colopts;
>  
>  static const char *const builtin_clean_usage[] = {
> -	N_("git clean [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <paths>..."),
> +	N_("git clean [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <pathspec>..."),
>  	NULL
>  };
>  
> diff --git a/builtin/commit-graph.c b/builtin/commit-graph.c
> index 13cbb75ca28..e8f77f535f3 100644
> --- a/builtin/commit-graph.c
> +++ b/builtin/commit-graph.c
> @@ -10,10 +10,10 @@
>  #include "tag.h"
>  
>  #define BUILTIN_COMMIT_GRAPH_VERIFY_USAGE \
> -	N_("git commit-graph verify [--object-dir <objdir>] [--shallow] [--[no-]progress]")
> +	N_("git commit-graph verify [--object-dir <dir>] [--shallow] [--[no-]progress]")
>  
>  #define BUILTIN_COMMIT_GRAPH_WRITE_USAGE \
> -	N_("git commit-graph write [--object-dir <objdir>] [--append]\n" \
> +	N_("git commit-graph write [--object-dir <dir>] [--append]\n" \
>  	   "                       [--split[=<strategy>]] [--reachable | --stdin-packs | --stdin-commits]\n" \
>  	   "                       [--changed-paths] [--[no-]max-new-filters <n>] [--[no-]progress]\n" \
>  	   "                       <split options>")
> diff --git a/builtin/credential-cache--daemon.c b/builtin/credential-cache--daemon.c
> index 4c6c89ab0de..ca672a6a619 100644
> --- a/builtin/credential-cache--daemon.c
> +++ b/builtin/credential-cache--daemon.c
> @@ -267,7 +267,7 @@ int cmd_credential_cache_daemon(int argc, const char **argv, const char *prefix)
>  	const char *socket_path;
>  	int ignore_sighup = 0;
>  	static const char *usage[] = {
> -		"git-credential-cache--daemon [opts] <socket_path>",
> +		"git-credential-cache--daemon [opts] <socket-path>",
>  		NULL
>  	};
>  	int debug = 0;

Heh, so we are allowed to change _BOTH_ code and text to make them
consistent.  We are not limited to pick the existing word used in
one or the other.  If that is the case, using <repository> instead
of <git-dir> for receive-pack may be a good change to make here as
well.

In any case, reviewing code part of this step is far easier than the
documentation part, as the latter must be done more carefully to
spot the mention of the earlier word in the entire document.