Version Control

Version Control #

Table of Contents #

Resources #

[ h ][ d ][ y ] Git

[ d ] gitattributes
[ h ][ g ][ w ] git-annex
[ h ][ g ][ w ] Git LFS
- [ d ] Managing large files
- https://www.atlassian.com/git/tutorials/git-lfs
[ h ][ g ][ w ] git-sizer
[ h ][ g ][ w ] pre-commit

[ h ][ d ][ y ] GitHub

[ h ][ d ][ g ] GitHub CLI
[ h ][ d ][ g ] GitHub Pages

[ h ][ d ][ y ] GitLab

Use SSH keys to communicate with GitLab

[ h ] Graphite

More Git Providers

[ h ][ d ] AWS CodeCommit
[ h ][ d ] Atlassian Bitbucket

[2020][2019] MIT Missing Semester: Version Control

David Mahler

[ y ] David Mahler. (2018). “Introduction to Git - Remotes”.
[ y ] David Mahler. (2017). “Introduction to Git - Branching and Merging”.
[ y ] David Mahler. (2017). “Introduction to Git - Core Concepts”.

freeCodeCamp

[ y ] 11-18-2021. freeCodeCamp. “Advanced Git Tutorial - Interactive Rebase, Cherry-Picking, Reflog, Submodules, and more”. YouTube.
[ y ] 09-30-2021. freeCodeCamp. “Git for Professionals Tutorial - Tools & Concepts for Mastering Version Control with Git”. YouTube.
[ y ] 07-13-2021. freeCodeCamp. “Git Branch Tutorial”.
[ y ] 11-24-2020. freeCodeCamp. “How to Undo Mistakes WIth Git Using the Command Line”. YouTube.
[ y ] 05-28-2020. freeCodeCamp. “Git and GitHub for Beginners - Crash Course”. YouTube.
[ y ] 09-23-2016. freeCodeCamp. “Git & GitHub”.

YouTube

[ y ] GitLab. (14 Nov 2017). “Git Internals - How Git Works - Fear Not The SHA!”. YouTube.
[ y ] Mr. P Solver. (16 May 2022). “A Git Tutorial Based On Examples (Code Along!)”. YouTube.
[ y ] CS50. (11 Apr 2018). “Git Internals by John Britton of GitHub - CS50 Tech Talk”. YouTube.
[ y ] HackersOnBoard. (2013). “[Linux.conf.au 2013] - Git For Ages 4 and Up”.

VS Code

[ d ] Using Git source control in VS Code
[ e ] Git Graph extension
[ e ] Git History extension
[ e ] GitLens extension

More

[ y ] 02-08-2024. GitButler. “So You Think You Know Git - FOSDEM 2024”.

Texts #

Chacon, Scott & Ben Straub. (2014). Pro Git: Everything You Need to Know About Git, 2nd Ed. Apress. Home.

Ponuthorai, Prem Kumar & Jon Loeliger. (2022). Version Control with Git: Powerful Tools and Techniques for Collaborative Software Development. 3rd Ed. O’Reilly.

Silverman, Richard E. (2013). Git Pocket Guide: A Working Introduction. O’Reilly.

Vinto, Natale & Alex Soto Bueno. (2023). GitOps Cookbook: Kubernetes Automation in Practice. O’Reilly.

Terms #

[ w ] Atlassian
[ w ] Atomic Commit
[ w ] Binary Large Object (BLOB)
[ w ] Bitbucket
[ w ] Branch
[ w ] Centralized Version Control
[ w ] Changeset
[ w ] Checksum
[ w ] Commit (version control)
[ w ] Commit (data management)
[ w ] Concurrent Versions System (CVS)
[ w ] Content-Addressable Storage (CAS)
[ w ] Darcs
[ w ] Data Differencing
[ w ] Delta Encoding
[ w ] Detached State
[ w ] diff
[ w ] diff3
[ w ] Directory Structure
[ w ] Distributed Version Control
[ w ] Edit Conflict
[ w ] etckeeper
[ w ] Forge
[ w ] Git
[ w ] Git Provider
[ w ] git-annex
[ w ] GitHub
[ w ] GitLab
[ w ] GNU Arch
[ w ] GNU Bazaar
[ w ] Local Folder
[ w ] Local Repository
[ w ] Mercurial
[ w ] Merge
[ w ] Merge Conflict
[ w ] Merkle Tree
[ w ] Metadata
[ w ] Microsoft Visual SourceSafe (VSS)
[ w ] Monorepo
[ w ] Monotone
[ w ] Patch
[ w ] patch
[ w ] Pull Request
[ w ] Remote Repository
[ w ] Repository
[ w ] Revision Control System (RCS)
[ w ] Revision Tag
[ w ] Source Code Control System (SCCS)
[ w ] Source Code Management (SCM)
[ w ] Staging Area
[ w ] Subversion (SVN)
[ w ] Tag
[ w ] Three-Phase Commit Protocol
[ w ] Tree
[ w ] Tree Structure
[ w ] Two-Phase Commit Protocol
[ w ] Version Control
[ w ] Working Tree

Notes #

$1\quad$ Working Directory

files are edited in the working directory

git add; git rm; git mv

“staging a file”; “caching a file”; “putting a file in the index”
a file is copied into the object store and indexed by its SHA-1

$2\quad$ Index (or Cache or Staging Directory) (virtual, mutable data structure)

the index collects (or “stages”) alterations to files as a final step before commit (i.e., it tracks what you want to commit)
the index caches info about the working directory, and the next revision to be committed
the index serves as an interface between the working tree and the object database
the index is a binary file and so stores binary data
its content is transient; and describes the structure of the entire repo at a specific point in time
- a virtual tree state representing a tree object that will be referenced by a future commit
- a sorted list of file pathnames in its virtual state along with its permissions and a reference to the SHA-1 ID of the corresponding blob objects
- a cached representation of all the blob objects that reflect the current state of the working directory
the index does not contain file content
plays a role in the following: committing; querying the status of the repo; merging branches

git commit

checks the index–not the working directory–to discover what to commit as a single changeset

$3\quad$ Repo (or Local Commit History) (virtual)

the repo is a key-value pair database

Object Store (or Object Database) (append-only data structure) - contains the original data files; log messages; author info; datetimes; etc.

Blobs “Binary Large Object” (immutable) - represents a version of a file; contains the file’s data only
- a version of a file that holds the file’s data; a blob’s name is a hash of its content
Trees (immutable) - represents one level of directory info (blob IDs; pathnames; metadata; recursively references other subtree objects); a snapshot of the source tree that contains a list of file names each with a reference to a blob or tree object
Commits (immutable) - points to a tree object; links tree objects together into a history; contains the name of the tree object, a timestamp, a log message, and the names of zero or more parent commit objects
- Author
- Committer
- Commit Date
- Log Message
Tags - assigns a human-readable name to an object; a container that contains a reference to another object with metadata
- Annotated Tag (immutable) - creates an object in the object store
- Lightweight Tag (mutable) - a reference to a commit object; private to the repo; not stored in the object store
Packfile?

Git file classification

Tracked - a tracked file is a file that is either in the repo or in the index
Ignored - an ignored file must be explicitly declared as such even though it may remain present in the working directory
Untracked - an untracked file is a file that is neither tracked or ignored
- working directory - (tracked + ignored) = untracked

A commit holds a snapshot.

A snapshot is made from the files in the index.

Hashes #

print(10**48 < 2**160 < 10**49)
print(10**48)
print(2**160)
print(10**49)
print(int(1e12) * int(1e12) * 60 * 60 * 24 * 365 * int(1e12))

# a trillion people each of whom produces
# a trillion new unique blobs per second for
# a trillion years
# is still five orders of magnitude less

True
1000000000000000000000000000000000000000000000000
1461501637330902918203684832716283019655932542976
10000000000000000000000000000000000000000000000000
31536000000000000000000000000000000000000000

Commits #

Git stores a commit object that contains

a pointer to the snapshot of the content that was staged
the author’s name and email
the commit message
pointer(s) to the parent commit
- 0 for initial commit
- 1 for normal commit
- 2 or more for merge commit

Commits

a commit represents a single atomic changeset w.r.t. the previous state: regardless of the number of directories, files, lines, or bytes that change with a commit, either all changes apply or none do.
a commit snapshot represents the state of the total set of modified files and directories–which means it represents a given tree state
a changeset between two snapshots represents a complete transformation from one tree state to another

Changeset

Git also records a mode flag indicating the executability of each file; changes to this flag are also part of the changeset

Absolute Commit Name - references a commit explicitly

the globally unique 40-digit hexadecimal SHA-1 commit object ID - globally unique not just for one repo but for any and all repos

Relative Commit Name (ref, symref) - references a commit implicitly

a ref points to a SHA-1 within the Git object store (it usually refers to a commit object)
a symbolic reference is a name that indirectly points to a Git object
each symref has a full name that begins with refs/; there are three namespaces
- .git/refs/heads/ (local branch names)
  - refs/heads/feature
- .git/refs/remotes/ (remote tracking branch names)
  - refs/remotes/origin/main
- .git/refs/tags (tag names)
internal
- .git/HEAD a pointer to the most recent commit in the currently checked-out branch
- .git/ORIG_HEAD
- .git/FETCH_HEAD
- .git/MERGE_HEAD
- .git/CHERRY_PICK_HEAD

ref^n is the n-th parent of commit ref
ref^ is the same as ref^1
ref^^ is the same as ref~2 and is the first parent of the first parent of commit ref
ref~n is the first [ parent, grandparent, great-grandparent, etc. ] of commit ref
ref~ is the same as ref~1
^ref exclude commit ref

set difference

X..Y the set of commits starting after X up to and including Y; or ^X Y all commits reachable from Y minus all commits up to and including X
..Y is equivalent to HEAD..Y
X.. is equivalent to X..HEAD

set symmetric difference (the set of commits that are reachable from either or but not both)

X...Y = X Y --not $(git merge-base --all X Y)
“show everything in branch X or in branch Y but only back to the point where the two branches diverged”

Example

b..e = ^b e

= e - b = {a, b, c, d, e} - {a, b}

= c d e

                      main
                     /
a <- b <- c <- d <- e
          -    -    -

Example - main at v is merged into feature at b

feature..main = ^feature main

= main - feature = {t, u, v, w, x, y, z} - {a, b, c, d, e, t, u, v}

= w x y z

                              feature
                             /
        a <- b <- c <- d <- e
            /                   main
           /                   /
t <- u <- v <- w <- x <- y <- z
               -    -    -    -

Example - feature is merged into main

feature..main = ^feature main

= main - feature = {a, b, v, w, x, y, z} - {a, b}

= v w x y z

            feature
           /
  <- a <- b
           \             main
            \           /
<- v <- w <- x <- y <- z
   -    -    -    -    -

Example - feature at d is merged into main at z

feature..main = ^feature main

= main - feature = {a, b, c, d, t, u, v, w, x, y, z} - {a, b, c, d, e, t, u, v}

= w x y z

                                  feature
                                 /
        a <- b  <-  c  <-  d <- e
            /               \   main
           /                 \ /
t <- u <- v <- w <- x <- y <- z
               -    -    -    -

Example

dev...main

= dev main $(git merge-base --all dev main)

= dev OR main AND NOT (merge-base --all dev main)

= (dev OR main) - (dev AND main)

main = {a, b, c, d, e, f, g, h, i, u, v, w}

dev = {a, b, c, u, v, w, x, y, z}

= d e f g h i x y z

                                          main
                                         /
