ghost refs

ghost refs

[John Dlugosz]

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.

Re: ghost refs

[Avery Pennarun]

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

Re: ghost refs

[Jeff King]

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

RE: ghost refs

[John Dlugosz]

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

Re: ghost refs

[Avery Pennarun]

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

RE: ghost refs

[John Dlugosz]

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.

Re: ghost refs

[Avery Pennarun]

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

Re: ghost refs

[Jeff King]

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

RE: ghost refs

[John Dlugosz]

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

Re: ghost refs

[Junio C Hamano]

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.

Re: ghost refs

[Jeff King]

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

Re: ghost refs

[Junio C Hamano]

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.

Re: ghost refs

[Avery Pennarun]

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

Re: ghost refs

[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

Re: ghost refs

[Jeff King]

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

Re: ghost refs

[Junio C Hamano]

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.

Re: Git documentation writing guidelines (was: Re: ghost refs)

[Jakub Narebski]

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

Re: Git documentation writing guidelines

[Junio C Hamano]

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.

    

RE: ghost refs

[John Dlugosz]

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.

Re: ghost refs

[Yann Dirson]

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

Re: ghost refs

[Jeff King]

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

Re: ghost refs

[Zefram]

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

Re: ghost refs

[Yann Dirson]

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

Re: ghost refs

[Zefram]

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

Re: ghost refs

[Jay Soffian]

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.

Re: ghost refs

[Jeff King]

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

Re: ghost refs

[Yann Dirson]

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

Re: ghost refs

[Jay Soffian]

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.

Re: ghost refs

[Alex Riesen]

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.

Re: ghost refs

[Jeff King]

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