v3git checkout -b: unparent the new branch with -o

Sometimes it is interesting to start a new unparented branch in an existing repository.

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 committed. Before committing you should 'git rm -rf' anything which is not going to take part in the new branch and change the work tree and index the way you want it to be since they remain untouched as before checkout command.

There are two potential work flows where this feature is most useful:

(1) "mostly common paths" work flow; (2) "no common paths" work flow;

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

Major rewrite to conform to Junio's demands.

Now after checkout to the new unparented branch, the index and the work tree remain unchanged.

 Documentation/git-checkout.txt |   13 ++++++++++
 builtin/checkout.c             |   10 ++++++-
 t/t2017-checkout-orphan.sh     |   49 ++++++++++++++++++++++++++++++++++++++++
 3 files changed, 70 insertions(+), 2 deletions(-)
 create mode 100755 t/t2017-checkout-orphan.sh

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

This paragraph makes the patch incoherent. It talks as if "no common paths" is the majority case, and everybody inconveniently has to perform an extra step that shouldn't be needed if the implementation were done right. If "no common paths" is indeed the assumed primary target, why doesn't the implementation empty both index and files in the working tree so that users don't have to do so themselves?

My _only_ complaint was that your version that _only_ emptied the index without touching the working tree made things difficult for everybody, both "no common paths" people and "mostly common paths" people.

You need to at least qualify the above paragraph with something like "if you want to create an unrelated branch whose contents do not resemble the original branch at all, then you should ...".

Better yet, try to advertise what you are giving your users in a positive way, instead of in a way that only scares users, perhaps like this:

    After 'checkout --orphan', your HEAD will point at an unborn branch,
    and the next commit will start a new history without any prior commit.
    To help create such a new history that has contents mostly the same as
    that of the original branch, the command does not touch the index nor
    the working tree, and "checkout --orphan" immediately followed by
    "commit -a" would record a tree very similar to what you had in the
    original branch.  This is useful when you want to ... [insert a
    summary of "going open source" example from my previous message if you
    want here].

    If on the other hand you want to start a new branch whose contents do
    not resemble the original branch at all, you may want to start from an
    empty index and the working tree, with "git rm -rf ." immediately
    after running this command.

The same comment applies to the documentation part.

By the way, I wouldn't mind if you believe "no common paths" is the majority case; if that is the case, then the code and behaviour would be different, and the presentation would say something like this:

    After 'checkout --orphan', your HEAD will point at an unborn branch,
    and the next commit will start a new history without any prior commit.
    To help create such a new history that has contents totally different
    from the original branch, the command empties the index and removes
    all tracked files from the working tree.  The command refuses to work
    if you have uncommitted changes, so that you won't lose them.
    Conclude the work in progress on your current branch first by first
    recording the changes in commits (or "git stash save") before
    re-running the command.

    After "checkout --orphan" you can immediately start preparing the
    files to be tracked in this new branch, without files unrelated to
    this branch getting in the way.  This is useful when you want to
    ... [I don't think any "no commmon paths" workflow makes sense to be
    done in the same repository, but you seem to do do so, so give readers
    such an example here].

    If on the other hand you want to start a new branch whose contents
    mostly match the original branch, you may need to start from an
    index and the working tree files from the original branch, by running
    "git checkout <original-branch-name> ."  after running this command.

Hi,

Junio, you are the leader. And I really don't want to bother you with my opinions.

I am just trying to make you satisfied so gitsters, I mean git users, will have this feature as soon as possible.

2010/3/16 Junio C Hamano <gitster@pobox.com>:

I was NOT trying to scare with my message. That paragraph was meant to let people who would need to do something ("no common paths") know what they will need to do. I think it is good enough because "mostly common paths" people will be happy too by knowing that everything is unchanged as they want it to be. So I haven't thought about scaring at all. I thought it was good indeed! :-)

Just to clarify my point-of-view about the design:

I do prefer my first design mainly because it mimics the state of an initial commit. I think that is subjectively better.

You have been asking me to make one of the two possible work flow uses you pictured as favored so things will be already set to them. No further commands to them.

I did it! As a matter of fact the "mostly common paths" people were favored as you have noticed your inclination to it before.

As I told you, I just want to make you happy so people that needs the feature I am working on could have it as fast as possible.

