Git

Comprehensive guide for git operations, GitHub CLI usage, commit practices, and version control workflows.

Local workflow policy

Before implementation or worktree operations, read ~/.pi/agent/workflows/worktrees.md. It owns checkout selection, workspace-manager precedence, agent permission, issue identity, and cleanup. Its rules take precedence over the generic command examples below.

• Use Conventional Commits unless the repository defines another format. Commits, PRs, and tags MUST NOT include AI attribution.
• Before a branch's first push, make its name earn the PR: lowercase type/short-slug (or the issue's gitBranchName) that names the change, not a placeholder like patch-1, fix, wip, or a tool-generated slug. Rename with git branch -m while the branch is still local only. MUST NOT rename a branch that is already on the remote, has an open PR, or belongs to a Superset workspace; those keep their name, so choose it well at creation.
• Deliver one PR unless Justin explicitly requests a stack. Each stack branch runs full CI; restacking reruns it across the stack. Do not routinely rebase or sync a stack; restack only for conflicts or immediately before merge.
• A stack should have one final migration. Collapse development migrations before delivery unless separate migrations are required for safe rollout. Confirm before running migrations.
• Link an existing task issue when publishing and verify the linkage. Do not invent an issue requirement for tasks without one. Outside the Mastra internal exception below, ask for an existing issue when repository policy requires one. Never create GitHub issues in Mastra repositories.
• Run applicable existing checks before commits or pushes. Publication, merges, and reviewer requests require their respective user authorization.

Git CLI Essentials

Status & Information

# Current state
git status                    # Working tree status
git status -sb                # Short format with branch info

# View changes
git diff                      # Unstaged changes
git diff --staged             # Staged changes
git diff HEAD~3               # Last 3 commits
git diff main...HEAD          # Changes since branching from main

# History
git log --oneline -20         # Last 20 commits, compact
git log --graph --oneline     # Visual branch history
git log --stat                # With file change stats
git log -p path/to/file       # History of specific file
git log --author="name"       # Filter by author

# Blame & inspection
git blame path/to/file        # Line-by-line attribution
git show <commit>             # Show commit details
git show <commit>:path/file   # Show file at specific commit

Staging & Committing

# Stage changes
git add <file>                # Stage specific file
git add .                     # Stage all changes
git add -p                    # Interactive staging (patch mode)
git add -u                    # Stage modified/deleted, not new

# Unstage
git restore --staged <file>   # Unstage file (keep changes)
git reset HEAD <file>         # Alternative unstage

# Commit
git commit -m "message"       # Commit with message
git commit                    # Open editor for message
git commit -am "message"      # Stage tracked + commit
git commit --amend            # Amend last commit (CAUTION)
git commit --amend --no-edit  # Amend without changing message

Branches

# List & info
git branch                    # List local branches
git branch -a                 # List all (local + remote)
git branch -vv                # With tracking info

# Create & switch
git branch <name>             # Create branch
git switch <name>             # Switch to branch
git switch -c <name>          # Create and switch
git checkout -b <name>        # Alternative create+switch

# Delete
git branch -d <name>          # Delete (safe - checks merged)
git branch -D <name>          # Force delete (CAUTION)

# Rename
git branch -m <old> <new>     # Rename branch

Remote Operations

# Fetch & pull
git fetch                     # Fetch all remotes
git fetch origin              # Fetch specific remote
git pull                      # Fetch + merge
git pull --rebase             # Fetch + rebase (cleaner history)

# Push
git push                      # Push current branch
git push -u origin <branch>   # Push and set upstream
git push --force-with-lease   # Safe force push (CAUTION)
git push --force              # Force push (DANGER)

# Remote management
git remote -v                 # List remotes
git remote add <name> <url>   # Add remote
git remote set-url origin <url>  # Change remote URL

Merging & Rebasing

