my-vault/06_Metadata/Reference/GIT_WORKFLOW.md

---
created: 2026-01-06
type: reference
tags: [git, workflow, version-control]
---

# Git Workflow Guide

Complete guide to Git version control for your Obsidian vault.

---

## Critical Rule

**ALWAYS start sessions with `git pull`** to sync latest changes from remote repository.

This prevents conflicts and ensures you're working with the latest version.

---

## Daily Workflow

### Morning (Session Start)

```bash
cd ~/Documents/ob-vault/my-vault
git pull
git status                  # Check for any conflicts
```

**What this does**:
- Changes to vault directory
- Pulls latest changes from remote
- Shows current status (conflicts, uncommitted changes)

### During Work

```bash
git status                  # Periodically check changes
```

**Optional**: Check what's been modified while working.

### Evening (Session End)

```bash
git status                  # Review all changes
git add <改动的具体路径>      # 按路径暂存，别盲加
node .scripts/verify-vault.mjs   # 密钥扫描，退出码必须为 0
git commit -m "vault backup: $(date +%Y-%m-%d\ %H:%M:%S)"
git push                    # Sync to remote（仅人工执行；agent 受 AGENTS.md 约束）
```

**What this does**:
- Shows all modified/new/deleted files
- Stages everything for commit
- Creates commit with timestamp
- Pushes to remote repository

---

## Commit Message Guidelines

### Format

```
[type]: [brief description]

Examples:
vault backup: 2026-01-06 20:30:15
Add: Project planning notes for Q1 initiatives
Update: Weekly review template with new sections
Organize: Moved inbox items to appropriate folders
Archive: Completed research project
```

### Common Types

| Type | When to Use | Example |
|------|-------------|---------|
| `vault backup:` | Regular daily backup | `vault backup: 2026-01-06 20:00` |
| `Add:` | New notes/projects | `Add: Machine learning project notes` |
| `Update:` | Modify existing content | `Update: CLAUDE.md with new workflow` |
| `Organize:` | File movements | `Organize: Processed inbox items` |
| `Archive:` | Moving to archive | `Archive: Completed Q4 projects` |
| `Fix:` | Bug fixes, broken links | `Fix: Broken attachment links` |

### When to Commit

- ✅ After organizing inbox
- ✅ After creating new notes
- ✅ After significant edits
- ✅ Before ending session
- ✅ After weekly review
- ✅ After major reorganization

**Don't**: Commit every single edit. Batch related changes together.

---

## Common Git Commands

### Essential Commands

```bash
git status                  # Check current state
git pull                    # Sync from remote
git add <具体路径>           # Stage specific files
git commit -m "message"     # Commit with message
git push                    # Sync to remote
git log --oneline -10       # View recent commits
```

### Useful Commands

```bash
# View what changed in a file
git diff filename.md

# View all recent changes
git diff

# View commit history
git log --oneline

# View changes in last commit
git show

# Unstage a file (before commit)
git restore --staged filename.md

# Discard changes to a file (DANGER)
git restore filename.md
```

### File History

```bash
# Find when a file was deleted/moved
git log --all --full-history -- path/to/file.md

# View all commits that touched a file
git log --follow -- path/to/file.md

# See file contents from specific commit
git show <commit-hash>:path/to/file.md
```

---

## Handling Conflicts

### When Conflicts Happen

**Scenario**: You run `git pull` and see:

```
CONFLICT (content): Merge conflict in filename.md
Automatic merge failed; fix conflicts and then commit the result.
```

### Resolution Steps

**1. Open conflicted file**

You'll see markers like this:

```markdown
Normal content here...

<<<<<<< HEAD
Your local changes
=======
Remote changes from other device
>>>>>>> origin/main

More normal content...
```

**2. Resolve manually**

Choose which version to keep (or combine both):

```markdown
Normal content here...

Combined changes (best of both versions)

More normal content...
```

Delete conflict markers (`<<<<<<<`, `=======`, `>>>>>>>`).

**3. Stage and commit**

```bash
git add <已解决冲突的文件>
git commit -m "Resolve merge conflicts"
git push
```

### Preventing Conflicts

**Best Practices**:
1. ✅ Always `git pull` before starting work
2. ✅ Commit and push at end of each session
3. ✅ Don't edit same file on multiple devices simultaneously
4. ✅ Use descriptive commit messages to track changes

