File Committer

A TypeScript class and CLI tool that automates versioning of a folder using Git with intelligent file purpose detection.

🚀 Features

• 🚀 Automated Git Commits: Automatically commit each file individually with meaningful messages
• 🤖 AI-Powered Purpose Detection: Use OpenAI GPT-4 to intelligently determine each file's purpose
• 🔍 Heuristic Analysis: Fallback to language-agnostic heuristics when AI is disabled
• 📁 Flexible Exclusions: Exclude specific paths or file patterns
• 🌐 GitHub Integration: Automatically push to GitHub after committing
• 🔒 Dry Run Mode: Simulate operations without making actual changes
• 📅 Preserved Timestamps: Commit dates match file modification times
• 🖥️ CLI Interface: Easy-to-use command line interface
• 📦 NPM Package: Ready to install and use in any project

📦 Installation

Global Installation (CLI Usage)

npm install -g mds-file-committer

Local Installation (Programmatic Usage)

npm install mds-file-committer

🖥️ CLI Usage

Quick Start

# Commit files in current directory with basic heuristic analysis
file-committer commit --name "Your Name" --email "[email protected]"

# Dry run to see what would happen
file-committer commit --name "Your Name" --email "[email protected]" --dry-run

# Use AI for purpose detection
file-committer commit --name "Your Name" --email "[email protected]" --ai

# Push to GitHub after committing
file-committer commit --name "Your Name" --email "[email protected]" --github "username/repo"

Full CLI Options

file-committer commit [options]

Options:
  -p, --path <path>              Path to folder (default: ".")
  -n, --name <name>              Git user name
  -e, --email <email>            Git user email  
  -x, --exclude <patterns...>    Exclude patterns (default: node_modules,dist,*.log,.env)
  -d, --dry-run                  Simulate without changes
  -a, --ai                       Use AI purpose detection
  -g, --github <username/repo>   Push to GitHub
  -h, --help                     Display help

Initialize Configuration

# Create a .env file with example configuration
file-committer init

Configuration

1. Environment Variables (optional but recommended):

# Create .env file
file-committer init

# Or manually create .env with:
OPENAI_API_KEY=your_openai_api_key_here
GIT_USER_NAME=Your Name
[email protected]

2. CLI Flags (override environment variables):

file-committer commit --name "John Doe" --email "[email protected]"

📚 Programmatic Usage

import { FileCommitter, GitUser, FileCommitterOptions } from 'mds-file-committer';

const gitUser: GitUser = {
  name: 'Your Name',
  email: '[email protected]'
};

const options: FileCommitterOptions = {
  excludePaths: ['node_modules', '*.log', 'dist', '.env'],
  dryRun: false,
  aiPurpose: true, // Requires OPENAI_API_KEY
  githubUsername: 'your-username',
  githubRepoName: 'your-repo'
};

const committer = new FileCommitter('/path/to/your/project', gitUser, options);
await committer.commit();

🔧 Configuration

API Reference

FileCommitter

Main class for automating Git versioning.

Constructor

new FileCommitter(folderPath: string, gitUser: GitUser, options?: FileCommitterOptions)

Parameters

• folderPath: Absolute or relative path to the folder to version
• gitUser: Object with name and email for Git commits
• options: Optional configuration object

Options

interface FileCommitterOptions {
  excludePaths?: string[];        // Paths/patterns to exclude
  dryRun?: boolean;              // Simulate without making changes
  githubUsername?: string;       // GitHub username for pushing
  githubRepoName?: string;       // GitHub repository name
  aiPurpose?: boolean;           // Use AI for purpose detection
}

Methods

• commit(): Execute the full commit process

File Purpose Detection

AI-Powered (when aiPurpose: true)

Uses OpenAI GPT-4 to analyze filename and content (first 1000 characters) to determine the file's purpose.

Heuristic-Based (default)

Uses pattern matching and content analysis to detect:

• Configuration files: package.json, *.config.js, *.yml, etc.
• Documentation: README.md, LICENSE, *.md files
• Test files: Files containing test, spec, or test patterns
• Database files: Migrations, schemas, seeds
• Source code: Components, controllers, models, services
• Assets: Stylesheets, images, static files

Example Commit Messages

Add package.json (Package configuration and dependency management)
Add UserController.ts (Controller handling HTTP requests and responses)
Add README.md (Documentation file providing project information)
Add auth.service.ts (Service layer for business logic implementation)

Error Handling

• Gracefully handles unreadable or binary files
• Continues processing if individual files fail
• Provides detailed logging with [FileCommitter] prefix
• Falls back to heuristic analysis if AI fails

Development

# Clone and install dependencies
git clone https://github.com/mwenaro/mds-file-committer.git
cd mds-file-committer
npm install

# Build the project
npm run build

# Run tests
npm test

# Run in development mode
npm run dev

# Run examples
npm run example
npm run example:advanced

📦 Publishing to NPM

Prerequisites

1. Create an npm account at npmjs.com
2. Login to npm: npm login
3. Update package.json with your details:
   • Change @your-username/file-committer to @yourusername/file-committer
   • Update author, repository URLs, etc.

Publishing Steps

# 1. Update version in package.json
npm version patch  # or minor/major

# 2. Build and test
npm run build
npm test

# 3. Publish to npm
npm publish

# 4. Install globally to test
npm install -g mds-file-committer

Automated Publishing with GitHub Actions

The package includes GitHub Actions workflow for automated testing and publishing on version tags.

🤝 Contributing

1. Fork the repository
2. Create your feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'Add amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

🐛 Issues and Support

• 🐛 Report bugs
• 💡 Request features
• 📖 Documentation
• 💬 Discussions

License

MIT