{"thread":{"id":"58542","subject":"[PATCH] git-reflog.txt: add an EXAMPLES section","startedAt":"2022-10-03T09:00:36Z","lastAt":"2022-10-03T16:41:14Z","messageCount":7,"participants":["Elia Pinto","Ævar Arnfjörð Bjarmason","Bagas Sanjaya","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"464062","messageId":"20221003084654.183966-1-gitter.spiros@gmail.com","threadId":"58542","inReplyTo":null,"subject":"[PATCH] git-reflog.txt: add an EXAMPLES section","fromName":"Elia Pinto","fromEmail":"gitter.spiros@gmail.com","sentAt":"2022-10-03T08:46:54Z","receivedAt":"2022-10-03T09:00:36Z","isPatch":true,"sender":{"key":"gitter.spiros@gmail.com","avatar":"https://avatars.githubusercontent.com/u/158490?v=4"},"body":"This commit adds an \"EXAMPLES\" section to the git reflog man page.\nThis new section currently provides examples of using git reflog\nwith branches, for which doubts often exist. In this commit we also\nadd a \"SEE ALSO\" section which refers to further information\non git commands or documentation referenced in the git reflog man page.\n\nSigned-off-by: Elia Pinto \n---\n Documentation/git-reflog.txt | 42 ++++++++++++++++++++++++++++++++++++\n 1 file changed, 42 insertions(+)\n\ndiff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt\nindex 70791b9fd8..5bbd5958fe 100644\n--- a/Documentation/git-reflog.txt\n+++ b/Documentation/git-reflog.txt\n@@ -96,6 +96,48 @@ them.\n --verbose::\n \tPrint extra information on screen.\n \n+EXAMPLES\n+--------\n+\n+`git reflog`::\n+\tLists entries of reflog of HEAD, starting at `HEAD@{0}`.\n+\n+`git reflog HEAD`::\n+\tThe same.\n+\n+`git reflog show HEAD`::\n+\tThe same.\n+\n+`git reflog HEAD@{4}`::\n+\tThe same, starting at the 4th prior value of HEAD.\n+\n+`git reflog master`::\n+\tLists entries of reflog of `master`.\n+\n+`git reflog master@{0}`::\n+\tThe same.\n+\n+`git reflog master@{now}`::\n+\tThe same, show with timestamp.\n+\n+`git reflog master@{4.minutes}`::\n+\tThe same, starting at master, 4 minutes ago.\n+\n+For the branch that is currently checked out, you can omit the name\n+when you use any of the @{..} notation, so\n+\n+`git reflog @{0}`\n+\n+`git reflog @{now}`\n+\n+are often the easiest ways to view what you did on the current\n+branch\n+\n+SEE ALSO\n+--------\n+linkgit:gitrevisions[7],\n+linkgit:git-log[1]\n+\n GIT\n ---\n Part of the linkgit:git[1] suite\n-- \n2.37.3\n\n"},{"id":"464067","messageId":"221003.86o7uttfxg.gmgdl@evledraar.gmail.com","threadId":"58542","inReplyTo":"20221003084654.183966-1-gitter.spiros@gmail.com","subject":"Re: [PATCH] git-reflog.txt: add an EXAMPLES section","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-03T09:20:05Z","receivedAt":"2022-10-03T09:34:44Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Mon, Oct 03 2022, Elia Pinto wrote:\n\n> This commit adds an \"EXAMPLES\" section to the git reflog man page.\n> This new section currently provides examples of using git reflog\n> with branches, for which doubts often exist. In this commit we also\n> add a \"SEE ALSO\" section which refers to further information\n> on git commands or documentation referenced in the git reflog man page.\n\nI think it can be valuable to have an EXAMPLES section, but:\n\n> +EXAMPLES\n> +--------\n> +\n> +`git reflog`::\n> +\tLists entries of reflog of HEAD, starting at `HEAD@{0}`.\n> +\n> +`git reflog HEAD`::\n> +\tThe same.\n> +\n> +`git reflog show HEAD`::\n> +\tThe same.\n> +\n> +`git reflog HEAD@{4}`::\n> +\tThe same, starting at the 4th prior value of HEAD.\n> +\n> +`git reflog master`::\n> +\tLists entries of reflog of `master`.\n> +\n> +`git reflog master@{0}`::\n> +\tThe same.\n> +\n> +`git reflog master@{now}`::\n> +\tThe same, show with timestamp.\n> +\n> +`git reflog master@{4.minutes}`::\n> +\tThe same, starting at master, 4 minutes ago.\n> +\n> +For the branch that is currently checked out, you can omit the name\n> +when you use any of the @{..} notation, so\n> +\n> +`git reflog @{0}`\n> +\n> +`git reflog @{now}`\n> +\n> +are often the easiest ways to view what you did on the current\n> +branch\n\nMost of this really just seems to be duplicating \"SPECIFYING REVISIONS\",\nand some of it such as \"show with timestamp\" is ambiguous/misleading. If\nI didn't know how it worked I'd think that it might affect the output\nitself (maybe showing times \"relative to now\"), but it's just\ngitrevisions syntax.\n\n> +SEE ALSO\n> +--------\n> +linkgit:gitrevisions[7],\n> +linkgit:git-log[1]\n\nLikewise \"SEE ALSO\" sections can be really valuable, but they're really\nfor \"now that you've read the above, maybe this is also useful\". It's\nnot a \"SEE STUFF YOU SAW BEFORE\" :)\n\nIn this case we link to these in the first and third paragraphs of the\nDESCRIPTION section (respectively), since explaining the revision syntax\netc. is really core to understanding how this command works.\n\nThe \"SEE ALSO\" section is really more for stuff like (in this case)\n'git-fsck', 'git-filter-branch', 'git-rev-list' or 'git-stash'. All of\nthose commansd have some direct interaction with the 'reflog', but are\nnot mentioned in the main prose.\n\n\n\n\n\n"},{"id":"464071","messageId":"da2c8d2f-eefa-1681-b1f2-93c7865c300c@gmail.com","threadId":"58542","inReplyTo":"20221003084654.183966-1-gitter.spiros@gmail.com","subject":"Re: [PATCH] git-reflog.txt: add an EXAMPLES section","fromName":"Bagas Sanjaya","fromEmail":"bagasdotme@gmail.com","sentAt":"2022-10-03T13:07:33Z","receivedAt":"2022-10-03T13:07:42Z","isPatch":true,"sender":{"key":"bagasdotme@gmail.com","avatar":"https://avatars.githubusercontent.com/u/40219486?v=4"},"body":"On 10/3/22 15:46, Elia Pinto wrote:\n> This commit adds an \"EXAMPLES\" section to the git reflog man page.\n> This new section currently provides examples of using git reflog\n> with branches, for which doubts often exist. In this commit we also\n> add a \"SEE ALSO\" section which refers to further information\n> on git commands or documentation referenced in the git reflog man page.\n> \n\nBetter say \"Add git-reflog usage examples to the man page.\"\nAlso, shouldn't \"SEE ALSO\" additions be split from this patch?\n\n-- \nAn old man doll... just what I always wanted! - Clara\n"},{"id":"464073","messageId":"CA+EOSBkp7xUPOa1uJcSi1MBYqUG6r7KQmDjAWDLqLXJwwQ0djA@mail.gmail.com","threadId":"58542","inReplyTo":"221003.86o7uttfxg.gmgdl@evledraar.gmail.com","subject":"Re: [PATCH] git-reflog.txt: add an EXAMPLES section","fromName":"Elia Pinto","fromEmail":"gitter.spiros@gmail.com","sentAt":"2022-10-03T13:53:06Z","receivedAt":"2022-10-03T13:53:27Z","isPatch":true,"sender":{"key":"gitter.spiros@gmail.com","avatar":"https://avatars.githubusercontent.com/u/158490?v=4"},"body":"Il giorno lun 3 ott 2022 alle ore 11:27 Ævar Arnfjörð Bjarmason\n ha scritto:\n>\n>\n> On Mon, Oct 03 2022, Elia Pinto wrote:\n>\n> > This commit adds an \"EXAMPLES\" section to the git reflog man page.\n> > This new section currently provides examples of using git reflog\n> > with branches, for which doubts often exist. In this commit we also\n> > add a \"SEE ALSO\" section which refers to further information\n> > on git commands or documentation referenced in the git reflog man page.\n>\n> I think it can be valuable to have an EXAMPLES section, but:\n>\n> > +EXAMPLES\n> > +--------\n> > +\n> > +`git reflog`::\n> > + Lists entries of reflog of HEAD, starting at `HEAD@{0}`.\n> > +\n> > +`git reflog HEAD`::\n> > + The same.\n> > +\n> > +`git reflog show HEAD`::\n> > + The same.\n> > +\n> > +`git reflog HEAD@{4}`::\n> > + The same, starting at the 4th prior value of HEAD.\n> > +\n> > +`git reflog master`::\n> > + Lists entries of reflog of `master`.\n> > +\n> > +`git reflog master@{0}`::\n> > + The same.\n> > +\n> > +`git reflog master@{now}`::\n> > + The same, show with timestamp.\n> > +\n> > +`git reflog master@{4.minutes}`::\n> > + The same, starting at master, 4 minutes ago.\n> > +\n> > +For the branch that is currently checked out, you can omit the name\n> > +when you use any of the @{..} notation, so\n> > +\n> > +`git reflog @{0}`\n> > +\n> > +`git reflog @{now}`\n> > +\n> > +are often the easiest ways to view what you did on the current\n> > +branch\n>\n> Most of this really just seems to be duplicating \"SPECIFYING REVISIONS\",\n> and some of it such as \"show with timestamp\" is ambiguous/misleading. If\n> I didn't know how it worked I'd think that it might affect the output\n> itself (maybe showing times \"relative to now\"), but it's just\n> gitrevisions syntax.\n\nThanks a lot, in the meantime.\n\nThe examples included are based on an email exchange done here between\na user and a git developer, maybe Junio, I don't remember. The user\nfound the explanation useful, as he had a hard time understanding how\ngit-reflog worked with branches. I agree that better could be done,\nfor example by entering how to recover lost commits, but that was not\nthe goal at the moment. Later this is something that it is always\npossible to do. It is also true that the examples in practice show\nwhat should already be known with gitrevisions however obviously many\nusers cannot find the link between the two, I must imagine\n>\n> > +SEE ALSO\n> > +--------\n> > +linkgit:gitrevisions[7],\n> > +linkgit:git-log[1]\n>\n> Likewise \"SEE ALSO\" sections can be really valuable, but they're really\n> for \"now that you've read the above, maybe this is also useful\". It's\n> not a \"SEE STUFF YOU SAW BEFORE\" :)\n>\n> In this case we link to these in the first and third paragraphs of the\n> DESCRIPTION section (respectively), since explaining the revision syntax\n> etc. is really core to understanding how this command works.\n>\n> The \"SEE ALSO\" section is really more for stuff like (in this case)\n> 'git-fsck', 'git-filter-branch', 'git-rev-list' or 'git-stash'. All of\n> those commansd have some direct interaction with the 'reflog', but are\n> not mentioned in the main prose.\n>\n\nBetter not to put a \"SEE ALSO\" then? I personally don't know\n\n>\n>\n>\n>\n"},{"id":"464082","messageId":"xmqqfsg4x40q.fsf@gitster.g","threadId":"58542","inReplyTo":"221003.86o7uttfxg.gmgdl@evledraar.gmail.com","subject":"Re: [PATCH] git-reflog.txt: add an EXAMPLES section","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-10-03T16:31:33Z","receivedAt":"2022-10-03T16:31:40Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason writes:\n\n> On Mon, Oct 03 2022, Elia Pinto wrote:\n>\n>> This commit adds an \"EXAMPLES\" section to the git reflog man page.\n>> This new section currently provides examples of using git reflog\n>> with branches, for which doubts often exist. In this commit we also\n>> add a \"SEE ALSO\" section which refers to further information\n>> on git commands or documentation referenced in the git reflog man page.\n>\n> I think it can be valuable to have an EXAMPLES section, but:\n> ...\n> Most of this really just seems to be duplicating \"SPECIFYING REVISIONS\",\n> and some of it such as \"show with timestamp\" is ambiguous/misleading.\n\nIt would become immediately clear what these phrases want to say,\nwhen the reader runs \"git reflog @{0}\" and \"git reflog @{now}\" while\nreading the document. I am not sure if the description is ambiguous\nor misleading to those who haven't seen any reflog output, especially\nthe timestamped ones. Perhaps some sample output in the documentation\nwould help, do you think?\n\n $ git reflog -2 HEAD@{now}\n ce17cbfa2b HEAD@{Mon Oct 3 09:07:30 2022 -0700}: checkout: moving...\n ce17cbfa2b HEAD@{Mon Oct 3 09:07:14 2022 -0700}: am: ssh signing...\n $ git reflog -2 HEAD@{0}\n ce17cbfa2b HEAD@{0}: checkout: moving...\n ce17cbfa2b HEAD@{1}: am: ssh signing...\n\nI would freely admit that this is one of my least favourite part of\nGit UI that allows what comes inside @{} as parameter to \"git\nreflog\" affect both the starting point (e.g. @{2.days} omits the\nactivities of the past 48 hours) and the format of the output. The\ntaste of the design is bad, but it is what we ended up with.\n\n>> +SEE ALSO\n>> +--------\n>> +linkgit:gitrevisions[7],\n>> +linkgit:git-log[1]\n>\n> Likewise \"SEE ALSO\" sections can be really valuable, but they're really\n> for \"now that you've read the above, maybe this is also useful\". It's\n> not a \"SEE STUFF YOU SAW BEFORE\" :)\n>\n> In this case we link to these in the first and third paragraphs of the\n> DESCRIPTION section (respectively), since explaining the revision syntax\n> etc. is really core to understanding how this command works.\n\nI do not know about that.\n\nOnly the part of the revision syntax that refers to the tip of a ref\nworks as input for \"git reflog\". IOW, \"git reflog seen^2~4\" does\nnot work. I do not think the knowledge of revision syntax helps\nunderstanding how to operate the command that much because of the\nabove. I agree with you that it is dubious if it is a good idea to\nlist gitrevisions[7] here, but for an entirely different reason.\n\nOn the other hand, git-log[1] might not be a bad thing to refer to,\nin order to learn that you can say something like\n\n git reflog --pretty=short --stat @{now}\n\nThanks for a review.\n\n"},{"id":"464084","messageId":"xmqq4jwkx3st.fsf@gitster.g","threadId":"58542","inReplyTo":"da2c8d2f-eefa-1681-b1f2-93c7865c300c@gmail.com","subject":"Re: [PATCH] git-reflog.txt: add an EXAMPLES section","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-10-03T16:36:18Z","receivedAt":"2022-10-03T16:36:28Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Bagas Sanjaya writes:\n\n> On 10/3/22 15:46, Elia Pinto wrote:\n>> This commit adds an \"EXAMPLES\" section to the git reflog man page.\n>> This new section currently provides examples of using git reflog\n>> with branches, for which doubts often exist. In this commit we also\n>> add a \"SEE ALSO\" section which refers to further information\n>> on git commands or documentation referenced in the git reflog man page.\n>> \n>\n> Better say \"Add git-reflog usage examples to the man page.\"\n\nThanks, indeed.\n\n> Also, shouldn't \"SEE ALSO\" additions be split from this patch?\n\nI think they are better together. The overall theme is to help\nreaders of that one documentation page, and 80% of the effort of\nthis step is spent on adding an EXAMPLES section, while the rest\ngoes to SEE ALSO.\n\nThanks.\n"},{"id":"464085","messageId":"xmqqy1twvp1v.fsf@gitster.g","threadId":"58542","inReplyTo":"CA+EOSBkp7xUPOa1uJcSi1MBYqUG6r7KQmDjAWDLqLXJwwQ0djA@mail.gmail.com","subject":"Re: [PATCH] git-reflog.txt: add an EXAMPLES section","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-10-03T16:40:12Z","receivedAt":"2022-10-03T16:41:14Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Elia Pinto writes:\n\n> The examples included are based on an email exchange done here between\n> a user and a git developer, maybe Junio, I don't remember. The user\n> found the explanation useful, as he had a hard time understanding how\n> git-reflog worked with branches. I agree that better could be done,\n> for example by entering how to recover lost commits, but that was not\n> the goal at the moment. Later this is something that it is always\n> possible to do. It is also true that the examples in practice show\n> what should already be known with gitrevisions however obviously many\n> users cannot find the link between the two, I must imagine\n\nGeez. I did find the examples, especially the use of \"4\" as a\nrandom number pulled out of thin air, vaguely familiar. You seem\nto mean https://lore.kernel.org/git/xmqqo7xuif46.fsf@gitster.g/\n"}]}