{"thread":{"id":"23122","subject":"[PATCH v3] git checkout: create unparented branch by --orphan","startedAt":"2010-03-21T15:34:38Z","lastAt":"2010-03-22T20:19:11Z","messageCount":13,"participants":["Erick Mattos","Peter Baumann","Junio C Hamano","Michael J Gruber","Chris Johnsen","Jakub Narebski"],"isPatch":true,"patchVersion":3,"patchTotal":null},"messages":[{"id":"137450","messageId":"1269185678-3039-1-git-send-email-erick.mattos@gmail.com","threadId":"23122","inReplyTo":null,"subject":"[PATCH v3] git checkout: create unparented branch by --orphan","fromName":"Erick Mattos","fromEmail":"erick.mattos@gmail.com","sentAt":"2010-03-21T15:34:38Z","receivedAt":"2010-03-21T15:34:38Z","isPatch":true,"sender":{"key":"erick.mattos@gmail.com","avatar":"https://avatars.githubusercontent.com/u/134001?v=4"},"body":"Similar to -b, --orphan creates a new branch, but it starts without any\ncommit.  After running \"git checkout --orphan newbranch\", you are on a\nnew branch \"newbranch\", and the first commit you create from this state\nwill start a new history without any ancestry.\n\n\"git checkout --orphan\" keeps the index and the working tree files\nintact in order to make it convenient for creating a new history whose\ntrees resemble the ones from the original branch.\n\nWhen creating a branch whose trees have no resemblance to the ones from\nthe original branch, it may be easier to start work on the new branch by\nuntracking and removing all working tree files that came from the\noriginal branch, by running a 'git rm -rf .' immediately after running\n\"checkout --orphan\".\n\nSigned-off-by: Erick Mattos <erick.mattos@gmail.com>\n---\n\nFinal patch version (I think so... :-) ).\n\nAdded some further script tests by Junio.\n\n Documentation/git-checkout.txt |   21 +++++++++-\n builtin/checkout.c             |   15 ++++++-\n t/t2017-checkout-orphan.sh     |   90 ++++++++++++++++++++++++++++++++++++++++\n 3 files changed, 123 insertions(+), 3 deletions(-)\n create mode 100755 t/t2017-checkout-orphan.sh\n\ndiff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\nindex 37c1810..5a50997 100644\n--- a/Documentation/git-checkout.txt\n+++ b/Documentation/git-checkout.txt\n@@ -9,7 +9,7 @@ SYNOPSIS\n --------\n [verse]\n 'git checkout' [-q] [-f] [-m] [<branch>]\n-'git checkout' [-q] [-f] [-m] [-b <new_branch>] [<start_point>]\n+'git checkout' [-q] [-f] [-m] [[-b|--orphan] <new_branch>] [<start_point>]\n 'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <paths>...\n 'git checkout' --patch [<tree-ish>] [--] [<paths>...]\n \n@@ -90,6 +90,25 @@ explicitly give a name with '-b' in such a case.\n \tCreate the new branch's reflog; see linkgit:git-branch[1] for\n \tdetails.\n \n+--orphan::\n+\tCreate a new branch named <new_branch>, unparented to any other\n+\tbranch.  The new branch you switch to does not have any commit\n+\tand after the first one it will become the root of a new history\n+\tcompletely unconnected from all the other branches.\n++\n+When you use \"--orphan\", a new unparented branch is created having the\n+index and the working tree intact.  This allows you to start a new\n+history that records set of paths similar to that of the start-point\n+commit, which is useful when you want to keep different branches for\n+different audiences you are working to like when you have an open source\n+and commercial versions of a software, for example.\n++\n+If you want to start a disconnected history that records set of paths\n+totally different from the original branch, you may want to first clear\n+the index and the working tree, by running \"git rm -rf .\" from the\n+top-level of the working tree, before preparing your files (by copying\n+from elsewhere, extracting a tarball, etc.) in the working tree.\n+\n -m::\n --merge::\n \tWhen switching branches,\ndiff --git a/builtin/checkout.c b/builtin/checkout.c\nindex acefaaf..37d8278 100644\n--- a/builtin/checkout.c\n+++ b/builtin/checkout.c\n@@ -33,6 +33,7 @@ struct checkout_opts {\n \tint writeout_error;\n \n \tconst char *new_branch;\n+\tconst char *new_orphan_branch;\n \tint new_branch_log;\n \tenum branch_track track;\n };\n@@ -491,8 +492,9 @@ static void update_refs_for_switch(struct checkout_opts *opts,\n \tstruct strbuf msg = STRBUF_INIT;\n \tconst char *old_desc;\n \tif (opts->new_branch) {\n-\t\tcreate_branch(old->name, opts->new_branch, new->name, 0,\n-\t\t\t      opts->new_branch_log, opts->track);\n+\t\tif (!opts->new_orphan_branch)\n+\t\t\tcreate_branch(old->name, opts->new_branch, new->name, 0,\n+\t\t\t\t      opts->new_branch_log, opts->track);\n \t\tnew->name = opts->new_branch;\n \t\tsetup_branch_path(new);\n \t}\n@@ -632,6 +634,7 @@ int cmd_checkout(int argc, const char **argv, const char *prefix)\n \t\tOPT_BOOLEAN('l', NULL, &opts.new_branch_log, \"log for new branch\"),\n \t\tOPT_SET_INT('t', \"track\",  &opts.track, \"track\",\n \t\t\tBRANCH_TRACK_EXPLICIT),\n+\t\tOPT_STRING(0, \"orphan\", &opts.new_orphan_branch, \"new branch\", \"new unparented branch\"),\n \t\tOPT_SET_INT('2', \"ours\", &opts.writeout_stage, \"stage\",\n \t\t\t    2),\n \t\tOPT_SET_INT('3', \"theirs\", &opts.writeout_stage, \"stage\",\n@@ -677,6 +680,14 @@ int cmd_checkout(int argc, const char **argv, const char *prefix)\n \t\topts.new_branch = argv0 + 1;\n \t}\n \n+\tif (opts.new_orphan_branch) {\n+\t\tif (opts.new_branch)\n+\t\t\tdie(\"--orphan and -b are mutually exclusive\");\n+\t\tif (opts.track > 0 || opts.new_branch_log)\n+\t\t\tdie(\"--orphan should not be used with -t or -l\");\n+\t\topts.new_branch = opts.new_orphan_branch;\n+\t}\n+\n \tif (conflict_style) {\n \t\topts.merge = 1; /* implied */\n \t\tgit_xmerge_config(\"merge.conflictstyle\", conflict_style, NULL);\ndiff --git a/t/t2017-checkout-orphan.sh b/t/t2017-checkout-orphan.sh\nnew file mode 100755\nindex 0000000..a8297c6\n--- /dev/null\n+++ b/t/t2017-checkout-orphan.sh\n@@ -0,0 +1,90 @@\n+#!/bin/sh\n+#\n+# Copyright (c) 2010 Erick Mattos\n+#\n+\n+test_description='git checkout --orphan\n+\n+Main Tests for --orphan functionality.'\n+\n+. ./test-lib.sh\n+\n+TEST_FILE=foo\n+\n+test_expect_success 'Setup' '\n+\techo \"Initial\" >\"$TEST_FILE\" &&\n+\tgit add \"$TEST_FILE\" &&\n+\tgit commit -m \"First Commit\"\n+\ttest_tick &&\n+\techo \"State 1\" >>\"$TEST_FILE\" &&\n+\tgit add \"$TEST_FILE\" &&\n+\ttest_tick &&\n+\tgit commit -m \"Second Commit\"\n+'\n+\n+test_expect_success '--orphan creates a new orphan branch from HEAD' '\n+\tgit checkout --orphan alpha &&\n+\ttest_must_fail git rev-parse --verify HEAD &&\n+\ttest \"refs/heads/alpha\" = \"$(git symbolic-ref HEAD)\" &&\n+\ttest_tick &&\n+\tgit commit -m \"Third Commit\" &&\n+\ttest_must_fail git rev-parse --verify HEAD^ &&\n+\tgit diff-tree --quiet master alpha\n+'\n+\n+test_expect_success '--orphan creates a new orphan branch from <start_point>' '\n+\tgit checkout master &&\n+\tgit checkout --orphan beta master^ &&\n+\ttest_must_fail git rev-parse --verify HEAD &&\n+\ttest \"refs/heads/beta\" = \"$(git symbolic-ref HEAD)\" &&\n+\ttest_tick &&\n+\tgit commit -m \"Fourth Commit\" &&\n+\ttest_must_fail git rev-parse --verify HEAD^ &&\n+\tgit diff-tree --quiet master^ beta\n+'\n+\n+test_expect_success '--orphan must be rejected with -b' '\n+\tgit checkout master &&\n+\ttest_must_fail git checkout --orphan new -b newer &&\n+\ttest refs/heads/master = \"$(git symbolic-ref HEAD)\"\n+'\n+\n+test_expect_success '--orphan is rejected with an existing name' '\n+\tgit checkout master &&\n+\ttest_must_fail git checkout --orphan master &&\n+\ttest refs/heads/master = \"$(git symbolic-ref HEAD)\"\n+'\n+\n+test_expect_success '--orphan refuses to switch if a merge is needed' '\n+\tgit checkout master &&\n+\tgit reset --hard &&\n+\techo local >>\"$TEST_FILE\" &&\n+\tcat \"$TEST_FILE\" >\"$TEST_FILE.saved\" &&\n+\ttest_must_fail git checkout --orphan gamma master^ &&\n+\ttest refs/heads/master = \"$(git symbolic-ref HEAD)\" &&\n+\ttest_cmp \"$TEST_FILE\" \"$TEST_FILE.saved\" &&\n+\tgit diff-index --quiet --cached HEAD &&\n+\tgit reset --hard\n+'\n+\n+test_expect_success '--orphan does not mix well with -t' '\n+\tgit checkout master &&\n+\ttest_must_fail git checkout -t master --orphan gamma &&\n+\ttest refs/heads/master = \"$(git symbolic-ref HEAD)\"\n+'\n+\n+test_expect_success '--orphan ignores branch.autosetupmerge' '\n+\tgit checkout -f master &&\n+\tgit config branch.autosetupmerge always &&\n+\tgit checkout --orphan delta &&\n+\ttest -z \"$(git config branch.delta.merge)\" &&\n+\ttest refs/heads/delta = \"$(git symbolic-ref HEAD)\" &&\n+\ttest_must_fail git rev-parse --verify HEAD^\n+'\n+\n+test_expect_success '--orphan does not mix well with -l' '\n+\tgit checkout -f master &&\n+\ttest_must_fail git checkout -l --orphan gamma\n+'\n+\n+test_done\n-- \n1.7.0.2.324.g7eb48.dirty\n"},{"id":"137456","messageId":"20100321171431.GE2557@m62s10.vlinux.de","threadId":"23122","inReplyTo":"1269185678-3039-1-git-send-email-erick.mattos@gmail.com","subject":"Re: [PATCH v3] git checkout: create unparented branch by --orphan","fromName":"Peter Baumann","fromEmail":"waste.manager@gmx.de","sentAt":"2010-03-21T17:14:31Z","receivedAt":"2010-03-21T17:14:31Z","isPatch":true,"sender":{"key":"waste.manager@gmx.de","avatar":null},"body":"On Sun, Mar 21, 2010 at 12:34:38PM -0300, Erick Mattos wrote:\n> Similar to -b, --orphan creates a new branch, but it starts without any\n> commit.  After running \"git checkout --orphan newbranch\", you are on a\n> new branch \"newbranch\", and the first commit you create from this state\n> will start a new history without any ancestry.\n> \n> \"git checkout --orphan\" keeps the index and the working tree files\n> intact in order to make it convenient for creating a new history whose\n> trees resemble the ones from the original branch.\n> \n\nSorry to skim in so late but --orphan sounds - at least to me as a non native\nspeaker - a little strange. Yes, I know it means \"without parents\", but\nactually it would be the *last* thing I would search for after opening the\nmanpage.\n\nWouldn't --empty-parent or --no-parent describe the situation better?\nIt actually has the benefit that it would match on a search for /parent/,\nwhich I would have searched for if I want to create a new empty branch.\n\n--\nPeter\n"},{"id":"137465","messageId":"55bacdd31003211055r348f37b0sb4ff02c38c64722b@mail.gmail.com","threadId":"23122","inReplyTo":"20100321171431.GE2557@m62s10.vlinux.de","subject":"Re: [PATCH v3] git checkout: create unparented branch by --orphan","fromName":"Erick Mattos","fromEmail":"erick.mattos@gmail.com","sentAt":"2010-03-21T17:55:03Z","receivedAt":"2010-03-21T17:55:03Z","isPatch":true,"sender":{"key":"erick.mattos@gmail.com","avatar":"https://avatars.githubusercontent.com/u/134001?v=4"},"body":"Hi,\n\n2010/3/21 Peter Baumann <waste.manager@gmx.de>:\n> Sorry to skim in so late but --orphan sounds - at least to me as a non native\n> speaker - a little strange. Yes, I know it means \"without parents\", but\n> actually it would be the *last* thing I would search for after opening the\n> manpage.\n\nIt is never late to contribute, even for skimming.  Free software are\norganic and living things people can mold it whenever they want.\n\nWe are both non native English speakers but for me orphan is the real\nobvious for no parents.  And that is the name of the command you type:\nshorter and not similar to other ones is the best.\n\nI don't care about names as long as its bearer does what it is\nsupposed to do.  But in this particular case I think it fits the job.\n\n> Wouldn't --empty-parent or --no-parent describe the situation better?\n> It actually has the benefit that it would match on a search for /parent/,\n> which I would have searched for if I want to create a new empty branch.\n\n--empty-parent try to give the \"plumbing\" idea but it is not really\n'empty' but 'non-existant' and also it is not good to make\n\"porcelainners\" (inventing this term) see it as an unparented though.\n\n--no-parent is just added characters and make it feel as if it exists\na --parent too.\n\nYou WILL match on a search for /parent/ already.\n\n> --\n> Peter\n>\n\nThanks for you contributing ideas.\n\nAlthough I don't agree with you on this subject, I am very happy you\nparticipated your ideas to me.  It is good to get some attention :-)\n\nIn this particular case I see Junio as a native English speaker better\nfitted to comment.\n\nBest regards\n"},{"id":"137471","messageId":"7vd3yxqxdj.fsf@alter.siamese.dyndns.org","threadId":"23122","inReplyTo":"20100321171431.GE2557@m62s10.vlinux.de","subject":"Re: [PATCH v3] git checkout: create unparented branch by --orphan","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-03-21T19:37:44Z","receivedAt":"2010-03-21T19:37:44Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Peter Baumann <waste.manager@gmx.de> writes:\n\n> Sorry to skim in so late but --orphan sounds - at least to me as a non native\n> speaker - a little strange. Yes, I know it means \"without parents\", but\n> actually it would be the *last* thing I would search for after opening the\n> manpage.\n\nI'm not native either, and \"orphan\" sounded strange in that we've never\nused that word in any of our use case or workflow description in our\ndocuments.\n\nGitTips page of git wiki mentions this under \"a new branch that has no\nancestor\", and speaks of a way to add \"a new and empty branch\".  Scott\nChacon also creates \"new empty branches\" in the community book.\n\nBut if one compares them with what we discussed in the messages in the\nthreads on earlier iterations of this patch, one would realize that\nneither of these pages is backed by enough thought/discussion on the\nreason why the end user might want to do this in the first place; they\nchoose the word \"empty\" without even realizing that it describes only one\nmode of operation (aka \"no common paths\" in our discussion) that a\ndisconnected history might be wanted by users.\n\nThe main point of the feature is not the emptyness of the resulting tree\n(it is merely one possible outcome), but is the lack of parents in the\nresulting commit.  So I would recommend against --empty.  --root might be\na good synonym, though, and we _do_ already use that word for that purpose\nin some commands (e.g. \"log --root\").\n"},{"id":"137480","messageId":"55bacdd31003211415k79b7a039n3f19eb95eefcad43@mail.gmail.com","threadId":"23122","inReplyTo":"7vd3yxqxdj.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH v3] git checkout: create unparented branch by --orphan","fromName":"Erick Mattos","fromEmail":"erick.mattos@gmail.com","sentAt":"2010-03-21T21:15:12Z","receivedAt":"2010-03-21T21:15:12Z","isPatch":true,"sender":{"key":"erick.mattos@gmail.com","avatar":"https://avatars.githubusercontent.com/u/134001?v=4"},"body":"Hi,\n\n2010/3/21 Junio C Hamano <gitster@pobox.com>:\n> I'm not native either, and \"orphan\" sounded strange in that we've never\n> used that word in any of our use case or workflow description in our\n> documents.\n\nI didn't know.  I thought you were American.\n\n> The main point of the feature is not the emptyness of the resulting tree\n> (it is merely one possible outcome), but is the lack of parents in the\n> resulting commit.  So I would recommend against --empty.  --root might be\n> a good synonym, though, and we _do_ already use that word for that purpose\n> in some commands (e.g. \"log --root\").\n\n--root could be a synonym but the reason I haven't chosen it was the\nfact that it could mislead people to think the functionality will do\nsomething with/based on the first commit of the actual branch,\nsubjectively thinking \"THE ROOT\".\n\nIMHO --orphan (no parents) is more obvious.\n\nWe should argue one of our native English speaker amidst this\ndeveloper community to be sure.\n\nAnyway that is just a word to change or not in the patch... :-)\n\nRegards\n"},{"id":"137484","messageId":"7vk4t5icdj.fsf@alter.siamese.dyndns.org","threadId":"23122","inReplyTo":"7vd3yxqxdj.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH v3] git checkout: create unparented branch by --orphan","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-03-21T21:38:32Z","receivedAt":"2010-03-21T21:38:32Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano <gitster@pobox.com> writes:\n\n> GitTips page of git wiki mentions this under \"a new branch that has no\n> ancestor\", and speaks of a way to add \"a new and empty branch\".  Scott\n> Chacon also creates \"new empty branches\" in the community book.\n\nBy the way, I would actually suggest updating these web pages not to make\nit sound as if it is a good thing to create a new \"empty\" history (aka \"no\ncommon paths\") in an existing repository.  Git wiki lists \"create in a\nseparate repository and push into the same\" as \"The easy way\", as if it is\neasy-but-amateurish, making it sound as if experts should use different\nways for extra coolness point.  People may think that having branches like\n'man' and 'html' in the same repository as I do is somehow cool, but it is\na total misconception.  That part of Git wiki page should be reworded to\nreduce user confusion; \"The easy way\" is actually \"the one true way\".\n\nWhile it indeed is useful to have them in the same public repository\n(think of my git.git repository at k.org) for distribution purposes, it\ndoes not mean that it is a good thing to create and manipulate these\nunrelated histories in the same repository at all.  These two branches\n(and the same thing can be said for 'todo' branch) are never checked out\nin a repository with an worktree that normally checks out the primary\nbranches (e.g. 'master', 'next', etc.) nowhere in my workflow for two very\nsimple reasons:\n\n (1) doing so would disrupt the normal work done in the primary branches.\n\n (2) updating them requires a separate checkout of the primary branch\n     anyway.\n\nGrowing these histories are done in separate repositories unrelated to the\nprimary project worktree; they are pushed into the same public repository\nonly for ease of cloning, for Documentation/install-doc-quick.sh script to\nrun a moral equivalent of \"tar-tree | (cd elsewhere && tar xf -)\".\n\nAnd even the \"ease-of-cloning\" is merely a justfication after the fact.\nThe original and the only reason why these pregenerated documentation\nbranches are in the same distribution repository is because I only have\nwrite privilege to /pub/scm/git/git.git/ at k.org, and not to the whole\n/pub/scm/git/ hierarchy.  Otherwise I may have published these unrelated\nbranches in their own repositories (e.g. /pub/scm/git/docs.git/) and made\ninstall-doc-quick.sh use data from there; it might have avoided confusing\nend users, perhaps.\n\nIt also might be useful to extend these pages with the \"going open source?\nhere is how to use a 'mostly same paths' disconnected history to do so\"\nexample from the discussion.  That workflow I can see how it may make\nsense to use \"checkout --orphan\" to create the new history in the same\nrepository.\n"},{"id":"137530","messageId":"4BA73057.1020602@drmicha.warpmail.net","threadId":"23122","inReplyTo":"55bacdd31003211415k79b7a039n3f19eb95eefcad43@mail.gmail.com","subject":"Re: [PATCH v3] git checkout: create unparented branch by --orphan","fromName":"Michael J Gruber","fromEmail":"git@drmicha.warpmail.net","sentAt":"2010-03-22T08:54:47Z","receivedAt":"2010-03-22T08:54:47Z","isPatch":true,"sender":{"key":"git@grubix.eu","avatar":"https://avatars.githubusercontent.com/u/233215?v=4"},"body":"Erick Mattos venit, vidit, dixit 21.03.2010 22:15:\n> Hi,\n> \n> 2010/3/21 Junio C Hamano <gitster@pobox.com>:\n>> I'm not native either, and \"orphan\" sounded strange in that we've never\n>> used that word in any of our use case or workflow description in our\n>> documents.\n> \n> I didn't know.  I thought you were American.\n> \n>> The main point of the feature is not the emptyness of the resulting tree\n>> (it is merely one possible outcome), but is the lack of parents in the\n>> resulting commit.  So I would recommend against --empty.  --root might be\n>> a good synonym, though, and we _do_ already use that word for that purpose\n>> in some commands (e.g. \"log --root\").\n> \n> --root could be a synonym but the reason I haven't chosen it was the\n> fact that it could mislead people to think the functionality will do\n> something with/based on the first commit of the actual branch,\n> subjectively thinking \"THE ROOT\".\n> \n> IMHO --orphan (no parents) is more obvious.\n> \n> We should argue one of our native English speaker amidst this\n> developer community to be sure.\n\n[Disclosure: non-native speaker but having lived with natives ;)]\n\nI'd favour \"root\" for several reasons:\n\n- \"root\" is the correct technical term in graph theory\n- \"root\" is used the same way in other (Git) places\n- \"orphan\" is someone who used to have parents, so with \"orphan\" I would\nrather associate the process of removing parents from the picture\n(removing parentship information from an existing commit)\n\nJust my two Euro-cents :)\nMichael\n"},{"id":"137545","messageId":"3F619EAA-288D-4310-B9C6-8121FE00E7B0@pobox.com","threadId":"23122","inReplyTo":"1269185678-3039-1-git-send-email-erick.mattos@gmail.com","subject":"Re: [PATCH v3] git checkout: create unparented branch by --orphan","fromName":"Chris Johnsen","fromEmail":"chris_johnsen@pobox.com","sentAt":"2010-03-22T12:43:44Z","receivedAt":"2010-03-22T12:43:44Z","isPatch":true,"sender":{"key":"chris_johnsen@pobox.com","avatar":"https://avatars.githubusercontent.com/u/107071?v=4"},"body":"On 2010 Mar 21, at 10:34, Erick Mattos wrote:\n> Similar to -b, --orphan creates a new branch, but it starts without  \n> any\n> commit.  After running \"git checkout --orphan newbranch\", you are on a\n> new branch \"newbranch\", and the first commit you create from this  \n> state\n> will start a new history without any ancestry.\n>\n> \"git checkout --orphan\" keeps the index and the working tree files\n> intact in order to make it convenient for creating a new history whose\n> trees resemble the ones from the original branch.\n>\n> When creating a branch whose trees have no resemblance to the ones  \n> from\n> the original branch, it may be easier to start work on the new  \n> branch by\n> untracking and removing all working tree files that came from the\n> original branch, by running a 'git rm -rf .' immediately after running\n\nMaybe use double quotes in the above command to be consistent with  \nthe rest of inline commands in the commit message.\n\n> \"checkout --orphan\".\n>\n> Signed-off-by: Erick Mattos <erick.mattos@gmail.com>\n> ---\n\n> diff --git a/Documentation/git-checkout.txt b/Documentation/git- \n> checkout.txt\n> index 37c1810..5a50997 100644\n> --- a/Documentation/git-checkout.txt\n> +++ b/Documentation/git-checkout.txt\n\n> @@ -90,6 +90,25 @@ explicitly give a name with '-b' in such a case.\n>  \tCreate the new branch's reflog; see linkgit:git-branch[1] for\n>  \tdetails.\n>\n> +--orphan::\n> +\tCreate a new branch named <new_branch>, unparented to any other\n> +\tbranch.  The new branch you switch to does not have any commit\n> +\tand after the first one it will become the root of a new history\n> +\tcompletely unconnected from all the other branches.\n> ++\n> +When you use \"--orphan\", a new unparented branch is created having  \n> the\n> +index and the working tree intact.  This allows you to start a new\n> +history that records set of paths similar to that of the start-point\n> +commit, which is useful when you want to keep different branches for\n> +different audiences you are working to like when you have an open  \n> source\n> +and commercial versions of a software, for example.\n> ++\n> +If you want to start a disconnected history that records set of paths\n> +totally different from the original branch, you may want to first  \n> clear\n> +the index and the working tree, by running \"git rm -rf .\" from the\n> +top-level of the working tree, before preparing your files (by  \n> copying\n> +from elsewhere, extracting a tarball, etc.) in the working tree.\n> +\n>  -m::\n>  --merge::\n>  \tWhen switching branches,\n\n(American) English is my first language, but that does not imply that  \nI speak, read, or write perfectly.\n\n\"unparented\" sounds a bit awkward to me.\n\n\"unconnected from all\": the usual constructions are \"unconnected to\",  \n\"connected to\" or \"disconnected from\"; might be better as  \n\"disconnected from all\" or \"not connected to any\"\n\n\"unparented\" sounds odd to me, especially \"unparented to\". For  \n\"unparented branch\", I would use \"branch without parents\", maybe  \n\"history-free branch\".\n\nI think the repeated uses of \"unparented\" in the first and second  \nparagraphs, and its description can be coalesced into the the first  \nparagraph, leaving the later paragraphs to describe the \"common  \npaths\" and \"no common paths\" cases.\n\nThe second sentence of the second paragraph seems overly long and  \ngets a bit muddled near the end. I can not parse \"audiences you are  \nworking to\". Maybe it should be \"audiences you are working with\" or  \n\"... for\"?\n\nIn the third paragraph, \"first clear the index and the working tree\"  \nbit could be taken to mean \"clear the index and working tree before  \ncreating the new branch\" (which might work, but leaves a possibly  \nconfusing state if the user is distracted between \"rm -rf\" and  \n\"checkout --orphan\" (still on the original branch, the deletion of  \neverything has been staged)). Also, use backquotes to properly format  \nthe example command.\n\nHere is my take on these paragraphs:\n\n-->8---->8--\n--orphan::\n\tCreate a new, 'orphan' branch named <new_branch>, and start it\n\tat <start_point>. The first commit made on this new branch will\n\thave no parents (it will be the root of a new history that is\n\tnot connected to any the other branches or commits).\n+\nAn orphan branch allows you to start a new history that records a set of\npaths similar to <start_point>.\nThis can be useful when you want to publish the tree from a commit  \nwithout\nexposing its full history.\nYou might want to do this to publish an open source branch of a project\nwhose current tree is \"clean\", but whose full history contains  \nproprietary\nor otherwise encumbered bits of code.\n+\nIf you want to start a disconnected history that records a set of paths\nthat is totally different from <start_point>, you may want to clear the\nindex and the working tree after creating the orphan branch.\nRun `git rm -rf .` from the top level of the working tree, then prepare\nyour new files by copying them from elsewhere, extracting a tarball, or\notherwise populating the working tree.\n--8<----8<--\n\n-- \nChris\n"},{"id":"137546","messageId":"953BEDE2-1A17-49EA-BEC5-D198DBB1FF23@pobox.com","threadId":"23122","inReplyTo":"55bacdd31003211415k79b7a039n3f19eb95eefcad43@mail.gmail.com","subject":"Re: [PATCH v3] git checkout: create unparented branch by --orphan","fromName":"Chris Johnsen","fromEmail":"chris_johnsen@pobox.com","sentAt":"2010-03-22T12:46:34Z","receivedAt":"2010-03-22T12:46:34Z","isPatch":true,"sender":{"key":"chris_johnsen@pobox.com","avatar":"https://avatars.githubusercontent.com/u/107071?v=4"},"body":"2010/3/21 Junio C Hamano <gitster@pobox.com>:\n> The main point of the feature is not the emptyness of the resulting  \n> tree\n> (it is merely one possible outcome), but is the lack of parents in the\n> resulting commit.  So I would recommend against --empty.  --root  \n> might be\n> a good synonym, though, and we _do_ already use that word for that  \n> purpose\n> in some commands (e.g. \"log --root\").\n\nOn 2010 Mar 21, at 16:15, Erick Mattos wrote:\n> --root could be a synonym but the reason I haven't chosen it was the\n> fact that it could mislead people to think the functionality will do\n> something with/based on the first commit of the actual branch,\n> subjectively thinking \"THE ROOT\".\n\nThe existing uses of --root are close to, but not identical to this  \nproposed usage. The existing uses all relate to handling the already  \ncreated root commit(s) of a commit/branch/repository. This proposed  \nusage relates to the yet to be created first commit on the new  \nbranch. It is possible to use the \"already created\" interpretation in  \nthis context (create a new branch based on the root commits of the  \nspecified commits), but it really does not make much sense. Still,  \nqualifying \"root\" might help prevent some confusion:\n\n     --new-root\n     --fresh-root\n     --root-branch?\n\n     --new-history\n     --fresh-history\n     --fresh-branch\n\nLogically, both --orphan and --root are descriptions of the commit  \nthat will _eventually_ be stored under the branch, but not  \ndescriptions of the transient state of the branch itself. This state  \nis described in a few error/warning messages as \"not yet born\" or  \n\"unborn\" (checkout, pull, fsck). It seems to be an unofficial term  \nthough (or maybe just unimportant) since it is not otherwise  \ndocumented (it is not in the glossary, but it does appear in the  \nrelease notes a few times). So with some weight of existing  \nterminology behind it:\n\n     --unborn\n\n--no-parent was mentioned elsewhere in the thread, but it suffers  \nfrom looking like a negation of a potential --parent option. Though  \nmuch longer, --without- does not suffer this same problem.\n\n     --without-parents\n     --without-history\n     --ahistorically    (probably the non-standard prefix is too  \n\"native\")\n\n     --ex-nihilo        (just kidding?)\n\n-- \nChris\n"},{"id":"137551","messageId":"55bacdd31003220714qa9fb915k9fe152019b4d88b4@mail.gmail.com","threadId":"23122","inReplyTo":"3F619EAA-288D-4310-B9C6-8121FE00E7B0@pobox.com","subject":"Re: [PATCH v3] git checkout: create unparented branch by --orphan","fromName":"Erick Mattos","fromEmail":"erick.mattos@gmail.com","sentAt":"2010-03-22T14:14:03Z","receivedAt":"2010-03-22T14:14:03Z","isPatch":true,"sender":{"key":"erick.mattos@gmail.com","avatar":"https://avatars.githubusercontent.com/u/134001?v=4"},"body":"Hi,\n\n2010/3/22 Chris Johnsen <chris_johnsen@pobox.com>:\n> On 2010 Mar 21, at 10:34, Erick Mattos wrote:\n>>\n>> Similar to -b, --orphan creates a new branch, but it starts without any\n>> commit.  After running \"git checkout --orphan newbranch\", you are on a\n>> new branch \"newbranch\", and the first commit you create from this state\n>> will start a new history without any ancestry.\n>>\n>> \"git checkout --orphan\" keeps the index and the working tree files\n>> intact in order to make it convenient for creating a new history whose\n>> trees resemble the ones from the original branch.\n>>\n>> When creating a branch whose trees have no resemblance to the ones from\n>> the original branch, it may be easier to start work on the new branch by\n>> untracking and removing all working tree files that came from the\n>> original branch, by running a 'git rm -rf .' immediately after running\n>\n> Maybe use double quotes in the above command to be consistent with the rest\n> of inline commands in the commit message.\n>\n>> \"checkout --orphan\".\n>>\n>> Signed-off-by: Erick Mattos <erick.mattos@gmail.com>\n>> ---\n>\n>> diff --git a/Documentation/git-checkout.txt\n>> b/Documentation/git-checkout.txt\n>> index 37c1810..5a50997 100644\n>> --- a/Documentation/git-checkout.txt\n>> +++ b/Documentation/git-checkout.txt\n>\n>> @@ -90,6 +90,25 @@ explicitly give a name with '-b' in such a case.\n>>        Create the new branch's reflog; see linkgit:git-branch[1] for\n>>        details.\n>>\n>> +--orphan::\n>> +       Create a new branch named <new_branch>, unparented to any other\n>> +       branch.  The new branch you switch to does not have any commit\n>> +       and after the first one it will become the root of a new history\n>> +       completely unconnected from all the other branches.\n>> ++\n>> +When you use \"--orphan\", a new unparented branch is created having the\n>> +index and the working tree intact.  This allows you to start a new\n>> +history that records set of paths similar to that of the start-point\n>> +commit, which is useful when you want to keep different branches for\n>> +different audiences you are working to like when you have an open source\n>> +and commercial versions of a software, for example.\n>> ++\n>> +If you want to start a disconnected history that records set of paths\n>> +totally different from the original branch, you may want to first clear\n>> +the index and the working tree, by running \"git rm -rf .\" from the\n>> +top-level of the working tree, before preparing your files (by copying\n>> +from elsewhere, extracting a tarball, etc.) in the working tree.\n>> +\n>>  -m::\n>>  --merge::\n>>        When switching branches,\n>\n> (American) English is my first language, but that does not imply that I\n> speak, read, or write perfectly.\n>\n> \"unparented\" sounds a bit awkward to me.\n>\n> \"unconnected from all\": the usual constructions are \"unconnected to\",\n> \"connected to\" or \"disconnected from\"; might be better as \"disconnected from\n> all\" or \"not connected to any\"\n>\n> \"unparented\" sounds odd to me, especially \"unparented to\". For \"unparented\n> branch\", I would use \"branch without parents\", maybe \"history-free branch\".\n>\n> I think the repeated uses of \"unparented\" in the first and second\n> paragraphs, and its description can be coalesced into the the first\n> paragraph, leaving the later paragraphs to describe the \"common paths\" and\n> \"no common paths\" cases.\n>\n> The second sentence of the second paragraph seems overly long and gets a bit\n> muddled near the end. I can not parse \"audiences you are working to\". Maybe\n> it should be \"audiences you are working with\" or \"... for\"?\n>\n> In the third paragraph, \"first clear the index and the working tree\" bit\n> could be taken to mean \"clear the index and working tree before creating the\n> new branch\" (which might work, but leaves a possibly confusing state if the\n> user is distracted between \"rm -rf\" and \"checkout --orphan\" (still on the\n> original branch, the deletion of everything has been staged)). Also, use\n> backquotes to properly format the example command.\n>\n> Here is my take on these paragraphs:\n>\n> -->8---->8--\n> --orphan::\n>        Create a new, 'orphan' branch named <new_branch>, and start it\n>        at <start_point>. The first commit made on this new branch will\n>        have no parents (it will be the root of a new history that is\n>        not connected to any the other branches or commits).\n> +\n> An orphan branch allows you to start a new history that records a set of\n> paths similar to <start_point>.\n> This can be useful when you want to publish the tree from a commit without\n> exposing its full history.\n> You might want to do this to publish an open source branch of a project\n> whose current tree is \"clean\", but whose full history contains proprietary\n> or otherwise encumbered bits of code.\n> +\n> If you want to start a disconnected history that records a set of paths\n> that is totally different from <start_point>, you may want to clear the\n> index and the working tree after creating the orphan branch.\n> Run `git rm -rf .` from the top level of the working tree, then prepare\n> your new files by copying them from elsewhere, extracting a tarball, or\n> otherwise populating the working tree.\n> --8<----8<--\n>\n> --\n> Chris\n>\n\nI am in favor of changing the whole texts to your versions.  Let's\nwait for Junio's opinion.\n\nAfter this wonderful English and modesty lessons, I started thinking:\nsince Git is a worldwide spread software why it is not using gettext\nto have its translations?  It would not be a hard job because gettext\nseparates the job of translation from normal work flow with just minor\nchanges to inline message constants.\n\nBest regards to all\n"},{"id":"137553","messageId":"55bacdd31003220736u72ea6453pd59d8fa82a3ed12@mail.gmail.com","threadId":"23122","inReplyTo":"953BEDE2-1A17-49EA-BEC5-D198DBB1FF23@pobox.com","subject":"Re: [PATCH v3] git checkout: create unparented branch by --orphan","fromName":"Erick Mattos","fromEmail":"erick.mattos@gmail.com","sentAt":"2010-03-22T14:36:08Z","receivedAt":"2010-03-22T14:36:08Z","isPatch":true,"sender":{"key":"erick.mattos@gmail.com","avatar":"https://avatars.githubusercontent.com/u/134001?v=4"},"body":"Hi again,\n\n2010/3/22 Chris Johnsen <chris_johnsen@pobox.com>:\n> The existing uses of --root are close to, but not identical to this proposed\n> usage. The existing uses all relate to handling the already created root\n> commit(s) of a commit/branch/repository. This proposed usage relates to the\n> yet to be created first commit on the new branch. It is possible to use the\n> \"already created\" interpretation in this context (create a new branch based\n> on the root commits of the specified commits), but it really does not make\n> much sense. Still, qualifying \"root\" might help prevent some confusion:\n>\n>    --new-root\n>    --fresh-root\n>    --root-branch?\n>\n>    --new-history\n>    --fresh-history\n>    --fresh-branch\n>\n> Logically, both --orphan and --root are descriptions of the commit that will\n> _eventually_ be stored under the branch, but not descriptions of the\n> transient state of the branch itself. This state is described in a few\n> error/warning messages as \"not yet born\" or \"unborn\" (checkout, pull, fsck).\n> It seems to be an unofficial term though (or maybe just unimportant) since\n> it is not otherwise documented (it is not in the glossary, but it does\n> appear in the release notes a few times). So with some weight of existing\n> terminology behind it:\n>\n>    --unborn\n>\n> --no-parent was mentioned elsewhere in the thread, but it suffers from\n> looking like a negation of a potential --parent option. Though much longer,\n> --without- does not suffer this same problem.\n>\n>    --without-parents\n>    --without-history\n>    --ahistorically    (probably the non-standard prefix is too \"native\")\n>\n>    --ex-nihilo        (just kidding?)\n>\n> --\n> Chris\n>\n\n2010/3/22 Michael J Gruber <git@drmicha.warpmail.net>:\n> [Disclosure: non-native speaker but having lived with natives ;)]\n>\n> I'd favour \"root\" for several reasons:\n>\n> - \"root\" is the correct technical term in graph theory\n> - \"root\" is used the same way in other (Git) places\n> - \"orphan\" is someone who used to have parents, so with \"orphan\" I would\n> rather associate the process of removing parents from the picture\n> (removing parentship information from an existing commit)\n>\n> Just my two Euro-cents :)\n> Michael\n\nI really don't care about names as long as I will be able to create\nthe 'orphan' branches.\n\nWhatever you people decide is good to me.\n\nRegards\n"},{"id":"137560","messageId":"m3d3ywjq8p.fsf_-_@localhost.localdomain","threadId":"23122","inReplyTo":"55bacdd31003220714qa9fb915k9fe152019b4d88b4@mail.gmail.com","subject":"Translating error messages in Git (was: Re: [PATCH v3] git checkout: create unparented branch by --orphan)","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2010-03-22T16:06:41Z","receivedAt":"2010-03-22T16:06:41Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"Erick Mattos <erick.mattos@gmail.com> writes:\n\n> After this wonderful English and modesty lessons, I started thinking:\n> since Git is a worldwide spread software why it is not using gettext\n> to have its translations?  It would not be a hard job because gettext\n> separates the job of translation from normal work flow with just minor\n> changes to inline message constants.\n\nGit uses gettext, but only for gitk and git-gui.\n\nThe problem is that git is written in C (which can use gettext), Perl\n(which can use Locale::Maketext / Locale::Maketext::Gettext), but has\nalso some commands that are written in (POSIX) shell script.  The\n$\"...\" syntax for message localization is bash-ism, and additionally\nit is deprecated\n\n-- \nJakub Narebski\nPoland\nShadeHawk on #git\n"},{"id":"137582","messageId":"7vljdk85z4.fsf@alter.siamese.dyndns.org","threadId":"23122","inReplyTo":"3F619EAA-288D-4310-B9C6-8121FE00E7B0@pobox.com","subject":"Re: [PATCH v3] git checkout: create unparented branch by --orphan","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-03-22T20:19:11Z","receivedAt":"2010-03-22T20:19:11Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Chris Johnsen <chris_johnsen@pobox.com> writes:\n\n> --orphan::\n> \tCreate a new, 'orphan' branch named <new_branch>, and start it\n> \tat <start_point>. The first commit made on this new branch will\n> \thave no parents (it will be the root of a new history that is\n> \tnot connected to any the other branches or commits).\n> +\n> An orphan branch allows you to start a new history that records a set of\n> paths similar to <start_point>.\n\nStrictly speaking, an orphan branch allows you to start a new history that\ndoes not have any existing commit as its ancestry, and that is all there\nto it.  While the \"mostly common paths\" aspect is worth mentioning, as it\nis the use case it primarily targets, it is still secondary to the\ndescription of \"what it does.\"  \"What it is used for\" should come after\nthe reader is told \"what it does.\"\n\nIt would probably be better to say that the index and the working tree is\nkept intact during --orphan process as part of \"what it does\", before\ntalking about \"mostly common paths\":\n\n\tCreate a new branch <new_branch> and switch to it.  The first\n\tcommit you will make on this branch will become the root of a new\n\thistory, disconnected from any of existing commits.  \n\n\tThe index and the working tree is adjusted as if you ran \"git\n\tcheckout <start_point>\" (without -b nor paths), to allow you to\n\teasily record the root commit of the new history that records a\n\tset of paths similar to <start_point>.\n\n> This can be useful when you want to publish the tree from a commit\n> without\n> exposing its full history.\n> You might want to do this to publish an open source branch of a project\n> whose current tree is \"clean\", but whose full history contains\n> proprietary\n> or otherwise encumbered bits of code.\n\nGood.\n\n> +\n> If you want to start a disconnected history that records a set of paths\n> that is totally different from <start_point>, you may want to clear the\n> index and the working tree after creating the orphan branch.\n> Run `git rm -rf .` from the top level of the working tree, then prepare\n> your new files by copying them from elsewhere, extracting a tarball, or\n> otherwise populating the working tree.\n\nGood, even though I am tempted to suggest rephrasing it further:\n\n        If you want to start a disconnected history that records a set of\n        paths that is totally different from <start_point>, you could\n        clear the index and the working tree after creating the orphan\n        branch by running `git rm -rf .` from the top level of the working\n        tree.  Then prepare your new files by copying them from elsewhere,\n        extracting a tarball, or otherwise populating the working tree.\n\tIn general, however, it is cleaner and easier to create such an\n        unrelated history in a separate repository than creating in the\n        same repository.\n"}]}