# Git Workflow
> Git Workflow skill - professional version control practices Use when this capability is needed.
- Skill: `tomevault-io/git-workflow-44` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/git-workflow-44`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/git-workflow-44/raw
- Safety review: pending (external: skill-scanner PASS, skillspector WARNING)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/git-workflow-44
---
git workflow mode: CLEAN HISTORY, CLEAR INTENT
when this skill is active, you follow disciplined git practices.
this is a comprehensive guide to professional version control.
PHASE 0: ENVIRONMENT VERIFICATION
before doing ANY git operations, verify your configuration.
verify git is installed
git --version
if git not installed:
macOS:
brew install git
linux:
sudo apt install git
sudo yum install git
windows:
winget install Git.Git
verify git identity
git config --global user.name
git config --global user.email
if not configured:
git config --global user.name "Your Name"
git config --global user.email "you@example.com"
critical: use your real email.
your identity is part of the permanent record.
verify default branch
git config --global init.defaultBranch
if not set:
git config --global init.defaultBranch main
modern standard: main, not master.
verify useful defaults
git config --global core.autocrlf
macOS/Linux:
git config --global core.autocrlf input
windows:
git config --global core.autocrlf true
enable helpful options
git config --global core.quotePath false
git config --global init.defaultBranch main
git config --global rebase.autoStash true
git config --global push.autoSetupRemote true
verify remote access
git remote -v
if no remote:
[warn] working without backup
[warn] push to remote frequently
if remote exists, verify access:
git ls-remote origin
verify current repository state
git status
git branch --show-current
git log --oneline -5
understand where you are before making changes.
PHASE 1: GIT FUNDAMENTALS
the three states
working directory -> staging area -> repository
working directory: your actual files
staging area: files prepared for commit
repository: committed history
git status
shows: which files are in which state
the basic commands
add: move file from working to staging
git add filename.py
commit: move from staging to repository
git commit -m "message"
status: see what state files are in
git status
diff: see what changed
git diff # working vs staging
git diff --staged # staging vs repository
reading git status
$ git status
On branch main
Your branch is up to date with 'origin/main'.
Changes not staged for commit:
modified: app.py
modified: utils.py
Untracked files:
new_file.py
breakdown:
- on branch main: current branch
- up to date: local matches origin
- modified: changed but not staged
- untracked: new file, not tracked
PHASE 2: BRANCHING STRATEGY
why branch
branches enable:
- parallel work
- isolation of changes
- safe experimentation
- code review before merge
branch naming conventions
feature work:
feature/add-user-authentication
feature/payment-processing
feat/shopping-cart
bug fixes:
bugfix/login-timeout
fix/memory-leak
hotfix/security-patch
chores:
refactor/user-module
chore/update-dependencies
docs/api-endpoints
test/add-user-tests
release:
release/v1.2.0
prepare-release/v1.0.0
create a branch
git checkout -b feature/add-user-auth
equivalent:
git branch feature/add-user-auth
git checkout feature/add-user-auth
list branches
git branch
git branch -a # show remote too
git branch -vv # show tracking info
switch branches
git checkout main
git switch feature/add-user-auth
note: git switch is newer, more intuitive
delete branches
local:
git branch -d feature/complete
force delete (unmerged):
git branch -D feature/experimental
remote:
git push origin --delete feature/complete
PHASE 3: THE COMMIT HABIT
what makes a good commit
[ok] small, focused change
[ok] complete (works, tests pass)
[ok] clear message explaining why
[x] large, sweeping changes
[x] broken code (WIP commits)
[x] vague messages ("update", "fix stuff")
[x] multiple unrelated changes
commit message format
subject line (50 chars or less):
- imperative mood ("add" not "added" or "adds")
- complete sentence
- no trailing period
body (optional):
- what and why
- not how
- wrapped at 72 chars
examples:
add user authentication with JWT tokens
implement login and registration endpoints with JWT-based
authentication. passwords are hashed with bcrypt.
fixes #123
refactor: extract user validation to separate module
the validation logic was duplicated across multiple controllers.
extracting to a shared module reduces duplication and makes
testing easier.
fix: prevent null pointer in user lookup
when a user id doesn't exist, the lookup was returning None
without handling, causing a null pointer error. added explicit
check and raise 404 instead.
commit often
after each logical unit:
- one function extracted
- one test written
- one bug fixed
benefits:
- easier to revert if needed
- clearer history
- smaller review chunks
anti-pattern:
[x] one giant commit at end of day
[x] "work in progress" commits that break tests
amend commits
only for most recent commit:
git commit --amend
only for trivial fixes (typos, forgot to add file)
never amend pushed commits (rewrites history)
add file to previous commit:
git add forgotten_file.py
git commit --amend --no-edit
PHASE 4: STAGING AND COMMITTING
interactive staging
stage parts of a file:
git add -p filename.py
prompts for each hunk:
- y: stage this hunk
- n: don't stage this hunk
- s: split into smaller hunks
- q: quit
useful when:
- file has multiple unrelated changes
- want atomic commits
stage by file
stage specific files:
git add app.py utils.py
stage all changes:
git add .
careful: stages everything
review first with:
git status
unstage files
git restore --staged filename.py
or:
git reset HEAD filename.py
moves from staging back to working directory
discard working changes
git restore filename.py
or:
git checkout -- filename.py
warning: destroys changes
be certain you don't need them
PHASE 5: MERGE VS REBASE
when to merge
use merge when:
- preserving complete history
- working on shared branch
- want explicit merge commit
git checkout main
git merge feature/new-auth
creates merge commit combining histories.
when to rebase
use rebase when:
- cleaning up local branch before push
- linear history preferred
- integrating upstream changes
git checkout feature/new-auth
git rebase main
reapplies your commits on top of main.
golden rules
[1] never rebase pushed commits
rebase rewrites history
others may have based work on those commits
rebase = trouble for collaborators
[2] never rebase shared branches
main, develop, release branches
only rebase your local feature branches
[3] force push with caution
only after rebase
only to your own branches
git push --force-with-lease
PHASE 6: HANDLING MERGE CONFLICTS
conflict markers
when git can't auto-merge:
<<<<<<< HEAD
current branch content
=======
incoming branch content
>>>>>>> feature-branch
you decide which to keep, or combine both.
resolution process
[1] identify conflict
git status
shows "both modified" files
[2] open file in editor
find conflict markers
understand what each side does
[3] resolve conflict
choose:
- keep HEAD (current)
- keep incoming
- combine both
- write new solution
[4] remove markers
delete <<<<<<<, =======, >>>>>>>
[5] stage resolution
git add resolved_file.py
[6] complete merge/rebase
git commit # for merge
git rebase --continue # for rebase
conflict resolution tools
use merge tool:
git mergetool
configure:
git config --global merge.tool vscode
git config --global mergetool.vscode.cmd 'code --wait $MERGED'
abort on trouble
abort merge:
git merge --abort
abort rebase:
git rebase --abort
returns to state before operation.
PHASE 7: SYNCING WITH REMOTE
fetch vs pull
fetch: get remote changes, don't merge
git fetch origin
safe, lets you review before integrating
pull: fetch and merge in one step
git pull
convenient but creates merge commit
pull with rebase:
git pull --rebase
cleaner history, reapplies your work on top
push branches
first push (set upstream):
git push -u origin feature/new-auth
subsequent pushes:
git push
with autoSetupRemote configured:
git push # sets upstream automatically
update local branch
when remote has updates:
git fetch origin
git rebase origin/main
or:
git pull --rebase
before starting work
always start from latest:
git checkout main
git pull
git checkout -b feature/new-work
prevents merge conflicts later
PHASE 8: INSPECTING HISTORY
view commits
recent commits:
git log
one line per commit:
git log --oneline
with graph:
git log --oneline --graph --all
pretty format:
git log --pretty=format:"%h %ad | %s" --date=short
view specific commit
show commit details:
git show abc123
show file at commit:
git show abc123:path/to/file.py
view changes
diff between commits:
git diff abc123 def456
diff between branches:
git diff main feature
what changed in file:
git log -p filename.py
blame: who changed what
git blame filename.py
shows each line with commit and author.
specific line range:
git blame -L 50,60 filename.py
PHASE 9: UNDOING CHANGES
undo working directory changes
discard all changes:
git restore .
discard specific file:
git restore filename.py
warning: cannot be undone
undo staged changes
unstage file:
git restore --staged filename.py
unstage all:
git restore --staged .
undo commits (not pushed)
remove last commit, keep changes:
git reset --soft HEAD~1
remove last commit, discard changes:
git reset --hard HEAD~1
go back to specific commit:
git reset --hard abc123
undo pushed commits
create reversal commit:
git revert abc123
reverts changes in new commit.
safe for shared history.
PHASE 10: STASHING
when to stash
temporarily save work when:
- need to switch branches
- want to pull latest changes
- need to test something else
stash is a stack of temporary commits
basic stash
git stash
saves working directory and index.
returns to clean state.
view stashes
git stash list
stash@{0}: On main: add user login
stash@{1}: On feature: WIP on authentication
apply stash
git stash apply
applies most recent stash, keeps it in list.
apply specific stash:
git stash apply stash@{1}
drop stash
git stash drop
or combine:
git stash pop
applies and removes most recent stash.
stash with message
git stash save "work on user auth"
helpful for identifying stashes later
stash specific files
git stash push -m "config changes" config.json
only stashes specified file
PHASE 11: TAGGING
when to tag
mark releases:
- v1.0.0
- v1.1.0
- v2.0.0
tag production deployments
tag significant milestones
create tags
annotated (recommended):
git tag -a v1.0.0 -m "Release version 1.0.0"
lightweight:
git tag v1.0.0
annotated tags have message, date, author.
view tags
list all tags:
git tag
show tag details:
git show v1.0.0
push tags
push specific tag:
git push origin v1.0.0
push all tags:
git push origin --tags
delete tags
local:
git tag -d v1.0.0
remote:
git push origin --delete v1.0.0
checkout tags
view code at tag:
git checkout v1.0.0
creates detached HEAD state.
to work, create a branch:
git checkout -b patch-1.0.1 v1.0.0
PHASE 12: GITIGNORE
what to ignore
never commit:
- dependencies/ (node_modules, venv, __pycache__)
- build artifacts (.pyc, .o, .dll)
- environment files (.env, .env.local)
- ide settings (.idea/, .vscode/)
- os files (.DS_Store, Thumbs.db)
- logs (*.log)
- temporary files (*.tmp, *.swp)
create .gitignore
cat > .gitignore << 'EOF'
# python
__pycache__/
*.py[cod]
*$py.class
.venv/
venv/
*.egg-info/
# environment
.env
.env.local
.env.*.local
# ide
.idea/
.vscode/
*.swp
*.swo
# os
.DS_Store
Thumbs.db
# logs
*.log
logs/
# testing
.coverage
htmlcov/
.pytest_cache/
# build
dist/
build/
*.egg
EOF
existing .gitignore not working
files already tracked must be removed:
git rm --cached filename
for directory:
git rm -r --cached directory/
then commit.
ignore tracked file locally
git update-index --assume-unchanged config.local.json
keeps file locally, ignores for commits.
to undo:
git update-index --no-assume-unchanged config.local.json
PHASE 13: COMMON WORKFLOWS
feature branch workflow
1. update main
git checkout main
git pull
2. create feature branch
git checkout -b feature/new-feature
3. do work
# ... make changes ...
git add .
git commit -m "implement feature"
4. update from main
git fetch origin
git rebase origin/main
5. resolve conflicts if any
6. push
git push -u origin feature/new-feature
7. create pull request
8. after merge, delete branch
git branch -d feature/new-feature
hotfix workflow
1. create hotfix from main
git checkout main
git pull
git checkout -b hotfix/critical-bug
2. fix the bug
# ... make minimal fix ...
git commit -m "fix: critical security issue"
3. push and create expedited PR
git push -u origin hotfix/critical-bug
4. merge to main immediately
git checkout main
git merge hotfix/critical-bug
git push
5. tag release
git tag -a v1.0.1 -m "Hotfix for security issue"
git push origin v1.0.1
PHASE 14: REBASING FOR CLEAN HISTORY
interactive rebase
clean up last N commits:
git rebase -i HEAD~3
or:
git rebase -i abc123
opens editor with commands:
pick abc1234 first commit
pick def5678 second commit
pick ghi9012 third commit
commands:
- pick: keep as-is
- reword: edit commit message
- edit: pause for changes
- squash: combine with previous
- fixup: combine with previous, discard message
- drop: remove commit
squash related commits
before:
pick abc1234 add user model
pick def5678 fix user model typo
pick ghi9012 add user validation
after:
pick abc1234 add user model
fixup def5678 fix user model typo
fixup ghi9012 add user validation
result: one commit with message "add user model"
reorder commits
before:
pick abc1234 add feature
pick def5678 write tests
pick ghi9012 add documentation
after:
pick def5678 write tests
pick abc1234 add feature
pick ghi9012 add documentation
helps logical ordering
PHASE 15: RECOVERING FROM MISTAKES
reflog: find lost commits
git reflog
shows all git operations, including lost commits.
find the commit you want:
git reflog | grep "commit message"
restore it:
git checkout abc123
git checkout -b recovered-branch
recover dropped stash
git fsck --no-reflog | grep "stash"
or:
git log --oneline --all --graph --stash
recover:
git stash apply abc123
undo force push
if you force pushed and regret it:
find original reflog:
git reflog origin/main
reset to before force push:
git reset --hard origin/main@{1}
force push again (carefully!):
git push --force
recover deleted branch
git reflog | grep "checkout: from"
find where you were:
git checkout abc123
recreate branch:
git checkout -b feature/lost-branch
PHASE 16: GIT RULES (STRICT MODE)
while this skill is active, these rules are MANDATORY:
[1] NEVER commit broken code
tests must pass
code must work
no "wip" commits that break the build
[2] write meaningful commit messages
subject: what changed, imperative mood
body: why, if not obvious
reference issues: fixes #123
[3] pull before push
integrate remote changes first
avoid unnecessary merge commits
git pull --rebase
[4] never force push to shared branches
main, develop, release branches
only force push your own feature branches
git push --force-with-lease
[5] use branches for all work
never commit directly to main
feature branches, bugfix branches
one branch per logical unit
[6] keep commits atomic
one logical change per commit
complete and working
easy to review and revert
[7] review before committing
git diff
git status
know what you're committing
[8] push frequently
backup your work
enable code review
don't hold changes hostage
PHASE 17: GIT SESSION CHECKLIST
before starting work:
[ ] git status is clean
[ ] on correct branch
[ ] branch name is descriptive
[ ] pulled latest from origin
while working:
[ ] commit often
[ ] commit messages are clear
[ ] tests pass before commit
[ ] pushed to remote periodically
before creating PR:
[ ] branch is up to date with main
[ ] rebase if needed
[ ] no conflicts
[ ] tests pass
[ ] code is clean
after merge:
[ ] delete local branch
[ ] delete remote branch
[ ] pull latest main
[ ] ready for next feature
FINAL REMINDERS
git is your safety net
commit frequently
push often
small changes are easy to fix
big changes are scary
the golden rule
if you're unsure what will happen:
git status
git diff
git log --oneline -5
know your state before acting
when in doubt
branch is cheap
create one and experiment
you can always delete it
your work is safe on main
the goal
clean history
clear intent
easy to understand
easy to collaborate
now go commit something great.
---
> Source: [kollaborai/kollab](https://github.com/kollaborai/kollab) — distributed by [TomeVault](https://tomevault.io).