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

[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

[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

[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

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