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

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

[Erick Mattos]

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
"checkout --orphan".

Signed-off-by: Erick Mattos <erick.mattos@gmail.com>
---

Final patch version (I think so... :-) ).

Added some further script tests by Junio.

 Documentation/git-checkout.txt |   21 +++++++++-
 builtin/checkout.c             |   15 ++++++-
 t/t2017-checkout-orphan.sh     |   90 ++++++++++++++++++++++++++++++++++++++++
 3 files changed, 123 insertions(+), 3 deletions(-)
 create mode 100755 t/t2017-checkout-orphan.sh

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
@@ -9,7 +9,7 @@ SYNOPSIS
 --------
 [verse]
 'git checkout' [-q] [-f] [-m] [<branch>]
-'git checkout' [-q] [-f] [-m] [-b <new_branch>] [<start_point>]
+'git checkout' [-q] [-f] [-m] [[-b|--orphan] <new_branch>] [<start_point>]
 'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <paths>...
 'git checkout' --patch [<tree-ish>] [--] [<paths>...]
 
@@ -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,
diff --git a/builtin/checkout.c b/builtin/checkout.c
index acefaaf..37d8278 100644
--- a/builtin/checkout.c
+++ b/builtin/checkout.c
@@ -33,6 +33,7 @@ struct checkout_opts {
 	int writeout_error;
 
 	const char *new_branch;
+	const char *new_orphan_branch;
 	int new_branch_log;
 	enum branch_track track;
 };
