* ghost refs @ 2010-04-07 16:38 John Dlugosz 2010-04-07 16:58 ` Avery Pennarun 0 siblings, 1 reply; 30+ messages in thread From: John Dlugosz @ 2010-04-07 16:38 UTC (permalink / raw) To: git 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". --John (sorry about the footer) TradeStation 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. ^ permalink raw reply [flat|nested] 30+ messages in thread
* Re: ghost refs 2010-04-07 16:38 ghost refs John Dlugosz @ 2010-04-07 16:58 ` Avery Pennarun 2010-04-07 21:00 ` Jeff King 0 siblings, 1 reply; 30+ messages in thread From: Avery Pennarun @ 2010-04-07 16:58 UTC (permalink / raw) To: John Dlugosz; +Cc: git On Wed, Apr 7, 2010 at 12:38 PM, John Dlugosz <JDlugosz@tradestation.com> wrote: > 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". This is on purpose, based on the theory that you don't want to lose data from your local repo just because someone (accidentally?) deletes a branch on the remote server. Unfortunately, this theory is a bit flawed, since someone could just as easily overwrite the remote branch with a totally different commit, and you'd still lose it in *that* case. So mostly it's just confusing. Anyway, what you want is "git remote prune origin". Have fun, Avery ^ permalink raw reply [flat|nested] 30+ messages in thread
* Re: ghost refs 2010-04-07 16:58 ` Avery Pennarun @ 2010-04-07 21:00 ` Jeff King 2010-04-07 22:00 ` John Dlugosz 2010-04-20 7:02 ` Yann Dirson 0 siblings, 2 replies; 30+ messages in thread From: Jeff King @ 2010-04-07 21:00 UTC (permalink / raw) To: Avery Pennarun; +Cc: John Dlugosz, git On Wed, Apr 07, 2010 at 12:58:33PM -0400, Avery Pennarun wrote: > This is on purpose, based on the theory that you don't want to lose > data from your local repo just because someone (accidentally?) deletes > a branch on the remote server. Unfortunately, this theory is a bit > flawed, since someone could just as easily overwrite the remote branch > with a totally different commit, and you'd still lose it in *that* > case. So mostly it's just confusing. You do have a reflog in the case of overwrite. Delete kills off any associated reflog (it would be cool if we had a "graveyard" reflog that kept deleted branch reflogs around for a while). > Anyway, what you want is "git remote prune origin". Yep. I think there is "git fetch --prune" these days, too. We could perhaps add a config option if there isn't one already (I didn't look) so this happens automatically. -Peff ^ permalink raw reply [flat|nested] 30+ messages in thread
* RE: ghost refs 2010-04-07 21:00 ` Jeff King @ 2010-04-07 22:00 ` John Dlugosz 2010-04-07 22:03 ` Avery Pennarun 2010-04-20 7:02 ` Yann Dirson 1 sibling, 1 reply; 30+ messages in thread From: John Dlugosz @ 2010-04-07 22:00 UTC (permalink / raw) Cc: git > You do have a reflog in the case of overwrite. Delete kills off any > associated reflog (it would be cool if we had a "graveyard" reflog > that kept deleted branch reflogs around for a while). Hmm, 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. Someone 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. So, 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? --John TradeStation 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. ^ permalink raw reply [flat|nested] 30+ messages in thread
* Re: ghost refs 2010-04-07 22:00 ` John Dlugosz @ 2010-04-07 22:03 ` Avery Pennarun 2010-04-07 22:10 ` John Dlugosz 0 siblings, 1 reply; 30+ messages in thread From: Avery Pennarun @ 2010-04-07 22:03 UTC (permalink / raw) To: John Dlugosz; +Cc: git On Wed, Apr 7, 2010 at 6:00 PM, John Dlugosz <JDlugosz@tradestation.com> wrote: >> You do have a reflog in the case of overwrite. Delete kills off any >> associated reflog (it would be cool if we had a "graveyard" reflog >> that kept deleted branch reflogs around for a while). > > Hmm, I thought you only had reflogs on your local branches, not the remote branches. This used to be true, but I have confirmed that with the latest version of git, remote refs have reflogs (as they should for safety). Have fun, Avery ^ permalink raw reply [flat|nested] 30+ messages in thread
* RE: ghost refs 2010-04-07 22:03 ` Avery Pennarun @ 2010-04-07 22:10 ` John Dlugosz 2010-04-07 22:11 ` Avery Pennarun 0 siblings, 1 reply; 30+ messages in thread From: John Dlugosz @ 2010-04-07 22:10 UTC (permalink / raw) To: Avery Pennarun; +Cc: git 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? > -----Original Message----- > From: Avery Pennarun [mailto:apenwarr@gmail.com] > Sent: Wednesday, April 07, 2010 5:03 PM > To: John Dlugosz > Cc: git@vger.kernel.org > Subject: Re: ghost refs > > On Wed, Apr 7, 2010 at 6:00 PM, John Dlugosz > <JDlugosz@tradestation.com> wrote: > >> You do have a reflog in the case of overwrite. Delete kills off any > >> associated reflog (it would be cool if we had a "graveyard" reflog > >> that kept deleted branch reflogs around for a while). > > > > Hmm, I thought you only had reflogs on your local branches, not the > remote branches. > > This used to be true, but I have confirmed that with the latest > version of git, remote refs have reflogs (as they should for safety). > > Have fun, > > Avery TradeStation 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. ^ permalink raw reply [flat|nested] 30+ messages in thread
* Re: ghost refs 2010-04-07 22:10 ` John Dlugosz @ 2010-04-07 22:11 ` Avery Pennarun 2010-04-08 4:30 ` Jeff King 0 siblings, 1 reply; 30+ messages in thread From: Avery Pennarun @ 2010-04-07 22:11 UTC (permalink / raw) To: John Dlugosz; +Cc: git On Wed, Apr 7, 2010 at 6:10 PM, John Dlugosz <JDlugosz@tradestation.com> wrote: > 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? Why not try it and find out? I've never asked for a reflog explicitly and I seem to get them. Avery ^ permalink raw reply [flat|nested] 30+ messages in thread
* Re: ghost refs 2010-04-07 22:11 ` Avery Pennarun @ 2010-04-08 4:30 ` Jeff King 2010-04-08 16:07 ` John Dlugosz 0 siblings, 1 reply; 30+ messages in thread From: Jeff King @ 2010-04-08 4:30 UTC (permalink / raw) To: Avery Pennarun; +Cc: John Dlugosz, git On Wed, Apr 07, 2010 at 06:11:38PM -0400, Avery Pennarun wrote: > On Wed, Apr 7, 2010 at 6:10 PM, John Dlugosz <JDlugosz@tradestation.com> wrote: > > 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? > > Why not try it and find out? > > I've never asked for a reflog explicitly and I seem to get them. We create logs for remote branches when core.logallrefupdates is set since e19b9dd (core.logallrefupdates: log remotes/ tracking branches., 2006-12-28). We turned on logallrefupdates by default in non-bare repositories in 0bee591 (Enable reflogs by default in any repository with a working directory., 2006-12-14). Both were in v1.5.0. So it used to not be the case that we created such reflogs, but it has been for quite some time. -Peff ^ permalink raw reply [flat|nested] 30+ messages in thread
* RE: ghost refs 2010-04-08 4:30 ` Jeff King @ 2010-04-08 16:07 ` John Dlugosz 2010-04-08 16:55 ` Junio C Hamano 0 siblings, 1 reply; 30+ messages in thread From: John Dlugosz @ 2010-04-08 16:07 UTC (permalink / raw) Cc: git > We create logs for remote branches when core.logallrefupdates is set > since e19b9dd (core.logallrefupdates: log remotes/ tracking branches., > 2006-12-28). > > We turned on logallrefupdates by default in non-bare repositories in > 0bee591 (Enable reflogs by default in any repository with a working > directory., 2006-12-14). > > Both were in v1.5.0. So it used to not be the case that we created such > reflogs, but it has been for quite some time. > Thanks, 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. Who maintains the documentation? In git-branch, -l Create the branch's reflog. This activates recording of all changes made to the branch ref, enabling use of date based sha1 expressions such as "<branchname>@{yesterday}". the implication is that if you don't use this flag, the feature is not enabled or activated. I 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. --John TradeStation 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. ^ permalink raw reply [flat|nested] 30+ messages in thread
* Re: ghost refs 2010-04-08 16:07 ` John Dlugosz @ 2010-04-08 16:55 ` Junio C Hamano 2010-04-08 19:49 ` Jeff King 0 siblings, 1 reply; 30+ messages in thread From: Junio C Hamano @ 2010-04-08 16:55 UTC (permalink / raw) To: John Dlugosz; +Cc: Jeff King, git, Avery Pennarun John Dlugosz <JDlugosz@TradeStation.com> writes: > In git-branch, > > -l > > Create the branch's reflog. This activates recording of all > changes made to the branch ref, enabling use of date based > sha1 expressions such as "<branchname>@{yesterday}". That is how you selectively enable reflog for that particular branch when you have explicitly disabled "reflog by default" with the configuration. ^ permalink raw reply [flat|nested] 30+ messages in thread
* Re: ghost refs 2010-04-08 16:55 ` Junio C Hamano @ 2010-04-08 19:49 ` Jeff King 2010-04-08 20:42 ` Junio C Hamano 0 siblings, 1 reply; 30+ messages in thread From: Jeff King @ 2010-04-08 19:49 UTC (permalink / raw) To: Junio C Hamano; +Cc: John Dlugosz, git, Avery Pennarun On Thu, Apr 08, 2010 at 09:55:55AM -0700, Junio C Hamano wrote: > John Dlugosz <JDlugosz@TradeStation.com> writes: > > > In git-branch, > > > > -l > > > > Create the branch's reflog. This activates recording of all > > changes made to the branch ref, enabling use of date based > > sha1 expressions such as "<branchname>@{yesterday}". > > That is how you selectively enable reflog for that particular branch when > you have explicitly disabled "reflog by default" with the configuration. Maybe: -- >8 -- Subject: [PATCH] docs: clarify "branch -l" This option is mostly useless these days because we turn on reflogs by default in non-bare repos. Signed-off-by: Jeff King <peff@peff.net> --- Documentation/git-branch.txt | 2 ++ 1 files changed, 2 insertions(+), 0 deletions(-) diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index 903a690..d78f4c7 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -72,6 +72,8 @@ OPTIONS Create the branch's reflog. This activates recording of all changes made to the branch ref, enabling use of date based sha1 expressions such as "<branchname>@\{yesterday}". + Note that in non-bare repositories, reflogs are usually + enabled by default by the `core.logallrefupdates` config option. -f:: --force:: -- 1.7.1.rc0.248.g055378.dirty ^ permalink raw reply related [flat|nested] 30+ messages in thread
* Re: ghost refs 2010-04-08 19:49 ` Jeff King @ 2010-04-08 20:42 ` Junio C Hamano 2010-04-08 22:14 ` Avery Pennarun ` (2 more replies) 0 siblings, 3 replies; 30+ messages in thread From: Junio C Hamano @ 2010-04-08 20:42 UTC (permalink / raw) To: Jeff King; +Cc: John Dlugosz, git, Avery Pennarun Jeff King <peff@peff.net> writes: > Maybe: > > -- >8 -- > Subject: [PATCH] docs: clarify "branch -l" > > This option is mostly useless these days because we turn on > reflogs by default in non-bare repos. > > Signed-off-by: Jeff King <peff@peff.net> > --- > Documentation/git-branch.txt | 2 ++ > 1 files changed, 2 insertions(+), 0 deletions(-) > > diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt > index 903a690..d78f4c7 100644 > --- a/Documentation/git-branch.txt > +++ b/Documentation/git-branch.txt > @@ -72,6 +72,8 @@ OPTIONS > Create the branch's reflog. This activates recording of > all changes made to the branch ref, enabling use of date > based sha1 expressions such as "<branchname>@\{yesterday}". > + Note that in non-bare repositories, reflogs are usually > + enabled by default by the `core.logallrefupdates` config option. > > -f:: > --force:: That certainly is an improvement, but I've been wondering if it makes sense to also have a section in each commands the configuration variables that affects the behaviour of the command. core.logallrefupdates surely is not the only variable that affects how "git branch" behaves. We might want to have a general concensus on what we want to have in the documentation. As you noted, some have too sparse SYNOPSIS, while others have full list of options. Some mention configuration variables, while others don't. Some have extensive examples, while others lack any. Once we know the general direction in which we are going, we can hand off the actual documentation updates to the crowd ;-) I'll list my preference off the top of my head as a firestarter. NAME:: The name followed by what it is used for SYNOPSIS:: I prefer to have (almost) complete set of options in SYNOPSIS, rather than "command [<options>] <args>..." which is next to useless. This is especially true for commands whose one set of options is incompatible with other set of options and arguments (e.g. there is no place for "-b" to "checkout" that checks out paths out of the index or a tree-ish). I also prefer not to list "purely for backward compatibility" options in SYNOPSIS section. DESCRIPTION:: The description section should first state what the command is used for, iow, in which situation the user might want to use that command. OPTIONS:: List of full options. Some existing pages list them alphabetically, while others list them in functional groups. I prefer the latter which tends to make the page more concise, and is more suited for people who got used to the system (and remember, nobody stays to be a newbie forever, and people who stay to be newbies forever are not our primary audience). Detailed discussion of concepts:: Some manual pages need to have discussion of basic concepts that would not be a good fit for the DESCRIPTION section (e.g. "Detached HEAD" section in "checkout" manual). I am not sure if this kind of material is better given in OPTIONS section close to the functional group (e.g. "History Siimplification" heading in "log" manual). EXAMPLES:: I prefer to make it mandatory for Porcelain command manual pages to have a list of often used patterns that a reasonably intelligent person can guess how to tweak to match the particular situation s/he is in. AUTHOR/DOCUMENTAITON:: These sections in most pages are not kept up to date, and I prefer to remove them altogether. They do not help end users who never clone git.git, and those who clone git.git will have shortlog to give them more accurate information. ^ permalink raw reply [flat|nested] 30+ messages in thread
* Re: ghost refs 2010-04-08 20:42 ` Junio C Hamano @ 2010-04-08 22:14 ` Avery Pennarun 2010-04-08 23:04 ` Nicolas Sebrecht 2010-04-17 11:51 ` Jeff King 2 siblings, 0 replies; 30+ messages in thread From: Avery Pennarun @ 2010-04-08 22:14 UTC (permalink / raw) To: Junio C Hamano; +Cc: Jeff King, John Dlugosz, git On Thu, Apr 8, 2010 at 4:42 PM, Junio C Hamano <gitster@pobox.com> wrote: > That certainly is an improvement, but I've been wondering if it makes > sense to also have a section in each commands the configuration variables > that affects the behaviour of the command. core.logallrefupdates surely > is not the only variable that affects how "git branch" behaves. I agree that you bring up a good point here. I just hope you don't lose Jeff's (useful and improving) patch during the ensuing discussion :) > We might want to have a general concensus on what we want to have in the > documentation. As you noted, some have too sparse SYNOPSIS, while others > have full list of options. Some mention configuration variables, while > others don't. Some have extensive examples, while others lack any. The length of the synopsis section doesn't affect me much. Mentioning the equivalent config variable next to a command-line option, where one exists, would probably be nice. It might be okay to not actually describe in each manpage how the relevant config options work; just referring people to git-config is probably okay. Having them all in git-config is useful in itself. As for examples, well, people seem to really love examples. So if someone sends a patch to add more examples, I'm hoping there's no reason to turn them down. :) > SYNOPSIS:: > > I prefer to have (almost) complete set of options in SYNOPSIS, rather than > "command [<options>] <args>..." which is next to useless. This is > especially true for commands whose one set of options is incompatible with > other set of options and arguments (e.g. there is no place for "-b" to > "checkout" that checks out paths out of the index or a tree-ish). I almost agree with you, except that nowadays there are *so* many options that it doesn't really help much to have them all listed up there. It might be better to list only the most common ones. When the same command has multiple modes, I agree that it makes sense to list multiple synopses. > I also prefer not to list "purely for backward compatibility" options in > SYNOPSIS section. Sure. > OPTIONS:: > > List of full options. Some existing pages list them alphabetically, while > others list them in functional groups. I prefer the latter which tends to > make the page more concise, and is more suited for people who got used to > the system (and remember, nobody stays to be a newbie forever, and people > who stay to be newbies forever are not our primary audience). I actually get mildly annoyed when man pages don't list the options in alphabetical order, because I naturally start looking for them in that order. But I can just as easily do a search for the option, so that's probably just me being pointless. In contrast, my pager can't help me sort out the options by functional group, so that's probably a more useful way to do it. That said, I don't think consistency here is much benefit. It's okay if for some pages, functional groups aren't needed so alphabetical order is used as a fallback. > Detailed discussion of concepts:: > > Some manual pages need to have discussion of basic concepts that would not > be a good fit for the DESCRIPTION section (e.g. "Detached HEAD" section in > "checkout" manual). I am not sure if this kind of material is better > given in OPTIONS section close to the functional group (e.g. "History > Siimplification" heading in "log" manual). I think some pages have a DISCUSSION section right at the bottom, after the description, options, and examples. This seems like a good way to do it. man pages should have concise stuff so you can find the information quickly, but there's nothing wrong with having detailed stuff further down. > EXAMPLES:: > > I prefer to make it mandatory for Porcelain command manual pages to have a > list of often used patterns that a reasonably intelligent person can guess > how to tweak to match the particular situation s/he is in. To be honest, I've often wished that the plumbing pages would also have such detailed examples. :) Which reminds me, it would be really great if somehow each command's manual would describe a) whether it's plumbing or porcelain, and b) the alternative to look for if what you *need* is plumbing or porcelain and the command is the wrong one. But I don't know what a good format for this information would be. > AUTHOR/DOCUMENTAITON:: > > These sections in most pages are not kept up to date, and I prefer to > remove them altogether. They do not help end users who never clone > git.git, and those who clone git.git will have shortlog to give them more > accurate information. I might be just being silly, but I really like seeing the Author sections, even though I know they're usually obsolete and/or wrong. It just makes git seem more human somehow, like real people were involved in writing it. I'm sure it results in Linus getting a bit more credit than he deserves (it seems like the vast majority of man pages name Linus as the/an author) but it's pleasant and seemingly harmless. Have fun, Avery ^ permalink raw reply [flat|nested] 30+ messages in thread
* Re: ghost refs 2010-04-08 20:42 ` Junio C Hamano 2010-04-08 22:14 ` Avery Pennarun @ 2010-04-08 23:04 ` Nicolas Sebrecht 2010-04-17 11:51 ` Jeff King 2 siblings, 0 replies; 30+ messages in thread From: Nicolas Sebrecht @ 2010-04-08 23:04 UTC (permalink / raw) To: Junio C Hamano Cc: Jeff King, John Dlugosz, git, Avery Pennarun, Nicolas Sebrecht The 08/04/10, Junio C Hamano wrote: > > We might want to have a general concensus on what we want to have in the > documentation. <...> > I'll list my preference off the top of my head as a firestarter. Nice. If a concensus is found for writing consistent documentation I think it's worth to save in a file like Documentation/README or Documentation/CONTRIBUTE. -- Nicolas Sebrecht ^ permalink raw reply [flat|nested] 30+ messages in thread
* Re: ghost refs 2010-04-08 20:42 ` Junio C Hamano 2010-04-08 22:14 ` Avery Pennarun 2010-04-08 23:04 ` Nicolas Sebrecht @ 2010-04-17 11:51 ` Jeff King 2010-04-17 16:32 ` Junio C Hamano 2010-04-19 15:33 ` ghost refs John Dlugosz 2 siblings, 2 replies; 30+ messages in thread From: Jeff King @ 2010-04-17 11:51 UTC (permalink / raw) To: Junio C Hamano; +Cc: John Dlugosz, git, Avery Pennarun On Thu, Apr 08, 2010 at 01:42:01PM -0700, Junio C Hamano wrote: > We might want to have a general concensus on what we want to have in the > documentation. As you noted, some have too sparse SYNOPSIS, while others > have full list of options. Some mention configuration variables, while > others don't. Some have extensive examples, while others lack any. > Once we know the general direction in which we are going, we can hand off > the actual documentation updates to the crowd ;-) I would also like to have consensus on this, too. But it seems like it gets bikeshedded to death every time it comes up. But hey, why not try it one more time? :) > I'll list my preference off the top of my head as a firestarter. > > NAME:: > > The name followed by what it is used for Yep, makes sense. > SYNOPSIS:: > > I prefer to have (almost) complete set of options in SYNOPSIS, rather than > "command [<options>] <args>..." which is next to useless. This is > especially true for commands whose one set of options is incompatible with > other set of options and arguments (e.g. there is no place for "-b" to > "checkout" that checks out paths out of the index or a tree-ish). I much prefer to have the "major modes of operation". So yes, "command [<options>] <args>" is useless. But git log [<option>] [<since>..<until>] [[--] <path>...] is sparse but useful. You immediately get a sense of how to invoke the command, and it is very readable. If you were to put in the dozens of possible options, it would become hard to see what it is saying. If you want a complete list of options (IMHO), they should be in list form. As another example, for git-branch, I would suggest: git branch [<options>] git branch [<options>] <branchname> <start-point> git branch -m [<oldbranch>] <newbranch> git branch -d [<options>] <branchname> >From that I can quickly see that there are four major modes: listing, creating a new branch, moving a branch, and deleting a branch. I would also be happy if each mode was explicitly described. Some of my favorite synopses are those of perl modules, which tend to give you a very short and readable code snippet of how you might use the module, along with comments showing anything non-obvious. In the case of branch, enumerating the options in the synopsis doesn't bother me much, because there are few enough that it remains fairly readable. But something something like "git format-patch" or "git apply" are getting pretty long. I know that others disagree, though. When this came up last time, some people said they really like having that giant clump of options. Our manpages currently seem to be split between the two types. > I also prefer not to list "purely for backward compatibility" options in > SYNOPSIS section. Definitely. > DESCRIPTION:: > > The description section should first state what the command is used for, > iow, in which situation the user might want to use that command. Yes. Also, it should probably discuss the different modes of operation if there is more than one. > OPTIONS:: > > List of full options. Some existing pages list them alphabetically, while > others list them in functional groups. I prefer the latter which tends to > make the page more concise, and is more suited for people who got used to > the system (and remember, nobody stays to be a newbie forever, and people > who stay to be newbies forever are not our primary audience). I also prefer sorting by functionality. The only reason to prefer alphabetical is for people finding a specific option. Presumably their pager has a search function (whereas for grouping by functionality, I agree with your conciseness argument, and it means you are more likely to find related options that might help you). > Detailed discussion of concepts:: > > Some manual pages need to have discussion of basic concepts that would not > be a good fit for the DESCRIPTION section (e.g. "Detached HEAD" section in > "checkout" manual). I am not sure if this kind of material is better > given in OPTIONS section close to the functional group (e.g. "History > Siimplification" heading in "log" manual). I would really prefer most of this material to be pushed out into its own manual pages, and referred to by name (e.g., say "see githistory(7) for a discussion of history simplification" or "history is simplified as described in githistory(7)"). Here's my reasoning. There is a lot of overlap in git commands. The same concepts come up in many places (e.g., revision traversal, formatting, and diff options in log, show, whatchanged, diff, diff-*, etc). History simplification will come up in at least rev-list and log. So our options are: 1. choose one place as the canonical location, and say "see history simplification in git-log(1)" everywhere else. This is annoying because the user has to find the right section in git-log. For manpages, it would be nicer to just do "man githistory", and for formats with hyperlinks, it should be a hyperlink. 2. factor it out into history.txt, and include it in each relevant page. This is what we do with pretty-formats.txt, diff-options, and some others. My problem with this approach is two-fold: a. There is some value to naming the concept to the user. If I read the "git show" page and then the "git log" page, I may see that they both have pretty options. But it takes some mental effort to see that they are identical and then reduce it to "both commands take the same pretty options" in my mind. But if we explicitly link, then we are saying "there is a concept called pretty options. You can use it here, and when you see other places mention that concept, it is the same thing." Which IMHO makes git easier to learn for new users; they learn easily digestable concepts and build on them instead of being overwhelmed with commands and options. b. As an experienced user who already knows that "pretty formats" is a concept, I find it annoying to have to find them inside of git-log(1) when I want to see them. I would much prefer to do "man gitpretty". c. These subsegments can get long. pretty-formats.txt is 186 lines. That is a big chunk to be in my way if I am reading git-log(1). I get to the "pretty formats" section and say "that is not interesting to me. What is the next section?" and then have to scroll down through 186 lines. 3. factor it into githistory(7), and reference it by name Obviously this is my favorite. :) It does have one downside, though. If we convert pretty-formats.txt into gitpretty(7), then searching for "oneline" in git-log may not turn up what you want. I wonder if we can summarize with something like: --format=: --pretty=<oneline|full|raw>: --oneline: Format the output. See gitpretty(7). in git-log(1). > EXAMPLES:: > > I prefer to make it mandatory for Porcelain command manual pages to have a > list of often used patterns that a reasonably intelligent person can guess > how to tweak to match the particular situation s/he is in. Yes, examples are good. > AUTHOR/DOCUMENTAITON:: > > These sections in most pages are not kept up to date, and I prefer to > remove them altogether. They do not help end users who never clone > git.git, and those who clone git.git will have shortlog to give them more > accurate information. Agreed. I find them useless at best, clutter at worst. You didn't mention configuration variables. I do think it would be better to have the variables for a specific command in that command's manpage (in an ENVIRONMENT section that also mentions environment variables). For variables that affect many commands, I would suggest factoring them out as described above. git-config (or perhaps even gitconfig(7)) should have a list of all variables and where they are described, like: apply.ignorewhitespace git-apply(1) apply.whitespace git-apply(1) branch.autosetupmerge git-branch(1) [etc] There is not much point in having full descriptions in one giant list. Instead, you can peruse the whole list, and then go to the configuration section of the relevant manpage to see a bunch of related options. Such a list should be pretty easy to generate automatically from the other documentation. -Peff ^ permalink raw reply [flat|nested] 30+ messages in thread
* Re: ghost refs 2010-04-17 11:51 ` Jeff King @ 2010-04-17 16:32 ` Junio C Hamano 2010-04-17 16:57 ` Git documentation writing guidelines (was: Re: ghost refs) Jakub Narebski 2010-04-19 15:33 ` ghost refs John Dlugosz 1 sibling, 1 reply; 30+ messages in thread From: Junio C Hamano @ 2010-04-17 16:32 UTC (permalink / raw) To: Jeff King; +Cc: John Dlugosz, git, Avery Pennarun Jeff King <peff@peff.net> writes: > I would also like to have consensus on this, too. But it seems like it > gets bikeshedded to death every time it comes up. But hey, why not try > it one more time? :) > >> I'll list my preference off the top of my head as a firestarter. >> >> NAME:: >> >> The name followed by what it is used for > > Yep, makes sense. > >> SYNOPSIS:: > ... > As another example, for git-branch, I would suggest: > > git branch [<options>] > git branch [<options>] <branchname> <start-point> > git branch -m [<oldbranch>] <newbranch> > git branch -d [<options>] <branchname> > > From that I can quickly see that there are four major modes: listing, > creating a new branch, moving a branch, and deleting a branch. I would > also be happy if each mode was explicitly described. Some of my favorite > synopses are those of perl modules, which tend to give you a very short > and readable code snippet of how you might use the module, along with > comments showing anything non-obvious. Yes, that makes a lot more sense than "list every possible option". >> Detailed discussion of concepts:: >> >> Some manual pages need to have discussion of basic concepts that would not >> be a good fit for the DESCRIPTION section (e.g. "Detached HEAD" section in >> "checkout" manual). I am not sure if this kind of material is better >> given in OPTIONS section close to the functional group (e.g. "History >> Siimplification" heading in "log" manual). > > I would really prefer most of this material to be pushed out into its > own manual pages, and referred to by name (e.g., say "see > githistory(7) for a discussion of history simplification" or "history > is simplified as described in githistory(7)"). > > Here's my reasoning. [jc: good summary of possible solutions skipped] > ... > 3. factor it into githistory(7), and reference it by name > > Obviously this is my favorite. :) It does have one downside, > though. If we convert pretty-formats.txt into gitpretty(7), then > searching for "oneline" in git-log may not turn up what you want. > I wonder if we can summarize with something like: > > --format=: > --pretty=<oneline|full|raw>: > --oneline: > Format the output. See gitpretty(7). > > in git-log(1). I like the suggested outcome. One way of doing this is to strip the description from pretty-format.txt and move the description to gitpretty.txt (and anything that supports pretty format will continue to include pretty-format.txt). But we will need to list _all_ the options twice if we go this route; pretty-format.txt for the heading, and the descriptions in gitpretty.txt. Perhaps pretty-format.txt can be autogenerated from gitpretty.txt to keep them in sync. > You didn't mention configuration variables. Yeah, I forgot. > git-config (or perhaps even gitconfig(7)) should have a list of all > variables and where they are described, like: > > apply.ignorewhitespace git-apply(1) > apply.whitespace git-apply(1) > branch.autosetupmerge git-branch(1) > [etc] > > There is not much point in having full descriptions in one giant list. > Instead, you can peruse the whole list, and then go to the configuration > section of the relevant manpage to see a bunch of related options. Such > a list should be pretty easy to generate automatically from the other > documentation. Yes, I like it. ^ permalink raw reply [flat|nested] 30+ messages in thread
* Re: Git documentation writing guidelines (was: Re: ghost refs) 2010-04-17 16:32 ` Junio C Hamano @ 2010-04-17 16:57 ` Jakub Narebski 2010-04-18 0:28 ` Git documentation writing guidelines Junio C Hamano 0 siblings, 1 reply; 30+ messages in thread From: Jakub Narebski @ 2010-04-17 16:57 UTC (permalink / raw) To: Junio C Hamano; +Cc: Jeff King, John Dlugosz, git, Avery Pennarun Junio C Hamano <gitster@pobox.com> writes: > Jeff King <peff@peff.net> writes: > > git-config (or perhaps even gitconfig(7)) should have a list of all > > variables and where they are described, like: > > > > apply.ignorewhitespace git-apply(1) > > apply.whitespace git-apply(1) > > branch.autosetupmerge git-branch(1) > > [etc] > > > > There is not much point in having full descriptions in one giant list. > > Instead, you can peruse the whole list, and then go to the configuration > > section of the relevant manpage to see a bunch of related options. Such > > a list should be pretty easy to generate automatically from the other > > documentation. > > Yes, I like it. Well, there are some variables, like advice.*, or core.*, or alias.*, or color.*, or browser.<tool>.path, or i18n.*, or interactive.singlekey, or notes.*, or user.* that do not really belong to single git command (well, perhaps they could be put in git(1) manpage), or belong to more than one command. -- Jakub Narebski Poland ShadeHawk on #git ^ permalink raw reply [flat|nested] 30+ messages in thread
* Re: Git documentation writing guidelines 2010-04-17 16:57 ` Git documentation writing guidelines (was: Re: ghost refs) Jakub Narebski @ 2010-04-18 0:28 ` Junio C Hamano 0 siblings, 0 replies; 30+ messages in thread From: Junio C Hamano @ 2010-04-18 0:28 UTC (permalink / raw) To: Jakub Narebski Cc: Junio C Hamano, Jeff King, John Dlugosz, git, Avery Pennarun Jakub Narebski <jnareb@gmail.com> writes: > Junio C Hamano <gitster@pobox.com> writes: > >> Jeff King <peff@peff.net> writes: > >> > git-config (or perhaps even gitconfig(7)) should have a list of all >> > variables and where they are described, like: >> > >> > apply.ignorewhitespace git-apply(1) >> > apply.whitespace git-apply(1) >> > branch.autosetupmerge git-branch(1) >> > [etc] >> > >> > There is not much point in having full descriptions in one giant list. >> > Instead, you can peruse the whole list, and then go to the configuration >> > section of the relevant manpage to see a bunch of related options. Such >> > a list should be pretty easy to generate automatically from the other >> > documentation. >> >> Yes, I like it. > > Well, there are some variables, like advice.*, or core.*, or alias.*, or > color.*, or browser.<tool>.path, or i18n.*, or interactive.singlekey, > or notes.*, or user.* that do not really belong to single git command > (well, perhaps they could be put in git(1) manpage), or belong to more > than one command. So? Naturally they will be listed like: alias.* git(1) color.diff.* git-diff(1) browser.*.path git(1) ... and I don't see a problem in the general structure Jeff suggested. ^ permalink raw reply [flat|nested] 30+ messages in thread
* RE: ghost refs 2010-04-17 11:51 ` Jeff King 2010-04-17 16:32 ` Junio C Hamano @ 2010-04-19 15:33 ` John Dlugosz 1 sibling, 0 replies; 30+ messages in thread From: John Dlugosz @ 2010-04-19 15:33 UTC (permalink / raw) To: Jeff King, Junio C Hamano; +Cc: git, Avery Pennarun 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. Ideally, 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. Perhaps 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,...). --John > -----Original Message----- > From: Jeff King [mailto:peff@peff.net] > Sent: Saturday, April 17, 2010 6:51 AM > To: Junio C Hamano > Cc: John Dlugosz; git@vger.kernel.org; Avery Pennarun > Subject: Re: ghost refs > > On Thu, Apr 08, 2010 at 01:42:01PM -0700, Junio C Hamano wrote: > > > We might want to have a general concensus on what we want to have in > the > > documentation. As you noted, some have too sparse SYNOPSIS, while > others > > have full list of options. Some mention configuration variables, > while > > others don't. Some have extensive examples, while others lack any. > > Once we know the general direction in which we are going, we can hand > off > > the actual documentation updates to the crowd ;-) > > I would also like to have consensus on this, too. But it seems like it > gets bikeshedded to death every time it comes up. But hey, why not try > it one more time? :) > > > I'll list my preference off the top of my head as a firestarter. > > > > NAME:: > > > > The name followed by what it is used for > > Yep, makes sense. > > > SYNOPSIS:: > > > > I prefer to have (almost) complete set of options in SYNOPSIS, rather > than > > "command [<options>] <args>..." which is next to useless. This is > > especially true for commands whose one set of options is incompatible > with > > other set of options and arguments (e.g. there is no place for "-b" > to > > "checkout" that checks out paths out of the index or a tree-ish). > > I much prefer to have the "major modes of operation". So yes, "command > [<options>] <args>" is useless. But > > git log [<option>] [<since>..<until>] [[--] <path>...] > > is sparse but useful. You immediately get a sense of how to invoke the > command, and it is very readable. If you were to put in the dozens of > possible options, it would become hard to see what it is saying. If you > want a complete list of options (IMHO), they should be in list form. > > As another example, for git-branch, I would suggest: > > git branch [<options>] > git branch [<options>] <branchname> <start-point> > git branch -m [<oldbranch>] <newbranch> > git branch -d [<options>] <branchname> > > From that I can quickly see that there are four major modes: listing, > creating a new branch, moving a branch, and deleting a branch. I would > also be happy if each mode was explicitly described. Some of my > favorite > synopses are those of perl modules, which tend to give you a very short > and readable code snippet of how you might use the module, along with > comments showing anything non-obvious. > > In the case of branch, enumerating the options in the synopsis doesn't > bother me much, because there are few enough that it remains fairly > readable. But something something like "git format-patch" or "git > apply" > are getting pretty long. > > I know that others disagree, though. When this came up last time, some > people said they really like having that giant clump of options. Our > manpages currently seem to be split between the two types. > > > I also prefer not to list "purely for backward compatibility" options > in > > SYNOPSIS section. > > Definitely. > > > DESCRIPTION:: > > > > The description section should first state what the command is used > for, > > iow, in which situation the user might want to use that command. > > Yes. Also, it should probably discuss the different modes of operation > if there is more than one. > > > OPTIONS:: > > > > List of full options. Some existing pages list them alphabetically, > while > > others list them in functional groups. I prefer the latter which > tends to > > make the page more concise, and is more suited for people who got > used to > > the system (and remember, nobody stays to be a newbie forever, and > people > > who stay to be newbies forever are not our primary audience). > > I also prefer sorting by functionality. The only reason to prefer > alphabetical is for people finding a specific option. Presumably their > pager has a search function (whereas for grouping by functionality, I > agree with your conciseness argument, and it means you are more likely > to find related options that might help you). > > > Detailed discussion of concepts:: > > > > Some manual pages need to have discussion of basic concepts that > would not > > be a good fit for the DESCRIPTION section (e.g. "Detached HEAD" > section in > > "checkout" manual). I am not sure if this kind of material is better > > given in OPTIONS section close to the functional group (e.g. "History > > Siimplification" heading in "log" manual). > > I would really prefer most of this material to be pushed out into its > own manual pages, and referred to by name (e.g., say "see > githistory(7) for a discussion of history simplification" or "history > is simplified as described in githistory(7)"). > > Here's my reasoning. There is a lot of overlap in git commands. The > same concepts come up in many places (e.g., revision traversal, > formatting, and diff options in log, show, whatchanged, diff, diff-*, > etc). History simplification will come up in at least rev-list and log. > So our options are: > > 1. choose one place as the canonical location, and say "see history > simplification in git-log(1)" everywhere else. > > This is annoying because the user has to find the right section in > git-log. For manpages, it would be nicer to just do "man > githistory", and for formats with hyperlinks, it should be a > hyperlink. > > 2. factor it out into history.txt, and include it in each relevant > page. This is what we do with pretty-formats.txt, diff-options, > and > some others. > > My problem with this approach is two-fold: > > a. There is some value to naming the concept to the user. If I > read the "git show" page and then the "git log" page, I may > see that they both have pretty options. But it takes some > mental effort to see that they are identical and then reduce > it to "both commands take the same pretty options" in my > mind. > But if we explicitly link, then we are saying "there is a > concept called pretty options. You can use it here, and when > you see other places mention that concept, it is the same > thing." Which IMHO makes git easier to learn for new users; > they learn easily digestable concepts and build on them > instead of being overwhelmed with commands and options. > > b. As an experienced user who already knows that "pretty > formats" is a concept, I find it annoying to have to find > them inside of git-log(1) when I want to see them. I would > much prefer to do "man gitpretty". > > c. These subsegments can get long. pretty-formats.txt is 186 > lines. That is a big chunk to be in my way if I am reading > git-log(1). I get to the "pretty formats" section and say > "that is not interesting to me. What is the next section?" > and then have to scroll down through 186 lines. > > 3. factor it into githistory(7), and reference it by name > > Obviously this is my favorite. :) It does have one downside, > though. If we convert pretty-formats.txt into gitpretty(7), then > searching for "oneline" in git-log may not turn up what you want. > I wonder if we can summarize with something like: > > --format=: > --pretty=<oneline|full|raw>: > --oneline: > Format the output. See gitpretty(7). > > in git-log(1). > > > EXAMPLES:: > > > > I prefer to make it mandatory for Porcelain command manual pages to > have a > > list of often used patterns that a reasonably intelligent person can > guess > > how to tweak to match the particular situation s/he is in. > > Yes, examples are good. > > > AUTHOR/DOCUMENTAITON:: > > > > These sections in most pages are not kept up to date, and I prefer to > > remove them altogether. They do not help end users who never clone > > git.git, and those who clone git.git will have shortlog to give them > more > > accurate information. > > Agreed. I find them useless at best, clutter at worst. > > > You didn't mention configuration variables. I do think it would be > better to have the variables for a specific command in that command's > manpage (in an ENVIRONMENT section that also mentions environment > variables). For variables that affect many commands, I would suggest > factoring them out as described above. > > git-config (or perhaps even gitconfig(7)) should have a list of all > variables and where they are described, like: > > apply.ignorewhitespace git-apply(1) > apply.whitespace git-apply(1) > branch.autosetupmerge git-branch(1) > [etc] > > There is not much point in having full descriptions in one giant list. > Instead, you can peruse the whole list, and then go to the > configuration > section of the relevant manpage to see a bunch of related options. Such > a list should be pretty easy to generate automatically from the other > documentation. > > -Peff TradeStation 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. ^ permalink raw reply [flat|nested] 30+ messages in thread
* Re: ghost refs 2010-04-07 21:00 ` Jeff King 2010-04-07 22:00 ` John Dlugosz @ 2010-04-20 7:02 ` Yann Dirson 2010-04-20 11:51 ` Jeff King 1 sibling, 1 reply; 30+ messages in thread From: Yann Dirson @ 2010-04-20 7:02 UTC (permalink / raw) To: git Jeff King <peff <at> peff.net> writes: > On Wed, Apr 07, 2010 at 12:58:33PM -0400, Avery Pennarun wrote: > > > This is on purpose, based on the theory that you don't want to lose > > data from your local repo just because someone (accidentally?) deletes > > a branch on the remote server. Unfortunately, this theory is a bit > > flawed, since someone could just as easily overwrite the remote branch > > with a totally different commit, and you'd still lose it in *that* > > case. So mostly it's just confusing. > > You do have a reflog in the case of overwrite. Delete kills off any > associated reflog (it would be cool if we had a "graveyard" reflog that > kept deleted branch reflogs around for a while). Wouldn't it jus be sufficient to keep reflogs on branch deletion, and let reflog entries subject be expired by gc just like for any branch, so that way we may only need to gc the reflog itself when it becomes empty ? -- Yann ^ permalink raw reply [flat|nested] 30+ messages in thread
* Re: ghost refs 2010-04-20 7:02 ` Yann Dirson @ 2010-04-20 11:51 ` Jeff King 2010-04-20 12:02 ` Zefram 2010-04-20 13:33 ` Jay Soffian 0 siblings, 2 replies; 30+ messages in thread From: Jeff King @ 2010-04-20 11:51 UTC (permalink / raw) To: Yann Dirson; +Cc: git On Tue, Apr 20, 2010 at 07:02:05AM +0000, Yann Dirson wrote: > > You do have a reflog in the case of overwrite. Delete kills off any > > associated reflog (it would be cool if we had a "graveyard" reflog that > > kept deleted branch reflogs around for a while). > > Wouldn't it jus be sufficient to keep reflogs on branch deletion, and > let reflog entries subject be expired by gc just like for any branch, > so that way we may only need to gc the reflog itself when it becomes > empty ? Almost. The complication is that a branch "foo" prevents any branch "foo/bar" from being created. So if you leave the reflog in place, you are blocking the creation of the reflog for a new branch. So you need some solution to that problem. Things I thought of are: 1. Leave the reflog in place until such a foo/bar branch is created. But that means branch creation unexpectedly kills off old unrelated reflog entries. Combingin user surprise and destruction of data is probably bad. 2. Make a refs/dead hierarchy so that the reflogs don't interfere with new branches. This just pushes off the problem, though, for when you try to delete "foo/bar" and see that "refs/dead/foo" is already blocking its spot in the reflog graveyard. 3. Stick everything in a big "graveyard" reflog. I think there are some complications here with the reflog format, though. Namely: - reflog entries don't actually name the ref they're on. We could munge the comment field to add the name of the ref as we put them in the graveyard ref. - entries just have a timestamp, and I think we assume they're in order. So I guess we can merge-sort the old graveyard ref with what we're adding to keep things in order. But it means you will have entries from various refs interspersed. I guess that is OK, though, as it's not unlike the HEAD reflog. So (3) seems like the only viable option to me, but I would be happy to hear alternatives. -Peff ^ permalink raw reply [flat|nested] 30+ messages in thread
* Re: ghost refs 2010-04-20 11:51 ` Jeff King @ 2010-04-20 12:02 ` Zefram 2010-04-20 13:00 ` Yann Dirson 2010-04-20 13:33 ` Jay Soffian 1 sibling, 1 reply; 30+ messages in thread From: Zefram @ 2010-04-20 12:02 UTC (permalink / raw) To: Jeff King; +Cc: Yann Dirson, git Jeff King wrote: > 2. Make a refs/dead hierarchy so that the reflogs don't interfere with > new branches. This just pushes off the problem, though, for when > you try to delete "foo/bar" and see that "refs/dead/foo" is already > blocking its spot in the reflog graveyard. This is easily solved by tweaking the name for dead reflogs. logs/dead_refs/foo~ doesn't clash with logs/dead_refs/foo/bar~. You might also want to stick a sequence number into the filename, for when you delete more than one foo/bar branch. -zefram ^ permalink raw reply [flat|nested] 30+ messages in thread
* Re: ghost refs 2010-04-20 12:02 ` Zefram @ 2010-04-20 13:00 ` Yann Dirson 2010-04-20 13:14 ` Zefram 0 siblings, 1 reply; 30+ messages in thread From: Yann Dirson @ 2010-04-20 13:00 UTC (permalink / raw) To: Zefram; +Cc: Jeff King, git Le Tue, 20 Apr 2010 13:02:28 +0100, Zefram <zefram@fysh.org> a écrit : > Jeff King wrote: > > 2. Make a refs/dead hierarchy so that the reflogs don't interfere > > with new branches. This just pushes off the problem, though, for > > when you try to delete "foo/bar" and see that "refs/dead/foo" is > > already blocking its spot in the reflog graveyard. > > This is easily solved by tweaking the name for dead reflogs. > logs/dead_refs/foo~ doesn't clash with logs/dead_refs/foo/bar~. > > You might also want to stick a sequence number into the filename, for > when you delete more than one foo/bar branch. That sounds cool. A logs/dead_refs/ namespace of some sort seems to be unavoidable, to avoid the clash between old "logs/refs/foo/bar~" and new "logs/refs/foo". We would also need a syntax for accessing those. Maybe something reminiscent of Debian "epochs" in version number. That would give a syntax like "foo@{1:1}" and "foo@{2:1}" to access the dead and long-dead refs' logs, respectively looking into foo~<largest> and foo~<largest-1>. Going that way, we would probably want to add a "delete" entries in the reflog when deleting a ref - but that would make "foo@{1:0}" a non-sense, we could just reject it. Another option than adding a sequence number would be to move back the dead_refs/ log back to refs/ when the branch is creating again. That way just after resurection we have: foo@{0} : now foo@{1} : invalid (deleted state) foo@{2} : the ref as it was 2 operations before That would kinda make sense too, but then if the new "foo" is something completely unrelated, we may rather want to refer to foo{1:1} (which is stable until next deletion of foo) rather than foo@{2}, which varies with current foo. But the 1st solution could give us that too, by considering logs/dead_refs/foo~ the logical continuation of logs/refs/foo. Would that make sense ? -- Yann ^ permalink raw reply [flat|nested] 30+ messages in thread
* Re: ghost refs 2010-04-20 13:00 ` Yann Dirson @ 2010-04-20 13:14 ` Zefram 0 siblings, 0 replies; 30+ messages in thread From: Zefram @ 2010-04-20 13:14 UTC (permalink / raw) To: Yann Dirson; +Cc: Jeff King, git Yann Dirson wrote: >Another option than adding a sequence number would be to move back the >dead_refs/ log back to refs/ when the branch is creating again. Yes, that also makes sense. Pick one model or the other. A mixture would *not* make sense. -zefram ^ permalink raw reply [flat|nested] 30+ messages in thread
* Re: ghost refs 2010-04-20 11:51 ` Jeff King 2010-04-20 12:02 ` Zefram @ 2010-04-20 13:33 ` Jay Soffian 2010-04-20 14:24 ` Jeff King 1 sibling, 1 reply; 30+ messages in thread From: Jay Soffian @ 2010-04-20 13:33 UTC (permalink / raw) To: Jeff King; +Cc: Yann Dirson, git On Tue, Apr 20, 2010 at 7:51 AM, Jeff King <peff@peff.net> wrote: > Almost. The complication is that a branch "foo" prevents any branch > "foo/bar" from being created. So if you leave the reflog in place, you > are blocking the creation of the reflog for a new branch. > > So you need some solution to that problem. Things I thought of are: > > 1. Leave the reflog in place until such a foo/bar branch is created. > [...] > 2. Make a refs/dead hierarchy so that the reflogs don't interfere with > [...] > 3. Stick everything in a big "graveyard" reflog. I think there are > [...] 4. Just append to the existing reflog? Given: $ git checkout -b topic origin/master # 1 $ git add; git commit ... $ git checkout master $ git merge topic $ git branch -d topic $ git checkout -b topic origin/master # 2 Whose to say that the branch named topic from (1) and the branch named topic from (2) are unrelated? Isn't the fact that they have the same name is an indication that they are likely to be related. And even if they are unrelated, what's wrong with re-using the same reflog? Wouldn't it be obvious what happened? e.g.: 64c7587 topic@{0}: branch: Created from HEAD abcdef3 topic@{1}: branch: deleted topic <---- I made this one up 3568c4b topic@{2}: commit: turned the knob to 11 707d9fb topic@{3}: branch: Created from HEAD j. ^ permalink raw reply [flat|nested] 30+ messages in thread
* Re: ghost refs 2010-04-20 13:33 ` Jay Soffian @ 2010-04-20 14:24 ` Jeff King 2010-04-20 14:42 ` Yann Dirson 2010-04-20 14:52 ` Jay Soffian 0 siblings, 2 replies; 30+ messages in thread From: Jeff King @ 2010-04-20 14:24 UTC (permalink / raw) To: Jay Soffian; +Cc: Yann Dirson, git On Tue, Apr 20, 2010 at 09:33:42AM -0400, Jay Soffian wrote: > 4. Just append to the existing reflog? Given: > > $ git checkout -b topic origin/master # 1 > $ git add; git commit ... > $ git checkout master > $ git merge topic > $ git branch -d topic > $ git checkout -b topic origin/master # 2 I like how the user would interact with that, but what happens with: git checkout -b topic/subtopic The reflog of the deleted branch is in the way. -Peff ^ permalink raw reply [flat|nested] 30+ messages in thread
* Re: ghost refs 2010-04-20 14:24 ` Jeff King @ 2010-04-20 14:42 ` Yann Dirson 2010-04-20 14:52 ` Jay Soffian 1 sibling, 0 replies; 30+ messages in thread From: Yann Dirson @ 2010-04-20 14:42 UTC (permalink / raw) To: Jeff King; +Cc: Jay Soffian, git Le Tue, 20 Apr 2010 10:24:44 -0400, Jeff King <peff@peff.net> a écrit : > On Tue, Apr 20, 2010 at 09:33:42AM -0400, Jay Soffian wrote: > > > 4. Just append to the existing reflog? Given: > > > > $ git checkout -b topic origin/master # 1 > > $ git add; git commit ... > > $ git checkout master > > $ git merge topic > > $ git branch -d topic > > $ git checkout -b topic origin/master # 2 > > I like how the user would interact with that, but what happens with: > > git checkout -b topic/subtopic > > The reflog of the deleted branch is in the way. That would be addressed by considering logs/dead_refs/* contents *logical* continuations of logs/refs/* (bottom-most suggestion in my other email) -- Yann ^ permalink raw reply [flat|nested] 30+ messages in thread
* Re: ghost refs 2010-04-20 14:24 ` Jeff King 2010-04-20 14:42 ` Yann Dirson @ 2010-04-20 14:52 ` Jay Soffian 2010-04-20 15:03 ` Alex Riesen 2010-04-20 15:10 ` Jeff King 1 sibling, 2 replies; 30+ messages in thread From: Jay Soffian @ 2010-04-20 14:52 UTC (permalink / raw) To: Jeff King; +Cc: Yann Dirson, git On Tue, Apr 20, 2010 at 10:24 AM, Jeff King <peff@peff.net> wrote: > On Tue, Apr 20, 2010 at 09:33:42AM -0400, Jay Soffian wrote: > I like how the user would interact with that, but what happens with: > > git checkout -b topic/subtopic > > The reflog of the deleted branch is in the way. Handle it just as gracefully as we do today. This is what happens when you try to create a branch with a similar collision: $ git branch foo/bar $ git branch foo error: there are still refs under 'refs/heads/foo' fatal: Failed to lock ref for update: Is a directory So the reflog analog would be: $ git branch topic/subtopic error: there are still logs under 'logs/refs/heads/topic' fatal: Failed to lock log for update: Is a directory I think it's an edge case; thus I think it's okay to fail as long as we give a reasonable error and a way to rename it. j. ^ permalink raw reply [flat|nested] 30+ messages in thread
* Re: ghost refs 2010-04-20 14:52 ` Jay Soffian @ 2010-04-20 15:03 ` Alex Riesen 2010-04-20 15:10 ` Jeff King 1 sibling, 0 replies; 30+ messages in thread From: Alex Riesen @ 2010-04-20 15:03 UTC (permalink / raw) To: Jay Soffian; +Cc: Jeff King, Yann Dirson, git On Tue, Apr 20, 2010 at 16:52, Jay Soffian <jaysoffian@gmail.com> wrote: > On Tue, Apr 20, 2010 at 10:24 AM, Jeff King <peff@peff.net> wrote: >> On Tue, Apr 20, 2010 at 09:33:42AM -0400, Jay Soffian wrote: >> I like how the user would interact with that, but what happens with: >> >> git checkout -b topic/subtopic >> >> The reflog of the deleted branch is in the way. > > Handle it just as gracefully as we do today. This is what happens when > you try to create a branch with a similar collision: > > $ git branch foo/bar > $ git branch foo > error: there are still refs under 'refs/heads/foo' > fatal: Failed to lock ref for update: Is a directory > > So the reflog analog would be: > > $ git branch topic/subtopic > error: there are still logs under 'logs/refs/heads/topic' > fatal: Failed to lock log for update: Is a directory > > I think it's an edge case; thus I think it's okay to fail as long as > we give a reasonable error and a way to rename it. No it is not. Creation of the reflog is not the purpose of git branch operation (creation of the branch itself is). It will be just annoyance, especially if the user will have to do a rename which could be done automatically. ^ permalink raw reply [flat|nested] 30+ messages in thread
* Re: ghost refs 2010-04-20 14:52 ` Jay Soffian 2010-04-20 15:03 ` Alex Riesen @ 2010-04-20 15:10 ` Jeff King 1 sibling, 0 replies; 30+ messages in thread From: Jeff King @ 2010-04-20 15:10 UTC (permalink / raw) To: Jay Soffian; +Cc: Yann Dirson, git On Tue, Apr 20, 2010 at 10:52:42AM -0400, Jay Soffian wrote: > On Tue, Apr 20, 2010 at 10:24 AM, Jeff King <peff@peff.net> wrote: > > On Tue, Apr 20, 2010 at 09:33:42AM -0400, Jay Soffian wrote: > > I like how the user would interact with that, but what happens with: > > > > git checkout -b topic/subtopic > > > > The reflog of the deleted branch is in the way. > > Handle it just as gracefully as we do today. This is what happens when > you try to create a branch with a similar collision: > > $ git branch foo/bar > $ git branch foo > error: there are still refs under 'refs/heads/foo' > fatal: Failed to lock ref for update: Is a directory Yeah, but my next step would be "branch -d foo/bar"; under your proposal that no longer works. Now I have to do "branch -m foo/bar foobar" where "foobar" is some name that I know means "the old reflog for foo/bar". So I think it makes more sense to come up with that naming scheme ourselves and make using it semi-transparent. > $ git branch topic/subtopic > error: there are still logs under 'logs/refs/heads/topic' > fatal: Failed to lock log for update: Is a directory > > I think it's an edge case; thus I think it's okay to fail as long as > we give a reasonable error and a way to rename it. It is an edge-case, but I'd rather just have a scheme that works nicely in the normal case and "degrades" only in the error case. Like if creating "foo/bar" we see that we have "foo", but that the last reflog entry is deletion, we move "foo" to "foo-1" or something. It's ugly, but it just doesn't come up that much. -Peff ^ permalink raw reply [flat|nested] 30+ messages in thread
end of thread, other threads:[~2010-04-20 15:10 UTC | newest] Thread overview: 30+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2010-04-07 16:38 ghost refs John Dlugosz 2010-04-07 16:58 ` Avery Pennarun 2010-04-07 21:00 ` Jeff King 2010-04-07 22:00 ` John Dlugosz 2010-04-07 22:03 ` Avery Pennarun 2010-04-07 22:10 ` John Dlugosz 2010-04-07 22:11 ` Avery Pennarun 2010-04-08 4:30 ` Jeff King 2010-04-08 16:07 ` John Dlugosz 2010-04-08 16:55 ` Junio C Hamano 2010-04-08 19:49 ` Jeff King 2010-04-08 20:42 ` Junio C Hamano 2010-04-08 22:14 ` Avery Pennarun 2010-04-08 23:04 ` Nicolas Sebrecht 2010-04-17 11:51 ` Jeff King 2010-04-17 16:32 ` Junio C Hamano 2010-04-17 16:57 ` Git documentation writing guidelines (was: Re: ghost refs) Jakub Narebski 2010-04-18 0:28 ` Git documentation writing guidelines Junio C Hamano 2010-04-19 15:33 ` ghost refs John Dlugosz 2010-04-20 7:02 ` Yann Dirson 2010-04-20 11:51 ` Jeff King 2010-04-20 12:02 ` Zefram 2010-04-20 13:00 ` Yann Dirson 2010-04-20 13:14 ` Zefram 2010-04-20 13:33 ` Jay Soffian 2010-04-20 14:24 ` Jeff King 2010-04-20 14:42 ` Yann Dirson 2010-04-20 14:52 ` Jay Soffian 2010-04-20 15:03 ` Alex Riesen 2010-04-20 15:10 ` Jeff King
This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.