Git Skills & Best Practices

Git workflow standards, commit conventions, hooks, and pull request practices.

•Git Workflow
•Git Hooks
•Pull Request Templates
•GitHub CLI (gh) Integration

Git Workflow

Conventional Commits

MUST use Conventional Commits format - this is a strict requirement. Follow the Conventional Commits specification:

Format:

code

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Types:

•feat: A new feature
•fix: A bug fix
•docs: Documentation only changes
•style: Changes that do not affect the meaning of the code
•refactor: A code change that neither fixes a bug nor adds a feature
•perf: A code change that improves performance
•test: Adding missing tests or correcting existing tests
•chore: Changes to the build process or auxiliary tools

Examples:

code

feat(auth): add user login functionality
fix(api): resolve race condition in data fetching
docs: update README with setup instructions

.gitignore

Include standard exclusions for React/React Native projects:

Essential entries:

code

# Environment variables
.env
.env.local
.env.*.local

# Dependencies
node_modules/
.pnp
.pnp.js

# Build outputs
dist/
build/
.next/
out/

# Testing
coverage/
.nyc_output/

# IDE
.vscode/
.idea/
*.swp
*.swo
*~

# OS
.DS_Store
Thumbs.db

# Logs
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
lerna-debug.log*
pnpm-debug.log*

# pnpm
.pnpm-store/

# Misc
.cache/
.temp/
.turbo/

Git Hooks

Lefthook Integration

PREFER using Lefthook for managing git hooks (guideline). Other tools are acceptable if they meet the strict hook requirements below.

Configuration (lefthook.yml):

yaml

pre-commit:
  parallel: true
  commands:
    lint:
      run: pnpm run lint
      stage_fixed: true
    format:
      run: pnpm run format:check
      stage_fixed: true
    test:
      run: pnpm run test:ci
      stage_fixed: true

pre-push:
  parallel: true
  commands:
    test:
      run: pnpm run test
    typecheck:
      run: pnpm run typecheck

Pre-commit hooks (Strict Requirements):

•MUST run linting checks
•MUST run formatting checks
•MUST run unit tests
•Auto-fix issues when possible

Pre-push hooks (Strict Requirements):

•MUST run full test suite
•MUST run TypeScript type checking (tsc)
•MUST prevent pushing if checks fail

Pull Request Templates

Create .github/pull_request_template.md with the following structure:

markdown

## Overview
<!-- Brief description of what this PR accomplishes -->

## Solution
<!-- Detailed explanation of the approach and implementation -->

## Screenshots
<!-- Add screenshots or screen recordings if applicable -->
<!-- For web: browser screenshots -->
<!-- For mobile: iOS/Android screenshots -->

## Ticket
<!-- Link to JIRA ticket or other project management tool -->
<!-- Format: [PROJECT-123](link-to-ticket) -->

## Tested On
<!-- Check all that apply -->
- [ ] Web
- [ ] Mobile
- [ ] iOS
- [ ] Android
- [ ] Other: ___________

## Additional Notes
<!-- Any additional context, breaking changes, or follow-up items -->

GitHub CLI (gh) Integration

The GitHub CLI (gh) enables AI agents to interact with GitHub repositories programmatically, automating common Git and GitHub workflows.

Authentication

Setup:

bash

# Login to GitHub
gh auth login

# Check authentication status
gh auth status

# Refresh authentication token
gh auth refresh

For AI Agents:

•Use gh auth token to retrieve the authentication token for API calls
•Configure authentication before performing any GitHub operations
•Use gh auth setup-git to configure Git credentials automatically

Pull Request Management

Create Pull Requests:

bash

# Create a PR interactively
gh pr create

# Create a PR with title and body
gh pr create --title "feat: add user authentication" --body "Implements OAuth2 login flow"

# Create a PR from current branch to main
gh pr create --base main --head feature/auth --title "feat: add authentication"

# Create a draft PR
gh pr create --draft

View and Manage PRs:

bash

# List open PRs
gh pr list

# View PR details
gh pr view <number>

# View PR diff
gh pr diff <number>

# Checkout PR locally
gh pr checkout <number>

# Review PR status and checks
gh pr checks <number>

# Comment on PR
gh pr comment <number> --body "LGTM! Great work."

# Approve PR
gh pr review <number> --approve

