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

Merge branch 'jk/notes-dwim-doc'

2015-10-14T21:30:15Z

The way how --ref/--notes to specify the notes tree reference are DWIMmed was not clearly documented. * jk/notes-dwim-doc: notes: correct documentation of DWIMery for notes references

notes: correct documentation of DWIMery for notes references

2015-09-22T22:24:01Z

expand_notes_ref is used by --ref from git-notes(1) and --notes from the git log to find the full refname of a notes reference. Previously the documentation of these options was not clear about what sorts of expansions would be performed. Fix the documentation to clearly and accurately describe the behavior of the expansions. Add a test for this expansion when using git notes get-ref in order to prevent future patches from changing this behavior. Signed-off-by: Jacob Keller Signed-off-by: Junio C Hamano

notes: teach git-notes about notes..mergeStrategy option

2015-08-17T22:39:13Z

Teach notes about a new "notes..mergeStrategy" option for configuring the notes merge strategy when merging into refs/notes/. This option allows for the selection of merge strategy for particular notes refs, rather than all notes ref merges, as user may not want cat_sort_uniq for all refs, but only some. Note that the is the local reference we are merging into, not the remote ref we merged from. The assumption is that users will mostly want to configure separate local ref merge strategies rather than strategies depending on which remote ref they merge from. notes..mergeStrategy overrides the general behavior as it is more specific. Signed-off-by: Jacob Keller Signed-off-by: Junio C Hamano

notes: add notes.mergeStrategy option to select default strategy

2015-08-17T22:38:54Z

Teach git-notes about "notes.mergeStrategy" to select a general strategy for all notes merges. This enables a user to always get expected merge strategy such as "cat_sort_uniq" without having to pass the "-s" option manually. Signed-off-by: Jacob Keller Signed-off-by: Junio C Hamano

notes: document cat_sort_uniq rewriteMode

2015-08-17T22:35:49Z

Teach documentation about the cat_sort_uniq rewriteMode that got added at the same time as the equivalent merge strategy. Signed-off-by: Jacob Keller Signed-off-by: Junio C Hamano

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