@@ -491,8 +492,9 @@ static void update_refs_for_switch(struct checkout_opts *opts,
 	struct strbuf msg = STRBUF_INIT;
 	const char *old_desc;
 	if (opts->new_branch) {
-		create_branch(old->name, opts->new_branch, new->name, 0,
-			      opts->new_branch_log, opts->track);
+		if (!opts->new_orphan_branch)
+			create_branch(old->name, opts->new_branch, new->name, 0,
+				      opts->new_branch_log, opts->track);
 		new->name = opts->new_branch;
 		setup_branch_path(new);
 	}
@@ -632,6 +634,7 @@ int cmd_checkout(int argc, const char **argv, const char *prefix)
 		OPT_BOOLEAN('l', NULL, &opts.new_branch_log, "log for new branch"),
 		OPT_SET_INT('t', "track",  &opts.track, "track",
 			BRANCH_TRACK_EXPLICIT),
+		OPT_STRING(0, "orphan", &opts.new_orphan_branch, "new branch", "new unparented branch"),
 		OPT_SET_INT('2', "ours", &opts.writeout_stage, "stage",
 			    2),
 		OPT_SET_INT('3', "theirs", &opts.writeout_stage, "stage",
@@ -677,6 +680,14 @@ int cmd_checkout(int argc, const char **argv, const char *prefix)
 		opts.new_branch = argv0 + 1;
 	}
 
+	if (opts.new_orphan_branch) {
+		if (opts.new_branch)
+			die("--orphan and -b are mutually exclusive");
+		if (opts.track > 0 || opts.new_branch_log)
+			die("--orphan should not be used with -t or -l");
+		opts.new_branch = opts.new_orphan_branch;
+	}
+
 	if (conflict_style) {
 		opts.merge = 1; /* implied */
 		git_xmerge_config("merge.conflictstyle", conflict_style, NULL);
diff --git a/t/t2017-checkout-orphan.sh b/t/t2017-checkout-orphan.sh
new file mode 100755
index 0000000..a8297c6
--- /dev/null
+++ b/t/t2017-checkout-orphan.sh
@@ -0,0 +1,90 @@
+#!/bin/sh
+#
+# Copyright (c) 2010 Erick Mattos
+#
+
+test_description='git checkout --orphan
+
+Main Tests for --orphan functionality.'
+
+. ./test-lib.sh
+
+TEST_FILE=foo
+
+test_expect_success 'Setup' '
+	echo "Initial" >"$TEST_FILE" &&
+	git add "$TEST_FILE" &&
+	git commit -m "First Commit"
+	test_tick &&
+	echo "State 1" >>"$TEST_FILE" &&
+	git add "$TEST_FILE" &&
+	test_tick &&
+	git commit -m "Second Commit"
+'
+
+test_expect_success '--orphan creates a new orphan branch from HEAD' '
+	git checkout --orphan alpha &&
+	test_must_fail git rev-parse --verify HEAD &&
+	test "refs/heads/alpha" = "$(git symbolic-ref HEAD)" &&
+	test_tick &&
+	git commit -m "Third Commit" &&
+	test_must_fail git rev-parse --verify HEAD^ &&
+	git diff-tree --quiet master alpha
+'
+
+test_expect_success '--orphan creates a new orphan branch from <start_point>' '
+	git checkout master &&
+	git checkout --orphan beta master^ &&
+	test_must_fail git rev-parse --verify HEAD &&
+	test "refs/heads/beta" = "$(git symbolic-ref HEAD)" &&
+	test_tick &&
+	git commit -m "Fourth Commit" &&
+	test_must_fail git rev-parse --verify HEAD^ &&
+	git diff-tree --quiet master^ beta
+'
+
+test_expect_success '--orphan must be rejected with -b' '
+	git checkout master &&
+	test_must_fail git checkout --orphan new -b newer &&
+	test refs/heads/master = "$(git symbolic-ref HEAD)"
+'
+
+test_expect_success '--orphan is rejected with an existing name' '
+	git checkout master &&
+	test_must_fail git checkout --orphan master &&
+	test refs/heads/master = "$(git symbolic-ref HEAD)"
+'
+
+test_expect_success '--orphan refuses to switch if a merge is needed' '
+	git checkout master &&
+	git reset --hard &&
+	echo local >>"$TEST_FILE" &&
+	cat "$TEST_FILE" >"$TEST_FILE.saved" &&
+	test_must_fail git checkout --orphan gamma master^ &&
+	test refs/heads/master = "$(git symbolic-ref HEAD)" &&
+	test_cmp "$TEST_FILE" "$TEST_FILE.saved" &&
+	git diff-index --quiet --cached HEAD &&
+	git reset --hard
+'
+
+test_expect_success '--orphan does not mix well with -t' '
+	git checkout master &&
+	test_must_fail git checkout -t master --orphan gamma &&
+	test refs/heads/master = "$(git symbolic-ref HEAD)"
+'
+
+test_expect_success '--orphan ignores branch.autosetupmerge' '
+	git checkout -f master &&
+	git config branch.autosetupmerge always &&
+	git checkout --orphan delta &&
+	test -z "$(git config branch.delta.merge)" &&
+	test refs/heads/delta = "$(git symbolic-ref HEAD)" &&
+	test_must_fail git rev-parse --verify HEAD^
+'
+
+test_expect_success '--orphan does not mix well with -l' '
+	git checkout -f master &&
+	test_must_fail git checkout -l --orphan gamma
+'
+
+test_done
-- 
1.7.0.2.324.g7eb48.dirty

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

[Peter Baumann]

On Sun, Mar 21, 2010 at 12:34:38PM -0300, 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.
> 

Sorry to skim in so late but --orphan sounds - at least to me as a non native
speaker - a little strange. Yes, I know it means "without parents", but
actually it would be the *last* thing I would search for after opening the
manpage.

Wouldn't --empty-parent or --no-parent describe the situation better?
It actually has the benefit that it would match on a search for /parent/,
which I would have searched for if I want to create a new empty branch.

--
Peter

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

[Erick Mattos]

Hi,

2010/3/21 Peter Baumann <waste.manager@gmx.de>:
> Sorry to skim in so late but --orphan sounds - at least to me as a non native
> speaker - a little strange. Yes, I know it means "without parents", but
> actually it would be the *last* thing I would search for after opening the
> manpage.

It is never late to contribute, even for skimming.  Free software are
organic and living things people can mold it whenever they want.

We are both non native English speakers but for me orphan is the real
obvious for no parents.  And that is the name of the command you type:
shorter and not similar to other ones is the best.

I don't care about names as long as its bearer does what it is
supposed to do.  But in this particular case I think it fits the job.

> Wouldn't --empty-parent or --no-parent describe the situation better?
> It actually has the benefit that it would match on a search for /parent/,
> which I would have searched for if I want to create a new empty branch.

--empty-parent try to give the "plumbing" idea but it is not really
'empty' but 'non-existant' and also it is not good to make
"porcelainners" (inventing this term) see it as an unparented though.

--no-parent is just added characters and make it feel as if it exists
a --parent too.

You WILL match on a search for /parent/ already.

> --
> Peter
>

Thanks for you contributing ideas.

Although I don't agree with you on this subject, I am very happy you
participated your ideas to me.  It is good to get some attention :-)

In this particular case I see Junio as a native English speaker better
fitted to comment.

Best regards

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

[Junio C Hamano]

Peter Baumann <waste.manager@gmx.de> writes:

> Sorry to skim in so late but --orphan sounds - at least to me as a non native
> speaker - a little strange. Yes, I know it means "without parents", but
> actually it would be the *last* thing I would search for after opening the
> manpage.

I'm not native either, and "orphan" sounded strange in that we've never
used that word in any of our use case or workflow description in our
documents.

GitTips page of git wiki mentions this under "a new branch that has no
ancestor", and speaks of a way to add "a new and empty branch".  Scott
Chacon also creates "new empty branches" in the community book.

But if one compares them with what we discussed in the messages in the
threads on earlier iterations of this patch, one would realize that
neither of these pages is backed by enough thought/discussion on the
reason why the end user might want to do this in the first place; they
choose the word "empty" without even realizing that it describes only one
mode of operation (aka "no common paths" in our discussion) that a
disconnected history might be wanted by users.

The main point of the feature is not the emptyness of the resulting tree
(it is merely one possible outcome), but is the lack of parents in the
resulting commit.  So I would recommend against --empty.  --root might be
a good synonym, though, and we _do_ already use that word for that purpose
in some commands (e.g. "log --root").

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

[Erick Mattos]

Hi,

2010/3/21 Junio C Hamano <gitster@pobox.com>:
> I'm not native either, and "orphan" sounded strange in that we've never
> used that word in any of our use case or workflow description in our
> documents.

I didn't know.  I thought you were American.

> The main point of the feature is not the emptyness of the resulting tree
> (it is merely one possible outcome), but is the lack of parents in the
> resulting commit.  So I would recommend against --empty.  --root might be
> a good synonym, though, and we _do_ already use that word for that purpose
> in some commands (e.g. "log --root").

--root could be a synonym but the reason I haven't chosen it was the
fact that it could mislead people to think the functionality will do
something with/based on the first commit of the actual branch,
subjectively thinking "THE ROOT".

IMHO --orphan (no parents) is more obvious.

We should argue one of our native English speaker amidst this
developer community to be sure.

Anyway that is just a word to change or not in the patch... :-)

