Git & GitHub: From Zero to Advanced

What is version control?

Version control records every change made to a set of files, so you can go back to any earlier state, see who changed what, and work with other people without overwriting their work.

1.1 The problem it solves

Everyone has seen a folder like this:

report.docx
report_final.docx
report_final_v2.docx
report_final_v2_REALLY_FINAL.docx
report_final_v2_REALLY_FINAL_ravi_edits.docx

Nobody knows which file is the latest, what changed between them, or who changed it. Now imagine 500 source files and 10 developers. Three things go wrong:

• Lost work. Someone overwrites a file and the earlier version is gone for good.
• No history. A bug appears and nobody can tell which change caused it.
• Collision. Two people edit the same file and one person's changes silently disappear.

A version control system (VCS) fixes all three. It keeps every version, labels each change with its author, date and reason, and helps merge work from many people.

1.2 Analogy: a time machine for your project

Think of a video game with save points. Before a hard level you save. If you fail, you reload and try again. Each commit in Git is a save point with a name and a note, and you can return to any save point whenever you like.

It is also like Google Docs version history, with more control: you decide when a save point is made, you write a note for it, and it works for any type of file.

1.3 Three generations of version control

When you clone a Git repository you get the complete history, not just the latest files. That is why most Git commands work without internet.

1.4 Key terms you will see everywhere

1.5 Why teams cannot work without it

• Collaboration: ten people can work on one codebase at the same time.
• Traceability: every line can be traced to a person, a date and a reason.
• Safety: a mistake is never permanent, because you can return to an earlier commit.
• Experimentation: try a risky idea on a branch and throw it away if it fails.
• Release management: mark exactly which version went to production.

1.6 Common mistakes

• Thinking version control is only for code. It works for documents, configuration and notebooks too. Very large binary files need extra tools (Git LFS, in Part 5).
• Waiting too long to start. Track the project from day one, not after a problem appears.

A short history of Git

Git was created in April 2005 by Linus Torvalds, the creator of Linux, because the Linux kernel project suddenly lost the version control tool it depended on.

2.1 Before Git: the BitKeeper story

The Linux kernel is one of the largest collaborative software projects in the world. Until 2002 its changes were passed around as patches and archives, which did not scale. From 2002 the kernel team used a proprietary distributed tool called BitKeeper, offered to the project free of charge.

In April 2005 the relationship broke down. The company behind BitKeeper withdrew the free licence after a dispute about reverse-engineering its protocol. The kernel developers now had thousands of contributors and no tool.

2.2 A tool built in days

Torvalds found no existing tool that met his goals, so he wrote a new one. His requirements:

• Speed: applying a patch should take seconds, even for a huge project.
• Simple design: a small, understandable core.
• Parallel work: thousands of branches that merge easily.
• Fully distributed: no single central server required.
• Integrity: impossible to change history without anyone noticing.

A first version worked within days, and the kernel began using Git for its own development within about two weeks. The name "git" is British slang for an unpleasant person; Torvalds has joked that he names his projects after himself. Junio Hamano has maintained Git since July 2005, and Git 1.0 was released in December 2005.

2.3 Timeline of milestones

2.4 Why Git won

• It is fast, because most operations happen on your own machine.
• Branching is cheap, so teams create branches freely.
• It stores snapshots and checks content with hashes, so history is trustworthy.
• It is free and open source.
• Websites like GitHub made sharing and reviewing code easy for everyone.

2.5 Common mistakes

• Confusing Git with GitHub. They are different things; Chapter 3 explains how.
• Assuming Git is only for Linux. It runs on Windows, macOS and Linux.

Git vs GitHub vs GitLab vs Bitbucket

Git is the tool that tracks your changes on your computer. GitHub, GitLab and Bitbucket are websites that host Git repositories online so teams can share and review them.

3.1 Analogy: the engine and the garage

Git is a car engine: it does the real work and runs on your own machine. GitHub is a big garage and showroom. It stores your car (the repository), lets other people see it, lets mechanics suggest improvements, and offers extra services such as testing. You can run the engine without the garage, but the garage is useless without the engine. Likewise, email is a technology and Gmail is a service built on it.

3.2 What Git does and what GitHub adds

3.3 The main hosting platforms

All three use Git underneath, so the commands you learn work on each of them. This handbook uses GitHub for online examples because it is the most widely used and has a generous free plan.

3.4 Common mistakes

• Saying "I pushed to Git". You push to a remote such as GitHub. Git is the tool, GitHub is the place.
• Treating GitHub as a guaranteed backup. It is hosting. Keep important repositories cloned in more than one place.

Installing Git

Installing Git takes about five minutes on any operating system, and you can confirm it worked by running git --version.

4.1 Pick your operating system

$ winget install --id Git.Git -e --source winget

$ git --version

$ brew install git

# Debian, Ubuntu
$ sudo apt update
$ sudo apt install git

# Fedora
$ sudo dnf install git

# Arch
$ sudo pacman -S git

4.2 Verify the installation

Open a new terminal window and run:

$ git --version
git version 2.45.0

Your version number will probably differ, and that is fine. Any reasonably recent version works with this handbook.

4.3 Common mistakes

• Terminal opened before installing. It does not see new programs until you close it and open a new one.
• "git is not recognized" on Windows. The PATH option was skipped. Run the installer again and choose the recommended PATH option.
• Opening Git CMD because the Start issue appeared. The issue page is waiting for a bot comment. Use Codespaces from that comment. You do not need Git CMD for the course.

First-time configuration

Before your first commit you must tell Git who you are, because every commit records its author's name and email.

5.1 The three configuration levels

Git reads settings from three places. A more specific level overrides a more general one.

5.2 Build your setup commands

Fill in your details and the commands below update as you type. Nothing is sent anywhere; this runs in your browser. Copy the result into your terminal.

• Default branch. Older Git versions named the first branch master. GitHub and most teams now use main; the command above makes every new repository start on it.
• Line endings. Windows ends lines with two hidden characters, macOS and Linux use one. The core.autocrlf setting stops this from creating noisy differences in mixed teams.

5.3 Check your settings

$ git config --list
user.name=Your Name
user.email=you@example.com
init.defaultbranch=main
core.editor=code --wait

# read a single value
$ git config user.name
Your Name

Settings live in a plain text file called .gitconfig in your home folder. You can open it in an editor and change values by hand.

5.4 Time-saving aliases

An alias is a short name for a longer command. Add these later, once you are comfortable.

$ git config --global alias.st status
$ git config --global alias.co checkout
$ git config --global alias.br branch
$ git config --global alias.lg "log --oneline --graph --all"

After this, git st does the same as git status.

5.5 Common mistakes

• Skipping the identity step. Git may refuse to commit, or guess a wrong name and email from your computer.
• Forgetting quotes around a name with a space, such as "Your Name".

Your first repository

Creating a repository turns an ordinary folder into a project that Git can track.

6.1 Creating a repository with git init

A repository is a folder that Git is watching. Any folder can become one with a single command.

$ mkdir hello-git
$ cd hello-git
$ git init
Initialized empty Git repository in /home/you/hello-git/.git/

That is all. Git created a hidden folder called .git inside your project. Everything Git knows about your project lives in that folder: the history, the settings and the branches. Your own files stay where they are.

6.2 What is inside the .git folder

You do not need to edit these files, but it helps to know what they are.

$ ls -a
.  ..  .git
$ ls .git
HEAD  config  description  hooks  info  objects  refs

6.3 Checking the state with git status

git status is the command you will type most often. It tells you which branch you are on and what has changed.

$ git status
On branch main

No commits yet

nothing to commit (create/copy files and use "git add" to track)

Now create a file and ask again.

$ echo "# Hello Git" > README.md
$ git status
On branch main

No commits yet

Untracked files:
  (use "git add <file>..." to include in what will be committed)
	README.md

nothing added to commit but untracked files present (use "git add" to track)

Untracked means Git can see the file but is not recording it yet. You will fix that in the next chapter.

6.4 Cloning an existing repository

Often you start from a project that already exists online. git clone downloads the whole repository, history included.

$ git clone https://github.com/git/git-scm.com.git
Cloning into 'git-scm.com'...
$ cd git-scm.com

Clone creates a new folder named after the repository. Cloning from GitHub is covered fully in Part 4.

6.5 Common mistakes

