Learning_Git/Git_Workflow_Guide.md

# Git Workflow Guide for Life Planner

## Table of Contents

### 1. Quick Reference Guides
- [Life Planner Git Workflow Cheat Sheet](#life-planner-git-workflow-cheat-sheet)
  - [Start Day Process](#start-day-process)
  - [Start Task Process](#start-task-process)
  - [Save Work Process](#save-work-process)
  - [Complete Task Process](#complete-task-process)
  - [End Day Process](#end-day-process)

### 2. Error Resolution Guides
- [Start of Day Errors](#start-of-day-errors)
  - [Branch Already Exists](#branch-already-exists)
  - [Uncommitted Changes](#uncommitted-changes)
  - [Local Changes Overwrite](#local-changes-overwrite)
  - [Branch Name Mismatch](#branch-name-mismatch)
  - [End of Day Errors](#end-of-day-errors)
  - [Push Rejection Handling](#push-rejection-handling)
  - [Merge Conflict Resolution](#merge-conflict-resolution)

### 3. Detailed Workflow Processes
- [Starting Work for the Day](#starting-work-for-the-day)
- [Branch and Directory Navigation](#branch-and-directory-navigation)  <!-- New section -->
- [Working on Tasks](#working-on-tasks)
- [Handling Remote Changes](#handling-remote-changes)
- [End of Day Procedures](#end-of-day-procedures)

### 4. File Management
- [Local vs Remote Changes](#local-vs-remote-changes)
  - [Viewing Differences](#viewing-differences)
  - [Keeping Remote Changes](#keeping-remote-changes)
  - [Keeping Local Changes](#keeping-local-changes)
  - [Comparing Files](#comparing-files)

### 5. Scripts and Automation
- [Project Status Scripts](#project-status-scripts)
  - [Check Project Status](#check-project-status)
  - [Start Working on Project](#start-working-on-project)
  - [Update Task Status](#update-task-status)
  - [End of Day Commit](#end-of-day-commit)
- [Task Management Commands](#task-management-commands)
- [Report Generation](#report-generation)

### 6. Reference
- [Common Commit Messages](#common-commit-messages)
- [Status Check Commands](#status-check-commands)
- [Installation Instructions](#installation-instructions)
- [Usage Examples](#usage-examples)

---

# 1. Quick Reference Guides

## Life Planner Git Workflow Cheat Sheet

### Start Day Process
```markdown
START DAY:
1. git checkout main
2. git branch                                              # See which branch to checkout or create a new one
3. git pull origin main
4. git checkout -b working_projectname_YYYYMMDD
```
### Start Task Process
```markdown
START TASK:
1. git status
2. Show counts of Tasks by Status:
```
-
   ```bash
   echo "WORKING tasks: $(grep -r "tags: .*WORKING" . | wc -l)"
   echo "OPEN tasks: $(grep -r "tags: .*OPEN" . | wc -l)"
   echo "CLOSED tasks: $(grep -r "tags: .*CLOSED" . | wc -l)"
   ```
```markdown
3. Identify Task to work on:
   - grep -r "tags: .*WORKING" .                                  # View WORKING tasks
   - grep -r "tags: .*OPEN" .                                     # View OPEN tasks
   - grep -r "tags: .*CLOSED" .                                   # View CLOSED tasks
4. nano filename.md
5. Update task status to WORKING if starting a new task
```

### Save Work Process
```markdown
SAVE WORK:
1. git add filename.md (or git add .)
2. git commit -m "message"
```

### Complete Task Process
```markdown
COMPLETE TASK:
1. Update task status to CLOSED
2. git add filename.md
3. git commit -m "Completed task message"
```

### End Day Process
```markdown
END DAY:
1. Review Changes:
   - git status                                      # Check current status
   - git diff --name-only                            # List changed files
   - git log --oneline                               # View recent commits
2. Check Branch Status:
   - git branch --merged                             # List merged branches
   - git branch --no-merged                          # List unmerged branches
   - git branch -vv                                  # View branch details
3. Merge and Push:
    - git checkout main
    - git merge working_projectname_YYYYMMDD
    - git push
4. Clean Up:
   - git branch -d working_projectname_YYYYMMDD      # Delete merged branch
   - git branch                                      # Verify cleanup
   - git status
   ```

### Common Task Status Commands
```markdown
# Quick status checks
git status                                            # Current repository status
git branch                                            # List all branches
git diff --name-only                                  # List modified files

# Task status queries
grep -r "tags: .*WORKING" .                           # Find all WORKING tasks
grep -r "tags: .*OPEN" .                              # Find all OPEN tasks
grep -r "tags: .*CLOSED" .                            # Find all CLOSED tasks

# Branch management
git branch --merged                                   # Show merged branches
git branch --no-merged                                # Show unmerged branches
git branch -vv                                        # Detailed branch information
```

[Back to Top](#git-workflow-guide-for-life-planner)

---

# 2. Error Resolution Guides

## Start of Day Errors

### Branch Already Exists
```bash
1. git checkout main                              # Return to main branch
2. git branch -D working_projectname_YYYYMMDD     # Delete existing branch
3. git checkout -b working_projectname_YYYYMMDD   # Create new branch
```

### Uncommitted Changes
```bash
1. git stash                                      # Save current changes
2. git checkout main                              # Switch to main
3. git pull origin main                           # Get updates
4. git checkout -b working_projectname_YYYYMMDD   # Create new branch
5. git stash pop                                  # Restore your changes
```

### Local Changes Overwrite
```bash
1. git add .                                      # Stage current changes
2. git commit -m "WIP - Saving current progress"  # Save changes
3. git checkout main                              # Then proceed with normal process
```

### Branch Name Mismatch
```bash
1. git branch                                     # Check existing branches
2. git checkout main                              # Ensure on main
3. git pull origin main                           # Get latest changes
4. git checkout -b working_projectname_YYYYMMDD   # Create new branch (check spelling)
```

## End of Day Errors

### Push Rejection Handling
```bash
# When you see the error in your image:
1. git pull origin main     # Get remote changes
2. git merge main          # Merge them into your branch
3. git push origin main    # Try pushing again
```

### Merge Conflict Resolution
If you get conflicts during the merge:
1. Open the conflicted files
2. Look for conflict markers (<<<<<<, =======, >>>>>>>)
3. Edit the files to resolve conflicts
4. Save the files
5. `git add .` to mark conflicts as resolved
6. `git commit -m "Resolved merge conflicts"`

[Back to Top](#git-workflow-guide-for-life-planner)

---

# 3. Detailed Workflow Processes

## Starting Work for the Day
1. `git checkout main`
   - Switch to main branch to ensure you're starting from the latest version
   
2. `git pull`
   - Get any updates that might have been made elsewhere

3. `git checkout -b working_projectname_YYYYMMDD`
   - Create and switch to a new branch for today's work
   - Example: `git checkout -b working_financial_20231031`

## Branch and Directory Navigation

### Best Practices
Always work from the life_planner root directory when creating and managing branches. This ensures proper version control and file tracking.

```bash
# Correct approach (from life_planner root directory):
/mnt/d/OneDrive/GH_Repositories/life_planner$ git checkout main
/mnt/d/OneDrive/GH_Repositories/life_planner$ git pull origin main
/mnt/d/OneDrive/GH_Repositories/life_planner$ git checkout -b working_projectname_YYYYMMDD
```

### Benefits of Working from Root Directory
1. Git tracks all project files from the root directory
2. Ensures consistent branch management
3. Prevents potential branch/tracking issues
4. Maintains clear project history

### Why Not CD Into Project Directory
- Git branches affect the entire repository
- Working from a subdirectory might:
  - Cause confusion about which files are being tracked
  - Lead to incomplete commits
  - Make it harder to manage multiple task files

### Example Workflow
```bash
# 1. Start in life_planner root
/mnt/d/OneDrive/GH_Repositories/life_planner$

# 2. Create/checkout branch
git checkout -b working_financial_20231101

# 3. Then you can edit files in any project subdirectory
vim ONG_Assessing_Financial_Situation/01_T_MS1_Connect_all_financial_accounts_in_Tiller.md

# 4. Git commands will work for all modified files
git status    # Shows changes across all directories
git add .     # Stages changes from all directories
```

## Working on Tasks

### Before Starting a Task
1. `git status`
   - Check which files have been modified
   - Verify you're on the correct branch

2. Update task status in markdown file
   - Change task status tag from OPEN to WORKING
   - Example: `tags: [WORKING, MS1_Tiller_Account_Setup]`

### While Working
1. `git add filename.md`
   - Stage specific files you've modified
   - Or use `git add .` to stage all changes

2. `git commit -m "Meaningful commit message"`
   - Save your changes with a clear message
   - Example: "Updated Task 1.1 status to WORKING"

## Handling Remote Changes

### Process for Remote Updates
1. First, stage your local changes:
```bash
git add .
git commit -m "End of day changes - YYYY-MM-DD"
```

2. Switch to main branch:
```bash
git checkout main
```

3. Get remote changes BEFORE merging your work:
```bash
git pull origin main
```

4. Switch back to your working branch:
```bash
git checkout working_projectname_YYYYMMDD
```

5. Integrate main's changes into your working branch:
```bash
git merge main
```
- Resolve any conflicts if they occur

## End of Day Procedures

### Finishing a Task
1. Update task status to CLOSED
   - Change task status tag to CLOSED
   - Example: `tags: [CLOSED, MS1_Tiller_Account_Setup]`

2. Stage and commit the status change:
```bash
git add filename.md
git commit -m "Completed Task 1.1 - [Brief description]"
```

### Final Steps
1. Switch to main branch:
```bash
git checkout main
```

2. Merge your work:
```bash
git merge working_projectname_YYYYMMDD
```

3. Push changes:
```bash
git push origin main
```

4. Clean up:
```bash
git branch -d working_projectname_YYYYMMDD
```

[Back to Top](#git-workflow-guide-for-life-planner)

---

# 4. File Management

## Local vs Remote Changes

### Viewing Differences
```bash
# See what's different between your local file and remote
git diff workflow_overview.md

# For a more detailed view
git diff origin/main workflow_overview.md

# View file content differences
git diff --word-diff workflow_overview.md
```

### Keeping Remote Changes
```bash
# Option 1: Discard local changes for specific file
git checkout origin/main workflow_overview.md

# Option 2: Force overwrite local with remote
git fetch origin
git reset --hard origin/main
```
⚠️ WARNING: `reset --hard` will discard ALL local changes!

### Keeping Local Changes
```bash
# Stash your local changes
git stash

# Pull remote changes
git pull

# Then decide:
git stash pop   # Apply your local changes back
# or
git stash drop  # Discard your local changes
```

### Comparing Files

#### View Current Changes
```bash
# View local file content
cat workflow_overview.md

# View remote file content
git show origin/main:workflow_overview.md

# Compare specific versions
git diff HEAD~1 workflow_overview.md  # Compare with previous version
```

#### Quick Solutions for Common Scenarios

##### To Overwrite Local with Remote:
```bash
# For specific file
1. git checkout origin/main workflow_overview.md
2. git pull

# For all files
1. git fetch origin
2. git reset --hard origin/main
```

##### To Keep Both and Decide Later:
```bash
1. git stash
2. git pull
3. git stash pop
4. # Resolve any conflicts manually
```

##### To Compare and Decide:
```bash
# View differences
git diff workflow_overview.md

# Keep remote version
git checkout origin/main workflow_overview.md

# Or keep local and commit
git add workflow_overview.md
git commit -m "Keeping local changes to workflow_overview.md"
git pull
```

#### Best Practices for File Management
1. Always check status before making changes:
   ```bash
   git status
   ```

2. Review changes before committing:
   ```bash
   git diff --staged  # For staged changes
   git diff          # For unstaged changes
   ```

3. Use meaningful commit messages:
   ```bash
   git commit -m "Updated workflow documentation with new file management section"
   ```

4. Regularly sync with remote:
   ```bash
   git fetch origin
   git status  # Check if you're behind/ahead
   ```

[Back to Top](#git-workflow-guide-for-life-planner)

---

# 5. Scripts and Automation

## Project Status Scripts

### Check Project Status
```bash
#!/bin/bash

echo "=== Current Project Statuses ==="
echo "-------------------------------"

# Find all README.md files and check their status tags
find . -name "README.md" -type f -exec sh -c '
    echo "Project: $(dirname {})"
    grep -H "STATUS:" {} 2>/dev/null
    echo
' \;

echo "=== Active (WORKING) Tasks ==="
echo "-----------------------------"
find . -name "*.md" -type f -exec sh -c '
    if grep -l "tags: .*WORKING" "$0" >/dev/null; then
        echo "File: $0"
        head -n 3 "$0"
        echo "---"
    fi
' {} \;
```

### Start Working on Project
```bash
#!/bin/bash

start_project() {
    local project_name=$1
    
    # Create and checkout new branch
    git checkout -b "working_${project_name}_$(date +%Y%m%d)"
    
    # Show current tasks in project
    echo "Current tasks in $project_name:"
    find "$project_name" -name "*.md" -type f -exec sh -c '
        echo "=== $(basename $1) ==="
        grep "tags:" "$1" 2>/dev/null
        echo
    ' sh {} \;
}

# Usage: ./start_project.sh project_name
start_project "$1"
```

### Update Task Status
```bash
#!/bin/bash

update_task_status() {
    local task_file=$1
    local new_status=$2
    
    # Update status in task file
    sed -i "s/tags: \[.*\]/tags: [$new_status/" "$task_file"
    
    # Add to git
    git add "$task_file"
    
    echo "Updated status of $task_file to $new_status"
}

# Usage: ./update_task.sh task_file.md WORKING
update_task_status "$1" "$2"
```

### End of Day Commit
```bash
#!/bin/bash

end_day_commit() {
    # Get current branch
    current_branch=$(git branch --show-current)
    
    # Generate work summary
    echo "=== Work Summary $(date +%Y-%m-%d) ===" > work_summary.tmp
    echo "Branch: $current_branch" >> work_summary.tmp
    echo "" >> work_summary.tmp
    
    # Find all modified files
    echo "Modified Tasks:" >> work_summary.tmp
    git diff --name-only | while read -r file; do
        if [[ $file == *.md ]]; then
            echo "- $file" >> work_summary.tmp
            grep "tags:" "$file" >> work_summary.tmp
        fi
    done
    
    # Create commit message
    commit_msg=$(cat work_summary.tmp)
    
    # Commit changes
    git add .
    git commit -m "$commit_msg"
    
    # Merge back to main
    git checkout main
    git merge "$current_branch"
    
    # Clean up
    rm work_summary.tmp
    
    echo "Day's work committed and merged"
}

end_day_commit
```

## Task Management Commands
```bash
# Show all WORKING tasks
find . -type f -name "*.md" -exec sh -c '
    if grep -l "tags: .*WORKING" "$0" >/dev/null; then
        echo "=== $0 ==="
        head -n 5 "$0"
        echo
    fi
' {} \;

# Show tasks by milestone
find . -type f -name "*.md" -exec sh -c '
    if grep -l "tags: .*MS1" "$0" >/dev/null; then
        echo "=== $0 ==="
        grep "tags:" "$0"
        echo
    fi
' {} \;
```

## Report Generation
```bash
#!/bin/bash

generate_report() {
    local report_file="progress_report_$(date +%Y%m%d).md"
    
    echo "# Progress Report $(date +%Y-%m-%d)" > "$report_file"
    echo "" >> "$report_file"
    
    # Project Status Summary
    echo "## Project Status" >> "$report_file"
    find . -name "README.md" -type f -exec sh -c '
        echo "### $(dirname {})"
        grep "STATUS:" {} 2>/dev/null
        echo
    ' >> "$report_file" \;
    
    # Task Status by Milestone
    echo "## Task Status by Milestone" >> "$report_file"
    for milestone in MS{1..7}; do
        echo "### $milestone" >> "$report_file"
        echo "#### WORKING:" >> "$report_file"
        find . -type f -name "*.md" -exec grep -l "tags: .*WORKING.*$milestone" {} \; >> "$report_file"
        echo "#### CLOSED:" >> "$report_file"
        find . -type f -name "*.md" -exec grep -l "tags: .*CLOSED.*$milestone" {} \; >> "$report_file"
        echo "" >> "$report_file"
    done
    
    echo "Report generated: $report_file"
}

generate_report
```

[Back to Top](#git-workflow-guide-for-life-planner)

---

# 6. Reference

## Common Commit Messages
```markdown
# Starting Task
"Started work on Task X.X - Brief description"
"Initialized Task X.X - Setting up environment"

# Status Updates
"Updated Task X.X status to WORKING"
"Updated Task X.X status to CLOSED"
"In progress: Task X.X - Current status update"

# Task Completion
"Completed Task X.X - Brief description of accomplishment"
"Finished Task X.X - Added all requested features"

# End of Day
"End of day commit - Tasks X.X, X.X completed"
"Daily progress - Multiple task updates"

# WIP (Work in Progress)
"WIP: Task X.X - Saving current progress"
"WIP: Intermediate save for Task X.X"
```

## Status Check Commands
```bash
# Basic Status Checks
git status                      # Current working state
git log --oneline              # Commit history in compact form
git branch                     # List all branches
git remote -v                  # Show remote repositories

# Detailed Checks
git log --graph --decorate     # Visual commit history
git diff --name-status         # List of changed files
git show HEAD                  # Latest commit details
git remote show origin         # Remote branch details

# Branch Information
git branch -vv                 # Verbose branch info
git branch --merged            # Show merged branches
git branch --no-merged        # Show unmerged branches

# File History
git log --follow filename     # File history including renames
git blame filename           # Line-by-line change history
```

## Installation Instructions

### 1. Initial Setup
```bash
# Make scripts directory
mkdir -p ~/life_planner/scripts

# Copy all scripts
cp *.sh ~/life_planner/scripts/

# Make scripts executable
chmod +x ~/life_planner/scripts/*.sh
```

### 2. Configure Git
```bash
# Set up user information
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

# Set default branch name
git config --global init.defaultBranch main

# Set up aliases for common commands
git config --global alias.st status
git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.ci commit
```

### 3. Script Installation
```bash
# Add to PATH (add to .bashrc or .zshrc)
export PATH="$PATH:$HOME/life_planner/scripts"

# Verify installation
which start_project.sh
which update_task.sh
which end_day_commit.sh
```

## Usage Examples

### Daily Workflow Example
```bash
# Morning Start
git checkout main
git pull
git checkout -b working_financial_20231101

# Start New Task
vim task1.md                    # Edit task status to WORKING
git add task1.md
git commit -m "Started Task 1.1 - Setting up Tiller"

# Complete Task
vim task1.md                    # Edit task status to CLOSED
git add task1.md
git commit -m "Completed Task 1.1 - Tiller setup complete"

# End of Day
git checkout main
git pull
git merge working_financial_20231101
git push
git branch -d working_financial_20231101
```

### Using Automation Scripts
```bash
# Start new project work
./start_project.sh financial_planning

# Update task status
./update_task.sh task1.md WORKING
./update_task.sh task1.md CLOSED

# Generate daily report
./generate_report.sh

# End of day commit
./end_day_commit.sh
```

### Common Scenarios

#### Handling Interruptions
```bash
# Save current work
git add .
git commit -m "WIP: Saving progress on Task 1.1"

# Switch to urgent task
git checkout -b urgent_fix
# ... work on urgent task ...

# Return to previous work
git checkout working_financial_20231101
```

#### Managing Multiple Tasks
```bash
# List all active tasks
find . -name "*.md" -exec grep -l "tags: .*WORKING" {} \;

# Check task status
git status
git diff --name-only

# Review day's changes
git log --since="6am" --oneline
```

[Back to Top](#git-workflow-guide-for-life-planner)

---