[PATCH] Documentation: replace - use consistent 'replace reference'

[PATCH] Documentation: replace - use consistent 'replace reference'

[Yaroslav Halchenko]

As a new user to 'git replace' I found it a little uncertain about what
"'replace' reference" documentation was talking since there was only
"replacement" mentioned in the command summary.  Decided to make it more
consistent as 'replace reference' after checking that in a few spots there is a
use of multi word entries within <>.

Signed-off-by: Yaroslav Halchenko <debian@onerussian.com>
---
 Documentation/git-replace.txt | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/Documentation/git-replace.txt b/Documentation/git-replace.txt
index f271d758c3..71f98edfe3 100644
--- a/Documentation/git-replace.txt
+++ b/Documentation/git-replace.txt
@@ -8,7 +8,7 @@ git-replace - Create, list, delete refs to replace objects
 SYNOPSIS
 --------
 [verse]
-'git replace' [-f] <object> <replacement>
+'git replace' [-f] <object> <replace reference>
 'git replace' [-f] --edit <object>
 'git replace' [-f] --graft <commit> [<parent>...]
 'git replace' [-f] --convert-graft-file
@@ -17,16 +17,16 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-Adds a 'replace' reference in `refs/replace/` namespace.
+Adds a 'replace reference' in `refs/replace/` namespace.
 
-The name of the 'replace' reference is the SHA-1 of the object that is
-replaced. The content of the 'replace' reference is the SHA-1 of the
+The name of the 'replace reference' is the SHA-1 of the object that is
+replaced. The content of the 'replace reference' is the SHA-1 of the
 replacement object.
 
 The replaced object and the replacement object must be of the same type.
 This restriction can be bypassed using `-f`.
 
-Unless `-f` is given, the 'replace' reference must not yet exist.
+Unless `-f` is given, the 'replace reference' must not yet exist.
 
 There is no other restriction on the replaced and replacement objects.
 Merge commits can be replaced by non-merge commits and vice versa.
-- 
2.35.1

Re: [PATCH] Documentation: replace - use consistent 'replace reference'

[Junio C Hamano]

Yaroslav Halchenko <debian@onerussian.com> writes:

> As a new user to 'git replace' I found it a little uncertain about what
> "'replace' reference" documentation was talking since there was only
> "replacement" mentioned in the command summary.  Decided to make it more
> consistent as 'replace reference' after checking that in a few spots there is a
> use of multi word entries within <>.
>
> Signed-off-by: Yaroslav Halchenko <debian@onerussian.com>
> ---
>  Documentation/git-replace.txt | 10 +++++-----
>  1 file changed, 5 insertions(+), 5 deletions(-)
>
> diff --git a/Documentation/git-replace.txt b/Documentation/git-replace.txt
> index f271d758c3..71f98edfe3 100644
> --- a/Documentation/git-replace.txt
> +++ b/Documentation/git-replace.txt
> @@ -8,7 +8,7 @@ git-replace - Create, list, delete refs to replace objects
>  SYNOPSIS
>  --------
>  [verse]
> -'git replace' [-f] <object> <replacement>
> +'git replace' [-f] <object> <replace reference>

If we must use a multi-word, perhaps come up with a dashed form to
make it still a single token, i.e.

	'git replace' [-f] <object> <replace-reference>

otherwise it forces people to first think "ah, command reads from a
file (whose name can be 'replace'), and then..." and then backtrack
because the "reference>" part would not be syntactically correct.

You earlier mentioned that you copied the pattern from elsewhere.
These places may have to be updated, too.


>  'git replace' [-f] --edit <object>
>  'git replace' [-f] --graft <commit> [<parent>...]
>  'git replace' [-f] --convert-graft-file
> @@ -17,16 +17,16 @@ SYNOPSIS
>  
>  DESCRIPTION
>  -----------
> -Adds a 'replace' reference in `refs/replace/` namespace.
> +Adds a 'replace reference' in `refs/replace/` namespace.

And this part becomes 'replace-reference', too.

If we must invent and use such a new multi-word jargon, it probably
is a good idea to define it in Documentation/glossary-content.txt

Other than that, looking good.

Thanks.