Re: [PATCH] git-branch.txt: document -f correctly

Re: [PATCH] git-branch.txt: document -f correctly

[John Dlugosz]

===  Re: ===
BTW, I noticed that 'git-subcmd' is used everywhere in here which does
not feel right, but I followed the existing style, leaving a consistent
clean-up for a later patch. Also, typesetting is inconsistent:
We have <branch> as well as `<branch>` when the text talks about the
options. Do we have a style guide or such?
=== end ===

I would agree that being factually correct and available immediately
trumps being wrong but pretty.

As an experienced writer and editor, the documentation is something I
might hack long before I tackle the code.  I see you edited a file with
.txt extension, and some kind of markup that's not the HTML files I'm
reading.  Beyond any kind of style guide, is there a guide to the
documentation _system_ in use?

--John
(please excuse the footer; it's not my idea)

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: [PATCH] git-branch.txt: document -f correctly

[git]

John Dlugosz venit, vidit, dixit 17.03.2009 17:07:
> ===  Re: ===
> BTW, I noticed that 'git-subcmd' is used everywhere in here which does
> not feel right, but I followed the existing style, leaving a consistent
> clean-up for a later patch. Also, typesetting is inconsistent:
> We have <branch> as well as `<branch>` when the text talks about the
> options. Do we have a style guide or such?
> === end ===
> 
> I would agree that being factually correct and available immediately
> trumps being wrong but pretty.

I can't really make much sense out of this but I guess I doesn't matter.
In any case, by "style guide" I mean something saying "write options as
monospaced", "write git commands without dash unless in links"...

> As an experienced writer and editor, the documentation is something I
> might hack long before I tackle the code.  I see you edited a file with
> .txt extension, and some kind of markup that's not the HTML files I'm
> reading.  Beyond any kind of style guide, is there a guide to the
> documentation _system_ in use?

It's asciidoc. Rather, asciidoc 7ish, current asciidoc is at 8.4.1.
The backticks are used for displaying commands, e.g., and usually come
out as monospaced in html, underlined in man.

Cheers,
Michael

Re: undoing something

[Junio C Hamano]

Nanako Shiraishi <nanako3@lavabit.com> writes:

> Quoting John Dlugosz <JDlugosz@TradeStation.com>:
>
>> === Re: ===
>>  (2) if you are not, you can obviously check out topic and do the above,
>>      or "git branch -f topic topic^".
>> === end ===
>>
>> As documented, this destroys the existing branch and makes a new one.
>> That would, by design, blow away the reflog for that branch.
>
> Does it?  If so I think you have an incorrect documentation.
>
> $ rm -fr /tmp/gomi && mkdir /tmp/gomi
> $ cd /tmp/gomi
> $ git init
> $ echo hello >world
> $ git add world
> $ git commit -m initial
> $ seq 1 100 | while read num; do echo $num >world; git commit -a -m $num; done
> $ git checkout -b side master~60
> $ git branch -f master master@{20}
> $ git log --oneline -g master | head -n 10
> 0acf8c1 master@{0}: branch: Reset from master@{20}
> 945c3ee master@{1}: commit: 100
> 54fcb36 master@{2}: commit: 99
> b314a1e master@{3}: commit: 98
> e91d999 master@{4}: commit: 97
> 0d88853 master@{5}: commit: 96
> 0124315 master@{6}: commit: 95
> 5df2cc5 master@{7}: commit: 94
> ...
> 0813a46 master@{9}: commit: 92

I didn't even notice there was another question buried.  Thanks.

Documentation/git-branch.txt says this:

        -f::
                Force the creation of a new branch even if it means deleting
                a branch that already exists with the same name.

which does imply that it first destroys the branch altogether and
recreates as if there was no such branch.

But that is actually not what the code does to reflog, and I think the
behaviour makes a lot more sense than "destroy and create" the
documentation implies.  branch.c::create_branch() has this:

	if (forcing)
		snprintf(msg, sizeof msg, "branch: Reset from %s",
			 start_name);
	else
		snprintf(msg, sizeof msg, "branch: Created from %s",
			 start_name);

The message for your master@{0} example came from the "forcing" codepath.

The documentation is indeed wrong.  It is more like "create a new branch,
or if the named branch already exists, reset the tip of it".  If we want
to sound alarmist, we could add "even if it means making the existing
history unreachable from the new tip of the branch", but I think "reset"
already means that and it would be redundant.

The create_branch() function does another thing, though.  It sets up the
tracking information _if asked_.  Because one branch cannot track more
than one "other things" at once, it inevitably overwrites the previous
tracking information if you say "branch --track -f dev origin/dev" if dev
were tracking something else.  But if you do not let it set up tracking,
the old tracking configuration is _not_ discarded.  I am not sure if that
was intended (the branch.<name>.remote nor branch.<name>.merge variables
are not something I use myself), but it makes sort of sense.  If you do
"git branch -f dev dev~2" to rewind its tip, you do not want to lose its
tracking information, so the current behaviour makes sense in that
respect.

I am not sure about how branch.autsetupmerge does interact with this in
the current code, nor how it should interact with it in the ideal world,
though.  That's for interested parties (I suspect Jay and Paolo?) to
figure out.

[PATCH] git-branch.txt: document -f correctly

[Michael J Gruber]

'git branch -f a b' resets a to b when a exists, rather then deleting a.
Say so in the documentation.

Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
---
Something like this?

BTW, I noticed that 'git-subcmd' is used everywhere in here which does
not feel right, but I followed the existing style, leaving a consistent
clean-up for a later patch. Also, typesetting is inconsistent:
We have <branch> as well as `<branch>` when the text talks about the
options. Do we have a style guide or such?

 Documentation/git-branch.txt |    4 ++--
 1 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
index 6103d62..27b73bc 100644
--- a/Documentation/git-branch.txt
+++ b/Documentation/git-branch.txt
@@ -76,8 +76,8 @@ OPTIONS
 	based sha1 expressions such as "<branchname>@\{yesterday}".
 
 -f::
-	Force the creation of a new branch even if it means deleting
-	a branch that already exists with the same name.
+	Reset <branchname> to <startpoint> if <branchname> exists
+	already. Without `-f` 'git-branch' refuses to change an existing branch.
 
 -m::
 	Move/rename a branch and the corresponding reflog.
-- 
1.6.2.149.g6462

Re: [PATCH] git-branch.txt: document -f correctly

[Junio C Hamano]

Michael J Gruber <git@drmicha.warpmail.net> writes:

> 'git branch -f a b' resets a to b when a exists, rather then deleting a.
> Say so in the documentation.
>
> Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
> ---
> Something like this?
>
> BTW, I noticed that 'git-subcmd' is used everywhere in here which does
> not feel right, but I followed the existing style, leaving a consistent
> clean-up for a later patch. Also, typesetting is inconsistent:
> We have <branch> as well as `<branch>` when the text talks about the
> options. Do we have a style guide or such?
>
>  Documentation/git-branch.txt |    4 ++--
>  1 files changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
> index 6103d62..27b73bc 100644
> --- a/Documentation/git-branch.txt
> +++ b/Documentation/git-branch.txt
> @@ -76,8 +76,8 @@ OPTIONS
>  	based sha1 expressions such as "<branchname>@\{yesterday}".
>  
>  -f::
> -	Force the creation of a new branch even if it means deleting
> -	a branch that already exists with the same name.
> +	Reset <branchname> to <startpoint> if <branchname> exists
> +	already. Without `-f` 'git-branch' refuses to change an existing branch.

And what happens if the branchname does not exist?

>  
>  -m::
>  	Move/rename a branch and the corresponding reflog.
> -- 
> 1.6.2.149.g6462

Re: [PATCH] git-branch.txt: document -f correctly

[Michael J Gruber]

Junio C Hamano venit, vidit, dixit 17.03.2009 17:37:
> Michael J Gruber <git@drmicha.warpmail.net> writes:
> 
>> 'git branch -f a b' resets a to b when a exists, rather then deleting a.
>> Say so in the documentation.
>>
>> Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
>> ---
>> Something like this?
>>
>> BTW, I noticed that 'git-subcmd' is used everywhere in here which does
>> not feel right, but I followed the existing style, leaving a consistent
>> clean-up for a later patch. Also, typesetting is inconsistent:
>> We have <branch> as well as `<branch>` when the text talks about the
>> options. Do we have a style guide or such?
>>
>>  Documentation/git-branch.txt |    4 ++--
>>  1 files changed, 2 insertions(+), 2 deletions(-)
>>
>> diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
>> index 6103d62..27b73bc 100644
>> --- a/Documentation/git-branch.txt
>> +++ b/Documentation/git-branch.txt
>> @@ -76,8 +76,8 @@ OPTIONS
>>  	based sha1 expressions such as "<branchname>@\{yesterday}".
>>  
>>  -f::
>> -	Force the creation of a new branch even if it means deleting
>> -	a branch that already exists with the same name.
>> +	Reset <branchname> to <startpoint> if <branchname> exists
>> +	already. Without `-f` 'git-branch' refuses to change an existing branch.
> 
> And what happens if the branchname does not exist?

Well, the standard behaviour of "git branch" is described in the
"description", the meaning of the options under "options"...
We could add

	If <branchname> does not exist it is created and '-f' has no effect.

although that seems a bit talkative.

> 
>>  
>>  -m::
>>  	Move/rename a branch and the corresponding reflog.
>> -- 
>> 1.6.2.149.g6462