# Merge
git merge <branch>            # Merge branch into current
git merge --no-ff <branch>    # Merge with merge commit
git merge --abort             # Abort failed merge

# Rebase
git rebase main               # Rebase onto main
git rebase -i HEAD~3          # Interactive rebase last 3
git rebase --abort            # Abort failed rebase
git rebase --continue         # Continue after fixing conflicts

# Cherry-pick
git cherry-pick <commit>      # Apply specific commit
git cherry-pick --abort       # Abort cherry-pick

Undoing Changes

# Discard working changes
git restore <file>            # Discard file changes
git restore .                 # Discard all changes
git checkout -- <file>        # Alternative discard

# Reset commits
git reset --soft HEAD~1       # Undo commit, keep staged
git reset --mixed HEAD~1      # Undo commit, keep unstaged (default)
git reset --hard HEAD~1       # Undo commit, discard changes (DANGER)

# Revert (safe undo)
git revert <commit>           # Create commit that undoes changes
git revert HEAD               # Revert last commit

# Recovery
git reflog                    # View all HEAD movements
git reset --hard <reflog-ref> # Recover lost commits

Stashing

git stash                     # Stash changes
git stash -m "message"        # Stash with message
git stash list                # List stashes
git stash pop                 # Apply and remove latest
git stash apply               # Apply without removing
git stash drop                # Remove latest stash
git stash clear               # Remove all stashes

GitHub CLI (gh)

Authentication

gh auth login                 # Interactive login
gh auth status                # Check auth status
gh auth logout                # Logout

Pull Requests

# Create
gh pr create                  # Interactive PR creation
gh pr create --title "..." --body "..."
gh pr create --draft          # Create as draft
gh pr create --base main      # Specify base branch

# List & view
gh pr list                    # List open PRs
gh pr list --state all        # All PRs
gh pr view                    # View current branch's PR
gh pr view <number>           # View specific PR
gh pr view --web              # Open in browser

# Review & merge
gh pr review                  # Start review
gh pr review --approve        # Approve PR
gh pr review --request-changes -b "feedback"
gh pr merge                   # Merge PR
gh pr merge --squash          # Squash merge
gh pr merge --rebase          # Rebase merge
gh pr merge --delete-branch   # Delete branch after merge

# Checkout
gh pr checkout <number>       # Checkout PR locally

Issues

# Create & list
gh issue create               # Interactive issue creation
gh issue create --title "..." --body "..."
gh issue list                 # List open issues
gh issue view <number>        # View issue

# Manage
gh issue close <number>       # Close issue
gh issue reopen <number>      # Reopen issue
gh issue comment <number> -b "..."  # Add comment

Repository

gh repo view                  # View current repo
gh repo clone <owner/repo>    # Clone repository
gh repo fork                  # Fork current repo
gh repo create                # Create new repo

Workflows & Actions

gh run list                   # List workflow runs
gh run view <id>              # View run details
gh run watch <id>             # Watch run in progress
gh run rerun <id>             # Rerun workflow

gh workflow list              # List workflows
gh workflow run <name>        # Trigger workflow

API Access

gh api repos/{owner}/{repo}/pulls
gh api repos/{owner}/{repo}/issues
gh api repos/{owner}/{repo}/pulls/<n>/comments

Conventional Commits

Format

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

Types

Examples

# Feature
git commit -m "feat(auth): add JWT refresh token support"

# Bug fix
git commit -m "fix(api): handle null response in user endpoint"

# Breaking change
git commit -m "feat(api)!: remove deprecated v1 endpoints

BREAKING CHANGE: v1 API endpoints are no longer available"

# With issue reference
git commit -m "fix(cart): prevent negative quantities

Closes #123"

# Multi-line (use editor)
git commit
# Opens editor:
# feat(dashboard): add real-time notifications
#
# - Implement WebSocket connection
# - Add notification bell component
# - Store notifications in local state
#
# Closes #456

Scopes (Project-Specific)

Common scopes:

• api, auth, ui, db, config
• deps, ci, docs, test
• Feature names: cart, checkout, profile

Branching Strategies

Trunk-Based Development (Recommended)

main ─────●─────●─────●─────●─────●─────
           \   /       \   /
            ●─●         ●─●
         (short-lived feature branches)

Rules:

• Main is always deployable
• Feature branches SHOULD live < 2 days
• MUST merge via PR with CI checks
• MUST delete branches after merge

Workflow:

git switch -c feat/add-login
# ... make changes ...
git push -u origin feat/add-login
gh pr create --base main
# After approval:
gh pr merge --squash --delete-branch

GitHub Flow

main ─────●─────●─────●─────●─────●─────
           \       /
            ●─────●
          (feature branch)

Workflow:

1. Create branch from main
2. Add commits
3. Open PR
4. Review & discuss
5. Merge to main
6. Deploy

Git Flow (Complex Projects)

main     ─────●───────────────●─────────
              │               │
develop  ─────●─────●─────●───●─────●───
               \   /       \     /
feature         ●─●         \   /
                         release─●

Branches:

• main - production releases
• develop - integration branch
• feature/* - new features
• release/* - release prep
• hotfix/* - production fixes

Common Workflows

Feature Development

# 1. Start fresh
git switch main
git pull

# 2. Create feature branch
git switch -c feat/user-profile

# 3. Work in small commits
git add -p                    # Stage selectively
git commit -m "feat(profile): add avatar upload"
# ... more work ...
git commit -m "feat(profile): add bio field"

# 4. Keep up with main
git fetch origin
git rebase origin/main        # Or merge

# 5. Push and create PR
git push -u origin feat/user-profile
cat > /tmp/pr-body.md <<'EOF'
Adds avatar upload (S3) and a markdown bio field to the profile page.

| | Light | Dark |
| --- | --- | --- |
| After | ![Profile page with avatar and bio in light mode](./after-light.png) | ![Profile page with avatar and bio in dark mode](./after-dark.png) |

Tested: uploaded png/jpg/webp, bio with html entities renders escaped.
EOF
gh pr create --title "feat(profile): add user profile page" \
  --body-file /tmp/pr-body.md \
  --attach ./after-light.png --attach ./after-dark.png

# 6. After approval
gh pr merge --squash --delete-branch
git switch main
git pull

Hotfix

# 1. Branch from main
git switch main
git pull
git switch -c hotfix/fix-login-crash

# 2. Fix and commit
git commit -m "fix(auth): handle null session token"

# 3. Push immediately
git push -u origin hotfix/fix-login-crash
gh pr create --title "fix(auth): critical login crash" --body "..."

# 4. Fast-track review and merge
gh pr merge --merge --delete-branch

Conflict Resolution

# During merge/rebase, if conflicts occur:

# 1. See conflicted files
git status

# 2. Open conflicted file - look for markers:
# <<<<<<< HEAD
# your changes
# =======
# their changes
# >>>>>>> branch-name

# 3. Edit to resolve (remove markers, keep correct code)

# 4. Mark resolved
git add <resolved-file>

# 5. Continue
git merge --continue          # If merging
git rebase --continue         # If rebasing

# Or abort
git merge --abort
git rebase --abort

Squashing Commits

# Before pushing (interactive rebase)
git rebase -i HEAD~5          # Last 5 commits

# In editor, change 'pick' to 'squash' or 's':
# pick abc1234 First commit
# squash def5678 WIP
# squash ghi9012 More WIP
# squash jkl3456 Fix typo
# squash mno7890 Final touches

# Save, then edit combined commit message

# Alternative: squash merge in PR
gh pr merge --squash

Mastra internal pull requests

When Justin works in mastra-ai/mastra, treat the pull request as an internal core-contributor change. The agent MUST NOT require, create, or link a GitHub issue unless Justin asks for one or the task already has one. The linked-issue requirement in CONTRIBUTING.md applies to external contributions and MUST NOT block these pull requests.

Every Mastra pull request MUST have a Linear ticket attached (compliance policy, SOC2/HIPAA). Use the task's existing Linear issue, or search Linear for an existing issue covering the work before starting; link it through the repository integration and verify the issue shows the pull request, or include the identifier in the branch name and pull request when automatic linking is unavailable. When no covering issue exists, stop before opening the pull request and ask Justin for one; do not create Linear issues without his explicit permission.

Pull request workflow

MUST load and follow preparing-pull-requests when preparing, opening, updating, or finalizing a PR. It owns the body format, Justin's voice, no-slop pass, screenshots, diff explanations, and publication checks. For UI work intended for a PR, load it before implementation so the before state is captured in time.

Safety Practices

MUST NOT Do (Without Explicit Permission)

# Force push to shared branches
git push --force origin main     # DANGER
git push --force origin develop  # DANGER

# Hard reset shared branches
git reset --hard origin/main     # On shared branch = DANGER

# Delete remote branches others use
git push origin --delete <shared-branch>

MUST Ask Before

git push --force-with-lease      # Safer force push, but still ask
git rebase                       # On shared branches
git reset --hard                 # Destructive
git clean -fd                    # Removes untracked files

Safe Practices

# SHOULD use --force-with-lease instead of --force
git push --force-with-lease origin feat/my-branch

# MUST check before destructive operations
git status
git log --oneline -5
git diff

# SHOULD stash before switching with changes
git stash
git switch other-branch
git switch -
git stash pop

# MAY use reflog for recovery
git reflog                       # Find lost commits
git reset --hard HEAD@{2}        # Recover

Commit Message Best Practices

MUST

• Use imperative mood: "add feature" not "added feature"
• Keep subject line < 72 characters
• Capitalize first letter of subject
• No period at end of subject
• Separate subject from body with blank line
• Explain "what" and "why" in body, not "how"
• Reference the task's issue when one exists: "Closes #123" or "Fixes #456"

MUST NOT

• Use vague messages: "fix bug", "update code", "WIP"
• Combine unrelated changes in one commit
• Include generated files in commits
• Commit secrets, credentials, or .env files

Template

<type>(<scope>): <what changed>

<why this change was needed>

<any additional context>

<footer: issues, breaking changes>

Git Configuration

Recommended Settings

# Identity
git config --global user.name "Your Name"
git config --global user.email "you@example.com"

# Editor
git config --global core.editor "code --wait"

# Default branch
git config --global init.defaultBranch main

# Pull strategy
git config --global pull.rebase true

# Push default
git config --global push.default current

# Aliases
git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.ci commit
git config --global alias.st status
git config --global alias.lg "log --oneline --graph --decorate"

Useful Aliases

# Add to ~/.gitconfig [alias] section:
[alias]
    # Short status
    s = status -sb
    
    # Pretty log
    lg = log --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit
    
    # Last commit
    last = log -1 HEAD --stat
    
    # Undo last commit (keep changes)
    undo = reset --soft HEAD~1
    
    # Amend without editing message
    amend = commit --amend --no-edit
    
    # List branches by recent
    recent = branch --sort=-committerdate --format='%(committerdate:relative)%09%(refname:short)'

Quick Reference

Daily Workflow

# Morning sync
git fetch && git status

# Before starting work
git switch main && git pull
git switch -c feat/new-thing

# During work
git add -p && git commit -m "..."

# Before pushing
git fetch origin
git rebase origin/main

# Push and PR
git push -u origin HEAD
gh pr create

Emergency Commands

# Undo last commit (keep changes)
git reset --soft HEAD~1

# Discard all local changes
git restore . && git clean -fd

# Recover deleted branch
git reflog
git checkout -b recovered-branch <sha>

# Abort everything
git merge --abort
git rebase --abort
git cherry-pick --abort