Using Git Commit History as a Lab Notebook

Discussion of this idea with ChatGPT. I copied the interesting parts here:

I’m thinking about using git commits more than just documenting changes, but as a journal for my work as it advances. Like a lab notebook in code.

I want to store my plans in the commit messages too, but I don’t want to add a bunch of temporary artifacts to the code base.

Is there any way to do this in git? Or did someone else already invented something like this?

Using Git commit messages as a form of a lab notebook is a great idea and can be highly effective for documenting your work and thoughts over time. However, you’re correct in wanting to avoid cluttering your codebase with temporary files or artifacts.

Use specific tags like [PLAN], [NOTE], or [JOURNAL] in your commit messages to categorize them.

Git has a feature called git notes that allows you to attach additional information to a commit without changing the commit itself. This is perfect for journaling since you can keep detailed logs, plans, and thoughts associated with specific commits without modifying the commit history.

If your project has a documentation directory, consider writing your plans, notes, and journal entries in markdown files or text files within that directory. You can commit these files without impacting your source code, keeping the codebase clean.

Looks like others are playing with this idea too.

• Simon Willison on X: “Started experimenting with "git notes” against a new repo on GitHub to see if they might offer a neat way to archive issue threads in the repository itself As far as I can tell the @github web UI doesn’t have any mechanism for displaying them? https://t.co/ezNxRTT3bO" / X
• Try adding git notes to some commits · Issue #1 · simonw/playing-with-git-notes
• Try storing issues in a separate branch · Issue #2 · simonw/playing-with-git-notes

Simon Willison’s Experiment: Simon is experimenting with using git notes to archive issue threads directly in the repository. This approach can help keep all relevant discussions, decisions, and context attached to specific commits, even if these discussions happen outside of the commit history (e.g., in GitHub issues).

While git notes are powerful, their lack of visibility in some platforms (like GitHub) might be a limitation. Therefore, using them in combination with more visible methods, like markdown files in a documentation branch, could provide a more robust solution.

Simon Willison also did a talk where he talked about how he uses GitHub issues to document his work. https://simonwillison.net/2022/Nov/26/productivity/

What about empty commit messages? Are they fit this use-case somehow?

Simon Willison’s talk about using GitHub issues to document his work is an insightful approach to managing and tracking the progress of projects. Here’s a summary of key takeaways from his talk, which might inspire your own workflow:

• Issue-Driven Development: You could adopt a similar approach by using GitHub issues to not only track tasks but also to plan and journal your work. This could include writing down your initial thoughts when starting a new task, logging challenges as they arise, and noting how you solved them.

• Cross-Referencing: Take advantage of GitHub’s ability to cross-reference issues, commits, and pull requests. This can help you maintain a detailed and interconnected log of your project’s history.

• Making It Public: If you’re working on open-source projects, consider making your work process public through GitHub issues. This transparency can foster collaboration and invite feedback, potentially leading to better outcomes.

• Personal Workflow: Even if you’re working on private projects, using GitHub issues as a journal can still be valuable. It provides a structured and organized way to document your work, which you can later review or share with others if needed.

Empty commit messages might seem unconventional, but they can indeed have a place in a workflow that treats Git as a form of lab notebook or journal.

Git allows you to create commits without changing any files using git commit –allow-empty. You can use this to create log entries that represent thoughts, decisions, or plans without altering the codebase. Although these commits are empty in terms of code changes, they can still have meaningful commit messages later amended or added.

Simon also compares his issue driven development approach to lab notebooks.

1. Structured Documentation:

   • Lab Notebooks: In scientific research, lab notebooks are used to document experiments, including the hypotheses, methods, observations, results, and conclusions. They provide a structured way to record every step of an experiment, making it possible to replicate the process, verify results, and learn from past work.
   • GitHub Issues: Similarly, Simon uses GitHub issues to document every task, idea, or problem in a structured manner. Each issue serves as a detailed record of the thought process, decisions made, and steps taken to solve a problem or implement a feature. This structure helps ensure that nothing is overlooked and that every aspect of the development process is documented.

2. Incremental Progress Tracking:

   • Lab Notebooks: In a lab notebook, scientists record their progress incrementally, noting down each observation, result, or adjustment as it happens. This allows them to track the progress of an experiment over time and adjust their approach based on real-time data.
   • GitHub Issues: In the same way, Simon tracks the progress of his development tasks by regularly updating issues with new information, insights, or adjustments. This continuous documentation allows him to track how a project evolves and helps in identifying when and where things changed, which is crucial for debugging and refining the work.

3. Reflection and Learning:

   • Lab Notebooks: Scientists often reflect on their experiments in their lab notebooks, noting what worked, what didn’t, and why. This reflection is crucial for learning and improving future experiments.
   • GitHub Issues: By documenting not just the steps taken but also the challenges faced and decisions made, GitHub issues become a tool for reflection. Simon can look back at issues to understand what worked and what didn’t, making it easier to apply those lessons to future tasks. This reflective practice can lead to better, more informed decision-making over time.

4. Transparency and Reproducibility:

   • Lab Notebooks: One of the key values of a lab notebook is that it allows others to reproduce an experiment. The detailed documentation means that another scientist can follow the steps exactly and verify the results.
   • GitHub Issues: Simon’s use of issues similarly allows for transparency in his development process. By making his thought process and actions visible in issues, others can understand why certain decisions were made and, if necessary, reproduce the steps taken to achieve a particular outcome. This is especially valuable in collaborative environments or in open-source projects where multiple contributors are involved.

5. Communication and Collaboration:

   • Lab Notebooks: In a research team, lab notebooks can be shared among team members, facilitating communication and collaboration. Everyone can see the progress, contribute ideas, and stay aligned on the goals and methods.
   • GitHub Issues: GitHub issues serve a similar role in software development teams. They are a central place where all discussions, decisions, and updates are recorded, making it easier for team members to stay informed, contribute, and collaborate effectively.