{"thread":{"id":"23370","subject":"ghost refs","startedAt":"2010-04-07T16:38:03Z","lastAt":"2010-04-20T15:10:14Z","messageCount":30,"participants":["John Dlugosz","Avery Pennarun","Jeff King","Junio C Hamano","Nicolas Sebrecht","Jakub Narebski","Yann Dirson","Zefram","Jay Soffian","Alex Riesen"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"138857","messageId":"89030B4A18ECCD45978A3A6B639D1F24032A074E1C@FL01EXMB01.trad.tradestation.com","threadId":"23370","inReplyTo":null,"subject":"ghost refs","fromName":"John Dlugosz","fromEmail":"jdlugosz@tradestation.com","sentAt":"2010-04-07T16:38:03Z","receivedAt":"2010-04-07T16:38:03Z","isPatch":false,"sender":{"key":"jdlugosz@tradestation.com","avatar":null},"body":"A couple times I've seen people who have some reference remotes/origin/foo after foo has been removed from origin.  What is the proper way to address that, other than removing the file directly?  It appears to not go away with a \"fetch\" even though it was deleted from the origin.  So what is the proper way to delete something on the origin so the deletion propagates?  I normally use \"git push origin :foo\".\n\n\n\n--John\n\n(sorry about the footer)\n\n\nTradeStation Group, Inc. is a publicly-traded holding company (NASDAQ GS: TRAD) of three operating subsidiaries, TradeStation Securities, Inc. (Member NYSE, FINRA, SIPC and NFA), TradeStation Technologies, Inc., a trading software and subscription company, and TradeStation Europe Limited, a United Kingdom, FSA-authorized introducing brokerage firm. None of these companies provides trading or investment advice, recommendations or endorsements of any kind. The information transmitted is intended only for the person or entity to which it is addressed and may contain confidential and/or privileged material. Any review, retransmission, dissemination or other use of, or taking of any action in reliance upon, this information by persons or entities other than the intended recipient is prohibited.\n  If you received this in error, please contact the sender and delete the material from any computer.\n"},{"id":"138858","messageId":"r2h32541b131004070958pa66bb7a3g6a1ecfaea0419965@mail.gmail.com","threadId":"23370","inReplyTo":"89030B4A18ECCD45978A3A6B639D1F24032A074E1C@FL01EXMB01.trad.tradestation.com","subject":"Re: ghost refs","fromName":"Avery Pennarun","fromEmail":"apenwarr@gmail.com","sentAt":"2010-04-07T16:58:33Z","receivedAt":"2010-04-07T16:58:33Z","isPatch":false,"sender":{"key":"apenwarr@gmail.com","avatar":"https://avatars.githubusercontent.com/u/20592?v=4"},"body":"On Wed, Apr 7, 2010 at 12:38 PM, John Dlugosz <JDlugosz@tradestation.com> wrote:\n> A couple times I've seen people who have some reference\n> remotes/origin/foo after foo has been removed from origin.\n> What is the proper way to address that, other than removing\n> the file directly?  It appears to not go away with a \"fetch\" even\n> though it was deleted from the origin.  So what is the proper way\n> to delete something on the origin so the deletion propagates?\n> I normally use \"git push origin :foo\".\n\nThis is on purpose, based on the theory that you don't want to lose\ndata from your local repo just because someone (accidentally?) deletes\na branch on the remote server.  Unfortunately, this theory is a bit\nflawed, since someone could just as easily overwrite the remote branch\nwith a totally different commit, and you'd still lose it in *that*\ncase.  So mostly it's just confusing.\n\nAnyway, what you want is \"git remote prune origin\".\n\nHave fun,\n\nAvery\n"},{"id":"138892","messageId":"20100407210010.GB27012@coredump.intra.peff.net","threadId":"23370","inReplyTo":"r2h32541b131004070958pa66bb7a3g6a1ecfaea0419965@mail.gmail.com","subject":"Re: ghost refs","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2010-04-07T21:00:10Z","receivedAt":"2010-04-07T21:00:10Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, Apr 07, 2010 at 12:58:33PM -0400, Avery Pennarun wrote:\n\n> This is on purpose, based on the theory that you don't want to lose\n> data from your local repo just because someone (accidentally?) deletes\n> a branch on the remote server.  Unfortunately, this theory is a bit\n> flawed, since someone could just as easily overwrite the remote branch\n> with a totally different commit, and you'd still lose it in *that*\n> case.  So mostly it's just confusing.\n\nYou do have a reflog in the case of overwrite. Delete kills off any\nassociated reflog (it would be cool if we had a \"graveyard\" reflog that\nkept deleted branch reflogs around for a while).\n\n> Anyway, what you want is \"git remote prune origin\".\n\nYep. I think there is \"git fetch --prune\" these days, too. We could\nperhaps add a config option if there isn't one already (I didn't look)\nso this happens automatically.\n\n-Peff\n"},{"id":"138894","messageId":"89030B4A18ECCD45978A3A6B639D1F24032A0750BE@FL01EXMB01.trad.tradestation.com","threadId":"23370","inReplyTo":"20100407210010.GB27012@coredump.intra.peff.net","subject":"RE: ghost refs","fromName":"John Dlugosz","fromEmail":"jdlugosz@tradestation.com","sentAt":"2010-04-07T22:00:11Z","receivedAt":"2010-04-07T22:00:11Z","isPatch":false,"sender":{"key":"jdlugosz@tradestation.com","avatar":null},"body":"> You do have a reflog in the case of overwrite. Delete kills off any \n> associated reflog (it would be cool if we had a \"graveyard\" reflog \n> that kept deleted branch reflogs around for a while).\n\nHmm, I thought you only had reflogs on your local branches, not the remote branches.  Often I have a local branch and a remote branch of the same name: I commit and advance one, then pushing updates the other.\n\nSomeone seeing a remote branch like remotes/origin/foo won't see my or anyone else's reflog for foo, as that doesn't get pushed.\n\nSo, I think that someone who fetches, and sees remotes/origin/foo has moved, doesn't have an automatic record of what it was previously.  Am I missing something?\n\n--John\n\n\n\n\n\n\n\n\n\n\n\n\nTradeStation Group, Inc. is a publicly-traded holding company (NASDAQ GS: TRAD) of three operating subsidiaries, TradeStation Securities, Inc. (Member NYSE, FINRA, SIPC and NFA), TradeStation Technologies, Inc., a trading software and subscription company, and TradeStation Europe Limited, a United Kingdom, FSA-authorized introducing brokerage firm. None of these companies provides trading or investment advice, recommendations or endorsements of any kind. The information transmitted is intended only for the person or entity to which it is addressed and may contain confidential and/or privileged material. Any review, retransmission, dissemination or other use of, or taking of any action in reliance upon, this information by persons or entities other than the intended recipient is prohibited. If you received this in error, please contact the sender and delete the material from any computer.\n"},{"id":"138895","messageId":"k2p32541b131004071503g4ce66e5bjac8270b10790a2af@mail.gmail.com","threadId":"23370","inReplyTo":"89030B4A18ECCD45978A3A6B639D1F24032A0750BE@FL01EXMB01.trad.tradestation.com","subject":"Re: ghost refs","fromName":"Avery Pennarun","fromEmail":"apenwarr@gmail.com","sentAt":"2010-04-07T22:03:06Z","receivedAt":"2010-04-07T22:03:06Z","isPatch":false,"sender":{"key":"apenwarr@gmail.com","avatar":"https://avatars.githubusercontent.com/u/20592?v=4"},"body":"On Wed, Apr 7, 2010 at 6:00 PM, John Dlugosz <JDlugosz@tradestation.com> wrote:\n>> You do have a reflog in the case of overwrite. Delete kills off any\n>> associated reflog (it would be cool if we had a \"graveyard\" reflog\n>> that kept deleted branch reflogs around for a while).\n>\n> Hmm, I thought you only had reflogs on your local branches, not the remote branches.\n\nThis used to be true, but I have confirmed that with the latest\nversion of git, remote refs have reflogs (as they should for safety).\n\nHave fun,\n\nAvery\n"},{"id":"138896","messageId":"89030B4A18ECCD45978A3A6B639D1F24032A0750CC@FL01EXMB01.trad.tradestation.com","threadId":"23370","inReplyTo":"k2p32541b131004071503g4ce66e5bjac8270b10790a2af@mail.gmail.com","subject":"RE: ghost refs","fromName":"John Dlugosz","fromEmail":"jdlugosz@tradestation.com","sentAt":"2010-04-07T22:10:41Z","receivedAt":"2010-04-07T22:10:41Z","isPatch":false,"sender":{"key":"jdlugosz@tradestation.com","avatar":null},"body":"So do I still have to specify that I want a reflog when I create a branch, or does that always happen with local branches too?\n\n\n\n\n\n\n\n> -----Original Message-----\n\n> From: Avery Pennarun [mailto:apenwarr@gmail.com]\n\n> Sent: Wednesday, April 07, 2010 5:03 PM\n\n> To: John Dlugosz\n\n> Cc: git@vger.kernel.org\n\n> Subject: Re: ghost refs\n\n> \n\n> On Wed, Apr 7, 2010 at 6:00 PM, John Dlugosz\n\n> <JDlugosz@tradestation.com> wrote:\n\n> >> You do have a reflog in the case of overwrite. Delete kills off any\n\n> >> associated reflog (it would be cool if we had a \"graveyard\" reflog\n\n> >> that kept deleted branch reflogs around for a while).\n\n> >\n\n> > Hmm, I thought you only had reflogs on your local branches, not the\n\n> remote branches.\n\n> \n\n> This used to be true, but I have confirmed that with the latest\n\n> version of git, remote refs have reflogs (as they should for safety).\n\n> \n\n> Have fun,\n\n> \n\n> Avery\n\n\nTradeStation Group, Inc. is a publicly-traded holding company (NASDAQ GS: TRAD) of three operating subsidiaries, TradeStation Securities, Inc. (Member NYSE, FINRA, SIPC and NFA), TradeStation Technologies, Inc., a trading software and subscription company, and TradeStation Europe Limited, a United Kingdom, FSA-authorized introducing brokerage firm. None of these companies provides trading or investment advice, recommendations or endorsements of any kind. The information transmitted is intended only for the person or entity to which it is addressed and may contain confidential and/or privileged material. Any review, retransmission, dissemination or other use of, or taking of any action in reliance upon, this information by persons or entities other than the intended recipient is prohibited.\n  If you received this in error, please contact the sender and delete the material from any computer.\n"},{"id":"138897","messageId":"k2x32541b131004071511i9bbe883az504547d6133aef@mail.gmail.com","threadId":"23370","inReplyTo":"89030B4A18ECCD45978A3A6B639D1F24032A0750CC@FL01EXMB01.trad.tradestation.com","subject":"Re: ghost refs","fromName":"Avery Pennarun","fromEmail":"apenwarr@gmail.com","sentAt":"2010-04-07T22:11:38Z","receivedAt":"2010-04-07T22:11:38Z","isPatch":false,"sender":{"key":"apenwarr@gmail.com","avatar":"https://avatars.githubusercontent.com/u/20592?v=4"},"body":"On Wed, Apr 7, 2010 at 6:10 PM, John Dlugosz <JDlugosz@tradestation.com> wrote:\n> So do I still have to specify that I want a reflog when I create a branch, or does that always happen with local branches too?\n\nWhy not try it and find out?\n\nI've never asked for a reflog explicitly and I seem to get them.\n\nAvery\n"},{"id":"138918","messageId":"20100408043059.GA28768@coredump.intra.peff.net","threadId":"23370","inReplyTo":"k2x32541b131004071511i9bbe883az504547d6133aef@mail.gmail.com","subject":"Re: ghost refs","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2010-04-08T04:30:59Z","receivedAt":"2010-04-08T04:30:59Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, Apr 07, 2010 at 06:11:38PM -0400, Avery Pennarun wrote:\n\n> On Wed, Apr 7, 2010 at 6:10 PM, John Dlugosz <JDlugosz@tradestation.com> wrote:\n> > So do I still have to specify that I want a reflog when I create a branch, or does that always happen with local branches too?\n> \n> Why not try it and find out?\n> \n> I've never asked for a reflog explicitly and I seem to get them.\n\nWe create logs for remote branches when core.logallrefupdates is set\nsince e19b9dd (core.logallrefupdates: log remotes/ tracking branches.,\n2006-12-28).\n\nWe turned on logallrefupdates by default in non-bare repositories in\n0bee591 (Enable reflogs by default in any repository with a working\ndirectory., 2006-12-14).\n\nBoth were in v1.5.0. So it used to not be the case that we created such\nreflogs, but it has been for quite some time.\n\n-Peff\n"},{"id":"138965","messageId":"89030B4A18ECCD45978A3A6B639D1F24032A075390@FL01EXMB01.trad.tradestation.com","threadId":"23370","inReplyTo":"20100408043059.GA28768@coredump.intra.peff.net","subject":"RE: ghost refs","fromName":"John Dlugosz","fromEmail":"jdlugosz@tradestation.com","sentAt":"2010-04-08T16:07:18Z","receivedAt":"2010-04-08T16:07:18Z","isPatch":false,"sender":{"key":"jdlugosz@tradestation.com","avatar":null},"body":"> We create logs for remote branches when core.logallrefupdates is set\n> since e19b9dd (core.logallrefupdates: log remotes/ tracking branches.,\n> 2006-12-28).\n> \n> We turned on logallrefupdates by default in non-bare repositories in\n> 0bee591 (Enable reflogs by default in any repository with a working\n> directory., 2006-12-14).\n> \n> Both were in v1.5.0. So it used to not be the case that we created such\n> reflogs, but it has been for quite some time.\n> \n\nThanks, that's good to know, and reassuring since I was worried that some front-end tools were not using the flags as described in the tutorials.\n\nWho maintains the documentation?\n\nIn git-branch,\n\n\t-l\n\n\t    Create the branch's reflog. This activates recording of all changes made to the branch ref, \tenabling use of date based sha1 expressions such as \"<branchname>@{yesterday}\".\n\nthe implication is that if you don't use this flag, the feature is not enabled or activated.\n\n\nI do see upon reviewing the User's Manual etc. that it no longer tells you to use the -l flag.  That must have been revised since I learned it, a year or two ago.\n\n--John\n\n\n\n\n\n\n\nTradeStation Group, Inc. is a publicly-traded holding company (NASDAQ GS: TRAD) of three operating subsidiaries, TradeStation Securities, Inc. (Member NYSE, FINRA, SIPC and NFA), TradeStation Technologies, Inc., a trading software and subscription company, and TradeStation Europe Limited, a United Kingdom, FSA-authorized introducing brokerage firm. None of these companies provides trading or investment advice, recommendations or endorsements of any kind. The information transmitted is intended only for the person or entity to which it is addressed and may contain confidential and/or privileged material. Any review, retransmission, dissemination or other use of, or taking of any action in reliance upon, this information by persons or entities other than the intended recipient is prohibited. If you received this in error, please contact the sender and delete the material from any computer.\n"},{"id":"138969","messageId":"7vwrwh6fz8.fsf@alter.siamese.dyndns.org","threadId":"23370","inReplyTo":"89030B4A18ECCD45978A3A6B639D1F24032A075390@FL01EXMB01.trad.tradestation.com","subject":"Re: ghost refs","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-04-08T16:55:55Z","receivedAt":"2010-04-08T16:55:55Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"John Dlugosz <JDlugosz@TradeStation.com> writes:\n\n> In git-branch,\n>\n> \t-l\n>\n> \t    Create the branch's reflog. This activates recording of all\n> \t    changes made to the branch ref, enabling use of date based\n> \t    sha1 expressions such as \"<branchname>@{yesterday}\".\n\nThat is how you selectively enable reflog for that particular branch when\nyou have explicitly disabled \"reflog by default\" with the configuration.\n"},{"id":"138982","messageId":"20100408194908.GB4222@sigill.intra.peff.net","threadId":"23370","inReplyTo":"7vwrwh6fz8.fsf@alter.siamese.dyndns.org","subject":"Re: ghost refs","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2010-04-08T19:49:08Z","receivedAt":"2010-04-08T19:49:08Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Thu, Apr 08, 2010 at 09:55:55AM -0700, Junio C Hamano wrote:\n\n> John Dlugosz <JDlugosz@TradeStation.com> writes:\n> \n> > In git-branch,\n> >\n> > \t-l\n> >\n> > \t    Create the branch's reflog. This activates recording of all\n> > \t    changes made to the branch ref, enabling use of date based\n> > \t    sha1 expressions such as \"<branchname>@{yesterday}\".\n> \n> That is how you selectively enable reflog for that particular branch when\n> you have explicitly disabled \"reflog by default\" with the configuration.\n\nMaybe:\n\n-- >8 --\nSubject: [PATCH] docs: clarify \"branch -l\"\n\nThis option is mostly useless these days because we turn on\nreflogs by default in non-bare repos.\n\nSigned-off-by: Jeff King <peff@peff.net>\n---\n Documentation/git-branch.txt |    2 ++\n 1 files changed, 2 insertions(+), 0 deletions(-)\n\ndiff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt\nindex 903a690..d78f4c7 100644\n--- a/Documentation/git-branch.txt\n+++ b/Documentation/git-branch.txt\n@@ -72,6 +72,8 @@ OPTIONS\n \tCreate the branch's reflog.  This activates recording of\n \tall changes made to the branch ref, enabling use of date\n \tbased sha1 expressions such as \"<branchname>@\\{yesterday}\".\n+\tNote that in non-bare repositories, reflogs are usually\n+\tenabled by default by the `core.logallrefupdates` config option.\n \n -f::\n --force::\n-- \n1.7.1.rc0.248.g055378.dirty\n"},{"id":"138987","messageId":"7vbpdt65ie.fsf@alter.siamese.dyndns.org","threadId":"23370","inReplyTo":"20100408194908.GB4222@sigill.intra.peff.net","subject":"Re: ghost refs","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-04-08T20:42:01Z","receivedAt":"2010-04-08T20:42:01Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King <peff@peff.net> writes:\n\n> Maybe:\n>\n> -- >8 --\n> Subject: [PATCH] docs: clarify \"branch -l\"\n>\n> This option is mostly useless these days because we turn on\n> reflogs by default in non-bare repos.\n>\n> Signed-off-by: Jeff King <peff@peff.net>\n> ---\n>  Documentation/git-branch.txt |    2 ++\n>  1 files changed, 2 insertions(+), 0 deletions(-)\n>\n> diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt\n> index 903a690..d78f4c7 100644\n> --- a/Documentation/git-branch.txt\n> +++ b/Documentation/git-branch.txt\n> @@ -72,6 +72,8 @@ OPTIONS\n>  \tCreate the branch's reflog.  This activates recording of\n>  \tall changes made to the branch ref, enabling use of date\n>  \tbased sha1 expressions such as \"<branchname>@\\{yesterday}\".\n> +\tNote that in non-bare repositories, reflogs are usually\n> +\tenabled by default by the `core.logallrefupdates` config option.\n>  \n>  -f::\n>  --force::\n\nThat certainly is an improvement, but I've been wondering if it makes\nsense to also have a section in each commands the configuration variables\nthat affects the behaviour of the command.  core.logallrefupdates surely\nis not the only variable that affects how \"git branch\" behaves.\n\nWe might want to have a general concensus on what we want to have in the\ndocumentation.  As you noted, some have too sparse SYNOPSIS, while others\nhave full list of options.  Some mention configuration variables, while\nothers don't.  Some have extensive examples, while others lack any.\nOnce we know the general direction in which we are going, we can hand off\nthe actual documentation updates to the crowd ;-)\n\nI'll list my preference off the top of my head as a firestarter.\n\nNAME::\n\nThe name followed by what it is used for\n\nSYNOPSIS::\n\nI prefer to have (almost) complete set of options in SYNOPSIS, rather than\n\"command [<options>] <args>...\" which is next to useless.  This is\nespecially true for commands whose one set of options is incompatible with\nother set of options and arguments (e.g. there is no place for \"-b\" to\n\"checkout\" that checks out paths out of the index or a tree-ish).\n\nI also prefer not to list \"purely for backward compatibility\" options in\nSYNOPSIS section.\n\nDESCRIPTION::\n\nThe description section should first state what the command is used for,\niow, in which situation the user might want to use that command.\n\nOPTIONS::\n\nList of full options.  Some existing pages list them alphabetically, while\nothers list them in functional groups.  I prefer the latter which tends to\nmake the page more concise, and is more suited for people who got used to\nthe system (and remember, nobody stays to be a newbie forever, and people\nwho stay to be newbies forever are not our primary audience).\n\nDetailed discussion of concepts::\n\nSome manual pages need to have discussion of basic concepts that would not\nbe a good fit for the DESCRIPTION section (e.g. \"Detached HEAD\" section in\n\"checkout\" manual).  I am not sure if this kind of material is better\ngiven in OPTIONS section close to the functional group (e.g. \"History\nSiimplification\" heading in \"log\" manual).\n\n\nEXAMPLES::\n\nI prefer to make it mandatory for Porcelain command manual pages to have a\nlist of often used patterns that a reasonably intelligent person can guess\nhow to tweak to match the particular situation s/he is in.\n\n\nAUTHOR/DOCUMENTAITON::\n\nThese sections in most pages are not kept up to date, and I prefer to\nremove them altogether.  They do not help end users who never clone\ngit.git, and those who clone git.git will have shortlog to give them more\naccurate information.\n"},{"id":"138991","messageId":"p2w32541b131004081514s5a9e36b5uff79453c2f6b359e@mail.gmail.com","threadId":"23370","inReplyTo":"7vbpdt65ie.fsf@alter.siamese.dyndns.org","subject":"Re: ghost refs","fromName":"Avery Pennarun","fromEmail":"apenwarr@gmail.com","sentAt":"2010-04-08T22:14:13Z","receivedAt":"2010-04-08T22:14:13Z","isPatch":false,"sender":{"key":"apenwarr@gmail.com","avatar":"https://avatars.githubusercontent.com/u/20592?v=4"},"body":"On Thu, Apr 8, 2010 at 4:42 PM, Junio C Hamano <gitster@pobox.com> wrote:\n> That certainly is an improvement, but I've been wondering if it makes\n> sense to also have a section in each commands the configuration variables\n> that affects the behaviour of the command.  core.logallrefupdates surely\n> is not the only variable that affects how \"git branch\" behaves.\n\nI agree that you bring up a good point here.  I just hope you don't\nlose Jeff's (useful and improving) patch during the ensuing discussion\n:)\n\n> We might want to have a general concensus on what we want to have in the\n> documentation.  As you noted, some have too sparse SYNOPSIS, while others\n> have full list of options.  Some mention configuration variables, while\n> others don't.  Some have extensive examples, while others lack any.\n\nThe length of the synopsis section doesn't affect me much.  Mentioning\nthe equivalent config variable next to a command-line option, where\none exists, would probably be nice.\n\nIt might be okay to not actually describe in each manpage how the\nrelevant config options work; just referring people to git-config is\nprobably okay.  Having them all in git-config is useful in itself.\n\nAs for examples, well, people seem to really love examples.  So if\nsomeone sends a patch to add more examples, I'm hoping there's no\nreason to turn them down. :)\n\n> SYNOPSIS::\n>\n> I prefer to have (almost) complete set of options in SYNOPSIS, rather than\n> \"command [<options>] <args>...\" which is next to useless.  This is\n> especially true for commands whose one set of options is incompatible with\n> other set of options and arguments (e.g. there is no place for \"-b\" to\n> \"checkout\" that checks out paths out of the index or a tree-ish).\n\nI almost agree with you, except that nowadays there are *so* many\noptions that it doesn't really help much to have them all listed up\nthere.  It might be better to list only the most common ones.\n\nWhen the same command has multiple modes, I agree that it makes sense\nto list multiple synopses.\n\n> I also prefer not to list \"purely for backward compatibility\" options in\n> SYNOPSIS section.\n\nSure.\n\n> OPTIONS::\n>\n> List of full options.  Some existing pages list them alphabetically, while\n> others list them in functional groups.  I prefer the latter which tends to\n> make the page more concise, and is more suited for people who got used to\n> the system (and remember, nobody stays to be a newbie forever, and people\n> who stay to be newbies forever are not our primary audience).\n\nI actually get mildly annoyed when man pages don't list the options in\nalphabetical order, because I naturally start looking for them in that\norder.  But I can just as easily do a search for the option, so that's\nprobably just me being pointless.  In contrast, my pager can't help me\nsort out the options by functional group, so that's probably a more\nuseful way to do it.\n\nThat said, I don't think consistency here is much benefit.  It's okay\nif for some pages, functional groups aren't needed so alphabetical\norder is used as a fallback.\n\n> Detailed discussion of concepts::\n>\n> Some manual pages need to have discussion of basic concepts that would not\n> be a good fit for the DESCRIPTION section (e.g. \"Detached HEAD\" section in\n> \"checkout\" manual).  I am not sure if this kind of material is better\n> given in OPTIONS section close to the functional group (e.g. \"History\n> Siimplification\" heading in \"log\" manual).\n\nI think some pages have a DISCUSSION section right at the bottom,\nafter the description, options, and examples.  This seems like a good\nway to do it.  man pages should have concise stuff so you can find the\ninformation quickly, but there's nothing wrong with having detailed\nstuff further down.\n\n> EXAMPLES::\n>\n> I prefer to make it mandatory for Porcelain command manual pages to have a\n> list of often used patterns that a reasonably intelligent person can guess\n> how to tweak to match the particular situation s/he is in.\n\nTo be honest, I've often wished that the plumbing pages would also\nhave such detailed examples. :)\n\nWhich reminds me, it would be really great if somehow each command's\nmanual would describe a) whether it's plumbing or porcelain, and b)\nthe alternative to look for if what you *need* is plumbing or\nporcelain and the command is the wrong one.  But I don't know what a\ngood format for this information would be.\n\n> AUTHOR/DOCUMENTAITON::\n>\n> These sections in most pages are not kept up to date, and I prefer to\n> remove them altogether.  They do not help end users who never clone\n> git.git, and those who clone git.git will have shortlog to give them more\n> accurate information.\n\nI might be just being silly, but I really like seeing the Author\nsections, even though I know they're usually obsolete and/or wrong.\nIt just makes git seem more human somehow, like real people were\ninvolved in writing it.  I'm sure it results in Linus getting a bit\nmore credit than he deserves (it seems like the vast majority of man\npages name Linus as the/an author) but it's pleasant and seemingly\nharmless.\n\nHave fun,\n\nAvery\n"},{"id":"138992","messageId":"20100408230419.GA13704@vidovic","threadId":"23370","inReplyTo":"7vbpdt65ie.fsf@alter.siamese.dyndns.org","subject":"Re: ghost refs","fromName":"Nicolas Sebrecht","fromEmail":"nicolas.s.dev@gmx.fr","sentAt":"2010-04-08T23:04:19Z","receivedAt":"2010-04-08T23:04:19Z","isPatch":false,"sender":{"key":"nicolas.s.dev@gmx.fr","avatar":null},"body":"The 08/04/10, Junio C Hamano wrote:\n> \n> We might want to have a general concensus on what we want to have in the\n> documentation.\n\n<...>\n\n> I'll list my preference off the top of my head as a firestarter.\n\nNice. If a concensus is found for writing consistent documentation I\nthink it's worth to save in a file like Documentation/README or\nDocumentation/CONTRIBUTE.\n\n-- \nNicolas Sebrecht\n"},{"id":"139740","messageId":"20100417115111.GB28623@coredump.intra.peff.net","threadId":"23370","inReplyTo":"7vbpdt65ie.fsf@alter.siamese.dyndns.org","subject":"Re: ghost refs","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2010-04-17T11:51:11Z","receivedAt":"2010-04-17T11:51:11Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Thu, Apr 08, 2010 at 01:42:01PM -0700, Junio C Hamano wrote:\n\n> We might want to have a general concensus on what we want to have in the\n> documentation.  As you noted, some have too sparse SYNOPSIS, while others\n> have full list of options.  Some mention configuration variables, while\n> others don't.  Some have extensive examples, while others lack any.\n> Once we know the general direction in which we are going, we can hand off\n> the actual documentation updates to the crowd ;-)\n\nI would also like to have consensus on this, too. But it seems like it\ngets bikeshedded to death every time it comes up.  But hey, why not try\nit one more time? :)\n\n> I'll list my preference off the top of my head as a firestarter.\n> \n> NAME::\n> \n> The name followed by what it is used for\n\nYep, makes sense.\n\n> SYNOPSIS::\n> \n> I prefer to have (almost) complete set of options in SYNOPSIS, rather than\n> \"command [<options>] <args>...\" which is next to useless.  This is\n> especially true for commands whose one set of options is incompatible with\n> other set of options and arguments (e.g. there is no place for \"-b\" to\n> \"checkout\" that checks out paths out of the index or a tree-ish).\n\nI much prefer to have the \"major modes of operation\". So yes, \"command\n[<options>] <args>\" is useless. But\n\n  git log [<option>] [<since>..<until>] [[--] <path>...]\n\nis sparse but useful. You immediately get a sense of how to invoke the\ncommand, and it is very readable. If you were to put in the dozens of\npossible options, it would become hard to see what it is saying. If you\nwant a complete list of options (IMHO), they should be in list form.\n\nAs another example, for git-branch, I would suggest:\n\n  git branch [<options>]\n  git branch [<options>] <branchname> <start-point>\n  git branch -m [<oldbranch>] <newbranch>\n  git branch -d [<options>] <branchname>\n\n>From that I can quickly see that there are four major modes: listing,\ncreating a new branch, moving a branch, and deleting a branch. I would\nalso be happy if each mode was explicitly described. Some of my favorite\nsynopses are those of perl modules, which tend to give you a very short\nand readable code snippet of how you might use the module, along with\ncomments showing anything non-obvious.\n\nIn the case of branch, enumerating the options in the synopsis doesn't\nbother me much, because there are few enough that it remains fairly\nreadable. But something something like \"git format-patch\" or \"git apply\"\nare getting pretty long.\n\nI know that others disagree, though. When this came up last time, some\npeople said they really like having that giant clump of options. Our\nmanpages currently seem to be split between the two types.\n\n> I also prefer not to list \"purely for backward compatibility\" options in\n> SYNOPSIS section.\n\nDefinitely.\n\n> DESCRIPTION::\n> \n> The description section should first state what the command is used for,\n> iow, in which situation the user might want to use that command.\n\nYes. Also, it should probably discuss the different modes of operation\nif there is more than one.\n\n> OPTIONS::\n> \n> List of full options.  Some existing pages list them alphabetically, while\n> others list them in functional groups.  I prefer the latter which tends to\n> make the page more concise, and is more suited for people who got used to\n> the system (and remember, nobody stays to be a newbie forever, and people\n> who stay to be newbies forever are not our primary audience).\n\nI also prefer sorting by functionality. The only reason to prefer\nalphabetical is for people finding a specific option. Presumably their\npager has a search function (whereas for grouping by functionality, I\nagree with your conciseness argument, and it means you are more likely\nto find related options that might help you).\n\n> Detailed discussion of concepts::\n> \n> Some manual pages need to have discussion of basic concepts that would not\n> be a good fit for the DESCRIPTION section (e.g. \"Detached HEAD\" section in\n> \"checkout\" manual).  I am not sure if this kind of material is better\n> given in OPTIONS section close to the functional group (e.g. \"History\n> Siimplification\" heading in \"log\" manual).\n\nI would really prefer most of this material to be pushed out into its\nown manual pages, and referred to by name (e.g., say \"see\ngithistory(7) for a discussion of history simplification\" or \"history\nis simplified as described in githistory(7)\").\n\nHere's my reasoning.  There is a lot of overlap in git commands. The\nsame concepts come up in many places (e.g., revision traversal,\nformatting, and diff options in log, show, whatchanged, diff, diff-*,\netc). History simplification will come up in at least rev-list and log.\nSo our options are:\n\n  1. choose one place as the canonical location, and say \"see history\n     simplification in git-log(1)\" everywhere else.\n\n     This is annoying because the user has to find the right section in\n     git-log. For manpages, it would be nicer to just do \"man\n     githistory\", and for formats with hyperlinks, it should be a\n     hyperlink.\n\n  2. factor it out into history.txt, and include it in each relevant\n     page. This is what we do with pretty-formats.txt, diff-options, and\n     some others.\n\n     My problem with this approach is two-fold:\n\n       a. There is some value to naming the concept to the user. If I\n          read the \"git show\" page and then the \"git log\" page, I may\n          see that they both have pretty options. But it takes some\n          mental effort to see that they are identical and then reduce\n          it to \"both commands take the same pretty options\" in my mind.\n          But if we explicitly link, then we are saying \"there is a\n          concept called pretty options. You can use it here, and when\n          you see other places mention that concept, it is the same\n          thing.\" Which IMHO makes git easier to learn for new users;\n          they learn easily digestable concepts and build on them\n          instead of being overwhelmed with commands and options.\n\n        b. As an experienced user who already knows that \"pretty\n           formats\" is a concept, I find it annoying to have to find\n           them inside of git-log(1) when I want to see them. I would\n           much prefer to do \"man gitpretty\".\n\n        c. These subsegments can get long. pretty-formats.txt is 186\n           lines. That is a big chunk to be in my way if I am reading\n           git-log(1). I get to the \"pretty formats\" section and say\n           \"that is not interesting to me. What is the next section?\"\n           and then have to scroll down through 186 lines.\n\n  3. factor it into githistory(7), and reference it by name\n\n     Obviously this is my favorite. :) It does have one downside,\n     though. If we convert pretty-formats.txt into gitpretty(7), then\n     searching for \"oneline\" in git-log may not turn up what you want.\n     I wonder if we can summarize with something like:\n\n       --format=:\n       --pretty=<oneline|full|raw>:\n       --oneline:\n         Format the output. See gitpretty(7).\n\n    in git-log(1).\n\n> EXAMPLES::\n> \n> I prefer to make it mandatory for Porcelain command manual pages to have a\n> list of often used patterns that a reasonably intelligent person can guess\n> how to tweak to match the particular situation s/he is in.\n\nYes, examples are good.\n\n> AUTHOR/DOCUMENTAITON::\n> \n> These sections in most pages are not kept up to date, and I prefer to\n> remove them altogether.  They do not help end users who never clone\n> git.git, and those who clone git.git will have shortlog to give them more\n> accurate information.\n\nAgreed. I find them useless at best, clutter at worst.\n\n\nYou didn't mention configuration variables. I do think it would be\nbetter to have the variables for a specific command in that command's\nmanpage (in an ENVIRONMENT section that also mentions environment\nvariables). For variables that affect many commands, I would suggest\nfactoring them out as described above.\n\ngit-config (or perhaps even gitconfig(7)) should have a list of all\nvariables and where they are described, like:\n\n  apply.ignorewhitespace        git-apply(1)\n  apply.whitespace              git-apply(1)\n  branch.autosetupmerge         git-branch(1)\n  [etc]\n\nThere is not much point in having full descriptions in one giant list.\nInstead, you can peruse the whole list, and then go to the configuration\nsection of the relevant manpage to see a bunch of related options. Such\na list should be pretty easy to generate automatically from the other\ndocumentation.\n\n-Peff\n"},{"id":"139754","messageId":"7v8w8m3uqj.fsf@alter.siamese.dyndns.org","threadId":"23370","inReplyTo":"20100417115111.GB28623@coredump.intra.peff.net","subject":"Re: ghost refs","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-04-17T16:32:36Z","receivedAt":"2010-04-17T16:32:36Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King <peff@peff.net> writes:\n\n> I would also like to have consensus on this, too. But it seems like it\n> gets bikeshedded to death every time it comes up.  But hey, why not try\n> it one more time? :)\n>\n>> I'll list my preference off the top of my head as a firestarter.\n>> \n>> NAME::\n>> \n>> The name followed by what it is used for\n>\n> Yep, makes sense.\n>\n>> SYNOPSIS::\n> ...\n> As another example, for git-branch, I would suggest:\n>\n>   git branch [<options>]\n>   git branch [<options>] <branchname> <start-point>\n>   git branch -m [<oldbranch>] <newbranch>\n>   git branch -d [<options>] <branchname>\n>\n> From that I can quickly see that there are four major modes: listing,\n> creating a new branch, moving a branch, and deleting a branch. I would\n> also be happy if each mode was explicitly described. Some of my favorite\n> synopses are those of perl modules, which tend to give you a very short\n> and readable code snippet of how you might use the module, along with\n> comments showing anything non-obvious.\n\nYes, that makes a lot more sense than \"list every possible option\".\n\n>> Detailed discussion of concepts::\n>> \n>> Some manual pages need to have discussion of basic concepts that would not\n>> be a good fit for the DESCRIPTION section (e.g. \"Detached HEAD\" section in\n>> \"checkout\" manual).  I am not sure if this kind of material is better\n>> given in OPTIONS section close to the functional group (e.g. \"History\n>> Siimplification\" heading in \"log\" manual).\n>\n> I would really prefer most of this material to be pushed out into its\n> own manual pages, and referred to by name (e.g., say \"see\n> githistory(7) for a discussion of history simplification\" or \"history\n> is simplified as described in githistory(7)\").\n>\n> Here's my reasoning.  [jc: good summary of possible solutions skipped] \n> ...\n>   3. factor it into githistory(7), and reference it by name\n>\n>      Obviously this is my favorite. :) It does have one downside,\n>      though. If we convert pretty-formats.txt into gitpretty(7), then\n>      searching for \"oneline\" in git-log may not turn up what you want.\n>      I wonder if we can summarize with something like:\n>\n>        --format=:\n>        --pretty=<oneline|full|raw>:\n>        --oneline:\n>          Format the output. See gitpretty(7).\n>\n>     in git-log(1).\n\nI like the suggested outcome.\n\nOne way of doing this is to strip the description from pretty-format.txt\nand move the description to gitpretty.txt (and anything that supports\npretty format will continue to include pretty-format.txt).\n\nBut we will need to list _all_ the options twice if we go this route;\npretty-format.txt for the heading, and the descriptions in gitpretty.txt.\nPerhaps pretty-format.txt can be autogenerated from gitpretty.txt to keep\nthem in sync.\n\n> You didn't mention configuration variables.\n\nYeah, I forgot.\n\n> git-config (or perhaps even gitconfig(7)) should have a list of all\n> variables and where they are described, like:\n>\n>   apply.ignorewhitespace        git-apply(1)\n>   apply.whitespace              git-apply(1)\n>   branch.autosetupmerge         git-branch(1)\n>   [etc]\n>\n> There is not much point in having full descriptions in one giant list.\n> Instead, you can peruse the whole list, and then go to the configuration\n> section of the relevant manpage to see a bunch of related options. Such\n> a list should be pretty easy to generate automatically from the other\n> documentation.\n\nYes, I like it.\n"},{"id":"139758","messageId":"m3mxx2dnlu.fsf_-_@localhost.localdomain","threadId":"23370","inReplyTo":"7v8w8m3uqj.fsf@alter.siamese.dyndns.org","subject":"Re: Git documentation writing guidelines (was: Re: ghost refs)","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2010-04-17T16:57:40Z","receivedAt":"2010-04-17T16:57:40Z","isPatch":false,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"Junio C Hamano <gitster@pobox.com> writes:\n\n> Jeff King <peff@peff.net> writes:\n\n> > git-config (or perhaps even gitconfig(7)) should have a list of all\n> > variables and where they are described, like:\n> >\n> >   apply.ignorewhitespace        git-apply(1)\n> >   apply.whitespace              git-apply(1)\n> >   branch.autosetupmerge         git-branch(1)\n> >   [etc]\n> >\n> > There is not much point in having full descriptions in one giant list.\n> > Instead, you can peruse the whole list, and then go to the configuration\n> > section of the relevant manpage to see a bunch of related options. Such\n> > a list should be pretty easy to generate automatically from the other\n> > documentation.\n> \n> Yes, I like it.\n\nWell, there are some variables, like advice.*, or core.*, or alias.*, or\ncolor.*, or browser.<tool>.path, or i18n.*, or interactive.singlekey,\nor notes.*, or user.* that do not really belong to single git command\n(well, perhaps they could be put in git(1) manpage), or belong to more\nthan one command.\n\n-- \nJakub Narebski\nPoland\nShadeHawk on #git\n"},{"id":"139793","messageId":"7vtyr9y578.fsf@alter.siamese.dyndns.org","threadId":"23370","inReplyTo":"m3mxx2dnlu.fsf_-_@localhost.localdomain","subject":"Re: Git documentation writing guidelines","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-04-18T00:28:27Z","receivedAt":"2010-04-18T00:28:27Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jakub Narebski <jnareb@gmail.com> writes:\n\n> Junio C Hamano <gitster@pobox.com> writes:\n>\n>> Jeff King <peff@peff.net> writes:\n>\n>> > git-config (or perhaps even gitconfig(7)) should have a list of all\n>> > variables and where they are described, like:\n>> >\n>> >   apply.ignorewhitespace        git-apply(1)\n>> >   apply.whitespace              git-apply(1)\n>> >   branch.autosetupmerge         git-branch(1)\n>> >   [etc]\n>> >\n>> > There is not much point in having full descriptions in one giant list.\n>> > Instead, you can peruse the whole list, and then go to the configuration\n>> > section of the relevant manpage to see a bunch of related options. Such\n>> > a list should be pretty easy to generate automatically from the other\n>> > documentation.\n>> \n>> Yes, I like it.\n>\n> Well, there are some variables, like advice.*, or core.*, or alias.*, or\n> color.*, or browser.<tool>.path, or i18n.*, or interactive.singlekey,\n> or notes.*, or user.* that do not really belong to single git command\n> (well, perhaps they could be put in git(1) manpage), or belong to more\n> than one command.\n\nSo?\n\nNaturally they will be listed like:\n\n    alias.*\t\tgit(1)\n    color.diff.*\tgit-diff(1)\n    browser.*.path      git(1)\n    ...\n\nand I don't see a problem in the general structure Jeff suggested.\n\n    \n"},{"id":"139908","messageId":"89030B4A18ECCD45978A3A6B639D1F24032A523E62@FL01EXMB01.trad.tradestation.com","threadId":"23370","inReplyTo":"20100417115111.GB28623@coredump.intra.peff.net","subject":"RE: ghost refs","fromName":"John Dlugosz","fromEmail":"jdlugosz@tradestation.com","sentAt":"2010-04-19T15:33:17Z","receivedAt":"2010-04-19T15:33:17Z","isPatch":false,"sender":{"key":"jdlugosz@tradestation.com","avatar":null},"body":"If all the pages were poured into a wiki, then it would be easy for anyone to fuss with them when the mood hit.  It would also make it possible to consolidate the shared conceptual pages with hyperlinks.\n\nIdeally, the wiki engine should be able to spit out a set of static html/css files for inclusion on the local machine without a server.  A button on each page would switch to the live version of the page on the Internet, which would show current updates and offer editing capability, history, and discussion.\n\nPerhaps the documentation on the options could be entered abstractly, and the engine would automatically format the detailed list and any type of desired synopsis (alpha, categorical, long, short,...).\n\n--John\n\n> -----Original Message-----\n> From: Jeff King [mailto:peff@peff.net]\n> Sent: Saturday, April 17, 2010 6:51 AM\n> To: Junio C Hamano\n> Cc: John Dlugosz; git@vger.kernel.org; Avery Pennarun\n> Subject: Re: ghost refs\n> \n> On Thu, Apr 08, 2010 at 01:42:01PM -0700, Junio C Hamano wrote:\n> \n> > We might want to have a general concensus on what we want to have in\n> the\n> > documentation.  As you noted, some have too sparse SYNOPSIS, while\n> others\n> > have full list of options.  Some mention configuration variables,\n> while\n> > others don't.  Some have extensive examples, while others lack any.\n> > Once we know the general direction in which we are going, we can hand\n> off\n> > the actual documentation updates to the crowd ;-)\n> \n> I would also like to have consensus on this, too. But it seems like it\n> gets bikeshedded to death every time it comes up.  But hey, why not try\n> it one more time? :)\n> \n> > I'll list my preference off the top of my head as a firestarter.\n> >\n> > NAME::\n> >\n> > The name followed by what it is used for\n> \n> Yep, makes sense.\n> \n> > SYNOPSIS::\n> >\n> > I prefer to have (almost) complete set of options in SYNOPSIS, rather\n> than\n> > \"command [<options>] <args>...\" which is next to useless.  This is\n> > especially true for commands whose one set of options is incompatible\n> with\n> > other set of options and arguments (e.g. there is no place for \"-b\"\n> to\n> > \"checkout\" that checks out paths out of the index or a tree-ish).\n> \n> I much prefer to have the \"major modes of operation\". So yes, \"command\n> [<options>] <args>\" is useless. But\n> \n>   git log [<option>] [<since>..<until>] [[--] <path>...]\n> \n> is sparse but useful. You immediately get a sense of how to invoke the\n> command, and it is very readable. If you were to put in the dozens of\n> possible options, it would become hard to see what it is saying. If you\n> want a complete list of options (IMHO), they should be in list form.\n> \n> As another example, for git-branch, I would suggest:\n> \n>   git branch [<options>]\n>   git branch [<options>] <branchname> <start-point>\n>   git branch -m [<oldbranch>] <newbranch>\n>   git branch -d [<options>] <branchname>\n> \n> From that I can quickly see that there are four major modes: listing,\n> creating a new branch, moving a branch, and deleting a branch. I would\n> also be happy if each mode was explicitly described. Some of my\n> favorite\n> synopses are those of perl modules, which tend to give you a very short\n> and readable code snippet of how you might use the module, along with\n> comments showing anything non-obvious.\n> \n> In the case of branch, enumerating the options in the synopsis doesn't\n> bother me much, because there are few enough that it remains fairly\n> readable. But something something like \"git format-patch\" or \"git\n> apply\"\n> are getting pretty long.\n> \n> I know that others disagree, though. When this came up last time, some\n> people said they really like having that giant clump of options. Our\n> manpages currently seem to be split between the two types.\n> \n> > I also prefer not to list \"purely for backward compatibility\" options\n> in\n> > SYNOPSIS section.\n> \n> Definitely.\n> \n> > DESCRIPTION::\n> >\n> > The description section should first state what the command is used\n> for,\n> > iow, in which situation the user might want to use that command.\n> \n> Yes. Also, it should probably discuss the different modes of operation\n> if there is more than one.\n> \n> > OPTIONS::\n> >\n> > List of full options.  Some existing pages list them alphabetically,\n> while\n> > others list them in functional groups.  I prefer the latter which\n> tends to\n> > make the page more concise, and is more suited for people who got\n> used to\n> > the system (and remember, nobody stays to be a newbie forever, and\n> people\n> > who stay to be newbies forever are not our primary audience).\n> \n> I also prefer sorting by functionality. The only reason to prefer\n> alphabetical is for people finding a specific option. Presumably their\n> pager has a search function (whereas for grouping by functionality, I\n> agree with your conciseness argument, and it means you are more likely\n> to find related options that might help you).\n> \n> > Detailed discussion of concepts::\n> >\n> > Some manual pages need to have discussion of basic concepts that\n> would not\n> > be a good fit for the DESCRIPTION section (e.g. \"Detached HEAD\"\n> section in\n> > \"checkout\" manual).  I am not sure if this kind of material is better\n> > given in OPTIONS section close to the functional group (e.g. \"History\n> > Siimplification\" heading in \"log\" manual).\n> \n> I would really prefer most of this material to be pushed out into its\n> own manual pages, and referred to by name (e.g., say \"see\n> githistory(7) for a discussion of history simplification\" or \"history\n> is simplified as described in githistory(7)\").\n> \n> Here's my reasoning.  There is a lot of overlap in git commands. The\n> same concepts come up in many places (e.g., revision traversal,\n> formatting, and diff options in log, show, whatchanged, diff, diff-*,\n> etc). History simplification will come up in at least rev-list and log.\n> So our options are:\n> \n>   1. choose one place as the canonical location, and say \"see history\n>      simplification in git-log(1)\" everywhere else.\n> \n>      This is annoying because the user has to find the right section in\n>      git-log. For manpages, it would be nicer to just do \"man\n>      githistory\", and for formats with hyperlinks, it should be a\n>      hyperlink.\n> \n>   2. factor it out into history.txt, and include it in each relevant\n>      page. This is what we do with pretty-formats.txt, diff-options,\n> and\n>      some others.\n> \n>      My problem with this approach is two-fold:\n> \n>        a. There is some value to naming the concept to the user. If I\n>           read the \"git show\" page and then the \"git log\" page, I may\n>           see that they both have pretty options. But it takes some\n>           mental effort to see that they are identical and then reduce\n>           it to \"both commands take the same pretty options\" in my\n> mind.\n>           But if we explicitly link, then we are saying \"there is a\n>           concept called pretty options. You can use it here, and when\n>           you see other places mention that concept, it is the same\n>           thing.\" Which IMHO makes git easier to learn for new users;\n>           they learn easily digestable concepts and build on them\n>           instead of being overwhelmed with commands and options.\n> \n>         b. As an experienced user who already knows that \"pretty\n>            formats\" is a concept, I find it annoying to have to find\n>            them inside of git-log(1) when I want to see them. I would\n>            much prefer to do \"man gitpretty\".\n> \n>         c. These subsegments can get long. pretty-formats.txt is 186\n>            lines. That is a big chunk to be in my way if I am reading\n>            git-log(1). I get to the \"pretty formats\" section and say\n>            \"that is not interesting to me. What is the next section?\"\n>            and then have to scroll down through 186 lines.\n> \n>   3. factor it into githistory(7), and reference it by name\n> \n>      Obviously this is my favorite. :) It does have one downside,\n>      though. If we convert pretty-formats.txt into gitpretty(7), then\n>      searching for \"oneline\" in git-log may not turn up what you want.\n>      I wonder if we can summarize with something like:\n> \n>        --format=:\n>        --pretty=<oneline|full|raw>:\n>        --oneline:\n>          Format the output. See gitpretty(7).\n> \n>     in git-log(1).\n> \n> > EXAMPLES::\n> >\n> > I prefer to make it mandatory for Porcelain command manual pages to\n> have a\n> > list of often used patterns that a reasonably intelligent person can\n> guess\n> > how to tweak to match the particular situation s/he is in.\n> \n> Yes, examples are good.\n> \n> > AUTHOR/DOCUMENTAITON::\n> >\n> > These sections in most pages are not kept up to date, and I prefer to\n> > remove them altogether.  They do not help end users who never clone\n> > git.git, and those who clone git.git will have shortlog to give them\n> more\n> > accurate information.\n> \n> Agreed. I find them useless at best, clutter at worst.\n> \n> \n> You didn't mention configuration variables. I do think it would be\n> better to have the variables for a specific command in that command's\n> manpage (in an ENVIRONMENT section that also mentions environment\n> variables). For variables that affect many commands, I would suggest\n> factoring them out as described above.\n> \n> git-config (or perhaps even gitconfig(7)) should have a list of all\n> variables and where they are described, like:\n> \n>   apply.ignorewhitespace        git-apply(1)\n>   apply.whitespace              git-apply(1)\n>   branch.autosetupmerge         git-branch(1)\n>   [etc]\n> \n> There is not much point in having full descriptions in one giant list.\n> Instead, you can peruse the whole list, and then go to the\n> configuration\n> section of the relevant manpage to see a bunch of related options. Such\n> a list should be pretty easy to generate automatically from the other\n> documentation.\n> \n> -Peff\n\nTradeStation Group, Inc. is a publicly-traded holding company (NASDAQ GS: TRAD) of three operating subsidiaries, TradeStation Securities, Inc. (Member NYSE, FINRA, SIPC and NFA), TradeStation Technologies, Inc., a trading software and subscription company, and TradeStation Europe Limited, a United Kingdom, FSA-authorized introducing brokerage firm. None of these companies provides trading or investment advice, recommendations or endorsements of any kind. The information transmitted is intended only for the person or entity to which it is addressed and may contain confidential and/or privileged material. Any review, retransmission, dissemination or other use of, or taking of any action in reliance upon, this information by persons or entities other than the intended recipient is prohibited. If you received this in error, please contact the sender and delete the material from any computer.\n"},{"id":"139953","messageId":"loom.20100420T085842-887@post.gmane.org","threadId":"23370","inReplyTo":"20100407210010.GB27012@coredump.intra.peff.net","subject":"Re: ghost refs","fromName":"Yann Dirson","fromEmail":"yann.dirson@bertin.fr","sentAt":"2010-04-20T07:02:05Z","receivedAt":"2010-04-20T07:02:05Z","isPatch":false,"sender":{"key":"yann.dirson@bertin.fr","avatar":null},"body":"Jeff King <peff <at> peff.net> writes:\n> On Wed, Apr 07, 2010 at 12:58:33PM -0400, Avery Pennarun wrote:\n> \n> > This is on purpose, based on the theory that you don't want to lose\n> > data from your local repo just because someone (accidentally?) deletes\n> > a branch on the remote server.  Unfortunately, this theory is a bit\n> > flawed, since someone could just as easily overwrite the remote branch\n> > with a totally different commit, and you'd still lose it in *that*\n> > case.  So mostly it's just confusing.\n> \n> You do have a reflog in the case of overwrite. Delete kills off any\n> associated reflog (it would be cool if we had a \"graveyard\" reflog that\n> kept deleted branch reflogs around for a while).\n\nWouldn't it jus be sufficient to keep reflogs on branch deletion, and let reflog\nentries subject be expired by gc just like for any branch, so that way we may\nonly need to gc the reflog itself when it becomes empty ?\n\n-- \nYann\n"},{"id":"139966","messageId":"20100420115124.GB22907@coredump.intra.peff.net","threadId":"23370","inReplyTo":"loom.20100420T085842-887@post.gmane.org","subject":"Re: ghost refs","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2010-04-20T11:51:24Z","receivedAt":"2010-04-20T11:51:24Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Tue, Apr 20, 2010 at 07:02:05AM +0000, Yann Dirson wrote:\n\n> > You do have a reflog in the case of overwrite. Delete kills off any\n> > associated reflog (it would be cool if we had a \"graveyard\" reflog that\n> > kept deleted branch reflogs around for a while).\n> \n> Wouldn't it jus be sufficient to keep reflogs on branch deletion, and\n> let reflog entries subject be expired by gc just like for any branch,\n> so that way we may only need to gc the reflog itself when it becomes\n> empty ?\n\nAlmost. The complication is that a branch \"foo\" prevents any branch\n\"foo/bar\" from being created. So if you leave the reflog in place, you\nare blocking the creation of the reflog for a new branch.\n\nSo you need some solution to that problem. Things I thought of are:\n\n  1. Leave the reflog in place until such a foo/bar branch is created.\n     But that means branch creation unexpectedly kills off old unrelated\n     reflog entries. Combingin user surprise and destruction of data is\n     probably bad.\n\n  2. Make a refs/dead hierarchy so that the reflogs don't interfere with\n     new branches. This just pushes off the problem, though, for when\n     you try to delete \"foo/bar\" and see that \"refs/dead/foo\" is already\n     blocking its spot in the reflog graveyard.\n\n  3. Stick everything in a big \"graveyard\" reflog. I think there are\n     some complications here with the reflog format, though. Namely:\n\n       - reflog entries don't actually name the ref they're on. We could\n         munge the comment field to add the name of the ref as we put\n         them in the graveyard ref.\n\n       - entries just have a timestamp, and I think we assume they're in\n         order. So I guess we can merge-sort the old graveyard ref with\n         what we're adding to keep things in order. But it means you\n         will have entries from various refs interspersed. I guess that\n         is OK, though, as it's not unlike the HEAD reflog.\n\nSo (3) seems like the only viable option to me, but I would be happy to\nhear alternatives.\n\n-Peff\n"},{"id":"139967","messageId":"20100420120228.GM17930@lake.fysh.org","threadId":"23370","inReplyTo":"20100420115124.GB22907@coredump.intra.peff.net","subject":"Re: ghost refs","fromName":"Zefram","fromEmail":"zefram@fysh.org","sentAt":"2010-04-20T12:02:28Z","receivedAt":"2010-04-20T12:02:28Z","isPatch":false,"sender":{"key":"zefram@fysh.org","avatar":null},"body":"Jeff King wrote:\n>  2. Make a refs/dead hierarchy so that the reflogs don't interfere with\n>     new branches. This just pushes off the problem, though, for when\n>     you try to delete \"foo/bar\" and see that \"refs/dead/foo\" is already\n>     blocking its spot in the reflog graveyard.\n\nThis is easily solved by tweaking the name for dead reflogs.\nlogs/dead_refs/foo~ doesn't clash with logs/dead_refs/foo/bar~.\n\nYou might also want to stick a sequence number into the filename, for\nwhen you delete more than one foo/bar branch.\n\n-zefram\n"},{"id":"139972","messageId":"20100420150015.4bd80387@chalon.bertin.fr","threadId":"23370","inReplyTo":"20100420120228.GM17930@lake.fysh.org","subject":"Re: ghost refs","fromName":"Yann Dirson","fromEmail":"dirson@bertin.fr","sentAt":"2010-04-20T13:00:15Z","receivedAt":"2010-04-20T13:00:15Z","isPatch":false,"sender":{"key":"dirson@bertin.fr","avatar":null},"body":"Le Tue, 20 Apr 2010 13:02:28 +0100,\nZefram <zefram@fysh.org> a écrit :\n\n> Jeff King wrote:\n> >  2. Make a refs/dead hierarchy so that the reflogs don't interfere\n> > with new branches. This just pushes off the problem, though, for\n> > when you try to delete \"foo/bar\" and see that \"refs/dead/foo\" is\n> > already blocking its spot in the reflog graveyard.\n> \n> This is easily solved by tweaking the name for dead reflogs.\n> logs/dead_refs/foo~ doesn't clash with logs/dead_refs/foo/bar~.\n>\n> You might also want to stick a sequence number into the filename, for\n> when you delete more than one foo/bar branch.\n\nThat sounds cool.  A logs/dead_refs/ namespace of some sort seems to be\nunavoidable, to avoid the clash between old \"logs/refs/foo/bar~\"\nand new \"logs/refs/foo\".\n\nWe would also need a syntax for accessing those.  Maybe something\nreminiscent of Debian \"epochs\" in version number.  That would\ngive a syntax like \"foo@{1:1}\" and \"foo@{2:1}\" to access the dead and\nlong-dead refs' logs, respectively looking into foo~<largest> and\nfoo~<largest-1>.\n\nGoing that way, we would probably want to add a \"delete\" entries in the\nreflog when deleting a ref - but that would make \"foo@{1:0}\" a\nnon-sense, we could just reject it.\n\n\nAnother option than adding a sequence number would be to move back the\ndead_refs/ log back to refs/ when the branch is creating again.  That\nway just after resurection we have:\n\n\tfoo@{0}\t: now\n\tfoo@{1} : invalid (deleted state)\n\tfoo@{2} : the ref as it was 2 operations before\n\nThat would kinda make sense too, but then if the new \"foo\" is something\ncompletely unrelated, we may rather want to refer to foo{1:1}\n(which is stable until next deletion of foo) rather than foo@{2}, which\nvaries with current foo.  But the 1st solution could give us that too,\nby considering logs/dead_refs/foo~ the logical continuation of\nlogs/refs/foo.\n\nWould that make sense ?\n-- \nYann\n"},{"id":"139973","messageId":"20100420131447.GN17930@lake.fysh.org","threadId":"23370","inReplyTo":"20100420150015.4bd80387@chalon.bertin.fr","subject":"Re: ghost refs","fromName":"Zefram","fromEmail":"zefram@fysh.org","sentAt":"2010-04-20T13:14:47Z","receivedAt":"2010-04-20T13:14:47Z","isPatch":false,"sender":{"key":"zefram@fysh.org","avatar":null},"body":"Yann Dirson wrote:\n>Another option than adding a sequence number would be to move back the\n>dead_refs/ log back to refs/ when the branch is creating again.\n\nYes, that also makes sense.  Pick one model or the other.  A mixture\nwould *not* make sense.\n\n-zefram\n"},{"id":"139974","messageId":"s2m76718491004200633la1cb07a6n8bc0d8d8e71b4e92@mail.gmail.com","threadId":"23370","inReplyTo":"20100420115124.GB22907@coredump.intra.peff.net","subject":"Re: ghost refs","fromName":"Jay Soffian","fromEmail":"jaysoffian@gmail.com","sentAt":"2010-04-20T13:33:42Z","receivedAt":"2010-04-20T13:33:42Z","isPatch":false,"sender":{"key":"jaysoffian@gmail.com","avatar":"https://avatars.githubusercontent.com/u/155970?v=4"},"body":"On Tue, Apr 20, 2010 at 7:51 AM, Jeff King <peff@peff.net> wrote:\n> Almost. The complication is that a branch \"foo\" prevents any branch\n> \"foo/bar\" from being created. So if you leave the reflog in place, you\n> are blocking the creation of the reflog for a new branch.\n>\n> So you need some solution to that problem. Things I thought of are:\n>\n>  1. Leave the reflog in place until such a foo/bar branch is created.\n>     [...]\n>  2. Make a refs/dead hierarchy so that the reflogs don't interfere with\n>     [...]\n>  3. Stick everything in a big \"graveyard\" reflog. I think there are\n>     [...]\n\n4. Just append to the existing reflog? Given:\n\n$ git checkout -b topic origin/master # 1\n$ git add; git commit ...\n$ git checkout master\n$ git merge topic\n$ git branch -d topic\n$ git checkout -b topic origin/master # 2\n\nWhose to say that the branch named topic from (1) and the branch named\ntopic from (2) are unrelated? Isn't the fact that they have the same\nname is an indication that they are likely to be related. And even if\nthey are unrelated, what's wrong with re-using the same reflog?\n\nWouldn't it be obvious what happened? e.g.:\n\n64c7587 topic@{0}: branch: Created from HEAD\nabcdef3 topic@{1}: branch: deleted topic    <---- I made this one up\n3568c4b topic@{2}: commit: turned the knob to 11\n707d9fb topic@{3}: branch: Created from HEAD\n\nj.\n"},{"id":"139976","messageId":"20100420142444.GA8851@coredump.intra.peff.net","threadId":"23370","inReplyTo":"s2m76718491004200633la1cb07a6n8bc0d8d8e71b4e92@mail.gmail.com","subject":"Re: ghost refs","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2010-04-20T14:24:44Z","receivedAt":"2010-04-20T14:24:44Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Tue, Apr 20, 2010 at 09:33:42AM -0400, Jay Soffian wrote:\n\n> 4. Just append to the existing reflog? Given:\n> \n> $ git checkout -b topic origin/master # 1\n> $ git add; git commit ...\n> $ git checkout master\n> $ git merge topic\n> $ git branch -d topic\n> $ git checkout -b topic origin/master # 2\n\nI like how the user would interact with that, but what happens with:\n\n  git checkout -b topic/subtopic\n\nThe reflog of the deleted branch is in the way.\n\n-Peff\n"},{"id":"139978","messageId":"20100420164225.1400c280@chalon.bertin.fr","threadId":"23370","inReplyTo":"20100420142444.GA8851@coredump.intra.peff.net","subject":"Re: ghost refs","fromName":"Yann Dirson","fromEmail":"dirson@bertin.fr","sentAt":"2010-04-20T14:42:25Z","receivedAt":"2010-04-20T14:42:25Z","isPatch":false,"sender":{"key":"dirson@bertin.fr","avatar":null},"body":"Le Tue, 20 Apr 2010 10:24:44 -0400,\nJeff King <peff@peff.net> a écrit :\n\n> On Tue, Apr 20, 2010 at 09:33:42AM -0400, Jay Soffian wrote:\n> \n> > 4. Just append to the existing reflog? Given:\n> > \n> > $ git checkout -b topic origin/master # 1\n> > $ git add; git commit ...\n> > $ git checkout master\n> > $ git merge topic\n> > $ git branch -d topic\n> > $ git checkout -b topic origin/master # 2\n> \n> I like how the user would interact with that, but what happens with:\n> \n>   git checkout -b topic/subtopic\n> \n> The reflog of the deleted branch is in the way.\n\nThat would be addressed by considering logs/dead_refs/* contents\n*logical* continuations of logs/refs/* (bottom-most suggestion in my\nother email)\n\n-- \nYann\n"},{"id":"139980","messageId":"g2u76718491004200752gcf73abf1se05e89bd605e77a@mail.gmail.com","threadId":"23370","inReplyTo":"20100420142444.GA8851@coredump.intra.peff.net","subject":"Re: ghost refs","fromName":"Jay Soffian","fromEmail":"jaysoffian@gmail.com","sentAt":"2010-04-20T14:52:42Z","receivedAt":"2010-04-20T14:52:42Z","isPatch":false,"sender":{"key":"jaysoffian@gmail.com","avatar":"https://avatars.githubusercontent.com/u/155970?v=4"},"body":"On Tue, Apr 20, 2010 at 10:24 AM, Jeff King <peff@peff.net> wrote:\n> On Tue, Apr 20, 2010 at 09:33:42AM -0400, Jay Soffian wrote:\n> I like how the user would interact with that, but what happens with:\n>\n>  git checkout -b topic/subtopic\n>\n> The reflog of the deleted branch is in the way.\n\nHandle it just as gracefully as we do today. This is what happens when\nyou try to create a branch with a similar collision:\n\n$ git branch foo/bar\n$ git branch foo\nerror: there are still refs under 'refs/heads/foo'\nfatal: Failed to lock ref for update: Is a directory\n\nSo the reflog analog would be:\n\n$ git branch topic/subtopic\nerror: there are still logs under 'logs/refs/heads/topic'\nfatal: Failed to lock log for update: Is a directory\n\nI think it's an edge case; thus I think it's okay to fail as long as\nwe give a reasonable error and a way to rename it.\n\nj.\n"},{"id":"139981","messageId":"n2u81b0412b1004200803j578e834czfa8775110fb794eb@mail.gmail.com","threadId":"23370","inReplyTo":"g2u76718491004200752gcf73abf1se05e89bd605e77a@mail.gmail.com","subject":"Re: ghost refs","fromName":"Alex Riesen","fromEmail":"raa.lkml@gmail.com","sentAt":"2010-04-20T15:03:18Z","receivedAt":"2010-04-20T15:03:18Z","isPatch":false,"sender":{"key":"raa.lkml@gmail.com","avatar":"https://avatars.githubusercontent.com/u/324101?v=4"},"body":"On Tue, Apr 20, 2010 at 16:52, Jay Soffian <jaysoffian@gmail.com> wrote:\n> On Tue, Apr 20, 2010 at 10:24 AM, Jeff King <peff@peff.net> wrote:\n>> On Tue, Apr 20, 2010 at 09:33:42AM -0400, Jay Soffian wrote:\n>> I like how the user would interact with that, but what happens with:\n>>\n>>  git checkout -b topic/subtopic\n>>\n>> The reflog of the deleted branch is in the way.\n>\n> Handle it just as gracefully as we do today. This is what happens when\n> you try to create a branch with a similar collision:\n>\n> $ git branch foo/bar\n> $ git branch foo\n> error: there are still refs under 'refs/heads/foo'\n> fatal: Failed to lock ref for update: Is a directory\n>\n> So the reflog analog would be:\n>\n> $ git branch topic/subtopic\n> error: there are still logs under 'logs/refs/heads/topic'\n> fatal: Failed to lock log for update: Is a directory\n>\n> I think it's an edge case; thus I think it's okay to fail as long as\n> we give a reasonable error and a way to rename it.\n\nNo it is not. Creation of the reflog is not the purpose of\ngit branch operation (creation of the branch itself is).\nIt will be just annoyance, especially if the user will\nhave to do a rename which could be done automatically.\n"},{"id":"139982","messageId":"20100420151014.GA11785@coredump.intra.peff.net","threadId":"23370","inReplyTo":"g2u76718491004200752gcf73abf1se05e89bd605e77a@mail.gmail.com","subject":"Re: ghost refs","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2010-04-20T15:10:14Z","receivedAt":"2010-04-20T15:10:14Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Tue, Apr 20, 2010 at 10:52:42AM -0400, Jay Soffian wrote:\n\n> On Tue, Apr 20, 2010 at 10:24 AM, Jeff King <peff@peff.net> wrote:\n> > On Tue, Apr 20, 2010 at 09:33:42AM -0400, Jay Soffian wrote:\n> > I like how the user would interact with that, but what happens with:\n> >\n> >  git checkout -b topic/subtopic\n> >\n> > The reflog of the deleted branch is in the way.\n> \n> Handle it just as gracefully as we do today. This is what happens when\n> you try to create a branch with a similar collision:\n> \n> $ git branch foo/bar\n> $ git branch foo\n> error: there are still refs under 'refs/heads/foo'\n> fatal: Failed to lock ref for update: Is a directory\n\nYeah, but my next step would be \"branch -d foo/bar\"; under your proposal\nthat no longer works. Now I have to do \"branch -m foo/bar foobar\" where\n\"foobar\" is some name that I know means \"the old reflog for foo/bar\".\n\nSo I think it makes more sense to come up with that naming scheme\nourselves and make using it semi-transparent.\n\n> $ git branch topic/subtopic\n> error: there are still logs under 'logs/refs/heads/topic'\n> fatal: Failed to lock log for update: Is a directory\n> \n> I think it's an edge case; thus I think it's okay to fail as long as\n> we give a reasonable error and a way to rename it.\n\nIt is an edge-case, but I'd rather just have a scheme that works nicely\nin the normal case and \"degrades\" only in the error case. Like if\ncreating \"foo/bar\" we see that we have \"foo\", but that the last reflog\nentry is deletion, we move \"foo\" to \"foo-1\" or something. It's ugly, but\nit just doesn't come up that much.\n\n-Peff\n"}]}