• Running git init inside another repository. You then have a repository inside a repository, which confuses Git. Check with git status first; if it says "not a git repository" you are safe to initialise.
• Initialising your home folder. Always create a project folder first. Running git init in ~ makes Git try to track everything you own.
• Running Git commands outside a repository. The error fatal: not a git repository simply means you are in the wrong folder.
• Making a folder on your computer for the course. A folder is not a GitHub repository. For stage 1, use the template link in the Start comment, then Codespaces.
• Opening the yellow Compare & pull request banners on git-lab. greeting-a and greeting-b come with the template. Ignore them in every stage, and do not merge them. Stage 3 makes its own greeting branches in Codespaces. Yellow banners

The three areas of Git

Git moves your work through three areas, and understanding them explains almost every Git command.

7.1 The idea: a photo studio

Imagine a photo studio. The working directory is the stage where you arrange people and props. The staging area is the shelf where you place exactly the items you want in the next photo. The repository is the album where finished photos are stored forever. You can rearrange the stage as much as you like. Only what you place on the shelf gets photographed, and once a photo is in the album it stays there.

7.2 Why a staging area exists

Many beginners ask why Git does not just save everything you changed. The staging area lets you build clean commits. If you fixed a bug and also reformatted another file, you can stage and commit them separately. Each commit then tells one story, which makes history easy to read and easy to undo.

7.3 Adding files with git add

$ git add README.md
$ git status
On branch main

No commits yet

Changes to be committed:
  (use "git rm --cached <file>..." to unstage)
	new file:   README.md

The file is now staged. Useful variations:

7.4 A file can be in two states at once

Edit a file after staging it and Git remembers both versions: the one you staged, and the newer one in your working directory.

$ echo "More text" >> README.md
$ git status
Changes to be committed:
	new file:   README.md

Changes not staged for commit:
	modified:   README.md

Only the staged version goes into the next commit. Run git add README.md again to include the newer edit.

7.5 Staging part of a file

git add -p shows each changed chunk (called a hunk) and asks what to do.

$ git add -p
@@ -1,2 +1,3 @@
 # Hello Git
+More text
Stage this hunk [y,n,q,a,d,s,e,?]? y

7.6 Common mistakes

• Using git add . blindly. It can stage secrets, build files or large data. Always run git status before committing.
• Forgetting to stage again after editing. The commit contains the staged version, not your latest edit.
• Thinking git add saves your work. Staging is only a preparation step. Nothing is saved to history until you commit.

Making commits

A commit is a permanent snapshot of your staged changes together with a message explaining why you made them.

8.1 Your first commit

$ git commit -m "Add README"
[main (root-commit) 3f2a9c1] Add README
 1 file changed, 1 insertion(+)
 create mode 100644 README.md

Let us read this output. main is the branch, 3f2a9c1 is the start of the commit's unique ID (its hash), and the last lines say what changed.

8.2 What a commit contains

Every commit points to its parent, the commit before it. These links form the history chain that you saw in Chapter 1.

8.3 Commit command variations

8.4 Writing good commit messages

A good message explains why, not just what, and makes sense to a stranger a year from now.

Fix crash when the username is empty

The login form passed an empty string to validate(), which
raised an exception. Return a friendly error instead.

• Write a short first line of about 50 characters, in the imperative mood: "Add", "Fix", "Remove".
• Leave a blank line, then add details only if they help.
• Describe one logical change per commit.

8.5 Fixing the last commit with --amend

You committed, then noticed a typo or a forgotten file. Amend rewrites the last commit.

$ git add forgotten.txt
$ git commit --amend -m "Add README and licence"

8.6 Common mistakes

• Committing with no message or a vague one. Future you will not remember what "stuff" meant.
• Huge commits that mix unrelated changes. Use git add -p to split them.
• Committing secrets such as passwords or API keys. Removing them later is painful. Part 5 covers prevention.
• Skipping the Start command block. The portal counts only commits after Start that are pushed to GitHub. Paste every line, then git push.

Viewing history

Git remembers everything, and a handful of commands let you read that memory in many different ways.

9.1 git log: the history list

$ git log
commit 9a1c4e7d2b8f0c3a5e6d7f8a9b0c1d2e3f4a5b6c (HEAD -> main)
Author: Your Name <you@example.com>
Date:   Mon Oct 5 10:12:03 2026 +0530

    Fix typo in README

commit 3f2a9c1e5b7d4a8c9d21f6e5a4b3c2d1e0f9a8b7
Author: Your Name <you@example.com>
Date:   Mon Oct 5 09:40:11 2026 +0530

    Add README

Newest commits come first. Press q to leave the scrolling view.

9.2 Making log readable

$ git log --oneline
9a1c4e7 Fix typo in README
3f2a9c1 Add README

9.3 git show: look inside one commit

$ git show 3f2a9c1
commit 3f2a9c1e5b7d4a8c9d21f6e5a4b3c2d1e0f9a8b7
Author: Your Name <you@example.com>

    Add README

diff --git a/README.md b/README.md
new file mode 100644
+# Hello Git

You only need the first 7 or so characters of the hash, as long as they are unique.

9.4 git diff: compare changes

Diff shows what changed. Which two things it compares depends on the options.

diff --git a/README.md b/README.md
@@ -1 +1,2 @@
 # Hello Git
+More text

Lines beginning with + were added, lines beginning with - were removed, and @@ marks the position in the file.

9.5 git blame: who changed this line

$ git blame README.md
3f2a9c1e (Your Name 2026-10-05 1) # Hello Git
9a1c4e7d (Priya Shah 2026-10-05 2) More text

Blame shows, for every line, the commit and author that last changed it. Use it to ask "why is this here?", not to assign fault.

9.6 Other handy commands

• git shortlog -sn counts commits per author.
• git show HEAD~2 shows the commit two steps before the latest.
• git log -p shows the full patch for each commit.

9.7 Common mistakes

• Being stuck in the pager. Press q to exit a long log.
• Expecting git diff to show staged changes. Add --staged for those.
• Pasting a full 40-character hash. The short form works.

Ignoring files

A .gitignore file tells Git which files to leave alone, such as secrets, build output and temporary files.

10.1 Why some files must not be tracked

Some files should never enter your history:

• Passwords, API keys and .env files.
• Dependencies such as node_modules/ or venv/, which can be downloaded again.
• Build output, logs and cache files.
• Editor or operating system files such as .DS_Store or .vscode/.

Ignoring them keeps the repository small, clean and safe.

10.2 Creating a .gitignore

Create a plain text file named .gitignore in the project root. Each line is a pattern.

# Python
__pycache__/
*.pyc
venv/

# Secrets
.env

# Logs
*.log

# Operating system
.DS_Store

$ git add .gitignore
$ git commit -m "Add .gitignore"

Commit the .gitignore itself so everyone on the team shares the same rules.

10.3 Pattern rules

10.4 When a file is already tracked

.gitignore only affects files Git is not yet tracking. If you committed .env before ignoring it, Git keeps tracking it. Tell Git to stop, but keep the file on disk:

$ git rm --cached .env
rm '.env'
$ git commit -m "Stop tracking .env"

10.5 Checking why a file is ignored

$ git check-ignore -v debug.log
.gitignore:3:*.log	debug.log
$ git status --ignored

10.6 A global ignore file

Rules for your own computer, such as editor files, belong in a global file so you do not repeat them in every project.

$ git config --global core.excludesfile ~/.gitignore_global

10.7 Ready-made templates

GitHub maintains a collection of .gitignore templates for most languages and frameworks. Start from the one that matches your stack, then adjust it. GitHub also offers to add one when you create a new repository.

10.8 Common mistakes

