diff mbox series

Re* [PATCH] doc: glossary: add entry for revision range

Message ID xmqqbl993irp.fsf@gitster.g (mailing list archive)
State New, archived
Headers show
Series Re* [PATCH] doc: glossary: add entry for revision range | expand

Commit Message

Junio C Hamano May 17, 2021, 7:46 a.m. UTC
Felipe Contreras <felipe.contreras@gmail.com> writes:

> Revision ranges are one of the most pervasive concepts in Git. It belongs
> in the glossary.
>
> Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
> ---
>  Documentation/glossary-content.txt | 4 ++++
>  1 file changed, 4 insertions(+)
>
> diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt
> index 67c7a50b96..31151277ba 100644
> --- a/Documentation/glossary-content.txt
> +++ b/Documentation/glossary-content.txt
> @@ -554,6 +554,10 @@ The most notable example is `HEAD`.
>  [[def_revision]]revision::
>  	Synonym for <<def_commit,commit>> (the noun).
>  
> +[[def_revision_range]]revision range::
> +        A syntax to specify a list of commits, usually indicating the starting
> +        and ending points. For example: `master..@`.

As there is no need to spell out HEAD, `master..` would be a better
example.  Especially since most people are downstream consumers, I'd
suggest using `origin..` or `@{u}..` here.  Either is in line with
the spirit of the example in the patch that asks "what did I do on
my own on this branch since I forked?".  Incidentally, it also
avoids fruitless arguments about what the name of the primary
integration branch ought to be.

Also "see the 'Specifying Ranges' and 'Revision Range Summary'
sections of linkgit:gitrevisions[7] for details" would be a helpful
addition to readers.  Since there are examples there, we may even be
able to drop "For example..." from here and have just refer the
readers to these sections.

By the way, this reminds of me one thing that seems to occasionally
confuse new people.  Most Git commands take a single range, even
though you can give multiple bottoms and tops.  This is because a
revision range is *not* just a random "list" of commits, but a single
connected set of commits, and to new people, the distinction between
them seems to be a bit unclear.

We may want to clarify with something like the following.

 Documentation/revisions.txt | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

Comments

Felipe Contreras May 17, 2021, 10:30 a.m. UTC | #1
Junio C Hamano wrote:
> Felipe Contreras <felipe.contreras@gmail.com> writes:
> 
> > Revision ranges are one of the most pervasive concepts in Git. It belongs
> > in the glossary.
> >
> > Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
> > ---
> >  Documentation/glossary-content.txt | 4 ++++
> >  1 file changed, 4 insertions(+)
> >
> > diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt
> > index 67c7a50b96..31151277ba 100644
> > --- a/Documentation/glossary-content.txt
> > +++ b/Documentation/glossary-content.txt
> > @@ -554,6 +554,10 @@ The most notable example is `HEAD`.
> >  [[def_revision]]revision::
> >  	Synonym for <<def_commit,commit>> (the noun).
> >  
> > +[[def_revision_range]]revision range::
> > +        A syntax to specify a list of commits, usually indicating the starting
> > +        and ending points. For example: `master..@`.
> 
> As there is no need to spell out HEAD, `master..` would be a better
> example.

I don't think so. The description said _starting_ and _ending_ points...
`master..` has no ending point.

If we must not use @, then I would rather use `master..mybranch`, or
something like that. HEAD seems like a technical accident. But of course
I would prefer HEAD to nothing, because at least it qualifies as an
ending point.

> Especially since most people are downstream consumers, I'd
> suggest using `origin..` or `@{u}..` here.

Nobody uses "origin" (what does that even mean?), and @{u} is way too
technical, and something not a lot of people know about (@{upstream}
would be a little less cryptic, but still suffer from the same
disadvantage).

> Either is in line with the spirit of the example in the patch that
> asks "what did I do on my own on this branch since I forked?".

No it wouldn't. I don't have an "origin" head in any of my repositories.

If you really don't want to give a real example (like `master..@`--which
I guarantee does work on 99% of your repositories), then we can go with
'start..end' (it would not work on any real scenario, but neither does
many of your suggestions).

> Incidentally, it also avoids fruitless arguments about what the name
> of the primary integration branch ought to be.

Anybody who wants to get into that first needs to address the issue
that:

  git -C Documentation grep '\bmaster\b' -- \
    SubmittingPatches '*.txt' ':!RelNotes/*'

Returns 799 matching lines (many with more than one instance).

So, if this patch makes it 800, I don't think it would be a significant
factor in transitioning the documentation away from "master" (when and
if that happens).

Today people use "master". When they don't, the glossary can be updated.
It takes a second (which is much less than the time we've spent talking
about it already).

> Also "see the 'Specifying Ranges' and 'Revision Range Summary'
> sections of linkgit:gitrevisions[7] for details" would be a helpful
> addition to readers.

