Effective Git

Intelligent Git workflow assistant following best practices. Use when user needs help with git commits, analyzing changes, writing commit messages, pushing c...

Security Scan

The skill's code, scripts, and instructions are consistent with an intelligent Git helper; nothing requested or installed is disproportionate to that purpose.

Purpose & Capability

Name/description match the provided scripts and docs. The skill only operates on a Git repository (status, diffs, commits, conflict analysis, backups) and does not request unrelated credentials, binaries, or external services.

Instruction Scope

Runtime instructions call local helper scripts that inspect repository state, show diffs, save pre-merge diffs to .git/merge-diffs, create backup branches, and present conflict sections. These actions are appropriate for a Git assistant, but they will read and print file contents (including untracked files) and write backup diff files into the repo; users should expect repository content to be displayed and a .git/merge-diffs directory to be created.

Install Mechanism

There is no install spec and no remote downloads — the skill is delivered as scripts and docs only. No archives or external install hosts are used.

Credentials

The skill declares no required environment variables or credentials. Scripts do honor optional environment variables (GIT_QUICK_DIFF_TERMINAL, GIT_QUICK_DIFF_PAGER/PAGER). That is reasonable, but because GIT_QUICK_DIFF_TERMINAL is executed (to open a terminal with a bash -c command), a maliciously-crafted terminal command in that variable could execute arbitrary shell code — this is a general risk of honoring shell commands from env vars, not an unexplained requirement from the skill.

Persistence & Privilege

The skill does not request permanent platform presence (always:false) and does not modify other skills or global agent settings. It writes only into the repository (.git/merge-diffs and backup branches) which is expected for its function.

Assessment

This skill appears coherent and focused on Git workflows. Before using it: (1) review the included scripts yourself — they will read and print repo files (including untracked files) and will create backups under .git/merge-diffs and create backup branches; (2) run it in a non-sensitive repository first to observe behavior; (3) ensure your GIT_QUICK_DIFF_TERMINAL env var (if set) is a trusted terminal command — the script will execute it to display diffs; (4) the skill will not push or rewrite history without explicit confirmation per its docs, but always review any proposed push/rewrite and confirm manually; (5) remove .git/merge-diffs after use if you don't want diffs persisted in the repo. If you want extra assurance, run the scripts manually rather than granting the agent autonomous invocation.

Smart Git workflow assistant that helps you commit, push, and manage code changes following best practices.

Getting Help

Quick help: When user asks "gq help", "gq:h", or "git help", run scripts/show_help.sh to display usage guide

Detailed help: When user asks about specific topics:

• "show me git best practices" → Read references/best-practices.md
• "how to resolve conflicts" → Read references/conflict-resolution.md
• "quick commands list" → Read references/quick-commands.md

Usage examples:

• Use gq <command> for quick operations (status, branch switching, etc.)
• Use natural language for commits, pushes, merges (full workflow with analysis and safety checks)
• Examples:
  • "gq b:l" → Quick branch list
  • "help me commit code" → Full commit workflow with analysis
  • "gq:s" → Quick status
  • "resolve conflicts" → Full conflict resolution with guidance

Core Workflow

When helping with git operations, follow this sequence:

Quick Operations Mode

For simple, read-only operations or quick checks, use scripts/git_quick.sh:

When user asks for:

• "list branches" → git_quick.sh b:l
• "switch to xxx" → git_quick.sh "b->" xxx
• "create branch xxx" → git_quick.sh b:n xxx
• "check status" → git_quick.sh s
• "recent commits" → git_quick.sh l
• "show changes" → git_quick.sh "d"
  • If GIT_QUICK_DIFF_TERMINAL is set, opens in new terminal window
  • Otherwise uses $PAGER (default: less)
  • Staged changes: git_quick.sh "d:s"

See references/quick-commands.md for full command list.

Full Workflow Mode

For commits, pushes, merges, and conflict resolution, follow the detailed workflow below:

1. Analyze Recent Changes

Run scripts/analyze_changes.sh to understand:

• Current branch
• Uncommitted changes
• Recent commit history
• Last commit details

2. Determine Commit Strategy

Check if changes should amend the last commit or create a new one:

Use git commit --amend when:

• Fixing typos or small issues in the last commit
• Adding forgotten files to the last commit
• Last commit hasn't been pushed yet
• Changes are logically part of the last commit

Use git commit -m "message" when:

• Changes represent a new logical unit of work
• Last commit has been pushed
• Changes are unrelated to the last commit

3. Check Project Conventions

Before writing commit message:

