mirror of
https://github.com/shumadrid/obsidian-git-changelog.git
synced 2026-07-22 05:42:16 +00:00
docs: update README
This commit is contained in:
shumadrid
parent
d907fc8984
commit
7d4d0ecdb3
4 changed files with 89 additions and 45 deletions
BIN
.github/vault-git-history-comparison-modal.png
vendored
Normal file
BIN
.github/vault-git-history-comparison-modal.png
vendored
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 62 KiB |
126
README.md
126
README.md
|
|
@ -13,6 +13,8 @@ A new [Obsidian](https://obsidian.md) plugin that utilizes Git commit history to
|
|||
- [Changelog Customizability](#changelog-customizability)
|
||||
- [Live Stats in the Status Bar for the Current Note](#live-stats-in-the-status-bar-for-the-current-note)
|
||||
- [Integration with Git Plugin's Diff View](#integration-with-git-plugins-diff-view)
|
||||
- [Compare Two Vault States in History](#compare-two-vault-states-in-history)
|
||||
- [See Changes since the Last Checkpoint](#see-changes-since-the-last-checkpoint)
|
||||
- [Data Loss Monitoring](#data-loss-monitoring)
|
||||
- [Common Causes of Data Loss](#common-causes-of-data-loss)
|
||||
- [How to Use](#how-to-use)
|
||||
|
|
@ -47,35 +49,36 @@ To easily see the what's new in future updates, it's recommended to use the [Plu
|
|||
- The files are sorted from most number of lines changed to least.
|
||||
- **Exclude Files and Folders:**
|
||||
|
||||
Usually you specify files and folders you want to exclude from your Git repository in the `.gitignore` file.
|
||||
- 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).
|
||||
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.
|
||||
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`, `/attachments` and `/.obsidian` folders, debug/log files, or conflict files generated by a syncing service that can clutter the changelog stats.
|
||||
Common examples for this: `/.trash`, `/attachments` 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.
|
||||
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.
|
||||
- **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.
|
||||
> [!NOTE]
|
||||
> 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.
|
||||
|
||||
- **Include items:**
|
||||
|
||||
Convert the `Exclude Files and Folders` list to an include list, while excluding everything else.
|
||||
- Convert the `Exclude Files and Folders` list to an include list, while excluding everything else.
|
||||
|
||||
An example case where this can come in handy is when you notice your vault misbehaving, you can trigger this setting and put `.obsidian` in the list to exclusively see changes made inside your configuration folder.
|
||||
- An example case where this can come in handy is when you notice your vault misbehaving, you can trigger this setting and put `.obsidian` in the list to exclusively see changes made inside your configuration folder.
|
||||
|
||||
Then you can easily investigate what settings recently changed and if some of the changes are the cause of your issue.
|
||||
Then you can easily investigate what settings recently changed and if some of the changes are the cause of your issue.
|
||||
|
||||
|
||||
|
||||
|
||||
### File Changelog View
|
||||
|
||||
- Shows the count of added and deleted lines for all previous versions of the active note.
|
||||
|
||||
|
||||
|
||||
|
||||
### Changelog Customizability
|
||||
|
||||
|
|
@ -85,11 +88,11 @@ To easily see the what's new in future updates, it's recommended to use the [Plu
|
|||
- Choose from 5 options to ignore whitespace changes with varying intensity.
|
||||
- **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.
|
||||
- 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.
|
||||
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.
|
||||
- Higher strictness results in detecting less renames.
|
||||
|
||||
### Live Stats in the Status Bar for the Current Note
|
||||
|
||||
|
|
@ -99,8 +102,24 @@ To easily see the what's new in future updates, it's recommended to use the [Plu
|
|||
|
||||
- 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.
|
||||
> [!WARNING]
|
||||
> Currently, only the "Split" diff view works. The "Unified" view shows inaccurate changes.
|
||||
|
||||
### Compare Two Vault States in History
|
||||
|
||||
- Use the `Compare two vault states in history` command to compare any two points in the vault's git history.
|
||||
|
||||
- All settings that apply to the vault changelog view also apply to this command.
|
||||
|
||||
|
||||
|
||||
### See Changes since the Last Checkpoint
|
||||
|
||||
- The easiest way to track all changes made to your vault over time is to use the `Show vault changes since the last checkpoint` command to open a temporary view that shows all changes that happened since the last checkpoint (meaning: the last time you ran this command and approved the shown changes).
|
||||
|
||||
- If you're someone who's always concerned about data integrity, you don't need to have the vault changelog view open all the time in order to track changes. 😁 Just run this command every now and then to inspect all changes made since the last time you checked. (Be it a few minutes ago or a few months.)
|
||||
|
||||
- All settings that apply to the vault changelog view also apply to this command.
|
||||
|
||||
## Data Loss Monitoring
|
||||
|
||||
|
|
@ -115,41 +134,60 @@ This plugin can also serve as a tool for early detection of data loss: if the di
|
|||
- 📜 Running faulty or outdated scripts
|
||||
- 🤖 **AI Tools**: They have a tendency to overwrite or delete random content.
|
||||
|
||||
### How to Use
|
||||
The result of all of this can be you asking yourself:
|
||||
|
||||
This plugin was not designed to accumulate all changes made inside an interval.
|
||||
> Wait, didn’t this note have more lines yesterday? 🤔
|
||||
|
||||
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 plugin tries it's best to help you answer that question. 😎
|
||||
|
||||
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.
|
||||
- The recommended way to monitor for data loss is to simply frequently run the [See Changes since the Last Checkpoint](#see-changes-since-the-last-checkpoint) command.
|
||||
|
||||
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.
|
||||
### How it works
|
||||
|
||||
A "Copy commit hash" context menu option is provided so that you can further investigate the commit tied to some suspicious version.
|
||||
- This plugin was not designed to accumulate all changes made inside an interval.
|
||||
|
||||
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).
|
||||
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.
|
||||
|
||||
But if some version of a file wasn't committed, you can still rely on the [File Recovery](https://help.obsidian.md/plugins/file-recovery) plugin, or the [Version history](https://help.obsidian.md/Obsidian+Sync/Version+history) feature to recover it.
|
||||
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.
|
||||
|
||||
Use the [Version History Diff](https://github.com/kometenstaub/obsidian-version-history-diff) plugin for easier navigation through those versions.
|
||||
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.
|
||||
|
||||
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:
|
||||
- A "Copy commit hash" context menu option is provided so that you can further investigate the commit tied to some suspicious version.
|
||||
|
||||
```bash
|
||||
git fsck -full
|
||||
```
|
||||
- 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](https://help.obsidian.md/plugins/file-recovery) plugin, or the [Version history](https://help.obsidian.md/Obsidian+Sync/Version+history) feature to recover it.
|
||||
|
||||
Use the [Version History Diff](https://github.com/kometenstaub/obsidian-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:
|
||||
|
||||
```bash
|
||||
git fsck -full
|
||||
```
|
||||
|
||||
## Limitations
|
||||
|
||||
⚠️There are quite a few limitations, and some of them are simply the result of choosing this specific approach to changelog management.
|
||||
|
||||
- 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.
|
||||
|
||||
- Interaction with submodules isn't tested yet!
|
||||
|
||||
## Roadmap
|
||||
|
|
@ -165,7 +203,7 @@ git fsck -full
|
|||
- [ ] 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.
|
||||
- [x] Command to compare any two points in the vault (repo) history.
|
||||
- [ ] Extensive per-file type stats.
|
||||
- [ ] Optimize computing stats performance.
|
||||
- [ ] Integrate the status bar and the file changelog view with [Git plugin's](https://github.com/Vinzent03/obsidian-git) diff views.
|
||||
|
|
@ -175,7 +213,13 @@ git fsck -full
|
|||
|
||||
## Alternatives
|
||||
|
||||
If you don't want to depend on Git, check out the [Vault Changelog](https://github.com/philoserf/obsidian-vault-changelog) plugin.
|
||||
If you don't want to depend on Git, check out the these alternative plugins:
|
||||
|
||||
- [Vault Changelog](https://github.com/philoserf/obsidian-vault-changelog) - tested and reliable, writes a changelog note to your vault
|
||||
|
||||
- [List Modified](https://github.com/franciskafieh/obsidian-list-modified) - popular, links all modified files meeting certain criteria to a note.
|
||||
|
||||
- [Edit History](https://github.com/antoniotejada/obsidian-edit-history) - similar to this plugin, but generates it's own history files instead of relying on other tools.
|
||||
|
||||
## FAQ
|
||||
|
||||
|
|
@ -197,23 +241,23 @@ If you don't want to depend on Git, check out the [Vault Changelog](https://gith
|
|||
|
||||
## Debugging
|
||||
|
||||
By default, debug messages for this plugin are hidden. They aren't intended for the user.
|
||||
- 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:
|
||||
To show them, enable `Verbose` mode in the console and run the following command:
|
||||
|
||||
```bash
|
||||
window.DEBUG.enable('git-changelog');
|
||||
```
|
||||
```bash
|
||||
window.DEBUG.enable('git-changelog');
|
||||
```
|
||||
|
||||
For more details, refer to [this guide](https://github.com/mnaoumov/obsidian-dev-utils?tab=readme-ov-file#debugging).
|
||||
- For more details, refer to [this guide](https://github.com/mnaoumov/obsidian-dev-utils?tab=readme-ov-file#debugging).
|
||||
|
||||
## Contributing
|
||||
|
||||
Feel free to submit a PR or a feature request. I'd especially appreciate help with styling and restructuring the code.
|
||||
- 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.
|
||||
- This plugin is in beta, so please do report all bugs that you find.
|
||||
|
||||
For easier development, [define](https://github.com/mnaoumov/generator-obsidian-plugin?tab=readme-ov-file#build-development-version) a `OBSIDIAN_CONFIG_DIR` variable and run `npm run dev`.
|
||||
- For easier development, [define](https://github.com/mnaoumov/obsidian-dev-utils?tab=readme-ov-file#build-development-version) a `OBSIDIAN_CONFIG_FOLDER` variable and run `npm run dev`.
|
||||
|
||||
## Credits
|
||||
|
||||
|
|
|
|||
|
|
@ -49,9 +49,9 @@
|
|||
"svelte-eslint-parser": "^0.43.0",
|
||||
"svelte-infinite": "^0.5.0",
|
||||
"svelte-preprocess": "^6.0.3",
|
||||
"type-fest": "^4.39.1",
|
||||
"typescript": "^5.8.2",
|
||||
"typescript-eslint": "^8.25.0",
|
||||
"type-fest": "^4.39.1"
|
||||
"typescript-eslint": "^8.25.0"
|
||||
},
|
||||
"overrides": {
|
||||
"boolean": "npm:dry-uninstall"
|
||||
|
|
|
|||
|
|
@ -51,8 +51,8 @@ export function addCommands(plugin: GitChangelogPlugin): void {
|
|||
{ reveal: true }
|
||||
);
|
||||
},
|
||||
id: `open-${COMPARE_TO_CHECKPOINT_VIEW_CONFIG.type}`,
|
||||
name: `Open ${COMPARE_TO_CHECKPOINT_VIEW_CONFIG.name.toLocaleLowerCase()}`
|
||||
id: `show-${COMPARE_TO_CHECKPOINT_VIEW_CONFIG.type}`,
|
||||
name: `Show ${COMPARE_TO_CHECKPOINT_VIEW_CONFIG.name.toLocaleLowerCase()}`
|
||||
});
|
||||
|
||||
plugin.addCommand({
|
||||
|
|
|
|||
Loading…
Reference in a new issue