# Merge PR
gh pr merge <number> --squash
gh pr merge <number> --merge
gh pr merge <number> --rebase

For AI Agents:

•Automatically create PRs after completing features
•Check PR status and wait for CI checks to pass
•Add comments with analysis or suggestions
•Merge PRs after approval (when appropriate)

Issue Management

Create and Manage Issues:

bash

# Create an issue
gh issue create --title "Bug: login fails" --body "Description of the bug"

# List issues
gh issue list

# View issue details
gh issue view <number>

# Comment on issue
gh issue comment <number> --body "This is fixed in PR #123"

# Close issue
gh issue close <number>

# Reopen issue
gh issue reopen <number>

For AI Agents:

•Create issues for bugs discovered during code review
•Link issues to PRs automatically
•Update issue status based on PR status
•Create issues from TODO comments or technical debt

Repository Operations

Repository Management:

bash

# Clone a repository
gh repo clone owner/repo

# View repository details
gh repo view

# Create a new repository
gh repo create my-project --public --clone

# Fork a repository
gh repo fork owner/repo

# View repository settings
gh repo view --web

For AI Agents:

•Clone repositories for analysis or contribution
•Create new repositories with proper structure
•Fork repositories for experimentation

Branch and Commit Operations

Branch Management:

bash

# List branches
gh repo view --json defaultBranchRef

# Create branch from issue
gh issue develop <number> --branch feature/issue-123

Browse GitHub Resources:

bash

# Open current PR in browser
gh pr view --web

# Open current issue in browser
gh issue view --web

# Open repository in browser
gh repo view --web

Search and Discovery

Search Capabilities:

bash

# Search code
gh search code "function authenticate"

# Search repositories
gh search repos "react typescript"

# Search issues
gh search issues "bug login"

# Search pull requests
gh search prs "is:open author:@me"

For AI Agents:

•Search for similar implementations before creating new code
•Find existing issues or PRs related to current work
•Discover patterns and best practices from other repositories

API Access

Direct API Calls:

bash

# Make authenticated API calls
gh api repos/:owner/:repo/pulls

# Get specific data
gh api repos/:owner/:repo/pulls/123 --jq '.title, .body'

# POST requests
gh api repos/:owner/:repo/issues -X POST -f title="New Issue" -f body="Description"

For AI Agents:

•Access GitHub API for advanced operations not covered by CLI commands
•Retrieve detailed data in JSON format for processing
•Perform bulk operations efficiently

Workflow Automation Examples

Complete Feature Workflow:

bash

# 1. Create and checkout feature branch
git checkout -b feature/new-feature

# 2. Make changes and commit
git add .
git commit -m "feat: implement new feature"

# 3. Push branch
git push -u origin feature/new-feature

# 4. Create PR
gh pr create --title "feat: implement new feature" --body "Description" --draft

# 5. Wait for CI checks
gh pr checks --watch

# 6. After approval, merge
gh pr merge --squash --delete-branch

For AI Agents:

•Automate the complete PR workflow from branch creation to merge
•Monitor CI checks and retry failed workflows
•Update PR descriptions with analysis or documentation
•Clean up branches after merge

Best Practices for AI Agents

•Always authenticate first: Check gh auth status before operations
•Use appropriate PR flags: Use --draft for work-in-progress, --fill to auto-populate from commits
•Monitor CI checks: Use gh pr checks --watch to wait for checks to complete
•Provide context: Always include meaningful titles and descriptions
•Link related items: Reference issues in PR descriptions with Closes #123
•Handle errors gracefully: Check command exit codes and provide helpful error messages
•Respect rate limits: Implement delays for bulk operations
•Use JSON output: Use --json flag for programmatic processing

Additional Resources

Notes

•This document should be reviewed and updated regularly as best practices evolve
•Team-specific additions and modifications are encouraged
•When in doubt, refer to official documentation and community standards

Git Skills & Best Practices

Table of Contents

Git Workflow

Conventional Commits

.gitignore

Git Hooks

Lefthook Integration

Pull Request Templates

GitHub CLI (gh) Integration

Authentication

Pull Request Management

Issue Management

Repository Operations

Branch and Commit Operations

Search and Discovery

API Access

Workflow Automation Examples

Best Practices for AI Agents

Additional Resources

Notes