Skip to content
Eon-Labs KB

Cursor Agent: Git commit and push workflow

Source: Notion | Last edited: 2025-01-10 | ID: 1752d2dc-3ef...

File attachment

---
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

Section titled “2. Remote and Branch Status”
Terminal window
# 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

Section titled “Workspace Analysis”

1. Status Overview

Section titled “1. Status Overview”
Terminal window
# 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

Section titled “2. Changes Analysis”
Terminal window
# 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

Section titled “Safety Verification”

1. Commit Safety Check

Section titled “1. Commit Safety Check”
Terminal window
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

Section titled “2. Pre-Push Check”
Terminal window
# 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

Section titled “Next Steps”

After completing these preparation steps:

  1. If all checks pass ✅ - Proceed to Git Workflow: Changes Analysis
  2. If any warnings ⚠️ - Address them before proceeding
  3. If any errors ❌ - Stop and consult team lead
2025-01-10 auto open GitHub commit ID-ed page


2025-01-09 fix: interactive 60 sec wait now working


```markdown
---
title: "Git Workflow: Changes Analysis"
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 second phase of our Git workflow: analyzing changes and creating well-structured commits. It assumes you have completed the environment preparation phase outlined in [Git Workflow: Environment Preparation](git_workflow_preparation.qmd).


# Change Analysis Phase


## 1. Scope Analysis
Analyze the changes to understand:
1. Number of files changed
2. Types of files affected
3. Lines added/modified/deleted
4. Unintended changes or debug code
5. Sensitive data exposure


## 2. Impact Analysis
Consider the implications:
1. Dependencies affected
2. Breaking changes
3. Performance implications
4. Security considerations
5. Potential side effects


## 3. Context Analysis
Review the development context:
1. Original problem statement
2. Key constraints and requirements
3. Solution approach and rationale
4. Technical decisions made
5. Future considerations or TODOs


# Commit Creation Phase


## 1. Title Format
- Based on the context of the commit, state the type carefully:
  * chore: Maintenance tasks
  * docs: Documentation changes
  * feat: New features
  * fix: Bug fixes
  * refactor: Code restructuring
  * style: Formatting changes
  * test: Test-related changes
- Suffix all title lines with the current Jira Story ID (e.g. " EI-1009")


## 2. Body Format
- Multi-paragraph body with clear sections
- No markdown formatting
- Use nested dash (-) bullet points
- Surround code elements in backticks:
  * Code snippets
  * Variable names
  * Filenames
  * Git branch names
- Values in footers use backticks except:
  * "Reviewed-by:"
  * "Refs:"


## 3. Interactive Commit Creation
```bash
# Create and preview commit message with interactive confirmation
MSG=$(printf 'type: subject line EI-XXXX\n\nProblem Context:\n- Files affected: [list affected files]\n- Scope: [describe scope of changes]\n- Impact: [describe impact on system]\n\nSolution Implementation:\n- [key implementation detail 1]\n- [key implementation detail 2]\n- [key implementation detail 3]\n\nChanges Made:\n- [specific change 1]\n- [specific change 2]\n- [specific change 3]\n- [specific change 4]\n\nSummary:\n- [high-level outcome 1]\n- [high-level outcome 2]\n- [high-level outcome 3]\n\nDate: %s' "$(date '+%Y-%m-%d %H:%M:%S %z (%Z)')") && \
echo -e "\033[1;34m=== COMMIT MESSAGE PREVIEW ===\033[0m\n$MSG" && \
echo -e "\nProceed with this commit message? (y/n) " && \
read -r response && \
if [ "$response" = "y" ]; then
    git add . && git commit -m "$MSG" && git push origin $(git branch --show-current)
else
    echo "Commit aborted"
fi

4. Amending Commits (Only if Unpushed)

Section titled “4. Amending Commits (Only if Unpushed)”
Terminal window
# First verify commit is not pushed
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"
    exit 1
fi


# Create and preview amended message with interactive confirmation
AMEND_MSG=$(printf 'type: subject line EI-XXXX\n\nProblem Context:\n- Files affected: [list affected files]\n- Scope: [describe scope of changes]\n- Impact: [describe impact on system]\n\nSolution Implementation:\n- [key implementation detail 1]\n- [key implementation detail 2]\n- [key implementation detail 3]\n\nChanges Made:\n- [specific change 1]\n- [specific change 2]\n- [specific change 3]\n- [specific change 4]\n\nSummary:\n- [high-level outcome 1]\n- [high-level outcome 2]\n- [high-level outcome 3]\n\nDate: %s' "$(date '+%Y-%m-%d %H:%M:%S %z (%Z)')") && \
echo -e "\033[1;34m=== AMENDED COMMIT MESSAGE PREVIEW ===\033[0m\n$AMEND_MSG" && \
echo -e "\nProceed with this amended commit message? (y/n) " && \
read -r response && \
if [ "$response" = "y" ]; then
    git commit --amend -m "$AMEND_MSG"
else
    echo "Amend aborted"
fi

Common Mistakes to Avoid

Section titled “Common Mistakes to Avoid”

1. Command Syntax

Section titled “1. Command Syntax”
  1. NEVER use -am flag with piped input
  2. ALWAYS use --amend -F - for piped commits
  3. NEVER add trailing - as a separate argument

Examples:

Terminal window
❌ echo "$MSG" | git commit -am -     # Wrong: -am with trailing -
❌ git commit -am "$MSG"              # Wrong: -am with piped message
❌ echo "$MSG" | git commit -m -      # Wrong: -m with piped input
✅ echo "$MSG" | git commit --amend -F -  # Correct: proper piping with -F

2. Process Mistakes

Section titled “2. Process Mistakes”
  1. Not reviewing changes before commit
  2. Skipping the interactive confirmation
  3. Amending pushed commits
  4. Using force push without approval
  5. Not checking branch status

Commit Review and Link Handling

Section titled “Commit Review and Link Handling”

After pushing, review commit in browser:

  1. Using open command (macOS):

    Terminal window
    # Get latest commit hash and open in browser
    open "$(git remote get-url origin | sed 's/git@github.com:/https:\/\/github.com\//')/commit/$(git rev-parse HEAD)"
---


## Updates


2025-01-09 seperation of concerns into two QMD files; 60 seconds wait time when interacting with users on  `y/n`


2025-01-08 interactive PREVIEW and confirmation `y/n` of the commit message