> Since there are examples there, we may even be able to drop "For
> example..." from here and have just refer the readers to these
> sections.

I think we need both. Detailed explanations are good, but so is a
succinct example.

> By the way, this reminds of me one thing that seems to occasionally
> confuse new people.  Most Git commands take a single range, even
> though you can give multiple bottoms and tops.  This is because a
> revision range is *not* just a random "list" of commits, but a single
> connected set of commits, and to new people, the distinction between
> them seems to be a bit unclear.

Yeah, but at this point that's overcomplicating the issue.

For example, if you do master..feature-a, and master..feature-b that
technically can be considered a revision range", since it's something
accepted by `git log`, and `git log` accepts "revision ranges".

But anyone that understands English would say that's not a single
range, but two ranges.

So English and git are at odds in this instance.

I think a..b should be a revision range, and multiple of those could be
called a revision spec (or revspec for short). We have pathspecs, why
not revspecs?

Mercurial for example calls them revsets.

Either way. I'm trying to start from the lowest common denominator.

  1. Revision ranges do exist throughout the documentation
  2. `git log` accepts a revision range

So let's describe what a revision range is, in the simplest form.

The rest can be done later.

Cheers.
Jeff King May 17, 2021, 11:55 a.m. UTC | #2
On Mon, May 17, 2021 at 05:30:01AM -0500, Felipe Contreras wrote:

> > As there is no need to spell out HEAD, `master..` would be a better
> > example.
> 
> I don't think so. The description said _starting_ and _ending_ points...
> `master..` has no ending point.
> 
> If we must not use @, then I would rather use `master..mybranch`, or
> something like that. HEAD seems like a technical accident. But of course
> I would prefer HEAD to nothing, because at least it qualifies as an
> ending point.

I agree that if the purpose is to be illustrative, using shortcuts like
"an empty endpoint means HEAD" is not helpful. And likewise for "@"; if
you need to have "revision range" defined, there is a good chance that
you don't know about shortcuts like "@" either.

So I would prefer something more explicit (whether it's "mybranch" or
"end" or "HEAD" or whatever).

In a more fleshed-out description it might be nice to casually introduce
such shortcuts to let the user pick them up naturally, but in a
one-liner like a glossary entry, I think clarity is the most important
thing.

> > Especially since most people are downstream consumers, I'd
> > suggest using `origin..` or `@{u}..` here.
> 
> Nobody uses "origin" (what does that even mean?), [...]

I guess I'm "nobody" then, because I use it all the time.

The example in Documentation/rev-list-description.txt (which feeds into
the git-log and git-rev-list manpages) uses "origin..HEAD", as well.

IMHO it is a pretty reasonable example, but the examples in
gitrevisions(7) use made up "r1..r2", and that seems perfectly readable,
as well.

-Peff
Felipe Contreras May 17, 2021, 5:22 p.m. UTC | #3
Jeff King wrote:
> On Mon, May 17, 2021 at 05:30:01AM -0500, Felipe Contreras wrote:
> 
> > > As there is no need to spell out HEAD, `master..` would be a better
> > > example.
> > 
> > I don't think so. The description said _starting_ and _ending_ points...
> > `master..` has no ending point.
> > 
> > If we must not use @, then I would rather use `master..mybranch`, or
> > something like that. HEAD seems like a technical accident. But of course
> > I would prefer HEAD to nothing, because at least it qualifies as an
> > ending point.
> 
> I agree that if the purpose is to be illustrative, using shortcuts like
> "an empty endpoint means HEAD" is not helpful. And likewise for "@"; if
> you need to have "revision range" defined, there is a good chance that
> you don't know about shortcuts like "@" either.

But they don't need to know what @ means; it's clearly a shortcut for
_something_, and that's all they need to know. In fact, I'd say most
people can quickly realize what a shorcut for it is, which is why it was
picked by the git project, and many Mercurial projects as well.

Sure the same argument applies to HEAD too, but if we are going to pick
a placeholder for _something_ the user doesn't need to know about, then
@ is much simpler than HEAD.

We could do X too (typically used for _whatever_), but I'd argue @ is
much better than X because it actually works, and not just works, but
it's what the user most often would use.

> So I would prefer something more explicit (whether it's "mybranch" or
> "end" or "HEAD" or whatever).

I prefer something less explicit, because it's not relevant what X is,
just that it is an end point.

But if you feel strongly about it, "mybranch" it is.

Actually, I would prefer something more real, like "feature-x".

> In a more fleshed-out description it might be nice to casually introduce
> such shortcuts to let the user pick them up naturally, but in a
> one-liner like a glossary entry, I think clarity is the most important
> thing.

Indeed, but I find `master..@` is a perfectly clear example of a
revision range from something to something.

