command-cheat-sheet.md

Git Stream Command Cheat Sheet

This document shows the underlying git commands executed by each Git Stream (gstr) command. Git Stream wraps standard git operations with workflow validation, safety checks, and automated tagging.

Legend

• Direct git calls: Commands executed directly via Process
• Repository methods: Git operations through the Repository wrapper
• Conditional: Only executed under certain conditions (remote mode, etc.)
• Optional: May or may not be executed based on user choices

init

Initializes Git Stream in a repository or creates a new git repository.

Direct Git Commands

# If creating new repository
git init
git rev-parse HEAD                    # Check for existing commits
git add .gitignore                    # Stage .gitignore
git commit -m "Initial commit with .gitignore"
# OR
git commit --allow-empty -m "Initial commit"

Repository Methods

git rev-parse --abbrev-ref HEAD       # Get current branch
git branch main                       # Create main branch
git checkout main                     # Switch to main
git checkout -b develop               # Create develop branch

feature start

Creates a new feature branch from the base branch (develop by default).

Repository Methods

git status --porcelain                # Validate working tree clean
git rev-parse --verify <branch>       # Check if branch exists
git rev-parse --abbrev-ref HEAD       # Get current branch
git checkout <base-branch>            # Switch to base branch

# If remote exists:
git fetch origin <base-branch>        # Fetch latest changes
git pull origin <base-branch>         # Pull latest changes

git checkout -b <feature-branch>      # Create and switch to feature branch

feature finish

Merges a feature branch back to develop and cleans up.

Repository Methods

git status --porcelain                # Validate working tree clean
git checkout <feature-branch>         # Switch to feature branch

# If remote exists:
git push --set-upstream origin <feature-branch>  # Push feature branch

git checkout develop                  # Switch to develop
git merge-base HEAD <feature-branch>  # Check merge possibility
git merge --no-commit --no-ff <feature-branch>  # Dry run merge
git reset --hard HEAD                 # Reset from dry run
git merge --no-ff <feature-branch> -m "Merge feature: <name>"  # Actual merge
git branch -d <feature-branch>        # Delete feature branch

epic start

Creates a new epic branch from main.

Repository Methods

git rev-parse --verify <branch>       # Check if branch exists
git status --porcelain                # Validate working tree clean
git rev-parse --abbrev-ref HEAD       # Get current branch
git checkout main                     # Switch to main

# If remote exists:
git fetch origin main                 # Fetch latest changes
git pull origin main                  # Pull latest changes

git checkout -b <epic-branch>         # Create and switch to epic branch

epic finish

Merges an epic branch to develop and cleans up.

Repository Methods

git status --porcelain                # Validate working tree clean
git checkout <epic-branch>            # Switch to epic branch

# If remote exists:
git push --set-upstream origin <epic-branch>  # Push epic branch

git checkout develop                  # Switch to develop
git merge-base HEAD <epic-branch>     # Check merge possibility
git merge --no-commit --no-ff <epic-branch>  # Dry run merge
git reset --hard HEAD                 # Reset from dry run
git merge --no-ff <epic-branch> -m "Merge epic: <key>"  # Actual merge
git branch -d <epic-branch>           # Delete epic branch

release start

Creates a release branch from main with selected features/epics.

Repository Methods

git status --porcelain                # Validate working tree clean
git rev-parse --abbrev-ref HEAD       # Get current branch
git checkout main                     # Switch to main

# If remote exists:
git fetch origin main                 # Fetch latest changes
git pull origin main                  # Pull latest changes

git checkout -b <release-branch>      # Create and switch to release branch

# For each selected feature/epic:
git merge-base HEAD <feature-branch>  # Check merge possibility
git merge --no-commit --no-ff <feature-branch>  # Dry run merge
git reset --hard HEAD                 # Reset from dry run
git merge --no-ff <feature-branch> -m "Merge <feature> into release <version>"  # Merge feature

release add

Adds additional features or epics to an existing release branch.

Repository Methods

git status --porcelain                # Validate working tree clean
git checkout <release-branch>         # Switch to release branch

# For each feature/epic to add:
git merge-base HEAD <feature-branch>  # Check merge possibility
git merge --no-commit --no-ff <feature-branch>  # Dry run merge
git reset --hard HEAD                 # Reset from dry run
git merge --no-ff <feature-branch> -m "Add <feature> to release <version>"  # Merge feature

---

release remove

Removes features or epics from an existing release using safe git revert operations.

Repository Methods

git status --porcelain                # Validate working tree clean
git checkout <release-branch>         # Switch to release branch

