JCC Git Workflow

Step 01 — one time only

git clone

First time only. Downloads the JCC repo from GitHub to your Mac.

# Brings repo to ~/Documents/repos/jcc
git clone https://aabad420:$(op item get
  "GitHub Personal Access Token - JCC"
  --vault "Personal" --reveal --fields password)
  @github.com/aabad420/jcc.git

clone

←

GitHub — source of truth

main branch lives here

Private repo. Nobody touches this directly. All changes go through PRs.

# github.com/aabad420/jcc
# main branch — source of truth
# private repo ✓ protected ✓

↓

Step 02 — every single time, no exceptions

cd into jcc → git pull

Muscle memory sequence. The moment you open Terminal and need to work on jcc — cd in, git pull immediately. Don't skip this. Skipping it = stale code = merge conflicts later.

# Step 1 — navigate into jcc
cd ~/Documents/repos/jcc

# Step 2 — immediately pull before anything else
git pull

# That's it. You're synced. Ready to branch.
# git status optional — pull already shows what changed

git pull

←

GitHub remote

Latest main comes down

git pull talks to GitHub and syncs any new commits to your local main. Both are now in sync — safe to branch.

# GitHub jcc main → your local jcc main
# Both in sync ✓
# Safe to branch now ✓

↓

Step 03 — local only

Create a Branch

Your branch is a copy of local main at this exact moment. Local main stays completely frozen from here — it will NOT move until Step 09 when you git pull again.

# Already inside jcc from Step 02 — no need to cd again
# Create + switch to new branch off fresh main
git checkout -b feature/jcc-add-network-configs

# Confirm which branch you're on
git branch

local only

↓

Step 04 — local only, on your branch only

Do Your Work

All commits happen on your feature branch only. git commit does NOT touch local main — it doesn't even know this is happening. Local main stays frozen.

# Open jcc repo in VS Code
code ~/Documents/repos/jcc

# Check what changed on your branch (local only)
git status

# Stage everything on your branch
git add .

# Snapshot saved on feature branch only
# local main is NOT touched by this command
git commit -m "jcc: add network config files for home lab"

local only

↓

State right now → 🔒 local main — frozen ✏️ local branch — active 🔒 GitHub main — frozen ⬆️ GitHub branch — not pushed yet

↓

Step 05 — sends to GitHub

Push Branch to GitHub

First push uses -u to link the branch. After that just git push.

# First push for this branch — links it to GitHub
git push -u origin feature/jcc-add-network-configs

# Every push after that
git push

git push

→

GitHub remote

Branch appears on GitHub

Your feature branch is now on GitHub. No PR yet — just the branch sitting there ready.

# github.com/aabad420/jcc/tree/
# feature/jcc-add-network-configs
# Branch is up. Ready to open a PR.

↓

Step 06 — optional CLI method

Open PR via GitHub CLI (gh)

Install gh once via Homebrew. Then open PRs without leaving Terminal. Power user move — stick with GUI first until the flow is automatic.

# One time install
brew install gh
gh auth login

# Open a PR from current branch
gh pr create \
  --title "Add network configs to jcc" \
  --body "Added firewall and network config files"

# Open as draft (still WIP)
gh pr create --draft \
  --title "Add network configs to jcc"

# Check PR status from Terminal
gh pr status
gh pr list

open pr

→

Step 06 — GitHub UI method

Open PR via GitHub.com

This is what devs mean by "I have a PR ready" or "PR in draft." Most common method — do this first until gh CLI feels natural.

# In the GitHub UI:
# 1. Go to github.com/aabad420/jcc
# 2. Click "Compare & pull request"
# 3. Title: "Add network configs to jcc"
# 4. Draft = still WIP
# 5. Ready for Review = send it
# 6. Submit the PR

↓

Step 07 — if changes requested

Address Review Feedback

Reviewer asks for changes? Fix locally, commit, push. PR auto-updates on GitHub.

# Make your fixes in jcc, then:
git add .
git commit -m "jcc: fix PR feedback - update firewall rules"
git push

# PR at github.com/aabad420/jcc auto-updates

git push

→

Step 07 — GitHub UI

PR Review

