gittutorial(7) — A Tutorial Introduction to Git

Reference, not a lesson — condensed from the official Git manual page gittutorial(7). The numbered course pages teach the model; this records what the manual says. Checked against Git 2.48.1: nothing on this page depends on a newer release.

Official tutorial introduction to Git for importing projects, making changes, managing branches, collaborating with other developers, and exploring repository history.

High-level manual pages and low-level mechanics:

Git-Man-Page (git(1)): Primary command-line tool, options, and subcommand classifications.
Git-Core-Tutorial-Man-Page (gitcore-tutorial(7)): Plumbing commands, object database architecture, and 3-way merge mechanics.

Overview & Setup

Synopsis

git *

Accessing Built-In Help

To open the manual page for any Git command (e.g., git log):

$ git help log
# OR
$ man git-log

Initial Configuration (Identity Setup)

Before creating commits or repository objects, configure your name and public email address:

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

Importing a New Project

To place an existing project (e.g., unpacked from project.tar.gz) under Git revision control:

$ tar xzf project.tar.gz
$ cd project
$ git init

Output: Initialized empty Git repository in .git/ (creates the hidden .git metadata directory).

Stage all existing files and record the initial commit:

$ git add .
$ git commit -m "Initial commit"

Making Changes & Staging

Key Concept: Git Tracks Content Snapshots

Unlike traditional VCS tools that record file deltas, Git’s git add captures a content snapshot of specified files and stages them into the index (staging area). git add works identically for newly created files and newly modified tracked files.

# Stage content of specific files into the index
$ git add file1 file2 file3

# View staged changes (Index vs. HEAD commit)
$ git diff --cached

# View unstaged working tree changes (Working Directory vs. Index)
$ git diff

# View overall repository status
$ git status

Example `git status` Output

On branch master
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)

        modified:   file1
        modified:   file2
        modified:   file3

Commit staged changes:

$ git commit

Shortcut Command

To automatically stage all modified (already-tracked) files and record a commit in a single step:

$ git commit -a

Commit Message Conventions

Begin commit messages with a concise summary line (≤ 50 characters).
Follow with a blank line and detailed explanation.
The summary line serves as the commit title across Git tools (e.g., subject line in git format-patch emails or short logs in git log --oneline).

Viewing Project History

$ git log                 # Chronological commit log
$ git log -p              # Commit log with full unified diffs
$ git log --stat --summary # Commit log with diffstats and file creation/deletion summaries

Managing Branches & Conflict Resolution

Branches allow independent lines of development within a single repository.

Branch Workflow

# Create a branch named 'experimental'
$ git branch experimental

# List branches (* marks active HEAD branch)
$ git branch

# Switch to 'experimental' branch
$ git switch experimental
# (Alternative legacy command: git checkout experimental)

# Edit files and commit on 'experimental'
$ git commit -a

# Switch back to 'master' branch
$ git switch master

# Diverge history by committing on 'master'
$ git commit -a

# Merge 'experimental' branch into 'master'
$ git merge experimental

Handling Merge Conflicts

If changes on both branches conflict, Git flags conflict markers inside the affected files.

Inspect unmerged files and conflict diffs:
```
$ git diff
```
Manually edit files to resolve conflicts.
Stage resolved files and complete merge commit:
```
$ git commit -a
```
Visualize resulting merge graph graphically:
```
$ gitk
```

Deleting Branches

# Safe delete (verifies changes are merged into current branch)
$ git branch -d experimental

# Force delete an unmerged branch
$ git branch -D crazy-idea

Collaboration & Remote Repositories

Example Scenario: Alice and Bob

1. Cloning

Bob clones Alice’s repository into a new local folder myrepo:

bob$ git clone /home/alice/project myrepo

Bob commits local changes:

bob$ git commit -a

Alice pulls Bob’s commits into her repository:

alice$ cd /home/alice/project
alice$ git pull /home/bob/myrepo master

Note on git pull: pull performs a fetch followed by a merge. Local changes should be committed prior to pulling to avoid conflicts with uncommitted working directory state.

3. Inspecting Before Merging

To safely inspect Bob’s work before merging:

