Git Commands for Documentation

Overview

The https://obs-ops.lsst.io/v/ workflow requires many git commands (push, merge, rebase, etc.) to move a document from Confluence to Github. This document is designed to provide clarity as to what each git command does with respect to the documentation workflow. Included here are a list of the most important git commands used when migrating documents to obs-ops as well as simple visual representations as to what the common commands with respect with respect to an entire git project (working directory, local repository, remote repository, etc.).

Fig 1: Visual of the Common Git Workflow for Documentation

Getting Started

Configuring user information, initializing and cloning repositories (Fig 1).

Git Command	Description
git init	Initialize an existing directory as a Git repository.
git remote	See which remote servers you have configured to your working directory. Note To verify which URL is currently set: git remote -v To set an existing remote repository <name> to a new URL: git remote set-url <name> <url>
git clone <url>	Retrieve an entire repository from a hosted location via URL.

Managing Branches

Isolating work in branches, changing context, and integrating changes (Fig 1).

Git Command	Description
git branch	Lists your available branches. Note The \(*\) symbol will appear next to the currently active branch.
git branch <name>	Creates a new branch at the current commit.
git checkout <branch>	Switch to another branch and check it out into your working directory.

Staging & Committing

Working with snapshots and the Git staging area (Fig 1).

Git Command	Description
git status	Show modified files in working directory, staged for your next commit.
git add <file>	Add a file as it looks now to your next commit (stage). Note To add all files at once as staged: git add -A
git reset <file>	Un-stage a file while retaining the changes in working directory.
git diff	Show differences of what files are changed but not staged. Note To show differences of what files are staged but not committed: git diff --staged
git commit -m “<message>”	Commit your staged content as a new commit snapshot. Warning Commit messages should be short yet dense with information.
git log	Show all commits in the current branch’s history.

Updating Repositories

Retrieving updates from another repository and updating local repos (Fig 1).

Git Command	Description
git remote show <repo>	Displays information (e.g., remote branches) about the remote repository.
git fetch --all	Fetch down all the branches from that Git remote.
git merge <branch>	Merge a remote branch into your current branch to bring it up to date. Note To safely bring a branch up to date and preserve history: git merge <branch> --no-ff
git push <remote> <branch>	Transmit local <branch> commits to the <remote> repository. Note First push (sets up remote): git push --set-upstream <remote> <branch> Consecutive pushes (on branch): git push If a normal push does not update the remote repository, one can safely push with force: git push --force-with-lease
git pull <remote>	Fetch and merge any commits from the tracking remote branch to the local branch.

Fig 2: Visual of Rebasing Branches in a Git Project

Amending History of Branches & Repositories

Rewriting branches, updating commits and clearing history (Fig 2).

Git Command	Description
git rebase <branch>	Apply any commits of current branch ahead of specified <branch>. Note Make sure you are on the branch you want to rebase before applying this command. Typically the commands will be: 1. git checkout <branch> 2. git rebase origin/main
git rebase -i <base>	Interactively rebase current branch onto. Launches editor to enter commands for how each commit will be transferred to the new base. Note A common <base> to use is HEAD~n where n specifies the number of commits to update interactively.
git reset --hard <commit>	Clear staging area, rewrite working tree from specified commit. Warning This command is useful if branches accidentally merged incorrectly and the local repository needs to be reset. Keep in mind that this will undo any previous work in the repository.