Teammate reviews. Approves, comments, or requests changes. Quality gate before main.

# Reviewer options in GitHub UI:
# ✅ Approve
# 💬 Comment
# 🔄 Request changes

↓

Step 08 — CLI method (gh)

Merge PR via Terminal

If you opened the PR with gh, you can merge it from Terminal too. Keeps you in the flow without switching to the browser.

# Check PR is approved and ready
gh pr status

# Merge the PR from Terminal
gh pr merge --merge \
--subject "Add network configs to jcc"

# feature/jcc-add-network-configs → main ✓

merge

→

Step 08 — go to prod moment

Merge PR via GitHub.com

PR approved. Click Merge on GitHub. Branch folds into main. Equivalent of promoting to prod.

# In GitHub UI at github.com/aabad420/jcc:
# Click "Merge pull request"
# Confirm the merge
# feature/jcc-add-network-configs → main ✓

↓

Step 09 — the ONLY moment local main moves forward

Sync Local Main & Clean Up

This git pull is the one and only time local main gets updated. It was frozen since Step 02 — now it finally syncs forward with the merged changes from GitHub.

# Get back to main
git checkout main

# Sync GitHub jcc main → local jcc main
git pull

# Delete branch locally
git branch -d feature/jcc-add-network-configs

# Delete branch on GitHub
git push origin --delete feature/jcc-add-network-configs

# Starting next feature? Go back to Step 02.
# cd ~/Documents/repos/jcc → git pull → branch

git pull

←

GitHub remote

Main is up to date

GitHub main has your merged changes. New source of truth. Start the cycle again for the next feature.

# main branch updated ✓
# feature branch deleted ✓
# Ready for next cycle 🔁

Command	Talks to GitHub?	What It Does
git status	❌ No	Shows local changes only — your Mac, not GitHub
git add .	❌ No	Stages all changed files locally
git commit -m "..."	❌ No	Saves a local snapshot — nothing goes to GitHub yet
git branch	❌ No	Lists your local branches
git checkout -b <name>	❌ No	Creates and switches to a new local branch
git log --oneline	❌ No	Shows local commit history in a clean list
git pull	✅ Yes	Grabs latest changes from GitHub → syncs your local
git push	✅ Yes	Sends your local commits up to GitHub
git clone <url>	✅ Yes	First time only — downloads a GitHub repo to your Mac

⚙️ Git version control

git --versionCheck Git is installed and see the version

git config --global user.nameSet your global Git username

git config --global user.emailSet your global Git email

git config --global --listVerify all global Git config settings

git config pull.rebase falseSet pull strategy to merge not rebase

git initInitialize a brand new local Git repo

git clone <url>Download a GitHub repo to your Mac — one time only

git statusCheck local changes — does NOT talk to GitHub

git add <file>Stage a specific file for commit

git add .Stage all changed files at once

git commit -m "message"Save a local snapshot — does NOT touch main or GitHub

git pushSend local commits up to GitHub

git push -u origin mainFirst push — links local branch to GitHub remote

git pullSync GitHub main → local. Only way local main moves forward.

git pull origin main --allow-unrelated-historiesForce pull when repos have different starting points

git branch -m mainRename current branch to main

git remote add origin <url>Link local repo to a GitHub remote for the first time

git remote set-url origin <url>Update the GitHub remote URL on an existing repo

💻 Terminal Basics mac cli

pwdPrint working directory — shows where you are

lsList files and folders in current directory

ls -laList all files including hidden ones with details

cdNavigate to home directory (~)

cd <folder>Navigate into a specific folder

cd ..Go up one folder level

mkdir -p <folder>Create a folder and parent folders if needed

cat <file>Read and display contents of a file

nano <file>Open a file in the Terminal text editor

echo "text" > file.mdCreate a file and write text into it

brew --versionConfirm Homebrew is installed

wget <url>Download a file from the internet via Terminal

🔐 1Password CLI credential management

op --versionConfirm 1Password CLI is installed

eval Sign in — required before any op commands

op account addAdd a 1Password account to the CLI

op vault listList all vaults in your 1Password account

op item createCreate a new item in 1Password from Terminal

