git/Documentation/git-notes.txt, branch v2.5.2

builtin/notes: add --allow-empty, to allow storing empty notes

2014-11-12T19:00:11Z

Although the "git notes" man page advertises that we support binary-safe notes addition (using the -C option), we currently do not support adding the empty note (i.e. using the empty blob to annotate an object). Instead, an empty note is always treated as an intent to remove the note altogether. Introduce the --allow-empty option to the add/append/edit subcommands, to explicitly allow an empty note to be stored into the notes tree. Also update the documentation, and add test cases for the new option. Reported-by: James H. Fisher Improved-by: Kyle J. McKay Improved-by: Junio C Hamano Signed-off-by: Johan Herland Signed-off-by: Junio C Hamano

parse-options: multi-word argh should use dash to separate words

2014-03-24T17:43:34Z

"When you need to use space, use dash" is a strange way to say that you must not use a space. Because it is more common for the command line descriptions to use dashed-multi-words, you do not even want to use spaces in these places. Rephrase the documentation to avoid this strangeness. Fix a few existing multi-word argument help strings, i.e. - GPG key-ids given to -S/--gpg-sign are "key-id"; - Refs used for storing notes are "notes-ref"; and - Expiry timestamps given to --expire are "expiry-date". and update the corresponding documentation pages. Signed-off-by: Junio C Hamano

doc: remote author/documentation sections from more pages

2014-01-27T16:34:34Z

We decided at 48bb914e (doc: drop author/documentation sections from most pages, 2011-03-11) to remove "author" and "documentation" sections from our documentation. Remove a few stragglers. Signed-off-by: Michael Haggerty Reviewed-by: Jonathan Nieder Signed-off-by: Junio C Hamano

Doc notes: Include the format-patch --notes option

2012-10-25T10:15:56Z

git format-patch gained a --notes option. Tell the notes user. Signed-off-by: Philip Oakley Signed-off-by: Jeff King

docs: stop using asciidoc no-inline-literal

2012-04-26T20:19:06Z

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: foo bar 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 ` 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..\*` properly escaped the asterisk in the first case, but literally passed through the backslash in the second case. Signed-off-by: Jeff King Signed-off-by: Junio C Hamano

git-notes.txt: clarify -C vs. copy and -F

2011-08-25T20:16:46Z

The current description of '-C' together with the analogy to 'git commit -C' can lead to the wrong conclusion that '-C' copies notes between objects. Make this clearer by rewording and pointing to 'copy'. The example for attaching binary notes with 'git hash-object' followed by 'git notes add -C' immediately raises the question: "Why not use 'git notes add -F'?". Answer it (the latter is not binary-safe). Signed-off-by: Michael J Gruber Acked-by: Johan Herland Signed-off-by: Junio C Hamano

notes remove: --stdin reads from the standard input

2011-05-19T17:54:16Z

Teach the command to read object names to remove from the standard input, in addition to the object names given from the command line. Signed-off-by: Junio C Hamano

notes remove: --ignore-missing

2011-05-19T17:46:42Z

Depending on the application, it is not necessarily an error for an object to lack a note, especially if the only thing the caller wants to make sure is that notes are cleared for an object. By passing this option from the command line, the "git notes remove" command considers it a success if the object did not have any note to begin with. Signed-off-by: Junio C Hamano

notes remove: allow removing more than one

2011-05-19T17:44:44Z

While "xargs -n1 git notes rm" is certainly a possible way to remove notes from many objects, this would create one notes "commit" per removal, which is not quite suitable for seasonal housekeeping. Allow taking more than one on the command line, and record their removal as a single atomic event if everthing goes well. Even though the old code insisted that "git notes rm" must be given only one object (or zero, in which case it would default to HEAD), this condition was not tested. Add tests to handle the new case where we feed multiple objects, and also make sure if there is a bad input, no change is recorded. Signed-off-by: Junio C Hamano

Make "git notes add" more user-friendly when there are existing notes

2011-03-30T20:13:52Z

Currently, "notes add" (without -f/--force) will abort when the given object already has existing notes. This makes sense for the modes of "git notes add" that would necessarily overwrite the old message (when using the -m/-F/-C/-c options). However, when no options are given (meaning the notes are created from scratch in the editor) it is not very user-friendly to abort on existing notes, and forcing the user to run "git notes edit". Instead, it is better to simply "redirect" to "git notes edit" automatically, i.e. open the existing notes in the editor and let the user edit them. This patch does just that. This changes the behavior of "git notes add" without options when notes already exist for the given object, but I doubt that many users really depend on the previous failure from "git notes add" in this case. Signed-off-by: Johan Herland Signed-off-by: Junio C Hamano