git/list[1] front-page[2] threads[3] people[4] search[5] about
 

Re: [PATCH] builtin-branch - allow deleting a fully specified branch-name

From
Jeff King <peff@peff.net>
Date
Apr 13, 2009, 10:57 UTC
Message-ID
<20090413105742.GA15676@coredump.intra.peff.net>
In-Reply-To
<20090413085622.GC9846@coredump.intra.peff.net>
On Mon, Apr 13, 2009 at 04:56:22AM -0400, Jeff King wrote:
Show 6 quoted lines
> > I think "the apporachable part" aka "synopsis" should be kept the way it
> > is, but we should clarify in the description when the most general form is
> > different from the white lie we feed to newbies.
> 
> Hmm. I tried something in this direction, but I actually think it ended
> up more confusing.

I meant to attach a patch here so you could judge for yourself, but I forgot. I am preparing a patch series which I think is better, but for reference, here is what I came up with before:

---
diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 223ea9c..344c57a 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -131,15 +131,20 @@ the conflicted merge in the specified paths.
 	the index will be used.
 
 <branch>::
-	Branch to checkout (when no paths are given); may be any object
-	ID that resolves to a commit.  Defaults to HEAD.
+	If "-b" is not given, specifies the branch to checkout. If it
+	names a non-branch (i.e., a name that, when prepended with
+	"refs/heads/", does not exist) but does point to a
+	valid commit object, then the HEAD becomes 'detached', and you
+	are no longer on any branch.  As a special case, the `"@\{-N\}"`
+	syntax for the N-th last branch checks out the branch (instead
+	of detaching).  You may also specify `-` which is synonymous
+	with `"@\{-1\}"`.
 +
-When this parameter names a non-branch (but still a valid commit object),
-your HEAD becomes 'detached'.
+If "-b" is given, specifies the start point of the newly created
+branch. Specifying a non-branch is irrelevant here, since git will
+checkout the newly created branch, not the start point.
 +
-As a special case, the `"@\{-N\}"` syntax for the N-th last branch
-checks out the branch (instead of detaching).  You may also specify
-`-` which is synonymous with `"@\{-1\}"`.
+In either case, if the parameter is omitted, it defaults to HEAD.
 
 
 Detached HEAD
Previous: Jeff KingNext: Jeff King
Message 22 of 24 in “builtin-branch - allow deleting a fully specified branch-name”
  1. builtin-branch - allow deleting a fully specified branch-nameMark Levedahl, Apr 10, 2009
  2. Junio C HamanoApr 10, 2009
  3. Mark LevedahlApr 10, 2009
  4. Junio C HamanoApr 10, 2009
  5. Mark LevedahlApr 11, 2009
  6. Jeff KingApr 12, 2009
  7. Junio C HamanoApr 12, 2009
  8. Jeff KingApr 13, 2009
  9. Junio C HamanoApr 13, 2009
  10. Jeff KingApr 13, 2009
  11. 1/5 doc: clarify --no-track optionJeff King, Apr 13, 2009
  12. 2/5 doc: refer to tracking configuration as "upstream"Jeff King, Apr 13, 2009
  13. 3/5 doc/checkout: refer to git-branch(1) as appropriateJeff King, Apr 13, 2009
  14. 4/5 doc/checkout: split checkout and branch creation in synopsisJeff King, Apr 13, 2009
  15. 5/5 docs/checkout: clarify what "non-branch" meansJeff King, Apr 13, 2009
  16. Junio C HamanoApr 13, 2009
  17. Mark LevedahlApr 14, 2009
  18. Junio C HamanoApr 14, 2009
  19. Jakub NarebskiApr 14, 2009
  20. Jeff KingApr 15, 2009
  21. Jeff KingApr 15, 2009
  22. Jeff KingApr 13, 2009
  23. Jeff KingApr 13, 2009
  24. Sverre RabbelierApr 13, 2009

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.