How do I manage a development journal?

Question

I am working solo on small development projects on my own time, using Git. For each project, I like to have a development journal which is associated with that project and not associated with other projects. The journal is a simple markdown file, journal.md.

Here are my requirements for managing the journal in my workflow:

• there must be exactly one managed version of journal.md in the project repository; and

• I need to be able to make changes to journal.md from any branch, and keep those changes when checking out different branches via git checkout (i.e., the file must not change as a result of switching branches, and must not be deleted when switching branches).

I am looking for workflows (either a sequence of Git commands for switching branches, or a way of storing journal.md, or something else which enables me to work normally in Git while satisfying the above requirements).

I have investigated the following options.

1. Keep a separate orphan branch journal; commit the initial journal, and journal updates, to this branch and no other branches. This satisfies the first requirement, but the second requirement is trickier due to the behavior of git checkout.

   • Suppose I've finished the day and committed my journal updates to journal; then, when starting the next day, I need to switch from journal to master. In this situation, git checkout will delete journal.md, even though I want to keep the file around and modify it.
   • Suppose I have a modified version of journal.md while on master, and I want to commit this modified version to journal. In this situation, git checkout will complain that "local changes will be overwritten".
   • I could avoid both of these issues if I could add/commit a single file to journal while on master, without actually checking out master. However, I have not found a way to do this.

2. Keep a separate repository for the journal file for this particular project--e.g., <project>-journal. This obviously doesn't satisfy the first requirement, although it does satisfy the second. The primary problem with this approach is that I have two separate repositories for a single (small) project. This feels...wrong.

Any suggestions would be appreciated.

Answer 1

First, I suggest you reconsider the idea about having one 'journal' for the entire repository, regardless of branch. I do something similar for my larger projects (Release-Notes.md, many people also call this ChangeLog).

Example:

• https://github.com/SophistSolutions/Stroika/blob/V2.1-Release/Release-Notes.md

• https://github.com/SophistSolutions/Stroika/blob/V2.0-Release/Release-Notes.md

But if you are confident in that choice (one journal regardless of branch) - storing it in its own repository is a fairly viable solution, and gets a little closer to your goal when you combine it with git submodules. Make the journal folder a submodule, and keep all branches up to date with the latest version of that submodule.

Answer 2

I’ll suggest a modified version of alternative 1:

• Use an orphan branch journal
• Keep it in a separate worktree

    git worktree add --detach ../journal
    cd ../journal/
    git switch --orphan journal
    touch journal.md
    git add journal.md
    git commit -m 'Init journal'

Now you can always edit this journal by accessing this worktree, which can stay forever checked out on this branch.

Answer 3

Store the "real" journal in the project's parent folder, and frequently copy snapshots into the currently checked out branch. So its history will be recorded with each routine $ git commit -a.

A branch that hasn't been checked out in several weeks will have stale journal history, and that's OK. Eventually it will catch up. And when the feature branch is merged down to main, the aggregate history will all be there.

Assuming "append only" (or append "mostly") record keeping, merge conflicts should be trivial to resolve, if they happen at all.

In emacs I find C-c . (CTRL/C dot) a convenient way of adding standardized datestamps to org-mode markdown files.

---

For projects "foo" and "baz", here is an example layout. Each of my projects has a Makefile to support common command sequences like $ make lint test or $ make release, and I imagine journaling would get folded into that. Or you could write a brief copy-the-journal shell script that is common across projects.

├── baz
│   ├── Makefile
│   ├── cache
│   │   └── baz-journal.md
│   └── src
├── baz-journal.md
├── foo
│   ├── Makefile
│   ├── cache
│   │   └── foo-journal.md
│   └── src
└── foo-journal.md