> > > Especially since most people are downstream consumers, I'd
> > > suggest using `origin..` or `@{u}..` here.
> > 
> > Nobody uses "origin" (what does that even mean?), [...]
> 
> I guess I'm "nobody" then, because I use it all the time.

Language is rarely 100% specific. By "nobody" of course I meant
"virtually nobody".

And yeah, I know you actually use "origin", because you do have correct
"origin/HEAD" for many of your repositories. I don't, and I'd argume
most users don't either.

It's right next in my to-do list to work on fetch.updateHead so I (and
many users) can join you in using "origin". But that's not the case
today.

> The example in Documentation/rev-list-description.txt (which feeds into
> the git-log and git-rev-list manpages) uses "origin..HEAD", as well.

I think it shouldn't, but that's a separate topic.

> IMHO it is a pretty reasonable example, but the examples in
> gitrevisions(7) use made up "r1..r2", and that seems perfectly readable,
> as well.

It is readable, sure, but it's not a real example. When picking an
example of English sentence with subject and predicate I'd pick "Mary
went to the moves" over "Subject predicate" in heartbeat.

An instance that doesn't come from the set of real commands is not
really an example to me.

Cheers.
Junio C Hamano May 17, 2021, 7:26 p.m. UTC | #4
Jeff King <peff@peff.net> writes:

> I agree that if the purpose is to be illustrative, using shortcuts like
> "an empty endpoint means HEAD" is not helpful. And likewise for "@"; if
> you need to have "revision range" defined, there is a good chance that
> you don't know about shortcuts like "@" either.
>
> So I would prefer something more explicit (whether it's "mybranch" or
> "end" or "HEAD" or whatever).

Perhaps.  Being illustrative for common use case is also important,
so I do not mind teaching "missing endpoint at either side defaults
to HEAD" early.

If "missing" endpoint is disturbing, the description can be fixed to
stress that they are "often but not always" given.

>> > Especially since most people are downstream consumers, I'd
>> > suggest using `origin..` or `@{u}..` here.
>> 
>> Nobody uses "origin" (what does that even mean?), [...]
>
> I guess I'm "nobody" then, because I use it all the time.

Oh, I'm nobody, too, and so are many others ;-)

> The example in Documentation/rev-list-description.txt (which feeds into
> the git-log and git-rev-list manpages) uses "origin..HEAD", as well.
>
> IMHO it is a pretty reasonable example, but the examples in
> gitrevisions(7) use made up "r1..r2", and that seems perfectly readable,
> as well.
>
> -Peff
Felipe Contreras May 17, 2021, 9:05 p.m. UTC | #5
Junio C Hamano wrote:
> Jeff King <peff@peff.net> writes:
> 
> > I agree that if the purpose is to be illustrative, using shortcuts like
> > "an empty endpoint means HEAD" is not helpful. And likewise for "@"; if
> > you need to have "revision range" defined, there is a good chance that
> > you don't know about shortcuts like "@" either.
> >
> > So I would prefer something more explicit (whether it's "mybranch" or
> > "end" or "HEAD" or whatever).
> 
> Perhaps.  Being illustrative for common use case is also important,
> so I do not mind teaching "missing endpoint at either side defaults
> to HEAD" early.

A glossary is not a place to teach (anything other than the definition).
It's supposed to contain glosses (brief explanations).

You don't find a complete recipe when you look for the definition of
"recpipe". That information belongs elsewhere.

> If "missing" endpoint is disturbing, the description can be fixed to
> stress that they are "often but not always" given.

This is unnecessary information.

If we teach that then we also have to teach that the starting point is
not always given either (`..mybranch`). And where does it end? We would
have to teach that `mybranch ^master` is yet another form of a revision
range, and so is -1.

That's what gitrevisions(7) is for.

> >> > Especially since most people are downstream consumers, I'd
> >> > suggest using `origin..` or `@{u}..` here.
> >> 
> >> Nobody uses "origin" (what does that even mean?), [...]
> >
> > I guess I'm "nobody" then, because I use it all the time.
> 
> Oh, I'm nobody, too, and so are many others ;-)

That depends on the definition of "many". My guess is that it's less
than 1% of users (probably 0.01%), and for me that's not many.

If you google for `git remote "set-head"` there's barely any
information. It's basically all online man pages.

I don't think anyone can argue it's not obscure.

Cheers.
Junio C Hamano May 18, 2021, 12:51 a.m. UTC | #6
Felipe Contreras <felipe.contreras@gmail.com> writes:

