The Version Control "Field Manual"

Objective: Create a comprehensive "Field Manual" that explains not just the
what (commands), but the how and why (workflows and strategies) of using

Git. This document should be written clearly enough to serve as a learning

resource for you in your projects.

Module 1: The Command Dictionary

Goal: Build a quick-reference guide for essential Git commands.

Instructions: Research the following commands. Create a table with the

columns listed below. Do not just copy-paste official documentation; rewrite

the "Explanation" in your own words.

Required Table Columns:

1. Command Name

2. Basic Syntax (e.g., git commit -m "message")

3. Plain English Explanation (What does it actually do?)

4. When to Use It (In what situation do you run this?)

5. Risk Level (Safe vs. Destructive/Can lose data)

Commands to Document:

● Setup: git config, git init, git clone

● Staging & Saving: git status, git add, git commit, git diff

● Branching: git branch, git checkout, git switch, git merge

 ● Syncing: git fetch, git pull, git push

● History: git log, git show, git blame

● Undo/Fix: git stash, git reset, git revert

Sol.

Setup

Command Basic Syntax Explanation When to Use Risk Level

Name

git config git config Configures Initially setting Safe

--global Git's global or up Git on a
local machine, or
[Link]
preferences, when you need
"Your Name"
such as your to update
or git identity (name default settings
config -- and email), (e.g., name,
global preferred email, or
[Link] editor, etc. The default branch
"you@exampl --global flag name).
[Link]" applies the
settings to all
repositories.

git init git init Initializes a To start Safe (but can

new, empty Git tracking an be confusing if
repository in existing project
you run it
the current folder that is
directory by not yet under inside an
adding a .git version control. already-tracked
subdirectory. repo or nested
directories)
git clone git clone Creates a local When you Safe
<URL> copy of a need to retrieve
remote the code and
[target-
repository, full history from
dir]
including its a remote
entire history. source (like
GitHub, GitLab)

Staging & Saving

Comm Basic Plain English When to Use It Risk Level

and Syntax Explanation
Name

git git Shows what’s Frequently, to Safe

status status changed, understand
what’s what’s pending
staged, and before
which branch committing or
you’re on. switching
branches.

git add git add Puts changes Before Safe (but

/ git into the committing; to be mindful:
add . “staging select exactly git add .
area” so the which changes can stage
next commit go into a unintended
includes commit. files)
them.

git git Saves staged After staging Safe

 commi commi changes into changes that
t t -m history with a logically belong
"messa message. together.
ge" / Without -m,
git opens editor
commi for a detailed
t message.

git diff git Shows line- To review Safe

diff / by-line changes before
git diff differences. staging/committ
-- Default ing, or to
staged compares compare
/ git working copy branches/comm
diff vs. index; -- its.
staged
compares
index vs. last
commit;
comparing
refs shows
differences
across
history.

Branching

Comman Basic Plain English When to Use It Risk Level

d Name Syntax Explanation

git git Lists branches; Creating topic Safe (deleting

branch branch / creates or branches for with -d is safe
git deletes a features/bugfixes; if merged; use
branch / branch pointer. cleaning up old -D cautiously
git It doesn’t branches. —Destructive)
branch - switch you; it
d just manages
branches.

git git Switches Switching Mixed

checkout checkout branches or branches; creating (switching is
/ git restores files. -b a branch quickly; Safe; restoring
checkout creates and discarding local files with -- is
-b / git switches to a changes to Destructive to
checkout new branch. -- specific files. uncommitted
-- <file> changes)
discards
changes to a
file by restoring
from HEAD.

git git switch A newer, Prefer this over Safe

switch / git simpler way to checkout for
switch -c change branch switching
branches (it’s clearer/safer).
without the file-
restore
behavior of
checkout. -c
creates and
switches to a
new branch.
git git Combines the When integrating Safe (can
merge merge specified completed work cause
branch into from another conflicts you
your current branch (feature → must resolve;
branch. main or updating history
Creates a your feature from changes are
merge commit main). additive)
if needed; fast-
forwards if
possible.

Syncing (Remote Collaboration)

Comman Basic Plain English When to Use It Risk Level

d Name Syntax Explanation

git fetch git fetch Downloads new To see what’s Safe

[remote] commits/refs new on the
[branch] from the remote, remote without
but doesn’t changing local
change your files; before
working branch. reviewing
incoming work.

git pull git pull / Fetches, then To update your Mixed (can
git pull -- integrates branch with the cause merge
rebase changes into latest remote conflicts; --
your current changes. Use -- rebase
branch (merge rebase to keep a rewrites your
 by default, or clean, linear local commits
rebase with -- history (team —be cautious)
rebase). policy-
dependent).

git push git push Uploads your When sharing Mixed

[remote] local commits to your work or (pushing is
[branch] the remote. -u publishing a Safe; force-
/ git push sets upstream branch. pushing -f/--
-u origin tracking for force is
future Destructive to
pulls/pushes. shared
history)

History

Comman Basic Plain English When to Use Risk Level

d Name Syntax Explanation It

git log git log / Shows commit To explore Safe

git log -- history. Options history,
oneline -- help visualize understand
graph -- branches and branch
decorate simplify output. topology, or
--all find specific
changes.

git show git show / Displays details Inspecting a Safe

 git show : of a commit specific
(message, diff). commit or
With viewing a file
<commit>:<path as it was at a
>, shows a file’s point in time.
content at that
commit.

git blame git blame Shows line-by- To find Safe (use

line authorship who/when a thoughtfully;
and the commit line changed pair with git
that last for log -L and
changed each debugging, discussions
line. ownership, or rather than
context. finger-pointing)

Undo / Fix

Comman Basic Plain English When to Use It Risk Level

d Name Syntax Explanation

git stash git stash Temporarily Pausing work Safe (but

/ git shelves your quickly—e.g., to stashes can
stash - uncommitted fix something be lost if not
 u / git changes so you elsewhere— applied; -u
stash list can switch without stashes more
/ git branches or pull committing. content—
stash cleanly. -u includes know what
apply / untracked files. you’re
git stash apply replays shelving)
pop without removal;
pop replays and
removes from
stash.

git reset git reset Moves the current Rewriting local Destructive
--soft / branch pointer to a history or (especially --
git reset different commit. undoing hard; also
-- --soft keeps commits. Use risky if applied
mixed / changes staged; --soft to to pushed
git reset --mixed (default) rework a commits)
--hard keeps changes in commit; --hard
working area; -- to throw away
hard discards changes. Never
changes. hard-reset
shared history.

git revert git revert Creates a new Safely undo a Safe (may
commit that bad commit in require
undoes the a shared conflict
changes of the branch (no resolution if
specified commit, rewrite). the original
preserving history. commit
touched
many areas)
Quick Usage Patterns (Workflow Tips)

● Daily Flow:
git status → git add (selective) → git commit -m "Clear message"
→ git pull --rebase (if team prefers) → resolve conflicts if any → git
push.
● Feature Branching:
git switch -c feature/xyz → work & commit → git push -u origin
feature/xyz → open PR → after review, git merge via platform → delete
local branch: git branch -d feature/xyz.
● Safe Undo:
Use git revert on shared branches; use git reset on your local,
unpushed commits only.
● Review Before Commit:
git diff (unstaged) and git diff --staged (what you’re about to
commit).
● Stay in Sync:
git fetch regularly; git pull when ready to integrate.

Risk Legend

● Safe: Read-only or additive; won’t destroy local work.

● Mixed: Can be safe, but context matters (rebase, merge conflicts,
overwriting).
● Destructive: Can permanently discard changes or rewrite history; use
with caution.

Module 2: Visualizing the Workflow

Goal: Demonstrate understanding of the data flow between

different Git areas.

Instructions: Version control moves files between four specific "zones."
Create a visual diagram (or a detailed text-based flow) illustrating how code

moves through these zones.

Key Concepts to Cover:

1. Working Directory (Where you edit files)

2. Staging Area / Index (Where you prepare files)

3. Local Repository (Your private history)

4. Remote Repository (The shared team history)

Deliverable:

● A diagram or step-by-step description showing which commands

move code from one zone to another (e.g., Which command moves

code from Working Directory -> Staging Area?).

Sol.
Flow Explanation: How Code Moves Through Git Zones

1. Working Directory → Staging Area

○ Command: git add <file>

○ Action: Takes modified files from your working directory and

places them in the staging area (index). This means you’re

preparing them for the next commit.

2. Staging Area → Local Repository

○ Command: git commit -m "message"

○ Action: Creates a snapshot of the staged changes and saves it in

your local repository as a commit. This is your private history.

3. Local Repository → Remote Repository

 ○ Command: git push origin <branch>

○ Action: Sends your local commits to the remote repository so

others can access them. This updates the shared team history.

4. Remote Repository → Local Repository

○ Command: git fetch or git pull

○ Action: Brings changes from the remote repository into your local

repository. git fetch only downloads, while git pull downloads

and merges (or rebases).

Reverse Flows (Undo or Move Backwards)

● Local Repository → Staging Area: git reset --soft <commit> (moves

HEAD back but keeps changes staged).

● Staging Area → Working Directory: git reset <file> (unstages a file).

● Working Directory (discard changes): git checkout -- <file> or git

restore <file> (reverts file to last committed state).

Module 3: The "Scenario Doctor" (Troubleshooting) Goal: Apply

your research to solve common problems without running code.

Instructions:

Imagine a colleague comes to you with the following issues. Research the

situation and write down the solution steps and the commands needed to fix

it.
Scenarios:

1. The "Premature" Switch: "I'm working on a bug fix, but I need to switch

branches to review someone else's code. I'm not ready to commit my

work yet. How do I save my work temporarily without committing?"

2. The Wrong Message: "I just committed my code, but I realized I made a

typo in the commit message. How do I fix the message without

creating a new commit?"

3. The Oops Delete: "I accidentally deleted a critical file ([Link]) from my

folder, but I haven't committed the deletion yet. How do I get the file

back?"

4. The Detached Head: "I checked out a specific commit ID to look at old

code, and now Git says I am in a 'detached HEAD' state. How do I get

back to my normal development state?"

Sol.

1) The “Premature” Switch

