]>
Commit | Line | Data |
---|---|---|
65d9fb48 JS |
1 | git-notes(1) |
2 | ============ | |
3 | ||
4 | NAME | |
5 | ---- | |
7d541174 | 6 | git-notes - Add/inspect object notes |
65d9fb48 JS |
7 | |
8 | SYNOPSIS | |
9 | -------- | |
10 | [verse] | |
e397421a | 11 | 'git notes' [list [<object>]] |
0691cff7 | 12 | 'git notes' add [-f] [-F <file> | -m <msg> | (-c | -C) <object>] [<object>] |
160baa0d | 13 | 'git notes' copy [-f] ( --stdin | <from-object> <to-object> ) |
0691cff7 | 14 | 'git notes' append [-F <file> | -m <msg> | (-c | -C) <object>] [<object>] |
aaec9bcf | 15 | 'git notes' edit [<object>] |
e397421a JH |
16 | 'git notes' show [<object>] |
17 | 'git notes' remove [<object>] | |
18 | 'git notes' prune | |
19 | ||
65d9fb48 JS |
20 | |
21 | DESCRIPTION | |
22 | ----------- | |
7d541174 JH |
23 | This command allows you to add/remove notes to/from objects, without |
24 | changing the objects themselves. | |
65d9fb48 | 25 | |
7d541174 JH |
26 | A typical use of notes is to extend a commit message without having |
27 | to change the commit itself. Such commit notes can be shown by `git log` | |
28 | along with the original commit message. To discern these notes from the | |
29 | message stored in the commit object, the notes are indented like the | |
894a9d33 | 30 | message, after an unindented line saying "Notes (<refname>):" (or |
9eb3f816 | 31 | "Notes:" for `refs/notes/commits`). |
7d541174 | 32 | |
894a9d33 TR |
33 | This command always manipulates the notes specified in "core.notesRef" |
34 | (see linkgit:git-config[1]), which can be overridden by GIT_NOTES_REF. | |
35 | To change which notes are shown by 'git-log', see the | |
36 | "notes.displayRef" configuration. | |
65d9fb48 | 37 | |
6956f858 TR |
38 | See the description of "notes.rewrite.<command>" in |
39 | linkgit:git-config[1] for a way of carrying your notes across commands | |
40 | that rewrite commits. | |
65d9fb48 JS |
41 | |
42 | ||
43 | SUBCOMMANDS | |
44 | ----------- | |
45 | ||
e397421a JH |
46 | list:: |
47 | List the notes object for a given object. If no object is | |
48 | given, show a list of all note objects and the objects they | |
49 | annotate (in the format "<note object> <annotated object>"). | |
50 | This is the default subcommand if no subcommand is given. | |
51 | ||
7aa4754e JH |
52 | add:: |
53 | Add notes for a given object (defaults to HEAD). Abort if the | |
48716a23 | 54 | object already has notes (use `-f` to overwrite an |
7aa4754e JH |
55 | existing note). |
56 | ||
e73bbd96 JH |
57 | copy:: |
58 | Copy the notes for the first object onto the second object. | |
59 | Abort if the second object already has notes, or if the first | |
48716a23 | 60 | object has none (use -f to overwrite existing notes to the |
e73bbd96 JH |
61 | second object). This subcommand is equivalent to: |
62 | `git notes add [-f] -C $(git notes list <from-object>) <to-object>` | |
160baa0d TR |
63 | + |
64 | In `\--stdin` mode, take lines in the format | |
65 | + | |
66 | ---------- | |
67 | <from-object> SP <to-object> [ SP <rest> ] LF | |
68 | ---------- | |
69 | + | |
70 | on standard input, and copy the notes from each <from-object> to its | |
71 | corresponding <to-object>. (The optional `<rest>` is ignored so that | |
72 | the command can read the input given to the `post-rewrite` hook.) | |
e73bbd96 | 73 | |
2347fae5 JH |
74 | append:: |
75 | Append to the notes of an existing object (defaults to HEAD). | |
76 | Creates a new notes object if needed. | |
77 | ||
65d9fb48 | 78 | edit:: |
7d541174 | 79 | Edit the notes for a given object (defaults to HEAD). |
65d9fb48 JS |
80 | |
81 | show:: | |
7d541174 | 82 | Show the notes for a given object (defaults to HEAD). |
65d9fb48 | 83 | |
92b3385f | 84 | remove:: |
7d541174 | 85 | Remove the notes for a given object (defaults to HEAD). |
92b3385f JH |
86 | This is equivalent to specifying an empty note message to |
87 | the `edit` subcommand. | |
88 | ||
d6576e1f JH |
89 | prune:: |
90 | Remove all notes for non-existing/unreachable objects. | |
65d9fb48 | 91 | |
d9246d43 JH |
92 | OPTIONS |
93 | ------- | |
7aa4754e JH |
94 | -f:: |
95 | --force:: | |
96 | When adding notes to an object that already has notes, | |
97 | overwrite the existing notes (instead of aborting). | |
98 | ||
d9246d43 | 99 | -m <msg>:: |
ba20f15e | 100 | --message=<msg>:: |
d9246d43 | 101 | Use the given note message (instead of prompting). |
cd067d3b JH |
102 | If multiple `-m` options are given, their values |
103 | are concatenated as separate paragraphs. | |
8d6888ec JN |
104 | Lines starting with `#` and empty lines other than a |
105 | single line between paragraphs will be stripped out. | |
d9246d43 JH |
106 | |
107 | -F <file>:: | |
ba20f15e | 108 | --file=<file>:: |
d9246d43 JH |
109 | Take the note message from the given file. Use '-' to |
110 | read the note message from the standard input. | |
8d6888ec JN |
111 | Lines starting with `#` and empty lines other than a |
112 | single line between paragraphs will be stripped out. | |
d9246d43 | 113 | |
0691cff7 JH |
114 | -C <object>:: |
115 | --reuse-message=<object>:: | |
8d6888ec JN |
116 | Take the note message from the given blob object (for |
117 | example, another note). | |
0691cff7 JH |
118 | |
119 | -c <object>:: | |
120 | --reedit-message=<object>:: | |
121 | Like '-C', but with '-c' the editor is invoked, so that | |
122 | the user can further edit the note message. | |
d9246d43 | 123 | |
dcf783a2 TR |
124 | --ref <ref>:: |
125 | Manipulate the notes tree in <ref>. This overrides both | |
126 | GIT_NOTES_REF and the "core.notesRef" configuration. The ref | |
127 | is taken to be in `refs/notes/` if it is not qualified. | |
128 | ||
66d68199 | 129 | |
9eb3f816 JN |
130 | DISCUSSION |
131 | ---------- | |
132 | ||
133 | Commit notes are blobs containing extra information about an object | |
134 | (usually information to supplement a commit's message). These blobs | |
135 | are taken from notes refs. A notes ref is usually a branch which | |
136 | contains "files" whose paths are the object names for the objects | |
137 | they describe, with some directory separators included for performance | |
138 | reasons footnote:[Permitted pathnames have the form | |
139 | 'ab'`/`'cd'`/`'ef'`/`'...'`/`'abcdef...': a sequence of directory | |
140 | names of two hexadecimal digits each followed by a filename with the | |
141 | rest of the object ID.]. | |
66d68199 TR |
142 | |
143 | Every notes change creates a new commit at the specified notes ref. | |
144 | You can therefore inspect the history of the notes by invoking, e.g., | |
9eb3f816 JN |
145 | `git log -p notes/commits`. Currently the commit message only records |
146 | which operation triggered the update, and the commit authorship is | |
147 | determined according to the usual rules (see linkgit:git-commit[1]). | |
148 | These details may change in the future. | |
149 | ||
150 | It is also permitted for a notes ref to point directly to a tree | |
151 | object, in which case the history of the notes can be read with | |
152 | `git log -p -g <refname>`. | |
66d68199 TR |
153 | |
154 | ||
8d6888ec JN |
155 | EXAMPLES |
156 | -------- | |
157 | ||
158 | You can use notes to add annotations with information that was not | |
159 | available at the time a commit was written. | |
160 | ||
161 | ------------ | |
162 | $ git notes add -m 'Tested-by: Johannes Sixt <j6t@kdbg.org>' 72a144e2 | |
163 | $ git show -s 72a144e | |
164 | [...] | |
165 | Signed-off-by: Junio C Hamano <gitster@pobox.com> | |
166 | ||
167 | Notes: | |
168 | Tested-by: Johannes Sixt <j6t@kdbg.org> | |
169 | ------------ | |
170 | ||
171 | In principle, a note is a regular Git blob, and any kind of | |
172 | (non-)format is accepted. You can binary-safely create notes from | |
173 | arbitrary files using 'git hash-object': | |
174 | ||
175 | ------------ | |
176 | $ cc *.c | |
177 | $ blob=$(git hash-object -w a.out) | |
178 | $ git notes --ref=built add -C "$blob" HEAD | |
179 | ------------ | |
180 | ||
181 | Of course, it doesn't make much sense to display non-text-format notes | |
182 | with 'git log', so if you use such notes, you'll probably need to write | |
183 | some special-purpose tools to do something useful with them. | |
184 | ||
185 | ||
65d9fb48 JS |
186 | Author |
187 | ------ | |
7d541174 JH |
188 | Written by Johannes Schindelin <johannes.schindelin@gmx.de> and |
189 | Johan Herland <johan@herland.net> | |
65d9fb48 JS |
190 | |
191 | Documentation | |
192 | ------------- | |
7d541174 | 193 | Documentation by Johannes Schindelin and Johan Herland |
65d9fb48 JS |
194 | |
195 | GIT | |
196 | --- | |
197 | Part of the linkgit:git[7] suite |