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

[PATCH 2/6] Introduce commit notes

From
Johannes Schindelin <johannes.schindelin@gmx.de>
Date
Jul 15, 2007, 23:23 UTC
Message-ID
<Pine.LNX.4.64.0707160022560.14781@racer.site>
In-Reply-To
<Pine.LNX.4.64.0707152326080.14781@racer.site>

Commit notes are blobs which are shown together with the commit message. These blobs are taken from the notes ref, which you can configure by the config variable core.notesRef, which in turn can be overridden by the environment variable GIT_NOTES_REF.

The notes ref is a branch which contains trees much like the loose object trees in .git/objects/. In other words, to get at the commit notes for a given SHA-1, take the first two hex characters as directory name, and the remaining 38 hex characters as base name, and look that up in the notes ref.

The rationale for putting this information into a ref is this: we want to be able to fetch and possibly union-merge the notes, maybe even look at the date when a note was introduced, and we want to store them efficiently together with the other objects.

There is one severe shortcoming, though. Since tree objects can contain file names of a variable length, it is not possible to do a binary search for the correct base name in the tree object's contents. Therefore this approach does not scale well, because the average lookup time will be proportional to the number of commit objects, and therefore the slowdown will be quadratic in that number.

However, a remedy is near: in a later commit, a .git/notes-index will be introduced, a cached mapping from commits to commit notes, to be written when the tree name of the notes ref changes. In case that notes-index cannot be written, the current (possibly slow) code will come into effect again.

Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
---
 Documentation/config.txt |   15 +++++++++++
 Makefile                 |    3 +-
 cache.h                  |    1 +
 commit.c                 |    5 +++
 config.c                 |    5 +++
 environment.c            |    1 +
 notes.c                  |   64 ++++++++++++++++++++++++++++++++++++++++++++++
 notes.h                  |    9 ++++++
 8 files changed, 102 insertions(+), 1 deletions(-)
 create mode 100644 notes.c
 create mode 100644 notes.h
diff --git a/Documentation/config.txt b/Documentation/config.txt
index d0e9a17..5fe833d 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -285,6 +285,21 @@ core.pager::
 	The command that git will use to paginate output.  Can be overridden
 	with the `GIT_PAGER` environment variable.
 
+core.notesRef::
+	When showing commit messages, also show notes which are stored in
+	the given ref.  This ref is expected to contain paths of the form
+	??/*, where the directory name consists of the first two
+	characters of the commit name, and the base name consists of
+	the remaining 38 characters.
++
+If such a path exists in the given ref, the referenced blob is read, and
+appended to the commit message, separated by a "Notes:" line.  If the
+given ref itself does not exist, it is not an error, but means that no
+notes should be print.
++
+This setting defaults to "refs/notes/commits", and can be overridden by
+the `GIT_NOTES_REF` environment variable.
+
 alias.*::
 	Command aliases for the gitlink:git[1] command wrapper - e.g.
 	after defining "alias.last = cat-file commit HEAD", the invocation
diff --git a/Makefile b/Makefile
index d7541b4..119d949 100644
--- a/Makefile
+++ b/Makefile
@@ -322,7 +322,8 @@ LIB_OBJS = \
 	write_or_die.o trace.o list-objects.o grep.o match-trees.o \
 	alloc.o merge-file.o path-list.o help.o unpack-trees.o $(DIFF_OBJS) \
 	color.o wt-status.o archive-zip.o archive-tar.o shallow.o utf8.o \
-	convert.o attr.o decorate.o progress.o mailmap.o symlinks.o remote.o
+	convert.o attr.o decorate.o progress.o mailmap.o symlinks.o remote.o \
+	notes.o
 
 BUILTIN_OBJS = \
 	builtin-add.o \
diff --git a/cache.h b/cache.h
index 328c1ad..c89cac5 100644
--- a/cache.h
+++ b/cache.h
@@ -309,6 +309,7 @@ extern size_t packed_git_window_size;
 extern size_t packed_git_limit;
 extern size_t delta_base_cache_limit;
 extern int auto_crlf;
+extern char *notes_ref_name;
 
 #define GIT_REPO_VERSION 0
 extern int repository_format_version;
diff --git a/commit.c b/commit.c
index 0c350bc..3529b6a 100644
--- a/commit.c
+++ b/commit.c
@@ -6,6 +6,7 @@
 #include "interpolate.h"
 #include "diff.h"
 #include "revision.h"
+#include "notes.h"
 
 int save_commit_buffer = 1;
 
@@ -1254,6 +1255,10 @@ unsigned long pretty_print_commit(enum cmit_fmt fmt,
 	 */
 	if (fmt == CMIT_FMT_EMAIL && offset <= beginning_of_body)
 		buf[offset++] = '\n';
