From 7d541174650fb209a00b629d113cb954c24a19de Mon Sep 17 00:00:00 2001 From: Johan Herland Date: Sat, 13 Feb 2010 22:28:29 +0100 Subject: [PATCH] Documentation: Generalize git-notes docs to 'objects' instead of 'commits' Notes can annotate arbitrary objects (not only commits), but this is not reflected in the current documentation. This patch rewrites the git-notes documentation to talk about 'objects' instead of 'commits'. However, the discussion on commit notes and how they are displayed by 'git log' is largely preserved. Finally, I add myself to the Author/Documentation credits, since most of the lines in the git-notes code and docs are blamed on me. Cc: Johannes Schindelin Signed-off-by: Johan Herland Signed-off-by: Junio C Hamano --- Documentation/git-notes.txt | 35 ++++++++++++++++++++--------------- 1 file changed, 20 insertions(+), 15 deletions(-) diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt index 3973f9026..84db2a467 100644 --- a/Documentation/git-notes.txt +++ b/Documentation/git-notes.txt @@ -3,37 +3,41 @@ git-notes(1) NAME ---- -git-notes - Add/inspect commit notes +git-notes - Add/inspect object notes SYNOPSIS -------- [verse] -'git notes' (edit [-F | -m ] | show | remove | prune) [commit] +'git notes' (edit [-F | -m ] | show | remove | prune) [object] DESCRIPTION ----------- -This command allows you to add/remove notes to/from commit messages, -without changing the commit. To discern these notes from the message -stored in the commit object, the notes are indented like the message, -after an unindented line saying "Notes:". +This command allows you to add/remove notes to/from objects, without +changing the objects themselves. -To disable commit notes, you have to set the config variable -core.notesRef to the empty string. Alternatively, you can set it -to a different ref, something like "refs/notes/bugzilla". This setting -can be overridden by the environment variable "GIT_NOTES_REF". +A typical use of notes is to extend a commit message without having +to change the commit itself. Such commit notes can be shown by `git log` +along with the original commit message. To discern these notes from the +message stored in the commit object, the notes are indented like the +message, after an unindented line saying "Notes:". + +To disable notes, you have to set the config variable core.notesRef to +the empty string. Alternatively, you can set it to a different ref, +something like "refs/notes/bugzilla". This setting can be overridden +by the environment variable "GIT_NOTES_REF". SUBCOMMANDS ----------- edit:: - Edit the notes for a given commit (defaults to HEAD). + Edit the notes for a given object (defaults to HEAD). show:: - Show the notes for a given commit (defaults to HEAD). + Show the notes for a given object (defaults to HEAD). remove:: - Remove the notes for a given commit (defaults to HEAD). + Remove the notes for a given object (defaults to HEAD). This is equivalent to specifying an empty note message to the `edit` subcommand. @@ -54,11 +58,12 @@ OPTIONS Author ------ -Written by Johannes Schindelin +Written by Johannes Schindelin and +Johan Herland Documentation ------------- -Documentation by Johannes Schindelin +Documentation by Johannes Schindelin and Johan Herland GIT --- -- 2.30.2