Git Principles & Common Commands¶

Blackcairn Infrastructure Guide¶

This document explains the core principles of Git and the common commands used when maintaining and expanding the Blackcairn infrastructure repositories.

It is intended as a practical reference rather than a full Git tutorial.

1. Core Git Concepts¶

Repository (Repo)¶

A repository is a version-controlled project.
For Blackcairn, repositories hold: - Docker Compose stacks - Scripts - Configuration files - Documentation

Example: - blackcairn-infra is the source of truth for infrastructure.

Working Tree¶

Your local files on disk.
Changes here are not tracked until explicitly added.

Staging Area (Index)¶

An intermediate step where you choose what will be committed.

Think of it as a “pre-flight checklist” before committing.

Commit¶

A snapshot of staged changes with a message explaining why the change exists.

Commits should be: - Small - Purposeful - Descriptive

Branch¶

A branch is a line of development.

Blackcairn convention: - main = stable, deployable state - Feature branches are optional but encouraged for larger changes

Remote¶

A remote is a shared copy of the repository, usually on GitHub.

For Blackcairn: - origin = GitHub repository

2. Blackcairn Git Philosophy¶

GitHub is the source of truth
Infrastructure is defined as code
History should be clean and readable
Prefer rebasing over merging for day-to-day pulls
Changes should be reviewable via git log

3. Repository Setup & Status¶

Check repository status¶

git status

Shows: - Modified files - Staged files - Untracked files

View commit history¶

git log --oneline --decorate --graph

Useful for: - Understanding change flow - Debugging regressions

4. Making Changes¶

See what changed¶

git diff

Stage files¶

git add file.txt
git add .

Commit changes¶

git commit -m "Add Portainer stack for monitoring"

Good commit messages - Start with a verb - Explain intent, not mechanics

5. Syncing with GitHub¶

Fetch remote changes¶

git fetch

Downloads changes without modifying local files.

Pull (recommended: rebase)¶

git pull

With rebase configured, this: - Fetches origin/main - Replays your local commits on top

Push local commits¶

git push

Uploads commits to GitHub.

6. Divergent Branches¶

If Git reports divergent branches, it means: - Local and remote branches both moved

Recommended Blackcairn fix:

git config pull.rebase true

This keeps history linear and predictable.

7. Branching (Optional but Useful)¶

Create a branch¶

git checkout -b feature/homepage-refresh

Switch branches¶

git checkout main

Delete a local branch¶

git branch -d feature/homepage-refresh

8. Undoing Mistakes (Safely)¶

Unstage a file¶

git restore --staged file.txt

Discard local changes¶

git restore file.txt

Amend last commit¶

git commit --amend

Useful for: - Fixing commit messages - Adding forgotten files

9. Git + Infrastructure Workflow (Blackcairn)¶

Typical flow: 1. Edit stack / config / script 2. git diff 3. git add 4. git commit 5. git pull 6. git push 7. Deploy via Portainer / automation

This ensures: - Traceability - Repeatability - Recoverability

10. Golden Rules¶

Never edit live containers without committing changes
If it’s running, it should exist in Git
Commit before deploying
Small commits beat clever commits
Git history is documentation

11. Quick Command Cheat Sheet¶

git status
git diff
git add .
git commit -m "message"
git pull
git push
git log --oneline --graph

Summary¶

Git is the backbone of Blackcairn: - It documents intent - Enables safe change - Supports GitOps-style infrastructure

Treat the repository as the map of the keep, not just a toolbox.