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
status-all - Shows git status for all modified repositories
commitly - Main orchestration function that coordinates commit workflow
push-all - Pushes all repositories without committing
-main - CLI argument parsing and entry point

Workflow

Scan current directory for subdirectories with .git folders
Filter to only repos with uncommitted changes (for commit operations)
For each modified repo: stage all changes and commit with provided message
If push subcommand is used, push each successfully committed repo (or all repos if no commit message)
Report success/failure for each repository

Common Commands

Basic Usage

Note: These examples assume commitly is in your PATH.

# Show status of all modified subrepos
commitly status

# Commit changes across all modified subrepos (no push)
commitly "commit message"

# Commit and push changes
commitly push "commit message"

# Push only (no commit) - useful after manual commits
commitly push

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 (or ./commitly if running from the repo directory)
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

Push Subcommand Behavior

The push subcommand 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 push  # 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.

4.2 KiB Raw Blame History