A comprehensive, step-by-step guide to Git and GitHub: from installation to branching, merging, and troubleshooting common problems.
- 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
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)
git/
│
├── README.md # This file — complete guide
├── .gitignore # Files to ignore
└── git_cheatsheet.md # All commands at a glance
- Go to git-scm.com/download/win
- Download and install Git
- Open Git Bash (search "Git Bash" in Start menu)
Open Terminal and type:
git --versionIf Git is not installed, a window will open to install it automatically.
sudo apt install gitgit --version
# Expected: git version 2.x.xDo 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# Create a new folder
mkdir my-project
cd my-project
# Initialize Git in this folder
git init💡
git initcreates a hidden.git/folder that contains the entire history.
git statusThe 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 ✅
# Add ONE specific file
git add my_file.py
# Add ALL modified files
git add .
# Add only .py files
git add *.pygit 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# Full history
git log
# Short history (one line per commit)
git log --oneline
# History with branch graph
git log --oneline --graph --all# After creating the repo on github.com:
git remote add origin https://github.com/YourUsername/my-repo.git
# Verify connection
git remote -v# First push (creates main branch on GitHub)
git push -u origin main
# Subsequent pushes (no need for -u)
git pushgit pullgit clone https://github.com/YourUsername/my-repo.git
cd my-repoA branch is an isolated copy of your code where you can experiment without touching the main code.
main ──●──●──●──────────────●
\ /
feature ●──●──●──●──●
# 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# 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# 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 mainfatal: not a git repository (or any of the parent directories): .git
Cause: You're not in a Git folder.
# Check where you are
pwd
# Either navigate to the right folder
cd my-project
# Or initialize Git here
git initCONFLICT (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)
def clean_data(df):
return df.dropna()
=======
# Code from the other branch
def clean_data(df):
return df.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"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 mainerror: 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# Undo commit BUT keep modifications in files
git reset --soft HEAD~1
# Undo commit AND modifications (⚠️ irreversible!)
git reset --hard HEAD~1# Unstage a specific file
git restore --staged my_file.py
# Unstage everything
git restore --staged .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# Remove from Git tracking but keep on disk
git rm --cached my_file.py
# Add it to .gitignore
echo "my_file.py" >> .gitignore
git add .gitignore
git commit -m "Remove my_file.py from tracking"HEAD detached at a3f5d92
Cause: You navigated to an old commit with git checkout <hash>.
# Return to main branch
git checkout main# See list of deleted files
git status
# Restore a deleted file
git restore my_deleted_file.pySince 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
repoandworkflow - Copy the token (you'll only see it once!)
- When Git asks for a password → paste the token
# Install all listed dependencies
pip install -r requirements.txt
# Create a requirements.txt from your environment
pip freeze > requirements.txt| 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 |
- 🎮 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