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.

  • Do you actually need to make changes to that journal, or only append to it? In the latter case, you could think outside the box and manage the journal entries as commit messages on a journal branch and then generate the journal.md from output of git log for that branch. – Jörg W Mittag Jul 23 '18 at 13:41
  • 1
    Another idea: rig something up with git notes, e.g. keep the journal as a note on the root commit. – Jörg W Mittag Jul 23 '18 at 13:43
  • so.. commit messages? – Ewan Jul 23 '18 at 13:57
  • What kinds of things are you putting in the journal? – Greg Burghardt Jul 23 '18 at 15:59

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).


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.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.