diff options
Diffstat (limited to 'Documentation/git-notes.txt')
| -rw-r--r-- | Documentation/git-notes.txt | 113 |
1 files changed, 74 insertions, 39 deletions
diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt index 296f314eae..43677297f3 100644 --- a/Documentation/git-notes.txt +++ b/Documentation/git-notes.txt @@ -9,15 +9,15 @@ SYNOPSIS -------- [verse] 'git notes' [list [<object>]] -'git notes' add [-f] [-F <file> | -m <msg> | (-c | -C) <object>] [<object>] +'git notes' add [-f] [--allow-empty] [-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' append [--allow-empty] [-F <file> | -m <msg> | (-c | -C) <object>] [<object>] +'git notes' edit [--allow-empty] [<object>] 'git notes' show [<object>] -'git notes' merge [-v | -q] [-s <strategy> ] <notes_ref> +'git notes' merge [-v | -q] [-s <strategy> ] <notes-ref> 'git notes' merge --commit [-v | -q] 'git notes' merge --abort [-v | -q] -'git notes' remove [<object>] +'git notes' remove [--ignore-missing] [--stdin] [<object>...] 'git notes' prune [-n | -v] 'git notes' get-ref @@ -39,6 +39,10 @@ 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]. @@ -57,8 +61,11 @@ list:: add:: Add notes for a given object (defaults to HEAD). Abort if the - object already has notes (use `-f` to overwrite an - existing note). + 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. @@ -67,7 +74,7 @@ copy:: 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 +In `--stdin` mode, take lines in the format + ---------- <from-object> SP <to-object> [ SP <rest> ] LF @@ -94,7 +101,7 @@ merge:: 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, +conflicting notes (see the "NOTES MERGE STRATEGIES" section) 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. @@ -103,8 +110,9 @@ When done, the user can either finalize the merge with 'git notes merge --abort'. remove:: - Remove the notes for a given object (defaults to HEAD). - This is equivalent to specifying an empty note message to + 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:: @@ -138,18 +146,34 @@ OPTIONS -C <object>:: --reuse-message=<object>:: - Take the note message from the given blob object (for - example, another note). + 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 + Like '-C', but with `-c` the editor is invoked, so that the user can further edit the note message. +--allow-empty:: + Allow an empty note object to be stored. The default behavior is + to automatically remove empty notes. + --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. + `GIT_NOTES_REF` and the "core.notesRef" configuration. The ref + 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. + +--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 the standard + input (there is no reason you cannot combine this with object + names from the command line). -n:: --dry-run:: @@ -161,6 +185,7 @@ OPTIONS When merging notes, resolve notes conflicts using the given strategy. The following strategies are recognized: "manual" (default), "ours", "theirs", "union" and "cat_sort_uniq". + This option overrides the "notes.mergeStrategy" configuration setting. See the "NOTES MERGE STRATEGIES" section below for more information on each notes merge strategy. @@ -225,6 +250,9 @@ When done, the user can either finalize the merge with 'git notes merge --commit', or abort the merge with 'git notes merge --abort'. +Users may select an automated merge strategy from among the following using +either -s/--strategy option or configuring notes.mergeStrategy accordingly: + "ours" automatically resolves conflicting notes in favor of the local version (i.e. the current notes ref). @@ -269,9 +297,11 @@ arbitrary files using 'git hash-object': ------------ $ cc *.c $ blob=$(git hash-object -w a.out) -$ git notes --ref=built add -C "$blob" HEAD +$ git notes --ref=built add --allow-empty -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. @@ -286,13 +316,27 @@ core.notesRef:: This setting can be overridden through the environment and command line. +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. + +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. + 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 + `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. + `GIT_NOTES_DISPLAY_REF` environment variable. See linkgit:git-log[1]. notes.rewrite.<command>:: @@ -301,13 +345,14 @@ notes.rewrite.<command>:: 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' +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`. + `concatenate`, `cat_sort_uniq`, or `ignore`. Defaults to + `concatenate`. + This setting can be overridden with the `GIT_NOTES_REWRITE_MODE` environment variable. @@ -321,33 +366,33 @@ notes.rewriteRef:: 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. +Can be overridden with the `GIT_NOTES_REWRITE_REF` environment variable. ENVIRONMENT ----------- -'GIT_NOTES_REF':: +`GIT_NOTES_REF`:: Which ref to manipulate notes from, instead of `refs/notes/commits`. This overrides the `core.notesRef` setting. -'GIT_NOTES_DISPLAY_REF':: +`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 + `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':: +`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`. + Must be one of `overwrite`, `concatenate`, `cat_sort_uniq`, or `ignore`. This overrides the `core.rewriteMode` setting. -'GIT_NOTES_REWRITE_REF':: +`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. @@ -355,16 +400,6 @@ does not match any refs is silently ignored. 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 +Part of the linkgit:git[1] suite |