66d6819984
To the displaying code, the only interesting thing about a notes ref is that it has a tree of the required format. However, notes actually have a history since they are recorded as successive commits. Make a note about the existence of this history in the manpage, but keep some doors open if we want to change the details. Signed-off-by: Thomas Rast <trast@student.ethz.ch> Acked-by: Johan Herland <johan@herland.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
150 lines
4.3 KiB
Plaintext
150 lines
4.3 KiB
Plaintext
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.
|
|
|
|
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 the default setting).
|
|
|
|
This command always manipulates the notes specified in "core.notesRef"
|
|
(see linkgit:git-config[1]), which can be overridden by GIT_NOTES_REF.
|
|
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, abort. (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
|
|
objects 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.
|
|
|
|
-F <file>::
|
|
--file=<file>::
|
|
Take the note message from the given file. Use '-' to
|
|
read the note message from the standard input.
|
|
|
|
-C <object>::
|
|
--reuse-message=<object>::
|
|
Reuse the note message from the given note object.
|
|
|
|
-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 both
|
|
GIT_NOTES_REF and the "core.notesRef" configuration. The ref
|
|
is taken to be in `refs/notes/` if it is not qualified.
|
|
|
|
|
|
NOTES
|
|
-----
|
|
|
|
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.
|
|
|
|
|
|
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
|