DevJournal

A Git-integrated development journal for tracking project events and milestones.

Overview

DevJournal is a command-line tool that helps developers track important events, decisions, and milestones throughout a project's development lifecycle. It integrates directly with Git to automatically capture key development events while also providing a simple interface for manual entries.

Features

• 🔄 Git Integration: Automatically captures commits, merges, and branch events
• 📝 Event Tracking: Record development events, bug fixes, and milestones
• 💻 Command Line Interface: Simple CLI for managing journal entries
• 🔍 Powerful Search: Find and filter past events
• 📊 Timeline View: Get analytics on your development patterns
• 🤝 Team Collaboration: Share journal entries with your team
• 🏷️ Smart Categorization: Automatic categorization of development events

Installation

Global Installation (Recommended)

npm install -g devjournal

Local Project Installation

# Install as a dev dependency
npm install --save-dev devjournal

# Or install as a regular dependency
npm install --save devjournal

Quick Start

1. Initialize Journal

# Navigate to your Git repository
cd your-project

# Initialize journal (creates .devjournal directory)
devjournal init

# Initialize with automatic Git hooks installation
devjournal init --install-hooks

2. Add Manual Entries

# Add a simple entry
devjournal add "Implemented user authentication"

# Add entry with category and importance
devjournal add "Fixed critical database bug" --category bug --importance critical

# Add entry with description
devjournal add "Added new API endpoint" --description "Created REST endpoint for user profile management" --category development

# Interactive mode for detailed entries
devjournal add --interactive

3. View Journal Entries

# List recent entries (default: 10)
devjournal list

# List with filters
devjournal list --category bug --importance critical
devjournal list --search "authentication" --limit 5
devjournal list --after 2023-10-01 --before 2023-10-31

# List all entries
devjournal list --limit 0

4. Git Hooks Integration

# Install Git hooks for automatic tracking
devjournal hooks install

# List installed hooks
devjournal hooks list

Configuration

DevJournal can be configured using .devjournalrc in your project root or globally in your home directory:

{
  "journalDir": ".devjournal",
  "journalFile": "entries.json",
  "autoCommit": true,
  "captureCategories": ["feature", "bugfix", "refactor", "docs", "test"],
  "defaultCategory": "development",
  "defaultImportance": "minor",
  "timestampFormat": "iso",
  "hooks": {
    "postCommit": true,
    "postMerge": true,
    "postCheckout": false
  }
}

CLI Commands

devjournal init [options]

Initialize a journal in the current Git repository.

Options:

• -f, --force - Force re-initialization if journal already exists
• --init-git - Initialize a new Git repository if one does not exist
• --install-hooks - Install Git hooks automatically

devjournal add [options]

Add a new journal entry.

Options:

• -t, --title <title> - Entry title
• -d, --description <description> - Entry description
• -c, --category <category> - Entry category (development, database, server, bug, milestone, system, other)
• -i, --importance <importance> - Entry importance (critical, major, minor, info)
• -g, --git-data <gitData> - Associated Git data (commit hash, etc.)
• --interactive - Use interactive prompt to create entry
• --automatic - Entry is being created automatically (internal use)

devjournal list [options]

List journal entries with optional filtering.

Options:

• -c, --category <category> - Filter by category
• -i, --importance <importance> - Filter by importance
• -s, --search <search> - Search in title and description
• -l, --limit <limit> - Limit number of entries (default: 10, 0 for all)
• -b, --before <date> - Show entries before date (YYYY-MM-DD)
• -a, --after <date> - Show entries after date (YYYY-MM-DD)

devjournal hooks <action> [options]

Manage Git hooks.

Actions:

• install - Install Git hooks in the repository
• list - List installed hooks

Options:

• -h, --hook <hook> - Specific hook to install

Programmatic Usage

DevJournal can also be used as a Node.js module:

const devjournal = require('devjournal');

// Initialize journal
await devjournal.init('/path/to/repo');

// Add entry
await devjournal.addEntry('New feature implemented', {
  category: 'development',
  importance: 'major',
  description: 'Added user authentication system'
});

// Get entries
const entries = await devjournal.getEntries({
  category: 'bug',
  limit: 5
});

Requirements

• Node.js: >= 14.0.0
• Git: Must be run in a Git repository
• npm: For installation and updates

Project Status

DevJournal is actively maintained and ready for production use. We follow semantic versioning and welcome contributions.

Contributing

We welcome contributions! Please see our Contributing Guide for details.

License

MIT © DevJournal Contributors

Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions