Re: [PATCH] branch: rework the descriptions of rename and copy operations

On 16-feb-2024 04:32:10, Dragan Simic wrote:

Well, my point was not about new terms in this series, but to see if the idea of reusing an existing one might be of interest.

I find it interesting to have common terms like "<commit>" "<path>", "<envvar>"...

This builds intuition in the user, making it easier to grasp the meaning of a term, which refers to a similar /thing/, regardless of being used in different contexts. And in turn, it can also help to better understand the context.

     Side note:  My gut tells me that my patch 5aea3955bc (branch:
     clarify <oldbranch> term, 2024-01-06) which was originated by a
     report [1] of a user who found the documentation confusing, would
     have been less likely to happen (the report and consequently my
     patch) if "<branchname>" had been used instead of "<oldbranch>" in
     the documentation.  Not because "<branchname>" is a better name,
     but because it is already being used in other commands with a
     clearer meaning of: "if not specified it defaults to the current
     branch".  And because of that a user might have be able to fill the
     gaps in -m|-c.  Of course this is based on my intuition, which I
     know is seriously biased.

     [1] https://lore.kernel.org/git/pull.1613.git.git.1701303891791.gitgitgadget@gmail.com/

And not only can it be of help to the user, but also to developers (or reviewers) when documenting new commands or options; because there is no need to search for a, maybe new, name if there is one that is consolidated.

Perhaps, less names can also improve the lives of translators by making it easier to reuse some of the translations.

As I write, I realise that all this probably belongs to CodingGuideLines or similar. Or maybe it is too academic to be practical. I Dunno.

So, to your proposal: it does not make things worse, and it reuses terms that are already used elsewhere:

	$ for a in '<new>' '<old>' '<name>'; do echo $a $(git grep --no-line-number -E "$a" v2.44.0-rc1 -- Documentation/git-*.txt | wc -l); done
	<new> 7
	<old> 7
	<name> 147

But based on the idea I've just described, IMHO the user might not easily find the similarities in <old> with <name>:

At least, not better than with <oldbranch> and <branchname>.

And it won't be easy either with <name> and other man pages. For example we have:

	$ git grep -E 'git checkout.*(new-)?branch' Documentation/git-checkout.txt
	Documentation/git-checkout.txt:'git checkout' [-q] [-f] [-m] [<branch>]
	Documentation/git-checkout.txt:'git checkout' [-q] [-f] [-m] --detach [<branch>]
	Documentation/git-checkout.txt:'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new-branch>] [<start-point>]
	Documentation/git-checkout.txt:'git checkout' [<branch>]::
	Documentation/git-checkout.txt:$ git checkout -b <branch> --track <remote>/<branch>
	Documentation/git-checkout.txt:'git checkout' -b|-B <new-branch> [<start-point>]::
	Documentation/git-checkout.txt:$ git checkout <branch>
	Documentation/git-checkout.txt:'git checkout' --detach [<branch>]::
	Documentation/git-checkout.txt:     "git branch" with "-f" followed by "git checkout" of that branch;
	Documentation/git-checkout.txt:$ git checkout -b <branch> --track <remote>/<branch>

On the names chosen, the risk of bikesheeding is high and there is nothing wrong here, so it is way better to let you work. You have taken the initiative from Junios's response to my patch, so thank you for that.

Yeah, but maybe we can do it without writing it down :)