Introduction
We have all been there. You are working on a coding project, and you decide to test a new feature. To protect your working code, you make a copy of the folder and name it portfolio-backup. A few hours later, you make another copy named portfolio-v2-final. By the end of the week, your hard drive is cluttered with folders like portfolio-v3-really-final-use-this-one.
This manual approach to version control is messy, wastes disk space, and makes collaborating with other developers impossible. If two developers edit the same file at the same time in separate folders, merging their changes manually is a nightmare.
This is where Git and GitHub come in. Git is a tool that tracks changes to your files over time, allowing you to recall specific versions at any time and work collaboratively without overwriting each other's code. This guide simplifies Git and GitHub, detailing the core workflow, branching, and collaboration.
The Three Stages of Git
Git manages your code across three distinct local environments before sending it to a remote host like GitHub.
1. Working Directory: The actual files on your computer's filesystem. This is where you write and edit code.
2. Staging Area (Index): A preparation area. You mark files here that you want to include in your next snapshot.
3. Local Repository: The permanent history store on your machine. When you commit, Git saves a snapshot of your staged files here.
4. Remote Repository (GitHub): A hosted copy of your local repository on the web, enabling collaboration.
┌───────────────────┐ git add ┌───────────────────┐
│ WORKING DIRECTORY │ ────────────────────> │ STAGING AREA │
└───────────────────┘ └───────────────────┘
▲ │
│ git checkout │ git commit
│ ▼
┌───────────────────┐ git push ┌───────────────────┐
│ REMOTE REPOSITORY │ <──────────────────── │ LOCAL REPOSITORY │
│ (GitHub) │ └───────────────────┘
└───────────────────┘
The Core Git Workflow
To track files using Git, open your terminal in your project's root folder and follow these core steps:
1. Initialize Git
Create a hidden .git directory in your project folder. This folder acts as Git's tracking database:
git init
2. Check Status
Check which files are untracked or modified:
git status
3. Stage Files
Add specific files to the staging area:
# Stage a single file
git add index.html
# Stage all files in the current directory
git add .
4. Commit Changes
Save a snapshot of the staged files to your local history. Always write a clear description of what changed:
git commit -m "feat: add semantic header to portfolio landing page"
Branching & Merging
A branch is an isolated timeline of commits. When you want to build a feature, fix a bug, or experiment, create a branch. This keeps your experiments safe without affecting the stable production code on your main branch.
Creating and Switching Branches
Create a branch and switch to it immediately:
# Modern command to switch and create
git switch -c feature/contact-form
`/
#### Merging Branches
Once your feature is complete and tested, merge it back into the main branch:
# 1. Switch to the target branch
git switch main
# 2. Merge the feature branch
git merge feature/contact-form
---
### Handling Merge Conflicts
A **merge conflict** occurs when two branches modify the exact same line of code in a file, and you try to merge them. Git does not know which version is correct, so it pauses the merge and asks you to resolve it.
#### Conflict Markers
When a conflict occurs, Git marks the affected file with visual boundaries:
<<<<<<< HEAD
<h1 class="title">Samad's Coding Portfolio</h1>
=======
<h1 class="title">Samad Shaikh | Full Stack Engineer</h1>
>>>>>>> feature/contact-form
* The code between `<<<<<<< HEAD` and `=======` represents the version on the branch you are currently on.
* The code between `=======` and `>>>>>>> feature/contact-form` is the version from the branch you are trying to merge.
#### Resolution Steps
1. Open the conflicted file in your text editor (VS Code highlights these files automatically).
2. Delete the conflict markers (`<<<<<<<`, `=======`, `>>>>>>>`).
3. Edit the code to keep the version you want, or combine both.
4. Save the file.
5. Stage the resolved file: `git add <filename>`.
6. Finalize the merge commit: `git commit -m "merge: resolve contact form title conflict"`.
---
### GitHub & Remote Collaboration
While Git is a local command-line tool, **GitHub** is a cloud hosting service for Git repositories.
#### Cloning a Remote Repo
To download an existing repository from GitHub to your computer:
git clone https://github.com/username/repo-name.git
#### Sharing & Synchronizing Changes
* **`git push`**: Upload your local commits to GitHub.
* **`git pull`**: Download and merge the latest commits from GitHub into your local working directory. Run this before starting work to avoid conflicts.
#### The Pull Request (PR) Workflow
When working in teams, developers do not push code directly to the main branch. Instead, they use Pull Requests:
1. Create a local branch and make your commits.
2. Push your branch to GitHub: `git push -u origin feature/new-button`.
3. Open GitHub in your browser and click **Compare & pull request**.
4. Describe your changes and request reviews from teammates.
5. Once approved, click **Merge pull request** to merge your branch into the main branch.
---
### Production-Grade Git Configurations
To configure Git with your credentials and set up standard files, follow these configurations:
#### Global Git Setup
Set your identity so Git commits are correctly attributed to you:
# Configure username and email
git config --global user.name "Samad Shaikh"
git config --global user.email "samad@samadshaikh.me"
# Configure default branch name to 'main'
git config --global init.defaultBranch main
#### Production-Grade `.gitignore` Template
Create a `.gitignore` file in your root directory to prevent temporary files and secure keys from being uploaded to GitHub:
# filepath: .gitignore
# Dependency directories
node_modules/
jspm_packages/
# Build outputs
dist/
build/
.next/
# Environmental variables (CRITICAL: Contains private API keys)
.env
.env.local
.env.production
# System and logs files
.DS_Store
Thumbs.db
npm-debug.log*
yarn-debug.log*