Erick Mattos <erick.mattos@xxxxxxxxx> writes:
> 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.
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.
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html