automaker/docs/checkout-branch-pr.md

Git Workflow: Branch, Commit, Push, and Pull Request

This document outlines the standard workflow for creating a branch, committing changes, pushing to remote, and creating a pull request.

Prerequisites

• Git installed and configured
• GitHub CLI (gh) installed (optional, but recommended for PR creation)
• Access to the repository
• Authentication configured (SSH keys or GitHub CLI authentication)

Step-by-Step Workflow

1. Check Current Status

First, check what changes exist in your working directory:

git status

This shows:

• Modified files
• Deleted files
• Untracked files
• Current branch

2. Create a New Branch

Create and switch to a new branch for your changes:

git checkout -b <branch-name>

Branch naming conventions:

• feature/ - for new features
• fix/ or bugfix/ - for bug fixes
• refactor/ - for code refactoring
• docs/ - for documentation changes
• chore/ - for maintenance tasks

Example:

git checkout -b refactor/monorepo-restructure

3. Stage Changes

Stage all changes (including deletions and new files):

git add -A

Or stage specific files:

git add <file1> <file2>

4. Commit Changes

Create a commit with a descriptive message:

git commit -m "type: descriptive commit message"

Commit message conventions:

• Use conventional commits format: type: description
• Types: feat, fix, refactor, docs, chore, test, style
• Keep messages concise but descriptive

Example:

git commit -m "refactor: restructure project to monorepo with apps directory"

5. Push Branch to Remote

Push your branch to the remote repository:

git push -u origin <branch-name>

The -u flag sets up tracking so future pushes can use git push without specifying the branch.

Example:

git push -u origin refactor/monorepo-restructure

6. Create Pull Request

Option A: Using GitHub CLI (Recommended)

If you have GitHub CLI installed:

gh pr create --title "Your PR Title" --body "Description of changes"

To open in browser for review before creating:

gh pr create --title "Your PR Title" --body "Description" --web

Option B: Using GitHub Web Interface

After pushing, GitHub will provide a URL in the terminal output:

remote: Create a pull request for '<branch-name>' on GitHub by visiting:
remote:      https://github.com/<org>/<repo>/pull/new/<branch-name>

Visit that URL to create the PR through the web interface.

Option C: Manual PR Creation

1. Go to your repository on GitHub
2. Click "Pull requests" tab
3. Click "New pull request"
4. Select your branch as the source
5. Select the target branch (usually main or master)
6. Fill in title and description
7. Click "Create pull request"

Complete Example Workflow

# 1. Check status
git status

# 2. Create branch
git checkout -b feature/add-new-component

# 3. Make your changes (edit files, etc.)

# 4. Stage changes
git add -A

# 5. Commit
git commit -m "feat: add new user dashboard component"

# 6. Push
git push -u origin feature/add-new-component

# 7. Create PR
gh pr create --title "feat: add new user dashboard component" --body "Implements new dashboard component with user statistics and activity feed."

Handling Additional Changes

If you need to make more changes after pushing:

# Make your changes
git add -A
git commit -m "fix: address review feedback"
git push

The PR will automatically update with the new commits.

Troubleshooting

Branch already exists

git checkout <existing-branch-name>

Need to update from main before creating PR

git checkout main
git pull origin main
git checkout <your-branch>
git merge main
# Resolve conflicts if any
git push

PR creation fails

• Ensure branch is pushed: git push -u origin <branch-name>
• Check GitHub CLI authentication: gh auth status
• Verify repository access permissions
• Try creating PR via web interface instead

Best Practices

1. Keep branches focused: One branch = one feature/fix
2. Write clear commit messages: Help reviewers understand changes
3. Keep PRs small: Easier to review and merge
4. Update before creating PR: Merge latest main into your branch
5. Add tests: Include tests for new features
6. Update documentation: Keep docs in sync with code changes
7. Request reviews: Tag relevant team members for review

Quick Reference Commands

# Status check
git status

# Create branch
git checkout -b <branch-name>

# Stage all changes
git add -A

# Commit
git commit -m "type: message"

# Push
git push -u origin <branch-name>

# Create PR (GitHub CLI)
gh pr create --title "Title" --body "Description"

# View PR
gh pr view

# List PRs
gh pr list