Git Tutorial: Essential Commands and Scenarios

Git is a distributed version control system that helps you track changes to your code, collaborate with others, and manage project history. This simple tutorial covers some of the most commonly used git commands and workflows you will need in real-world development.

What does "git" stand for? From the first README by the developers, we see the following

GIT – the stupid content tracker
        
"git" can mean anything, depending on your mood.

- random three-letter combination that is pronounceable, and not
  actually used by any common UNIX command. The fact that it is a
  mispronunciation of "get" may or may not be relevant.
- stupid. contemptible and despicable. simple. Take your pick from the
  dictionary of slang.
- "global information tracker": you're in a good mood, and it actually
  works for you. Angels sing, and a light suddenly fills the room.
- "goddamn idiotic truckload of sh*t": when it breaks

This is a stupid (but extremely fast) directory content manager. It
doesn't do a whole lot, but what it _does_ do is track directory
contents efficiently.

Table of Contents

1. Setup and Configuration
2. Basic Workflow
3. Branching and Merging
4. Collaboration
5. Fixing Mistakes
6. Common Scenarios
7. Tips and Best Practices
8. Cheat Sheet

1. Setup and Configuration

Before using Git, set up your identity:

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

• Check your configuration: git config --list
• Initialize a new Git repository: git init

2. Basic Workflow

The basic Git workflow involves staging changes, committing them, and viewing history.

Create and Track Files

• Create a file (e.g., readme.md).
• Check the status of your repository: git status

Stage Changes

• Add specific files to the staging area: git add readme.md
• Add all modified files: git add .

Commit Changes

• Save staged changes with a message: git commit -m "Add readme file"
• Stage and commit in one step:

git commit -am "Update readme"

View History

• See commit history: git log
• Compact version: git log --oneline

3. Branching and Merging

Branches allow you to work on features or fixes without affecting the main codebase.

Create and Switch Branches

• Create a new branch: git branch feature-branch
• Switch to it: git checkout feature-branch
• Create and switch in one command:

git checkout -b feature-branch

List Branches

• See all branches (current branch marked with *): git branch

Merge Branches

• Switch to the target branch (e.g., master): git checkout master
• Merge the feature branch into master: git merge feature-branch
  Note: I do not recommend directly merge feature-branch into master/main branch, unless you know what you are doing. Always open a Pull Request (PR) to merge your feature-branch into your master/main branch!
• If there are conflicts, resolve them manually, then:

  git add .
  git commit

Delete a Branch

• After merging, delete the branch: git branch -d feature-branch

4. Collaboration

Git can be very useful in team settings with remote repositories (e.g., GitHub, GitLab).

Clone a Repository

• Download a remote repo: git clone https://github.com/username/repo.git

Link to a Remote

• Add a remote repository: git remote add origin https://github.com/username/repo.git

Push Changes

• Send local commits to the remote: git push origin master

Pull Changes

• Fetch and merge updates from the remote: git pull origin master

Fetch Without Merging

• Download updates without merging: git fetch origin

5. Fixing Mistakes

Mistakes happen — Git provides ways to undo or fix them.

Unstage Changes

• Remove a file from staging: git restore --staged readme.md

Discard Local Changes

• Undo uncommitted changes to a file: git restore readme.md
• Discard all uncommitted changes: git restore .
• Discard all changes and revert back to where you have started (will lose all work!): git checkout -- .

Amend a Commit

• Edit the last commit message or add forgotten changes: git commit --amend -m "Updated message"

Revert a Commit

• Undo a commit by creating a new commit: git revert <commit-hash>

Reset Commits

• Move back to a previous commit: git reset --hard <commit-hash>
  Warning: This rewrites the commit history! That means if you have commits after the <commit-hash> that you reset to, those commits are no longer part of the branch’s history. They are effectively removed from the branch’s timeline.
• Uncommit but keep changes: git reset --soft <commit-hash>

6. Common Scenarios

Here are practical workflows for real-world situations.

Scenario 1: Starting a New Feature

1. Create a branch: git checkout -b new-feature
2. Work, stage, and commit:

   git add .
   git commit -m "Implement feature"

3. Push to remote: git push origin new-feature
4. Open a pull request (PR) on GitHub/GitLab.
   

Scenario 2: Fixing a Bug on Master

1. Switch to master: git checkout master
2. Create a bugfix branch: git checkout -b bugfix-issue-123
3. Fix the bug, commit, and push:

   git add .
   git commit -m "Fix issue #123"
   git push origin bugfix-issue-123

4. Merge into master via PR or locally:

   git checkout master
   git merge bugfix-issue-123

Scenario 3: Resolving Merge Conflicts

1. Run git merge and encounter conflicts.
2. Open conflicted files, resolve manually (look for <<<<<<<, =======, >>>>>>> markers).
3. Stage resolved files: git add <file>
4. Complete the merge: git commit

Scenario 4: Redirecting a PR to a Different Branch

In this scenario, contributor submits PR to master, but you want it on dev to review it first before merging into main, do:

1. Fetch the PR: git fetch origin pull/<PR-number>/head:pr-branch
2. Create a new branch based on dev:

   git checkout dev
   git checkout -b pr-dev-branch
   git merge pr-branch

3. Push and create a new PR: git push origin pr-dev-branch
4. Close the original PR with a note.

Scenario 5: Viewing Differences

• See changes in working directory: git diff
• Compare staged changes: git diff --staged
• Compare branches: git diff master feature-branch

7. Tips and Best Practices

1. Commit Often: Small, logical commits are easier to track and revert.
2. Write Good Messages: Use clear, concise commit messages, e.g., "Fix login bug" (good) vs "Changes" (bad).
3. Pull Before Pushing: Avoid conflicts by running git pull first.
4. Use Branches: Keep master (sometimes main) branch stable; experiment in feature branches.
5. Backup Work: Push to a remote regularly to avoid losing changes.

8. Cheat Sheet

Command	Description
git init	Initialize a new repository
git add <file>	Stage changes
git commit -m "msg"	Commit staged changes
git status	Check repository status
git log	View commit history
git branch	List branches
git checkout -b <name>	Create and switch to a branch
git merge <branch>	Merge a branch into the current one
git push origin <branch>	Push to remote repository
git pull origin <branch>	Pull updates from remote
git reset --hard	Reset to a commit (discard changes)
git revert <hash>	Undo a commit with a new commit

This tutorial covers the essentials to get you started and handle most day-to-day tasks with Git. Happy coding!