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

Michael Witten [off-list ref] writes:

-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.

This part used to be just this in v1:

-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
+This can be useful when you want to publish a tree without exposing its
+full history; for instance, 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.

is it intentionnal that you discarded completely the paragraph? If so,
then I disagree, the paragraph was one of the main motivation for
someone to use --orphan, without it, someone may understand _what_ it
does, but not _why_ it is useful.

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/

On Tue, Sep 27, 2011 at 16:01, Matthieu Moy
[off-list ref] wrote:

Michael Witten [off-list ref] writes:

quoted

-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.

This part used to be just this in v1:

-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
+This can be useful when you want to publish a tree without exposing its
+full history; for instance, 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.

is it intentionnal that you discarded completely the paragraph? If so,
then I disagree, the paragraph was one of the main motivation for
someone to use --orphan, without it, someone may understand _what_ it
does, but not _why_ it is useful.

It was intentional; I was finding it difficult to express that
paragraph succintly in a way that is consistent with correct
terminology. Then I realized it's fairly redundant, anyway.

I think that the last paragraph provides enough context to understand
its usefulness. Also, anybody who ever independently decided to carve
out proprietary bits in that way would immediately recognize the need
for creating a commit without parents, a notion which would lead him
or her pretty quickly to this documentation or jog his or her memory
about it based on the text of v2.

If everyone else is quite set on keeping that paragraph, though, I'll
take the challenge; however, I think that would be a waste of time.

From: "Matthieu Moy" <redacted>

Michael Witten [off-list ref] writes:

quoted

-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.

This part used to be just this in v1:

-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
+This can be useful when you want to publish a tree without exposing its
+full history; for instance, 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.

is it intentionnal that you discarded completely the paragraph? If so,
then I disagree, the paragraph was one of the main motivation for
someone to use --orphan, without it, someone may understand _what_ it
does, but not _why_ it is useful.

-- 

I agree - it would be wrong to discard the explanation of why it is used. As 
a relatively new git user, the man pages do need to properly inform the 
usage.

I have some orphan [i.e. independant] branches that are for documentation 
and for old matlab code that are both part of the project, but are separate 
from the various code branches. The original term `--orphan` was meaningful, 
though I do agree about it being a root commit.

It can be very easy for those that already know to presume knowledge of the 
reader that the reader doesn't have, leaving both sides frustrated. Reading 
the full manual could be a life times work to get all the nuances.

See:

  Re: Can a git changeset be created with no parent
  Carlos Martín Nieto [off-list ref]
  Message-ID: [off-list ref]
  http://article.gmane.org/gmane.comp.version-control.git/182170

and:

  git help glossary

Signed-off-by: Michael Witten <redacted>
---
 Documentation/git-checkout.txt |   65 +++++++++++++++++++++++++++------------
 1 files changed, 45 insertions(+), 20 deletions(-)

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",
+	except that the new commit will be referenced by the branch head
+	<new_branch> rather than "master".
++
+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. 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.
+
+	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.
++
+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.
++
+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.
+--
 
 -m::
 --merge::

-- 
1.7.6.409.ge7a85