CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Overview

Commitly is a Babashka CLI tool for managing commits across multiple independent git repositories within a monorepo structure. It automates committing and pushing changes that span multiple subrepos with a single command.

Architecture

Core Concept

The tool operates on a "monorepo of repos" pattern where:

The parent directory contains multiple subdirectories, each with its own .git directory
Each subrepo is an independent git repository (not git submodules)
Changes often span multiple repositories and need consistent commit messages

Code Structure

The entire implementation is a single Babashka script (commitly) with these key functions:

find-subrepos - Discovers all directories containing .git in the current directory
has-changes? - Uses git status --porcelain to detect uncommitted changes
commit-changes - Executes git add -A and git commit -m for a repo
push-changes - Executes git push for a repo
commitly - Main orchestration function that coordinates the workflow
-main - CLI argument parsing and entry point

Workflow

Scan current directory for subdirectories with .git folders
Filter to only repos with uncommitted changes
For each modified repo: stage all changes and commit with provided message
If -p flag is present, push each successfully committed repo
Report success/failure for each repository

Common Commands

Basic Usage

# Commit changes across all modified subrepos
./commitly "commit message"

# Commit and push changes
./commitly -p "commit message"

# Push only (no commit) - useful after manual commits
./commitly -p

Running via Babashka Tasks

# Alternative way to run using bb.edn tasks
bb run "commit message"

Development

The script is self-contained with no external dependencies beyond Babashka standard library (babashka.process, babashka.fs). To modify:

Edit the commitly script directly
Test changes by running ./commitly with test arguments
The script is executable via shebang #!/usr/bin/env bb

Important Implementation Details

Error Handling

Each repository operation is independent - one failure doesn't stop others
Failed commits/pushes are collected and reported at the end
Non-zero exit code (1) if any operations fail
Empty commit message validation prevents accidental empty commits

Special `-p` Flag Behavior

The -p flag has dual behavior:

With commit message: commits then pushes
Without commit message: pushes only (skips committing)

This allows workflows like:

# Manual commits in individual repos, then bulk push
cd service-manager && git commit -m "specific message"
cd ../www && git commit -m "different message"
cd ..
./commitly -p  # Push all repos

Process Execution

Uses babashka.process/shell with:

:continue true - Allows capturing errors without throwing exceptions
:dir - Sets working directory for each git command
:out :string and :err :string - Captures output for reporting

Context: Monorepo Usage

This tool is designed for the ajet-industries monorepo which contains:

service-manager/ - Clojure orchestration service
www/ - Clojure dashboard website
gateway/ - Nginx reverse proxy configuration
commitly/ - This tool itself
Other independent service repos

Each subrepo has its own git remote and CI/CD pipeline (Gitea Actions). When a cross-cutting change is made (e.g., updating CLAUDE.md files, shared configuration), commitly ensures all affected repos get consistent commit messages.

Skills Integration

The skills/ directory contains documentation for Claude Code skills. When working on commitly functionality or explaining its usage to users, reference skills/commitly.md for detailed usage patterns and examples.

3.9 KiB Raw Blame History