> Junio C Hamano wrote:
>> Jeff King <peff@peff.net> writes:
>> 
>> > I agree that if the purpose is to be illustrative, using shortcuts like
>> > "an empty endpoint means HEAD" is not helpful. And likewise for "@"; if
>> > you need to have "revision range" defined, there is a good chance that
>> > you don't know about shortcuts like "@" either.
>> >
>> > So I would prefer something more explicit (whether it's "mybranch" or
>> > "end" or "HEAD" or whatever).
>> 
>> Perhaps.  Being illustrative for common use case is also important,
>> so I do not mind teaching "missing endpoint at either side defaults
>> to HEAD" early.
>
> A glossary is not a place to teach (anything other than the definition).
> It's supposed to contain glosses (brief explanations).

Fair enough.  Then let's limit ourselves to the definition, but give
a correct one.  It is not "syntax" that the phrase "revision range"
refers to; it is what is specified by that syntax.

[[def_revision_range]]revision range::
        A set of connected commits to work on, usually specified by
        giving two end points, like `origin..mytopic`.  See the
        'Specifying Ranges' and 'Revision Range Summary' sections of
        linkgit:gitrevisions[7] for details.
Felipe Contreras May 18, 2021, 1:26 a.m. UTC | #7
Junio C Hamano wrote:
> Felipe Contreras <felipe.contreras@gmail.com> writes:
> > Junio C Hamano wrote:

> >> Perhaps.  Being illustrative for common use case is also important,
> >> so I do not mind teaching "missing endpoint at either side defaults
> >> to HEAD" early.
> >
> > A glossary is not a place to teach (anything other than the definition).
> > It's supposed to contain glosses (brief explanations).
> 
> Fair enough.  Then let's limit ourselves to the definition, but give
> a correct one.  It is not "syntax" that the phrase "revision range"
> refers to; it is what is specified by that syntax.

That's a distinction without a difference.

Like saying "Felipe is a person" is wrong, because "Felipe" is not a
person, but the _name_ of a person. This is excessive concern with minor
details to me.

In the minds of most people object identifiers are used interchangeably
with the object themselves: "Felipe" is a person, "master" is a branch, and
"master..@" is a revision range.

> [[def_revision_range]]revision range::
>         A set of connected commits to work on, usually specified by
>         giving two end points, like `origin..mytopic`.

endpoints.

As for the rest I already raised my concerns.

Cheers.
Jeff King May 18, 2021, 2:08 a.m. UTC | #8
On Mon, May 17, 2021 at 04:05:41PM -0500, Felipe Contreras wrote:

> > >> Nobody uses "origin" (what does that even mean?), [...]
> > >
> > > I guess I'm "nobody" then, because I use it all the time.
> > 
> > Oh, I'm nobody, too, and so are many others ;-)
> 
> That depends on the definition of "many". My guess is that it's less
> than 1% of users (probably 0.01%), and for me that's not many.
> 
> If you google for `git remote "set-head"` there's barely any
> information. It's basically all online man pages.

Why would people need to use "git remote set-head" most of the time? The
symlink is set up properly by git-clone, and has been for many years.
For most people, using "origin" just works (the exception is people who
"git init" and then "git remote add origin" themselves; since we're
guessing at numbers, I would guess that _that_ population is less than
1% of users).

-Peff
Junio C Hamano May 18, 2021, 2:57 a.m. UTC | #9
Jeff King <peff@peff.net> writes:

>> If you google for `git remote "set-head"` there's barely any
>> information. It's basically all online man pages.
>
> Why would people need to use "git remote set-head" most of the time?

I somehow thought Felipe wanted to say that there is nothing but
manual pages that mention the command and, "look how useful set-head
subcommand is, here is how you use it" blog posts are not seen
because nobody uses 'remote set-head'.

I do not quesiotn the frequency count of set-head, but I do not
think the lack of mention of set-head leads to the conclusion that
nobody uses "git log origin.."; there is a leap in logic.  As you
said below, "origin" is there without need for set-head, so the lack
of enthusiastic advocate for set-head does not mean anything wrt how
people find "origin" useful.

> The
> symlink is set up properly by git-clone, and has been for many years.
> For most people, using "origin" just works (the exception is people who
> "git init" and then "git remote add origin" themselves; since we're
> guessing at numbers, I would guess that _that_ population is less than
> 1% of users).
Felipe Contreras May 18, 2021, 5:02 a.m. UTC | #10
Jeff King wrote:
> On Mon, May 17, 2021 at 04:05:41PM -0500, Felipe Contreras wrote:
> 
> > > >> Nobody uses "origin" (what does that even mean?), [...]
> > > >
> > > > I guess I'm "nobody" then, because I use it all the time.
> > > 
> > > Oh, I'm nobody, too, and so are many others ;-)
> > 
> > That depends on the definition of "many". My guess is that it's less
> > than 1% of users (probably 0.01%), and for me that's not many.
> > 
> > If you google for `git remote "set-head"` there's barely any
> > information. It's basically all online man pages.
> 
> Why would people need to use "git remote set-head" most of the time? The
> symlink is set up properly by git-clone, and has been for many years.

