commitctl

A CLI tool that helps you customize your git commit timestamps. Perfect for maintaining consistent commit histories or backdating commits for project organization.

Features

• 🕐 Custom Timestamps: Set precise commit timestamps with date, time, and timezone
• ⚙️ YAML Configuration: Simple, readable configuration files
• 🔧 Git Integration: Seamlessly works with existing git workflows
• 🌍 Timezone Support: Full timezone support for accurate timestamp management
• ✅ Validation: Built-in validation for git repositories and staged changes

Installation

From Source

git clone https://github.com/iamsuudi/commitctl.git
cd commitctl
go install

Download Binary

Download the appropriate binary for your system from the Releases page.

Usage

CLI Commands

commitctl provides several commands to help manage your commit timestamps:

init - Initialize Configuration

commitctl init
commitctl init --force          # Overwrite existing config
commitctl init --interactive    # Interactive setup

commit - Make Commits

commitctl commit -m "feat: add amazing new feature"
commitctl commit --dry-run -m "test: preview commit"  # Preview only

validate - Validate Setup

commitctl validate

config - Configuration Management

commitctl config preview        # Show current config
commitctl config validate       # Validate config
commitctl config edit           # Edit interactively

preview - Preview Commits

commitctl preview -m "test: preview commit"

help - Get Help

commitctl help
commitctl --help

1. Initialize Configuration

First, initialize commitctl in your git repository:

commitctl init

This creates a .commitctl/settings.yaml file with default settings:

version: 1

timestamp:
  date: 2025-01-01
  time:
    hour: 0
    minute: 0
    second: 0
  timezone: UTC

Interactive Setup

For a guided configuration experience:

commitctl init --interactive

This will prompt you through setting up your timestamp configuration step by step.

2. Customize Configuration

Edit .commitctl/settings.yaml to set your desired timestamp:

version: 1

timestamp:
  date: 2024-12-25  # Christmas day
  time:
    hour: 9
    minute: 30
    second: 0
  timezone: America/New_York  # Your local timezone

Interactive Configuration

You can also edit your configuration interactively:

commitctl config edit

3. Make Commits

Stage your changes as usual, then use commitctl:

git add .
commitctl commit -m "feat: add amazing new feature"

commitctl will use the timestamp from your configuration file for both the author and committer dates.

Preview Commits

Preview what your commit will look like before executing:

commitctl commit --dry-run -m "feat: add amazing new feature"

Or use the dedicated preview command:

commitctl preview -m "feat: add amazing new feature"

Advanced Features

Configuration Management

View Current Configuration

commitctl config preview

Validate Configuration

commitctl config validate

Edit Configuration Interactively

commitctl config edit

Validation

Validate your setup before making commits:

commitctl validate

This checks:

• Git repository status
• Configuration file validity
• Git state (staged changes, unmerged paths, etc.)

Shell Completion

Bash Completion

Add the following to your ~/.bashrc:

source /path/to/commitctl/completion/commitctl.bash

Zsh Completion

Add the following to your ~/.zshrc:

fpath+=("/path/to/commitctl/completion")
autoload -U compinit && compinit

Configuration Options

Timestamp Configuration

• date: Date in YYYY-MM-DD format (required)
• time.hour: Hour of the day (0-23, optional, defaults to 0)
• time.minute: Minute of the hour (0-59, optional, defaults to 0)
• time.second: Second of the minute (0-59, optional, defaults to 0)
• timezone: IANA timezone identifier (optional, defaults to UTC)

Example Configurations

Set commits to a specific historical date:

version: 1
timestamp:
  date: 2020-01-01
  timezone: UTC

Set commits to 9 AM local time:

version: 1
timestamp:
  date: 2024-12-25
  time:
    hour: 9
    minute: 0
  timezone: Europe/London

Advanced Usage

Force Initialize

If you want to overwrite an existing configuration:

commitctl init --force

Using with Different Timezones

commitctl supports all IANA timezone identifiers:

version: 1
timestamp:
  date: 2024-12-25
  time:
    hour: 15
    minute: 30
  timezone: Asia/Tokyo

Error Handling

commitctl provides helpful error messages for common issues:

• Not in a git repository
• No staged changes
• Invalid configuration format
• Invalid timezone
• Missing commit message

Requirements

• Git installed and in PATH
• Go 1.25.5 or later (if building from source)

Development

Build

go build -o commitctl

Test

go test ./...

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Built with Go and the gopkg.in/yaml.v3 library
• Inspired by the need for consistent commit timestamp management