Re: [PATCH v3] git checkout: create unparented branch by --orphan

[Erick Mattos <erick.mattos@gmail.com>]

Hi,

2010/3/22 Chris Johnsen <chris_johnsen@pobox.com>:
> On 2010 Mar 21, at 10:34, Erick Mattos wrote:
>>
>> Similar to -b, --orphan creates a new branch, but it starts without any
>> commit.  After running "git checkout --orphan newbranch", you are on a
>> new branch "newbranch", and the first commit you create from this state
>> will start a new history without any ancestry.
>>
>> "git checkout --orphan" keeps the index and the working tree files
>> intact in order to make it convenient for creating a new history whose
>> trees resemble the ones from the original branch.
>>
>> When creating a branch whose trees have no resemblance to the ones from
>> the original branch, it may be easier to start work on the new branch by
>> untracking and removing all working tree files that came from the
>> original branch, by running a 'git rm -rf .' immediately after running
>
> Maybe use double quotes in the above command to be consistent with the rest
> of inline commands in the commit message.
>
>> "checkout --orphan".
>>
>> Signed-off-by: Erick Mattos <erick.mattos@gmail.com>
>> ---
>
>> diff --git a/Documentation/git-checkout.txt
>> b/Documentation/git-checkout.txt
>> index 37c1810..5a50997 100644
>> --- a/Documentation/git-checkout.txt
>> +++ b/Documentation/git-checkout.txt
>
>> @@ -90,6 +90,25 @@ explicitly give a name with '-b' in such a case.
>>        Create the new branch's reflog; see linkgit:git-branch[1] for
>>        details.
>>
>> +--orphan::
>> +       Create a new branch named <new_branch>, unparented to any other
>> +       branch.  The new branch you switch to does not have any commit
>> +       and after the first one it will become the root of a new history
>> +       completely unconnected from all the other branches.
>> ++
>> +When you use "--orphan", a new unparented branch is created having the
>> +index and the working tree intact.  This allows you to start a new
>> +history that records set of paths similar to that of the start-point
>> +commit, which is useful when you want to keep different branches for
>> +different audiences you are working to like when you have an open source
>> +and commercial versions of a software, for example.
>> ++
>> +If you want to start a disconnected history that records set of paths
>> +totally different from the original branch, you may want to first clear
>> +the index and the working tree, by running "git rm -rf ." from the
>> +top-level of the working tree, before preparing your files (by copying
>> +from elsewhere, extracting a tarball, etc.) in the working tree.
>> +
>>  -m::
>>  --merge::
>>        When switching branches,
>
> (American) English is my first language, but that does not imply that I
> speak, read, or write perfectly.
>
> "unparented" sounds a bit awkward to me.
>
> "unconnected from all": the usual constructions are "unconnected to",
> "connected to" or "disconnected from"; might be better as "disconnected from
> all" or "not connected to any"
>
> "unparented" sounds odd to me, especially "unparented to". For "unparented
> branch", I would use "branch without parents", maybe "history-free branch".
>
> I think the repeated uses of "unparented" in the first and second
> paragraphs, and its description can be coalesced into the the first
> paragraph, leaving the later paragraphs to describe the "common paths" and
> "no common paths" cases.
>
> The second sentence of the second paragraph seems overly long and gets a bit
> muddled near the end. I can not parse "audiences you are working to". Maybe
> it should be "audiences you are working with" or "... for"?
>
> In the third paragraph, "first clear the index and the working tree" bit
> could be taken to mean "clear the index and working tree before creating the
> new branch" (which might work, but leaves a possibly confusing state if the
> user is distracted between "rm -rf" and "checkout --orphan" (still on the
> original branch, the deletion of everything has been staged)). Also, use
> backquotes to properly format the example command.
>
> Here is my take on these paragraphs:
>
> -->8---->8--
> --orphan::
>        Create a new, 'orphan' branch named <new_branch>, and start it
>        at <start_point>. The first commit made on this new branch will
>        have no parents (it will be the root of a new history that is
>        not connected to any the other branches or commits).
> +
> An orphan branch allows you to start a new history that records a set of
> paths similar to <start_point>.
> This can be useful when you want to publish the tree from a commit without
> exposing its full history.
> You might want to do this to publish an open source branch of a project
> whose current tree is "clean", but whose full history contains proprietary
> or otherwise encumbered bits of code.
> +
> If you want to start a disconnected history that records a set of paths
> that is totally different from <start_point>, you may want to clear the
> index and the working tree after creating the orphan branch.
> Run `git rm -rf .` from the top level of the working tree, then prepare
> your new files by copying them from elsewhere, extracting a tarball, or
> otherwise populating the working tree.
> --8<----8<--
>
> --
> Chris
>

I am in favor of changing the whole texts to your versions.  Let's
wait for Junio's opinion.

After this wonderful English and modesty lessons, I started thinking:
since Git is a worldwide spread software why it is not using gettext
to have its translations?  It would not be a hard job because gettext
separates the job of translation from normal work flow with just minor
changes to inline message constants.

Best regards to all