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

[PATCH 3/6] branch: teach --edit-description option

From
Junio C Hamano <gitster@pobox.com>
Date
Sep 22, 2011, 22:09 UTC
Message-ID
<1316729362-7714-4-git-send-email-gitster@pobox.com>
In-Reply-To
<1316729362-7714-1-git-send-email-gitster@pobox.com>

Using branch.$name.description as the configuration key, give users a place to write about what the purpose of the branch is and things like that, so that various subsystems, e.g. "push -s", "request-pull", and "format-patch --cover-letter", can later be taught to use this information.

The "-m" option similar to "commit/tag" is deliberately omitted, as the whole point of branch description is about giving descriptive information (the name of the branch itself is a better place for information that fits on a single-line).

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/git-branch.txt |    5 +++
 builtin/branch.c             |   56 ++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 59 insertions(+), 2 deletions(-)
diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
index 507b8d0..8871a4e 100644
--- a/Documentation/git-branch.txt
+++ b/Documentation/git-branch.txt
@@ -14,6 +14,7 @@ SYNOPSIS
 'git branch' [--set-upstream | --track | --no-track] [-l] [-f] <branchname> [<start-point>]
 'git branch' (-m | -M) [<oldbranch>] <newbranch>
 'git branch' (-d | -D) [-r] <branchname>...
+'git branch' --edit-description [<branchname>]
 
 DESCRIPTION
 -----------
@@ -144,6 +145,10 @@ start-point is either a local or remote-tracking branch.
 	like '--track' would when creating the branch, except that where
 	branch points to is not changed.
 
+--edit-description::
+	Open an editor and edit the text to explain what the branch is
+	for, to be used by various other commands (e.g. `request-pull`).
+
 --contains <commit>::
 	Only list branches which contain the specified commit.
 
diff --git a/builtin/branch.c b/builtin/branch.c
index f49596f..fffa319 100644
--- a/builtin/branch.c
+++ b/builtin/branch.c
@@ -606,11 +606,49 @@ static int opt_parse_merge_filter(const struct option *opt, const char *arg, int
 	return 0;
 }
 
