🐙 Learn Git — Guide

A comprehensive, step-by-step guide to Git and GitHub: from installation to branching, merging, and troubleshooting common problems.

📌 Table of Contents

What is Git?
Project Structure
Installation
Configuration
The Basics — Step by Step
Branches — Working in Parallel
Complete Daily Workflow
Common Problems & Solutions
Command Cheatsheet
Resources

📌 What is Git?

Git is a version control tool — it tracks ALL changes to your code.
GitHub is the website that hosts your Git code online.

Your Computer → Git (local tool) → GitHub (online)

📂 Project Structure

git/
│
├── README.md # This file — complete guide
├── .gitignore # Files to ignore
└── git_cheatsheet.md # All commands at a glance

🚀 Installation

Windows

Go to git-scm.com/download/win
Download and install Git
Open Git Bash (search "Git Bash" in Start menu)

Mac

Open Terminal and type:

git --version

If Git is not installed, a window will open to install it automatically.

Linux

sudo apt install git

✅ Verify Installation

git --version
# Expected: git version 2.x.x

⚙️ Configuration

Do this ONCE — tell Git who you are:

git config --global user.name "YourUsername"
git config --global user.email "your-email@example.com"

Verify configuration:

git config --list

📖 The Basics — Step by Step

Step 1 — Create a Local Repository

# Create a new folder
mkdir my-project
cd my-project
# Initialize Git in this folder
git init

💡 git init creates a hidden .git/ folder that contains the entire history.

Step 2 — Check File Status

git status

The 3 states of a file:

Untracked → Git doesn't know this file yet (red)
Staged → Git will include this file in the next commit (green)
Committed → Saved in history ✅

Step 3 — Add Files (Staging)

# Add ONE specific file
git add my_file.py
# Add ALL modified files
git add .# Add only .py files
git add *.py

Step 4 — Commit (Save)

git commit -m "Clear description of what you did"

Good commit messages:

git commit -m "Add data cleaning function"
git commit -m "Fix bug in for loop"
git commit -m "Update README with install instructions"

Bad commit messages:

git commit -m "fix"# too vague
git commit -m "changes"# useless
git commit -m "aaaa"# incomprehensible

Step 5 — View History

# Full history
git log
# Short history (one line per commit)
git log --oneline
# History with branch graph
git log --oneline --graph --all

Step 6 — Connect to GitHub

# After creating the repo on github.com:
git remote add origin https://github.com/YourUsername/my-repo.git
# Verify connection
git remote -v

Step 7 — Push to GitHub

# First push (creates main branch on GitHub)
git push -u origin main
# Subsequent pushes (no need for -u)
git push

Step 8 — Pull Changes from GitHub

git pull

Step 9 — Clone an Existing Repo

git clone https://github.com/YourUsername/my-repo.git
cd my-repo

🌿 Branches — Working in Parallel

A branch is an isolated copy of your code where you can experiment without touching the main code.

main ──●──●──●──────────────●
\ /
feature ●──●──●──●──●

Create and Use a Branch

# See all branches (* = current branch)
git branch
# Create a new branch
git branch my-new-feature
# Switch to that branch
git checkout my-new-feature
# Shortcut: create AND switch in one command
git checkout -b my-new-feature
# Verify which branch you're on
git branch

Merge a Branch into Main

# 1. Switch back to main
git checkout main
# 2. Merge the branch
git merge my-new-feature
# 3. Delete the branch (optional, once merged)
git branch -d my-new-feature

🔄 Complete Daily Workflow

# Morning: pull latest changes
git pull
# Create a branch for your task
git checkout -b feature/add-cleaning-function
# ... you work, you code ...# See what changed
git status
git diff
# Save your work
git add .
git commit -m "Add clean_data() function"# Push to GitHub
git push origin feature/add-cleaning-function
# On GitHub: create a Pull Request to merge into main

🚨 Common Problems & Solutions

❌ Problem 1 — "fatal: not a git repository"

fatal: not a git repository (or any of the parent directories): .git

Cause: You're not in a Git folder.

# Check where you arepwd# Either navigate to the right foldercd my-project
# Or initialize Git here
git init

