Git reference¶

Terms and commands used when working with the CVDLink repositories. Intended for readers who use Git occasionally and want a reminder rather than a tutorial.

Core concepts¶

Repository. A project together with its complete history. The history is held in a hidden .git directory at the top of the project; the files beside it are the working copy you edit.

Working copy. The files as they currently exist on disk. Changes here belong to nobody until they are committed.

Commit. A recorded snapshot of the project at one moment, with a message explaining the change, an author and a timestamp. Commits are permanent and form the history.

Branch. A named line of development. The default branch in these repositories is main. Work that is not ready to be seen by others belongs on its own branch until it is merged.

Remote. A copy of the repository held elsewhere, usually on the GitLab server. The default remote is named origin.

Clone. A local copy of a remote repository, including its history and a link back to the remote.

Staging area. The set of changes marked to go into the next commit. A file can be edited without being staged, and staged without being committed.

HEAD. The commit currently checked out, normally the newest commit on the current branch.

The sequence of a change¶

A change passes through four states. Each command moves it to the next.

State	Where it is	Command to advance
Edited	Working copy only	`git add`
Staged	Marked for the next commit	`git commit`
Committed	In local history	`git push`
Pushed	On the server, visible to others	—

A change is only safe from loss once it has been pushed.

Everyday commands¶

Seeing what has changed¶

git status

Lists modified, staged and untracked files. The first command to run when unsure of the current state.

git diff

Shows the exact lines changed but not yet staged. git diff --staged shows what is staged and about to be committed.

Recording a change¶

git add <file>
git add -A

Stages a particular file, or every change including deletions.

git commit -m "Short description"

Records the staged changes. git commit -am "..." stages and commits modified files in one step, but does not include new files.

git push

Sends local commits to the server.

git pull

Fetches commits from the server and merges them into the current branch. Run this before starting work, so that changes are made on top of what others have done.

Looking at history¶

git log --oneline -10

The last ten commits, one line each.

git log --oneline --decorate

Also shows where branches point. A line marked origin/main is the newest commit the server has; anything above it has not been pushed.

git show <commit>

The full content of one commit.

Branches¶

git branch                      # list branches
git switch -c <name>            # create a branch and move to it
git switch main                 # return to the main branch
git merge <name>                # bring a branch into the current one

A branch is appropriate when a change will take more than one sitting, or when it should be reviewed before others depend on it. Small corrections to the documentation are usually committed to main directly.

Undoing¶

Judgement is needed here: some of these discard work permanently.

git restore <file>

Discards changes to a file that have not been staged. The work is not recoverable.

git restore --staged <file>

Removes a file from the staging area, keeping the edits.

git commit --amend

Replaces the previous commit. Use it to correct a message or add a forgotten file, but only before pushing: amending a pushed commit rewrites history that others may already have.

git revert <commit>

Creates a new commit that undoes an earlier one. This is the safe way to reverse a change that has been pushed, because it adds to the history rather than rewriting it.

git reset --hard <commit>

Moves the branch back and discards everything after it, including changes in the working copy. Destructive, and the usual cause of lost work. Prefer git revert.

Reading the status output¶

Symbol	Meaning
`M`	Modified
`A`	Added, staged for the next commit
`D`	Deleted
`??`	Untracked; Git is not following this file
`ahead 2`	Two commits recorded locally but not yet pushed
`behind 3`	The server has three commits not yet pulled

Files Git ignores¶

.gitignore lists paths Git should not track, such as build output and local virtual environments. In the documentation repository it excludes site/, which MkDocs regenerates on every build, and .venv/.

.gitattributes controls how file contents are handled. The documentation repository uses it to store text files with Unix line endings, so that shell scripts written on Windows still run on the server.

Commit messages¶

A message is read by people deciding whether a commit is relevant to a problem they are investigating, often long after it was written.

Write a short first line stating what the change does, in the imperative: Correct the ETL port rather than Corrected the ETL port or port fix. If more explanation is needed, leave a blank line and write plain prose saying why the change was made. What changed is visible in the diff; why it changed is not.

Situations you may meet¶

"Your branch is ahead of origin/main by 1 commit." The commit exists only on this machine. Run git push.

A push is rejected as non-fast-forward. The server has commits you do not. Run git pull, resolve any conflict, then push again.

A merge conflict. Two people changed the same lines. Git marks the competing versions in the file between <<<<<<< and >>>>>>>. Edit the file so it reads correctly, remove the markers, then git add the file and commit.

A file was committed that should not have been. Add it to .gitignore, then git rm --cached <file> to stop tracking it while keeping it on disk. If it contained a password, treat that password as compromised and change it: the value remains in the history.