First instructions from GitHub:

  echo "# test" >> README.md
  git init
  git add README.md
  git commit -m "first commit"
  git branch -M main
  git remote add origin git@github.com:felipec/test.git
  git push -u origin main

Second instructions from GitHub:

  git remote add origin git@github.com:felipec/test.git
  git branch -M main
  git push -u origin main

None of these use `git clone`.

Of 31 repositories I work on and have quickly at hand only 8 have
origin/HEAD.

> For most people, using "origin" just works (the exception is people who
> "git init" and then "git remote add origin" themselves; since we're
> guessing at numbers, I would guess that _that_ population is less than
> 1% of users).

On what do you base that guess?

The GitHub instructions don't use `git clone`. I can gather similar
instructions from other places if you are unconvinced.

I don't think most people set up their repositories as you think they
do.


And even *if* origin/HEAD did work on most repositories (hardly the
case), most people are not going to train their fingers to type `git cmd
$x` when the only $x where the command works is "origin"; they would
rather train their fingers to do $x/master which works on many more
repositories.

Cheers.
Felipe Contreras May 18, 2021, 5:20 a.m. UTC | #11
Junio C Hamano wrote:
> Jeff King <peff@peff.net> writes:
> 
> >> If you google for `git remote "set-head"` there's barely any
> >> information. It's basically all online man pages.
> >
> > Why would people need to use "git remote set-head" most of the time?
> 
> I somehow thought Felipe wanted to say that there is nothing but
> manual pages that mention the command and, "look how useful set-head
> subcommand is, here is how you use it" blog posts are not seen
> because nobody uses 'remote set-head'.
> 
> I do not quesiotn the frequency count of set-head, but I do not
> think the lack of mention of set-head leads to the conclusion that
> nobody uses "git log origin.."; there is a leap in logic.

I did not say that is the only evidence to lead to that conclusion.

But it is evidence.

> As you said below, "origin" is there without need for set-head,

Only sometimes.

> so the lack of enthusiastic advocate for set-head does not mean
> anything wrt how people find "origin" useful.

Yes it does. Contrary to popular belief absence of evidence can be
evidence of absence. If I walk around Central Park for half an hour and
I don't see any elephants, that's evidence that there are no elephants
in Central Park at this very moment. It is not *conclusive* evidence,
but it is evidence.

Just because the evidence for $x is not sufficient to prove $x doesn't
mean there is no evidence for $x.
Jeff King May 18, 2021, 6:55 a.m. UTC | #12
On Tue, May 18, 2021 at 12:02:46AM -0500, Felipe Contreras wrote:

> > Why would people need to use "git remote set-head" most of the time? The
> > symlink is set up properly by git-clone, and has been for many years.
> 
> First instructions from GitHub:
> 
>   echo "# test" >> README.md
>   git init
>   git add README.md
>   git commit -m "first commit"
>   git branch -M main
>   git remote add origin git@github.com:felipec/test.git
>   git push -u origin main
> 
> Second instructions from GitHub:
> 
>   git remote add origin git@github.com:felipec/test.git
>   git branch -M main
>   git push -u origin main
> 
> None of these use `git clone`.

So? Here are some other instructions from GitHub[0]:

  Type git clone, and then paste the URL you copied earlier.

    $ git clone https://github.com/YOUR-USERNAME/YOUR-REPOSITORY

[0] https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/cloning-a-repository

Not to mention that every single repository page mentions cloning under
the "Code" button (including the command-line "gh repo clone" if you are
using their recommended tool).

People clone a lot more than they create new repositories.

> Of 31 repositories I work on and have quickly at hand only 8 have
> origin/HEAD.

And of 141 repositories I have on my workstation, 137 have origin/HEAD
(and of the 4 without, one does not even have a remote at all, and one
is a git-svn repository).

I don't think that proves anything except that your workflow is
different than mine. But I contend that most people get repositories by
cloning them.

> And even *if* origin/HEAD did work on most repositories (hardly the
> case), most people are not going to train their fingers to type `git cmd
> $x` when the only $x where the command works is "origin"; they would
> rather train their fingers to do $x/master which works on many more
> repositories.

I guess I'm not most people, because I sure have enjoyed typing the
shorter thing all these years.

Look, I get that you didn't know or care about the "origin/HEAD" feature
until recently. But it's been part of Git for over 15 years, and has
been used as the documentation examples for revision ranges in both
git-rev-list(1) and gitrevisions(7), as well as the user-manual.

I'm perfectly happy to use placeholder ref names in the glossary
documentation, but it's not like the use of "origin" as a name is some
obscure secret.

