Managing source code annotations and version control

Question

I would like to be able to annotate source code files with my own personal notes, strip these notes out before committing to version control, and merge changes back in from version control without generating merge conflicts when my own changes come back in.

I was inspired by org-mode's approach to literate programming, but I don't think org mode itself would be feasible because of the issues described above.

Is there any way of attaching annotations to source code in Emacs, either as in-place annotations that can be stripped and reinstated in the manner described, or in a separate file with Emacs marking the annotations dynamically?

Answer 1

You can bookmark any file, or any part of a code/text file. You can even bookmark a region (and have the region activated when you jump to the bookmark).

A bookmark can have an annotation, and that annotation can be simple text or a separate Org file.

Bookmarks are saved in a separate file from the places they bookmark. (And you can have multiple bookmark files, to help you organize your bookmarks.)

For better bookmark annotating, bookmarking a region, and better support for multiple bookmark files you need Bookmark+. But even vanilla Emacs offers bookmarks with annotations.

With Bookmark+, when looking at your bookmark-list display, you can:

• See immediately which bookmarks have annotations (they're labeled with a highlighted a).
• Use P A to incrementally filter the listed bookmarks by matching their annotations with a regexp.
• Use a to show the annotation of a bookmark.
• Use M-a to see the annotations of all listed bookmarks in a single buffer.
• Use C-u a to edit a bookmark's annotation.

Non-nil user option bookmark-automatically-show-annotations shows a bookmark's annotation each time you jump to the bookmark.

Non-nil option bookmark-use-annotations queries you for an annotation each time you save a bookmark.