+
+	if (fmt != CMIT_FMT_ONELINE)
+		get_commit_notes(commit, buf_p, &offset, space_p);
+
 	buf[offset] = '\0';
 	free(reencoded);
 	return offset;
diff --git a/config.c b/config.c
index f89a611..05d2ad6 100644
--- a/config.c
+++ b/config.c
@@ -395,6 +395,11 @@ int git_default_config(const char *var, const char *value)
 		return 0;
 	}
 
+	if (!strcmp(var, "core.notesref")) {
+		notes_ref_name = xstrdup(value);
+		return 0;
+	}
+
 	if (!strcmp(var, "user.name")) {
 		strlcpy(git_default_name, value, sizeof(git_default_name));
 		return 0;
diff --git a/environment.c b/environment.c
index f83fb9e..2e677d3 100644
--- a/environment.c
+++ b/environment.c
@@ -34,6 +34,7 @@ char *pager_program;
 int pager_in_use;
 int pager_use_color = 1;
 int auto_crlf = 0;	/* 1: both ways, -1: only when adding git objects */
+char *notes_ref_name;
 
 static const char *git_dir;
 static char *git_object_dir, *git_index_file, *git_refs_dir, *git_graft_file;
diff --git a/notes.c b/notes.c
new file mode 100644
index 0000000..5d1bb1a
--- /dev/null
+++ b/notes.c
@@ -0,0 +1,64 @@
+#include "cache.h"
+#include "commit.h"
+#include "notes.h"
+#include "refs.h"
+
+static int initialized;
+
+void get_commit_notes(const struct commit *commit,
+		char **buf_p, unsigned long *offset_p, unsigned long *space_p)
+{
+	char name[80];
+	const char *hex;
+	unsigned char sha1[20];
+	char *msg;
+	unsigned long msgoffset, msglen;
+	enum object_type type;
+
+	if (!initialized) {
+		const char *env = getenv(GIT_NOTES_REF);
+		if (env) {
+			if (notes_ref_name)
+				free(notes_ref_name);
+			notes_ref_name = xstrdup(getenv(GIT_NOTES_REF));
+		} else if (!notes_ref_name)
+			notes_ref_name = xstrdup("refs/notes/commits");
+		if (notes_ref_name && read_ref(notes_ref_name, sha1)) {
+			free(notes_ref_name);
+			notes_ref_name = NULL;
+		}
+		initialized = 1;
+	}
+	if (!notes_ref_name)
+		return;
+
+	hex = sha1_to_hex(commit->object.sha1);
+	snprintf(name, sizeof(name), "%s:%.*s/%.*s",
+			notes_ref_name, 2, hex, 38, hex + 2);
+	if (get_sha1(name, sha1))
+		return;
+
+	if (!(msg = read_sha1_file(sha1, &type, &msglen)) || !msglen)
+		return;
+	/* we will end the annotation by a newline anyway. */
+	if (msg[msglen - 1] == '\n')
+		msglen--;
+
+	ALLOC_GROW(*buf_p, *offset_p + 14 + msglen, *space_p);
+	*offset_p += sprintf(*buf_p + *offset_p, "\nNotes:\n");
+
+	for (msgoffset = 0; msgoffset < msglen;) {
+		int linelen = get_line_length(msg + msgoffset, msglen);
+
+		ALLOC_GROW(*buf_p, *offset_p + linelen + 6, *space_p);
+		*offset_p += sprintf(*buf_p + *offset_p,
+				"    %.*s", linelen, msg + msgoffset);
+		msgoffset += linelen;
+	}
+	ALLOC_GROW(*buf_p, *offset_p + 1, *space_p);
+	(*buf_p)[*offset_p] = '\n';
+	(*offset_p)++;
+	free(msg);
+}
+
+
diff --git a/notes.h b/notes.h
new file mode 100644
index 0000000..aed80e7
--- /dev/null
+++ b/notes.h
@@ -0,0 +1,9 @@
+#ifndef NOTES_H
+#define NOTES_H
+
+void get_commit_notes(const struct commit *commit,
+	char **buf_p, unsigned long *offset_p, unsigned long *space_p);
+
+#define GIT_NOTES_REF "GIT_NOTES_REF"
+
+#endif

-- 
1.5.3.rc1.2718.gd2dc9-dirty
Previous: Johannes SchindelinNext: Junio C Hamano
Message 3 of 42 in “Introduce commit notes”
  1. 0/6 Introduce commit notesJohannes Schindelin, Jul 15, 2007
  2. 1/6 Rename git_one_line() to git_line_length() and export itJohannes Schindelin, Jul 15, 2007
  3. 2/6 Introduce commit notesJohannes Schindelin, Jul 15, 2007
  4. Junio C HamanoJul 15, 2007
  5. Johannes SchindelinJul 15, 2007
  6. Junio C HamanoJul 16, 2007
  7. Junio C HamanoJul 16, 2007
  8. 2/6 Introduce commit notesJohannes Schindelin, Jul 19, 2007
  9. Linus TorvaldsJul 19, 2007
  10. Junio C HamanoJul 19, 2007
  11. Junio C HamanoJul 19, 2007
  12. Adam HayekJul 19, 2007
  13. Andy ParkinsJul 19, 2007
  14. Johannes SchindelinJul 19, 2007
  15. Andy ParkinsJul 19, 2007
  16. Linus TorvaldsJul 19, 2007
  17. Junio C HamanoJul 20, 2007
  18. Shawn O. PearceJul 20, 2007
  19. Linus TorvaldsJul 19, 2007
  20. Johannes SchindelinJul 19, 2007
  21. Olivier GalibertJul 19, 2007
  22. Linus TorvaldsJul 19, 2007
  23. Wincent ColaiutaJul 19, 2007
  24. Johannes SchindelinJul 19, 2007
  25. Sven VerdoolaegeJul 19, 2007
  26. 3/6 Add git-notesJohannes Schindelin, Jul 15, 2007
  27. Junio C HamanoJul 16, 2007
  28. 3/6 Add git-notesJohannes Schindelin, Jul 19, 2007
  29. Johannes SchindelinJul 19, 2007
  30. 4/6 Add a test script for "git notes"Johannes Schindelin, Jul 15, 2007
  31. Junio C HamanoJul 16, 2007
  32. 4/6 Add a test script for "git notes"Johannes Schindelin, Jul 19, 2007
  33. 5/6 Document git-notesJohannes Schindelin, Jul 15, 2007
  34. 6/6 notes: add notes-index for a substantial speedup.Johannes Schindelin, Jul 15, 2007
  35. Johannes SchindelinJul 15, 2007
  36. Shawn O. PearceJul 16, 2007
  37. Johannes SchindelinJul 16, 2007
  38. Andy ParkinsJul 16, 2007
  39. Junio C HamanoJul 16, 2007
  40. Johannes SchindelinJul 16, 2007
  41. Junio C HamanoJul 16, 2007
  42. Johannes SchindelinJul 19, 2007

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.