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:

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:

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.

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.

notevc status

notevc commit [options] "message"

Create a commit (snapshot) of changed files.

Options:

• --file <file>: Commit only a specific file

Examples:

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 <n> or -n <n>: Limit number of commits shown
• --since <time>: Show commits since specified time (e.g., "1h", "2d", "1w")
• --oneline: Show compact one-line format
• --file or -f [file]: Show file and block details for each commit

Examples:

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 <commit-hash> [options]

Show detailed information about a specific commit, including block/file contents.

Options:

• --file <file>: Show changes only for specific file
• --block <block-hash> or -b <block-hash>: Show specific block content
• --content or -c: Show full file content at commit

Examples:

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 <file>: Show diff for specific file only
• --block <block-hash> or -b <block-hash>: Compare specific block only

Examples:

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 <commit-hash> [file] [options]

Restore files or blocks from a specific commit.

Options:

• --block <block-hash> or -b <block-hash>: Restore specific block only

Examples:

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.

notevc version

---

Frontmatter Support

Control versioning behavior with YAML frontmatter:

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