[PATCH] git checkout -b: unparent the new branch with -o

[PATCH] git checkout -b: unparent the new branch with -o

[Erick Mattos]

Sometimes it is necessary to start up a new development branch of code
intended to be merged in the near future to existing branches but which
actually does not relate to them.

The new -o/--orphan is intended to solve this situation allowing the
creation of a new branch unparented to any other.

After the 'checkout -o -b' the new branch is not saved until some files are
added to the index and committed, exactly as if it was an initial commit.
A 'git clean -df' would delete everything from the work tree making it
empty for new files.

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

This new option just make it easy to add orphan branches to git repositories.

There are a lot of hacks to do the same thing ( I had been using some!  :-) )
but this should be seen as a part of a normal work flow so just an option.

A good example to show the need of this option is a Debian folder of control
files.  Whenever a maintainer needs to debianize a source code to build
packages he needs to add a folder called Debian with a lot of files inside it.
Those files are connected to the source code of the program but they are not
really part of the program development.  On this situation using the new
option, that maintainer would do:

	git checkout -ob debian
	git clean -df
	mkdir Debian
	add all control files
	...hack it enough...
	git add Debian
	git commit

And then when ready to build the packages from the master branch he would just
need to merge or cherry-pick the Debian branch on it.  On this work flow both
developments occur paralleled and fuse only at the moment of building the
Debian's packages.

I have some other examples to tell but I think you people already have figured
the needs and possible uses out.  :-)

Kind regards

 builtin-checkout.c             |   14 +++++++++-
 t/t2017-checkout-orphan.sh     |   50 ++++++++++++++++++++++++++++++++++++++++
 3 files changed, 72 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..6534934 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 <new_branch> [-o]] [<start_point>]
 'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <paths>...
 'git checkout' --patch [<tree-ish>] [--] [<paths>...]
 
@@ -25,6 +25,10 @@ linkgit:git-branch[1] were called; in this case you can
 use the --track or --no-track options, which will be passed to `git
 branch`.  As a convenience, --track without `-b` implies branch
 creation; see the description of --track below.
+When using -b, it is possible to use the option -o to set the new branch
+as unparented thus unrelated to the previous branch.  The new code will
+be committed by using 'git add' and 'git commit' as if it was an initial
+commit.
 
 When <paths> or --patch are given, this command does *not* switch
 branches.  It updates the named paths in the working tree from
@@ -86,6 +90,11 @@ explicitly give a name with '-b' in such a case.
 	Do not set up "upstream" configuration, even if the
 	branch.autosetupmerge configuration variable is true.
 
+-o::
+--orphan::
+	When creating a new branch, set it up as unparented thus
+	unrelated to the previous branch.
+
 -l::
 	Create the new branch's reflog; see linkgit:git-branch[1] for
 	details.
diff --git a/builtin-checkout.c b/builtin-checkout.c
index c5ab783..4882613 100644
--- a/builtin-checkout.c
+++ b/builtin-checkout.c
@@ -34,6 +34,7 @@ struct checkout_opts {
 
 	const char *new_branch;
 	int new_branch_log;
+	int new_branch_orphan;
 	enum branch_track track;
 };
 
@@ -509,8 +510,13 @@ 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_branch_orphan) {
+			discard_cache();
+			remove_path(get_index_file());
+		}
+		else
+			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);
 	}
@@ -647,6 +653,7 @@ int cmd_checkout(int argc, const char **argv, const char *prefix)
 	struct option options[] = {
 		OPT__QUIET(&opts.quiet),
 		OPT_STRING('b', NULL, &opts.new_branch, "new branch", "branch"),
+		OPT_BOOLEAN('o', "orphan", &opts.new_branch_orphan, "make the new branch unparented"),
 		OPT_BOOLEAN('l', NULL, &opts.new_branch_log, "log for new branch"),
 		OPT_SET_INT('t', "track",  &opts.track, "track",
 			BRANCH_TRACK_EXPLICIT),
@@ -695,6 +702,9 @@ int cmd_checkout(int argc, const char **argv, const char *prefix)
 		opts.new_branch = argv0 + 1;
 	}
 
+	if (opts.new_branch_orphan && !opts.new_branch)
+		die("-o is used only with -b");
+
 	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..7170641
