124 lines
4.4 KiB
Markdown
124 lines
4.4 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
|
|
- `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.
|