Regards

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

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

> GitTips page of git wiki mentions this under "a new branch that has no
> ancestor", and speaks of a way to add "a new and empty branch".  Scott
> Chacon also creates "new empty branches" in the community book.

By the way, I would actually suggest updating these web pages not to make
it sound as if it is a good thing to create a new "empty" history (aka "no
common paths") in an existing repository.  Git wiki lists "create in a
separate repository and push into the same" as "The easy way", as if it is
easy-but-amateurish, making it sound as if experts should use different
ways for extra coolness point.  People may think that having branches like
'man' and 'html' in the same repository as I do is somehow cool, but it is
a total misconception.  That part of Git wiki page should be reworded to
reduce user confusion; "The easy way" is actually "the one true way".

While it indeed is useful to have them in the same public repository
(think of my git.git repository at k.org) for distribution purposes, it
does not mean that it is a good thing to create and manipulate these
unrelated histories in the same repository at all.  These two branches
(and the same thing can be said for 'todo' branch) are never checked out
in a repository with an worktree that normally checks out the primary
branches (e.g. 'master', 'next', etc.) nowhere in my workflow for two very
simple reasons:

 (1) doing so would disrupt the normal work done in the primary branches.

 (2) updating them requires a separate checkout of the primary branch
     anyway.

Growing these histories are done in separate repositories unrelated to the
primary project worktree; they are pushed into the same public repository
only for ease of cloning, for Documentation/install-doc-quick.sh script to
run a moral equivalent of "tar-tree | (cd elsewhere && tar xf -)".

And even the "ease-of-cloning" is merely a justfication after the fact.
The original and the only reason why these pregenerated documentation
branches are in the same distribution repository is because I only have
write privilege to /pub/scm/git/git.git/ at k.org, and not to the whole
/pub/scm/git/ hierarchy.  Otherwise I may have published these unrelated
branches in their own repositories (e.g. /pub/scm/git/docs.git/) and made
install-doc-quick.sh use data from there; it might have avoided confusing
end users, perhaps.

It also might be useful to extend these pages with the "going open source?
here is how to use a 'mostly same paths' disconnected history to do so"
example from the discussion.  That workflow I can see how it may make
sense to use "checkout --orphan" to create the new history in the same
repository.

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

[Michael J Gruber]

Erick Mattos venit, vidit, dixit 21.03.2010 22:15:
> Hi,
> 
> 2010/3/21 Junio C Hamano <gitster@pobox.com>:
>> I'm not native either, and "orphan" sounded strange in that we've never
>> used that word in any of our use case or workflow description in our
>> documents.
> 
> I didn't know.  I thought you were American.
> 
>> The main point of the feature is not the emptyness of the resulting tree
>> (it is merely one possible outcome), but is the lack of parents in the
>> resulting commit.  So I would recommend against --empty.  --root might be
>> a good synonym, though, and we _do_ already use that word for that purpose
>> in some commands (e.g. "log --root").
> 
> --root could be a synonym but the reason I haven't chosen it was the
> fact that it could mislead people to think the functionality will do
> something with/based on the first commit of the actual branch,
> subjectively thinking "THE ROOT".
> 
> IMHO --orphan (no parents) is more obvious.
> 
> We should argue one of our native English speaker amidst this
> developer community to be sure.

[Disclosure: non-native speaker but having lived with natives ;)]

