# 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
- `pull-changes` - Executes `git pull` 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
- `pull-all` - Pulls changes for all repositories
- `-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 (for commit operations)
3. For each modified repo: stage all changes and commit with provided message
4. If `push` subcommand is used, push each successfully committed repo (or all repos if no commit message)
5. Report success/failure for each repository

## Common Commands

### Basic Usage

**Note:** These examples assume `commitly` is in your PATH.

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

# Pull changes for all subrepos
commitly pull
```

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

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