A step-by-step guide for developers new to version control.

Table of Contents

  1. Setup
  2. Authentication
  3. Creating & Deleting Repositories
  4. Branches
  5. Merging & Conflicts
  6. Staging, Committing & History
  7. Push & Pull
  8. Undo & Redo
  9. Other Basic Tips
  10. Complete Example Workflow
  11. Cheat Sheet

1. Setup

Installing Git

  1. Linux (Debian/Ubuntu):
1

sudo apt install git
  1. macOS — Git ships with Xcode tools. Run git --version and macOS will prompt an install if needed. Or use Homebrew:
1

brew install git
  1. Windows — Download from git-scm.com. Includes Git Bash terminal.

Configure Your Identity

Git tags every commit with your name and email. Set them once:

1
2
3

git config --global user.name  "Your Name"
git config --global user.email "[email protected]"
git config --list   # verify settings

2. Authentication

  1. Generate a key pair:
1

ssh-keygen -t ed25519 -C "[email protected]"
  1. Copy the public key and paste it into GitHub/GitLab under Settings → SSH Keys:
1
2
3
4
5

# macOS
cat ~/.ssh/id_ed25519.pub | pbcopy

# Linux
cat ~/.ssh/id_ed25519.pub
  1. Test the connection:
  1. Remove a key locally:
1

rm ~/.ssh/id_ed25519 ~/.ssh/id_ed25519.pub

HTTPS with Credential Helper

1
2

git config --global credential.helper store   # saves to disk
# macOS uses the keychain automatically

To clear stored credentials (logout):

1
2
3
4
5
6

git credential reject
# then type: protocol=https
#             host=github.com
# and press Ctrl+D

# macOS: open Keychain Access and delete the github.com entry

3. Creating & Deleting Repositories

Start Fresh vs. Clone

1
2

git init my-project       # create a new local repo
git clone <url>           # copy an existing remote repo

1
2

git remote add origin [email protected]:you/repo.git
git remote -v             # confirm

Deleting Repositories

Local: Simply delete the folder:

1

rm -rf my-project/

Remote: Use the hosting platform’s UI (Settings → Danger Zone → Delete), or the GitHub CLI:

1

gh repo delete you/repo --yes

To delete a remote branch only:

1

git push origin --delete branch-name

4. Branches

1
2
3
4
5
6
7

git branch                     # list local branches
git branch feature/login       # create new branch
git switch feature/login       # switch to it (modern)
git checkout -b feature/login  # create + switch (classic)
git branch -m old-name new-name  # rename
git branch -d feature/login    # delete (safe — merged only)
git branch -D feature/login    # force delete

Feature branch workflow: Always branch off main, do your work, then merge back. Keeps main stable.

5. Merging & Conflicts

git merge vs. git rebase

1
2
3
4
5
6
7

# Merge: preserves history, creates a merge commit
git switch main
git merge feature/login

# Rebase: replays your commits on top of main (linear history)
git switch feature/login
git rebase main

Tip for beginners: Use merge. Rebase is powerful but rewrites history — learn it after you’re comfortable with merge.

Resolving Conflicts

When Git can’t auto-merge, it marks the file:

<<<<<<< HEAD
your change
=======
incoming change
>>>>>>> feature/login

Edit the file to keep what you want, then:

1
2
3
4
5

git add conflicted-file.txt
git commit                    # completes the merge

# Changed your mind? Abort:
git merge --abort

6. Staging, Committing & History

The basic flow:

edit files  →  git add  →  git commit  →  history

1
2
3
4
5
6
7
8

git status                     # see what changed
git add file.txt               # stage one file
git add .                      # stage everything
git commit -m "add login form" # commit with message
git commit --amend             # fix the last commit (before push)

git log                        # full history
git log --oneline --graph      # compact view

Good commit message formula: verb + what + why Example: fix: prevent login crash when email is empty

7. Push & Pull

1
2
3
4
5
6

git push origin main                 # send commits to remote
git push -u origin feature/login     # push + track new branch

git pull                             # fetch + merge in one step
git fetch                            # download only (no merge)
git merge origin/main                # then merge manually

⚠️ Force push warning: git push --force overwrites remote history and can delete teammates’ work. Use git push --force-with-lease instead — it fails safely if anyone else has pushed since your last fetch.

8. Undo & Redo

Discard Local File Changes

1
2

git restore file.txt            # modern (Git 2.23+)
git checkout -- file.txt        # classic equivalent

Unstage a File

1
2

git restore --staged file.txt   # modern
git reset HEAD file.txt         # classic

Undo Commits Safely (Public History)

1

git revert <commit-hash>        # creates a new "undo" commit

Reset (Rewrite Local History)

1
2
3

git reset --soft  HEAD~1        # undo commit, keep staged
git reset --mixed HEAD~1        # undo commit + unstage (default)
git reset --hard  HEAD~1        # undo commit + discard changes

⚠️ Never use --hard reset on commits already pushed to a shared branch. It deletes work for everyone.

Recover Lost Commits with Reflog

1
2

git reflog                      # shows every HEAD move
git checkout <hash>             # jump back to a lost state

9. Other Basic Tips

.gitignore

Create a .gitignore file in your repo root to exclude files:

# .gitignore
node_modules/
.env
*.log
dist/

Useful Everyday Commands

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

git diff                        # unstaged changes
git diff --staged               # staged vs last commit

git stash                       # save dirty work temporarily
git stash pop                   # restore stashed changes

git tag v1.0.0                  # mark a release
git push origin v1.0.0          # push tag to remote

git remote -v                   # show remote URLs

Simple branching strategy for beginners: Keep main always deployable. For every feature or fix, create a branch like feature/thing or fix/bug, do your work, then merge it back into main via a pull request.

10. Complete Example Workflow

A full flow from scratch: init → commit → branch → merge → push.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

# 1. Create & enter project
mkdir hello-git && cd hello-git
git init

# 2. First commit on main
echo "# Hello Git" > README.md
git add README.md
git commit -m "init: add README"

# 3. Create a feature branch
git switch -c feature/greeting

# 4. Make a change and commit
echo "Hello, world!" > greeting.txt
git add greeting.txt
git commit -m "feat: add greeting file"

# 5. Merge back to main
git switch main
git merge feature/greeting

# 6. Link to GitHub and push
git remote add origin [email protected]:you/hello-git.git
git push -u origin main

# 7. Clean up the feature branch
git branch -d feature/greeting

Cheat Sheet

The most common Git commands you’ll use every day:

Command What it does
git init Create a new local repo
git clone <url> Copy a remote repo
git status See what changed
git add . Stage all changes
git commit -m "msg" Save a snapshot
git push Upload commits to remote
git pull Download + merge from remote
git switch -c branch Create and switch to a new branch
git merge <branch> Merge a branch into current
git log --oneline Compact commit history
git stash Shelve dirty work temporarily
git restore file Discard local changes to a file
git revert <hash> Safely undo a commit
git reflog Find lost commits
git diff --staged Review staged changes before commit
git remote -v Show remote URLs

Git takes practice — the best way to learn is to use it on real projects. Start with the example workflow above, repeat it a few times, and the commands will become second nature.