Erick Mattos <erick.mattos@xxxxxxxxx> writes:
> Sometimes it is interesting to start a new unparented branch in an
> existing repository.
You don't have to be "interesting". It is enough to say what it does and
how it is used; leave it to readers to judge if they find it useful and
worthwhile addition.
> 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' you are in an new unborn branch ready to be
> committed which will start a new history without any ancestry.
>
> By a 'git commit -a' the commit tree is going to resemble the one from
> the previous branch. This way you begin a "mostly common paths" work
> flow.
>
> In case you are doing this orphan branch intending to start a "no common
> paths" work flow then with a 'git rm -rf .' you are ready to go.
>
> Signed-off-by: Erick Mattos <erick.mattos@xxxxxxxxx>
> ---
>
> Trying to be concise and more positive on this new option descriptions. :-)
Here is my take on it:
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 before it.
"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 either resemble, the one from the original branch.
When creating a branch whose trees have no resemblance to the one 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".
I realized that -o shouldn't be an additional option to -b, but should be
an option that is incompatible with -b (and everything that is
incompatible with -b); --orphan without -b does not make any sense, and
having to type -b when you mean to also say --orphan feels silly.
Also it is a very special purpose mode of operation that would be rarely
used in a normal workflow, so I'd rather not give it short-and-sweet -o
from the beginning. It is not too late to consider adding a short-hand
only after people gained experience with it, and found that they were
using the option every hour.
> +'git checkout' [-q] [-f] [-m] [-b <new_branch> [-o]]
> 'git checkout' [-q] [-f] [-m] [-b <new_branch>] [<start_point>]
So I think these two lines should instead be a single:
'git checkout' [-q] [-f] [-m] [[-b|--orphan] <new_branch>] [<start_point>]
I didn't see anything wrong to start a new rootless branch starting from a
commit that is different from where you currently are (did your
implementation forbid giving an explicit <start_point>, by the way?).
Side note:
Quiz: What does this sequence do?
$ git checkout --orphan new
$ git checkout -
> @@ -26,6 +27,18 @@ 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. After the command
> +you are in an new unborn branch ready to be committed which will start a
> +new history without any ancestry.
> +
> +By a 'git commit -a' the commit tree is going to resemble the one from
> +the previous branch. This way you begin a "mostly common paths" work
> +flow.
> +In case you are doing this orphan branch intending to start a "no common
> +paths" work flow then with a 'git rm -rf .' you are ready to go.
> +
Readers won't know what you are talking about by "mostly common paths
workflow" nor "no common paths workflow".
In any case, I am suggesting to make --orphan separate and parallel to -b,
so how about removing all of the above, and instead have this:
--orphan::
Creates a new branch and switches to it, but unlike "-b", the new
branch you switch to does not have any commit (yet). The first commit
in this state will become the root commit of the new history that is
disconnected from all the other branches.
+
When you use "--orphan", the index and the working tree are kept 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
... [insert the "the original history cannot be shown" example here],
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 files in 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.
If you cannot give a good use example in-line, you may instead only say
"see EXAMPLES section to see how this is useful" in the above, and then
give a more detailed description in the EXAMPLES section.
I already suggested a replacement above, so everything below is a bit of
moot point, but I am giving it just for a future reference.
> +-o::
> +--orphan::
> + When creating a new branch, set it up as unparented thus
> + unrelated to the previous branch.
One good trick I learned when writing
manual pages is that if you said "A thus B" or "A (in other words B)",
stop and read it again to see if the description makes sense with only "B"
without any frills. It often becomes easier to understand, and if it
doesn't then it often means your rephasing with "thus" or "in other words"
weren't very helpful for readers. E.g.
Create a new branch that is unrelated to the previous branch.
I think "unrelated" does not convey what we want to say. Two topic
branches that fork from the same commit may be "unrelated" in the sense
that they try to fix two independent bugs. What we want to say is not
"related or not", but "with a separate root", or "disconnected".
--
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