cclogs

A CLI tool for managing markdown document history.

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

Unlike Git, cclogs 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 cclogs

Install from Source

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

Usage

Initialize a Project

Initialize cclogs in your current directory:

cclogs init

This creates:

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

Save Document Snapshots

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

cclogs save -m "Added notification system analysis"

Save specific files:

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

Save interactively (will prompt for commit message):

cclogs save

View History

Show history for all files:

cclogs log

Show history for a specific file:

cclogs log .cclogs/docs/analysis.md

Compare Versions

Compare a specific version with the current file:

cclogs diff _docs/analysis.md 20250619105643

Compare two specific versions:

cclogs diff _docs/analysis.md 20250619105643 20250619120000

Restore Files

Restore a file to a previous version:

cclogs 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 .cclogs/config.yaml:

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

File Structure

your-project/
└── .cclogs/                     # cclogs 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
cclogs init	Initialize cclogs in current directory
cclogs save [-m message] [files...]	Save document snapshots
cclogs log [file]	Show commit history
cclogs diff <file> <version1> [version2]	Show differences between versions
cclogs 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

cclogs provides clear error messages for common issues:

• Missing configuration (run cclogs 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.