Johan Herland wrote:
> --- a/notes.h
> +++ b/notes.h
> @@ -104,6 +104,10 @@ const unsigned char *get_note(struct notes_tree *t,
> * Copy a note from one object to another in the given notes_tree.
> *
> * Fails if the to_obj already has a note unless 'force' is true.
> + *
> + * IMPORTANT: The changes made by copy_note() to the given notes_tree structure
> + * are not persistent until a subsequent call to write_notes_tree() returns
> + * zero.
This reminds me: I sometimes wish there were a
Documentation/technical/api-notes.txt giving a high-level overview of
the API, something like this to start (warning: formatting probably
broken):
-- 8< --
notes API
=========
So you want to write or access persistent, per-object text? The notes
API might help.
Calling sequence
----------------
The caller:
* Allocates and clears a `struct notes_tree`, then fills it based on a
new or existing notes ref with `init_notes()`.
* Adds, removes, and retrieves notes as desired:
. To add notes: use `write_sha1_file()` to create a blob object
containing the information to be stored, and add it to the
in-core notes tree with `add_note()`.
. Retrieve notes as blob objects with `get_note()`, or as
text with `format_note()`.
. Change which objects a note is attached to with `copy_note()`
and `remove_note()`.
* Can iterate over all notes with `for_each_note()`.
* Can remove notes attached to missing objects with `prune_notes()`.
* (Optionally) makes changes persist with `write_notes_tree()`.
* Frees resources associated to the notes tree with `free_notes()`.
A program like 'git log' that needs to find the notes corresponding
to certain objects in multiple notes trees might instead use the
display notes API. In this case, the caller:
* (Optionally) prepares a `struct display_notes_opt` with settings
about which notes trees to use.
* Initializes the display notes machinery with `init_display_notes()`.
* Retrieves notes for each object of interest with
`format_display_notes()`.
-- >8 --
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html