https://github.com/darwincereska/notevc
Version control for markdown files
https://github.com/darwincereska/notevc
backup cli kotlin markdown md mit open-source opensource version-control versioncontrol versioning
Last synced: 19 days ago
JSON representation
Version control for markdown files
- Host: GitHub
- URL: https://github.com/darwincereska/notevc
- Owner: darwincereska
- License: mit
- Created: 2025-11-06T02:17:23.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2025-11-24T17:13:55.000Z (7 months ago)
- Last Synced: 2025-11-28T05:02:10.691Z (7 months ago)
- Topics: backup, cli, kotlin, markdown, md, mit, open-source, opensource, version-control, versioncontrol, versioning
- Language: Kotlin
- Homepage: https://notevc.org
- Size: 146 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
#  NoteVC: Version Control for Markdown
Block-level version control for markdown files. Track changes at the heading level, not just file level.
## Features
- **Block-level tracking**: Version control at heading granularity
- **Frontmatter support**: Control versioning with YAML frontmatter (tags, title, enabled flag)
- **Smart commits**: Only commits changed blocks
- **Block restoration**: Restore individual sections without affecting the entire file
- **Rich diffs**: See exactly which sections changed
---
## Installation
Build from source:
```bash
gradle build
```
The executable will be in `build/install/notevc/bin/notevc`
---
## Global Options
These options work with any command and should be placed before the command name:
- `--no-color`: Disable colored output
**Examples:**
```bash
notevc --no-color status
notevc --no-color diff
notevc --no-color log --oneline
notevc --no-color show a1b2c3d4
```
**Alternative methods to disable colors:**
- Set `NO_COLOR=1` environment variable: `NO_COLOR=1 notevc status`
- Pipe output: `notevc status | less` (colors auto-disabled)
- CI environments automatically disable colors
---
## Command Reference
### Repository Management
#### `notevc init [path]`
Initialize a new notevc repository in the current or specified directory.
```bash
notevc init # Initialize in current directory
notevc init ./notes # Initialize in specific directory
```
#### `notevc status` or `notevc st`
Show the status of tracked files and which blocks have changed.
```bash
notevc status
```
#### `notevc commit [options] "message"`
Create a commit (snapshot) of changed files.
**Options:**
- `--file `: Commit only a specific file
**Examples:**
```bash
notevc commit "Added new features" # Commit all changed files
notevc commit --file notes.md "Updated notes" # Commit specific file
```
---
### Viewing History
#### `notevc log [options]`
Show commit history with details.
**Options:**
- `--max-count ` or `-n `: Limit number of commits shown
- `--since
**Examples:**
```bash
notevc log # Show all commits
notevc log --max-count 5 # Show last 5 commits
notevc log --since 1d # Show commits from last day
notevc log --oneline # Compact format
notevc log --file # Show with file details
notevc log --file notes.md # Show commits affecting specific file
notevc log --file --oneline # Compact format with file info
```
#### `notevc show [options]`
Show detailed information about a specific commit, including block/file contents.
**Options:**
- `--file `: Show changes only for specific file
- `--block ` or `-b `: Show specific block content
- `--content` or `-c`: Show full file content at commit
**Examples:**
```bash
notevc show a1b2c3d4 # Show commit details
notevc show a1b2c3d4 --file notes.md # Show changes to specific file
notevc show a1b2c3d4 --file notes.md --content # Show full file content
notevc show a1b2c3d4 --file notes.md --block 1a2b3c # Show specific block
```
---
### Viewing Changes
#### `notevc diff [commit1] [commit2] [options]`
Show differences between commits or working directory with enhanced visual formatting.
**Options:**
- `--file `: Show diff for specific file only
- `--block ` or `-b `: Compare specific block only
**Examples:**
```bash
notevc diff # Show uncommitted changes (enhanced view)
notevc diff a1b2c3d4 # Compare working dir to commit
notevc diff a1b2c3d4 b5c6d7e8 # Compare two commits
notevc diff --file notes.md # Diff specific file
notevc diff a1b2c3d4 --file notes.md # Compare specific file to commit
notevc diff --block 1a2b3c --file notes.md # Compare specific block
notevc diff a1b2c3d4 --block 1a2b3c --file notes.md # Compare block to commit
```
**Visual Enhancements:**
- Clear separators (+++/---/~~~) for ADDED/DELETED/MODIFIED blocks
- Line-by-line diffs showing exact changes (+/- prefixes)
- Context lines shown in gray for unchanged content
- Block-level comparison for targeted analysis
---
### Restoration
#### `notevc restore [file] [options]`
Restore files or blocks from a specific commit.
**Options:**
- `--block ` or `-b `: Restore specific block only
**Examples:**
```bash
notevc restore a1b2c3d4 # Restore entire repository
notevc restore a1b2c3d4 notes.md # Restore specific file
notevc restore a1b2c3d4 notes.md --block 1a2b3c # Restore specific block
```
---
### Other Commands
#### `notevc version` or `notevc -v`
Show the version of notevc.
```bash
notevc version
```
---
## Frontmatter Support
Control versioning behavior with YAML frontmatter:
```markdown
---
enabled: "true" # Enable/disable tracking (default: true)
automatic: "true" # Auto-commit on changes (default: false)
title: "My Note" # Note title for sorting
tags: # Tags for categorization
- project
- important
---
# Your content here
```
**Frontmatter fields:**
- `enabled`: Set to "false" to exclude file from commits (default: true)
- `automatic`: Enable automatic commits (default: false)
- `title`: Custom title for the note
- `tags`: List of tags (array or comma-separated string)
---
## How It Works
NoteVC splits markdown files into blocks based on headings. Each block is:
- Identified by a stable hash
- Tracked independently
- Versioned separately
- **Compressed automatically** (GZIP) when content > 100 bytes
This means you can:
- See which sections changed
- Restore individual sections
- Track content at a granular level
- **Save disk space** with automatic compression
### Storage Optimization
NoteVC includes built-in compression for efficient storage:
- **Automatic GZIP compression** for block content over 100 bytes
- Typical compression ratio: 60-80% space savings for text
- Transparent decompression when reading
- No performance impact on small blocks