a <- b <- c <- d <- e <- f <- g <- h <- i
           \   -    -    -   /-    -    -   dev
            \               /              /
             u  <-  v  <-  w <- x <- y <- z
                                -    -    -

Branches #

Branch

a file that contains the 40-character SHA-1 checksum of the commit it points to
creating a branch is as quick and as simple as writing 41 bytes to a file (40 characters and a newline)

Three kinds of branches

branch on the remote repo (bugfix)
local snapshot of the remote branch (origin/bugfix)
local branch tracking the remote branch (bugfix)

Identify merged branches

list branches that have been merged into a branch
useful for knowing what commits / feature branches have been incorporated
useful for cleanup after merging many feature branches (makes sure nothing is deleted that hasn’t yet been merged in)

Prune (delete all) stale branches

stale branch: a remote-tracking branch that no longer tracks anything because the actual branch in the remote repo has been deleted
when you delete a remote branch, the associated remote-tracking branch is also deleted
when collaborators delete a remote branch, your remote-tracking branch remains: remote-tracking branches have to be manually pruned
git fetch does not automatically delete remote-tracking branches

Tags #

Tags

tags allow marking points in history as important
a tag is named reference to a commit (and so identifies a particular commit in the history)
frequently used to mark software release versions
can mark key features or changes
can mark points for discussion with collaborators
git show v1.1
git log v1.0..v1.1
git diff v1.0..v1.1
git switch v1.0 fatal: a branch is expected, got tag ‘v1.0’
git switch -c branch_v1 v1.0 create a new branch from a preexisting tag
like branches, tags are local unless shared to a remote; git push doesn’t transfer tags by default; tabs must be explicitly transferred
git fetch automatically retrieves shared tags

Tag, annotated

stored as full objects in the Git database
checksummed
contain the tagger name, email, date
have a tagging message
can be signed and verified with GNU Privacy Guard (GPG)

Tag, lightweight: like a branch that doesn’t change (the commit checksum stored in a file, a pointer to a specific commit)

Git stores data as a series of snapshots (not as a series of changesets or differences).

Git move ops: a mechanism based on the similarity of the content between two file versions

Detached state: the files being viewed are not connected to the current version of the code; you are in some part of the history of the repo, so you cannot commit anything in the current branch.

Force Push

reason: the local version is preferable to the remote version (maybe because the remote version is wrong or corrupt)
reason: versions have diverged and merging is undesirable
force pushing can be thought of as “replacing” the remote version with the local version

git push -f
git show
git show origin/main
git fetch
git reset --hard origin/main

Interactive staging

stage changes interactively
allows staging portions of changed files
helps to make smaller, focused commits

Patch mode

allows staging portions of a changed files
hunk: an area where two files differ (may seem arbitrary)
hunks can be staged, skipped, or split into smaller hunks

Split a hunk

a hunk can contain multiple changes (may seem arbitrary)
if we don’t want to stage an entire hunk, we can tell git to try to split a hunk further
this requires one or more unchanged lines between changes

Edit a hunk

useful when a hunk cannot be split automatically
diff-style line prefixes: + (line added), - (line removed), space (line unchanged)
any other line prefixes will cause the edit to the hunk to be rejected

Cherry-picking commits

share code between branches and between repositories
applies the changes from one or more existing commits
each commit targeted will become a new commit on the current branch with the same commit message
conceptually similar to copy-paste
the new commit will have the same changes and message but a different SHA (because the SHA is based on more than just the changes: it includes information about the commit that precedes it)
can cherry-pick commits from any branch including remote-tracking branches
cannot cherry-pick a merge commit because it does not contain the set of changes to apply, it’s connecting a set of commits
can result in conflicts that must be resolved just like merge conflicts
cherry-picking a commit is applying an existing set of changes to the current branch (these changes may conflict with the current state of the branch)

Diff patches

