Added Git_Workflow_Guide.md

I added this git workflow that I made for a project I have on my GitHub.  I created the project to track projects using GitHub so I could learn Git along with using a new task management process that I created. Most of this is relevant for any Git,  but keep in mind it was created for specifically my task management on Github.
This commit is contained in:
2024-10-31 16:24:12 -06:00
commit 3428c131a2

716
Git_Workflow_Guide.md Normal file
View File

@@ -0,0 +1,716 @@
# 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)
- [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 pull
3. git checkout -b working_projectname_YYYYMMDD
```
### Start Task Process
```markdown
START TASK:
4. git status
5. Update task status to WORKING
```
### Save Work Process
```markdown
SAVE WORK:
6. git add filename.md (or git add .)
7. git commit -m "message"
```
### Complete Task Process
```markdown
COMPLETE TASK:
8. Update task status to CLOSED
9. git add filename.md
10. git commit -m "Completed task message"
```
### End Day Process
```markdown
END DAY:
11. git checkout main
12. git merge working_projectname_YYYYMMDD
13. git push
14. git branch -d working_projectname_YYYYMMDD
```
[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`
## 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)
---