alice$ git fetch /home/bob/myrepo master
alice$ git log -p HEAD..FETCH_HEAD

HEAD..FETCH_HEAD: Shows commits reachable from FETCH_HEAD (Bob’s state) excluding commits reachable from HEAD (Alice’s state).

Visualize divergence with gitk:

# Two-dot notation: Commits Bob has that Alice lacks
$ gitk HEAD..FETCH_HEAD

# Three-dot notation: Symmetric difference (commits on either branch not shared)
$ gitk HEAD...FETCH_HEAD

4. Defining Remote Repositories (`git remote`)

Define shorthand aliases for remote locations:

alice$ git remote add bob /home/bob/myrepo
alice$ git fetch bob
alice$ git log -p master..bob/master
alice$ git merge bob/master

5. Automatic Tracking & Origin

When Bob cloned Alice’s repository, Git automatically configured origin:

bob$ git config --get remote.origin.url
# Output: /home/alice/project

bob$ git branch -r
# Output: origin/master

bob$ git pull
# Fetches and merges origin/master into local active branch automatically

6. Protocols & Centralized Workflows

Git supports remote repository transfers via SSH (alice.org:/home/alice/project), native Git protocol (git://), and HTTP/HTTPS, supporting distributed peer-to-peer or centralized CVS/SVN-style push/pull models.

Exploring History & Revision Syntax

Object Identification

Full SHA Hash: c82a22c39cbc32576f64f5c6b3f24b99ea8149c7
Short SHA: c82a22c39c
Symbolic Reference: HEAD, branch names (master, experimental), tags (v2.5).

Parent Traversal Operators

HEAD^ / HEAD^1: First parent of commit.
HEAD^2: Second parent of a merge commit.
HEAD^^: Grandparent commit (HEAD^1^1).
HEAD~4: 4th generation parent commit along first-parent chain.

Tagging Commits

$ git tag v2.5 1b2e1d63ff

Revision Specifiers in Action

# Compare current working state with tag v2.5
$ git diff v2.5 HEAD

# Create branch 'stable' starting at tag v2.5
$ git branch stable v2.5

# Hard reset current branch and working directory to parent commit
$ git reset --hard HEAD^

Warning on git reset --hard: Permanently discards uncommitted working tree changes and unreferenced commits on current branch. Use git revert to undo published public commits safely.

Searching Content (`git grep`)

# Search for string "hello" inside project tree at tag v2.5
$ git grep "hello" v2.5

# Search across tracked files in working directory
$ git grep "hello"

Specifying Commit Ranges

$ git log v2.5..v2.6            # Commits reachable from v2.6 but not v2.5
$ git log v2.5..                # All commits made since v2.5
$ git log --since="2 weeks ago" # Commits from the past two weeks
$ git log v2.5.. Makefile       # Commits modifying Makefile since v2.5
$ git log stable..master        # Commits on 'master' not present on 'stable'
$ git log master..stable        # Commits on 'stable' not present on 'master'

Graphical History & Filtering (`gitk`)

$ gitk --since="2 weeks ago" drivers/

(Tip: In gitk, adjust font sizes using Ctrl + + and Ctrl + -).

Inspecting Specific File Versions

$ git show v2.5:Makefile                  # Display Makefile content as it existed at tag v2.5
$ git diff v2.5:Makefile HEAD:Makefile.in # Compare Makefile at v2.5 against Makefile.in at HEAD

Core Concepts & Follow-Up Guides

Two Core Architectural Foundations

Object Database: Content-addressable store holding immutable project history objects (blobs, trees, commits, tags).
Index File: Intermediate cache tracking directory tree state, used to prepare commits, checkout files, and resolve 3-way merges.

gittutorial-2(7): In-depth tutorial covering object database structures and index file mechanics.
git-format-patch(1) / git-am(1): Creating and applying email patch series.
git-bisect(1): Binary search tool for pinpointing bug-introducing commits.
gitworkflows(7): Recommended branching and integration strategies.
giteveryday(7): Everyday Git reference covering ~20 essential commands.
gitcvs-migration(7): Migration guide for CVS users.