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.
390 lines
13 KiB
390 lines
13 KiB
git-notes(1) |
|
============ |
|
|
|
NAME |
|
---- |
|
git-notes - Add or 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' merge [-v | -q] [-s <strategy> ] <notes_ref> |
|
'git notes' merge --commit [-v | -q] |
|
'git notes' merge --abort [-v | -q] |
|
'git notes' remove [--ignore-missing] [--stdin] [<object>...] |
|
'git notes' prune [-n | -v] |
|
'git notes' get-ref |
|
|
|
|
|
DESCRIPTION |
|
----------- |
|
Adds, removes, or reads notes attached to objects, without touching |
|
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 supplement a commit message without |
|
changing the commit itself. Notes can be shown by 'git log' along with |
|
the original commit message. To distinguish 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`). |
|
|
|
Notes can also be added to patches prepared with `git format-patch` by |
|
using the `--notes` option. Such notes are added as a patch commentary |
|
after a three dash separator line. |
|
|
|
To change which notes are shown by 'git log', see the |
|
"notes.displayRef" configuration in linkgit:git-log[1]. |
|
|
|
See the "notes.rewrite.<command>" configuration for a way to carry |
|
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 existing notes). |
|
However, if you're using `add` interactively (using an editor |
|
to supply the notes contents), then - instead of aborting - |
|
the existing notes will be opened in the editor (like the `edit` |
|
subcommand). |
|
|
|
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). |
|
|
|
merge:: |
|
Merge the given notes ref into the current notes ref. |
|
This will try to merge the changes made by the given |
|
notes ref (called "remote") since the merge-base (if |
|
any) into the current notes ref (called "local"). |
|
+ |
|
If conflicts arise and a strategy for automatically resolving |
|
conflicting notes (see the -s/--strategy option) is not given, |
|
the "manual" resolver is used. This resolver checks out the |
|
conflicting notes in a special worktree (`.git/NOTES_MERGE_WORKTREE`), |
|
and instructs the user to manually resolve the conflicts there. |
|
When done, the user can either finalize the merge with |
|
'git notes merge --commit', or abort the merge with |
|
'git notes merge --abort'. |
|
|
|
remove:: |
|
Remove the notes for given objects (defaults to HEAD). When |
|
giving zero or one object from the command line, this is |
|
equivalent to specifying an empty note message to |
|
the `edit` subcommand. |
|
|
|
prune:: |
|
Remove all notes for non-existing/unreachable objects. |
|
|
|
get-ref:: |
|
Print the current notes ref. This provides an easy way to |
|
retrieve the current notes ref (e.g. from scripts). |
|
|
|
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 given blob object (for example, another note) as the |
|
note message. (Use `git notes copy <object>` instead to |
|
copy notes between objects.) |
|
|
|
-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. |
|
|
|
--ignore-missing:: |
|
Do not consider it an error to request removing notes from an |
|
object that does not have notes attached to it. |
|
|
|
--stdin:: |
|
Also read the object names to remove notes from from the standard |
|
input (there is no reason you cannot combine this with object |
|
names from the command line). |
|
|
|
-n:: |
|
--dry-run:: |
|
Do not remove anything; just report the object names whose notes |
|
would be removed. |
|
|
|
-s <strategy>:: |
|
--strategy=<strategy>:: |
|
When merging notes, resolve notes conflicts using the given |
|
strategy. The following strategies are recognized: "manual" |
|
(default), "ours", "theirs", "union" and "cat_sort_uniq". |
|
See the "NOTES MERGE STRATEGIES" section below for more |
|
information on each notes merge strategy. |
|
|
|
--commit:: |
|
Finalize an in-progress 'git notes merge'. Use this option |
|
when you have resolved the conflicts that 'git notes merge' |
|
stored in .git/NOTES_MERGE_WORKTREE. This amends the partial |
|
merge commit created by 'git notes merge' (stored in |
|
.git/NOTES_MERGE_PARTIAL) by adding the notes in |
|
.git/NOTES_MERGE_WORKTREE. The notes ref stored in the |
|
.git/NOTES_MERGE_REF symref is updated to the resulting commit. |
|
|
|
--abort:: |
|
Abort/reset a in-progress 'git notes merge', i.e. a notes merge |
|
with conflicts. This simply removes all files related to the |
|
notes merge. |
|
|
|
-q:: |
|
--quiet:: |
|
When merging notes, operate quietly. |
|
|
|
-v:: |
|
--verbose:: |
|
When merging notes, be more verbose. |
|
When pruning notes, report all object names whose notes are |
|
removed. |
|
|
|
|
|
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>`. |
|
|
|
|
|
NOTES MERGE STRATEGIES |
|
---------------------- |
|
|
|
The default notes merge strategy is "manual", which checks out |
|
conflicting notes in a special work tree for resolving notes conflicts |
|
(`.git/NOTES_MERGE_WORKTREE`), and instructs the user to resolve the |
|
conflicts in that work tree. |
|
When done, the user can either finalize the merge with |
|
'git notes merge --commit', or abort the merge with |
|
'git notes merge --abort'. |
|
|
|
"ours" automatically resolves conflicting notes in favor of the local |
|
version (i.e. the current notes ref). |
|
|
|
"theirs" automatically resolves notes conflicts in favor of the remote |
|
version (i.e. the given notes ref being merged into the current notes |
|
ref). |
|
|
|
"union" automatically resolves notes conflicts by concatenating the |
|
local and remote versions. |
|
|
|
"cat_sort_uniq" is similar to "union", but in addition to concatenating |
|
the local and remote versions, this strategy also sorts the resulting |
|
lines, and removes duplicate lines from the result. This is equivalent |
|
to applying the "cat | sort | uniq" shell pipeline to the local and |
|
remote versions. This strategy is useful if the notes follow a line-based |
|
format where one wants to avoid duplicated lines in the merge result. |
|
Note that if either the local or remote version contain duplicate lines |
|
prior to the merge, these will also be removed by this notes merge |
|
strategy. |
|
|
|
|
|
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 |
|
------------ |
|
|
|
(You cannot simply use `git notes --ref=built add -F a.out HEAD` |
|
because that is not binary-safe.) |
|
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:: |
|
Which ref (or refs, if a glob or specified more than once), in |
|
addition to the default set by `core.notesRef` or |
|
'GIT_NOTES_REF', to read notes from when showing commit |
|
messages with the 'git log' family of commands. |
|
This setting can be overridden on the command line or by the |
|
'GIT_NOTES_DISPLAY_REF' environment variable. |
|
See linkgit:git-log[1]. |
|
|
|
notes.rewrite.<command>:: |
|
When rewriting commits with <command> (currently `amend` or |
|
`rebase`), if this variable is `false`, git will not copy |
|
notes from the original to the rewritten commit. Defaults to |
|
`true`. See also "`notes.rewriteRef`" below. |
|
+ |
|
This setting can be overridden by the 'GIT_NOTES_REWRITE_REF' |
|
environment variable. |
|
|
|
notes.rewriteMode:: |
|
When copying notes during a rewrite, what to do if the target |
|
commit already has a note. Must be one of `overwrite`, |
|
`concatenate`, and `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. 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. |
|
+ |
|
Can be overridden with the 'GIT_NOTES_REWRITE_REF' environment variable. |
|
|
|
|
|
ENVIRONMENT |
|
----------- |
|
|
|
'GIT_NOTES_REF':: |
|
Which ref to manipulate notes from, instead of `refs/notes/commits`. |
|
This overrides the `core.notesRef` setting. |
|
|
|
'GIT_NOTES_DISPLAY_REF':: |
|
Colon-delimited list of refs or globs indicating which refs, |
|
in addition to the default from `core.notesRef` or |
|
'GIT_NOTES_REF', to read notes from when showing commit |
|
messages. |
|
This overrides the `notes.displayRef` setting. |
|
+ |
|
A warning will be issued for refs that do not exist, but a glob that |
|
does not match any refs is silently ignored. |
|
|
|
'GIT_NOTES_REWRITE_MODE':: |
|
When copying notes during a rewrite, what to do if the target |
|
commit already has a note. |
|
Must be one of `overwrite`, `concatenate`, and `ignore`. |
|
This overrides the `core.rewriteMode` setting. |
|
|
|
'GIT_NOTES_REWRITE_REF':: |
|
When rewriting commits, which notes to copy from the original |
|
to the rewritten commit. Must be a colon-delimited list of |
|
refs or globs. |
|
+ |
|
If not set in the environment, the list of notes to copy depends |
|
on the `notes.rewrite.<command>` and `notes.rewriteRef` settings. |
|
|
|
|
|
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
|
|
|