**If working on multiple devices**:
- Device A: Edit → Commit → Push
- Device B: Pull → Edit → Commit → Push
- Device A: Pull (gets Device B's changes)

---

## Advanced Workflows

### Checking Changes Before Commit

```bash
# See what will be committed
git status

# See detailed changes
git diff

# Review changes file by file
git diff filename.md
```

### Selective Staging

```bash
# Stage specific files only
git add path/to/file1.md path/to/file2.md

# Stage all markdown files
git add "*.md"

# Stage entire folder
git add 01_Projects/
```

### Commit History

```bash
# Last 10 commits (one line each)
git log --oneline -10

# Detailed view
git log -5

# With file changes
git log --stat -5

# Search commits by message
git log --grep="inbox"

# Commits from last week
git log --since="1 week ago"
```

### Undoing Changes

**Before Commit (Unstage)**:
```bash
# Unstage specific file
git restore --staged filename.md

# Unstage everything
git restore --staged .
```

**Discard Local Changes** (⚠️ DANGER - Cannot undo):
```bash
# Discard changes to specific file
git restore filename.md

# Discard ALL local changes
git restore .
```

**After Commit (Advanced)**:
```bash
# Undo last commit (keep changes)
git reset --soft HEAD~1

# Undo last commit (discard changes) - DANGER
git reset --hard HEAD~1
```

⚠️ **Warning**: Only use `reset --hard` if you're certain. Changes are lost permanently.

---

## .gitignore

### What to Ignore

Your `.gitignore` file should exclude:

```gitignore
# Obsidian workspace (device-specific)
.obsidian/workspace.json
.obsidian/workspace-mobile.json

# System files
.DS_Store
Thumbs.db
desktop.ini

# Temporary files
*.tmp
~$*.md

# Sensitive files (if any)
.env
secrets/
```

### What to Commit

✅ **Do commit**:
- `.obsidian/` (most config)
- All markdown files (`.md`)
- Attachments in `05_Attachments/`
- Templates, scripts, documentation

❌ **Don't commit**:
- Workspace files (device-specific layout)
- System files (`.DS_Store`)
- Large binary files (videos) - use Git LFS
- Sensitive information (API keys, passwords)

---

## Troubleshooting

### "Repository not found"

**Problem**: Can't push/pull from remote

**Solution**:
```bash
# Check remote URL
git remote -v

# Fix remote URL if needed
git remote set-url origin <correct-url>
```

### "Your branch is ahead by N commits"

**Meaning**: You have local commits not pushed to remote

**Solution**:
```bash
git push
```

### "Your branch is behind by N commits"

**Meaning**: Remote has commits you don't have locally

**Solution**:
```bash
git pull
```

### "Diverged branches"

**Meaning**: You and remote both have different commits

**Solution**:
```bash
git pull                    # May auto-merge
# If conflicts, resolve manually
git add <已解决冲突的文件>
git commit -m "Resolve merge conflicts"
git push
```

### "Permission denied (publickey)"

**Problem**: SSH key not configured

**Solutions**:
1. **Use HTTPS instead of SSH**:
   ```bash
   git remote set-url origin https://github.com/username/repo.git
   ```

2. **Or configure SSH key**:
   - Generate: `ssh-keygen -t ed25519 -C "your_email@example.com"`
   - Add to GitHub: Settings → SSH Keys → Add Key

### Accidentally Committed Sensitive File

**Immediate Action**:
```bash
# Remove from Git (keep local file)
git rm --cached sensitive-file.txt

# Add to .gitignore
echo "sensitive-file.txt" >> .gitignore

# Commit removal
git add .gitignore
git commit -m "Remove sensitive file from tracking"
git push
```

**⚠️ Note**: File still exists in Git history. For complete removal, use `git filter-branch` or BFG Repo-Cleaner (advanced).

---

## Best Practices

### DO ✅

- **Pull before starting work** (every session)
- **Commit frequently** (daily minimum)
- **Use descriptive messages** (understand changes later)
- **Push at end of session** (backup to remote)
- **Review `git status`** before committing
- **Keep commits atomic** (one logical change per commit)

### DON'T ❌

- **Never force push** to main/master (`git push --force`) —— 例外仅限一次性的历史清理维护窗口（清除已泄漏密钥，见 SECURITY_ROTATION_LOG）
- **Don't commit secrets** (API keys, passwords) —— 提交前跑 `node .scripts/verify-vault.mjs`；agent 会话一律禁用 `git add .` 与 `git push`（见 AGENTS.md 权限表）
- **Don't commit huge files** (videos > 50MB - use Git LFS)
- **Don't edit history** of pushed commits (causes conflicts)
- **Don't ignore conflicts** (resolve immediately)

---

## Multi-Device Workflow

### Device A (Desktop)

```bash
# Morning
git pull

# Work throughout day...

# Evening
git add <改动的具体路径>
git commit -m "vault backup: $(date)"
git push
```

### Device B (Laptop)

```bash
# Later that evening
git pull                    # Gets Desktop's changes

# Work on laptop...

# Before sleep
git add <改动的具体路径>
git commit -m "vault backup: $(date)"
git push
```

### Device A (Next Day)

```bash
# Next morning
git pull                    # Gets Laptop's changes

# Continue working...
```

**Key**: Always pull before starting, push when done.

---

## Quick Reference

### Most Used Commands

```bash
# Daily workflow
git pull                                    # Start of session
git status                                  # Check changes
git add <paths>                             # Stage specific files
git commit -m "vault backup: $(date)"      # Commit
git push                                    # End of session

# Viewing history
git log --oneline -10                       # Recent commits
git diff                                    # See changes

# Fixing issues
git restore --staged .                      # Unstage
git restore filename.md                     # Discard changes
```

### Emergency Commands

```bash
# Conflicts during pull
git status                  # See conflicted files
# Edit files manually
git add .
git commit -m "Resolve conflicts"
git push

# Undo last commit (keep changes)
git reset --soft HEAD~1

# Completely reset to remote (DANGER - loses local changes)
git fetch origin
git reset --hard origin/main
```

---

## Further Reading

**Official Git Documentation**: https://git-scm.com/doc

**Recommended Learning**:
- Git basics: https://git-scm.com/book/en/v2/Getting-Started-About-Version-Control
- Branching (advanced): https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging

**Visual Git Tools**:
- GitKraken (GUI client)
- GitHub Desktop (simple interface)
- VS Code built-in Git (integrated)

---

**Last Updated**: 2026-09-26
**See Also**: [[CLAUDE]], [[QUICK_REFERENCE]], [[TROUBLESHOOTING]]