---
title: "Git Workflow: Environment Preparation"
author: "Terry Li"
date: last-modified
format:
  html:
    toc: true
    toc-depth: 3
    toc-expand: true
    number-sections: true
    code-fold: false
    code-tools: true
    code-link: true
---

# Overview

This document outlines the first phase of our Git workflow: environment preparation and status verification. It ensures a safe and informed starting point for any Git operations.

# Safety First: Core Principles

## Critical Safety Rules

1. NEVER amend pushed commits
   - Always check with `git rev-list --count origin/branch..HEAD` first
   - If the commit is pushed, create a new commit instead

2. NEVER force push without team approval
   - If you need to force push, consult team lead first
   - Document the reason for force push in commit message

3. ALWAYS verify remote status before:
   - Creating commits
   - Amending commits
   - Pushing changes

4. IF remote is ahead:
   - DO NOT amend any commits
   - Pull changes first
   - Create new commits for your changes

## Branch Divergence Prevention
1. Remote merge commits not in local branch
2. Force pushes to remote
3. Concurrent changes by multiple developers
4. Rebased remote branch

If divergence is detected:
1. Check the nature of divergence
2. Determine appropriate action:
   - If remote has merge commits: Pull and rebase
   - If local changes are independent: Create new branch
   - If changes conflict: Coordinate with team
3. Document resolution in commit message

# Environment Verification

## 1. SSH Connection Check
```bash
# Update remote info and verify connection
echo -e "\033[1;34m=== SSH VERIFICATION ===\033[0m" && \
ssh -T git@github.com-eonlabs 2>&1 | grep "successfully authenticated" && \
echo -e "\033[1;32m✓ SSH connection verified\033[0m"
```

## 2. Remote and Branch Status
```bash
# Check branch status
git remote update origin --prune

# Verify branch lineage and sync status
git rev-parse HEAD | xargs git branch -r --contains || \
echo "WARNING: Current commit not found in any remote branch"

git rev-list --left-right --count origin/$(git branch --show-current)...HEAD

# Check recent activity
echo -e "\033[1;34m=== BRANCH ACTIVITY ===\033[0m"
git for-each-ref --sort=-committerdate refs/remotes/origin \
--format='%(color:blue)%(authordate:relative)%09%(color:white)%(refname:short)%09%(color:reset)%(authorname)' | \
bat --style=plain --paging=never

echo -e "\n\033[1;34m=== YOUR BRANCHES ===\033[0m"
git for-each-ref --sort=-committerdate refs/remotes/origin \
--format='%(authordate:relative)%09%(refname:short)%09%(authorname)' | \
grep "Terry Li" | bat --style=plain --paging=never
```

# Workspace Analysis

## 1. Status Overview
```bash
# Show overall status and branch info
echo -e "\033[1;34m=== WORKSPACE STATUS ===\033[0m"
git status --branch --untracked-files=no | bat --style=plain --paging=never

# Show untracked files
echo -e "\n\033[1;34m=== UNTRACKED FILES ===\033[0m"
git ls-files --others --exclude-standard | bat --style=plain --paging=never || \
echo "No untracked files"
```

## 2. Changes Analysis
```bash
# Show changes summary
echo -e "\n\033[1;34m=== CHANGES SUMMARY ===\033[0m"
git diff --color=always --stat | bat --style=plain --paging=never --language=diff
git diff --cached --color=always --stat | bat --style=plain --paging=never --language=diff

# Show detailed changes (only if there are any)
if ! git diff --quiet; then
    echo -e "\n\033[1;34m=== UNSTAGED CHANGES ===\033[0m"
    git diff --color=always | bat --style=plain --paging=never --language=diff
fi

if ! git diff --cached --quiet; then
    echo -e "\n\033[1;34m=== STAGED CHANGES ===\033[0m"
    git diff --cached --color=always | bat --style=plain --paging=never --language=diff
fi
```

# Safety Verification

## 1. Commit Safety Check
```bash
echo -e "\033[1;34m=== COMMIT SAFETY CHECK ===\033[0m"

# Check if last commit exists on remote
echo "Remote commit check:"
AHEAD_COUNT=$(git rev-list --count origin/$(git branch --show-current)..HEAD)
if [ "$AHEAD_COUNT" -eq 0 ]; then
    echo -e "\033[1;31mWARNING: Commit is pushed - DO NOT AMEND\033[0m"
else
    echo -e "\033[1;32mSafe to amend - Commit is not pushed\033[0m"
fi

# Verify branch hasn't diverged
echo -e "\nDivergence check:"
if git merge-base --is-ancestor origin/$(git branch --show-current) HEAD; then
    echo -e "\033[1;32mBranch is up to date\033[0m"
else
    echo -e "\033[1;31mWARNING: Branches have diverged\033[0m"
    git log --graph --oneline --decorate HEAD...origin/$(git branch --show-current) | \
    bat --style=plain --paging=never --language=git
fi
```

## 2. Pre-Push Check
```bash
# Update remote info
git remote update origin --prune

# Check commits ahead/behind
git rev-list --left-right --count origin/$(git branch --show-current)...HEAD | \
bat --style=plain --paging=never

# Get commit ID for verification
git rev-parse HEAD | bat --style=plain --paging=never
```

# Next Steps

After completing these preparation steps:
1. If all checks pass ✅ - Proceed to [Git Workflow: Changes Analysis](git_workflow_changes.qmd)
2. If any warnings ⚠️ - Address them before proceeding
3. If any errors ❌ - Stop and consult team lead 