delta/git.git/Documentation/git-notes.txt, branch jk/robustify-parse-commit

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

2012-10-25T10:15:56+00:00

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:06+00:00

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:46+00:00

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:16+00:00

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:42+00:00

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:44+00:00

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:52+00:00

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

Provide 'git notes get-ref' to easily retrieve current notes ref

2010-11-17T21:23:55+00:00

Script may use 'git notes get-ref' to easily retrieve the current notes ref.

Suggested-by: Jonathan Nieder 
Signed-off-by: Johan Herland 
Signed-off-by: Junio C Hamano

git notes merge: Add another auto-resolving strategy: "cat_sort_uniq"

2010-11-17T21:22:53+00:00

This new strategy is similar to "concatenate", but in addition to
concatenating the two note candidates, this strategy sorts the resulting
lines, and removes duplicate lines from the result. This is equivalent to
applying the "cat | sort | uniq" shell pipeline to the two note candidates.

This strategy is useful if the notes follow a line-based format where one
wants to avoid duplicate lines in the merge result.

Note that if either of the note candidates contain duplicate lines _prior_
to the merge, these will also be removed by this merge strategy.

The patch also contains tests and documentation for the new strategy.

Signed-off-by: Johan Herland 
Signed-off-by: Junio C Hamano

git notes merge: Manual conflict resolution, part 2/2

2010-11-17T21:22:49+00:00

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 
Thanks-to: Sverre Rabbelier 
Signed-off-by: Johan Herland 
Signed-off-by: Junio C Hamano