AI generated in dialogue with humans. Not fully reviewed.
A plain-English explanation of git for people who want to understand what they're doing, not just memorize commands.
Git is like a time machine for your files. It lets you:
When working with git, your files exist in three different spaces:
This is your actual files - what you see and edit in Obsidian or any text editor. This is "right now" - your current reality.
Think of this as a loading dock or preparation area. You put files here when you're getting ready to take a snapshot. It's like saying "these are the files I want to include in my next snapshot."
The staging area lets you be selective - you might have changed 10 files but only want to snapshot 3 of them right now.
This is where all your snapshots are permanently stored on your computer. Once a snapshot is here, it's safe and you can always get back to it.
What it means: "I want this file in my next snapshot"
The metaphor: You're gathering items to photograph. You arrange them on a table (the staging area) before taking the picture.
Command: git add filename or git add . (for everything)
When you do it: After you've edited files and saved them, but before you take the snapshot
What it means: "Take a snapshot right now of everything in the staging area"
The metaphor: Clicking the camera button. You create a permanent photograph of exactly what's on the table (staging area). This photo gets added to your album (repository) and will never change.
Command: git commit -m "describe what changed"
What happens:
Important: A commit is LOCAL - it's only on your computer. The cloud doesn't know about it yet.
What it means: "Send all my local snapshots that the cloud doesn't have yet"
The metaphor: Uploading your photo album to cloud storage. You're synchronizing your local history with the remote backup.
Command: git push
What happens:
Important: Push ONLY uploads commits, not uncommitted changes. If you've edited files but haven't committed, those changes stay on your computer.
What it means: "Get any snapshots from the cloud that I don't have yet"
The metaphor: Downloading updates to the photo album that others have added. You're bringing your local copy up to date with what's in the cloud.
Command: git pull
What happens:
Important: Always pull before starting work if others might have made changes.
1. Edit your files in Obsidian
2. Save (Cmd+S)
3. Stage everything: git add .
4. Take snapshot: git commit -m "updated chapter 3"
5. Send to cloud: git push
Start of work:
1. Pull from cloud (get latest)
During work:
2. Edit files
3. Save frequently (Cmd+S)
4. Stage and commit whenever you complete a logical chunk
- After finishing a section
- After fixing a bug
- After completing a thought
End of work:
5. Final commit if needed
6. Push everything to cloud
1. Complete a significant piece of work
2. Stage and commit your changes
3. Push to cloud: git push
4. Create a tag: git tag "milestone-name"
5. Push the tag to cloud: git push --tags
CRITICAL: Tags are NOT pushed automatically!
You must explicitly run 'git push --tags' to send tags to the cloud.
Some people get confused by staging. Here's the deal:
Without staging: Every snapshot would include ALL changes to ALL files. You'd have no control.
With staging: You choose exactly what goes in each snapshot. This lets you:
Example: You fixed a typo in file A and rewrote a whole section in file B. These are unrelated changes. You can:
git add "file A.md"git commit -m "fixed typo"git add "file B.md"git commit -m "rewrote introduction"Now your history clearly shows two separate changes instead of one confusing mixed commit.
Key insight: You can commit 10 times locally, then push once to send all 10 commits to the cloud. Or you can push after every commit. It's up to you.
Command: git status
This tells you:
Think of it as asking "what's the current state of everything?"
Good rule: Commit whenever you complete a logical unit of work that you'd want to be able to return to.
Too often: After every sentence (creates noise)
Too rarely: Once a week (can't get back to intermediate states)
Just right: After completing a section, fixing an issue, or finishing a coherent thought
Minimum: At the end of each work session
Better: After each commit (if you want immediate backup)
Best: Whatever makes you feel your work is safely backed up
Remember: Committed work is safe locally. Pushed work is safe even if your computer dies.
Bad: "updates"
Bad: "fixed stuff"
Bad: "asdfasdf"
Good: "added section on git workflows"
Good: "fixed typo in chapter 3"
Good: "restructured introduction for clarity"
Rule of thumb: Someone reading just your commit message should understand what changed and why.
git status will show "modified" filesgit pushgit push --tagsgit tag -lgit push only pushes commits, not tags!Tags are like bookmarks in your project's history. They let you mark special commits that represent important moments.
What it means: "This snapshot is important - give it a memorable name"
The metaphor: Like putting a sticky note on a page in your photo album that says "Summer 2024 Trip" or "Before Renovation". Instead of remembering a cryptic commit ID, you have a meaningful name.
Why use tags:
Command: git tag "tag-name"
Example:
git tag "after-initial-claude-onboarding"
This creates a tag at your current commit (wherever HEAD is pointing).
What happens:
List all tags: git tag or git tag -l
See details about a tag: git show tag-name
Important: Tags are NOT automatically pushed when you git push!
You need to explicitly push tags:
Push all tags: git push --tags
Push one specific tag: git push origin tag-name
Once you've created a tag, you can use it anywhere you'd use a commit hash:
git checkout tag-namegit diff tag-nameGood tag names:
Avoid:
Use tags for:
Don't need tags for:
# You've just finished onboarding Claude Code
git commit -m "completed Claude Code setup and documentation"
git push
# Mark this milestone
git tag "after-initial-claude-onboarding"
# Send the tag to the cloud
git push --tags
Now you (and others) can always return to this exact moment in your project's history by referencing the tag name instead of trying to find the right commit.
Think of commits as every photo in your album, and tags as the photos you've starred or put in a "favorites" collection.
The Obsidian Git plugin does these actions for you with keyboard shortcuts:
Note: The Obsidian Git plugin does NOT automatically create or push tags.
When you hit Cmd+U, behind the scenes it's doing:
git add . (stage everything)git commit -m "backup: [timestamp]" (take snapshot)git push (send to cloud)Think of git as a three-stage process:
The flow is always: Desk → Outbox → Filing Cabinet → Backup
Or in git terms: Edit → Stage → Commit → Push