I'd favour "root" for several reasons:

- "root" is the correct technical term in graph theory
- "root" is used the same way in other (Git) places
- "orphan" is someone who used to have parents, so with "orphan" I would
rather associate the process of removing parents from the picture
(removing parentship information from an existing commit)

Just my two Euro-cents :)
Michael

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

[Chris Johnsen]

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

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

[Chris Johnsen]

2010/3/21 Junio C Hamano <gitster@pobox.com>:
> The main point of the feature is not the emptyness of the resulting  
> tree
> (it is merely one possible outcome), but is the lack of parents in the
> resulting commit.  So I would recommend against --empty.  --root  
> might be
> a good synonym, though, and we _do_ already use that word for that  
> purpose
> in some commands (e.g. "log --root").

On 2010 Mar 21, at 16:15, Erick Mattos wrote:
> --root could be a synonym but the reason I haven't chosen it was the
> fact that it could mislead people to think the functionality will do
> something with/based on the first commit of the actual branch,
> subjectively thinking "THE ROOT".

The existing uses of --root are close to, but not identical to this  
proposed usage. The existing uses all relate to handling the already  
created root commit(s) of a commit/branch/repository. This proposed  
usage relates to the yet to be created first commit on the new  
branch. It is possible to use the "already created" interpretation in  
this context (create a new branch based on the root commits of the  
specified commits), but it really does not make much sense. Still,  
qualifying "root" might help prevent some confusion:

     --new-root
     --fresh-root
     --root-branch?

     --new-history
     --fresh-history
     --fresh-branch

Logically, both --orphan and --root are descriptions of the commit  
that will _eventually_ be stored under the branch, but not  
descriptions of the transient state of the branch itself. This state  
is described in a few error/warning messages as "not yet born" or  
"unborn" (checkout, pull, fsck). It seems to be an unofficial term  
though (or maybe just unimportant) since it is not otherwise  
documented (it is not in the glossary, but it does appear in the  
release notes a few times). So with some weight of existing  
terminology behind it:

     --unborn

