{"thread":{"id":"18817","subject":"[PATCH] builtin-branch - allow deleting a fully specified branch-name","startedAt":"2009-04-10T00:28:55Z","lastAt":"2009-04-15T18:00:59Z","messageCount":24,"participants":["Mark Levedahl","Junio C Hamano","Jeff King","Sverre Rabbelier","Jakub Narebski"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"110971","messageId":"1239323335-4684-1-git-send-email-mlevedahl@gmail.com","threadId":"18817","inReplyTo":null,"subject":"[PATCH] builtin-branch - allow deleting a fully specified branch-name","fromName":"Mark Levedahl","fromEmail":"mlevedahl@gmail.com","sentAt":"2009-04-10T00:28:55Z","receivedAt":"2009-04-10T00:28:55Z","isPatch":true,"sender":{"key":"mdl123@verizon.net","avatar":"https://avatars.githubusercontent.com/u/5302462?v=4"},"body":"This change allows, for instance\n\tgit branch -d refs/heads/foo\nto succeed. Without this patch, the code just assumes that the\ngiven branch name should be appended to \"refs/heads\" or\n\"refs/remotes\", thus attempting (and failing) in the above case\nto delete \"refs/heads/refs/heads/foo\"\n\nSigned-off-by: Mark Levedahl \n---\n builtin-branch.c | 6 +++++-\n 1 files changed, 5 insertions(+), 1 deletions(-)\n\ndiff --git a/builtin-branch.c b/builtin-branch.c\nindex ca81d72..f433bc5 100644\n--- a/builtin-branch.c\n+++ b/builtin-branch.c\n@@ -131,7 +131,11 @@ static int delete_branches(int argc, const char **argv, int force, int kinds)\n \n \t\tfree(name);\n \n-\t\tname = xstrdup(mkpath(fmt, bname.buf));\n+\t\tif (bname.len < 5 || memcmp(\"refs/\", bname.buf, 5))\n+\t\t\tname = xstrdup(mkpath(fmt, bname.buf));\n+\t\telse\n+\t\t\tname = xstrdup(bname.buf);\n+\n \t\tif (!resolve_ref(name, sha1, 1, NULL)) {\n \t\t\terror(\"%sbranch '%s' not found.\",\n \t\t\t\t\tremote, bname.buf);\n-- \n1.6.2.2.27.g034b\n"},{"id":"110979","messageId":"7vhc0x1gvh.fsf@gitster.siamese.dyndns.org","threadId":"18817","inReplyTo":"1239323335-4684-1-git-send-email-mlevedahl@gmail.com","subject":"Re: [PATCH] builtin-branch - allow deleting a fully specified branch-name","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-04-10T00:39:46Z","receivedAt":"2009-04-10T00:39:46Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Mark Levedahl writes:\n\n> This change allows, for instance\n> \tgit branch -d refs/heads/foo\n> to succeed. Without this patch, the code just assumes that the\n> given branch name should be appended to \"refs/heads\" or\n> \"refs/remotes\", thus attempting (and failing) in the above case\n> to delete \"refs/heads/refs/heads/foo\"\n\nYour logic is broken.\n\nWhy doesn't the user simply say \"git branch -d foo\"? The command takes\n\"the branch name\", not \"arbitrary ref name\".\n"},{"id":"110980","messageId":"200904092119.10520.mlevedahl@gmail.com","threadId":"18817","inReplyTo":"7vhc0x1gvh.fsf@gitster.siamese.dyndns.org","subject":"Re: [PATCH] builtin-branch - allow deleting a fully specified branch-name","fromName":"Mark Levedahl","fromEmail":"mlevedahl@gmail.com","sentAt":"2009-04-10T01:19:09Z","receivedAt":"2009-04-10T01:19:09Z","isPatch":true,"sender":{"key":"mdl123@verizon.net","avatar":"https://avatars.githubusercontent.com/u/5302462?v=4"},"body":"On Thursday 09 April 2009 20:39:46 Junio C Hamano wrote:\n> Mark Levedahl writes:\n> > This change allows, for instance\n> > \tgit branch -d refs/heads/foo\n> > to succeed. Without this patch, the code just assumes that the\n> > given branch name should be appended to \"refs/heads\" or\n> > \"refs/remotes\", thus attempting (and failing) in the above case\n> > to delete \"refs/heads/refs/heads/foo\"\n>\n> Your logic is broken.\n>\n> Why doesn't the user simply say \"git branch -d foo\"? The command takes\n> \"the branch name\", not \"arbitrary ref name\".\n\n1) git branch -d refs/ used to work, I haven't bisected to find \nwhen this stopped working, but the change broke one of my scripts, so this is \nnot new behavior, it is restoration of previous behavior.\n2) If I create branch refs/frotz/bar , how do I ever delete it?\n\nAlso, the following all work\n3) git branch refs/heads/foo\n4) git branch -m refs/heads/foo refs/heads/bar \n5) git [checkout|pull|push|fetch|show] refs/heads/foo\n\nSo, why is \"git branch -d\" so special?\n\nMark\n"},{"id":"110985","messageId":"7vbpr519jq.fsf@gitster.siamese.dyndns.org","threadId":"18817","inReplyTo":"200904092119.10520.mlevedahl@gmail.com","subject":"Re: [PATCH] builtin-branch - allow deleting a fully specified branch-name","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-04-10T03:18:01Z","receivedAt":"2009-04-10T03:18:01Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Mark Levedahl writes:\n\n> On Thursday 09 April 2009 20:39:46 Junio C Hamano wrote:\n>> Mark Levedahl writes:\n>> > This change allows, for instance\n>> > \tgit branch -d refs/heads/foo\n>> > to succeed. Without this patch, the code just assumes that the\n>> > given branch name should be appended to \"refs/heads\" or\n>> > \"refs/remotes\", thus attempting (and failing) in the above case\n>> > to delete \"refs/heads/refs/heads/foo\"\n>>\n>> Your logic is broken.\n>>\n>> Why doesn't the user simply say \"git branch -d foo\"? The command takes\n>> \"the branch name\", not \"arbitrary ref name\".\n>\n> 1) git branch -d refs/ used to work, I haven't bisected to find \n> when this stopped working, but the change broke one of my scripts, so this is \n> not new behavior, it is restoration of previous behavior.\n\nI need to look at the history, if that is the case then perhaps Ok.\n\n> 2) If I create branch refs/frotz/bar , how do I ever delete it?\n\nBy this you must mean .git/refs/heads/refs/frotz/bar, right? Then\nshouldn't \"git branch -d refs/frotz/bar\" just work as is? If you are\ntalking about .git/refs/frotz/bar, \"git branch\" should not touch it, it is\nnot even a branch.\n\n> Also, the following all work\n\n> 3) git branch refs/heads/foo\n> 4) git branch -m refs/heads/foo refs/heads/bar \n\nIf you mean it creates .git/refs/heads/refs/heads/foo, then sure it\nshould. If it creates .git/refs/heads/foo, I think it is broken.\n\n> 5) git [checkout|pull|push|fetch|show] refs/heads/foo\n\nAmong these, checkout is the only special case that can take \"branch name\"\nto switch branches. Everything else takes extended SHA-1 expression.\nCheckout can interpret the first argument as \"branch to switch to\", but it\ndoes not necessarily so---think \"detached HEAD\", and also think \"checking\nout paths out of tree-ish\".\n\n> So, why is \"git branch -d\" so special?\n\n\"git branch -d\", \"git branch -m\" and friends all take branch name, and as\nsuch it can use \"@{-1}\" to _name_ 'the previous branch\". In that context,\nyou are _not_ naming the commit at the tip of the branch. You are naming\nthe branch itself.\n\nAll other commands happen to take a branch name because that is just one\ncase of extended SHA-1 expression to name an object. In that context, a\nrefname (which a branch name is a special case of) refers to the commit\npointed by it. E.g.\n\n \"git checkout HEAD~20 -- Makefile\"\n \"git show refs/heads/foo\"\n \"git show heads/foo\"\n \"git show foo\"\n"},{"id":"111050","messageId":"200904111301.31250.mlevedahl@gmail.com","threadId":"18817","inReplyTo":"7vbpr519jq.fsf@gitster.siamese.dyndns.org","subject":"Re: [PATCH] builtin-branch - allow deleting a fully specified branch-name","fromName":"Mark Levedahl","fromEmail":"mlevedahl@gmail.com","sentAt":"2009-04-11T17:01:30Z","receivedAt":"2009-04-11T17:01:30Z","isPatch":true,"sender":{"key":"mdl123@verizon.net","avatar":"https://avatars.githubusercontent.com/u/5302462?v=4"},"body":"On Thursday 09 April 2009 23:18:01 you wrote:\n>\n> All other commands happen to take a branch name because that is just one\n> case of extended SHA-1 expression to name an object. In that context, a\n> refname (which a branch name is a special case of) refers to the commit\n> pointed by it. E.g.\n>\n> \"git checkout HEAD~20 -- Makefile\"\n> \"git show refs/heads/foo\"\n> \"git show heads/foo\"\n> \"git show foo\"\n\nI think my underlying problem here is the porcelain's ability to use either a \nbranch name or a ref name, in different contexts, leading to a sometimes \ninconsistent interface. Consider the following\n $ git checkout master\n checks out branch master\n $ git checkout refs/heads/master\n checks out commit pointed to by refs/heads/master on a detached \nHEAD\n\n $ git checkout -b refs/heads/master refs/heads/master\n creates a new branch, refname = refs/heads/refs/heads/master\n\nThe last command is the one that I find most curious. The exact same string \nhas two entirely different meanings to the same command. I can explain why \nthis happens, but I cannot explain why this is a good thing. \n\nA model I could explain without mental gymnastics would be \"branch names are \nsimply refnames without the leading refs/heads or refs/remotes, and a refname \nmay be used wherever a branch name is requested. While branch names are \npotentially ambiguous, refnames never are.\" Of course, this would mean that \nthe refs/heads/refs/... namespace is illegal. I don't know of any other \ndownside (except of course to someone using that namespace), and frankly I \ndon't think the existence of the refs/heads/refs namespace is a good thing, \ngiven the potential for confusion.\n\nJust a thought.\n\nMark\n"},{"id":"111119","messageId":"20090412072056.GA25837@coredump.intra.peff.net","threadId":"18817","inReplyTo":"200904111301.31250.mlevedahl@gmail.com","subject":"Re: [PATCH] builtin-branch - allow deleting a fully specified branch-name","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2009-04-12T07:20:57Z","receivedAt":"2009-04-12T07:20:57Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Sat, Apr 11, 2009 at 01:01:30PM -0400, Mark Levedahl wrote:\n\n> $ git checkout -b refs/heads/master refs/heads/master\n> creates a new branch, refname = refs/heads/refs/heads/master\n> \n> The last command is the one that I find most curious. The exact same string \n> has two entirely different meanings to the same command. I can explain why \n> this happens, but I cannot explain why this is a good thing. \n\nA command like \"grep foo foo\" has the same property (one string with\ndifferent meanings based on argument position). The problem is that you\nare thinking of it as:\n\n git checkout -b \n\nAnd I can see why you might think of it that way, because that is what\nthe synopsis in git-checkout(1) says. :) But it is really:\n\n git checkout -b \n\nI'm not sure if changing that synopsis would really help, or if it is\na bit too subtle.\n\n> A model I could explain without mental gymnastics would be \"branch names are \n> simply refnames without the leading refs/heads or refs/remotes, and a refname \n> may be used wherever a branch name is requested. While branch names are \n> potentially ambiguous, refnames never are.\" Of course, this would mean that \n\nSo the current model is: \"branch names are simply refnames without the\nleading refs/heads or refs/remotes. A can be referenced by the\nusual names (see git rev-parse, \"specifying revisions\" for details)\".\n\nThe thing that I think is more confusing about that is not the\nfinal example you pointed out, but the difference between\n\n git checkout master\n\nand\n\n git checkout refs/heads/master\n\nWhich is explained by the fact that the usage for checkout is not\n\n git checkout \n\nbut actually\n\n git checkout \n\nIf a branch, then we checkout the branch. If a commit, then we detach on\nthat commit.\n\nI'm not sure if that explanation helps you at all, but that is how I\nthink of it (and it makes sense to me).\n\n-Peff\n"},{"id":"111120","messageId":"7v7i1qb7sw.fsf@gitster.siamese.dyndns.org","threadId":"18817","inReplyTo":"20090412072056.GA25837@coredump.intra.peff.net","subject":"Re: [PATCH] builtin-branch - allow deleting a fully specified branch-name","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-04-12T08:22:23Z","receivedAt":"2009-04-12T08:22:23Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n> And I can see why you might think of it that way, because that is what\n> the synopsis in git-checkout(1) says. :) But it is really:\n>\n> git checkout -b \n>\n> I'm not sure if changing that synopsis would really help, or if it is\n> a bit too subtle.\n\nI think in many places we used to be stricter in terminology (e.g. when we\nonly need tree-ish we used to write tree-ish) but during the \"usability\nand approachiablility drive\" people updated doc with \"most of the time the\ncommand takes commit, so we say commit\".\n\nI think \"the apporachable part\" aka \"synopsis\" should be kept the way it\nis, but we should clarify in the description when the most general form is\ndifferent from the white lie we feed to newbies.\n"},{"id":"111169","messageId":"20090413085622.GC9846@coredump.intra.peff.net","threadId":"18817","inReplyTo":"7v7i1qb7sw.fsf@gitster.siamese.dyndns.org","subject":"Re: [PATCH] builtin-branch - allow deleting a fully specified branch-name","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2009-04-13T08:56:22Z","receivedAt":"2009-04-13T08:56:22Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Sun, Apr 12, 2009 at 01:22:23AM -0700, Junio C Hamano wrote:\n\n> > And I can see why you might think of it that way, because that is what\n> > the synopsis in git-checkout(1) says. :) But it is really:\n> >\n> > git checkout -b \n> >\n> > I'm not sure if changing that synopsis would really help, or if it is\n> > a bit too subtle.\n> \n> I think in many places we used to be stricter in terminology (e.g. when we\n> only need tree-ish we used to write tree-ish) but during the \"usability\n> and approachiablility drive\" people updated doc with \"most of the time the\n> command takes commit, so we say commit\".\n\nYeah, I think this is one of the fundamental usability debates of git.\nOn one hand, if you assume that the user learns about the object types,\nthe DAG, and refs, then all of this is very straightforward to explain.\nThe price you pay is a steep learning curve. On the other, you can get\n95% of what you need done without ever being exposed to the technical\ndetails, so I can see why people push for learning materials that gloss\nover it.\n\n> I think \"the apporachable part\" aka \"synopsis\" should be kept the way it\n> is, but we should clarify in the description when the most general form is\n> different from the white lie we feed to newbies.\n\nHmm. I tried something in this direction, but I actually think it ended\nup more confusing.\n\nI think it would be better in the synopsis to split this into two use\ncases:\n\n git checkout []\n git checkout -b []\n\nAnd then explain them as separate definitions.\n\n-Peff\n"},{"id":"111170","messageId":"7vws9ohoa4.fsf@gitster.siamese.dyndns.org","threadId":"18817","inReplyTo":"20090413085622.GC9846@coredump.intra.peff.net","subject":"Re: [PATCH] builtin-branch - allow deleting a fully specified branch-name","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-04-13T09:54:27Z","receivedAt":"2009-04-13T09:54:27Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n> I think it would be better in the synopsis to split this into two use\n> cases:\n>\n> git checkout []\n> git checkout -b []\n>\n> And then explain them as separate definitions.\n\nI'd agree it would make it much nicer.\n\nThanks for a bit of sanity. I sometimes misplace it when I got grumpy.\n"},{"id":"111174","messageId":"20090413105742.GA15676@coredump.intra.peff.net","threadId":"18817","inReplyTo":"20090413085622.GC9846@coredump.intra.peff.net","subject":"Re: [PATCH] builtin-branch - allow deleting a fully specified branch-name","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2009-04-13T10:57:42Z","receivedAt":"2009-04-13T10:57:42Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Mon, Apr 13, 2009 at 04:56:22AM -0400, Jeff King wrote:\n\n> > I think \"the apporachable part\" aka \"synopsis\" should be kept the way it\n> > is, but we should clarify in the description when the most general form is\n> > different from the white lie we feed to newbies.\n> \n> Hmm. I tried something in this direction, but I actually think it ended\n> up more confusing.\n\nI meant to attach a patch here so you could judge for yourself, but I\nforgot. I am preparing a patch series which I think is better, but for\nreference, here is what I came up with before:\n\n---\ndiff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\nindex 223ea9c..344c57a 100644\n--- a/Documentation/git-checkout.txt\n+++ b/Documentation/git-checkout.txt\n@@ -131,15 +131,20 @@ the conflicted merge in the specified paths.\n \tthe index will be used.\n \n ::\n-\tBranch to checkout (when no paths are given); may be any object\n-\tID that resolves to a commit. Defaults to HEAD.\n+\tIf \"-b\" is not given, specifies the branch to checkout. If it\n+\tnames a non-branch (i.e., a name that, when prepended with\n+\t\"refs/heads/\", does not exist) but does point to a\n+\tvalid commit object, then the HEAD becomes 'detached', and you\n+\tare no longer on any branch. As a special case, the `\"@\\{-N\\}\"`\n+\tsyntax for the N-th last branch checks out the branch (instead\n+\tof detaching). You may also specify `-` which is synonymous\n+\twith `\"@\\{-1\\}\"`.\n +\n-When this parameter names a non-branch (but still a valid commit object),\n-your HEAD becomes 'detached'.\n+If \"-b\" is given, specifies the start point of the newly created\n+branch. Specifying a non-branch is irrelevant here, since git will\n+checkout the newly created branch, not the start point.\n +\n-As a special case, the `\"@\\{-N\\}\"` syntax for the N-th last branch\n-checks out the branch (instead of detaching). You may also specify\n-`-` which is synonymous with `\"@\\{-1\\}\"`.\n+In either case, if the parameter is omitted, it defaults to HEAD.\n \n \n Detached HEAD\n"},{"id":"111175","messageId":"20090413110947.GA15647@coredump.intra.peff.net","threadId":"18817","inReplyTo":"7vws9ohoa4.fsf@gitster.siamese.dyndns.org","subject":"Re: [PATCH] builtin-branch - allow deleting a fully specified branch-name","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2009-04-13T11:09:47Z","receivedAt":"2009-04-13T11:09:47Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Mon, Apr 13, 2009 at 02:54:27AM -0700, Junio C Hamano wrote:\n\n> > I think it would be better in the synopsis to split this into two use\n> > cases:\n> >\n> > git checkout []\n> > git checkout -b []\n> >\n> > And then explain them as separate definitions.\n> \n> I'd agree it would make it much nicer.\n\nA 5-patch series follows which does this and a few other fixups. I think\nthe result is better.\n\n 1/5 doc: clarify --no-track option\n 2/5 doc: refer to tracking configuration as \"upstream\"\n 3/5 doc/checkout: refer to git-branch(1) as appropriate\n 4/5 doc/checkout: split checkout and branch creation in synopsis\n 5/5 docs/checkout: clarify what \"non-branch\" means\n\n-Peff\n"},{"id":"111176","messageId":"20090413111116.GA15982@coredump.intra.peff.net","threadId":"18817","inReplyTo":"20090413110947.GA15647@coredump.intra.peff.net","subject":"[PATCH 1/5] doc: clarify --no-track option","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2009-04-13T11:11:16Z","receivedAt":"2009-04-13T11:11:16Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"It is not really about ignoring the config option; it is\nabout turning off tracking, _even if_ the config option is\nset.\n\nSigned-off-by: Jeff King \n---\nThis I just noticed while working in the area, and it bothered me.\n\n Documentation/git-branch.txt | 3 ++-\n Documentation/git-checkout.txt | 3 ++-\n 2 files changed, 4 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt\nindex ba3dea6..19f1b0d 100644\n--- a/Documentation/git-branch.txt\n+++ b/Documentation/git-branch.txt\n@@ -124,7 +124,8 @@ OPTIONS\n \tstart-point is either a local or remote branch.\n \n --no-track::\n-\tIgnore the branch.autosetupmerge configuration variable.\n+\tDo not set up tracking configuration, even if the\n+\tbranch.autosetupmerge configuration variable is true.\n \n --contains ::\n \tOnly list branches which contain the specified commit.\ndiff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\nindex 223ea9c..4992fc6 100644\n--- a/Documentation/git-checkout.txt\n+++ b/Documentation/git-checkout.txt\n@@ -90,7 +90,8 @@ guessing results in an empty name, the guessing is aborted. You can\n explicitly give a name with '-b' in such a case.\n \n --no-track::\n-\tIgnore the branch.autosetupmerge configuration variable.\n+\tDo not set up tracking configuration, even if the\n+\tbranch.autosetupmerge configuration variable is true.\n \n -l::\n \tCreate the new branch's reflog. This activates recording of\n-- \n1.6.3.rc0.148.g141203.dirty\n"},{"id":"111177","messageId":"20090413111156.GB15982@coredump.intra.peff.net","threadId":"18817","inReplyTo":"20090413110947.GA15647@coredump.intra.peff.net","subject":"[PATCH 2/5] doc: refer to tracking configuration as \"upstream\"","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2009-04-13T11:11:56Z","receivedAt":"2009-04-13T11:11:56Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"The term \"tracking\" often creates confusion between remote\ntracking branches and local branches which track a remote\nbranch. The term \"upstream\" captures more clearly the idea\nof \"branch A is based on branch B in some way\", so it makes\nsense to mention it.\n\nAt the same time, upstream branches are used for more\nthan just git-pull these days; let's mention that here.\n\nSigned-off-by: Jeff King \n---\nI think this matches nicely with Santi's recent addition of upstream to\nthe glossary.\n\n Documentation/git-branch.txt | 24 +++++++++++++-----------\n Documentation/git-checkout.txt | 2 +-\n 2 files changed, 14 insertions(+), 12 deletions(-)\n\ndiff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt\nindex 19f1b0d..cbd4275 100644\n--- a/Documentation/git-branch.txt\n+++ b/Documentation/git-branch.txt\n@@ -112,19 +112,21 @@ OPTIONS\n \tDisplay the full sha1s in the output listing rather than abbreviating them.\n \n --track::\n-\tWhen creating a new branch, set up the configuration so that 'git-pull'\n-\twill automatically retrieve data from the start point, which must be\n-\ta branch. Use this if you always pull from the same upstream branch\n-\tinto the new branch, and if you do not want to use \"git pull\n-\t \" explicitly. This behavior is the default\n-\twhen the start point is a remote branch. Set the\n-\tbranch.autosetupmerge configuration variable to `false` if you want\n-\t'git-checkout' and 'git-branch' to always behave as if '--no-track' were\n-\tgiven. Set it to `always` if you want this behavior when the\n-\tstart-point is either a local or remote branch.\n+\tWhen creating a new branch, set up configuration to mark the\n+\tstart-point branch as \"upstream\" from the new branch. This\n+\tconfiguration will tell git to show the relationship between the\n+\ttwo branches in `git status` and `git branch -v`. Furthermore,\n+\tit directs `git pull` without arguments to pull from the\n+\tupstream when the new branch is checked out.\n++\n+This behavior is the default when the start point is a remote branch.\n+Set the branch.autosetupmerge configuration variable to `false` if you\n+want `git checkout` and `git branch` to always behave as if '--no-track'\n+were given. Set it to `always` if you want this behavior when the\n+start-point is either a local or remote branch.\n \n --no-track::\n-\tDo not set up tracking configuration, even if the\n+\tDo not set up \"upstream\" configuration, even if the\n \tbranch.autosetupmerge configuration variable is true.\n \n --contains ::\ndiff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\nindex 4992fc6..16d3c87 100644\n--- a/Documentation/git-checkout.txt\n+++ b/Documentation/git-checkout.txt\n@@ -90,7 +90,7 @@ guessing results in an empty name, the guessing is aborted. You can\n explicitly give a name with '-b' in such a case.\n \n --no-track::\n-\tDo not set up tracking configuration, even if the\n+\tDo not set up \"upstream\" configuration, even if the\n \tbranch.autosetupmerge configuration variable is true.\n \n -l::\n-- \n1.6.3.rc0.148.g141203.dirty\n"},{"id":"111178","messageId":"20090413111852.GC15982@coredump.intra.peff.net","threadId":"18817","inReplyTo":"20090413110947.GA15647@coredump.intra.peff.net","subject":"[PATCH 3/5] doc/checkout: refer to git-branch(1) as appropriate","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2009-04-13T11:18:52Z","receivedAt":"2009-04-13T11:18:52Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"Most of description for the branch creation options is\nsimply cut and paste from git-branch. There are two reasons\nto fix this:\n\n 1. It can grow stale with respect to what's in \"git\n branch\" (which it is now is).\n\n 2. It is not just an implementation detail, but rather the\n desired mental model for the command that we are using\n \"git branch\" here. Being explicit about that can help\n the user understand what is going on.\n\nIt also makes sense to strip the branch creation options\nfrom the synopsis, as they are making it a long,\nhard-to-read line. They are still easily discovered by\nreading the options list, and --track is explicitly\nreferenced when branch creation is described.\n\nSigned-off-by: Jeff King \n---\nThere are two things here that people might disagree with:\n\n 1. Referring the user instead of using asciidoc magic to just include\n the repeated text. While it is nice to save the user the effort\n of referencing the other documentation, I think sometimes we go too\n far with this in git. Sometimes it is beneficial for the user not\n just to get the information, but to have it pointed out that the\n link exists. Then they can better understand exactly what it is git\n is doing (it is not \"oh, this is a totally unrelated way to create\n branches\" but \"this is a convenience wrapper that calls git branch\"\n -- I think the latter is the model we want to use).\n\n 2. Shortening the synopsis field. The long lines look awful in the\n manpage on an 80-column terminal. I don't read git documentation\n very often, so I have not really noticed, but some of our synopses\n are quite complex and IMHO unreadable. We are much better off just\n saying \"there are some options, then these 1 or 2 arguments\" which\n give an overview of how you would invoke the command. You can look\n at the option list if you want to actually see the options.\n\n In this patch I just shortened the ones related to branch creation.\n But I was tempted to take this a step further and get rid of the\n \"-f\", \"-q\", and \"-m\" options in the synopsis, as well, which I think\n would look much better.\n\n Documentation/git-checkout.txt | 28 +++++++++-------------------\n 1 files changed, 9 insertions(+), 19 deletions(-)\n\ndiff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\nindex 16d3c87..22ad10d 100644\n--- a/Documentation/git-checkout.txt\n+++ b/Documentation/git-checkout.txt\n@@ -8,7 +8,7 @@ git-checkout - Checkout a branch or paths to the working tree\n SYNOPSIS\n --------\n [verse]\n-'git checkout' [-q] [-f] [-t | --track | --no-track] [-b [-l]] [-m] []\n+'git checkout' [-q] [-f] [-m] [-b ] []\n 'git checkout' [-f|--ours|--theirs|-m|--conflict=