Re: [PATCH v3] Docs: git checkout --orphan: `root commit' and `branch head'

[Junio C Hamano <gitster@pobox.com>]

Michael Witten <mfwitten@gmail.com> writes:

> See:
>
>   Re: Can a git changeset be created with no parent
>   Carlos Martín Nieto <cmn@elego.de>
>   Message-ID: <1317073309.5579.9.camel@centaur.lab.cmartin.tk>
>   http://article.gmane.org/gmane.comp.version-control.git/182170
>
> and:
>
>   git help glossary

I think I had to tell somebody on this list not to do this no more than a
month ago.

It is a good practice to point to earlier discussions while polishing
patch, and it also is good to include pointers in the commit log message
as a _supporting material_ (additional reading), but that is *NOT* a
substitute for a properly written commit log message. You need to state
what problem you are trying to fix and how the proposed patch fixes it.

Pretty please.

As to what the updated text wants to talk about, I think most of them are
improvement, but there are a few glitches and nits.

> diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
> index c0a96e6..0b6e528 100644
> --- a/Documentation/git-checkout.txt
> +++ b/Documentation/git-checkout.txt
> @@ -125,29 +125,54 @@ explicitly give a name with '-b' in such a case.
>  	below for details.
>  
> ---orphan::
> -	Create a new 'orphan' branch, named <new_branch>, started from
> -	<start_point> and switch to it.  The first commit made on this
> -	new branch will have no parents and it will be the root of a new
> -	history totally disconnected from all the other branches and
> -	commits.
> -+
> -The index and the working tree are adjusted as if you had previously run
> -"git checkout <start_point>".  This allows you to start a new history
> -that records a set of paths similar to <start_point> by easily running
> -"git commit -a" to make the root commit.
> -+
> -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 the one of <start_point>, then you should
> -clear the index and the working tree right after creating the orphan
> -branch by running "git rm -rf ." from the top level of the working tree.
> -Afterwards you will be ready to prepare your new files, repopulating the
> -working tree, by copying them from elsewhere, extracting a tarball, etc.
> +--orphan::
> +	Tell git to turn the next commit you create into a root commit
> +	(that is, a commit without any parent); creating the next commit
> +	is similar to creating the first commit after running "git{nbsp}init",

I do not think we ever used {nbsp} in our documentation set. Is it
absolutely necessary to use it in this context, and are you absolutely
sure this does not break various versions of documentation toolchain
people have?

> +	except that the new commit will be referenced by the branch head
> +	<new_branch> rather than "master".

The option works as a substitute for -B/-b in the sense that it takes a
name of the new branch, and the only difference is that the new branch
will start with no commit (yet).  To reduce confusion, it might make sense
to update this part (and description of -b/-B) to begin like this:

	--orphan <new_branch>::

to match the new explanation text, and the output from "git checkout -h".
By the way, shouldn't the entry for -b in "git checkout -h" output also
say <new branch>?

Micronit: "referenced by the branch head <new_branch>" might be easier to
read and understand with s/branch head/branch name/. Or perhaps

	except that the new commit will be made on <new_branch> branch
        rather than "master".

might be even better.

> ++
> +Furthermore, the working tree and index are adjusted as if you ran
> +"git{nbsp}checkout{nbsp}<start_point>"; thus, by just running
> +"git{nbsp}commit", you can create a root commit with a tree that is
> +exactly the same as the tree of <start_point>.
> ++
> +Naturally, before creating the commit, you may manipulate the index
> +in any way you want. ...

What value does "Naturally, " add to the understanding here? I would
understand if it were "Alternatively, ", though.

> +... For example, if you want to create a root commit
> +with a tree that is totally different from the tree of <start_point>,
> +then just clear the working tree and index first: From the top level
> +of the working tree, run "git{nbsp}rm{nbsp}-rf{nbsp}.", and then
> +prepare your new working tree and index as desired.
> ++
> +There are two common uses for this option:
> ++
> +--
> +	Separate history::
> +		Suppose that for convenience, you want to maintain
> +		the website for your project in the same repository
> +		as the project itself. In such a case, it may not
> +		make much sense to interleave the history of the
> +		website with the history of the project; you can use
> +		the "--orphan" option in order to create these two
> +		completely separate histories.

I suspect this is *not* common at all, and also because you would need a
working tree to update both lines of histories that are not related to
each other at all at the content level, I do not believe that "for
convenience" supports or justifies the use case at all. It would be less
convenient to update these two unrelated histories (switching between
branches would need to nuke the whole working tree, and the semantics to
carry local changes floating on top of the tip commit of the current
branch across branch switching actively works against you).

You would be better off using another repository to keep track of "the
website for your project".

In short, I do not think we would want to list the above as if we are
somehow encouraging the use of this option for such a use. It falls into
"because with --orphan you _could_", and definitely not "because having
these two unrelated projects in the same repository you work in is
convenient and/or necessary".

> +	Hidden history::
> +		Suppose you have a project that has proprietary
> +		material that is never meant to be released to the
> +		public, yet you now want to maintain an open source
> +		history that may be published widely.

This cause does make sense; you would want the local changes floating on
top of the tip commit of the current branch carried across branch
switching.

> +In this case, it would not be enough just to remove the proprietary
> +material from the working tree and then create a new commit, because
> +the proprietary material would still be accessible through the new
> +commit's ancestry; the proprietary history must be hidden from the new
> +commit, and the "--orphan" option allows you to do so by ensuring that
> +the new commit has no parent.

Does this "In this case" paragraph format as part of the "Hidden history"
paragraph?

> ++
> +However, removing proprietary material from ancestry is usually a task
> +that is better performed by linkgit:git-filter-branch[1] and
> +linkgit:git-rebase[1], especially when there are multiple commits that
> +are already suitable for the open source history.
> +--

In general it is true, and not "especially". When you are just abandoning
the history and publishing tidied up tree without history afresh.

I suspect this is not exactly "filter-branch is better but you could use
checkout --orphan" like you made it sound in the above paragraph.  If you
are bootstrapping a new open source project from the tip of a proprietary
tree, "checkout --orphan && edit to sanitize && commit" to start your
history afresh would be perfectly adequate for your PR people to say "Now
we are open", especially when you do not intend to accept fixes to older
revisions; you could filter-branch the older proprietary history but you
would not get much benefit out of the cost for doing so, I think.

Thanks.