{"thread":{"id":"55703","subject":"[PATCH] doc: glossary: add entry for revision range","startedAt":"2021-05-16T20:38:28Z","lastAt":"2021-05-18T21:10:08Z","messageCount":19,"participants":["Felipe Contreras","Junio C Hamano","Jeff King"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"424689","messageId":"20210516203736.1098072-1-felipe.contreras@gmail.com","threadId":"55703","inReplyTo":null,"subject":"[PATCH] doc: glossary: add entry for revision range","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-16T20:37:36Z","receivedAt":"2021-05-16T20:38:28Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Revision ranges are one of the most pervasive concepts in Git. It belongs\nin the glossary.\n\nSigned-off-by: Felipe Contreras \n---\n Documentation/glossary-content.txt | 4 ++++\n 1 file changed, 4 insertions(+)\n\ndiff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt\nindex 67c7a50b96..31151277ba 100644\n--- a/Documentation/glossary-content.txt\n+++ b/Documentation/glossary-content.txt\n@@ -554,6 +554,10 @@ The most notable example is `HEAD`.\n [[def_revision]]revision::\n \tSynonym for <> (the noun).\n \n+[[def_revision_range]]revision range::\n+ A syntax to specify a list of commits, usually indicating the starting\n+ and ending points. For example: `master..@`.\n+\n [[def_rewind]]rewind::\n \tTo throw away part of the development, i.e. to assign the\n \t<> to an earlier <>.\n-- \n2.31.1\n\n"},{"id":"424710","messageId":"xmqqbl993irp.fsf@gitster.g","threadId":"55703","inReplyTo":"20210516203736.1098072-1-felipe.contreras@gmail.com","subject":"Re* [PATCH] doc: glossary: add entry for revision range","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-05-17T07:46:02Z","receivedAt":"2021-05-17T07:46:08Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Felipe Contreras writes:\n\n> Revision ranges are one of the most pervasive concepts in Git. It belongs\n> in the glossary.\n>\n> Signed-off-by: Felipe Contreras \n> ---\n> Documentation/glossary-content.txt | 4 ++++\n> 1 file changed, 4 insertions(+)\n>\n> diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt\n> index 67c7a50b96..31151277ba 100644\n> --- a/Documentation/glossary-content.txt\n> +++ b/Documentation/glossary-content.txt\n> @@ -554,6 +554,10 @@ The most notable example is `HEAD`.\n> [[def_revision]]revision::\n> \tSynonym for <> (the noun).\n> \n> +[[def_revision_range]]revision range::\n> + A syntax to specify a list of commits, usually indicating the starting\n> + and ending points. For example: `master..@`.\n\nAs there is no need to spell out HEAD, `master..` would be a better\nexample. Especially since most people are downstream consumers, I'd\nsuggest using `origin..` or `@{u}..` here. Either is in line with\nthe spirit of the example in the patch that asks \"what did I do on\nmy own on this branch since I forked?\". Incidentally, it also\navoids fruitless arguments about what the name of the primary\nintegration branch ought to be.\n\nAlso \"see the 'Specifying Ranges' and 'Revision Range Summary'\nsections of linkgit:gitrevisions[7] for details\" would be a helpful\naddition to readers. Since there are examples there, we may even be\nable to drop \"For example...\" from here and have just refer the\nreaders to these sections.\n\nBy the way, this reminds of me one thing that seems to occasionally\nconfuse new people. Most Git commands take a single range, even\nthough you can give multiple bottoms and tops. This is because a\nrevision range is *not* just a random \"list\" of commits, but a single\nconnected set of commits, and to new people, the distinction between\nthem seems to be a bit unclear.\n\nWe may want to clarify with something like the following.\n\n Documentation/revisions.txt | 17 +++++++++++++++++\n 1 file changed, 17 insertions(+)\n\ndiff --git c/Documentation/revisions.txt w/Documentation/revisions.txt\nindex d9169c062e..2b7d8e3745 100644\n--- c/Documentation/revisions.txt\n+++ w/Documentation/revisions.txt\n@@ -260,6 +260,9 @@ any of the given commits.\n A commit's reachable set is the commit itself and the commits in\n its ancestry chain.\n \n+There are several notations to specify a set of connected commits\n+(called a \"revision range\"), illustrated below.\n+\n \n Commit Exclusions\n ~~~~~~~~~~~~~~~~~\n@@ -294,6 +297,20 @@ is a shorthand for 'HEAD..origin' and asks \"What did the origin do since\n I forked from them?\" Note that '..' would mean 'HEAD..HEAD' which is an\n empty range that is both reachable and unreachable from HEAD.\n \n+Commands that are specifically designed to take two distinct ranges\n+(e.g. \"git range-diff R1 R2\" to compare two ranges) do exist, but\n+they are exceptions. Unless otherwise noted, all \"git\" commands\n+that operate on set of commits work on a single revision range. In\n+other words, giving two dotted ranges next to each other, e.g.\n+\n+ $ git log 'r1..r2' 'r3..r4'\n+\n+does *not* specify two revision ranges for most commands. Instead\n+it will name a single connected set of commits, i.e. those that are\n+reachable from either r2 or r4 but are reachable from neither r1 or\n+r3.\n+\n+\n Other {caret} Parent Shorthand Notations\n ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n Three other shorthands exist, particularly useful for merge commits,\n"},{"id":"424721","messageId":"60a245a927c62_126333208ea@natae.notmuch","threadId":"55703","inReplyTo":"xmqqbl993irp.fsf@gitster.g","subject":"RE: Re* [PATCH] doc: glossary: add entry for revision range","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-17T10:30:01Z","receivedAt":"2021-05-17T10:30:06Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Junio C Hamano wrote:\n> Felipe Contreras writes:\n> \n> > Revision ranges are one of the most pervasive concepts in Git. It belongs\n> > in the glossary.\n> >\n> > Signed-off-by: Felipe Contreras \n> > ---\n> > Documentation/glossary-content.txt | 4 ++++\n> > 1 file changed, 4 insertions(+)\n> >\n> > diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt\n> > index 67c7a50b96..31151277ba 100644\n> > --- a/Documentation/glossary-content.txt\n> > +++ b/Documentation/glossary-content.txt\n> > @@ -554,6 +554,10 @@ The most notable example is `HEAD`.\n> > [[def_revision]]revision::\n> > \tSynonym for <> (the noun).\n> > \n> > +[[def_revision_range]]revision range::\n> > + A syntax to specify a list of commits, usually indicating the starting\n> > + and ending points. For example: `master..@`.\n> \n> As there is no need to spell out HEAD, `master..` would be a better\n> example.\n\nI don't think so. The description said _starting_ and _ending_ points...\n`master..` has no ending point.\n\nIf we must not use @, then I would rather use `master..mybranch`, or\nsomething like that. HEAD seems like a technical accident. But of course\nI would prefer HEAD to nothing, because at least it qualifies as an\nending point.\n\n> Especially since most people are downstream consumers, I'd\n> suggest using `origin..` or `@{u}..` here.\n\nNobody uses \"origin\" (what does that even mean?), and @{u} is way too\ntechnical, and something not a lot of people know about (@{upstream}\nwould be a little less cryptic, but still suffer from the same\ndisadvantage).\n\n> Either is in line with the spirit of the example in the patch that\n> asks \"what did I do on my own on this branch since I forked?\".\n\nNo it wouldn't. I don't have an \"origin\" head in any of my repositories.\n\nIf you really don't want to give a real example (like `master..@`--which\nI guarantee does work on 99% of your repositories), then we can go with\n'start..end' (it would not work on any real scenario, but neither does\nmany of your suggestions).\n\n> Incidentally, it also avoids fruitless arguments about what the name\n> of the primary integration branch ought to be.\n\nAnybody who wants to get into that first needs to address the issue\nthat:\n\n git -C Documentation grep '\\bmaster\\b' -- \\\n SubmittingPatches '*.txt' ':!RelNotes/*'\n\nReturns 799 matching lines (many with more than one instance).\n\nSo, if this patch makes it 800, I don't think it would be a significant\nfactor in transitioning the documentation away from \"master\" (when and\nif that happens).\n\nToday people use \"master\". When they don't, the glossary can be updated.\nIt takes a second (which is much less than the time we've spent talking\nabout it already).\n\n> Also \"see the 'Specifying Ranges' and 'Revision Range Summary'\n> sections of linkgit:gitrevisions[7] for details\" would be a helpful\n> addition to readers.\n\n> Since there are examples there, we may even be able to drop \"For\n> example...\" from here and have just refer the readers to these\n> sections.\n\nI think we need both. Detailed explanations are good, but so is a\nsuccinct example.\n\n> By the way, this reminds of me one thing that seems to occasionally\n> confuse new people. Most Git commands take a single range, even\n> though you can give multiple bottoms and tops. This is because a\n> revision range is *not* just a random \"list\" of commits, but a single\n> connected set of commits, and to new people, the distinction between\n> them seems to be a bit unclear.\n\nYeah, but at this point that's overcomplicating the issue.\n\nFor example, if you do master..feature-a, and master..feature-b that\ntechnically can be considered a revision range\", since it's something\naccepted by `git log`, and `git log` accepts \"revision ranges\".\n\nBut anyone that understands English would say that's not a single\nrange, but two ranges.\n\nSo English and git are at odds in this instance.\n\nI think a..b should be a revision range, and multiple of those could be\ncalled a revision spec (or revspec for short). We have pathspecs, why\nnot revspecs?\n\nMercurial for example calls them revsets.\n\nEither way. I'm trying to start from the lowest common denominator.\n\n 1. Revision ranges do exist throughout the documentation\n 2. `git log` accepts a revision range\n\nSo let's describe what a revision range is, in the simplest form.\n\nThe rest can be done later.\n\nCheers.\n\n-- \nFelipe Contreras\n"},{"id":"424726","messageId":"YKJZt4vFECoLZhc2@coredump.intra.peff.net","threadId":"55703","inReplyTo":"60a245a927c62_126333208ea@natae.notmuch","subject":"Re: Re* [PATCH] doc: glossary: add entry for revision range","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2021-05-17T11:55:35Z","receivedAt":"2021-05-17T11:55:38Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Mon, May 17, 2021 at 05:30:01AM -0500, Felipe Contreras wrote:\n\n> > As there is no need to spell out HEAD, `master..` would be a better\n> > example.\n> \n> I don't think so. The description said _starting_ and _ending_ points...\n> `master..` has no ending point.\n> \n> If we must not use @, then I would rather use `master..mybranch`, or\n> something like that. HEAD seems like a technical accident. But of course\n> I would prefer HEAD to nothing, because at least it qualifies as an\n> ending point.\n\nI agree that if the purpose is to be illustrative, using shortcuts like\n\"an empty endpoint means HEAD\" is not helpful. And likewise for \"@\"; if\nyou need to have \"revision range\" defined, there is a good chance that\nyou don't know about shortcuts like \"@\" either.\n\nSo I would prefer something more explicit (whether it's \"mybranch\" or\n\"end\" or \"HEAD\" or whatever).\n\nIn a more fleshed-out description it might be nice to casually introduce\nsuch shortcuts to let the user pick them up naturally, but in a\none-liner like a glossary entry, I think clarity is the most important\nthing.\n\n> > Especially since most people are downstream consumers, I'd\n> > suggest using `origin..` or `@{u}..` here.\n> \n> Nobody uses \"origin\" (what does that even mean?), [...]\n\nI guess I'm \"nobody\" then, because I use it all the time.\n\nThe example in Documentation/rev-list-description.txt (which feeds into\nthe git-log and git-rev-list manpages) uses \"origin..HEAD\", as well.\n\nIMHO it is a pretty reasonable example, but the examples in\ngitrevisions(7) use made up \"r1..r2\", and that seems perfectly readable,\nas well.\n\n-Peff\n"},{"id":"424769","messageId":"60a2a670648b1_12801e20895@natae.notmuch","threadId":"55703","inReplyTo":"YKJZt4vFECoLZhc2@coredump.intra.peff.net","subject":"Re: Re* [PATCH] doc: glossary: add entry for revision range","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-17T17:22:56Z","receivedAt":"2021-05-17T17:23:01Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Jeff King wrote:\n> On Mon, May 17, 2021 at 05:30:01AM -0500, Felipe Contreras wrote:\n> \n> > > As there is no need to spell out HEAD, `master..` would be a better\n> > > example.\n> > \n> > I don't think so. The description said _starting_ and _ending_ points...\n> > `master..` has no ending point.\n> > \n> > If we must not use @, then I would rather use `master..mybranch`, or\n> > something like that. HEAD seems like a technical accident. But of course\n> > I would prefer HEAD to nothing, because at least it qualifies as an\n> > ending point.\n> \n> I agree that if the purpose is to be illustrative, using shortcuts like\n> \"an empty endpoint means HEAD\" is not helpful. And likewise for \"@\"; if\n> you need to have \"revision range\" defined, there is a good chance that\n> you don't know about shortcuts like \"@\" either.\n\nBut they don't need to know what @ means; it's clearly a shortcut for\n_something_, and that's all they need to know. In fact, I'd say most\npeople can quickly realize what a shorcut for it is, which is why it was\npicked by the git project, and many Mercurial projects as well.\n\nSure the same argument applies to HEAD too, but if we are going to pick\na placeholder for _something_ the user doesn't need to know about, then\n@ is much simpler than HEAD.\n\nWe could do X too (typically used for _whatever_), but I'd argue @ is\nmuch better than X because it actually works, and not just works, but\nit's what the user most often would use.\n\n> So I would prefer something more explicit (whether it's \"mybranch\" or\n> \"end\" or \"HEAD\" or whatever).\n\nI prefer something less explicit, because it's not relevant what X is,\njust that it is an end point.\n\nBut if you feel strongly about it, \"mybranch\" it is.\n\nActually, I would prefer something more real, like \"feature-x\".\n\n> In a more fleshed-out description it might be nice to casually introduce\n> such shortcuts to let the user pick them up naturally, but in a\n> one-liner like a glossary entry, I think clarity is the most important\n> thing.\n\nIndeed, but I find `master..@` is a perfectly clear example of a\nrevision range from something to something.\n\n> > > Especially since most people are downstream consumers, I'd\n> > > suggest using `origin..` or `@{u}..` here.\n> > \n> > Nobody uses \"origin\" (what does that even mean?), [...]\n> \n> I guess I'm \"nobody\" then, because I use it all the time.\n\nLanguage is rarely 100% specific. By \"nobody\" of course I meant\n\"virtually nobody\".\n\nAnd yeah, I know you actually use \"origin\", because you do have correct\n\"origin/HEAD\" for many of your repositories. I don't, and I'd argume\nmost users don't either.\n\nIt's right next in my to-do list to work on fetch.updateHead so I (and\nmany users) can join you in using \"origin\". But that's not the case\ntoday.\n\n> The example in Documentation/rev-list-description.txt (which feeds into\n> the git-log and git-rev-list manpages) uses \"origin..HEAD\", as well.\n\nI think it shouldn't, but that's a separate topic.\n\n> IMHO it is a pretty reasonable example, but the examples in\n> gitrevisions(7) use made up \"r1..r2\", and that seems perfectly readable,\n> as well.\n\nIt is readable, sure, but it's not a real example. When picking an\nexample of English sentence with subject and predicate I'd pick \"Mary\nwent to the moves\" over \"Subject predicate\" in heartbeat.\n\nAn instance that doesn't come from the set of real commands is not\nreally an example to me.\n\nCheers.\n\n-- \nFelipe Contreras\n"},{"id":"424774","messageId":"xmqqpmxp6u13.fsf@gitster.g","threadId":"55703","inReplyTo":"YKJZt4vFECoLZhc2@coredump.intra.peff.net","subject":"Re: Re* [PATCH] doc: glossary: add entry for revision range","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-05-17T19:26:48Z","receivedAt":"2021-05-17T19:26:57Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n> I agree that if the purpose is to be illustrative, using shortcuts like\n> \"an empty endpoint means HEAD\" is not helpful. And likewise for \"@\"; if\n> you need to have \"revision range\" defined, there is a good chance that\n> you don't know about shortcuts like \"@\" either.\n>\n> So I would prefer something more explicit (whether it's \"mybranch\" or\n> \"end\" or \"HEAD\" or whatever).\n\nPerhaps. Being illustrative for common use case is also important,\nso I do not mind teaching \"missing endpoint at either side defaults\nto HEAD\" early.\n\nIf \"missing\" endpoint is disturbing, the description can be fixed to\nstress that they are \"often but not always\" given.\n\n>> > Especially since most people are downstream consumers, I'd\n>> > suggest using `origin..` or `@{u}..` here.\n>> \n>> Nobody uses \"origin\" (what does that even mean?), [...]\n>\n> I guess I'm \"nobody\" then, because I use it all the time.\n\nOh, I'm nobody, too, and so are many others ;-)\n\n> The example in Documentation/rev-list-description.txt (which feeds into\n> the git-log and git-rev-list manpages) uses \"origin..HEAD\", as well.\n>\n> IMHO it is a pretty reasonable example, but the examples in\n> gitrevisions(7) use made up \"r1..r2\", and that seems perfectly readable,\n> as well.\n>\n> -Peff\n"},{"id":"424787","messageId":"60a2daa57d8a6_13c370208f3@natae.notmuch","threadId":"55703","inReplyTo":"xmqqpmxp6u13.fsf@gitster.g","subject":"Re: Re* [PATCH] doc: glossary: add entry for revision range","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-17T21:05:41Z","receivedAt":"2021-05-17T21:05:45Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Junio C Hamano wrote:\n> Jeff King writes:\n> \n> > I agree that if the purpose is to be illustrative, using shortcuts like\n> > \"an empty endpoint means HEAD\" is not helpful. And likewise for \"@\"; if\n> > you need to have \"revision range\" defined, there is a good chance that\n> > you don't know about shortcuts like \"@\" either.\n> >\n> > So I would prefer something more explicit (whether it's \"mybranch\" or\n> > \"end\" or \"HEAD\" or whatever).\n> \n> Perhaps. Being illustrative for common use case is also important,\n> so I do not mind teaching \"missing endpoint at either side defaults\n> to HEAD\" early.\n\nA glossary is not a place to teach (anything other than the definition).\nIt's supposed to contain glosses (brief explanations).\n\nYou don't find a complete recipe when you look for the definition of\n\"recpipe\". That information belongs elsewhere.\n\n> If \"missing\" endpoint is disturbing, the description can be fixed to\n> stress that they are \"often but not always\" given.\n\nThis is unnecessary information.\n\nIf we teach that then we also have to teach that the starting point is\nnot always given either (`..mybranch`). And where does it end? We would\nhave to teach that `mybranch ^master` is yet another form of a revision\nrange, and so is -1.\n\nThat's what gitrevisions(7) is for.\n\n> >> > Especially since most people are downstream consumers, I'd\n> >> > suggest using `origin..` or `@{u}..` here.\n> >> \n> >> Nobody uses \"origin\" (what does that even mean?), [...]\n> >\n> > I guess I'm \"nobody\" then, because I use it all the time.\n> \n> Oh, I'm nobody, too, and so are many others ;-)\n\nThat depends on the definition of \"many\". My guess is that it's less\nthan 1% of users (probably 0.01%), and for me that's not many.\n\nIf you google for `git remote \"set-head\"` there's barely any\ninformation. It's basically all online man pages.\n\nI don't think anyone can argue it's not obscure.\n\nCheers.\n\n-- \nFelipe Contreras\n"},{"id":"424796","messageId":"xmqq1ra46f0h.fsf@gitster.g","threadId":"55703","inReplyTo":"60a2daa57d8a6_13c370208f3@natae.notmuch","subject":"Re: Re* [PATCH] doc: glossary: add entry for revision range","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-05-18T00:51:10Z","receivedAt":"2021-05-18T00:51:16Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Felipe Contreras writes:\n\n> Junio C Hamano wrote:\n>> Jeff King writes:\n>> \n>> > I agree that if the purpose is to be illustrative, using shortcuts like\n>> > \"an empty endpoint means HEAD\" is not helpful. And likewise for \"@\"; if\n>> > you need to have \"revision range\" defined, there is a good chance that\n>> > you don't know about shortcuts like \"@\" either.\n>> >\n>> > So I would prefer something more explicit (whether it's \"mybranch\" or\n>> > \"end\" or \"HEAD\" or whatever).\n>> \n>> Perhaps. Being illustrative for common use case is also important,\n>> so I do not mind teaching \"missing endpoint at either side defaults\n>> to HEAD\" early.\n>\n> A glossary is not a place to teach (anything other than the definition).\n> It's supposed to contain glosses (brief explanations).\n\nFair enough. Then let's limit ourselves to the definition, but give\na correct one. It is not \"syntax\" that the phrase \"revision range\"\nrefers to; it is what is specified by that syntax.\n\n[[def_revision_range]]revision range::\n A set of connected commits to work on, usually specified by\n giving two end points, like `origin..mytopic`. See the\n 'Specifying Ranges' and 'Revision Range Summary' sections of\n linkgit:gitrevisions[7] for details.\n"},{"id":"424799","messageId":"60a317ab5068_149b6620891@natae.notmuch","threadId":"55703","inReplyTo":"xmqq1ra46f0h.fsf@gitster.g","subject":"Re: Re* [PATCH] doc: glossary: add entry for revision range","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-18T01:26:03Z","receivedAt":"2021-05-18T01:26:09Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Junio C Hamano wrote:\n> Felipe Contreras writes:\n> > Junio C Hamano wrote:\n\n> >> Perhaps. Being illustrative for common use case is also important,\n> >> so I do not mind teaching \"missing endpoint at either side defaults\n> >> to HEAD\" early.\n> >\n> > A glossary is not a place to teach (anything other than the definition).\n> > It's supposed to contain glosses (brief explanations).\n> \n> Fair enough. Then let's limit ourselves to the definition, but give\n> a correct one. It is not \"syntax\" that the phrase \"revision range\"\n> refers to; it is what is specified by that syntax.\n\nThat's a distinction without a difference.\n\nLike saying \"Felipe is a person\" is wrong, because \"Felipe\" is not a\nperson, but the _name_ of a person. This is excessive concern with minor\ndetails to me.\n\nIn the minds of most people object identifiers are used interchangeably\nwith the object themselves: \"Felipe\" is a person, \"master\" is a branch, and\n\"master..@\" is a revision range.\n\n> [[def_revision_range]]revision range::\n> A set of connected commits to work on, usually specified by\n> giving two end points, like `origin..mytopic`.\n\nendpoints.\n\nAs for the rest I already raised my concerns.\n\nCheers.\n\n-- \nFelipe Contreras\n"},{"id":"424806","messageId":"YKMhqZNhamnKqWfi@coredump.intra.peff.net","threadId":"55703","inReplyTo":"60a2daa57d8a6_13c370208f3@natae.notmuch","subject":"Re: Re* [PATCH] doc: glossary: add entry for revision range","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2021-05-18T02:08:41Z","receivedAt":"2021-05-18T02:08:48Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Mon, May 17, 2021 at 04:05:41PM -0500, Felipe Contreras wrote:\n\n> > >> Nobody uses \"origin\" (what does that even mean?), [...]\n> > >\n> > > I guess I'm \"nobody\" then, because I use it all the time.\n> > \n> > Oh, I'm nobody, too, and so are many others ;-)\n> \n> That depends on the definition of \"many\". My guess is that it's less\n> than 1% of users (probably 0.01%), and for me that's not many.\n> \n> If you google for `git remote \"set-head\"` there's barely any\n> information. It's basically all online man pages.\n\nWhy would people need to use \"git remote set-head\" most of the time? The\nsymlink is set up properly by git-clone, and has been for many years.\nFor most people, using \"origin\" just works (the exception is people who\n\"git init\" and then \"git remote add origin\" themselves; since we're\nguessing at numbers, I would guess that _that_ population is less than\n1% of users).\n\n-Peff\n"},{"id":"424809","messageId":"xmqq1ra44ul5.fsf@gitster.g","threadId":"55703","inReplyTo":"YKMhqZNhamnKqWfi@coredump.intra.peff.net","subject":"Re: Re* [PATCH] doc: glossary: add entry for revision range","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-05-18T02:57:42Z","receivedAt":"2021-05-18T02:57:45Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n>> If you google for `git remote \"set-head\"` there's barely any\n>> information. It's basically all online man pages.\n>\n> Why would people need to use \"git remote set-head\" most of the time?\n\nI somehow thought Felipe wanted to say that there is nothing but\nmanual pages that mention the command and, \"look how useful set-head\nsubcommand is, here is how you use it\" blog posts are not seen\nbecause nobody uses 'remote set-head'.\n\nI do not quesiotn the frequency count of set-head, but I do not\nthink the lack of mention of set-head leads to the conclusion that\nnobody uses \"git log origin..\"; there is a leap in logic. As you\nsaid below, \"origin\" is there without need for set-head, so the lack\nof enthusiastic advocate for set-head does not mean anything wrt how\npeople find \"origin\" useful.\n\n> The\n> symlink is set up properly by git-clone, and has been for many years.\n> For most people, using \"origin\" just works (the exception is people who\n> \"git init\" and then \"git remote add origin\" themselves; since we're\n> guessing at numbers, I would guess that _that_ population is less than\n> 1% of users).\n"},{"id":"424822","messageId":"60a34a7616cda_14d1bc20818@natae.notmuch","threadId":"55703","inReplyTo":"YKMhqZNhamnKqWfi@coredump.intra.peff.net","subject":"Re: Re* [PATCH] doc: glossary: add entry for revision range","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-18T05:02:46Z","receivedAt":"2021-05-18T05:02:50Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Jeff King wrote:\n> On Mon, May 17, 2021 at 04:05:41PM -0500, Felipe Contreras wrote:\n> \n> > > >> Nobody uses \"origin\" (what does that even mean?), [...]\n> > > >\n> > > > I guess I'm \"nobody\" then, because I use it all the time.\n> > > \n> > > Oh, I'm nobody, too, and so are many others ;-)\n> > \n> > That depends on the definition of \"many\". My guess is that it's less\n> > than 1% of users (probably 0.01%), and for me that's not many.\n> > \n> > If you google for `git remote \"set-head\"` there's barely any\n> > information. It's basically all online man pages.\n> \n> Why would people need to use \"git remote set-head\" most of the time? The\n> symlink is set up properly by git-clone, and has been for many years.\n\nFirst instructions from GitHub:\n\n echo \"# test\" >> README.md\n git init\n git add README.md\n git commit -m \"first commit\"\n git branch -M main\n git remote add origin git@github.com:felipec/test.git\n git push -u origin main\n\nSecond instructions from GitHub:\n\n git remote add origin git@github.com:felipec/test.git\n git branch -M main\n git push -u origin main\n\nNone of these use `git clone`.\n\nOf 31 repositories I work on and have quickly at hand only 8 have\norigin/HEAD.\n\n> For most people, using \"origin\" just works (the exception is people who\n> \"git init\" and then \"git remote add origin\" themselves; since we're\n> guessing at numbers, I would guess that _that_ population is less than\n> 1% of users).\n\nOn what do you base that guess?\n\nThe GitHub instructions don't use `git clone`. I can gather similar\ninstructions from other places if you are unconvinced.\n\nI don't think most people set up their repositories as you think they\ndo.\n\n\nAnd even *if* origin/HEAD did work on most repositories (hardly the\ncase), most people are not going to train their fingers to type `git cmd\n$x` when the only $x where the command works is \"origin\"; they would\nrather train their fingers to do $x/master which works on many more\nrepositories.\n\nCheers.\n\n-- \nFelipe Contreras\n"},{"id":"424823","messageId":"60a34e834f208_14d1bc208e4@natae.notmuch","threadId":"55703","inReplyTo":"xmqq1ra44ul5.fsf@gitster.g","subject":"Re: Re* [PATCH] doc: glossary: add entry for revision range","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-18T05:20:03Z","receivedAt":"2021-05-18T05:20:08Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Junio C Hamano wrote:\n> Jeff King writes:\n> \n> >> If you google for `git remote \"set-head\"` there's barely any\n> >> information. It's basically all online man pages.\n> >\n> > Why would people need to use \"git remote set-head\" most of the time?\n> \n> I somehow thought Felipe wanted to say that there is nothing but\n> manual pages that mention the command and, \"look how useful set-head\n> subcommand is, here is how you use it\" blog posts are not seen\n> because nobody uses 'remote set-head'.\n> \n> I do not quesiotn the frequency count of set-head, but I do not\n> think the lack of mention of set-head leads to the conclusion that\n> nobody uses \"git log origin..\"; there is a leap in logic.\n\nI did not say that is the only evidence to lead to that conclusion.\n\nBut it is evidence.\n\n> As you said below, \"origin\" is there without need for set-head,\n\nOnly sometimes.\n\n> so the lack of enthusiastic advocate for set-head does not mean\n> anything wrt how people find \"origin\" useful.\n\nYes it does. Contrary to popular belief absence of evidence can be\nevidence of absence. If I walk around Central Park for half an hour and\nI don't see any elephants, that's evidence that there are no elephants\nin Central Park at this very moment. It is not *conclusive* evidence,\nbut it is evidence.\n\nJust because the evidence for $x is not sufficient to prove $x doesn't\nmean there is no evidence for $x.\n\n-- \nFelipe Contreras\n"},{"id":"424834","messageId":"YKNk+5k3hKW/xPBZ@coredump.intra.peff.net","threadId":"55703","inReplyTo":"60a34a7616cda_14d1bc20818@natae.notmuch","subject":"Re: Re* [PATCH] doc: glossary: add entry for revision range","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2021-05-18T06:55:55Z","receivedAt":"2021-05-18T06:55:59Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Tue, May 18, 2021 at 12:02:46AM -0500, Felipe Contreras wrote:\n\n> > Why would people need to use \"git remote set-head\" most of the time? The\n> > symlink is set up properly by git-clone, and has been for many years.\n> \n> First instructions from GitHub:\n> \n> echo \"# test\" >> README.md\n> git init\n> git add README.md\n> git commit -m \"first commit\"\n> git branch -M main\n> git remote add origin git@github.com:felipec/test.git\n> git push -u origin main\n> \n> Second instructions from GitHub:\n> \n> git remote add origin git@github.com:felipec/test.git\n> git branch -M main\n> git push -u origin main\n> \n> None of these use `git clone`.\n\nSo? Here are some other instructions from GitHub[0]:\n\n Type git clone, and then paste the URL you copied earlier.\n\n $ git clone https://github.com/YOUR-USERNAME/YOUR-REPOSITORY\n\n[0] https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/cloning-a-repository\n\nNot to mention that every single repository page mentions cloning under\nthe \"Code\" button (including the command-line \"gh repo clone\" if you are\nusing their recommended tool).\n\nPeople clone a lot more than they create new repositories.\n\n> Of 31 repositories I work on and have quickly at hand only 8 have\n> origin/HEAD.\n\nAnd of 141 repositories I have on my workstation, 137 have origin/HEAD\n(and of the 4 without, one does not even have a remote at all, and one\nis a git-svn repository).\n\nI don't think that proves anything except that your workflow is\ndifferent than mine. But I contend that most people get repositories by\ncloning them.\n\n> And even *if* origin/HEAD did work on most repositories (hardly the\n> case), most people are not going to train their fingers to type `git cmd\n> $x` when the only $x where the command works is \"origin\"; they would\n> rather train their fingers to do $x/master which works on many more\n> repositories.\n\nI guess I'm not most people, because I sure have enjoyed typing the\nshorter thing all these years.\n\nLook, I get that you didn't know or care about the \"origin/HEAD\" feature\nuntil recently. But it's been part of Git for over 15 years, and has\nbeen used as the documentation examples for revision ranges in both\ngit-rev-list(1) and gitrevisions(7), as well as the user-manual.\n\nI'm perfectly happy to use placeholder ref names in the glossary\ndocumentation, but it's not like the use of \"origin\" as a name is some\nobscure secret.\n\n-Peff\n"},{"id":"424835","messageId":"YKNl6IAFGezjCZUf@coredump.intra.peff.net","threadId":"55703","inReplyTo":"60a2a670648b1_12801e20895@natae.notmuch","subject":"Re: Re* [PATCH] doc: glossary: add entry for revision range","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2021-05-18T06:59:52Z","receivedAt":"2021-05-18T06:59:55Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Mon, May 17, 2021 at 12:22:56PM -0500, Felipe Contreras wrote:\n\n> > > If we must not use @, then I would rather use `master..mybranch`, or\n> > > something like that. HEAD seems like a technical accident. But of course\n> > > I would prefer HEAD to nothing, because at least it qualifies as an\n> > > ending point.\n> > \n> > I agree that if the purpose is to be illustrative, using shortcuts like\n> > \"an empty endpoint means HEAD\" is not helpful. And likewise for \"@\"; if\n> > you need to have \"revision range\" defined, there is a good chance that\n> > you don't know about shortcuts like \"@\" either.\n> \n> But they don't need to know what @ means; it's clearly a shortcut for\n> _something_, and that's all they need to know. In fact, I'd say most\n> people can quickly realize what a shorcut for it is, which is why it was\n> picked by the git project, and many Mercurial projects as well.\n\nThat's my point. It _isn't_ clearly a shortcut for something for all\npeople. If you are reading the glossary entry for \"revision range\", you\nmight not know about the \"..\" syntax at all. So what does:\n\n foo..@\n\nmean? Does it parse as three (foo, .., @) or is \"..@\" a special symbol?\n\nI expect most people would figure it out. But if your point is to serve\nas documentation, especially for people who do not yet know all of the\nconcepts, then why not try to reduce the chance of error as much as\npossible?\n\n> Actually, I would prefer something more real, like \"feature-x\".\n\nSure, that is fine with me.\n\n-Peff\n"},{"id":"424855","messageId":"60a3a808d7eeb_151987208bb@natae.notmuch","threadId":"55703","inReplyTo":"YKNk+5k3hKW/xPBZ@coredump.intra.peff.net","subject":"Re: Re* [PATCH] doc: glossary: add entry for revision range","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-18T11:42:00Z","receivedAt":"2021-05-18T11:42:10Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Jeff King wrote:\n> On Tue, May 18, 2021 at 12:02:46AM -0500, Felipe Contreras wrote:\n> \n> > > Why would people need to use \"git remote set-head\" most of the time? The\n> > > symlink is set up properly by git-clone, and has been for many years.\n> > \n> > First instructions from GitHub:\n> > \n> > echo \"# test\" >> README.md\n> > git init\n> > git add README.md\n> > git commit -m \"first commit\"\n> > git branch -M main\n> > git remote add origin git@github.com:felipec/test.git\n> > git push -u origin main\n> > \n> > Second instructions from GitHub:\n> > \n> > git remote add origin git@github.com:felipec/test.git\n> > git branch -M main\n> > git push -u origin main\n> > \n> > None of these use `git clone`.\n> \n> So? Here are some other instructions from GitHub[0]:\n> \n> Type git clone, and then paste the URL you copied earlier.\n> \n> $ git clone https://github.com/YOUR-USERNAME/YOUR-REPOSITORY\n> \n> [0] https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/cloning-a-repository\n\nA random github.com link doesn't show anything. The instructions I'm\ntalking about are the **first** thing the site gives to users.\n\nOn the other hand let's see how we get to your link.\n\n 1. Click \"New\"\n 2. Type \"Repository Name\"\n 3. Click \"Create repository\"\n 4. Ignore the entire setup page (with the `git remote add` commands)\n 5. Click on your profile icon\n 6. Select \"Help\"\n 7. Go to the GitHub.com submenu\n 8. Ignore the Quickstart\n 8.1. Ignore the Git cheatsheet\n 8.1.1. Ignore the `git remote add` part of the cheatsheet that\n comes before the `git clone` part\n 9. Ignore Getting started with Git\n 9.1. Ignore About remote repositories\n 9.1.1 Ignore the section Creating remote repositories which does\n `git remote add` before it mentions `git clone`\n 9.2. Ignore Managing remote repositories (talks about `git remote\n add`)\n 10. Select Creating, cloning, and archiving repositories\n 11. Select Cloning a repository\n\nFinally we reach that link.\n\nTo reach that link we need to ignore **all** the tips GitHub gives, and\ndirectly click on a sbusbusection called \"Cloning a repository\", which\nis part of a subsection \"Creating, cloning, and archiving repositories\"\nwhich is part of the section GitHub.com, which is part of the help.\n\nI seriously dobut this is one of the first things any user sees.\n\n> Not to mention that every single repository page mentions cloning under\n> the \"Code\" button (including the command-line \"gh repo clone\" if you are\n> using their recommended tool).\n> \n> People clone a lot more than they create new repositories.\n\nDepends what you call \"people\". If you are talking about professional\nsoftware developers, then maybe.\n\nBut they are not the only users of git.\n\nDo you have any stats?\n\n> > Of 31 repositories I work on and have quickly at hand only 8 have\n> > origin/HEAD.\n> \n> And of 141 repositories I have on my workstation, 137 have origin/HEAD\n> (and of the 4 without, one does not even have a remote at all, and one\n> is a git-svn repository).\n> \n> I don't think that proves anything except that your workflow is\n> different than mine.\n\nExactly, and we cannot assume most people follow your workflow. In fact,\nI'd say your workflow is probably one of the most atypical in the world.\nYou know tricks 99.99% of users don't know about, in fact that probably\n99% of git.git developers don't know.\n\nIt is sufficient to acknowledge that there are different workflows.\n\n> > And even *if* origin/HEAD did work on most repositories (hardly the\n> > case), most people are not going to train their fingers to type `git cmd\n> > $x` when the only $x where the command works is \"origin\"; they would\n> > rather train their fingers to do $x/master which works on many more\n> > repositories.\n> \n> I guess I'm not most people, because I sure have enjoyed typing the\n> shorter thing all these years.\n\nYou are not part of that subset.\n\nI'm talking about people that do have \"origin/HEAD\", but *don't* have\nany other \"$remote/HEAD\".\n\nDo you have a HEAD configured for most of your remotes?\n\n> Look, I get that you didn't know or care about the \"origin/HEAD\" feature\n> until recently. But it's been part of Git for over 15 years, and has\n> been used as the documentation examples for revision ranges in both\n> git-rev-list(1) and gitrevisions(7), as well as the user-manual.\n\nThe fact that something is part of the documentation doesn't mean it is\nwell-known.\n\nThe `git remote add -m` option has been documented since 2007, and you\nyourself didn't know about it. If you google for that you find nothing.\nThere's only 1. a qustion on Stack Overflow with zero votes, and 2. the\nmail I send you about it. That's it.\n\nDo you agree that `git remote add -m` is obscure?\n\nIf so, why is it different from origin/HEAD?\n\nI decided to skim through the entire Pro Git book to see if I could find\nany instance in which they use this shortcut... I found **zero**.\n\nIf a user can read the most well-known book about git that had hundreds\nof contributors without finding a single instance of this shortcut...\nHow common do you really think it is?\n\nIn, fact, I found an interesting quote: \"The git rerere functionality is\na bit of a hidden feature.\" If rerere is a \"hidden feature\" then what\nwhat is origin/HEAD?\n\n> I'm perfectly happy to use placeholder ref names in the glossary\n> documentation, but it's not like the use of \"origin\" as a name is some\n> obscure secret.\n\nIt's easier to flip the problem around: if origin/HEAD is well-known,\nwhat would we *not* expect to find?\n\nIs there anything that would falsify the premise?\n\nCheers.\n\n-- \nFelipe Contreras\n"},{"id":"424861","messageId":"60a3b2f8eb3b_1519872087c@natae.notmuch","threadId":"55703","inReplyTo":"YKNl6IAFGezjCZUf@coredump.intra.peff.net","subject":"Re: Re* [PATCH] doc: glossary: add entry for revision range","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-18T12:28:40Z","receivedAt":"2021-05-18T12:28:44Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Jeff King wrote:\n> On Mon, May 17, 2021 at 12:22:56PM -0500, Felipe Contreras wrote:\n> \n> > > > If we must not use @, then I would rather use `master..mybranch`, or\n> > > > something like that. HEAD seems like a technical accident. But of course\n> > > > I would prefer HEAD to nothing, because at least it qualifies as an\n> > > > ending point.\n> > > \n> > > I agree that if the purpose is to be illustrative, using shortcuts like\n> > > \"an empty endpoint means HEAD\" is not helpful. And likewise for \"@\"; if\n> > > you need to have \"revision range\" defined, there is a good chance that\n> > > you don't know about shortcuts like \"@\" either.\n> > \n> > But they don't need to know what @ means; it's clearly a shortcut for\n> > _something_, and that's all they need to know. In fact, I'd say most\n> > people can quickly realize what a shorcut for it is, which is why it was\n> > picked by the git project, and many Mercurial projects as well.\n> \n> That's my point. It _isn't_ clearly a shortcut for something for all\n> people. If you are reading the glossary entry for \"revision range\", you\n> might not know about the \"..\" syntax at all. So what does:\n> \n> foo..@\n> \n> mean?\n\nAn ellipsis is a common feature of both human and computer languages...\n\n The ... fox jumps ...\n\nIs easily understood by most English speakers, so is a, b, c ... z.\n\nIt is used in math as well 1, 2, 3,..., 100.\n\nIt's used in computer languages, like Pascal, Modula, Oberon, Ada,\nHaskell, Perl, Ruby, Swift, Kotlin, F#, and MATLAB.\n\n (1..10).each { |i| puts i }\n\nI think most readers would infer that a) the starting point is at the\nleft of the ending point b) there's nothing after the ending point.\n\nSo what could the thing at the right of the starting point, follwing an\nellipsis, and not followed by anything else be? I think most people\nwould get it.\n\n> I expect most people would figure it out. But if your point is to serve\n> as documentation, especially for people who do not yet know all of the\n> concepts, then why not try to reduce the chance of error as much as\n> possible?\n\nWe want to minimize the chances of error... up to a point. We also want\nto be useful.\n\nMoreover, most readers don't learn at the speed they read, it takes\ntime, and often practice. Copy-pasting `master..@` to their terminal\nwill most likely work, and with any luck they'll understand it right\naway.\n\nThey don't need to understand revision ranges completely when they read\nthe glossary, they just need a brief explanation.\n\n[1] https://en.wikipedia.org/wiki/Ellipsis\n\n-- \nFelipe Contreras\n"},{"id":"424862","messageId":"YKO3eeNPxCwvIkEw@coredump.intra.peff.net","threadId":"55703","inReplyTo":"60a3a808d7eeb_151987208bb@natae.notmuch","subject":"Re: Re* [PATCH] doc: glossary: add entry for revision range","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2021-05-18T12:47:53Z","receivedAt":"2021-05-18T12:48:00Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Tue, May 18, 2021 at 06:42:00AM -0500, Felipe Contreras wrote:\n\n> A random github.com link doesn't show anything. The instructions I'm\n> talking about are the **first** thing the site gives to users.\n\nI would think the first thing most users see is _somebody else's\nrepository_, full of commits, that they then clone.\n\n> > People clone a lot more than they create new repositories.\n> \n> Depends what you call \"people\". If you are talking about professional\n> software developers, then maybe.\n> \n> But they are not the only users of git.\n> \n> Do you have any stats?\n\nOn one of GitHub's servers (selected randomly), there were ~300k clones\nin the past 24 hours. In the same time period on the same server, there\nwere 1780 new repos. Even that's overstating it, since some portion of\nthose are just forks of existing repos (so the user probably either\ncloned their fork immediately, or was already working on a clone of the\nupstream fork, rather than having run \"git init\" locally).\n\n> > I don't think that proves anything except that your workflow is\n> > different than mine.\n> \n> Exactly, and we cannot assume most people follow your workflow. In fact,\n> I'd say your workflow is probably one of the most atypical in the world.\n> You know tricks 99.99% of users don't know about, in fact that probably\n> 99% of git.git developers don't know.\n> \n> It is sufficient to acknowledge that there are different workflows.\n\nI'm not making some bizarre claim about workflows. I'm saying that\npeople commonly use \"git clone\" to get repositories. That really doesn't\nseem controversial.\n\nBut you know what, I've wasted enough time on this thread. If you want\nto believe that people don't use \"git clone\", go for it.\n\n-Peff\n"},{"id":"424903","messageId":"60a42d26c91ed_2c10208e3@natae.notmuch","threadId":"55703","inReplyTo":"YKO3eeNPxCwvIkEw@coredump.intra.peff.net","subject":"Re: Re* [PATCH] doc: glossary: add entry for revision range","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-18T21:09:58Z","receivedAt":"2021-05-18T21:10:08Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Jeff King wrote:\n> On Tue, May 18, 2021 at 06:42:00AM -0500, Felipe Contreras wrote:\n> \n> > A random github.com link doesn't show anything. The instructions I'm\n> > talking about are the **first** thing the site gives to users.\n> \n> I would think the first thing most users see is _somebody else's\n> repository_, full of commits, that they then clone.\n\nAll the tutorials I've seen start with `git init`. If you want to learn\ngit starting from a monstrous repository such as Chrome OS is probably\nnot a good idea.\n\nAnd yeah, if you assume most users are professional programmers, then\nyeah, that's probably true. But that's an assumption.\n\nMany users are students, others are amateur programmers, others might\nbe using git to track something other than code, like writing a book, or\ntheir dotfiles.\n\nExperts often forget what it is to be a beginner.\n\n> > > People clone a lot more than they create new repositories.\n> > \n> > Depends what you call \"people\". If you are talking about professional\n> > software developers, then maybe.\n> > \n> > But they are not the only users of git.\n> > \n> > Do you have any stats?\n> \n> On one of GitHub's servers (selected randomly), there were ~300k clones\n> in the past 24 hours. In the same time period on the same server, there\n> were 1780 new repos. Even that's overstating it, since some portion of\n> those are just forks of existing repos (so the user probably either\n> cloned their fork immediately, or was already working on a clone of the\n> upstream fork, rather than having run \"git init\" locally).\n\nHow do you distinguish a git clone from a git init + git remote add + git\nfetch?\n\n> > > I don't think that proves anything except that your workflow is\n> > > different than mine.\n> > \n> > Exactly, and we cannot assume most people follow your workflow. In fact,\n> > I'd say your workflow is probably one of the most atypical in the world.\n> > You know tricks 99.99% of users don't know about, in fact that probably\n> > 99% of git.git developers don't know.\n> > \n> > It is sufficient to acknowledge that there are different workflows.\n> \n> I'm not making some bizarre claim about workflows. I'm saying that\n> people commonly use \"git clone\" to get repositories. That really doesn't\n> seem controversial.\n\nIt's not controversial, but it's also not necessarily true.\n\nOn what are you basing that claim?\n\n> But you know what, I've wasted enough time on this thread. If you want\n> to believe that people don't use \"git clone\", go for it.\n\nI'll parse that as an answer to my quesion:\n\n> > Is there anything that would falsify the premise?\n\n\"No, there's absolutely nothing that would falsify my premise\".\n\nIf there's no way to falsify a claim, then there is no point in even\nentertaining that claim.\n\nCheers.\n\n-- \nFelipe Contreras\n"}]}