2009-10-09 10:21:58 +00:00
|
|
|
git-notes(1)
|
|
|
|
============
|
|
|
|
|
|
|
|
NAME
|
|
|
|
----
|
2010-05-09 03:37:21 +00:00
|
|
|
git-notes - Add or inspect object notes
|
2009-10-09 10:21:58 +00:00
|
|
|
|
|
|
|
SYNOPSIS
|
|
|
|
--------
|
|
|
|
[verse]
|
2010-02-13 21:28:30 +00:00
|
|
|
'git notes' [list [<object>]]
|
2014-11-12 00:40:14 +00:00
|
|
|
'git notes' add [-f] [--allow-empty] [-F <file> | -m <msg> | (-c | -C) <object>] [<object>]
|
2010-03-12 17:04:31 +00:00
|
|
|
'git notes' copy [-f] ( --stdin | <from-object> <to-object> )
|
2014-11-12 00:40:14 +00:00
|
|
|
'git notes' append [--allow-empty] [-F <file> | -m <msg> | (-c | -C) <object>] [<object>]
|
|
|
|
'git notes' edit [--allow-empty] [<object>]
|
2010-02-13 21:28:30 +00:00
|
|
|
'git notes' show [<object>]
|
2014-03-23 22:58:12 +00:00
|
|
|
'git notes' merge [-v | -q] [-s <strategy> ] <notes-ref>
|
git notes merge: Manual conflict resolution, part 2/2
When the notes merge conflicts in .git/NOTES_MERGE_WORKTREE have been
resolved, we need to record a new notes commit on the appropriate notes
ref with the resolved notes.
This patch implements 'git notes merge --commit' which the user should
run after resolving conflicts in the notes merge worktree. This command
finalizes the notes merge by recombining the partial notes tree from
part 1 with the now-resolved conflicts in the notes merge worktree in a
merge commit, and updating the appropriate ref to this merge commit.
In order to correctly finalize the merge, we need to keep track of three
things:
- The partial merge result from part 1, containing the auto-merged notes.
This is now stored into a ref called .git/NOTES_MERGE_PARTIAL.
- The unmerged notes. These are already stored in
.git/NOTES_MERGE_WORKTREE, thanks to part 1.
- The notes ref to be updated by the finalized merge result. This is now
stored in a symref called .git/NOTES_MERGE_REF.
In addition to "git notes merge --commit", which uses the above details
to create the finalized notes merge commit, this patch also implements
"git notes merge --reset", which aborts the ongoing notes merge by simply
removing the files/directory described above.
FTR, "git notes merge --commit" reuses "git notes merge --reset" to remove
the information described above (.git/NOTES_MERGE_*) after the notes merge
have been successfully finalized.
The patch also contains documentation and testcases for the two new options.
This patch has been improved by the following contributions:
- Ævar Arnfjörð Bjarmason: Fix nonsense sentence in --commit description
- Sverre Rabbelier: Rename --reset to --abort
Thanks-to: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Thanks-to: Sverre Rabbelier <srabbelier@gmail.com>
Signed-off-by: Johan Herland <johan@herland.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-11-09 21:49:52 +00:00
|
|
|
'git notes' merge --commit [-v | -q]
|
|
|
|
'git notes' merge --abort [-v | -q]
|
2011-05-18 23:44:30 +00:00
|
|
|
'git notes' remove [--ignore-missing] [--stdin] [<object>...]
|
2017-11-21 19:17:21 +00:00
|
|
|
'git notes' prune [-n] [-v]
|
2010-11-09 21:49:57 +00:00
|
|
|
'git notes' get-ref
|
2010-02-13 21:28:30 +00:00
|
|
|
|
2009-10-09 10:21:58 +00:00
|
|
|
|
|
|
|
DESCRIPTION
|
|
|
|
-----------
|
2010-05-09 03:37:21 +00:00
|
|
|
Adds, removes, or reads notes attached to objects, without touching
|
|
|
|
the objects themselves.
|
2009-10-09 10:21:58 +00:00
|
|
|
|
2010-05-09 03:23:58 +00:00
|
|
|
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.
|
|
|
|
|
2010-05-09 03:37:21 +00:00
|
|
|
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
|
2010-02-13 21:28:29 +00:00
|
|
|
message stored in the commit object, the notes are indented like the
|
2010-03-12 17:04:26 +00:00
|
|
|
message, after an unindented line saying "Notes (<refname>):" (or
|
2010-05-09 03:19:35 +00:00
|
|
|
"Notes:" for `refs/notes/commits`).
|
2010-02-13 21:28:29 +00:00
|
|
|
|
2012-10-21 21:34:09 +00:00
|
|
|
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.
|
|
|
|
|
2010-05-09 03:32:24 +00:00
|
|
|
To change which notes are shown by 'git log', see the
|
|
|
|
"notes.displayRef" configuration in linkgit:git-log[1].
|
2009-10-09 10:21:58 +00:00
|
|
|
|
2010-05-09 03:33:28 +00:00
|
|
|
See the "notes.rewrite.<command>" configuration for a way to carry
|
|
|
|
notes across commands that rewrite commits.
|
2009-10-09 10:21:58 +00:00
|
|
|
|
|
|
|
|
|
|
|
SUBCOMMANDS
|
|
|
|
-----------
|
|
|
|
|
2010-02-13 21:28:30 +00:00
|
|
|
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.
|
|
|
|
|
2010-02-13 21:28:32 +00:00
|
|
|
add::
|
|
|
|
Add notes for a given object (defaults to HEAD). Abort if the
|
2011-03-30 00:02:55 +00:00
|
|
|
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).
|
2010-02-13 21:28:32 +00:00
|
|
|
|
2010-02-13 21:28:38 +00:00
|
|
|
copy::
|
|
|
|
Copy the notes for the first object onto the second object.
|
|
|
|
Abort if the second object already has notes, or if the first
|
2010-03-04 14:31:17 +00:00
|
|
|
object has none (use -f to overwrite existing notes to the
|
2010-02-13 21:28:38 +00:00
|
|
|
second object). This subcommand is equivalent to:
|
|
|
|
`git notes add [-f] -C $(git notes list <from-object>) <to-object>`
|
2010-03-12 17:04:31 +00:00
|
|
|
+
|
docs: stop using asciidoc no-inline-literal
In asciidoc 7, backticks like `foo` produced a typographic
effect, but did not otherwise affect the syntax. In asciidoc
8, backticks introduce an "inline literal" inside which markup
is not interpreted. To keep compatibility with existing
documents, asciidoc 8 has a "no-inline-literal" attribute to
keep the old behavior. We enabled this so that the
documentation could be built on either version.
It has been several years now, and asciidoc 7 is no longer
in wide use. We can now decide whether or not we want
inline literals on their own merits, which are:
1. The source is much easier to read when the literal
contains punctuation. You can use `master~1` instead
of `master{tilde}1`.
2. They are less error-prone. Because of point (1), we
tend to make mistakes and forget the extra layer of
quoting.
This patch removes the no-inline-literal attribute from the
Makefile and converts every use of backticks in the
documentation to an inline literal (they must be cleaned up,
or the example above would literally show "{tilde}" in the
output).
Problematic sites were found by grepping for '`.*[{\\]' and
examined and fixed manually. The results were then verified
by comparing the output of "html2text" on the set of
generated html pages. Doing so revealed that in addition to
making the source more readable, this patch fixes several
formatting bugs:
- HTML rendering used the ellipsis character instead of
literal "..." in code examples (like "git log A...B")
- some code examples used the right-arrow character
instead of '->' because they failed to quote
- api-config.txt did not quote tilde, and the resulting
HTML contained a bogus snippet like:
<tt><sub></tt> foo <tt></sub>bar</tt>
which caused some parsers to choke and omit whole
sections of the page.
- git-commit.txt confused ``foo`` (backticks inside a
literal) with ``foo'' (matched double-quotes)
- mentions of `A U Thor <author@example.com>` used to
erroneously auto-generate a mailto footnote for
author@example.com
- the description of --word-diff=plain incorrectly showed
the output as "[-removed-] and {added}", not "{+added+}".
- using "prime" notation like:
commit `C` and its replacement `C'`
confused asciidoc into thinking that everything between
the first backtick and the final apostrophe were meant
to be inside matched quotes
- asciidoc got confused by the escaping of some of our
asterisks. In particular,
`credential.\*` and `credential.<url>.\*`
properly escaped the asterisk in the first case, but
literally passed through the backslash in the second
case.
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-04-26 08:51:57 +00:00
|
|
|
In `--stdin` mode, take lines in the format
|
2010-03-12 17:04:31 +00:00
|
|
|
+
|
|
|
|
----------
|
|
|
|
<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.)
|
2010-02-13 21:28:38 +00:00
|
|
|
|
2010-02-13 21:28:33 +00:00
|
|
|
append::
|
|
|
|
Append to the notes of an existing object (defaults to HEAD).
|
|
|
|
Creates a new notes object if needed.
|
|
|
|
|
2009-10-09 10:21:58 +00:00
|
|
|
edit::
|
2010-02-13 21:28:29 +00:00
|
|
|
Edit the notes for a given object (defaults to HEAD).
|
2009-10-09 10:21:58 +00:00
|
|
|
|
|
|
|
show::
|
2010-02-13 21:28:29 +00:00
|
|
|
Show the notes for a given object (defaults to HEAD).
|
2009-10-09 10:21:58 +00:00
|
|
|
|
2010-11-09 21:49:50 +00:00
|
|
|
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
|
2015-08-17 21:33:33 +00:00
|
|
|
conflicting notes (see the "NOTES MERGE STRATEGIES" section) is not given,
|
2010-11-09 21:49:51 +00:00
|
|
|
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.
|
git notes merge: Manual conflict resolution, part 2/2
When the notes merge conflicts in .git/NOTES_MERGE_WORKTREE have been
resolved, we need to record a new notes commit on the appropriate notes
ref with the resolved notes.
This patch implements 'git notes merge --commit' which the user should
run after resolving conflicts in the notes merge worktree. This command
finalizes the notes merge by recombining the partial notes tree from
part 1 with the now-resolved conflicts in the notes merge worktree in a
merge commit, and updating the appropriate ref to this merge commit.
In order to correctly finalize the merge, we need to keep track of three
things:
- The partial merge result from part 1, containing the auto-merged notes.
This is now stored into a ref called .git/NOTES_MERGE_PARTIAL.
- The unmerged notes. These are already stored in
.git/NOTES_MERGE_WORKTREE, thanks to part 1.
- The notes ref to be updated by the finalized merge result. This is now
stored in a symref called .git/NOTES_MERGE_REF.
In addition to "git notes merge --commit", which uses the above details
to create the finalized notes merge commit, this patch also implements
"git notes merge --reset", which aborts the ongoing notes merge by simply
removing the files/directory described above.
FTR, "git notes merge --commit" reuses "git notes merge --reset" to remove
the information described above (.git/NOTES_MERGE_*) after the notes merge
have been successfully finalized.
The patch also contains documentation and testcases for the two new options.
This patch has been improved by the following contributions:
- Ævar Arnfjörð Bjarmason: Fix nonsense sentence in --commit description
- Sverre Rabbelier: Rename --reset to --abort
Thanks-to: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Thanks-to: Sverre Rabbelier <srabbelier@gmail.com>
Signed-off-by: Johan Herland <johan@herland.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-11-09 21:49:52 +00:00
|
|
|
When done, the user can either finalize the merge with
|
|
|
|
'git notes merge --commit', or abort the merge with
|
|
|
|
'git notes merge --abort'.
|
2010-11-09 21:49:50 +00:00
|
|
|
|
2010-02-13 21:28:25 +00:00
|
|
|
remove::
|
2011-05-18 22:44:37 +00:00
|
|
|
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
|
2010-02-13 21:28:25 +00:00
|
|
|
the `edit` subcommand.
|
|
|
|
|
2010-02-13 21:28:28 +00:00
|
|
|
prune::
|
|
|
|
Remove all notes for non-existing/unreachable objects.
|
2009-10-09 10:21:58 +00:00
|
|
|
|
2010-11-09 21:49:57 +00:00
|
|
|
get-ref::
|
|
|
|
Print the current notes ref. This provides an easy way to
|
|
|
|
retrieve the current notes ref (e.g. from scripts).
|
|
|
|
|
2009-10-09 10:22:01 +00:00
|
|
|
OPTIONS
|
|
|
|
-------
|
2010-02-13 21:28:32 +00:00
|
|
|
-f::
|
|
|
|
--force::
|
|
|
|
When adding notes to an object that already has notes,
|
|
|
|
overwrite the existing notes (instead of aborting).
|
|
|
|
|
2009-10-09 10:22:01 +00:00
|
|
|
-m <msg>::
|
2010-02-13 21:28:31 +00:00
|
|
|
--message=<msg>::
|
2009-10-09 10:22:01 +00:00
|
|
|
Use the given note message (instead of prompting).
|
2010-02-13 21:28:20 +00:00
|
|
|
If multiple `-m` options are given, their values
|
|
|
|
are concatenated as separate paragraphs.
|
2010-05-09 03:21:34 +00:00
|
|
|
Lines starting with `#` and empty lines other than a
|
|
|
|
single line between paragraphs will be stripped out.
|
2009-10-09 10:22:01 +00:00
|
|
|
|
|
|
|
-F <file>::
|
2010-02-13 21:28:31 +00:00
|
|
|
--file=<file>::
|
2009-10-09 10:22:01 +00:00
|
|
|
Take the note message from the given file. Use '-' to
|
|
|
|
read the note message from the standard input.
|
2010-05-09 03:21:34 +00:00
|
|
|
Lines starting with `#` and empty lines other than a
|
|
|
|
single line between paragraphs will be stripped out.
|
2009-10-09 10:22:01 +00:00
|
|
|
|
2010-02-13 21:28:36 +00:00
|
|
|
-C <object>::
|
|
|
|
--reuse-message=<object>::
|
2011-08-25 10:26:37 +00:00
|
|
|
Take the given blob object (for example, another note) as the
|
|
|
|
note message. (Use `git notes copy <object>` instead to
|
|
|
|
copy notes between objects.)
|
2010-02-13 21:28:36 +00:00
|
|
|
|
|
|
|
-c <object>::
|
|
|
|
--reedit-message=<object>::
|
2016-06-28 11:40:10 +00:00
|
|
|
Like '-C', but with `-c` the editor is invoked, so that
|
2010-02-13 21:28:36 +00:00
|
|
|
the user can further edit the note message.
|
2009-10-09 10:22:01 +00:00
|
|
|
|
2014-11-12 00:40:14 +00:00
|
|
|
--allow-empty::
|
|
|
|
Allow an empty note object to be stored. The default behavior is
|
|
|
|
to automatically remove empty notes.
|
|
|
|
|
2010-03-12 17:04:35 +00:00
|
|
|
--ref <ref>::
|
2010-05-09 03:23:58 +00:00
|
|
|
Manipulate the notes tree in <ref>. This overrides
|
2016-06-07 22:35:06 +00:00
|
|
|
`GIT_NOTES_REF` and the "core.notesRef" configuration. The ref
|
2015-09-22 22:15:03 +00:00
|
|
|
specifies the full refname when it begins with `refs/notes/`; when it
|
|
|
|
begins with `notes/`, `refs/` and otherwise `refs/notes/` is prefixed
|
|
|
|
to form a full name of the ref.
|
2010-03-12 17:04:35 +00:00
|
|
|
|
2011-05-18 23:02:58 +00:00
|
|
|
--ignore-missing::
|
|
|
|
Do not consider it an error to request removing notes from an
|
|
|
|
object that does not have notes attached to it.
|
|
|
|
|
2011-05-18 23:44:30 +00:00
|
|
|
--stdin::
|
2017-09-12 22:58:39 +00:00
|
|
|
Also read the object names to remove notes from the standard
|
2011-05-18 23:44:30 +00:00
|
|
|
input (there is no reason you cannot combine this with object
|
|
|
|
names from the command line).
|
|
|
|
|
2010-05-14 21:42:07 +00:00
|
|
|
-n::
|
2010-08-06 20:28:09 +00:00
|
|
|
--dry-run::
|
2010-05-14 21:42:07 +00:00
|
|
|
Do not remove anything; just report the object names whose notes
|
|
|
|
would be removed.
|
|
|
|
|
2010-11-09 21:49:50 +00:00
|
|
|
-s <strategy>::
|
|
|
|
--strategy=<strategy>::
|
|
|
|
When merging notes, resolve notes conflicts using the given
|
|
|
|
strategy. The following strategies are recognized: "manual"
|
2010-11-14 23:57:17 +00:00
|
|
|
(default), "ours", "theirs", "union" and "cat_sort_uniq".
|
2015-08-17 21:33:33 +00:00
|
|
|
This option overrides the "notes.mergeStrategy" configuration setting.
|
2010-11-09 21:49:50 +00:00
|
|
|
See the "NOTES MERGE STRATEGIES" section below for more
|
|
|
|
information on each notes merge strategy.
|
|
|
|
|
git notes merge: Manual conflict resolution, part 2/2
When the notes merge conflicts in .git/NOTES_MERGE_WORKTREE have been
resolved, we need to record a new notes commit on the appropriate notes
ref with the resolved notes.
This patch implements 'git notes merge --commit' which the user should
run after resolving conflicts in the notes merge worktree. This command
finalizes the notes merge by recombining the partial notes tree from
part 1 with the now-resolved conflicts in the notes merge worktree in a
merge commit, and updating the appropriate ref to this merge commit.
In order to correctly finalize the merge, we need to keep track of three
things:
- The partial merge result from part 1, containing the auto-merged notes.
This is now stored into a ref called .git/NOTES_MERGE_PARTIAL.
- The unmerged notes. These are already stored in
.git/NOTES_MERGE_WORKTREE, thanks to part 1.
- The notes ref to be updated by the finalized merge result. This is now
stored in a symref called .git/NOTES_MERGE_REF.
In addition to "git notes merge --commit", which uses the above details
to create the finalized notes merge commit, this patch also implements
"git notes merge --reset", which aborts the ongoing notes merge by simply
removing the files/directory described above.
FTR, "git notes merge --commit" reuses "git notes merge --reset" to remove
the information described above (.git/NOTES_MERGE_*) after the notes merge
have been successfully finalized.
The patch also contains documentation and testcases for the two new options.
This patch has been improved by the following contributions:
- Ævar Arnfjörð Bjarmason: Fix nonsense sentence in --commit description
- Sverre Rabbelier: Rename --reset to --abort
Thanks-to: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Thanks-to: Sverre Rabbelier <srabbelier@gmail.com>
Signed-off-by: Johan Herland <johan@herland.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-11-09 21:49:52 +00:00
|
|
|
--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::
|
2018-06-22 06:50:37 +00:00
|
|
|
Abort/reset an in-progress 'git notes merge', i.e. a notes merge
|
git notes merge: Manual conflict resolution, part 2/2
When the notes merge conflicts in .git/NOTES_MERGE_WORKTREE have been
resolved, we need to record a new notes commit on the appropriate notes
ref with the resolved notes.
This patch implements 'git notes merge --commit' which the user should
run after resolving conflicts in the notes merge worktree. This command
finalizes the notes merge by recombining the partial notes tree from
part 1 with the now-resolved conflicts in the notes merge worktree in a
merge commit, and updating the appropriate ref to this merge commit.
In order to correctly finalize the merge, we need to keep track of three
things:
- The partial merge result from part 1, containing the auto-merged notes.
This is now stored into a ref called .git/NOTES_MERGE_PARTIAL.
- The unmerged notes. These are already stored in
.git/NOTES_MERGE_WORKTREE, thanks to part 1.
- The notes ref to be updated by the finalized merge result. This is now
stored in a symref called .git/NOTES_MERGE_REF.
In addition to "git notes merge --commit", which uses the above details
to create the finalized notes merge commit, this patch also implements
"git notes merge --reset", which aborts the ongoing notes merge by simply
removing the files/directory described above.
FTR, "git notes merge --commit" reuses "git notes merge --reset" to remove
the information described above (.git/NOTES_MERGE_*) after the notes merge
have been successfully finalized.
The patch also contains documentation and testcases for the two new options.
This patch has been improved by the following contributions:
- Ævar Arnfjörð Bjarmason: Fix nonsense sentence in --commit description
- Sverre Rabbelier: Rename --reset to --abort
Thanks-to: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Thanks-to: Sverre Rabbelier <srabbelier@gmail.com>
Signed-off-by: Johan Herland <johan@herland.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-11-09 21:49:52 +00:00
|
|
|
with conflicts. This simply removes all files related to the
|
|
|
|
notes merge.
|
|
|
|
|
2010-11-09 21:49:50 +00:00
|
|
|
-q::
|
|
|
|
--quiet::
|
|
|
|
When merging notes, operate quietly.
|
|
|
|
|
2010-05-14 21:42:07 +00:00
|
|
|
-v::
|
2010-08-06 20:28:09 +00:00
|
|
|
--verbose::
|
2010-11-09 21:49:50 +00:00
|
|
|
When merging notes, be more verbose.
|
|
|
|
When pruning notes, report all object names whose notes are
|
|
|
|
removed.
|
2010-05-14 21:42:07 +00:00
|
|
|
|
2010-03-12 17:04:37 +00:00
|
|
|
|
2010-05-09 03:19:35 +00:00
|
|
|
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.].
|
2010-03-12 17:04:37 +00:00
|
|
|
|
|
|
|
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.,
|
2010-05-09 03:19:35 +00:00
|
|
|
`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>`.
|
2010-03-12 17:04:37 +00:00
|
|
|
|
|
|
|
|
2010-11-09 21:49:50 +00:00
|
|
|
NOTES MERGE STRATEGIES
|
|
|
|
----------------------
|
|
|
|
|
2010-11-09 21:49:51 +00:00
|
|
|
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.
|
git notes merge: Manual conflict resolution, part 2/2
When the notes merge conflicts in .git/NOTES_MERGE_WORKTREE have been
resolved, we need to record a new notes commit on the appropriate notes
ref with the resolved notes.
This patch implements 'git notes merge --commit' which the user should
run after resolving conflicts in the notes merge worktree. This command
finalizes the notes merge by recombining the partial notes tree from
part 1 with the now-resolved conflicts in the notes merge worktree in a
merge commit, and updating the appropriate ref to this merge commit.
In order to correctly finalize the merge, we need to keep track of three
things:
- The partial merge result from part 1, containing the auto-merged notes.
This is now stored into a ref called .git/NOTES_MERGE_PARTIAL.
- The unmerged notes. These are already stored in
.git/NOTES_MERGE_WORKTREE, thanks to part 1.
- The notes ref to be updated by the finalized merge result. This is now
stored in a symref called .git/NOTES_MERGE_REF.
In addition to "git notes merge --commit", which uses the above details
to create the finalized notes merge commit, this patch also implements
"git notes merge --reset", which aborts the ongoing notes merge by simply
removing the files/directory described above.
FTR, "git notes merge --commit" reuses "git notes merge --reset" to remove
the information described above (.git/NOTES_MERGE_*) after the notes merge
have been successfully finalized.
The patch also contains documentation and testcases for the two new options.
This patch has been improved by the following contributions:
- Ævar Arnfjörð Bjarmason: Fix nonsense sentence in --commit description
- Sverre Rabbelier: Rename --reset to --abort
Thanks-to: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Thanks-to: Sverre Rabbelier <srabbelier@gmail.com>
Signed-off-by: Johan Herland <johan@herland.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-11-09 21:49:52 +00:00
|
|
|
When done, the user can either finalize the merge with
|
|
|
|
'git notes merge --commit', or abort the merge with
|
|
|
|
'git notes merge --abort'.
|
2010-11-09 21:49:50 +00:00
|
|
|
|
2015-08-17 21:33:33 +00:00
|
|
|
Users may select an automated merge strategy from among the following using
|
|
|
|
either -s/--strategy option or configuring notes.mergeStrategy accordingly:
|
|
|
|
|
2010-11-09 21:49:50 +00:00
|
|
|
"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.
|
|
|
|
|
2010-11-14 23:57:17 +00:00
|
|
|
"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.
|
|
|
|
|
2010-11-09 21:49:50 +00:00
|
|
|
|
2010-05-09 03:21:34 +00:00
|
|
|
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)
|
2014-11-12 00:40:14 +00:00
|
|
|
$ git notes --ref=built add --allow-empty -C "$blob" HEAD
|
2010-05-09 03:21:34 +00:00
|
|
|
------------
|
|
|
|
|
2011-08-25 10:26:37 +00:00
|
|
|
(You cannot simply use `git notes --ref=built add -F a.out HEAD`
|
|
|
|
because that is not binary-safe.)
|
2010-05-09 03:21:34 +00:00
|
|
|
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.
|
|
|
|
|
|
|
|
|
2010-05-09 03:21:59 +00:00
|
|
|
CONFIGURATION
|
|
|
|
-------------
|
|
|
|
|
|
|
|
core.notesRef::
|
2010-05-09 03:23:58 +00:00
|
|
|
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.
|
2010-05-09 03:21:59 +00:00
|
|
|
|
2015-08-17 21:33:33 +00:00
|
|
|
notes.mergeStrategy::
|
|
|
|
Which merge strategy to choose by default when resolving notes
|
|
|
|
conflicts. Must be one of `manual`, `ours`, `theirs`, `union`, or
|
|
|
|
`cat_sort_uniq`. Defaults to `manual`. See "NOTES MERGE STRATEGIES"
|
|
|
|
section above for more information on each strategy.
|
|
|
|
+
|
|
|
|
This setting can be overridden by passing the `--strategy` option.
|
|
|
|
|
2015-08-17 21:33:34 +00:00
|
|
|
notes.<name>.mergeStrategy::
|
|
|
|
Which merge strategy to choose when doing a notes merge into
|
|
|
|
refs/notes/<name>. This overrides the more general
|
|
|
|
"notes.mergeStrategy". See the "NOTES MERGE STRATEGIES" section above
|
|
|
|
for more information on each available strategy.
|
|
|
|
|
2010-05-09 03:21:59 +00:00
|
|
|
notes.displayRef::
|
2010-05-09 03:32:24 +00:00
|
|
|
Which ref (or refs, if a glob or specified more than once), in
|
|
|
|
addition to the default set by `core.notesRef` or
|
2016-06-07 22:35:06 +00:00
|
|
|
`GIT_NOTES_REF`, to read notes from when showing commit
|
2010-05-09 03:32:24 +00:00
|
|
|
messages with the 'git log' family of commands.
|
|
|
|
This setting can be overridden on the command line or by the
|
2016-06-07 22:35:06 +00:00
|
|
|
`GIT_NOTES_DISPLAY_REF` environment variable.
|
2010-05-09 03:32:24 +00:00
|
|
|
See linkgit:git-log[1].
|
2010-05-09 03:21:59 +00:00
|
|
|
|
|
|
|
notes.rewrite.<command>::
|
|
|
|
When rewriting commits with <command> (currently `amend` or
|
2010-05-09 03:33:28 +00:00
|
|
|
`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.
|
|
|
|
+
|
2016-06-07 22:35:06 +00:00
|
|
|
This setting can be overridden by the `GIT_NOTES_REWRITE_REF`
|
2010-05-09 03:33:28 +00:00
|
|
|
environment variable.
|
2010-05-09 03:21:59 +00:00
|
|
|
|
|
|
|
notes.rewriteMode::
|
2010-05-09 03:33:28 +00:00
|
|
|
When copying notes during a rewrite, what to do if the target
|
|
|
|
commit already has a note. Must be one of `overwrite`,
|
2015-08-17 21:33:29 +00:00
|
|
|
`concatenate`, `cat_sort_uniq`, or `ignore`. Defaults to
|
|
|
|
`concatenate`.
|
2010-05-09 03:21:59 +00:00
|
|
|
+
|
|
|
|
This setting can be overridden with the `GIT_NOTES_REWRITE_MODE`
|
|
|
|
environment variable.
|
|
|
|
|
|
|
|
notes.rewriteRef::
|
|
|
|
When copying notes during a rewrite, specifies the (fully
|
2010-05-09 03:33:28 +00:00
|
|
|
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.
|
2010-05-09 03:21:59 +00:00
|
|
|
+
|
|
|
|
Does not have a default value; you must configure this variable to
|
|
|
|
enable note rewriting.
|
|
|
|
+
|
2016-06-07 22:35:06 +00:00
|
|
|
Can be overridden with the `GIT_NOTES_REWRITE_REF` environment variable.
|
2010-05-09 03:21:59 +00:00
|
|
|
|
2010-05-09 03:23:58 +00:00
|
|
|
|
|
|
|
ENVIRONMENT
|
|
|
|
-----------
|
|
|
|
|
2016-06-07 22:35:06 +00:00
|
|
|
`GIT_NOTES_REF`::
|
2010-05-09 03:23:58 +00:00
|
|
|
Which ref to manipulate notes from, instead of `refs/notes/commits`.
|
|
|
|
This overrides the `core.notesRef` setting.
|
|
|
|
|
2016-06-07 22:35:06 +00:00
|
|
|
`GIT_NOTES_DISPLAY_REF`::
|
2010-05-09 03:32:24 +00:00
|
|
|
Colon-delimited list of refs or globs indicating which refs,
|
|
|
|
in addition to the default from `core.notesRef` or
|
2016-06-07 22:35:06 +00:00
|
|
|
`GIT_NOTES_REF`, to read notes from when showing commit
|
2010-05-09 03:32:24 +00:00
|
|
|
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.
|
|
|
|
|
2016-06-07 22:35:06 +00:00
|
|
|
`GIT_NOTES_REWRITE_MODE`::
|
2010-05-09 03:33:28 +00:00
|
|
|
When copying notes during a rewrite, what to do if the target
|
|
|
|
commit already has a note.
|
2015-08-17 21:33:29 +00:00
|
|
|
Must be one of `overwrite`, `concatenate`, `cat_sort_uniq`, or `ignore`.
|
2010-05-09 03:33:28 +00:00
|
|
|
This overrides the `core.rewriteMode` setting.
|
|
|
|
|
2016-06-07 22:35:06 +00:00
|
|
|
`GIT_NOTES_REWRITE_REF`::
|
2010-05-09 03:33:28 +00:00
|
|
|
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.
|
|
|
|
|
2009-10-09 10:21:58 +00:00
|
|
|
GIT
|
|
|
|
---
|
2016-05-04 17:36:24 +00:00
|
|
|
Part of the linkgit:git[1] suite
|