• Ignoring after committing. Remember git rm --cached.
• Ignoring a folder, then expecting an exception inside it to work. Ignore files, or use folder/* style patterns.
• Ignoring everything with *. This hides real work. Be specific.

Undoing changes

Git offers a safe way back at every stage, and choosing the right undo command depends on where your mistake lives.

11.1 First, where is the mistake

Git has several undo commands because a mistake can live in three different places. Find the place first, then pick the command.

11.2 Discard changes in the working directory

$ git restore README.md

The file returns to its last committed (or staged) state.

11.3 Unstage a file

$ git add secret.txt
$ git restore --staged secret.txt

The file leaves the staging area, but your edits stay in the working directory.

11.4 git reset: move the branch back

git reset moves the current branch to an earlier commit. The three modes decide how much of your work is also reset.

$ git reset --soft HEAD~1
$ git reset HEAD~1
$ git reset --hard HEAD~1

• Use --soft to redo a commit: your changes stay staged, ready to commit again.
• Use --mixed to unstage and rethink.
• Use --hard only when you truly want to throw the work away.

11.5 git revert: undo safely in shared history

Reset rewrites history, which is dangerous once others have your commits. Revert adds a new commit that cancels an old one, so history is never rewritten.

$ git revert 3f2a9c1
[main 7b1d2e4] Revert "Add login"
 1 file changed, 5 deletions(-)

Use revert for anything that has been pushed to a shared branch.

11.6 git clean: remove untracked files

$ git clean -n
Would remove debug.log
$ git clean -f
Removing debug.log

Always run -n (dry run) first. Add -d to include untracked folders.

11.7 Decision guide

• Not committed yet: restore.
• Committed but not pushed: reset or --amend.
• Pushed and shared: revert.

11.8 Common mistakes

• Using reset --hard casually. Prefer --soft or --mixed.
• Resetting a shared branch and force-pushing. This breaks everyone else's history. Use revert.
• Confusing restore with revert. Restore changes files; revert creates a commit.

Renaming and deleting files

Git tracks file moves and deletions too, and the right commands keep the history clean.

12.1 Deleting a tracked file

$ git rm old-notes.txt
rm 'old-notes.txt'
$ git status
Changes to be committed:
	deleted:    old-notes.txt
$ git commit -m "Remove old notes"

git rm deletes the file from disk and stages the deletion in one step. If you delete a file in your file explorer instead, Git notices it as an unstaged deletion. Stage it with git add -A or git rm <file>.

12.2 Stop tracking but keep the file

$ git rm --cached config.local

This removes the file from Git's tracking but leaves it on disk. Pair it with .gitignore (Chapter 10).

12.3 Renaming and moving

$ git mv draft.txt final.txt
$ git status
Changes to be committed:
	renamed:    draft.txt -> final.txt

git mv is the same as renaming the file yourself and then running git add on both names. Git does not store renames explicitly. It detects them by comparing contents, so a rename plus tiny edits is still recognised.

12.4 Restoring a deleted file

Deleted something by mistake? It is still in history.

$ git restore old-notes.txt
$ git restore --source=HEAD~2 old-notes.txt

The second form brings the file back from two commits ago.

12.5 Common mistakes

• Deleting with the file explorer and forgetting to stage. The deletion is not committed until you stage it.
• Renaming and changing a file in one commit. If too much changes, Git may not recognise the rename. Rename first, commit, then edit.

How Git stores data

Git is a database of snapshots identified by hashes, and seeing its structure makes the commands feel logical.

13.1 Snapshots, not differences

Older tools stored a list of changes for every file. Git instead stores a snapshot of the whole project at each commit. Unchanged files are not copied again; the new snapshot simply points to the version that already exists. This is why branching and switching are so fast.

13.2 The four object types

Git stores everything as objects inside .git/objects, each named by a hash.

13.3 Hashes: the fingerprint of content

Every object is named by a hash of its contents. By default Git uses SHA-1, a 40-character hexadecimal code. Identical content always gives an identical hash, and any tiny change produces a completely different one.

$ echo "hello" | git hash-object --stdin
ce013625030ba8dba906f756967f9e9ca394464a

This is why Git history is trustworthy: a commit's hash depends on its content and its parent's hash, so changing an old commit changes every hash after it. Git also has experimental support for SHA-256 as a stronger option.

13.4 Looking inside

$ git cat-file -t 3f2a9c1
commit
$ git cat-file -p 3f2a9c1
tree 8c3a1b9d0e7f2a4b6c5d8e9f0a1b2c3d4e5f6a7b
author Your Name <you@example.com> 1759640000 +0530
committer Your Name <you@example.com> 1759640000 +0530

Add README
$ git cat-file -p 8c3a1b9
100644 blob 2f8d6a1b7c9e0a3b5d4c6e8f9a0b1c2d3e4f5a6b	README.md

-t shows the type and -p pretty-prints the content. The hashes above are examples; yours will differ.

13.5 Branches and HEAD are just pointers

A branch is a tiny file that holds one commit hash. HEAD is a file that says which branch you are on.

$ cat .git/HEAD
ref: refs/heads/main
$ cat .git/refs/heads/main
9a1c4e7d2b8f0c3a5e6d7f8a9b0c1d2e3f4a5b6c

Creating a branch means writing a 41-byte file, which explains why it is instant. Chapter 14 builds on this.

13.6 Common mistakes

• Thinking commits store only the differences. They store full snapshots, efficiently shared.
• Editing files inside .git. Use Git commands instead, so the data stays consistent.

Branches and HEAD

A branch is a separate line of work, so you can try ideas without disturbing the stable version of your project.

14.1 The idea: parallel drafts

Writing a report, you might copy the document to try a risky rewrite. If it works you keep it, and if not you throw the copy away. A branch gives you that without copying any files. Your stable work stays on main, while the experiment lives on its own branch.

Because a branch is only a pointer to a commit (Chapter 13), creating one is instant and costs almost no space.

14.2 Creating and listing branches

$ git branch feature-login
$ git branch
  feature-login
* main

The * marks the branch you are on. Creating a branch does not move you onto it.

14.3 Switching branches

$ git switch feature-login
Switched to branch 'feature-login'
$ git switch -c feature-search
Switched to a new branch 'feature-search'

git switch -c <name> creates and switches in one step, which is the form you will use most.

When you switch, Git rewrites the files in your working directory to match that branch. Work you committed on another branch seems to vanish and returns when you switch back.

14.4 HEAD: where you are

HEAD points to the branch you are on, and that branch points to its latest commit. Each new commit moves the branch forward, and HEAD follows.

14.5 Everyday branch commands

14.6 Detached HEAD

If you check out a commit hash or a tag, HEAD points straight at a commit, not a branch. Git calls this a detached HEAD.

$ git switch --detach 3f2a9c1
HEAD is now at 3f2a9c1 Add README

You can look around safely. But a commit made here belongs to no branch and can be lost. To keep the work, give it a branch:

$ git switch -c rescue-work

To leave without keeping anything, run git switch main.

14.7 Naming branches

• Use short lowercase names with hyphens: fix-login-bug.
• Group by purpose with a prefix: feature/search, bugfix/crash, docs/readme.
• Avoid spaces and personal names.

14.8 Uncommitted changes when switching

If your edits do not touch files that differ between the branches, they travel with you. If they would be overwritten, Git refuses to switch and asks you to commit or stash first (Chapter 19).

14.9 Common mistakes

• Committing on main by accident. Check git branch before you start.
• Forgetting which branch you are on. Use git status or a prompt that shows it.
• Deleting an unmerged branch with -D. You may lose the only copy of that work.

Merging

Merging brings the work of one branch into another, and Git chooses between two methods depending on how the history looks.

15.1 The basic command

Move to the branch that should receive the work, then merge the other one in.

$ git switch main
$ git merge feature-login

The rule to remember: you merge into the branch you are standing on.

15.2 Fast-forward merge

If main has not moved since you branched, Git simply slides the main pointer forward. No new commit is needed.

$ git merge feature-login
Updating 3f2a9c1..b81e6d2
Fast-forward
 login.py | 12 ++++++++++++
 1 file changed, 12 insertions(+)

15.3 Three-way merge

If both branches have new commits, a simple slide is impossible. Git compares three snapshots: the common ancestor and the two branch tips. It then creates a merge commit with two parents.

$ git merge feature-login
Merge made by the 'ort' strategy.
 login.py | 12 ++++++++++++
 1 file changed, 12 insertions(+)

Git opens your editor with a default message such as "Merge branch 'feature-login'". Save and close to finish.

15.4 Controlling the style of merge

Teams choose between them. --no-ff keeps a visible record of each feature. --squash keeps main tidy with one commit per feature. GitHub offers the same three choices on pull requests (Chapter 25).

15.5 After merging: clean up

$ git branch -d feature-login
Deleted branch feature-login (was b81e6d2).

The commits are safe, because they are now part of main. Only the label is removed.

15.6 Common mistakes

• Merging in the wrong direction. Check which branch you are on with git status.
• Merging with uncommitted changes. Commit or stash first.
• Never deleting old branches. They clutter the list. Delete them once merged.

Merge conflicts

A conflict happens when two branches change the same lines, and Git asks you to decide what the result should be.

16.1 Why conflicts happen

Git merges automatically when branches change different parts of a file. When both branches edit the same lines, Git cannot know which version you want. It stops and asks you. That is not an error, only a question that needs a human answer.

16.2 What a conflict looks like

$ git merge feature-login
Auto-merging app.py
CONFLICT (content): Merge conflict in app.py
Automatic merge failed; fix conflicts and then commit the result.

Open the file. Git has marked the conflicting area.

<<<<<<< HEAD
greeting = "Hello, user!"
=======
greeting = "Welcome back!"
>>>>>>> feature-login

16.3 Resolving it step by step

Suppose you decide to combine both greetings. Edit the file to the final text you want and remove the markers.

greeting = "Welcome back, user!"

$ git add app.py
$ git commit
[main 4d5e6f7] Merge branch 'feature-login'

16.4 Useful commands during a conflict

16.5 Making conflicts less likely

• Pull the latest main into your branch often.
• Keep branches short-lived and focused.
• Talk to teammates before large refactors or file moves.
• Keep functions and files small so edits rarely overlap.

16.6 Seeing more context

By default Git shows only two sides. The zdiff3 style also shows the common ancestor, which often makes the right choice obvious.

$ git config --global merge.conflictStyle zdiff3

16.7 Common mistakes

• Leaving markers in the file. Search for <<<<<<< before you commit. A project with markers will not run.
• Accepting one side without reading. You may silently throw away a teammate's work.
• Panicking. git merge --abort always takes you back to safety.

Rebase

Rebase replays your commits on top of another branch, which gives a straight, easy-to-read history.

17.1 The idea

Merging joins two histories with a merge commit. Rebasing takes your branch's commits and re-applies them one by one on top of the latest main, as if you had started your work from there.

$ git switch feature
$ git rebase main
Successfully rebased and updated refs/heads/feature.

The history is now a straight line. The feature commits have the same changes but new hashes, because their parent changed.

17.2 Merge or rebase

17.3 Rebase conflicts

Conflicts can appear while commits are replayed. Resolve them as in Chapter 16, then continue.

$ git add app.py
$ git rebase --continue
$ git rebase --abort
$ git rebase --skip

• --continue carries on after you fixed the files.
• --abort returns to how things were before the rebase.
• --skip drops the commit that is causing trouble.

17.4 The golden rule of rebase

Rebase your own local or personal-branch commits freely. Do not rebase main or any shared branch.

17.5 Pull with rebase

A normal git pull can add merge commits. This keeps your local history linear instead:

$ git pull --rebase
$ git config --global pull.rebase true

17.6 Common mistakes

• Rebasing a shared branch. Follow the golden rule.
• Force-pushing after a rebase without care. Use git push --force-with-lease, which refuses to overwrite work you have not seen.
• Rebasing in a panic during conflicts. Abort and look at the state first.

Cherry-pick

Cherry-pick copies a single commit from one branch onto another without merging everything else.

18.1 When you need it

Imagine a bug fix was committed on a feature branch, and the same fix is needed urgently on main, but the rest of the feature is not ready. Cherry-pick takes just that one commit.

18.2 The command

$ git switch main
$ git cherry-pick 8e4c1b7
[main a3b9d21] Fix null pointer crash
 1 file changed, 2 insertions(+)

The copy has a new hash, because it has a new parent.

18.3 Conflicts

If the change does not apply cleanly, Git stops. Resolve the files, then run:

$ git add file.py
$ git cherry-pick --continue
$ git cherry-pick --abort

18.4 When to use it, and when not to

• Good for hotfixes that must reach a release branch quickly.
• Good for rescuing one useful commit from an abandoned branch.
• Poor as a routine way to move work. Duplicate commits make history confusing, and you may see the same change twice when the branches are merged later.

18.5 Common mistakes

• Cherry-picking too much. If you need many commits, merge or rebase instead.
• Forgetting the original still exists. The source branch keeps its own copy.

Stash

Stash puts your unfinished work on a shelf so you can change branches with a clean working directory.

19.1 The problem

You are halfway through a change when a colleague asks for an urgent fix on another branch. Your work is not ready to commit, and Git refuses to switch because it would overwrite your edits. Stash solves exactly this.

19.2 Basic use

$ git stash
Saved working directory and index state WIP on feature: 8e4c1b7 Add form
$ git switch main

Your working directory is now clean. Do the urgent work, then come back.

$ git switch feature
$ git stash pop

pop re-applies the stashed changes and removes them from the stash.

19.3 Commands you will use

$ git stash list
stash@{0}: On feature: half-finished form
stash@{1}: WIP on main: a3b9d21 Fix typo
$ git stash apply stash@{1}

19.4 What stash does not include

By default stash saves changes to tracked files only. New files that Git has never seen stay behind unless you add -u. Ignored files need -a.

19.5 Conflicts when applying

If the branch changed since you stashed, pop can conflict. Resolve it like any merge conflict. After a conflict, Git keeps the stash, so nothing is lost.

19.6 Common mistakes

• Stashing and forgetting. Stashes are easy to lose track of. Give each a message and clear them regularly.
• Expecting new files to be stashed. Use -u.
• Using stash as long-term storage. For work you want to keep, make a branch and commit.

Tags

A tag is a permanent name for one commit, usually used to mark a release such as version 1.0.

20.1 Branches move, tags stay

A branch name follows new commits. A tag always points to the same commit, which makes it ideal for marking releases like v1.0.0.

20.2 Two kinds of tags

$ git tag v1.0.0-test
$ git tag -a v1.0.0 -m "First stable release"

Prefer annotated tags for anything public.

20.3 Working with tags

20.4 Sharing tags

git push does not send tags by default. You send them on purpose.

$ git push origin v1.0.0
$ git push origin --tags
$ git push origin --delete v1.0.0

20.5 Version numbers

Most projects follow semantic versioning: MAJOR.MINOR.PATCH.

On GitHub, a tag can become a Release, a page with notes and downloadable files for that version.

20.6 Common mistakes

• Forgetting to push tags. Teammates cannot see them.
• Moving a published tag. Others may already depend on it. Create a new tag instead.
• Using lightweight tags for releases. They carry no message or date.

Remotes and cloning

A remote is a copy of your repository stored somewhere else, usually on GitHub, and cloning is how you get one onto your machine.

21.1 What a remote is

So far everything lived on your computer. A remote is another copy of the repository on a server. Teammates push their work to it and pull each other's work from it. By tradition the main remote is called origin.

21.2 Creating a repository on GitHub

1. Sign in at github.com and choose New repository.
2. Enter a name such as hello-git and an optional description.
3. Choose Public (anyone can see it) or Private (only people you invite).
4. If you already have a local project, leave the options to add a README, .gitignore and licence unchecked, so the two do not clash.
5. Select Create repository. GitHub then shows the commands you need.

21.3 Connecting an existing local project

$ git remote add origin https://github.com/your-username/hello-git.git
$ git branch -M main
$ git push -u origin main

The first line registers the remote, the second makes sure your branch is called main, and the third uploads your history. The -u flag remembers the link, so later you can type only git push.

21.4 Cloning an existing repository

$ git clone https://github.com/your-username/hello-git.git
Cloning into 'hello-git'...
$ cd hello-git

Cloning downloads the full history, sets origin automatically and checks out the default branch. To use another folder name add it at the end: git clone <url> my-folder.

21.5 Inspecting remotes

$ git remote -v
origin  https://github.com/your-username/hello-git.git (fetch)
origin  https://github.com/your-username/hello-git.git (push)

21.6 HTTPS or SSH

Every repository has two kinds of address.

Chapter 23 explains how to set up each one.

21.7 Common mistakes

• Cloning inside another repository. Clone into a clean folder.
• Adding a README on GitHub and also locally. The histories differ, and your first push is rejected. Create the repository empty instead.
• Pushing to the wrong remote. Check git remote -v first.

Push, pull and fetch

These three commands move commits between your computer and GitHub, and knowing how they differ avoids most beginner surprises.

22.1 Push: send your commits

$ git push
Enumerating objects: 5, done.
To https://github.com/your-username/hello-git.git
   3f2a9c1..9a1c4e7  main -> main

Push uploads commits that the remote does not have yet. After the first git push -u, a plain git push is enough.

22.2 Fetch: look without touching

$ git fetch
From https://github.com/your-username/hello-git
   9a1c4e7..b81e6d2  main       -> origin/main

Fetch downloads new commits but does not change your working files or your branch. They are stored in a remote-tracking branch named origin/main. You can inspect them before deciding what to do.

$ git log main..origin/main --oneline
b81e6d2 Add contact page

22.3 Pull: fetch and merge

git pull is a shortcut: it runs git fetch and then merges the result into your current branch.

$ git pull
Updating 9a1c4e7..b81e6d2
Fast-forward
 contact.html | 8 ++++++++

Use git pull --rebase if you prefer a straight history (Chapter 17).

22.4 When a push is rejected

$ git push
 ! [rejected]        main -> main (fetch first)
error: failed to push some refs
hint: Updates were rejected because the remote contains work that
hint: you do not have locally.

Someone else pushed before you. The fix is always the same: bring in their work first.

22.5 Force pushing

$ git push --force-with-lease

A force push overwrites the remote history. You may need one after a rebase or an amend. Use --force-with-lease, which stops if someone else pushed in the meantime. Never force-push to main or any branch your team shares.

22.6 Other useful push commands

22.7 Common mistakes

• Pushing without pulling first. Make git pull a habit before you start work.
• Using --force instead of --force-with-lease. The first can erase a teammate's commits.
• Thinking fetch changes your files. It does not; only merge, rebase or pull do.

Authentication: SSH keys and tokens

GitHub needs to know who you are before it accepts a push, and there are two safe ways to prove it: SSH keys and access tokens.

23.1 Why passwords no longer work

Since 2021 GitHub does not accept your account password for Git operations over HTTPS. You use either a personal access token or an SSH key. Both are safer, because they can be limited and revoked without changing your password.

23.2 Option 1: SSH keys

An SSH key is a pair of files. The private key stays secret on your computer. The public key is given to GitHub. GitHub uses the pair to check that you hold the private key, without the secret ever travelling.

$ ssh-keygen -t ed25519 -C "you@example.com"
Generating public/private ed25519 key pair.
Enter file in which to save the key (/home/you/.ssh/id_ed25519):
Enter passphrase (empty for no passphrase):
$ eval "$(ssh-agent -s)"
$ ssh-add ~/.ssh/id_ed25519
$ cat ~/.ssh/id_ed25519.pub
ssh-ed25519 AAAAC3Nz...example you@example.com

Copy the whole line that starts with ssh-ed25519. On GitHub open Settings, then SSH and GPG keys, choose New SSH key, paste it and save.

$ ssh -T git@github.com
Hi your-username! You've successfully authenticated, but GitHub does not provide shell access.

Now use the SSH form of the address:

$ git remote set-url origin git@github.com:your-username/hello-git.git

Add a passphrase when asked. It protects the key if your laptop is stolen.

23.3 Option 2: Personal access tokens

A token is a long random string that acts like a password with limited powers. GitHub offers two kinds. Fine-grained tokens can be limited to selected repositories and permissions, and GitHub recommends them where possible. Classic tokens use broad scopes such as repo.

1. Open Settings, then Developer settings, then Personal access tokens.
2. Create a token, choose the repositories and permissions, and set an expiry date.
3. Copy it immediately; GitHub shows it only once.
4. When Git asks for a password over HTTPS, paste the token.

Git Credential Manager, which comes with Git for Windows and is available on other systems, stores the token safely so you do not paste it every time.

23.4 Choosing between them

23.5 GitHub CLI shortcut

The GitHub command-line tool gh can handle the login for you.

$ gh auth login

23.6 Common mistakes

• Committing a token or private key. Treat it as leaked and revoke it at once.
• Using a token with far too many permissions. Give the minimum.
• Mixing HTTPS and SSH remotes. An SSH key does nothing if your remote is an https:// address.

Forks

A fork is your own copy of someone else's repository on GitHub, which lets you propose changes to a project you do not own.

24.1 Why forks exist

You cannot push to a stranger's repository. A fork copies it into your account, where you have full control. You change your copy, then ask the owner to take your changes through a pull request (Chapter 25).

24.2 Fork versus clone

You usually do both: fork on GitHub, then clone your fork.

24.3 Forking step by step

1. Open the project's page and select Fork.
2. Choose your account and create the fork.
3. Clone your fork, not the original.

$ git clone git@github.com:your-username/project.git
$ cd project
$ git remote -v
origin  git@github.com:your-username/project.git (fetch)

24.4 Adding the upstream remote

The original repository is usually called upstream. Add it so you can pull in its new work.

$ git remote add upstream https://github.com/original-owner/project.git
$ git remote -v
origin    git@github.com:your-username/project.git (fetch)
upstream  https://github.com/original-owner/project.git (fetch)

24.5 Keeping your fork up to date

$ git fetch upstream
$ git switch main
$ git merge upstream/main
$ git push origin main

GitHub also has a Sync fork button on your fork's page that does the same thing without the command line.

24.6 Common mistakes

• Cloning the original instead of your fork. You cannot push to it.
• Forgetting to sync. Your changes drift away from the project and conflict later.
• Forking when you are already a collaborator. If you have write access, a branch in the same repository is simpler.

Pull requests

A pull request asks the project to take your branch, and it is where discussion, review and automatic checks happen before merging.

25.1 What a pull request is

A pull request (PR) is a proposal to merge one branch into another. It is a page on GitHub that shows the changes, hosts the discussion and runs automatic checks. Even on your own project, PRs are a good habit because they record why a change was made.

25.2 Opening a pull request

$ git switch -c fix-typo
$ git add README.md
$ git commit -m "Fix typo in installation steps"
$ git push -u origin fix-typo
remote: Create a pull request for 'fix-typo' on GitHub by visiting:
remote:   https://github.com/your-username/hello-git/pull/new/fix-typo

GitHub shows a Compare and pull request button. On the form, write:

• A clear title, like a good commit message.
• A description of what changed and why, with screenshots if the change is visual.
• Closing keywords such as Closes #12, which automatically close issue 12 when the PR merges.
• Reviewers and assignees, if your team uses them.

25.3 Draft pull requests

Choose Create draft pull request when the work is not ready. A draft cannot be merged. It tells people you want early feedback, not a final review.

25.4 Reading a pull request page

25.5 Three ways to merge

Repository owners can allow only the styles they prefer.

25.6 After the merge

$ git switch main
$ git pull
$ git branch -d fix-typo

GitHub offers a Delete branch button after merging. Use it to keep the branch list short.

25.7 Pull request templates

A file named .github/pull_request_template.md fills each new PR with a checklist, which helps authors remember tests and documentation.

## What does this change?

## How was it tested?

- [ ] Tests added or updated
- [ ] Documentation updated

25.8 Common mistakes

• Huge pull requests. Reviewers skim them. Keep PRs small and focused.
• No description. Explain the why, not just the what.
• Pushing more commits after approval without telling anyone. New commits usually require a fresh review.

Code review

Review is where teammates catch bugs, share knowledge and keep quality high, and a kind, clear style makes it work.

26.1 Why review code

Another pair of eyes finds problems the author no longer sees. Review also spreads knowledge across the team, so no part of the project is understood by only one person.

26.2 How a review works on GitHub

Open Files changed. Hover over a line, select the + button and leave a comment. When you finish, choose Review changes and pick one of three options.

26.3 Suggested changes

Inside a comment, choose the Add a suggestion button. GitHub inserts a special block that you edit to hold the replacement text, for example:

total = price * quantity

The author accepts it with Commit suggestion, and GitHub makes the commit for them. Suggestions are ideal for typos and small fixes.

26.4 What to look for

26.5 Writing helpful comments

• Comment on the code, not the person: "This loop can skip the last item" rather than "You made a mistake".
• Explain why, and offer an alternative when you can.
• Label small preferences, for example "nit:" for style points that need not block merging.
• Praise good work. It is part of a review too.

26.6 Receiving feedback

• Assume good intent. Reviewers want the project to succeed.
• Reply to every comment, even if only to say "Done".
• Disagree politely with reasons, and ask questions if something is unclear.
• Push fixes as new commits, then click Resolve conversation once addressed.

26.7 Requesting a review

Use the Reviewers panel on the right of the pull request. A file called CODEOWNERS (Chapter 33) can add the right reviewers automatically.

26.8 Common mistakes

• Approving without reading. A rubber stamp helps nobody.
• Rewriting the author's design in comments. Discuss big design questions before the code is written.
• Waiting days to review. Slow feedback blocks the team. Aim to respond within a working day.

Issues, labels and projects

Issues record bugs and ideas, and projects arrange them into a board, so the whole team can see what is happening.

27.1 What an issue is

An issue is a discussion thread about a bug, a task or a feature request. It has a title, a description, comments, an assignee and labels. Issues are numbered, such as #12, and you can refer to them from commits and pull requests.

27.2 Writing a good issue

A good bug report lets someone reproduce the problem without asking questions.

Title: Login button does nothing on Safari

Steps to reproduce
1. Open the login page in Safari 17
2. Enter a valid email and password
3. Click "Log in"

Expected: the dashboard opens
Actual: nothing happens and no error appears

Environment: macOS 14, Safari 17.2

27.3 Labels, assignees and milestones

GitHub provides default labels, and you can add your own. The good first issue label is a convention that helps newcomers find easy tasks.

27.4 Linking issues and code

Mention an issue anywhere with #12. Use closing keywords in a pull request description or a commit message:

Fix login on Safari

Closes #12

The keywords close, fix and resolve, in their various forms, close the issue when the change reaches the default branch.

27.5 Mentions and references

• @username notifies a person.
• #12 links to an issue or pull request.
• A full commit hash links to that commit.

27.6 GitHub Projects

A project is a board or table that collects issues and pull requests from one or more repositories. You can arrange them into columns such as Backlog, In progress, In review and Done, and add fields like priority or sprint.

27.7 Issue templates

Files inside .github/ISSUE_TEMPLATE/ give reporters a form to fill in, which makes reports more complete.

27.8 Discussions

For open-ended questions and ideas that are not tasks, repositories can turn on Discussions, a forum-style space separate from issues.

27.9 Common mistakes

• Vague issues like "it is broken". Add steps, expected and actual results.
• Duplicates. Search before you open a new issue.
• Issues without owners. Assign someone, or label them as available.

GitHub Pages

GitHub Pages turns a repository into a free website, with no server to manage.

28.1 What Pages gives you

GitHub Pages hosts static sites made of HTML, CSS and JavaScript files. It is free, serves over HTTPS and updates every time you push. It is ideal for portfolios, project documentation and landing pages. It cannot run server-side code or a database, which is why this handbook's interactive parts all run in the browser.

28.2 Two kinds of site

28.3 Publishing your first page

<!DOCTYPE html>
<html lang="en">
<head><meta charset="utf-8"><title>My first page</title></head>
<body>
  <h1>Hello from GitHub Pages</h1>
</body>
</html>

$ git add index.html
$ git commit -m "Add home page"
$ git push origin main

In the repository, open Settings, choose Pages, and under Build and deployment pick Deploy from a branch. Select main and the / (root) folder, then save. GitHub shows the address when the deployment finishes.

28.4 Using GitHub Actions to deploy

If your site needs a build step, for example a React app or a static site generator, choose GitHub Actions as the source and add a workflow that builds the site and publishes the output. Chapter 31 introduces workflows.

28.5 Custom domains

In Settings, then Pages, you can enter your own domain. Create the matching DNS record at your domain registrar, and GitHub provides the HTTPS certificate.

28.6 Handy tips

• Put images and styles in folders and link them with relative paths.
• A file named 404.html becomes your custom error page.
• A .nojekyll file turns off the default Jekyll processing, which helps with plain HTML projects that have folders starting with an underscore.

28.7 Common mistakes

• Missing index.html. Pages shows a 404 without it.
• Wrong path casing. File names are case sensitive on GitHub: Logo.png is not logo.png.
• Expecting instant updates. A deployment can take a minute or two.
• Putting secrets in a Pages repository. Everything published is public.

Repository hygiene

A well-kept repository welcomes newcomers and protects the project with a clear README, licence and contribution rules.

29.1 The README: the front door

The README is the first thing visitors see. GitHub displays it under the file list. A good README answers four questions in under a minute: What is this? How do I run it? How do I use it? How do I help?

# Project name

One sentence about what it does.

## Install
## Usage
## Contributing
## Licence

Add a screenshot, a short code example and badges for build status if you have them. Write in Markdown.

29.2 Markdown essentials

29.3 Choosing a licence

Without a licence, nobody has permission to reuse your code, even if it is public. Add a LICENSE file. GitHub can create one from a template when you add a file.

This is a simplified summary, not legal advice. For serious projects read the licence text or ask someone qualified.

29.4 Community files

GitHub shows these in the Community standards page of a repository and links them from the issue and PR screens.

29.5 Description, topics and social image

Fill in the one-line About description and add topics such as python or git-tutorial. Topics help people find your project in search.

29.6 A profile README

Create a public repository whose name is exactly your username, and add a README.md. GitHub shows it at the top of your profile, which is a good place for a short introduction and links to your best work.

29.7 Common mistakes

• No licence. People cannot legally reuse the code.
• A README that only says the project name. Explain installation and usage.
• Committing generated files and secrets. Use .gitignore.

Contributing to open source

Open source runs on small contributions from strangers, and the workflow you have learned is exactly how they are made.

30.1 Why contribute

Contributing to open source teaches you to read real code, work with reviewers and communicate in public. Your commits and merged pull requests also become a visible record of your skills on your GitHub profile.

30.2 Finding a first project

• Search GitHub issues with the label good first issue or help wanted.
• Start with tools you already use, and look at their documentation for typos or gaps.
• Check that the project is alive: recent commits, answered issues, and a CONTRIBUTING.md.

30.3 The complete workflow

$ git clone git@github.com:your-username/project.git
$ cd project
$ git remote add upstream https://github.com/owner/project.git
$ git switch -c fix-docs-typo
$ git add docs/install.md
$ git commit -m "Fix typo in installation guide"
$ git push -u origin fix-docs-typo

30.4 Small contributions count

You do not need to write a new feature. These are all welcome and valuable:

• Correcting documentation, typos and broken links.
• Adding a missing example.
• Reproducing a bug and adding details to the issue.
• Improving tests.
• Translating text.

30.5 Good etiquette

• Read the existing issues and pull requests first, so you do not duplicate work.
• Ask before starting a large change.
• Keep pull requests small and on topic.
• Be patient. Maintainers are often volunteers.
• Say thank you, and accept feedback gracefully.

30.6 When your pull request is not accepted

It happens, and it is not personal. The project may have a different direction. Ask what would make the change acceptable, learn from it, and try another issue.

30.7 Becoming a maintainer

Contributors who help regularly are sometimes invited to review and merge. As a maintainer, you will triage issues, review pull requests and keep documentation current, which makes your GitHub activity richer and more visible.

30.8 Common mistakes

• Opening a pull request without reading the contribution guide. It may be closed quickly.
• One giant pull request. Split it up.
• Working on main in your fork. Always use a branch.

GitHub Actions

Actions runs your tests and scripts automatically whenever something happens in your repository, and it works as the engine of your whole workflow.

31.1 What Actions does

GitHub Actions is a built-in automation service. When an event occurs, such as a push or a pull request, GitHub starts a virtual machine and runs the commands you describe. The most common use is continuous integration (CI): every change is built and tested automatically, so mistakes show up in minutes.

31.2 The vocabulary

31.3 Your first workflow

Create the file .github/workflows/ci.yml in your repository.

name: CI

on:
  push:
    branches: [main]
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pip install -r requirements.txt
      - run: pytest

Reading it from top to bottom: run on every push to main and on every pull request; start an Ubuntu machine; fetch the code; install Python; install dependencies; run the tests.

$ git add .github/workflows/ci.yml
$ git commit -m "Add CI workflow"
$ git push

31.4 Watching it run

Open the Actions tab of your repository. Each run shows a green tick or a red cross. Click a run, then a job, to read the log of every step. On a pull request, the same result appears at the bottom as a check. A failed step stops the job. Fix the code, push again, and the workflow re-runs. You can also choose Re-run jobs on a run page.

31.5 YAML in two minutes

• YAML uses spaces for nesting, never tabs. Two spaces is standard.
• A line starting with - is a list item.
• key: value pairs make a dictionary.
• Quote values that could be misread, like "3.12", which would otherwise be read as the number 3.12.

31.6 Common mistakes

• Wrong folder. Workflows must be in .github/workflows/.
• Tab characters. They break YAML. Use spaces.
• Forgetting actions/checkout. Without it, the runner has none of your files.
• Misquoting versions. Python 3.10 unquoted becomes 3.1.

Actions in practice

Matrices, secrets, caching and schedules turn a simple workflow into a dependable pipeline.

32.1 Test on several versions: matrix

A matrix runs the same job many times with different values.

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ["3.11", "3.12", "3.13"]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}
      - run: pytest

Three parallel jobs appear, one per version.

32.2 Secrets

Never write passwords or API keys in a workflow file. Store them under Settings, then Secrets and variables, then Actions, and read them in the workflow.

steps:
  - run: ./deploy.sh
    env:
      API_TOKEN: ${{ secrets.API_TOKEN }}

GitHub hides secret values in the logs. Secrets are not passed to workflows triggered from forks, which protects you from malicious pull requests.

32.3 Caching dependencies

Many setup actions can cache downloads and make runs faster.

- uses: actions/setup-python@v5
  with:
    python-version: "3.12"
    cache: pip

32.4 Other triggers

on:
  schedule:
    - cron: "0 3 * * 1"
  workflow_dispatch:

That runs every Monday at 03:00 UTC, and also gives you a manual Run workflow button.

32.5 Artifacts: keep the output

- uses: actions/upload-artifact@v4
  with:
    name: test-report
    path: reports/

Artifacts are files saved with a run, such as test reports or built packages, which you can download from the run page.

32.6 Deploying to GitHub Pages

permissions:
  contents: read
  pages: write
  id-token: write

The permissions block gives the workflow's built-in token only what it needs. Combined with the official Pages actions, it publishes your site after each push to main.

32.7 Writing safe workflows

• Give the token the least permissions with a permissions: block.
• Treat pull requests from forks as untrusted. Do not run their code with access to secrets.
• Trust actions from verified creators, and pin important third-party actions to a full commit hash.

32.8 Common mistakes

• Printing secrets in logs. Even masked values can leak when transformed.
• Using pull_request_target carelessly. It can expose secrets to untrusted code.
• Very slow workflows. Cache, run jobs in parallel and test only what changed.

Branch protection and CODEOWNERS

Protection rules make sure nothing reaches the main branch without review and passing checks, even by accident.

33.1 The problem

Rules in a document are easy to forget. Branch protection turns them into settings that GitHub enforces for everyone, including administrators if you choose.

33.2 Common rules

Open Settings, then Branches (or Rules, then Rulesets), and add a rule for main.

33.3 Rulesets

Rulesets are the newer, more flexible way to do this. They can target several branches or tags with patterns, can apply across an organisation, and can run in an evaluate mode first, which reports what would have been blocked without enforcing anything. Use them when you have more than a couple of rules.

33.4 CODEOWNERS

A file named CODEOWNERS assigns people or teams to parts of the codebase. When a pull request touches those files, GitHub asks the owners to review.

# Everything
*                  @your-username

# Documentation
/docs/             @docs-team

# Workflows need an admin's eye
/.github/workflows/ @your-username

Place the file in .github/, the root or docs/. With the rule Require review from Code Owners, no one can merge changes to those files without an owner's approval.

33.5 A sensible starting setup

• Require a pull request with one approval.
• Require the CI check to pass.
• Block force pushes and deletions.
• Add a CODEOWNERS file for sensitive paths.

33.6 Common mistakes

• Requiring checks that never run. The pull request will wait forever. Make sure the check name matches your workflow job.
• Too strict for a small team. Five required reviewers slows everyone. Match the rules to your team size.
• Letting admins bypass rules routinely. The exception becomes the habit.

Git hooks

Hooks are small scripts that Git runs automatically at key moments, so mistakes are stopped before they reach the team.

34.1 What a hook is

A hook is a script that Git starts when something happens, such as just before a commit. If the script exits with an error, Git cancels the action. Hooks live in .git/hooks/.

$ ls .git/hooks
applypatch-msg.sample  pre-commit.sample  pre-push.sample  commit-msg.sample

Git ships samples ending in .sample. Remove the suffix to activate one.

34.2 Useful hooks

34.3 A simple pre-commit hook

This script refuses any commit that includes a file called .env.

#!/bin/sh
if git diff --cached --name-only | grep -q '^\.env$'; then
  echo "Blocked: .env must not be committed."
  exit 1
fi

Save it as .git/hooks/pre-commit and make it executable.

$ chmod +x .git/hooks/pre-commit
$ git add .env
$ git commit -m "Add settings"
Blocked: .env must not be committed.

34.4 Hooks are not shared

Everything inside .git stays on your machine, so teammates do not receive your hooks. Two common ways to share them:

• Keep hooks in a folder in the repository and point Git at it: git config core.hooksPath .githooks.
• Use a hook manager such as the pre-commit framework (Python), Husky (JavaScript) or lefthook.

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.6.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-added-large-files

$ pip install pre-commit
$ pre-commit install

From now on those checks run on every commit.

34.5 Skipping a hook

$ git commit --no-verify -m "Emergency fix"

Use this rarely. Anyone can bypass local hooks, so important rules should also exist in CI (Chapter 31) and branch protection (Chapter 33).

34.6 Common mistakes

• Forgetting chmod +x. A hook that is not executable is silently ignored.
• Slow hooks. If a commit takes thirty seconds, people will skip them. Keep pre-commit fast and put long tests in pre-push or CI.
• Relying only on local hooks. They are a convenience, not security.

Reflog and recovery

Git rarely loses committed work, and the reflog is the diary that lets you find it again.

35.1 The safety net

You ran git reset --hard and your commits disappeared from git log. They are not truly gone. Git keeps a private diary, the reflog, of every place HEAD has pointed. As long as a commit appears in it, you can bring it back.

$ git reflog
9a1c4e7 HEAD@{0}: reset: moving to HEAD~2
b81e6d2 HEAD@{1}: commit: Add search
3f2a9c1 HEAD@{2}: commit: Add login

Entry HEAD@{1} is the commit that the reset made unreachable.

35.2 Recovering a lost commit

$ git switch -c rescue b81e6d2
$ git reset --hard b81e6d2

Creating a branch at the old hash is the safest form, because it adds a label to the commit without moving anything else. You can also reset the current branch back to the entry shown by the reflog:

$ git reset --hard HEAD@{1}

35.3 Typical rescue stories

35.4 Per-branch reflog

$ git reflog show feature

Each branch also has its own history of movements.

35.5 How long entries last

Reflog entries are kept for a limited time, by default about 90 days for reachable entries and 30 days for unreachable ones, after which Git's clean-up can remove them. Recover work soon rather than later.

35.6 When the reflog is not enough

Work that was never committed is not in the reflog. A file you edited and discarded with git restore cannot be recovered by Git. Commit early and often to give Git something to remember. For objects not reachable even from the reflog, git fsck --lost-found can list dangling commits, which is a last resort.

35.7 Common mistakes

• Panicking and running more commands. Stop and read the reflog first.
• Expecting to recover uncommitted work. Git cannot restore what it never saw.
• Waiting weeks. Old unreachable entries are eventually cleaned up.

Bisect and interactive rebase

Bisect finds the commit that introduced a bug, and interactive rebase lets you polish your commits before you share them.

36.1 git bisect: find the bad commit

Suppose a bug appeared somewhere in the last 200 commits. Checking each would take hours. Bisect performs a binary search, halving the range each time, so about eight checks are enough for 200 commits.

$ git bisect start
$ git bisect bad
$ git bisect good v1.2.0
Bisecting: 97 revisions left to test after this (roughly 7 steps)
$ git bisect good
$ git bisect bad
b81e6d2 is the first bad commit
$ git bisect reset

36.2 Automating bisect

If you have a test that fails on the bug, let Git run it.

$ git bisect start HEAD v1.2.0
$ git bisect run pytest tests/test_checkout.py

Git repeats the test at each step and reports the first failing commit by itself.

36.3 Interactive rebase: polish history

Before opening a pull request you may want to merge small "fix typo" commits or reword unclear messages. Interactive rebase does that on your own, unshared commits.

$ git rebase -i HEAD~4

An editor opens with a list, oldest commit first.

pick 3f2a9c1 Add login form
pick 8e4c1b7 Fix typo
pick a3b9d21 Add validation
pick 7b1d2e4 Fix validation bug

Change the word at the start of each line to say what to do.

pick 3f2a9c1 Add login form
fixup 8e4c1b7 Fix typo
pick a3b9d21 Add validation
fixup 7b1d2e4 Fix validation bug

Save and close. Four commits become two clean ones. You can also reorder commits by moving their lines.

36.4 Fixup commits

$ git commit --fixup 3f2a9c1
$ git rebase -i --autosquash HEAD~5

--fixup records a correction aimed at an earlier commit, and --autosquash arranges the list for you.

36.5 Safety

36.6 Common mistakes

• Rebasing shared commits. The golden rule from Chapter 17 applies.
• Marking the first line as squash. There is no earlier commit to merge into.
• Not knowing a good commit for bisect. Use a release tag or an older commit that you know worked.

Submodules, monorepos and large files

Big projects need tools for sharing code between repositories and storing large files, and each has trade-offs.

37.1 Submodules: a repository inside a repository

A submodule pins another repository at an exact commit inside yours. It is useful when you depend on a shared library that lives in its own repository.

$ git submodule add https://github.com/example/shared-lib.git libs/shared-lib
$ git commit -m "Add shared-lib as a submodule"

Git records the submodule's address in .gitmodules and the commit it points to. Cloning needs one more flag, or the folder will be empty.

$ git clone --recurse-submodules https://github.com/you/app.git
$ git submodule update --init --recursive
$ git submodule update --remote

Often a package manager (pip, npm, Maven) is simpler for libraries. Consider submodules when you need the source and its history together.

37.2 Monorepo or many repositories

Very large repositories can use sparse checkout, which downloads only some folders, and partial clone, which downloads file contents on demand.

$ git clone --filter=blob:none https://github.com/example/big-repo.git
$ git sparse-checkout set services/api

37.3 Large files and Git LFS

Git stores every version of every file forever, so large binary files such as videos, datasets and design files make a repository huge. GitHub warns about files over 50 MB and blocks files over 100 MB. Git LFS (Large File Storage) keeps lightweight pointer files in Git and stores the real content on a separate server.

$ git lfs install
$ git lfs track "*.psd"
$ git add .gitattributes
$ git add design.psd
$ git commit -m "Add design file with LFS"

Tracking rules are saved in .gitattributes, which you commit.

GitHub gives each account a limited LFS storage and bandwidth allowance, so check the current limits for your plan. Datasets that change often are better kept in dedicated tools for data versioning or in cloud storage.

37.4 Common mistakes

• Cloning a repository with submodules and getting empty folders. Use --recurse-submodules.
• Committing large datasets to normal Git. Use LFS or external storage.
• Moving to a monorepo without build tooling. Builds and tests become slow.

Security: secrets, Dependabot and signed commits

One leaked password can undo a project, so build safe habits and let GitHub's automatic tools watch for you.

38.1 Rule one: secrets do not belong in Git

Passwords, API keys, tokens and private keys must never be committed. Even if you delete the file later, the secret remains in the history, and public repositories are scanned by bots within minutes.

38.2 If you leak a secret

Revoking comes first because anyone may already have copied the secret. Cleaning history is a second, optional step.

38.3 Keeping secrets out

• Put them in a .env file that is listed in .gitignore, and commit a .env.example with fake values.
• Use your platform's secret store: GitHub Actions secrets, a cloud key vault or a password manager.
• Turn on secret scanning and push protection in your repository's security settings, which block pushes that contain recognised secrets.
• Add a pre-commit hook that scans for secrets (Chapter 34).

38.4 Dependabot

Dependabot watches your dependencies.

# .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: "pip"
    directory: "/"
    schedule:
      interval: "weekly"

38.5 Code scanning

Code scanning with CodeQL analyses your source for common vulnerability patterns and reports them on pull requests. It is free for public repositories and available for private ones on some plans.

38.6 Protect your account

• Use a strong, unique password in a password manager.
• Turn on two-factor authentication. GitHub requires it for people who contribute code.
• Consider passkeys or hardware security keys.
• Review Settings, then Sessions and SSH keys now and then, and remove what you do not recognise.

38.7 Signed commits

Anyone can set any name and email in Git, so a commit's author is not proof of identity. A signature proves that the commit came from the holder of a key. GitHub marks such commits Verified. Git can sign with an SSH key, which you may already have from Chapter 23.

$ git config --global gpg.format ssh
$ git config --global user.signingkey ~/.ssh/id_ed25519.pub
$ git config --global commit.gpgsign true

Add the same public key in GitHub under SSH and GPG keys, choosing the type Signing key.

38.8 Report vulnerabilities properly

A SECURITY.md file tells visitors how to report a problem privately. GitHub also offers private vulnerability reporting, so researchers do not post exploits in public issues.

38.9 Common mistakes

• Thinking a private repository is safe for secrets. Access changes, repositories get forked and leaked.
• Deleting the file and calling it fixed. The history still has it.
• Ignoring Dependabot pull requests. Old, vulnerable dependencies are a common way in.

Branching strategies

A branching strategy is the team's agreement on how branches are named, used and merged, and the right one depends on how often you release.

39.1 Why you need one

Git lets you branch in any way you like, which is exactly the problem. Without an agreement, every developer does something different, and merging becomes painful. A strategy gives everyone the same map.

39.2 GitHub Flow

The simplest model, used by many web teams. main is always ready to deploy. All work happens on short-lived branches that are merged by pull request.

39.3 Git Flow

A heavier model for software with versions and scheduled releases, such as mobile apps and libraries. It has permanent branches (main and develop) and temporary ones (feature, release, hotfix).

39.4 Trunk-based development

Everyone works on one shared branch, the trunk (main). Changes are tiny and merged at least daily, directly or through very short-lived branches. Unfinished features are hidden behind feature flags, switches that turn code on or off without a new deployment. It is the style used by many large teams that deploy continuously, and it relies on strong automated tests.

39.5 Comparing them

39.6 How to choose

• Deploy several times a week? Start with GitHub Flow.
• Ship numbered versions and support older ones? Consider Git Flow, or a simplified release-branch version of it.
• Have excellent tests and an experienced team? Try trunk-based development.

39.7 Common mistakes

• Choosing Git Flow because it looks professional. It adds overhead that small teams do not need.
• Long-lived feature branches. The longer a branch lives, the worse the conflicts.
• Having a strategy nobody wrote down. Put it in CONTRIBUTING.md.

Team best practices

Good habits make a repository pleasant for everyone, and most of them take only a few seconds.

40.1 Commits

• Commit small and often; each commit does one thing.
• Write messages in the imperative: "Add", "Fix", "Remove".
• Never commit secrets, generated files or large binaries.
• Make sure the project builds and the tests pass at every commit when you can.

40.2 Conventional commits

Many teams add a short type prefix, which helps tools generate change logs and version numbers.

40.3 Branches

• Name branches by purpose: feature/search, fix/login-timeout.
• Keep them short-lived and delete them after merging.
• Update from main regularly to avoid giant conflicts.

40.4 Pull requests

• Keep them small. A few hundred changed lines at most is a good target.
• Explain what and why, and link the issue.
• Run the tests yourself before asking for review.
• Review your own pull request first; you will catch things.

40.5 Reviews

• Respond within a working day.
• Be kind, specific and constructive (Chapter 26).
• Authors fix; reviewers do not push to someone else's branch without asking.

40.6 Repository settings

• Protect main and require reviews and checks (Chapter 33).
• Keep a clear README, CONTRIBUTING.md and .gitignore.
• Turn on Dependabot and secret scanning (Chapter 38).
• Use one line-ending policy through .gitattributes.

# .gitattributes
* text=auto
*.sh text eol=lf

40.7 Onboarding a new teammate

40.8 Common mistakes

• Different habits for each person. Write the rules down once.
• Huge, rare merges. Integrate small and often.
• Skipping reviews under pressure. That is exactly when bugs slip in.

Common mistakes and fixes

Everyone makes the same Git mistakes, and almost all of them have a short, safe fix.

41.1 I committed on the wrong branch

You meant to work on a feature branch but committed on main, and have not pushed yet.

$ git branch feature-x
$ git reset --hard origin/main
$ git switch feature-x

The first line keeps your commits on a new branch, the second moves main back to match the remote, and the third takes you to your work.

41.2 I want to undo my last commit but keep the changes

$ git reset --soft HEAD~1

41.3 I forgot a file in the last commit

$ git add forgotten.txt
$ git commit --amend --no-edit

41.4 I need to undo a merge

$ git merge --abort
$ git reset --hard ORIG_HEAD
$ git revert -m 1 <merge-hash>

Use the first when the merge is still in progress, the second right after a merge you have not pushed, and the third for a merge that is already pushed.

41.5 I committed a file that should be ignored

$ git rm --cached secrets.txt
$ echo "secrets.txt" >> .gitignore
$ git commit -am "Stop tracking secrets.txt"

If it held a real secret, follow Chapter 38.

41.6 Error messages and what they mean

41.7 I think I lost my work

Do not panic and do not run more commands blindly. Run git reflog, find the commit, and create a branch at it (Chapter 35). Uncommitted edits are the only thing Git cannot return.

41.8 Safety habits

• Run git status before and after every important command.
• Commit often so there is something to go back to.
• Create a backup branch before a risky operation: git branch backup.
• Use --dry-run or -n where a command offers it.
• Prefer --force-with-lease to --force.

Cheat sheet

One place to look up the commands you use most, grouped by what you want to do.

42.1 Setup and configuration

42.2 Starting a repository

42.3 Snapshots

42.4 Inspecting

42.5 Branching and merging

42.6 Remotes

42.7 Undoing

42.8 Shelving and marking

42.9 Advanced

42.10 Symbols worth knowing

Interview questions

These questions come up again and again in developer interviews, with short answers you can explain in your own words.

Tap a question to see a model answer. Try answering aloud first.

43.1 Basics

43.2 Branching and merging

43.3 Undoing and recovery

43.4 GitHub and teamwork

Glossary

Plain-language definitions of the terms used in this handbook.

44.1 Terms