And if one of the possible work flows have to be favored then I do agree with you about "mostly common paths" as the best choice.

But the point is that the other group will need to do further commands anyway so I would keep my previous design because of the resemblance to an initial commit: work tree full and nothing added to the index.

But I mean it! I really want to satisfy you. So this was the last time I talk about my preference.

Therefore let's find out what you want me to do so we can finish this production cycle. I don't want to bother you anymore.

I was trying to be concise on my message.  I realize you want it more explained.

What about that:

After the 'checkout -o -b' you are in an new unborn branch ready to be committed. The next commit will start a new history without any ancestry. If this new branch was made to start from scratch, not resembling the previous one, then you should use 'git rm -rf' to get an empty work tree and index. Otherwise with a 'git commit -a' you will have a tree exactly as in the previous branch. So just set things as you want it to be and commit the new unparented branch.

I agree with you in choosing "mostly common paths" as the target since you have decided to target one.

Before I send another patch version could you please tell me your position about my new explaining text up there. I will wait for your reply before sending a new patch version.

Best regards

Hi,

Erick Mattos wrote:

Well, hopefully everyone wants it to make sense, too. :)

I guess I am confused because I am not sure what you are trying to do:

 A. on one hand, you might want a command to use as a building block.
    In practice, people would use scripts or refer to known recipes to
    make use of this building block in one of a few known combinations
    with other commands.

 B. on the other hand, you might be trying to make it easier to get
    some particular task done.

Junio was discussing the case B. Whoever has the itch is in a good position to say what interface would be convenient. Usually one command invocation can be enough to accomplish most of what is needed on its own. There were two examples of such commands he gave:

 1.                                                    * [public]
                                                        \
     * --- * --- * [private]   ===>    * --- * --- * --- * [private]

   for the “we cannot publish the whole history” use,

and

 2.                                                 * [doc]

    * --- * --- * [master]  ===>  * --- * --- * --- * [master]

   for the “starting unrelated development but restrictive disk quotas
   mean I have to use the same working directory” use.

In these examples (which are just examples for illustration of what a well supported use case looks like), the content in the index and work tree after the command is run is tailored to what is expected to be needed.

I suspect you are aiming for case A instead. For scripts and special case recipes, it might be a good idea to have a command to use as an ingredient in tasks like (1) and (2) above. The recipe people currently use is usually something like the following:

  git symbolic-ref HEAD refs/heads/newbranch
  rm .git/index

but that indeed is not perfect: it does not check for a dirty index in case 1, it does not keep track of what files were not registered in the index so as not to delete them in case 2, and so on.

Also one might object to the knowledge of repository layout required; gitrepository-layout(5) is probably not the first place a person would look in trying to figure out how to carry out this task. That misses the point, though, in my opinion, since

 git symbolic-ref HEAD refs/heads/newbranch
 git rm --cached '*'

accomplishes the same thing. Anyway, if your goal is to create plumbing, I would suggest modifying a plumbing command instead of ‘git checkout’.

Thank you for your efforts. As hinted above, I would not mind seeing improvement in this area at all. Anyway, I hope this has provided some food for thought (if not, don’t mind me; please carry on).

Kind regards, Jonathan

Jonathan Nieder <jrnieder@gmail.com> writes:

Well, not really. Even as an ingredient, "nuke index, leaving files in the work tree around" is the most difficult-to-use mode of operation. Either "try to run 'git rm -f .' from the toplevel and only if it succeeds point HEAD to an unborn branch" (aka "remove both"), or "point HEAD to an unborn branch without doing anything else" (aka "keep both") would be an ingredient that is far easier to use.

Junio C Hamano wrote:

Okay, fair enough. From the point of view of plumbing, what is there left to do that

	git rm -f . &&
	git symbolic-ref HEAD refs/heads/new

or

	git symbolic-ref HEAD refs/heads/new

or

	git rm --cached . &&
	git symbolic-ref HEAD refs/heads/new

does not take care of?

I guess I should have said that I would be happier to see something tailored to a use case or a class of use cases.

I haven’t needed it for a while, but once upon a time I was making isolated branches like crazy for some abuse of git as a compression tool.

Jonathan

Jonathan Nieder <jrnieder@gmail.com> writes:

