112 lines
3.9 KiB
Markdown
112 lines
3.9 KiB
Markdown
# 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.
|