-Peff
Jeff King May 18, 2021, 6:59 a.m. UTC | #13
On Mon, May 17, 2021 at 12:22:56PM -0500, Felipe Contreras wrote:

> > > If we must not use @, then I would rather use `master..mybranch`, or
> > > something like that. HEAD seems like a technical accident. But of course
> > > I would prefer HEAD to nothing, because at least it qualifies as an
> > > ending point.
> > 
> > I agree that if the purpose is to be illustrative, using shortcuts like
> > "an empty endpoint means HEAD" is not helpful. And likewise for "@"; if
> > you need to have "revision range" defined, there is a good chance that
> > you don't know about shortcuts like "@" either.
> 
> But they don't need to know what @ means; it's clearly a shortcut for
> _something_, and that's all they need to know. In fact, I'd say most
> people can quickly realize what a shorcut for it is, which is why it was
> picked by the git project, and many Mercurial projects as well.

That's my point. It _isn't_ clearly a shortcut for something for all
people. If you are reading the glossary entry for "revision range", you
might not know about the ".." syntax at all. So what does:

  foo..@

mean? Does it parse as three (foo, .., @) or is "..@" a special symbol?

I expect most people would figure it out. But if your point is to serve
as documentation, especially for people who do not yet know all of the
concepts, then why not try to reduce the chance of error as much as
possible?

> Actually, I would prefer something more real, like "feature-x".

Sure, that is fine with me.

-Peff
Felipe Contreras May 18, 2021, 11:42 a.m. UTC | #14
Jeff King wrote:
> On Tue, May 18, 2021 at 12:02:46AM -0500, Felipe Contreras wrote:
> 
> > > Why would people need to use "git remote set-head" most of the time? The
> > > symlink is set up properly by git-clone, and has been for many years.
> > 
> > First instructions from GitHub:
> > 
> >   echo "# test" >> README.md
> >   git init
> >   git add README.md
> >   git commit -m "first commit"
> >   git branch -M main
> >   git remote add origin git@github.com:felipec/test.git
> >   git push -u origin main
> > 
> > Second instructions from GitHub:
> > 
> >   git remote add origin git@github.com:felipec/test.git
> >   git branch -M main
> >   git push -u origin main
> > 
> > None of these use `git clone`.
> 
> So? Here are some other instructions from GitHub[0]:
> 
>   Type git clone, and then paste the URL you copied earlier.
> 
>     $ git clone https://github.com/YOUR-USERNAME/YOUR-REPOSITORY
> 
> [0] https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/cloning-a-repository

A random github.com link doesn't show anything. The instructions I'm
talking about are the **first** thing the site gives to users.

On the other hand let's see how we get to your link.

 1. Click "New"
 2. Type "Repository Name"
 3. Click "Create repository"
 4. Ignore the entire setup page (with the `git remote add` commands)
 5. Click on your profile icon
 6. Select "Help"
 7. Go to the GitHub.com submenu
 8. Ignore the Quickstart
   8.1. Ignore the Git cheatsheet
     8.1.1. Ignore the `git remote add` part of the cheatsheet that
            comes before the `git clone` part
 9. Ignore Getting started with Git
   9.1. Ignore About remote repositories
     9.1.1 Ignore the section Creating remote repositories which does
           `git remote add` before it mentions `git clone`
   9.2. Ignore Managing remote repositories (talks about `git remote
        add`)
 10. Select Creating, cloning, and archiving repositories
 11. Select Cloning a repository

Finally we reach that link.

To reach that link we need to ignore **all** the tips GitHub gives, and
directly click on a sbusbusection called "Cloning a repository", which
is part of a subsection "Creating, cloning, and archiving repositories"
which is part of the section GitHub.com, which is part of the help.

I seriously dobut this is one of the first things any user sees.

> Not to mention that every single repository page mentions cloning under
> the "Code" button (including the command-line "gh repo clone" if you are
> using their recommended tool).
> 
> People clone a lot more than they create new repositories.

Depends what you call "people". If you are talking about professional
software developers, then maybe.

But they are not the only users of git.

Do you have any stats?

> > Of 31 repositories I work on and have quickly at hand only 8 have
> > origin/HEAD.
> 
> And of 141 repositories I have on my workstation, 137 have origin/HEAD
> (and of the 4 without, one does not even have a remote at all, and one
> is a git-svn repository).
> 
> I don't think that proves anything except that your workflow is
> different than mine.

Exactly, and we cannot assume most people follow your workflow. In fact,
I'd say your workflow is probably one of the most atypical in the world.
You know tricks 99.99% of users don't know about, in fact that probably
99% of git.git developers don't know.

It is sufficient to acknowledge that there are different workflows.

