Git Changelog

A new Obsidian plugin that utilizes Git commit history to display dynamic changelogs in your sidebar. Also usable as a practical data loss monitoring tool.

Installation

Install the plugin from the official Community Plugins repository.

Important

Requires the Git plugin to be installed. Installing it and maintaining a Git repository can be beneficial, even if you rely on other syncing services.

Note

This plugin is currently in beta and still under development, so your existing settings may break after each update.

Features

Vault Changelog View

• Detects renamed and moved files separately.

• Shows the total count of lines added and deleted.

• Displays counts of files added, modified, deleted, and moved/renamed (total or text and non-text separately). If a file is both renamed/moved and modified, it will contribute towards the renamed files stats.

• Lists per file lines added and deleted, along with additional file statuses (Added, Renamed, Moved, or Deleted).

• Exclude Files and Folders:

  Usually you specify files and folders you want to exclude from your Git repository in the .gitignore file.

  Example of suggested items to put in .gitignore include OS specific files like .DS_Store, .obsidian/workspace.json and other plugins' cache files that constantly change and trigger commits even when no changes were made to the vault. These files usually don't hold any important user data and are regenerated easily (in case of needing to restore the vault from a backup).

  But this setting is useful if you want to keep some files backed up by your repository (e.g. because they're valuable), but exclude them from appearing in the vault changelog.

  Common examples for this: .trash and .obsidian folders, debug/log files, or conflict files generated by a syncing service that can clutter the changelog stats.

  Also use this setting to filter files and folders that already exist in previous commits, since specifying files in .gitignore doesn't remove them from previous commits.

  Context menu integration: To exclude a file or folder, just right-click on it inside the File explorer and select "Git changelog: Exclude" from the context menu, no need to manually define paths.

  For advanced users: If you configured your Git repository to be below the vault root directory, the paths should be relative to the Git repo, not the vault.

File Changelog View

• Shows the count of added and deleted lines for all previous versions of the active note.
• Only Markdown files are currently supported.

Warning

Using the "Expand all" toggle will reduce view performance. This will be fixed soon.

Changelog Customizability

• Set a custom day start time (if you're a night owl and want to track your actual days).

• Set a custom timezone to base the intervals on or detect it automatically.

• Choose to view hourly, daily, weekly, or monthly intervals.

• Adjust file rename detection strictness:

  Git can't actually track which files you renamed. Instead, it tries to detect renames by comparing the file contents of the old and new files.

  It can falsely mark new files as some old file getting renamed, and it can miss actual renames and mark them as separate files getting deleted and created.

  Higher strictness results in detecting less renames.

Live Stats in the Status Bar for the Current Note

• Set any interval for the status bar stats. Setting a frequent auto-commit interval in the Git plugin's settings will also allow for a more frequent status bar interval. But this interval shouldn't be more frequent than the auto-commit interval in order to maintain accuracy.

Integration with Git Plugin's Diff View

• Click on any file version in the changelog views to open the corresponding diff view showing the changes.

Warning

Currently only the "Split" diff view works. The "Unified" view shows inaccurate changes.

Data Loss Monitoring

This plugin can also serve as a tool for early detection of data loss: if the displayed changelog stats seem incorrect, unintended vault changes might have occurred.

Common Causes of Data Loss

• 🔄 Sync conflicts
• ❌ Faulty plugins
• ⛓️‍💥 Device malfunction
• 🤷‍♂️ Accidental text overwrites and other user errors
• 🤖 AI Tools: They have a tendency to overwrite or delete random content.

How to Use

This plugin was not designed to accumulate all changes made inside an interval.

For example, if you add a block of text, delete it, re-add it, then delete it again in the same day, the changelog will show zero modifications instead of a bunch of additions and deletions.

This is because this plugin only compares neighboring versions (intervals) directly, and if a block of text didn't exist in the previous interval and is also absent in the latest interval, zero changes have occurred.

Consequently, if you add text that gets lost within the same interval, you can detect this data loss not by seeing a high 'lines deleted' count, but by noticing a lack of expected additions.

A "Copy commit hash" context menu option is provided so that you can further investigate the commit tied to some suspicious version.

If some lost data was never committed, it won't be recoverable by Git. So it's recommended to configure a frequent (< 5 minutes) auto-commit interval (no need to manually stage and commit files).

But if some version of a file wasn't committed, you can still rely on the File Recovery plugin, or the Version history feature to recover it.

Use the Version History Diff plugin for easier navigation through those versions.

It's also recommended to occasionally check the integrity of your repo. To do this, open a terminal at your vault's location and just run:

git fsck -full

Limitations

• No meaningful way of tracking changes to canvas files.
• No mobile support yet.
• File changelog doesn't clear if opening a diff view but keeps showing stats for the previous note. This is intentional for quickly switching between versions but may result in showing stats for a closed note. This will be fixed in the future.
• Only status bar counts update live; other views refresh on each commit because of performance reasons.
• Assumes your vault has a linear commit & date history (which it should have). This plugin is not tested or made for repos with non-linear commit history.
• Git does not track changes inside other nested Git repositories—you should use proper Git submodules instead if you want to track changes for multiple repositories inside your vault.
• By Git design, files/folders specified in .gitignore aren't watched for changes.
• Git decides if a file is binary (non-text) or a text file by analyzing the file contents rather than looking at the file extension. If you rename a text file to have a .png extension, Git will still count its lines and treat it as a text file.
• If some data loss is only a few words/lines in a heavily edited file, you probably won't notice it. Even though those few lines could have been important.
• When using this plugin, the Git plugin status bar branch indicator may get duplicated. (weird)
• Interaction with submodules isn't tested yet!

Roadmap

• Partial mobile support.
• Better view performance.
• Stable and consistent styling.
• Dedicated moved lines/words detection.
• File changelog support for all files.
• Add a word counting option (currently defaults to line counting).
• Syncthing integration (better conflict file handling).
• Visual representation of repo history.
• Code cleanup and refactoring.
• Improve README.
• Folder stats in the Vault changelog view.
• Command to compare the current state of the vault (repo) to any point in history.
• Extensive per-file type stats.
• Optimize computing stats performance.
• Integrate the status bar and the file changelog view with Git plugin's diff views.
• Notify if the amount of changes between neighboring commits exceeds a threshold.
• File & folder stats inside the File explorer view.

Alternatives

If you don't want to depend on Git, check out the Vault Changelog plugin.

FAQ

Will this plugin alter my Git repository/config?

• No. This plugin is intended to be read-only and does not alter any Git configurations. However, it's in beta, so bugs are possible.

I have been using Obsidian for some time but don't have a Git repo set up. Can I still use this plugin to view the history of my vault?

• No. 😔

Debugging

By default, debug messages for this plugin are hidden. They aren't intended for the user.

To show them, enable Verbose mode in the console and run the following command:

window.DEBUG.enable('git-changelog');

For more details, refer to this guide.

Contributing

Feel free to submit a PR or a feature request. I'd especially appreciate help with styling and restructuring the code.

This plugin is in beta, so please do report all bugs that you find.

For easier development, define a OBSIDIAN_CONFIG_DIR variable and run npm run dev.

Credits

• FlorianWoelki for settings code inspiration.

• Plugin template was generated with generator-obsidian-plugin, a modern Obsidian plugin template.

• obsidian-dev-utils is used extensively throughout the plugin to simplify development.

• A lot of functions are adapted from the Git plugin.