--- /dev/null
+++ b/t/t2017-checkout-orphan.sh
@@ -0,0 +1,50 @@
+#!/bin/sh
+#
+# Copyright (c) 2010 Erick Mattos
+#
+
+test_description='git checkout -b
+
+Tests for -o 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_expect_success '-b without -o checkout into a new clone branch' '
+	test_tick &&
+	echo "Test 1" >> "$TEST_FILE" &&
+	git add "$TEST_FILE" &&
+	git commit -m "Second Commit" &&
+	git log --pretty=oneline > base &&
+	git checkout -b alpha &&
+	test "alpha" = "$(git branch | sed -n "/*/s/\* //p")" &&
+	git log --pretty=oneline > actual &&
+	test_cmp base actual
+'
+
+test_expect_success '-b with -o checkout into an orphan branch' '
+	git checkout -ob beta &&
+	test -z "$(git branch | grep \*)" &&
+	test "beta" = "$(git symbolic-ref HEAD | sed "s,.*/,,")" &&
+	test -z "$(git ls-files)" &&
+	test_tick &&
+	echo "Test 2" >> "$TEST_FILE" &&
+	git add "$TEST_FILE" &&
+	git commit -m "Third Commit" &&
+	git log --pretty=oneline > actual &&
+	test 1 -eq $(wc -l actual | sed "s/ .*//") &&
+	! test_cmp base actual
+'
+
+test_expect_success '-o must be rejected without -b' '
+	test_must_fail git checkout -o alpha
+'
+
+test_done
-- 
1.7.0.84.g03684

Re: [PATCH] git checkout -b: unparent the new branch with -o

[Junio C Hamano]

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

> A good example to show the need of this option is a Debian folder of control
> files.  Whenever a maintainer needs to debianize a source code to build
> packages he needs to add a folder called Debian with a lot of files inside it.
> Those files are connected to the source code of the program but they are not
> really part of the program development.  On this situation using the new
> option, that maintainer would do:
>
> 	git checkout -ob debian
> 	git clean -df
> 	mkdir Debian
> 	add all control files
> 	...hack it enough...
> 	git add Debian
> 	git commit

I do not think that is a good example.

If you have an extract of an upstream tarball, say frotz-1.42.tar.gz, and
you are not porting anything older than that version, why not have two
branches, frotz and master, and do things this way?

 - frotz (or "vanilla" or "upstream") that keeps track of the "vendor
   drop" without debian/ directory;

 - master that forks from frotz and adds "debian/" and nothing else; and

 - any other topic branches that either fork from frotz if you are fixing
   upstream bug (or enhancing the vanilla version), or fork from master if
   you are fixing or enhancing the debianization.

When you receive frotz-1.43.tar.gz, you will advance 'frotz' branch with
it, and probably fork maint-1.42 branch from master so that you can keep
supporting older debianized frotz, while merging frotz into master so that
you can prepare a debianized version of newer package.

Your debianization will _never_ be totally independent of the vendor
version, so there is no good reason to have it as a rootless branch.

Re: [PATCH] git checkout -b: unparent the new branch with -o

[Jakub Narebski]

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

> Subject: [PATCH] git checkout -b: unparent the new branch with -o

I would say it is rather: "git checkout -b: allow creating unrelated branch",
or something like that.

By the way, for the solution to be complete it should work not only for 
"git checkout -b" shortcut, but also for "git branch".

>
> Sometimes it is necessary to start up a new development branch of code
> intended to be merged in the near future to existing branches but which
> actually does not relate to them.

I'm not sure if 'unrelated but _intended to merge_' is most common
workflow utilizing unrelated branches... and whether git should
promote such workflow, even if only describing it in the commit
message.

> 
> The new -o/--orphan is intended to solve this situation allowing the
> creation of a new branch unparented to any other.

I think that for example '--root', or '--rootless', or '--unrelated'
would be a better name than '--orphan'.  Besides I don't think that
such rarely used option should squat on rare resource of single-letter
option.

> 
> After the 'checkout -o -b' the new branch is not saved until some files are
> added to the index and committed, exactly as if it was an initial commit.
> A 'git clean -df' would delete everything from the work tree making it
> empty for new files.

Does it mean that the index is empty, but the working area is
unchanged?  It is not clear from the commit message.

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

> --- 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 <new_branch> [-o]] [<start_point>]

This is not stricly correct, as you can use either '-o' OR '<start_point>',
but not both (but you can use '-o' only together with '-b <new_branch>').



> +-o::
> +--orphan::
> +	When creating a new branch, set it up as unparented thus
> +	unrelated to the previous branch.
> +

Unparented?  Perhaps "set it up so first commit on this branch would
be root (parenless) commit".  Hmmm... it is not easy to describe it
well...

-- 
Jakub Narebski
Poland
ShadeHawk on #git

