description	applyTo	downloadCommand
Git workflow and best practices for AI agents and humans	**/*	curl -L --silent --remote-name https://gist.githubusercontent.com/jesperronn/8caa210551f86daee827bb628696d464/raw/git.instructions.md

Git Workflow

General Instructions

• Use Conventional Commits format for all commit messages
• Keep commits small and focused on a single purpose
• Create small, single-purpose pull requests that are easy to review
• Always verify changes compile and tests pass before committing

Conventional Commits Format

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

[optional body]

[optional footer(s)]

Types

• feat: New feature
• fix: Bug fix
• refactor: Code change that neither fixes a bug nor adds a feature
• docs: Documentation only changes
• style: Formatting, missing semicolons, etc (no code change)
• test: Adding or updating tests
• chore: Maintenance tasks, dependency updates
• perf: Performance improvements
• ci: CI/CD configuration changes
• build: Build system or external dependencies

Examples

feat(backend): add SAML destination validation
fix(frontend): resolve null pointer in password reset flow
refactor: break circular dependency in UserInfoFactory
docs: update API documentation for user endpoints
test(backend): add coverage for abnormal usage detection

Working with Git (Non-Interactive)

AI agents and scripts must use non-interactive git commands:

# Always disable pager for git commands
export GIT_PAGER=
# Or per-command:
GIT_PAGER= git log
GIT_PAGER= git show
GIT_PAGER= git diff

# Alternative: use --no-pager flag
git --no-pager log
git --no-pager show
git --no-pager diff

Common Git Commands

# View recent commits
GIT_PAGER= git log --oneline -10

# View specific commit
GIT_PAGER= git show <commit-hash>

# View changes in working directory
GIT_PAGER= git diff

# View staged changes
GIT_PAGER= git diff --cached

# View commit history with changes
GIT_PAGER= git log -p --oneline -5

# Check current branch and status
git branch --show-current
git status --short

# Stage and commit
git add <files>
git commit -m "type(scope): description"

# Create branch
git checkout -b feature/short-description

Pull Request Guidelines

Size and Scope

• Maximum ~300 lines changed per PR (excluding generated code, test data)
• Single responsibility: One logical change per PR
• Independent: PR should be reviewable and mergeable independently

Good PR Examples

• ✅ refactor(backend): break circular dependency in UserInfoMapper
• ✅ fix(frontend): correct password expiration calculation
• ✅ test(backend): add coverage for abnormal usage mapper

Bad PR Examples

• ❌ "Fix multiple issues and add features" (too broad)
• ❌ "Update code" (not descriptive)
• ❌ 2000+ line changes across 50 files (too large)

Branch Naming

feature/short-kebab-case-description
fix/issue-number-or-description
refactor/component-being-refactored
docs/what-is-being-documented

Before Committing

# Compile and test
./mvnw clean test

# For specific module
./mvnw -pl submodule-a test

# Check what you're committing
GIT_PAGER= git diff --cached

# Verify files staged
git status --short

Committing Changes

# Stage specific files
git add src/main/java/com/example/MyClass.java
git add src/test/java/com/example/MyClassTest.java

# Commit with conventional format
git commit -m "refactor(backend): extract mapper from DTO to break circular dependency"

# Amend last commit if needed (before pushing)
git commit --amend -m "refactor(backend): extract mapper from DTO to break circular dependency"

Reviewing Changes

# View what changed in last commit
GIT_PAGER= git show HEAD

# View what changed in last 3 commits
GIT_PAGER= git log -p -3

# View changes between branches
GIT_PAGER= git diff main..feature/my-branch

# View files changed in last commit
git show --name-only HEAD

Tips for AI Agents

1. Always use GIT_PAGER= or --no-pager when running git log, show, or diff commands
2. Read git history to understand project conventions and recent changes
3. Check existing commits in the module before making changes
4. Verify branch status before committing
5. Use git status --short for concise output
6. Stage files explicitly rather than using git add .
7. Write descriptive commit messages that explain the "why" not just the "what"

Example Workflow

# 1. Check current state
git branch --show-current
git status --short

# 2. Review recent changes
GIT_PAGER= git log --oneline -5

# 3. Make changes (edit files)

# 4. Review your changes
GIT_PAGER= git diff

# 5. Test changes
./mvnw -pl module-a test -Dtest=MyClassTest

# 6. Stage changes
git add src/main/java/com/example/MyClass.java
git add src/test/java/com/example/MyClassTest.java

# 7. Review staged changes
GIT_PAGER= git diff --cached

# 8. Commit with conventional format
git commit -m "refactor(backend): extract configuration to break circular dependency"

# 9. Verify commit
GIT_PAGER= git show HEAD