Skill: Branch and File Management

Purpose

Manage git branches and file changes for feature development, including creating branches, staging changes, and maintaining clean working directories.

When to Use

• Starting new feature development
• Creating branches for stories
• Managing working directory changes
• Handling file staging and unstaging
• Switching between work contexts

Tools Used

• git CLI commands
• gh CLI (GitHub CLI)

Configuration

{
  "owner": "{{github.owner}}",
  "repo": "{{github.repo}}",
  "defaultBranch": "{{github.defaultBranch}}"
}

---

Branch Management

Branch Naming Convention

<type>/<ticket>-<description>

Types:
- feature/  - New functionality
- bugfix/   - Bug fixes
- hotfix/   - Urgent production fixes
- chore/    - Maintenance tasks
- docs/     - Documentation
- refactor/ - Code refactoring
- test/     - Test additions

Examples:
feature/MDDEV-123-user-authentication
bugfix/MDDEV-456-login-validation
hotfix/MDDEV-789-security-patch

Creating Branches

# Create and checkout new branch
git checkout -b feature/MDDEV-123-new-feature

# Create from specific base
git checkout -b feature/MDDEV-123-new-feature origin/develop

# Create without checkout
git branch feature/MDDEV-123-new-feature

# Push and set upstream
git push -u origin feature/MDDEV-123-new-feature

Listing Branches

# List local branches
git branch

# List remote branches
git branch -r

# List all branches
git branch -a

# List with last commit info
git branch -v

# List merged branches
git branch --merged

# List unmerged branches
git branch --no-merged

Switching Branches

# Switch to existing branch
git checkout feature/MDDEV-123

# Switch and create if doesn't exist
git checkout -b feature/MDDEV-123

# Switch using git switch (newer syntax)
git switch feature/MDDEV-123
git switch -c feature/MDDEV-123  # create and switch

Deleting Branches

# Delete local branch (merged)
git branch -d feature/MDDEV-123

# Force delete local branch (unmerged)
git branch -D feature/MDDEV-123

# Delete remote branch
git push origin --delete feature/MDDEV-123

# Prune deleted remote branches
git fetch --prune

---

Working Directory Management

Checking Status

# Full status
git status

# Short status
git status -s

# Show ignored files too
git status --ignored

Staging Changes

# Stage specific file
git add path/to/file.ts

# Stage multiple files
git add file1.ts file2.ts

# Stage all changes
git add .

# Stage by pattern
git add "*.ts"
git add "src/**/*.ts"

# Stage interactively (choose hunks)
git add -p

# Stage with review
git add -N file.ts  # intent to add
git diff --cached   # review what's staged

Unstaging Changes

# Unstage specific file
git restore --staged path/to/file.ts

# Unstage all
git restore --staged .

# Old syntax (still works)
git reset HEAD path/to/file.ts

Discarding Changes

# Discard changes in file
git restore path/to/file.ts

# Discard all changes
git restore .

# Discard untracked files
git clean -fd

# Dry run (show what would be deleted)
git clean -fdn

---

Stashing Changes

Basic Stash Operations

# Stash current changes
git stash

# Stash with message
git stash push -m "WIP: feature implementation"

# Stash including untracked files
git stash -u

# Stash specific files
git stash push path/to/file.ts -m "Partial work"

# List stashes
git stash list

# Apply most recent stash
git stash pop

# Apply specific stash
git stash pop stash@{2}

# Apply without removing from stash
git stash apply

# Drop stash
git stash drop stash@{0}

# Clear all stashes
git stash clear

Stash Workflow

## Context Switching with Stash

1. Working on feature A
2. Urgent bug needs attention
3. Stash feature A work:
   ```bash
   git stash push -m "feature-a: halfway through implementation"

4. Switch to bugfix branch:

   git checkout bugfix/MDDEV-urgent
   

5. Fix bug, commit, merge
6. Return to feature A:

   git checkout feature/MDDEV-a
   git stash pop
   

7. Continue working

---

## File Operations

### Viewing Changes

```bash
# Show unstaged changes
git diff

# Show staged changes
git diff --staged

# Show changes in specific file
git diff path/to/file.ts

# Show file at specific commit
git show commit:path/to/file.ts

# Compare branches
git diff main..feature-branch

# Show changed files only
git diff --name-only
git diff --name-status

Moving/Renaming Files

# Rename/move file
git mv old-name.ts new-name.ts
git mv file.ts new-directory/

# If you renamed outside git
git add new-name.ts
git rm old-name.ts

Removing Files

# Remove file from repo and filesystem
git rm file.ts

# Remove from repo only (keep local)
git rm --cached file.ts

# Remove directory
git rm -r directory/

---

Branch Synchronization

Keeping Branch Updated

# Fetch latest from remote
git fetch origin

# Update current branch with remote
git pull

# Update with rebase (cleaner history)
git pull --rebase

# Merge main into feature branch
git checkout feature/my-branch
git merge main

# Rebase onto main
git checkout feature/my-branch
git rebase main

Handling Diverged Branches

# When local and remote have diverged
git fetch origin

# Option 1: Merge (creates merge commit)
git merge origin/feature/my-branch

# Option 2: Rebase (linear history)
git rebase origin/feature/my-branch

# Option 3: Reset to remote (discard local)
git reset --hard origin/feature/my-branch

---

Common Workflows

Starting New Feature

# Ensure main is up to date
git checkout main
git pull origin main

# Create feature branch
git checkout -b feature/MDDEV-123-new-feature

# Work on feature...
git add .
git commit -m "feat: initial implementation"

# Push branch
git push -u origin feature/MDDEV-123-new-feature

Updating Feature Branch

# Fetch latest
git fetch origin

# Rebase onto updated main
git rebase origin/main

# If conflicts, resolve then:
git rebase --continue

# Force push (only if branch not shared)
git push --force-with-lease

Cleaning Up After Merge

# Switch to main
git checkout main

# Pull latest
git pull origin main

# Delete local feature branch
git branch -d feature/MDDEV-123

# Delete remote feature branch
git push origin --delete feature/MDDEV-123

# Prune remote tracking branches
git fetch --prune

---

Best Practices

Branch Management

✅ Use descriptive branch names with ticket numbers
✅ Keep branches short-lived
✅ Delete branches after merge
✅ Regularly sync with base branch
✅ One feature per branch

❌ Don't work directly on main/master
❌ Don't keep stale branches
❌ Don't mix unrelated changes

Working Directory

✅ Commit or stash before switching branches
✅ Review changes before staging
✅ Use .gitignore for generated files
✅ Keep commits atomic

❌ Don't commit large binary files
❌ Don't commit secrets or credentials
❌ Don't ignore linting/formatting

---

Used By Agents

Agent	Branch/File Management Use
Senior Developer	Manages complex branch strategies
Junior Developer	Creates feature branches, manages changes
DevOps Engineer	Manages release branches
QA Engineer	Checks out branches for testing

Error Handling

Error	Cause	Resolution
Cannot switch branches	Uncommitted changes	Stash or commit changes
Branch already exists	Name conflict	Use different name or delete existing
Detached HEAD	Not on branch	git checkout <branch>
Merge conflicts	Divergent changes	Resolve conflicts manually