> > And even *if* origin/HEAD did work on most repositories (hardly the
> > case), most people are not going to train their fingers to type `git cmd
> > $x` when the only $x where the command works is "origin"; they would
> > rather train their fingers to do $x/master which works on many more
> > repositories.
> 
> I guess I'm not most people, because I sure have enjoyed typing the
> shorter thing all these years.

You are not part of that subset.

I'm talking about people that do have "origin/HEAD", but *don't* have
any other "$remote/HEAD".

Do you have a HEAD configured for most of your remotes?

> Look, I get that you didn't know or care about the "origin/HEAD" feature
> until recently. But it's been part of Git for over 15 years, and has
> been used as the documentation examples for revision ranges in both
> git-rev-list(1) and gitrevisions(7), as well as the user-manual.

The fact that something is part of the documentation doesn't mean it is
well-known.

The `git remote add -m` option has been documented since 2007, and you
yourself didn't know about it. If you google for that you find nothing.
There's only 1. a qustion on Stack Overflow with zero votes, and 2. the
mail I send you about it. That's it.

Do you agree that `git remote add -m` is obscure?

If so, why is it different from origin/HEAD?

I decided to skim through the entire Pro Git book to see if I could find
any instance in which they use this shortcut... I found **zero**.

If a user can read the most well-known book about git that had hundreds
of contributors without finding a single instance of this shortcut...
How common do you really think it is?

In, fact, I found an interesting quote: "The git rerere functionality is
a bit of a hidden feature." If rerere is a "hidden feature" then what
what is origin/HEAD?

> I'm perfectly happy to use placeholder ref names in the glossary
> documentation, but it's not like the use of "origin" as a name is some
> obscure secret.

It's easier to flip the problem around: if origin/HEAD is well-known,
what would we *not* expect to find?

Is there anything that would falsify the premise?

Cheers.
Felipe Contreras May 18, 2021, 12:28 p.m. UTC | #15
Jeff King wrote:
> On Mon, May 17, 2021 at 12:22:56PM -0500, Felipe Contreras wrote:
> 
> > > > If we must not use @, then I would rather use `master..mybranch`, or
> > > > something like that. HEAD seems like a technical accident. But of course
> > > > I would prefer HEAD to nothing, because at least it qualifies as an
> > > > ending point.
> > > 
> > > I agree that if the purpose is to be illustrative, using shortcuts like
> > > "an empty endpoint means HEAD" is not helpful. And likewise for "@"; if
> > > you need to have "revision range" defined, there is a good chance that
> > > you don't know about shortcuts like "@" either.
> > 
> > But they don't need to know what @ means; it's clearly a shortcut for
> > _something_, and that's all they need to know. In fact, I'd say most
> > people can quickly realize what a shorcut for it is, which is why it was
> > picked by the git project, and many Mercurial projects as well.
> 
> That's my point. It _isn't_ clearly a shortcut for something for all
> people. If you are reading the glossary entry for "revision range", you
> might not know about the ".." syntax at all. So what does:
> 
>   foo..@
> 
> mean?

An ellipsis is a common feature of both human and computer languages...

  The ... fox jumps ...

Is easily understood by most English speakers, so is a, b, c ... z.

It is used in math as well 1, 2, 3,..., 100.

It's used in computer languages, like Pascal, Modula, Oberon, Ada,
Haskell, Perl, Ruby, Swift, Kotlin, F#, and MATLAB.

  (1..10).each { |i| puts i }

I think most readers would infer that a) the starting point is at the
left of the ending point b) there's nothing after the ending point.

So what could the thing at the right of the starting point, follwing an
ellipsis, and not followed by anything else be? I think most people
would get it.

> I expect most people would figure it out. But if your point is to serve
> as documentation, especially for people who do not yet know all of the
> concepts, then why not try to reduce the chance of error as much as
> possible?

We want to minimize the chances of error... up to a point. We also want
to be useful.

Moreover, most readers don't learn at the speed they read, it takes
time, and often practice. Copy-pasting `master..@` to their terminal
will most likely work, and with any luck they'll understand it right
away.

They don't need to understand revision ranges completely when they read
the glossary, they just need a brief explanation.

[1] https://en.wikipedia.org/wiki/Ellipsis
Jeff King May 18, 2021, 12:47 p.m. UTC | #16
On Tue, May 18, 2021 at 06:42:00AM -0500, Felipe Contreras wrote:

> A random github.com link doesn't show anything. The instructions I'm
> talking about are the **first** thing the site gives to users.

I would think the first thing most users see is _somebody else's
repository_, full of commits, that they then clone.

> > People clone a lot more than they create new repositories.
> 
> Depends what you call "people". If you are talking about professional
> software developers, then maybe.
> 
> But they are not the only users of git.
> 
> Do you have any stats?

