# 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

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

## Common Commands

### Basic Usage

```bash
# 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

```bash
# 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:

1. Edit the `commitly` script directly
2. Test changes by running `./commitly` with test arguments
3. 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:
```bash
# 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.