--no-parent was mentioned elsewhere in the thread, but it suffers  
from looking like a negation of a potential --parent option. Though  
much longer, --without- does not suffer this same problem.

     --without-parents
     --without-history
     --ahistorically    (probably the non-standard prefix is too  
"native")

     --ex-nihilo        (just kidding?)

-- 
Chris

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

[Erick Mattos]

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

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

[Erick Mattos]

Hi again,

2010/3/22 Chris Johnsen <chris_johnsen@pobox.com>:
> The existing uses of --root are close to, but not identical to this proposed
> usage. The existing uses all relate to handling the already created root
> commit(s) of a commit/branch/repository. This proposed usage relates to the
> yet to be created first commit on the new branch. It is possible to use the
> "already created" interpretation in this context (create a new branch based
> on the root commits of the specified commits), but it really does not make
> much sense. Still, qualifying "root" might help prevent some confusion:
>
>    --new-root
>    --fresh-root
>    --root-branch?
>
>    --new-history
>    --fresh-history
>    --fresh-branch
>
> Logically, both --orphan and --root are descriptions of the commit that will
> _eventually_ be stored under the branch, but not descriptions of the
> transient state of the branch itself. This state is described in a few
> error/warning messages as "not yet born" or "unborn" (checkout, pull, fsck).
> It seems to be an unofficial term though (or maybe just unimportant) since
> it is not otherwise documented (it is not in the glossary, but it does
> appear in the release notes a few times). So with some weight of existing
> terminology behind it:
>
>    --unborn
>
> --no-parent was mentioned elsewhere in the thread, but it suffers from
> looking like a negation of a potential --parent option. Though much longer,
> --without- does not suffer this same problem.
>
>    --without-parents
>    --without-history
>    --ahistorically    (probably the non-standard prefix is too "native")
>
>    --ex-nihilo        (just kidding?)
>
> --
> Chris
>

2010/3/22 Michael J Gruber <git@drmicha.warpmail.net>:
> [Disclosure: non-native speaker but having lived with natives ;)]
>
> I'd favour "root" for several reasons:
>
> - "root" is the correct technical term in graph theory
> - "root" is used the same way in other (Git) places
> - "orphan" is someone who used to have parents, so with "orphan" I would
> rather associate the process of removing parents from the picture
> (removing parentship information from an existing commit)
>
> Just my two Euro-cents :)
> Michael

I really don't care about names as long as I will be able to create
the 'orphan' branches.

Whatever you people decide is good to me.

Regards

Translating error messages in Git (was: Re: [PATCH v3] git checkout: create unparented branch by --orphan)

[Jakub Narebski]

Erick Mattos <erick.mattos@gmail.com> writes:

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

Git uses gettext, but only for gitk and git-gui.

The problem is that git is written in C (which can use gettext), Perl
(which can use Locale::Maketext / Locale::Maketext::Gettext), but has
also some commands that are written in (POSIX) shell script.  The
$"..." syntax for message localization is bash-ism, and additionally
it is deprecated

-- 
Jakub Narebski
Poland
ShadeHawk on #git

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

[Junio C Hamano]

Chris Johnsen <chris_johnsen@pobox.com> writes:

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

Strictly speaking, an orphan branch allows you to start a new history that
does not have any existing commit as its ancestry, and that is all there
to it.  While the "mostly common paths" aspect is worth mentioning, as it
is the use case it primarily targets, it is still secondary to the
description of "what it does."  "What it is used for" should come after
the reader is told "what it does."

It would probably be better to say that the index and the working tree is
kept intact during --orphan process as part of "what it does", before
talking about "mostly common paths":

	Create a new branch <new_branch> and switch to it.  The first
	commit you will make on this branch will become the root of a new
	history, disconnected from any of existing commits.  

	The index and the working tree is adjusted as if you ran "git
	checkout <start_point>" (without -b nor paths), to allow you to
	easily record the root commit of the 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.

Good.

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

Good, even though I am tempted to suggest rephrasing it further:

        If you want to start a disconnected history that records a set of
        paths that is totally different from <start_point>, you could
        clear the index and the working tree after creating the orphan
        branch by running `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.
	In general, however, it is cleaner and easier to create such an
        unrelated history in a separate repository than creating in the
        same repository.