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

[Felipe Contreras <felipe.contreras@gmail.com>]

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