ccversion

A CLI tool for managing markdown document history.

ccversion is designed for individual developers to manage the history of Markdown documents (especially implementation logs, analysis documents, design intentions, etc.) in a .ccversion/docs/ directory in a simple, chronological manner.

Unlike Git, ccversion does not perform code version control (branches, merges, etc.) but specializes in recording document "snapshots" and "logs".

Features

• Document Snapshots: Save current state of markdown files with timestamp-based history
• History Management: View chronological history of document changes
• Diff Visualization: Compare different versions of documents
• File Restoration: Restore documents to previous versions
• Automatic Cleanup: Configurable history retention limits

Installation

Prerequisites

• Node.js 16.0.0 or higher

Install from npm

npm install -g ccversion

Install from Source

git clone <repository-url>
cd ccversion
npm install
npm run build
npm link

Usage

Initialize a Project

Initialize ccversion in your current directory:

ccversion init

This creates:

• .ccversion/ directory for configuration and history
• .ccversion/config.yaml with default settings
• .ccversion/docs/ for your markdown documents
• .ccversion/history/ for storing file snapshots

Save Document Snapshots

Save all markdown files in the .ccversion/docs/ directory:

ccversion save -m "Added notification system analysis"

Save specific files:

ccversion save -m "Updated design document" .ccversion/docs/design.md .ccversion/docs/api.md

Save interactively (will prompt for commit message):

ccversion save

View History

Show history for all files:

ccversion log

Show history for a specific file:

ccversion log .ccversion/docs/analysis.md

Compare Versions

Compare a specific version with the current file:

ccversion diff _docs/analysis.md 20250619105643

Compare two specific versions:

ccversion diff _docs/analysis.md 20250619105643 20250619120000

Restore Files

Restore a file to a previous version:

ccversion restore docs/analysis.md 20250619105643

This will:

• Create a backup of the current file (.backup extension)
• Restore the file to the specified version
• Prompt for confirmation before overwriting

Configuration

The configuration file is located at .ccversion/config.yaml:

docs_dir: ".ccversion/docs" # Directory containing markdown files
history_dir: ".ccversion/history" # Directory for storing history
max_history_entries: 100 # Maximum history entries per file

File Structure

your-project/
└── .ccversion/                     # ccversion data (add to .gitignore)
    ├── config.yaml                 # Configuration
    ├── commits.log                 # Commit history (JSONL format)
    ├── docs/                       # Your markdown documents
    │   ├── analysis.md
    │   └── design.md
    └── history/                    # File snapshots
        ├── 20250619105643_analysis.md
        └── 20250619120000_design.md

Recommended Document Structure

To better organize your documents, consider using this structure:

File Naming

Use date-prefixed names: yyyy-mm-dd_feature_name.md

Example: 2025-06-19_notification_system_analysis.md

YAML Front Matter

Add metadata at the beginning of your markdown files:

---
title: Notification System Analysis
feature_id: NOTIF-001
status: analysis_completed
related_items: [JIRA-1234, PR-567]
author: Your Name
date: 2025-06-19
purpose: Current state analysis of notification system and issue identification. Foundation for improvement proposals.
---

# Notification System Analysis

... document content ...

## Remaining Tasks

- User-specific notification settings investigation
- Retry strategy for delivery failures

The purpose field and Remaining Tasks section help maintain clear documentation of document intentions and incomplete tasks.

Commands Reference

Command	Description
ccversion init	Initialize ccversion in current directory
ccversion save [-m message] [files...]	Save document snapshots
ccversion log [file]	Show commit history
ccversion diff <file> <version1> [version2]	Show differences between versions
ccversion restore <file> <version>	Restore file to previous version

Version IDs

Version IDs are timestamp-based in the format YYYYMMDDHHMMSS (e.g., 20250619105643). You can also use partial hashes for identification.

Error Handling

ccversion provides clear error messages for common issues:

• Missing configuration (run ccversion init)
• File not found
• Invalid version IDs

Development

Building

npm run build

Testing

npm test

Linting

npm run lint

Formatting

npm run format

Publishing

To publish to npm:

npm run build
npm publish

License

MIT License - see LICENSE file for details.