How SwarmForge Enforces Role Bylines in Commits: Inside commit_msg_hook.bb

The commit_msg_hook.bb script automatically appends a "By [Role]." byline to every commit message by checking the SWARMFORGE_ROLE environment variable or inferring the role from a roles.tsv file, ensuring consistent attribution across the repository.

SwarmForge, an open-source framework maintained by Uncle Bob, ensures code traceability by requiring every Git commit to include a role-specific byline. The enforcement mechanism lives in swarmforge/scripts/commit_msg_hook.bb, a Babashka script that functions as a commit-msg Git hook. This script intercepts commit messages and automatically appends the correct role attribution before the commit is finalized.

How Role Detection Works

The script determines the author’s role through two distinct pathways implemented in the role function.

Environment Variable Lookup

If the SWARMFORGE_ROLE environment variable is set, the script uses its value directly. This approach is ideal for CI/CD pipelines or developers who switch roles frequently between projects.

export SWARMFORGE_ROLE="Engineer"
git commit -m "Implement new feature"

# Result: Commit message ends with "By Engineer."

File-Based Role Inference via roles.tsv

When the environment variable is absent, the script attempts to infer the role from a roles.tsv file. The roles-file function locates this file in either the repository’s .swarmforge directory or the common Git directory, while infer-role parses the entries.

According to the source code in swarmforge/scripts/commit_msg_hook.bb (lines 19-46), the infer-role function scans each line of the TSV file and compares the stored working-tree path (third column) with the current repository root. When a match is found, it returns the corresponding role name.

Building and Appending the Byline

Once the role is identified, the script constructs the standardized byline using the byline function:

(defn byline [role-name]
  (str "By " role-name "."))

The append-byline helper (lines 47-51) adds a blank line, the formatted byline, and a trailing newline to the existing message. This ensures consistent formatting regardless of whether the original message ended with newlines or not.

The Commit Message Patching Process

The -main entry point (lines 53-61) receives the path to the temporary commit message file that Git creates (typically .git/COMMIT_EDITMSG). It reads the current message content and checks whether the correct byline is already present. If the specific role byline is missing, the script writes the modified message back to the file with the appended byline.

If the script cannot locate a role—meaning neither the environment variable is set nor a matching entry exists in roles.tsv—it exits cleanly without modifying the message, allowing the commit to proceed unchanged.

Configuring Role Mappings with roles.tsv

The roles.tsv file enables per-project role assignment without environment variables. Each line follows a strict tab-separated format:

<role>	<description>	<working-tree-path>

For example:

Engineer	Develop new features	/home/user/projects/swarm-forge
Product Manager	Guide roadmap	/home/user/projects/swarm-forge

When you run git commit from /home/user/projects/swarm-forge, the infer-role function matches the repository root against the third column and identifies the committer as "Engineer".

Practical Usage Examples

Testing the Hook Manually

You can test the hook logic without creating a permanent commit:

echo "Test commit message" > /tmp/COMMIT_EDITMSG
bb swarmforge/scripts/commit_msg_hook.bb /tmp/COMMIT_EDITMSG
cat /tmp/COMMIT_EDITMSG

Viewing the Registration

The hook is registered by swarmforge/scripts/swarmforge.bb (lines 265-304), which configures Git to invoke commit_msg_hook.bb during the commit-msg phase.

Summary

• Automatic enforcement: The Babashka script functions as a Git commit-msg hook, intercepting every commit to verify role attribution.
• Dual detection method: Roles are determined via the SWARMFORGE_ROLE environment variable or inferred from roles.tsv paths.
• Non-blocking fallback: If no role is found, the script exits silently without preventing the commit.
• Standardized format: All bylines follow the exact pattern "By [Role]." with proper newline separation.
• Per-project configuration: The roles.tsv file allows different roles for different repositories based on working directory paths.

Frequently Asked Questions

What happens if I don't have a role configured?

If neither the SWARMFORGE_ROLE environment variable nor a matching entry in roles.tsv exists, the script exits without modifying your commit message. The commit proceeds normally, just without the SwarmForge byline.

Can I override the role for a single commit?

Yes. Set the SWARMFORGE_ROLE environment variable inline for a one-time override:

SWARMFORGE_ROLE="Product Manager" git commit -m "Update roadmap"

Where should the roles.tsv file be located?

The script searches for roles.tsv in two locations: the .swarmforge directory within your repository, or the common Git directory. According to the roles-file function in commit_msg_hook.bb, it checks these paths in order to find the appropriate role mappings.

How does the script handle existing bylines?

The -main function checks whether the commit message already contains the correct byline for the current role. If the exact "By [Role]." string is present, the script leaves the message unchanged. If the role has changed or the byline is missing, it appends the new correct byline to the end of the message.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}