Git reference guide

History

What is version control?

Version control is a system that helps track and manage changes to files, especially in software development. It lets multiple people collaborate on a project without overwriting each other's work, and keeps a history of every modification. It helps with:

• Tracking changes — every modification is recorded, making it easy to revert to a previous version if needed.
• Collaboration — multiple developers can work on the same project simultaneously without conflicts.
• Backup & recovery — if something goes wrong, you can restore an earlier version.
• Branching & merging — developers can create separate branches for new features or bug fixes, then merge them back into the main project.

Version control systems (VCS) fall into three main types:

1. Local Version Control (LVCS) — changes are stored locally on a single computer, saved as patches; hard to collaborate and easy to lose.
2. Centralized Version Control (CVCS) — a single repository stores all versions (e.g. Subversion, Microsoft TFS). Easier collaboration, but a single point of failure.
3. Distributed Version Control (DVCS) — every user has a full copy of the repository, allowing offline work and better redundancy (e.g. Git, Mercurial).

Limitations of centralized version control

Before Git, developers relied on centralized version control systems, which had real limitations: single points of failure and restricted offline work. Developers couldn't keep their own copy of the repository, so they couldn't work offline independently.

• Single point of failure — if the central server crashes, all history and collaboration are lost unless backups exist.
• Requires constant connectivity — developers must be connected to commit changes or view history.
• Limited offline work — no independent access to the central repository.
• Slower performance — every operation talks to the central server.
• Risk of data loss — a corrupted or compromised central repo can lose everything.

What was the need for Git?

• Distributed version control — every developer has a full copy of the repository, enabling offline work.
• Efficient collaboration — branches let people work on different features simultaneously.
• Change tracking — a detailed history makes it easy to revert.
• Performance & speed — optimized for large projects.
• Security & integrity — every change is stored using cryptographic hashing.

What is Git?

Git is a distributed version control system that helps developers track changes, collaborate efficiently, and manage different versions of a project. It was created by Linus Torvalds in 2005 to manage the Linux kernel, and quickly became the industry standard.

• Version control — keeps a history of all changes so you can revert if needed.
• Branching & merging — separate branches for new features or fixes, merged back into the main project.
• Collaboration — multiple developers work on the same project without overwriting each other's changes.
• Performance — fast and efficient, even for large projects.

What "distributed" means

In Git, every developer has a complete copy of the repository — including its entire history — on their local machine. Unlike centralized systems, Git lets developers work independently without needing constant access to a central server.

Git vs GitHub

Git is the engine; GitHub is the garage where teams collaborate.

• Git is a distributed version control system that runs locally on a developer's machine and allows offline work.
• GitHub is a web-based platform that hosts Git repositories, adding tools like pull requests, issue tracking, and project management.

Key differences

Alternatives

• GitLab — a complete DevOps platform with built-in CI/CD and issue tracking.
• Bitbucket — a good fit for teams already using Atlassian tools like Jira.
• SourceForge — supports multiple version control systems, including Git and SVN.
• Gitea — a lightweight, self-hosted Git service.
• Beanstalk — version control with built-in code review and deployment tools.

Git lifecycle

Every change moves through a handful of areas on its way from your editor to a shared remote.

Stash

A temporary locker for changes you're not ready to commit yet.

git stash              # Stash current changes
git stash list         # View stashed changes
git stash pop          # Apply and remove the latest stash
git stash apply        # Apply the latest stash without removing it
git stash drop         # Delete a specific stash

Workspace (working directory)

Where you create or modify files. Changes here aren't yet tracked by Git.

git status                 # Show changes in the working directory and staging area
git diff                   # View unstaged changes
git checkout -- <filename> # Discard changes in a file
git clean -fd              # Remove untracked files and directories

Index (staging area)

Where you prepare changes before committing.

git status              # Show changes in the working directory and staging area
git add <filename>      # Stage a file
git add .               # Stage all changes
git reset <filename>    # Unstage a file
git diff --cached        # View staged changes

Local repository

Where committed changes are stored locally.

git commit -m "commit message"   # Commit staged changes
git log                          # View commit history
git reset --soft HEAD^           # Undo last commit, keep changes staged
git reset --hard HEAD            # Reset to last commit, discard all changes

Upstream (remote repository)

The shared repository for collaboration — e.g. GitHub.

git remote -v            # Show remote URLs
git fetch                # Get changes from remote without merging
git pull                 # Fetch and merge changes from remote
git push                 # Push local commits to remote
git clone <url>          # Clone a remote repository

Walkthrough: stash, fix, and return

Scenario: you're mid-feature but need to fix a bug on main right now. Stash your work, switch branches, fix the bug, then come back.

# 1. Start from a feature branch — you're now in the workspace
git checkout -b feature/login-form

# 2. Make some changes, check status
git status

# 3. Stage one file
git add login.js

# 4. Stash both staged and unstaged changes
git stash push -m "WIP: login form"

# 5. Switch to main and fix the bug — this commit lands in the local repository
git checkout main
git add app.js
git commit -m "Fix: crash on login redirect"

# 6. Push the fix to the remote repository
git push origin main

# 7. Return to the feature branch
git checkout feature/login-form

# 8. Reapply the stash — files are restored as they were
git stash pop

Download & installation

• Go to the Git downloads page.
• Pick your platform (macOS / Windows / Linux) — it recommends the latest release automatically.
• Download and install it for your OS.

Configuration

Step 1: generate an SSH key pair

1. Open a terminal (Git Bash on Windows, Terminal on macOS/Linux).
2. Generate a new RSA key pair:

   ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

   Replace the email with your GitHub email.
3. Press Enter to accept the default file location (~/.ssh/id_rsa).
4. Optionally add a passphrase for extra security.

Step 2: add the key to the SSH agent

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_rsa

Step 3: add the key to GitHub

1. Copy the public key:

   cat ~/.ssh/id_rsa.pub

2. In GitHub, go to Settings → SSH and GPG keys.
3. Click New SSH Key, paste it in, and save.

Step 4: test the connection

ssh -T git@github.com

On success you'll see something like:

Hi username! You've successfully authenticated, but GitHub does not provide shell access.

First configurations

Use cases

Connecting to a remote repository

Assuming you already have a repository on GitHub and its URL.

1. Navigate to the folder where you want to clone it, open a terminal there, and run:

   git clone https://github.com/your-organization/repository-name.git

2. Move into the cloned repository:

   cd repository-name

3. Confirm the remote is set correctly:

   git remote -v

   If needed, add it:

   git remote add origin https://github.com/your-organization/repository-name.git

4. Pull updates regularly (replace main with your default branch if different):

   git pull origin main

5. If there's a merge conflict, resolve it manually, then:

   git add .
   git commit -m "Resolved merge conflicts"
   git push origin main

Syncing local changes to the remote

Keeps your local branch up to date and your contributions integrated with everyone else's.

# 1. Check what's changed
git status

# 2. Stage changes
git add .              # everything
git add filename       # or a specific file

# 3. Commit with a meaningful message
git commit -m "Updated files with latest changes"

# 4. Pull the latest changes before pushing (replace main if different)
git pull origin main --rebase

# 5. Push
git push origin main

# 6. Verify
git log --oneline -n 5