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

Jeff King wrote:

On Tue, May 18, 2021 at 12:02:46AM -0500, Felipe Contreras wrote:

quoted

quoted

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?

quoted

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.

quoted

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