allow us to share changes via files instead of a remote repo
useful when changes are not ready for a public branch
useful when collaborators do not share a remote with us
patches are used during discussion, review, or the approval process
applying a diff patch applies the changes in a diff patch file to the working directory (it makes the changes but does not automatically commit them)
a diff patch only contains the set of changes, not the commit history (like cherry-picking does)

Formatted patches

exports of commits in the Unix mailbox format
useful for email distribution of changes
includes commit messages and some metadata
puts each commit in a separate file by default
applying formatted patches extracts the author, commit message, and changes from a mailbox message and applies them to the current branch as commits
similar to cherry-picking commits: get the same changes and commit messages, but different SHAs (the commit history is transferred)

Rebase commits

take commits from a branch and replay them at another point, most often at the end of another branch (giving the commits a new base or starting points)
useful to integrate recent commits without merging
maintains a cleaner, more linear project history
rebasing during development ensures topic or feature branch commits apply cleanly back to the main branch
if we’re working with collaborators, it forces each one to take responsibility for resolving merge conflicts while they’re developing
some teams require rebasing before a feature branch can be considered for the main branch
the commit message and the metadata is kept, but the SHAs change because the previous commit in the chain has changed (it doesn’t just shift the changes, but reapplies them in order)
rebasing commits may conflit with existing code
when a conflict occurs, git pauses the rebase before each conflicting commit (similar to resolving merge and cherry-pick conflicts)

merging vs rebasing

two ways to incorporate changes from one branch into another branch
similar ends but different means
side effects!
merging: adds a merge commit; nondestructive; complete record of what happened and when; easy to undo; logs can become cluttered and nonlinear
rebasing: no additional merge commits (cleaner); destructive (SHA changes, commits are rewritten, rewriting history); no longer a complete record of what happened and when; tricky to undo; logs are cleaner and more linear
golden rule of rebasing: thou shalt not rebase a public branch (rebasing is destructive; do not rebase branches that others use); rebase abandons existing shared commits and creates new similar commits instead; collaborators would see project history vanish
merge to allow commits to stand out or to be clearly grouped
merge to bring large topic branches back into main
rebase to add minor commits in main to an in-progress topic branch: keeps it current and keeps the history cleaner
rebase to move commits from one branch to another
merge anytime the topic branch is already public and being used by others (the golden rule of rebasing)

interactive rebasing

modify commits as they are being replayed
instead of rebasing the commits immediately, opens the git-rebase-todo file for editing (can reorder, skip commits, edit commit contents)
pick (use) commit, drop (don’t use) commit, reword commit message, edit contents of change set, squash, fixup, exec (runs from command line shell)
squashing commits folds two or more commits into one
squash: combine changesets, edit and concatenate commit messages
fixup: combine changesets, discards commit messages and keeps the prior message
uses the first author in the commit series

pull rebase

pull usually fetches from a remote repo to remote-tracking branch and merges with local code
pull rebase fetches from the remote and then rebases the current branch to tip of remote-tracking branch instead of merging
pull rebase keeps history cleaner by reducing merge commits
only rebase on local commits not shared to a remote

log options

log is the primary interface to git: the purpose of git is to track changes over time and the log lists those changes
many options: sorting, filtering, output formatting

blame

browse annotated version of files
determine who changed which lines in a file and why
useful for probing the history behind a file’s contents
useful for identifying which commit introduced a bug

bisect

find the commit that introduced a bug or regression: when did things go wrong?
useful when there’s a problem in the code and we know that there was a time in the past when the problem didn’t exist
tell git the last time we know when the code was working and the first time we know it’s not working (i.e., mark the last good revision and the first bad revision)
bisect resets the code to the midpoint between the good and bad versions and lets you test it: mark as good or bad version, and repeat

Raspberry Pi

mkdir -p /home/pi/git/test.git
cd /home/pi/git/test.git
git init --bare

Local

git remote set-url origin ssh://pi@10.0.0.13:2222/home/pi/git/test.git