Problem: You’re in the middle of a bug fix but need to switch branches to

review someone else’s work. You’re not ready to commit.

Solution: Use a stash to shelve uncommitted changes, switch, then restore

them later.

Steps:

1. Stash your current changes (include untracked files if needed).

 2. Switch to the other branch and review.

3. Return to your original branch and reapply the stash.

Commands:

# Save changes (tracked files)

git stash

# OR include untracked files as well

git stash -u # or: git stash --include-untracked

# Switch to the branch you want to review

git switch other-branch

# ...review work...

# Return to your bugfix branch

git switch bugfix-branch

# Reapply the stashed changes and remove the stash entry

git stash pop

# (If you prefer to keep the stash entry, use 'git stash apply' instead of 'pop')


2) The Wrong Message

Problem: You committed, but your commit message has a typo.

Solution: Amend the last commit message.

⚠️If the commit has already been pushed, coordinate with your

team before amending and force-pushing.

Commands:
# Open editor to edit the last commit message
git commit --amend

# Or provide the corrected message directly

git commit --amend -m "Correct, clear subject line"


3) The Oops Delete

Problem: You accidentally deleted [Link] locally but haven’t committed

that deletion.

Solution: Restore the file from the last committed version (HEAD).

Commands:

# If the file existed in the last commit:

git restore [Link]

# Older Git (or alternate syntax):

git checkout -- [Link]

4) The Detached HEAD

Problem: You checked out a specific commit (not a branch) and now Git says

you’re in detached HEAD.

Solution: Switch back to a branch (e.g., main) or create a new branch from the

current commit if you need to keep changes.

Commands:
# Return to normal (attach HEAD to a branch)
git switch main

#If you want to keep work you did while detached:

Module 4: Best Practices & Etiquette

Goal: Understand the "Social" side of Version Control.

Instructions: Research and compile a list of "The 5 Commandments of

Git." These should be rules that ensure the team works together smoothly.

Topics to Research:

● Commit Messages: What is the structure of a professional commit

message? (Subject vs. Body).

● Commit Frequency: Should you commit once a week or multiple times a

day? Why?

● Branch Naming: What are common conventions for naming branches?

(e.g., feature/, bugfix/).

● The ".gitignore" File: What is this file and what kind of files should always

go in here?

Submission Guidelines

● Format: Pdf

● Use clear headings, code blocks for commands, and bold text for

emphasis.
Sol.

1) Write Professional Commit Messages

● Subject line: 50 characters max; imperative mood; summarize what

and why.

● Blank line after subject.

● Body (optional): Explain why and context, reference issues/PRs, note

risks or follow-ups.

Example:

Fix login redirect when token expires

Explain that the redirect now goes to /auth/renew and

preserves the return URL.

2) Commit in Small, Logical Chunks

● Prefer multiple small commits per day over one giant weekly commit.

● Each commit should compile/test and represent a single logical

change.

● Benefits: clearer history, easier reviews, simpler rollbacks, fewer conflicts.

3) Use Clear Branch Naming

● Prefix by purpose/type:

○ feature/<short-name> — new functionality

 ○ bugfix/<ticket-id-or-short-name> — non-critical fixes

○ hotfix/<issue> — urgent fix on production

○ chore/<task> — maintenance, tooling, deps

● Use kebab-case or slashes; keep names short and descriptive.

● Example: feature/payment-retry, bugfix/1234-null-pointer,

hotfix/ssl-expiry.

4) Maintain a Proper .gitignore

● Keep noisy and sensitive files out of version control:

○ Build artifacts: dist/, build/, out/

○ Dependencies: node_modules/, .venv/, vendor/

○ Logs & temp: *.log, *.tmp, coverage/

○ Secrets & local config: .env, *.key, *.pem, *.sqlite

● Start from language/framework templates and tailor to your project.

Example:

# Dependencies & builds

node_modules/
dist/
build/

# Logs & coverage

*.log
coverage/

# Env & secrets

.env
*.pem


5) Collaborate Responsibly

● Pull (or fetch) before push to avoid overwriting teammates’ work.

● Prefer git pull --rebase on feature branches if your team uses a

linear history.

● Avoid --force on shared branches; if necessary, communicate and

coordinate.

● Use PRs, code reviews, and descriptive messages; link issues; keep

discussions friendly and constructive.