On Tuesday 5. October 2010 16.55.43 Jonathan Nieder wrote: > 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, I thought studying the notes.h file and its comments was a sufficient introduction on how to work with notes in code. I'm certainly biased, though (as I obviously already know how to work with notes in code)... If you believe that api-notes.txt is a valuable addition to Documentation/, I have no problem ack-ing a patch that adds it. > 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 -- This looks like a good start. ...Johan -- Johan Herland, <johan@xxxxxxxxxxx> www.herland.net -- 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