+static const char edit_description[] = "BRANCH_DESCRIPTION";
+
+static int edit_branch_description(const char *branch_name)
+{
+	FILE *fp;
+	int status;
+	struct strbuf buf = STRBUF_INIT;
+	struct strbuf name = STRBUF_INIT;
+
+	read_branch_desc(&buf, branch_name);
+	if (!buf.len || buf.buf[buf.len-1] != '\n')
+		strbuf_addch(&buf, '\n');
+	strbuf_addf(&buf,
+		    "# Please edit the description for the branch\n"
+		    "#   %s\n"
+		    "# Lines starting with '#' will be stripped.\n",
+		    branch_name);
+	fp = fopen(git_path(edit_description), "w");
+	if ((fwrite(buf.buf, 1, buf.len, fp) < buf.len) || fclose(fp)) {
+		strbuf_release(&buf);
+		return error(_("could not write branch description template: %s\n"),
+			     strerror(errno));
+	}
+	strbuf_reset(&buf);
+	if (launch_editor(git_path(edit_description), &buf, NULL)) {
+		strbuf_release(&buf);
+		return -1;
+	}
+	stripspace(&buf, 1);
+
+	strbuf_addf(&name, "branch.%s.description", branch_name);
+	status = git_config_set(name.buf, buf.buf);
+	strbuf_release(&name);
+	strbuf_release(&buf);
+
+	return status;
+}
+
 int cmd_branch(int argc, const char **argv, const char *prefix)
 {
 	int delete = 0, rename = 0, force_create = 0;
 	int verbose = 0, abbrev = -1, detached = 0;
-	int reflog = 0;
+	int reflog = 0, edit_description = 0;
 	enum branch_track track;
 	int kinds = REF_LOCAL_BRANCH;
 	struct commit_list *with_commit = NULL;
@@ -648,6 +686,8 @@ int cmd_branch(int argc, const char **argv, const char *prefix)
 		OPT_BIT('m', NULL, &rename, "move/rename a branch and its reflog", 1),
 		OPT_BIT('M', NULL, &rename, "move/rename a branch, even if target exists", 2),
 		OPT_BOOLEAN('l', NULL, &reflog, "create the branch's reflog"),
+		OPT_BOOLEAN(0, "edit-description", &edit_description,
+			    "edit the description for the branch"),
 		OPT__FORCE(&force_create, "force creation (when already exists)"),
 		{
 			OPTION_CALLBACK, 0, "no-merged", &merge_filter_ref,
@@ -694,7 +734,19 @@ int cmd_branch(int argc, const char **argv, const char *prefix)
 
 	if (delete)
 		return delete_branches(argc, argv, delete > 1, kinds);
-	else if (argc == 0)
+	else if (edit_description) {
+		const char *branch_name;
+		if (detached)
+			die("Cannot give description to detached HEAD");
+		if (!argc)
+			branch_name = head;
+		else if (argc == 1)
+			branch_name = argv[0];
+		else
+			usage_with_options(builtin_branch_usage, options);
+		if (edit_branch_description(branch_name))
+			return 1;
+	} else if (argc == 0)
 		return print_ref_list(kinds, detached, verbose, abbrev, with_commit);
 	else if (rename && (argc == 1))
 		rename_branch(head, argv[0], rename > 1);

-- 
1.7.7.rc2.4.g5ec82
Previous: Junio C HamanoNext: Michael J Gruber
Message 44 of 62 in “[Survey] Signed push”
  1. Junio C HamanoSep 13, 2011
  2. 0/2 State commit name explicitly in request-pull messagesJunio C Hamano, Sep 13, 2011
  3. 1/2 fetch: allow asking for an explicit commit object by nameJunio C Hamano, Sep 13, 2011
  4. 2/2 request-pull: state exact commit object nameJunio C Hamano, Sep 13, 2011
  5. Guenter RoeckSep 13, 2011
  6. Junio C HamanoSep 13, 2011
  7. Junio C HamanoSep 14, 2011
  8. Sam VilainSep 14, 2011
  9. Shawn PearceSep 14, 2011
  10. Sam VilainSep 14, 2011
  11. Nguyen Thai Ngoc DuySep 14, 2011
  12. Jonathan NiederSep 14, 2011
  13. Nguyen Thai Ngoc DuySep 14, 2011
  14. Jeff KingSep 15, 2011
  15. Andy LutomirskiSep 14, 2011
  16. Junio C HamanoSep 14, 2011
  17. Andrew LutomirskiSep 14, 2011
  18. Fwd: [Survey] Signed pushLinus Torvalds, Sep 14, 2011
  19. Michael HaggertySep 14, 2011
  20. Matthieu MoySep 14, 2011
  21. Nguyen Thai Ngoc DuySep 14, 2011
  22. Johan HerlandSep 14, 2011
  23. Ted Ts'oSep 14, 2011
  24. Linus TorvaldsSep 14, 2011
  25. Matthieu MoySep 14, 2011
  26. Johan HerlandSep 14, 2011
  27. Philip OakleySep 14, 2011
  28. Linus TorvaldsSep 14, 2011
  29. Junio C HamanoSep 14, 2011
  30. Linus TorvaldsSep 14, 2011
  31. Junio C HamanoSep 14, 2011
  32. Linus TorvaldsSep 14, 2011
  33. Junio C HamanoSep 14, 2011
  34. Sam VilainSep 14, 2011
  35. request-pull: state what commit to expectJunio C Hamano, Sep 16, 2011
  36. Junio C HamanoSep 20, 2011
  37. 2/3 branch: teach --edit-description optionJunio C Hamano, Sep 20, 2011
  38. Andrew ArdillSep 21, 2011
  39. Junio C HamanoSep 21, 2011
  40. request-pull: use the branch descriptionJunio C Hamano, Sep 20, 2011
  41. 0/6 A handful of "branch description" patchesJunio C Hamano, Sep 22, 2011
  42. 1/6 branch: add read_branch_desc() helper functionJunio C Hamano, Sep 22, 2011
  43. 2/6 format-patch: use branch description in cover letterJunio C Hamano, Sep 22, 2011
  44. 3/6 branch: teach --edit-description optionJunio C Hamano, Sep 22, 2011
  45. Michael J GruberSep 23, 2011
  46. Nguyen Thai Ngoc DuySep 23, 2011
  47. Junio C HamanoSep 23, 2011
  48. Nguyen Thai Ngoc DuySep 25, 2011
  49. 4/6 request-pull: modernize styleJunio C Hamano, Sep 22, 2011
  50. 5/6 request-pull: state what commit to expectJunio C Hamano, Sep 22, 2011
  51. 6/6 request-pull: use the branch descriptionJunio C Hamano, Sep 22, 2011
  52. Michael J GruberSep 23, 2011
  53. Jeff KingSep 23, 2011
  54. Junio C HamanoSep 23, 2011
  55. Jeff KingSep 23, 2011
  56. Michael J GruberSep 24, 2011
  57. Jeff KingSep 27, 2011
  58. Annotated branch ≈ annotated tag?Michael Haggerty, Sep 28, 2011
  59. Andrew ArdillSep 28, 2011
  60. Michael HaggertySep 28, 2011
  61. Branch annotations [Re: Annotated branch ≈ annotated tag?]Michael J Gruber, Sep 28, 2011
  62. Jeff KingSep 29, 2011

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.