On one of GitHub's servers (selected randomly), there were ~300k clones
in the past 24 hours. In the same time period on the same server, there
were 1780 new repos. Even that's overstating it, since some portion of
those are just forks of existing repos (so the user probably either
cloned their fork immediately, or was already working on a clone of the
upstream fork, rather than having run "git init" locally).

> > I don't think that proves anything except that your workflow is
> > different than mine.
> 
> Exactly, and we cannot assume most people follow your workflow. In fact,
> I'd say your workflow is probably one of the most atypical in the world.
> You know tricks 99.99% of users don't know about, in fact that probably
> 99% of git.git developers don't know.
> 
> It is sufficient to acknowledge that there are different workflows.

I'm not making some bizarre claim about workflows. I'm saying that
people commonly use "git clone" to get repositories. That really doesn't
seem controversial.

But you know what, I've wasted enough time on this thread. If you want
to believe that people don't use "git clone", go for it.

-Peff
Felipe Contreras May 18, 2021, 9:09 p.m. UTC | #17
Jeff King wrote:
> On Tue, May 18, 2021 at 06:42:00AM -0500, Felipe Contreras wrote:
> 
> > A random github.com link doesn't show anything. The instructions I'm
> > talking about are the **first** thing the site gives to users.
> 
> I would think the first thing most users see is _somebody else's
> repository_, full of commits, that they then clone.

All the tutorials I've seen start with `git init`. If you want to learn
git starting from a monstrous repository such as Chrome OS is probably
not a good idea.

And yeah, if you assume most users are professional programmers, then
yeah, that's probably true. But that's an assumption.

Many users are students, others are amateur programmers, others might
be using git to track something other than code, like writing a book, or
their dotfiles.

Experts often forget what it is to be a beginner.

> > > People clone a lot more than they create new repositories.
> > 
> > Depends what you call "people". If you are talking about professional
> > software developers, then maybe.
> > 
> > But they are not the only users of git.
> > 
> > Do you have any stats?
> 
> On one of GitHub's servers (selected randomly), there were ~300k clones
> in the past 24 hours. In the same time period on the same server, there
> were 1780 new repos. Even that's overstating it, since some portion of
> those are just forks of existing repos (so the user probably either
> cloned their fork immediately, or was already working on a clone of the
> upstream fork, rather than having run "git init" locally).

How do you distinguish a git clone from a git init + git remote add + git
fetch?

> > > I don't think that proves anything except that your workflow is
> > > different than mine.
> > 
> > Exactly, and we cannot assume most people follow your workflow. In fact,
> > I'd say your workflow is probably one of the most atypical in the world.
> > You know tricks 99.99% of users don't know about, in fact that probably
> > 99% of git.git developers don't know.
> > 
> > It is sufficient to acknowledge that there are different workflows.
> 
> I'm not making some bizarre claim about workflows. I'm saying that
> people commonly use "git clone" to get repositories. That really doesn't
> seem controversial.

It's not controversial, but it's also not necessarily true.

On what are you basing that claim?

> But you know what, I've wasted enough time on this thread. If you want
> to believe that people don't use "git clone", go for it.

I'll parse that as an answer to my quesion:

> > Is there anything that would falsify the premise?

"No, there's absolutely nothing that would falsify my premise".

If there's no way to falsify a claim, then there is no point in even
entertaining that claim.

Cheers.
diff mbox series

Patch

diff --git c/Documentation/revisions.txt w/Documentation/revisions.txt
index d9169c062e..2b7d8e3745 100644
--- c/Documentation/revisions.txt
+++ w/Documentation/revisions.txt
@@ -260,6 +260,9 @@  any of the given commits.
 A commit's reachable set is the commit itself and the commits in
 its ancestry chain.
 
+There are several notations to specify a set of connected commits
+(called a "revision range"), illustrated below.
+
 
 Commit Exclusions
 ~~~~~~~~~~~~~~~~~
@@ -294,6 +297,20 @@  is a shorthand for 'HEAD..origin' and asks "What did the origin do since
 I forked from them?"  Note that '..' would mean 'HEAD..HEAD' which is an
 empty range that is both reachable and unreachable from HEAD.
 
+Commands that are specifically designed to take two distinct ranges
+(e.g. "git range-diff R1 R2" to compare two ranges) do exist, but
+they are exceptions.  Unless otherwise noted, all "git" commands
+that operate on set of commits work on a single revision range.  In
+other words, giving two dotted ranges next to each other, e.g.
+
+    $ git log 'r1..r2' 'r3..r4'
+
+does *not* specify two revision ranges for most commands.  Instead
+it will name a single connected set of commits, i.e. those that are
+reachable from either r2 or r4 but are reachable from neither r1 or
+r3.
+
+
 Other <rev>{caret} Parent Shorthand Notations
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Three other shorthands exist, particularly useful for merge commits,