op item get "<name>" --vault "<vault>" --reveal --fields passwordRetrieve a secret securely — injects PAT into git clone

🔑 SSH remote access

ssh root@<IP>SSH directly into a remote server as root

ssh -J jumphost root@<IP>SSH through a jump host to reach a private server

🏠 Home Assistant home automation

ha core checkValidate Home Assistant config before restarting

ha core restartRestart the Home Assistant core service

ha core logsView live Home Assistant logs for troubleshooting

ha supervisor infoShow supervisor status and version info

🌐 Networking diagnostics

ping <IP>Test connectivity to an IP address or hostname

ipconfig getifaddr en0Get your Mac local IP address on the network

GitHub CLI (gh) Commands — In the Order You Use Them install once · use every session

Step 01 — one time brew install gh

Install GitHub CLI via Homebrew One time only. Gives you the gh command in Terminal so you never have to open the browser for PR tasks.

Step 02 — one time gh auth login

Authenticate gh with your GitHub account One time setup. Links the gh CLI to your aabad420 GitHub account so it can act on your behalf.

Step 03 — after git push gh pr create --title "..." --body "..."

Open a Pull Request from Terminal Run after pushing your branch. Skip the browser entirely — PR is created on GitHub instantly.

Step 03 — optional gh pr create --draft --title "..."

Open a PR in Draft mode Use when you are still working on it and not ready for review. Signals WIP to teammates.

Step 04 — check status gh pr status

See status of your open PRs Check if your PR is approved, has review comments, or is still pending. No browser needed.

Step 04 — view all gh pr list

List all open PRs in the repo See every open PR at a glance — useful when managing multiple branches or reviewing others work.

Step 05 — once approved gh pr merge --merge --subject "..."

Merge an approved PR from Terminal PR is approved and ready. Merge it without touching the browser. Feature branch folds into main.

Learning Notes — Day 0 vs Day 1

📓 What Was Different — Direct Push vs Full PR Workflow May 16 → May 17, 2026

❌ Day 0 — Learning Mode (Direct to Main)

            # No branch — worked directly on main

            git add .

            git commit -m "Initial commit"

            git push -u origin main

            # Went straight to main. No PR.

Fine for learning the basics — but not how professionals work. No branch, no review, no audit trail.

✅ Day 1 — Professional Mode (Full PR Workflow)

            git pull

            git checkout -b feature/jcc-...

            git add .

            git commit -m "..."

            git push -u origin feature/jcc-...

            # Open PR → Review → Merge

            git checkout main

            git pull

            git branch -d feature/jcc-...

            git push origin --delete feature/jcc-...

Branch → commit → push branch → PR → merge → sync → cleanup. The full professional loop.

What	Day 0 — Direct Push	Day 1 — PR Workflow
Worked directly on	main ❌	feature branch ✅
Pull Request created	No ❌	Yes ✅
Code review possible	No ❌	Yes ✅
Audit trail	No ❌	Yes ✅
Main branch protected	No ❌	Yes ✅
Netlify auto-deploy triggered	No ❌	Yes ✅

🔍 Reading a Pull Request — What Each Tab Means GitHub UI

Conversation Tab

The Timeline

Read top to bottom — chronological order. PR opened → commits → bot reactions → review comments → merge → branch deleted. Full audit trail of everything that happened.

Commits Tab

Every Commit in the PR

Lists all commits that are part of this PR. Each has a hash, message, and author. Shows the history of work done on the branch.

Files Changed Tab

The Diff

Shows exactly what changed. Red lines = removed. Green lines = added. White lines = unchanged context. Reviewers read this — not the whole file — just what changed.

Checks Tab

Automated Tests & Deploys

Shows results of any automated checks — Netlify deploy previews, CI/CD pipelines, tests. Your Netlify bot showed up here automatically when the PR was opened.

Merge Options

3 Ways to Merge

Merge pull request = keeps all commits. Squash and merge = combines all commits into one clean commit. Rebase and merge = replays commits on top of main. Most teams use Squash.

Delete Branch Button

Same as git push --delete

After merging GitHub shows a Delete branch button. One click does what two Terminal commands do — deletes the branch both locally on GitHub and remotely.

Git & GitHub Workflow