Hello Ruben,
On 2024-02-17 15:58, Rubén Justo wrote:
On 16-feb-2024 04:32:10, Dragan Simic wrote:
Here's what I think the example from above should eventually look
like:
'git branch' (--set-upstream-to=<upstream> | -u <upstream>)
[<name>]
'git branch' --unset-upstream [<name>]
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.
Good point, ensuring such consistency would be really good.
I find it interesting to have common terms like "<commit>" "<path>",
"<envvar>"...
... or "<branch>". :)
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.
Agreed, consistency is good.
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@xxxxxxxxx/
After thinking a bit more about the whole thing, I think that using
"<branch>" instead of "<name>" or "<branchname>" would be our best
choice. It would be simple, direct and clear.
Regarding the branch copy and rename operations and their argument
names, perhaps the following would be a good choice:
--copy [<branch>] <destination>
--move [<branch>] <destination>
It would clearly reflect the nature of the performed operations, while
still using "<branch>" consistently, this time to refer to the source
branch. Using "<destination>" to select the destination name should
be pretty much self-descriptive, if you agree.
Of course, I'll get back to this later in this message.
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.
Perhaps. That should be another example of the long-term benefits
achieved through improved consistency.
'git branch' (-m | -M) [<old>] <new>
'git branch' (-c | -C) [<old>] <new>
'git branch' (-d | -D) [-r] <name>...
'git branch' --edit-description [<name>]
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>:
I agree after thinking about the whole thing a bit more.
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>
I'd say this solidifies "<branch>" as, hopefully, our best choice,
as already proposed above.
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.
I hope we'll eventually produce a great git-branch(1) man page together.
After that's completed, I have some more plans for improving git-branch,
by introducing some additional operations.
> We don't say that "--edit-description" defaults to the current branch;
> It is assumed. Perhaps we can take advantage of that assumption in
> -m|-c too.
We don't say that yet, :)
Yeah, but maybe we can do it without writing it down :)
Maybe, :) but again, spending a few additional words to describe that
might actually be beneficial. We'll see how it goes.
