Git Workflow

Git operations for the omnirepo using git-branchless.

Process

1. Inspect the current stack with git smartlog.
2. Stage only the intended changes with git add.
3. Commit with the required format and task trailer.
4. Restack if you amended or moved commits.
5. Verify with bild --test <namespace> and lint <namespace>.

Examples

git smartlog

git add .
git commit -m "Omni/Thing: Describe change"

git restack

Key Commands

View commit graph

git smartlog

Create a commit

git add .
git commit -m "Namespace: Short description"

Amend current commit

git add .
git amend

Move/restack commits

git move -s <source> -d <destination>
git restack

Commit Message Format

Namespace: Short description (max 72 chars)

Longer explanation if needed. Explain why, not just what.

Task-Id: t-123

Example:

Omni/Task: Add --namespace flag to create command

Allows associating tasks with specific code namespaces for
better organization and filtering.

Task-Id: t-456

Guidelines

• First line: Namespace: Short description
• Keep first line under 72 characters
• Blank line before body (if body needed)
• Body explains why, not just what
• Add Task-Id: trailer if working on a task

Before Committing

Always run:

bild --test <namespace>
lint <namespace>

Fix all errors before committing.

What NOT to Do

• ❌ git push without explicit user request
• ❌ git pull without explicit user request
• ❌ Force pushes or destructive operations
• ❌ Large commits mixing unrelated changes
• ❌ Commits that don’t compile
• ❌ Commits without running tests

When to Commit

DO commit:

• Completed features or bug fixes
• Working code that passes tests
• Significant milestones

DON’T commit:

• Work in progress (unless asked)
• Broken or untested code
• Temporary debugging changes

Stacking Workflow

For larger features, use stacking:

# Create first commit
git add . && git commit -m "Omni/Thing: Part 1 - types"

# Create second commit on top
git add . && git commit -m "Omni/Thing: Part 2 - implementation"

# View the stack
git smartlog

# Amend an earlier commit in the stack
git checkout <commit>
git add . && git amend
git checkout -   # back to tip
git restack      # rebase everything