# Discover merge commits for features/epics
git log --merges --grep="Merge .* into release"  # Find merge commits

# For each feature/epic to remove:
git revert -m 1 <merge-commit-hash> --no-edit  # Revert merge commit (parent 1 = release branch)

# If any revert fails:
git revert --abort                    # Abort current revert
git reset --hard HEAD~N               # Rollback all successful reverts

Common Usage Examples

# Interactive removal
gstr release remove v1.2.0

# Remove specific features
gstr release remove v1.2.0 --features=user-profile --features=api-auth

# Remove entire epic
gstr release remove v1.2.0 --epics=AUTH-123

# Preview without reverting (dry-run)
gstr release remove v1.2.0 --dry-run

# Skip auto-sync before removal
gstr release remove v1.2.0 --no-sync

---

release finish

Merges release to main and develop, creates tags.

Repository Methods

git status --porcelain                # Validate working tree clean
git checkout <release-branch>         # Switch to release branch

# If remote exists:
git push --set-upstream origin <release-branch>  # Push release branch

git checkout main                     # Switch to main
git merge-base HEAD <release-branch>  # Check merge possibility
git merge --no-commit --no-ff <release-branch>  # Dry run merge
git reset --hard HEAD                 # Reset from dry run
git merge --no-ff <release-branch> -m "Release: <version>"  # Merge to main
git tag -a <version> -m "<tag-message>"  # Create release tag

git checkout develop                  # Switch to develop
git merge --no-ff <release-branch> -m "Merge release <version> back to develop"  # Merge to develop

git branch -d <release-branch>        # Delete release branch

# If remote exists:
git push origin --tags                # Push tags

hotfix start

Creates a hotfix branch from main.

Repository Methods

git status --porcelain                # Validate working tree clean
git rev-parse --abbrev-ref HEAD       # Get current branch
git checkout main                     # Switch to main

# If remote exists:
git fetch origin main                 # Fetch latest changes
git pull origin main                  # Pull latest changes

git checkout -b <hotfix-branch>       # Create and switch to hotfix branch

hotfix finish

Merges hotfix to main and develop, creates tags.

Repository Methods

git status --porcelain                # Validate working tree clean
git checkout <hotfix-branch>          # Switch to hotfix branch

# If remote exists:
git push --set-upstream origin <hotfix-branch>  # Push hotfix branch

git checkout main                     # Switch to main
git merge-base HEAD <hotfix-branch>   # Check merge possibility
git merge --no-commit --no-ff <hotfix-branch>  # Dry run merge
git reset --hard HEAD                 # Reset from dry run
git merge --no-ff <hotfix-branch> -m "Hotfix: <name>"  # Merge to main
git tag -a <version> -m "Hotfix <version>: <name>"  # Create hotfix tag

git checkout develop                  # Switch to develop
git merge-base HEAD <hotfix-branch>   # Check merge possibility
git merge --no-commit --no-ff <hotfix-branch>  # Dry run merge
git reset --hard HEAD                 # Reset from dry run
git merge --no-ff <hotfix-branch> -m "Hotfix backport: <name>"  # Merge to develop

git branch -d <hotfix-branch>         # Delete hotfix branch

# If remote exists:
git push origin main                  # Push main
git push origin develop               # Push develop
git push origin --tags                # Push tags

merge

Safely merges branches with validation and conflict detection.

Repository Methods

git rev-parse --abbrev-ref HEAD       # Get current branch
git rev-parse --verify <source-branch>  # Verify source branch exists
git branch -a                         # List all branches for selection
git merge-base HEAD <source-branch>   # Check merge possibility
git merge --no-commit --no-ff <source-branch>  # Dry run merge (conflict check)
git reset --hard HEAD                 # Reset from dry run
git merge --no-ff <source-branch> -m "<message>"  # Actual merge with message

Direct Git Commands

# None - all operations go through Repository methods

Common Usage Examples

# Interactive branch selection
gstr merge

# Merge specific branch
gstr merge feature/user-auth

# Merge main into current branch (production sync)
gstr merge main

# Custom merge message
gstr merge feature/api -m "Integrate API client"

# Preview merge without executing
gstr merge feature/experimental --dry-run

# Force merge commit (explicit, default behavior)
gstr merge feature/updates --no-ff

Safety Validations

• Validates source branch exists
• Checks working tree is clean
• Detects merge conflicts before attempting
• Enforces safety level rules:
  • Protected: Only main → any allowed
  • Balanced: main → any, same-type merges (feature → feature, epic → epic, etc.)
  • Unrestricted: All except develop → any, any → main/develop
