| 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 |
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.
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
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.
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
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.
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.
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.
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
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).
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.
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.
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
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
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.
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
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
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 --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,