❌ Problem 2 — Merge Conflict

CONFLICT (content): Merge conflict in my_file.py
Automatic merge failed; fix conflicts and then commit the result.

Cause: Two people (or branches) modified the same part of the same file.

Solution — Step by step:

# 1. See which files have conflicts
git status
# 2. Open the file — you'll see markers like this:

<<<<<<<HEAD# Your code (current version)defclean_data(df):
returndf.dropna()
=======# Code from the other branchdefclean_data(df):
returndf.fillna(0)
>>>>>>>feature/other-branch

# 3. Edit the file manually: keep what you want, delete the markers# 4. Mark the conflict as resolved
git add my_file.py
# 5. Finalize the merge
git commit -m "Resolve conflict in my_file.py"

❌ Problem 3 — "error: failed to push some refs"

error: failed to push some refs to 'https://github.com/...'
hint: Updates were rejected because the remote contains work that you do not have locally.

Cause: GitHub has changes you don't have locally.

# 1. Pull remote changes first
git pull origin main
# 2. Resolve conflicts if needed (see Problem 2)# 3. Then push
git push origin main

❌ Problem 4 — "fatal: branch 'main' not found"

error: src refspec main does not match any

Cause: Your branch is called master, not main.

# Rename the branch to main
git branch -M main
# Then push
git push -u origin main

❌ Problem 5 — Undo Last Commit (Not Yet Pushed)

# Undo commit BUT keep modifications in files
git reset --soft HEAD~1
# Undo commit AND modifications (⚠️ irreversible!)
git reset --hard HEAD~1

❌ Problem 6 — Undo a git add (Unstage)

# Unstage a specific file
git restore --staged my_file.py
# Unstage everything
git restore --staged .

❌ Problem 7 — "Permission denied (publickey)"

git@github.com: Permission denied (publickey).

Cause: Using SSH without a configured key.

# See current URL
git remote -v
# Switch to HTTPS
git remote set-url origin https://github.com/YourUsername/my-repo.git

❌ Problem 8 — Remove a File from Git Tracking (Without Deleting It)

# Remove from Git tracking but keep on disk
git rm --cached my_file.py
# Add it to .gitignoreecho"my_file.py">> .gitignore
git add .gitignore
git commit -m "Remove my_file.py from tracking"

❌ Problem 9 — "detached HEAD state"

HEAD detached at a3f5d92

Cause: You navigated to an old commit with git checkout <hash>.

# Return to main branch
git checkout main

❌ Problem 10 — Recover a Deleted File

# See list of deleted files
git status
# Restore a deleted file
git restore my_deleted_file.py

❌ Problem 11 — GitHub Authentication (Token)

Since 2021, GitHub no longer accepts passwords — you need a Personal Access Token.

Go to GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)
Click Generate new token
Check repo and workflow
Copy the token (you'll only see it once!)
When Git asks for a password → paste the token

❌ Problem 12 — Missing Dependencies (requirements.txt)

# Install all listed dependencies
pip install -r requirements.txt
# Create a requirements.txt from your environment
pip freeze > requirements.txt

📋 Command Cheatsheet

Command	What It Does
`git init`	Initialize a Git repo in current folder
`git clone <url>`	Copy a remote repo locally
`git status`	Show file status
`git add .`	Add all files to staging
`git commit -m "msg"`	Save a snapshot with a message
`git push`	Send commits to GitHub
`git pull`	Get changes from GitHub
`git log --oneline`	Commit history
`git branch`	List branches
`git checkout -b name`	Create and switch to a new branch
`git merge name`	Merge a branch into current branch
`git diff`	Show uncommitted changes
`git stash`	Temporarily set aside changes
`git stash pop`	Retrieve stashed changes

🔗 Resources

🎮 learngitbranching.js.org — Learn Git visually (FREE)
📘 docs.github.com — Official GitHub documentation
🎬 git-scm.com/book — The official Git book
🛠️ ohshitgit.com — Solutions to common Git problems

Name		Name	Last commit message	Last commit date
Git cheatsheet.md		Git cheatsheet.md
README.md		README.md

Latest commit

History

Folders and files

Repository files navigation