• Always blocks:
  • develop as source (dirty integration branch)
  • Merges into main (use release/hotfix finish)
  • Merges into develop (use feature/epic finish)

Merge Types

• main → any: Production sync (always allowed)
• feature → feature: Combine feature work (balanced+)
• epic → epic: Merge epic branches (balanced+)
• epic-feature → epic-feature: Combine epic features (balanced+)
• release → release: Merge release branches (balanced+)
• Cross-type: Requires unrestricted level

---

commit

Creates a structured commit with Git Stream tagging.

Repository Methods

git rev-parse --abbrev-ref HEAD       # Get current branch
git add .                             # Stage all changes
git commit -m "<tagged-message>"      # Create commit (with GITSTREAM_COMMIT=1 env)

Amend Mode

git rev-parse --abbrev-ref HEAD       # Get current branch
git add .                             # Stage all changes
git commit --amend -m "<new-message>" # Amend commit
# OR
git commit --amend --no-edit          # Amend without changing message

sync

Fetches latest changes and processes merged branches.

Repository Methods

git fetch origin                      # Fetch from remote
git rev-parse --verify <branch>       # Check branch existence
git checkout <branch>                 # Switch to branch
git pull origin <branch>              # Pull latest changes
git tag -a <version> -m "Release <version>"  # Create release tag (for releases)
git push origin --tags                # Push tags
git branch -d <branch>                # Delete merged branches

clean

Removes merged branches and stale PR data.

Repository Methods

git rev-parse --verify <branch>       # Check local branch existence
git ls-remote --heads origin <branch> # Check remote branch existence
git branch -D <branch>                # Force delete local branch

status

Shows repository status and Git Stream state.

Repository Methods

git rev-parse --abbrev-ref HEAD       # Get current branch
git remote get-url origin             # Get remote origin URL
git status --porcelain                # Check working tree status

config

Manages Git Stream configuration (no direct git commands).

mode

Switches between local and remote workflow modes (no direct git commands).

deploy

Manages DTAP deployment tags for environment targeting.

Repository Methods

# Set deployment target
git tag -a deploy/<environment> <commit> -m "<metadata-json>"  # Create annotated tag
git push origin deploy/<environment>      # Push deployment tag

# Get deployment target
git rev-parse deploy/<environment>        # Get tagged commit
git tag -l -n99 deploy/<environment>      # Get tag annotation

# List deployment targets
git tag -l "deploy/*"                     # List all deployment tags
git for-each-ref refs/tags/deploy/* --format="%(refname:short) %(objectname:short)"

# Clear deployment target
git tag -d deploy/<environment>           # Delete local tag
git push origin :refs/tags/deploy/<environment>  # Delete remote tag

Common Usage Examples

# Set testing environment to develop
gstr deploy set testing develop

# Set acceptance to specific release
gstr deploy set acceptance release/v1.2.0

# Set production to main
gstr deploy set production main

# Get current production deployment
gstr deploy get production

# List all deployment targets
gstr deploy list

# Clear staging deployment
gstr deploy clear staging

list

Lists all available Git Stream commands (hidden utility command, no git operations).

Workflow Modes

Git Stream supports three workflow modes:

Remote Mode with PRs (Optional)

• Uses pull request API (GitHub/BitBucket)
• Creates PRs instead of direct merges
• Branches remain local until PR is merged
• Requires sync command to update local state after PR merge

Remote Mode without PRs (Default for Remote)

• Direct merge to target branches
• Pushes all changes to remote after merge
• Uses pushSafe() to bypass git hooks for protected branches
• Auto-updates deployment tags
• Works offline (pushes fail gracefully)

Local Mode

• No remote operations
• Direct merges only
• All operations work offline
• No deployment tag synchronization

Notes

• Safety First: Git Stream performs additional validation and safety checks before executing git commands
• Environment Variables: Some operations set GITSTREAM_COMMIT=1 to bypass hook restrictions
• Conditional Execution: Remote operations only execute when a remote origin is configured
• Branch Protection: Git hooks prevent direct git operations on protected branches (main, develop, release/, hotfix/)
• Hook Bypass: pushSafe() method bypasses pre-push hooks for protected branch synchronization
• Tagging: Commits are automatically tagged with format: [key] | [type] | [message]
  • Examples: user-login | feat | Add auth, v1.2.0 | rel | Release, MAIN | feat | Update
• Merge Strategy: All merges use --no-ff to preserve branch history
• Validation: Working tree cleanliness is validated before most operations
• Deployment Tags: Automatically updated after merges (testing→develop, production→main)