If we have the "just detach, don't touch index nor working tree", which happens to be the cheapest one in the middle (except that it probably wants to verify that "new" does not exist yet), the calling script of the Porcelain suite can use it in conjunction with various forms of "git rm" without incurring any additional overhead (other than a fork-and-exec), and I think that would be sufficient.

You could add

	git ls-files |
        while read path
        do
        	case $(choose-keep-drop-nuke "$path") in
                keep) ;;
                drop) git rm --cached -f "$path" ;;
                nuke) git rm -f "$path" ;;
        	esac
	done
	git symbolic-ref HEAD refs/heads/new

and have the caller supply a callback that intelligently choose what to keep and what to drop, if you want to be really fancy, but at that level of complexity, I think it is something the Porcelain writer using the plumbing would want to write himself as part of the Porcelain program.

We might want to add "git branch --switch <branchname>" that is roughly like this:

    ref="refs/heads/$branch"
    git check-ref-format "$ref" || die "malformed"
    if git rev-parse -q --verify "$ref" >/dev/null
    then
    	# exists
        exec git checkout "$branch"
    else
	# create
	exec git symbolic-ref HEAD "$ref"
    fi

2010/3/17 Jonathan Nieder <jrnieder@gmail.com>:

Thanks for your kindness.

We are almost at the end of this new option creation cycle. We are now building the appropriated explaining messages.

This improvement is indeed targeted to let end users create orphan branches. I don't see a reason for changing focus because I see this need as eventual really.

Kind regards

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

Don't try to satisfy _me_ personally. It is not likely that I am going to use "checkout --orphan" myself. But I would not reject a new feature that does make sense to some people, even if it is not something I would use. I am here to help people like you help others (and to prevent people from harming others).

I however am going to have to answer when people complain "why was this senseless new feature added to the system? what it does makes no sense and does not help me."

"Nuke index but not working tree" is not something I think I can defend and explain as sensible to these people, as I do not think it makes sense myself. So when Ispot a design that logically does not make sense to me, I would say so and ask clarifications. A major part of the maintainer's job is to ask questions and say "no".

You keep saying that, but I think it is misguided. And I do not think there is anything subjective there.

If you are starting from scratch, you would:

    $ git init newrepo
    $ cd newrepo

and that is how the state before the initial commit begins with. You might then do this to prepare for the commit:

    $ tar xf ~/junk/frotz-2.43.tar.gz
    $ git add .

Or perhaps you would work the other way around:

    $ tar xf ~/junk/frotz-2.43.tar.gz
    $ cd frotz-2.43
    $ git init
    $ git add .

Whichever way you work, notice that you wouldn't have any rubbish in the working tree unrelated to the "frotz" project, when the tool (in this case, "git init") prepares the repository with a dangling HEAD and the working tree "before the initial commit". You either have emptiness (to which you can untar into), or you already have files that you would want to have in the branch and no other cruft.

If you did "nuke index, leaving files in the work tree around", the result does not resemble "state before the initial commit" at all. The leftover files will get in the way.

The leftover worktree files will not get in the way ONLY if the user wants to record a tree that is similar to the original branch, but even in that case they have to do "git add ."; keeping the index intact would help them even better.

After realizing all that, do you still think "nuke only the index" is subjectively better?

Sure, I am saying that then you should advertise the result as such, without being negative.

Concise is good.  Negative is not.

I wouldn't start the description with

    if you want 'no common paths', then it would be more cumbersome than
    just this single command

if the primary workflow your chose to support with your implementation is 'mostly common paths'.

Look at the example I gave you more carefully. The primary use case we intend to support is described first. Also it is written in much more inviting tone, in order to help readers understand the motivation behind the feature. IOW, "Ah, that is something I may want to do in some cases, and the new feature indeed sounds useful." is what we want to hear from the readers (the log message for reviewers, and the documentation for the end users) after they read the explanation. The second paragraph then mentions the less common use case for completeness. To the readers who understand why the behaviour of the command makes sense for its primary use case (which is described first), it would be easier to accept that they have to run an extra command (by the way, it is "'git rm -rf .' from the top-level of the working tree; do not forget the dot at the end) to clean up the working tree to a prestine state, because they would understand the reason why the clearing is not done by default.

The same comment applies to the documentation part of the patch. Don't be negative. Positively explain why what you added is useful, and help the users understand why they might want to use it and in what situation.