Re: [PATCH] git checkout -b: unparent the new branch with -o

[Erick Mattos]

Hi,

> > Subject: [PATCH] git checkout -b: unparent the new branch with -o
>
> I would say it is rather: "git checkout -b: allow creating unrelated branch",
> or something like that.

I don't see a point to change something specific to a general not yet
defined option.

>
> By the way, for the solution to be complete it should work not only for
> "git checkout -b" shortcut, but also for "git branch".

That is not the idea.  The idea is to start coding a new orphan
branch.  Not to create an empty orphan branch for later.

Also it is not meant to clone a commit to a new orphan branch.  Even
though this could be done, using "git checkout TARGET; git checkout
-ob NEW_BRANCH; git add .; git commit -C/-c TARGET --reset-author".

It is meant to start a parallel development which will be connected to
existing ones.  Of course there will be other possible uses (I always
trust in people inventiveness).

>
> >
> > Sometimes it is necessary to start up a new development branch of code
> > intended to be merged in the near future to existing branches but which
> > actually does not relate to them.
>
> I'm not sure if 'unrelated but _intended to merge_' is most common
> workflow utilizing unrelated branches... and whether git should
> promote such workflow, even if only describing it in the commit
> message.

This is dependent of point-of-view.  So thank you very much for sharing yours.

Anyway all those unrelated branches uses you mentioned would be
satisfied by this new option.

>
> >
> > The new -o/--orphan is intended to solve this situation allowing the
> > creation of a new branch unparented to any other.
>
> I think that for example '--root', or '--rootless', or '--unrelated'
> would be a better name than '--orphan'.  Besides I don't think that
> such rarely used option should squat on rare resource of single-letter
> option.

Parent is the term employed even by the commits itself to describe the
commit of origin so I don't think those suggestions are nice.  I do
agree about the importance of single-letters because we only have 26
but in this case it would be only the fifth used.

> >
> > Signed-off-by: Erick Mattos <erick.mattos@gmail.com>
> > ---
>
> [...]
>
> > --- 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 <new_branch> [-o]] [<start_point>]
>
> This is not stricly correct, as you can use either '-o' OR '<start_point>',
> but not both (but you can use '-o' only together with '-b <new_branch>').

You are right on that because start_point would be useless.

>
>
>
> > +-o::
> > +--orphan::
> > +     When creating a new branch, set it up as unparented thus
> > +     unrelated to the previous branch.
> > +
>
> Unparented?  Perhaps "set it up so first commit on this branch would
> be root (parenless) commit".  Hmmm... it is not easy to describe it
> well...

Everything we try do define with human language is incomplete.  So we
normally employ added layers of information to better describe things
as much as requested.

In our case we start with a single word represented by a letter or not
that try to give an idea.  If not enough, by --help or when people use
it incorrectly they will get a small message describing the intended
use better.  Then by a 'man' a paragraph.  Further text is added to
the 'man' if necessary. And then the help files, tutorials and other
people.

I think all off those steps were taken correctly in this case and that
what is written now is good enough.

Thank you very much for your comments.  I did appreciate it.

Best regards.

Re: [PATCH] git checkout -b: unparent the new branch with -o

[Erick Mattos]

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

> A good example to show the need of this option is a Debian folder of control
> files.  Whenever a maintainer needs to debianize a source code to build
> packages he needs to add a folder called Debian with a lot of files inside it.
> Those files are connected to the source code of the program but they are not
> really part of the program development.  On this situation using the new
> option, that maintainer would do:
>
>       git checkout -ob debian
>       git clean -df
>       mkdir Debian
>       add all control files
>       ...hack it enough...
>       git add Debian
>       git commit

I do not think that is a good example.

If you have an extract of an upstream tarball, say frotz-1.42.tar.gz, and
you are not porting anything older than that version, why not have two
branches, frotz and master, and do things this way?

 - frotz (or "vanilla" or "upstream") that keeps track of the "vendor
  drop" without debian/ directory;

 - master that forks from frotz and adds "debian/" and nothing else; and

 - any other topic branches that either fork from frotz if you are fixing
  upstream bug (or enhancing the vanilla version), or fork from master if
  you are fixing or enhancing the debianization.

When you receive frotz-1.43.tar.gz, you will advance 'frotz' branch with
it, and probably fork maint-1.42 branch from master so that you can keep
supporting older debianized frotz, while merging frotz into master so that
you can prepare a debianized version of newer package.

Your debianization will _never_ be totally independent of the vendor
version, so there is no good reason to have it as a rootless branch.

