# How Commit Validation in `swarm_handoff.sh` Ensures Unique Commit Abbreviations

> Learn how swarm_handoff.sh validates commit abbreviations using Git rev-parse and merge-base to guarantee unique short SHAs, ensuring clear commit references.

- Repository: [Robert C. Martin/swarm-forge](https://github.com/unclebob/swarm-forge)
- Tags: how-to-guide
- Published: 2026-08-30

---

**The `swarm_handoff.bb` script validates commit abbreviations by generating a 10-character short SHA and verifying it resolves to exactly one unambiguous commit using Git's native `rev-parse` and `merge-base --is-ancestor` commands.**

The [`swarmhandoff.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmhandoff.sh) wrapper script in the `unclebob/swarm-forge` repository delegates to a Babashka script that enforces **strict commit abbreviation uniqueness** before accepting any hand-off draft. This prevents ambiguous short SHAs from corrupting Swarm Forge's task routing workflow.

## Generating a Deterministic Short SHA

The validation pipeline begins in `swarmforge/scripts/swarm_handoff.bb` with the `worktree-head` function. This generates a consistent 10-character abbreviation of the current `HEAD` commit:

```clojure
(defn worktree-head []
  (let [result (command (git-cwd) "git" "rev-parse" "--short=10" "HEAD")]
    (when-not (zero? (:exit result))
      (exit! 1 "Cannot read HEAD commit."))
    (str/trim (:out result))))

```

This 10-character length provides sufficient entropy to avoid collisions in typical repository sizes while remaining human-readable in hand-off drafts.

## Verifying Unambiguous Commit Resolution

The core uniqueness check occurs in the `commit-on-sender-branch?` function (lines 103-105). Rather than parsing output, the script leverages Git's exit codes to detect ambiguity:

```clojure
(defn commit-on-sender-branch? [sha]
  (zero? (:exit (command (git-cwd) "git" "merge-base" "--is-ancestor" sha "HEAD"))))

```

Git's `merge-base --is-ancestor` command returns **non-zero status** if:
- The abbreviation matches **multiple commits**
- The commit does **not exist** in the repository
- The abbreviation is **malformed**

When any of these conditions occur, `swarm_handoff.bb` aborts via `exit!` with a non-zero status, rejecting the hand-off draft before it enters the queue.

## Validating Descendant Relationships

For hand-offs that specify a `task_base_commit`, the script performs an additional uniqueness check at lines 107-109. It verifies the new commit descends from the task's base using the same `merge-base --is-ancestor` pattern:

```clojure
(defn commit-descends-from? [sha base]
  (zero? (:exit (command (git-cwd) "git" "merge-base" "--is-ancestor" base sha))))

```

This **double verification** guarantees that:
1. The abbreviation points to exactly one commit object
2. That commit occupies the correct position in the branch history

## Failure Modes and Script Behavior

The validation strictness produces clear error conditions:

```bash

# Example: Successful validation

$ ./swarmhandoff.sh draft.handoff

# Hand-off accepted – the abbreviation resolves to a single commit.

# Example: Failure due to ambiguous abbreviation

$ ./swarmhandoff.sh draft.handoff
CURRENT COMPLETION FAILED after handoff queued.

# The script exited because git rev-parse --verify <abbr> was ambiguous.

```

## Source Files for Commit Validation

| File | Purpose |
|------|---------|
| `swarmforge/scripts/swarm_handoff.bb` | Main validation logic (`worktree-head`, `commit-on-sender-branch?`, `commit-descends-from?` functions) |
| [`swarmforge/scripts/swarmhandoff.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/swarmhandoff.sh) | Thin shell wrapper that invokes `swarm_handoff.bb` |
| [`swarmforge/scripts/commit-msg-hook.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/commit-msg-hook.sh) | Git hook applying identical rules during local commits |

## Summary

- **10-character abbreviations** are generated via `git rev-parse --short=10` for optimal collision resistance
- **`git merge-base --is-ancestor`** provides exit-code-based verification of unique, unambiguous commit resolution
- **Descendant validation** ensures commit abbreviations reference commits in the correct historical position
- **Non-zero exit propagation** immediately rejects invalid hand-offs before queue entry

## Frequently Asked Questions

### What happens if two commits share the same 10-character abbreviation?

The `commit-on-sender-branch?` function detects this via Git's `merge-base --is-ancestor` returning non-zero or failing outright. According to the `unclebob/swarm-forge` source code, the script calls `exit!` with status 1, rejecting the hand-off draft with a failure message.

### Why use `merge-base --is-ancestor` instead of `rev-parse --verify`?

While `rev-parse --verify` checks for valid object names, `merge-base --is-ancestor` simultaneously validates **both** that the abbreviation resolves unambiguously **and** that the commit exists on the current branch lineage. This single-command efficiency matches the script's minimal dependency philosophy.

### Does the validation work with shallow clones or partial checkouts?

Yes. The `command` helper in `swarm_handoff.bb` executes Git operations against the actual working directory via `(git-cwd)`. As implemented in `unclebob/swarm-forge`, the validation respects whatever commit objects Git can resolve in the current environment, though very shallow clones increase collision probability for any fixed abbreviation length.

### Where is this validation reused outside hand-off scripts?

The [`swarmforge/scripts/commit-msg-hook.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/commit-msg-hook.sh) Git hook enforces identical commit-abbreviation rules during local development, ensuring consistency between individual commits and Swarm Forge hand-offs.