1. Review recent commit messages: git log --oneline -10
2. Look for patterns:
   • Prefixes (feat:, fix:, chore:, etc.)
   • Ticket references (#123, JIRA-456)
   • Emoji usage (✨, 🐛, 📝)
   • Capitalization style
3. If unclear, ask user about project conventions

4. Write Commit Message

Follow conventions from references/best-practices.md:

• Use imperative mood ("Add feature" not "Added feature")
• Keep subject line under 50 chars
• Be specific and descriptive
• Match project conventions discovered above

5. Safe Push Operations

Critical constraint: Only push to current branch.

Before pushing:

1. Confirm current branch: git branch --show-current
2. Show what will be pushed: git log origin/$(git branch --show-current)..HEAD --oneline
3. Ask user to confirm
4. Push: git push origin HEAD

Never use git push --force without explicit user confirmation.

Dangerous Operations

These require user confirmation before execution:

• git push --force or git push -f
• git reset --hard
• git clean -fd
• git rebase on shared/public branches
• git branch -D (force delete)
• Any history rewriting on pushed commits

Always explain the risk before asking for confirmation.

Conflict Resolution

Critical Principle: When resolving conflicts, the absolute priority is preserving all code. If unable to confidently resolve, you must summarize the issue and feedback to the user. DO NOT perform automatic merges.

Conflict Handling Workflow:

1. Pre-merge/Rebase Snapshot: Before attempting a merge or rebase, save a snapshot of the current state for documentation and safety.

   scripts/save_diff.sh
   # Also create backup branch
   git branch <current-branch>-backup
   

   This creates a git diff document before the merge.

2. Detect and Analyze Conflicts: If conflicts arise during a merge or rebase:

   scripts/analyze_conflicts.sh
   

   This provides detailed three-way diff analysis for each conflicted file.

3. Deep Conflict Analysis: For complex conflicts where both sides modified the same code:

   Analyze the intent:

   • What problem does each version solve?
   • What functionality does each add/remove/modify?
   • Is it a bug fix, feature, refactor, or optimization?

   Compare approaches:

   • Do they implement different algorithms?
   • Do they change APIs or interfaces differently?
   • What are the trade-offs (performance vs readability, simplicity vs robustness)?

   Determine resolution strategy:

   • Keep Both (Merge): Both changes are valuable and can be combined
   • Keep Ours: Our change is more complete/correct
   • Keep Theirs: Their change is more complete/correct
   • Rewrite: Neither is ideal, create better solution combining insights
   • Ask User: Cannot decide confidently, need user guidance

4. Present Analysis to User: When conflicts cannot be resolved automatically, create a structured summary:

   • Show both versions of conflicting code
   • Explain the intent and trade-offs of each
   • Provide your recommendation with reasoning
   • Ask for user's decision
   • See references/conflict-resolution.md for detailed template

5. Post-Resolution Documentation: After conflicts are resolved:

   # Generate diff of resolution
   git diff --cached > .git/merge-diffs/resolution_$(date +%Y%m%d_%H%M%S).diff
   
   # Show summary
   git diff --cached --stat
   

6. Verify No Code Loss: After completing merge/rebase:

   # Compare with backup branch
   git diff <branch>-backup <branch>
   
   # Review carefully for unexpected deletions
   

Special attention for edge cases:

• Detached HEAD: Scripts will detect and warn; recommend creating a branch before operations
• Submodules: Detected and flagged; require special handling (see references/conflict-resolution.md)
• Large files: Output automatically limited to prevent overwhelming context
• Rebase to less code: Default to preserving current branch's work (see references/conflict-resolution.md)

Rebase & Merge

Interactive Rebase

# Clean up last N commits
git rebase -i HEAD~N

# Rebase feature branch onto main
git checkout feature-branch
git fetch origin
git rebase origin/main

Merge Strategies

# Standard merge (preserves history)
git merge feature-branch

# Squash merge (single commit)
git merge --squash feature-branch

Common Tasks

Stash Changes

git stash                    # Stash current changes
git stash list              # List stashes
git stash pop               # Apply and remove last stash
git stash apply stash@{0}   # Apply specific stash

Cherry-pick

git cherry-pick <commit-hash>

Undo Changes

git restore <file>          # Discard working changes
git restore --staged <file> # Unstage file
git reset HEAD~1            # Undo last commit (keep changes)

Resources

• Help script: scripts/show_help.sh (usage guide and examples)
• Best practices reference: references/best-practices.md
• Conflict resolution guide: references/conflict-resolution.md (includes detailed analysis framework and templates)
• Quick commands reference: references/quick-commands.md (shorthand for common operations)
• Change analysis script: scripts/analyze_changes.sh
• Conflict analysis script: scripts/analyze_conflicts.sh (deep three-way diff analysis)
• Save diff script: scripts/save_diff.sh
• Visualize conflicts script: scripts/visualize_conflicts.sh
• Quick operations script: scripts/git_quick.sh (fast branch switching, status checks, etc.)

Quick Commands

For rapid git operations, use scripts/git_quick.sh with the gq prefix pattern:

Trigger pattern: When user message starts with gq: or uses git quick command syntax

Common commands:

• gq b:l or gq:b:l - List branches
• gq b-> <name> - Switch to branch
• gq b:n <name> - Create new branch from current
• gq s - Quick status
• gq l - Recent commits
• gq d - Show diff

Usage in conversation:

• User: "gq b:l" → Run scripts/git_quick.sh b:l
• User: "gq b-> feature" → Run scripts/git_quick.sh "b->" feature
• User: "gq:s" → Run scripts/git_quick.sh s

⚠️ Shell quoting rule: Always quote the command argument when calling git_quick.sh to prevent shell misinterpreting special characters. Use git_quick.sh "b->" <branch>, never git_quick.sh b-> <branch> (shell will treat > as redirection).

See references/quick-commands.md for full command list and usage patterns.

Important: Only trigger quick commands when user explicitly uses gq prefix or quick command syntax. Do not auto-trigger for general git questions.