Re: [PATCH] git checkout -b: unparent the new branch with -o

[Erick Mattos]

Thanks for the fast response.  Your level of commitment to this
project is awesome!

2010/2/23 Junio C Hamano <gitster@pobox.com>
>
> >       git checkout -ob debian
> >       git clean -df
> >       mkdir Debian
> >       add all control files
> >       ...hack it enough...
> >       git add Debian
> >       git commit
>
> I do not think that is a good example.

Well it is just an example. Its intention is to show some practical
data about this proposition.

> If you have an extract of an upstream tarball, say frotz-1.42.tar.gz, and
> you are not porting anything older than that version, why not have two
> branches, frotz and master, and do things this way?
>
>  - frotz (or "vanilla" or "upstream") that keeps track of the "vendor
>   drop" without debian/ directory;
>
>  - master that forks from frotz and adds "debian/" and nothing else; and
>
>  - any other topic branches that either fork from frotz if you are fixing
>   upstream bug (or enhancing the vanilla version), or fork from master if
>   you are fixing or enhancing the debianization.
>
> When you receive frotz-1.43.tar.gz, you will advance 'frotz' branch with
> it, and probably fork maint-1.42 branch from master so that you can keep
> supporting older debianized frotz, while merging frotz into master so that
> you can prepare a debianized version of newer package.

The main point here is not the way one prefers to work.  It is to let
one works the way one wants.  In other words: give more versatility to
what is already working fine.

> Your debianization will _never_ be totally independent of the vendor
> version, so there is no good reason to have it as a rootless branch.

In matter of fact, mine, personally, is.  Please follow:
I normally hack software I want to add features I feel is lacking.  As
a Debian user when I compile it at last to install my version I always
do Debian packages so to let APT do its works.  As I like not to
reinvent the wheel I normally extract the Debian folder from the
normal repository packages.

So after a while I just have in a separate Debian branch the commit
1.5, 1.6, ....  In case I have to change the Debian files then I will
have my commits spread in the middle of this branch.

But as what I had pictured before was a general approach then or you
could be right on your example work flow or separating it could be
better or whatever!  It was just an example.

All commits I post are stuff I use which, following free software
ideology, I just want to share so other people could use it too.  I
know how limited my efforts are to a project like git.  A project like
that needs people really involved and pro-active like you.  But even
being a small contributor I really like to contribute because I think
the approach of free software community is the best for all and it
should be supported by everyone who cares.

I hope some day we could find a way to spread this ideology to
everything else in our society.  Working just to make things better
for no other direct reason; communitarian development; freedom and
demo/meritocracy; ...  :-)

Sorry for writing too much.

Regards.

Re: [PATCH] git checkout -b: unparent the new branch with -o

[Erick Mattos]

Sorry for the e-mail sent wrong (GMANE/140995).  The message was
screwed by gmail by sending it in HTML which git list blocked.  I had
to forward another and mistakenly copied Junio's.

2010/2/24 Erick Mattos <erick.mattos@gmail.com>:
> Erick Mattos <erick.mattos@gmail.com> writes:
>
>> A good example to show the need of this option is a Debian folder of control
>> files.  Whenever a maintainer needs to debianize a source code to build
>> packages he needs to add a folder called Debian with a lot of files inside it.
>> Those files are connected to the source code of the program but they are not
>> really part of the program development.  On this situation using the new
>> option, that maintainer would do:
>>
>>       git checkout -ob debian
>>       git clean -df
>>       mkdir Debian
>>       add all control files
>>       ...hack it enough...
>>       git add Debian
>>       git commit
>
> I do not think that is a good example.
>
> If you have an extract of an upstream tarball, say frotz-1.42.tar.gz, and
> you are not porting anything older than that version, why not have two
> branches, frotz and master, and do things this way?
>
>  - frotz (or "vanilla" or "upstream") that keeps track of the "vendor
>  drop" without debian/ directory;
>
>  - master that forks from frotz and adds "debian/" and nothing else; and
>
>  - any other topic branches that either fork from frotz if you are fixing
>  upstream bug (or enhancing the vanilla version), or fork from master if
>  you are fixing or enhancing the debianization.
>
> When you receive frotz-1.43.tar.gz, you will advance 'frotz' branch with
> it, and probably fork maint-1.42 branch from master so that you can keep
> supporting older debianized frotz, while merging frotz into master so that
> you can prepare a debianized version of newer package.
>
> Your debianization will _never_ be totally independent of the vendor
> version, so there is no good reason to have it as a rootless branch.
>