Git Branch Protection

Git operations on protected branches carry outsized risk. Force-pushing to main or resetting production can affect your entire team. shellfirm detects the current git branch and escalates protection when you are on a protected branch.

How it works

When shellfirm evaluates a command, it runs:

git rev-parse --abbrev-ref HEAD

This returns the current branch name. If the command is not run inside a git repository, this step is silently skipped (no error, no slowdown).

The detected branch is compared against the list of protected branch patterns. If it matches, the risk level is set to Critical.

Default protected branches

Out of the box, these branches trigger Critical risk level:

Context label

When a protected branch is detected, shellfirm adds a label to the challenge banner:

Escalation behavior

On a protected branch (Critical risk level), the challenge is escalated to at least Yes by default:

Feature branches

Feature branches, topic branches, and any other branch not matching the protected patterns are treated as Normal risk. No escalation occurs.

Configuring protected branches

Edit ~/.shellfirm/settings.yaml to customize which branches are protected:

context:
  protected_branches:
    - main
    - master
    - production
    - staging
    - "release/*"
    - "hotfix/*"

Wildcard patterns

Patterns ending with /* match any branch starting with the prefix. For example, release/* matches release/v1.0, release/v2.0-rc1, and release/anything.

Only suffix wildcards are supported. Patterns like *-production or feature/*/main are not supported -- use exact names for those.

Practical examples

Force push on main

Same command on a feature branch

Notice the difference: on main the challenge is Yes (you must type "yes"), while on a feature branch it uses the default Math challenge.

Git reset on production

Team policy integration

Protected branches can also be configured in .shellfirm.yaml project policies. Team-level branch protections are merged with your global settings (union of both lists):

# .shellfirm.yaml in your repo
version: 1
context:
  protected_branches:
    - staging
    - "deploy/*"

This adds staging and deploy/* to the existing global list without removing main, master, or production.