You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
265 lines
8.3 KiB
265 lines
8.3 KiB
git-notes(1) |
|
============ |
|
|
|
NAME |
|
---- |
|
git-notes - Add/inspect object notes |
|
|
|
SYNOPSIS |
|
-------- |
|
[verse] |
|
'git notes' [list [<object>]] |
|
'git notes' add [-f] [-F <file> | -m <msg> | (-c | -C) <object>] [<object>] |
|
'git notes' copy [-f] ( --stdin | <from-object> <to-object> ) |
|
'git notes' append [-F <file> | -m <msg> | (-c | -C) <object>] [<object>] |
|
'git notes' edit [<object>] |
|
'git notes' show [<object>] |
|
'git notes' remove [<object>] |
|
'git notes' prune |
|
|
|
|
|
DESCRIPTION |
|
----------- |
|
This command allows you to add/remove notes to/from objects, without |
|
changing the objects themselves. |
|
|
|
By default, notes are saved to and read from `refs/notes/commits`, but |
|
this default can be overridden. See the OPTIONS, CONFIGURATION, and |
|
ENVIRONMENT sections below. If this ref does not exist, it will be |
|
quietly created when it is first needed to store a note. |
|
|
|
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 (<refname>):" (or |
|
"Notes:" for `refs/notes/commits`). |
|
|
|
To change which notes are shown by 'git-log', see the |
|
"notes.displayRef" configuration. |
|
|
|
See the description of "notes.rewrite.<command>" in |
|
linkgit:git-config[1] for a way of carrying your notes across commands |
|
that rewrite commits. |
|
|
|
|
|
SUBCOMMANDS |
|
----------- |
|
|
|
list:: |
|
List the notes object for a given object. If no object is |
|
given, show a list of all note objects and the objects they |
|
annotate (in the format "<note object> <annotated object>"). |
|
This is the default subcommand if no subcommand is given. |
|
|
|
add:: |
|
Add notes for a given object (defaults to HEAD). Abort if the |
|
object already has notes (use `-f` to overwrite an |
|
existing note). |
|
|
|
copy:: |
|
Copy the notes for the first object onto the second object. |
|
Abort if the second object already has notes, or if the first |
|
object has none (use -f to overwrite existing notes to the |
|
second object). This subcommand is equivalent to: |
|
`git notes add [-f] -C $(git notes list <from-object>) <to-object>` |
|
+ |
|
In `\--stdin` mode, take lines in the format |
|
+ |
|
---------- |
|
<from-object> SP <to-object> [ SP <rest> ] LF |
|
---------- |
|
+ |
|
on standard input, and copy the notes from each <from-object> to its |
|
corresponding <to-object>. (The optional `<rest>` is ignored so that |
|
the command can read the input given to the `post-rewrite` hook.) |
|
|
|
append:: |
|
Append to the notes of an existing object (defaults to HEAD). |
|
Creates a new notes object if needed. |
|
|
|
edit:: |
|
Edit the notes for a given object (defaults to HEAD). |
|
|
|
show:: |
|
Show the notes for a given object (defaults to HEAD). |
|
|
|
remove:: |
|
Remove the notes for a given object (defaults to HEAD). |
|
This is equivalent to specifying an empty note message to |
|
the `edit` subcommand. |
|
|
|
prune:: |
|
Remove all notes for non-existing/unreachable objects. |
|
|
|
OPTIONS |
|
------- |
|
-f:: |
|
--force:: |
|
When adding notes to an object that already has notes, |
|
overwrite the existing notes (instead of aborting). |
|
|
|
-m <msg>:: |
|
--message=<msg>:: |
|
Use the given note message (instead of prompting). |
|
If multiple `-m` options are given, their values |
|
are concatenated as separate paragraphs. |
|
Lines starting with `#` and empty lines other than a |
|
single line between paragraphs will be stripped out. |
|
|
|
-F <file>:: |
|
--file=<file>:: |
|
Take the note message from the given file. Use '-' to |
|
read the note message from the standard input. |
|
Lines starting with `#` and empty lines other than a |
|
single line between paragraphs will be stripped out. |
|
|
|
-C <object>:: |
|
--reuse-message=<object>:: |
|
Take the note message from the given blob object (for |
|
example, another note). |
|
|
|
-c <object>:: |
|
--reedit-message=<object>:: |
|
Like '-C', but with '-c' the editor is invoked, so that |
|
the user can further edit the note message. |
|
|
|
--ref <ref>:: |
|
Manipulate the notes tree in <ref>. This overrides |
|
'GIT_NOTES_REF' and the "core.notesRef" configuration. The ref |
|
is taken to be in `refs/notes/` if it is not qualified. |
|
|
|
|
|
DISCUSSION |
|
---------- |
|
|
|
Commit notes are blobs containing extra information about an object |
|
(usually information to supplement a commit's message). These blobs |
|
are taken from notes refs. A notes ref is usually a branch which |
|
contains "files" whose paths are the object names for the objects |
|
they describe, with some directory separators included for performance |
|
reasons footnote:[Permitted pathnames have the form |
|
'ab'`/`'cd'`/`'ef'`/`'...'`/`'abcdef...': a sequence of directory |
|
names of two hexadecimal digits each followed by a filename with the |
|
rest of the object ID.]. |
|
|
|
Every notes change creates a new commit at the specified notes ref. |
|
You can therefore inspect the history of the notes by invoking, e.g., |
|
`git log -p notes/commits`. Currently the commit message only records |
|
which operation triggered the update, and the commit authorship is |
|
determined according to the usual rules (see linkgit:git-commit[1]). |
|
These details may change in the future. |
|
|
|
It is also permitted for a notes ref to point directly to a tree |
|
object, in which case the history of the notes can be read with |
|
`git log -p -g <refname>`. |
|
|
|
|
|
EXAMPLES |
|
-------- |
|
|
|
You can use notes to add annotations with information that was not |
|
available at the time a commit was written. |
|
|
|
------------ |
|
$ git notes add -m 'Tested-by: Johannes Sixt <j6t@kdbg.org>' 72a144e2 |
|
$ git show -s 72a144e |
|
[...] |
|
Signed-off-by: Junio C Hamano <gitster@pobox.com> |
|
|
|
Notes: |
|
Tested-by: Johannes Sixt <j6t@kdbg.org> |
|
------------ |
|
|
|
In principle, a note is a regular Git blob, and any kind of |
|
(non-)format is accepted. You can binary-safely create notes from |
|
arbitrary files using 'git hash-object': |
|
|
|
------------ |
|
$ cc *.c |
|
$ blob=$(git hash-object -w a.out) |
|
$ git notes --ref=built add -C "$blob" HEAD |
|
------------ |
|
|
|
Of course, it doesn't make much sense to display non-text-format notes |
|
with 'git log', so if you use such notes, you'll probably need to write |
|
some special-purpose tools to do something useful with them. |
|
|
|
|
|
CONFIGURATION |
|
------------- |
|
|
|
core.notesRef:: |
|
Notes ref to read and manipulate instead of |
|
`refs/notes/commits`. Must be an unabbreviated ref name. |
|
This setting can be overridden through the environment and |
|
command line. |
|
|
|
notes.displayRef:: |
|
The (fully qualified) refname from which to show notes when |
|
showing commit messages. The value of this variable can be set |
|
to a glob, in which case notes from all matching refs will be |
|
shown. You may also specify this configuration variable |
|
several times. A warning will be issued for refs that do not |
|
exist, but a glob that does not match any refs is silently |
|
ignored. |
|
+ |
|
This setting can be overridden with the `GIT_NOTES_DISPLAY_REF` |
|
environment variable, which must be a colon separated list of refs or |
|
globs. |
|
+ |
|
The effective value of "core.notesRef" (possibly overridden by |
|
GIT_NOTES_REF) is also implicitly added to the list of refs to be |
|
displayed. |
|
|
|
notes.rewrite.<command>:: |
|
When rewriting commits with <command> (currently `amend` or |
|
`rebase`) and this variable is set to `true`, git |
|
automatically copies your notes from the original to the |
|
rewritten commit. Defaults to `true`, but see |
|
"notes.rewriteRef" below. |
|
|
|
notes.rewriteMode:: |
|
When copying notes during a rewrite (see the |
|
"notes.rewrite.<command>" option), determines what to do if |
|
the target commit already has a note. Must be one of |
|
`overwrite`, `concatenate`, or `ignore`. Defaults to |
|
`concatenate`. |
|
+ |
|
This setting can be overridden with the `GIT_NOTES_REWRITE_MODE` |
|
environment variable. |
|
|
|
notes.rewriteRef:: |
|
When copying notes during a rewrite, specifies the (fully |
|
qualified) ref whose notes should be copied. The ref may be a |
|
glob, in which case notes in all matching refs will be copied. |
|
You may also specify this configuration several times. |
|
+ |
|
Does not have a default value; you must configure this variable to |
|
enable note rewriting. |
|
+ |
|
This setting can be overridden with the `GIT_NOTES_REWRITE_REF` |
|
environment variable, which must be a colon separated list of refs or |
|
globs. |
|
|
|
|
|
ENVIRONMENT |
|
----------- |
|
|
|
'GIT_NOTES_REF':: |
|
Which ref to manipulate notes from, instead of `refs/notes/commits`. |
|
This overrides the `core.notesRef` setting. |
|
|
|
|
|
Author |
|
------ |
|
Written by Johannes Schindelin <johannes.schindelin@gmx.de> and |
|
Johan Herland <johan@herland.net> |
|
|
|
Documentation |
|
------------- |
|
Documentation by Johannes Schindelin and Johan Herland |
|
|
|
GIT |
|
--- |
|
Part of the linkgit:git[7] suite
|
|
|