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

created, type, tags

created	type	tags
2026-01-06	reference	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)

cd D:\tmp\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

git status                  # Periodically check changes

Optional: Check what's been modified while working.

Evening (Session End)

git status                  # Review all changes
git add .                   # Stage all changes
git commit -m "vault backup: $(date +%Y-%m-%d\ %H:%M:%S)"
git push                    # Sync to remote

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

git status                  # Check current state
git pull                    # Sync from remote
git add .                   # Stage all changes
git commit -m "message"     # Commit with message
git push                    # Sync to remote
git log --oneline -10       # View recent commits

Useful Commands

# 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

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

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

Normal content here...

Combined changes (best of both versions)

More normal content...

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

3. Stage and commit

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

# See what will be committed
git status

# See detailed changes
git diff

# Review changes file by file
git diff filename.md

Selective Staging

# 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

# 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):

# Unstage specific file
git restore --staged filename.md

# Unstage everything
git restore --staged .

Discard Local Changes (⚠️ DANGER - Cannot undo):

# Discard changes to specific file
git restore filename.md

# Discard ALL local changes
git restore .

After Commit (Advanced):

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

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

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

git push

"Your branch is behind by N commits"

Meaning: Remote has commits you don't have locally

Solution:

git pull

"Diverged branches"

Meaning: You and remote both have different commits

Solution:

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:

   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:

# 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)
• Don't commit secrets (API keys, passwords)
• 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)

# Morning
git pull

# Work throughout day...

# Evening
git add .
git commit -m "vault backup: $(date)"
git push

Device B (Laptop)

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

# Next morning
git pull                    # Gets Laptop's changes

# Continue working...

Key: Always pull before starting, push when done.

---

Quick Reference

Most Used Commands

# Daily workflow
git pull                                    # Start of session
git status                                  # Check changes
git add .                                   # Stage all
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

# 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-01-06 See Also: CLAUDE, QUICK_REFERENCE, TROUBLESHOOTING