Git And GitHub Workflow

Goal: clone a private repository, work on a branch, verify/stage a focused change, write a Conventional Commit, and open a reviewable pull request.

Prerequisites: your GitHub account can open the relevant repository in a browser and has accepted any organization invitation.

Execution context: Git commands run on your local computer in Windows PowerShell/Git Bash, macOS zsh, or Linux Bash. The same commands can run on a remote development machine only when the project intentionally lives there.

Required practice: First Safe Pull Request.

Table of Contents#

1. Why Git?
2. Semantic Commits (SemVer-friendly)
3. Prerequisites
4. Create / Upgrade Your GitHub Account
5. Install Git
6. Set Up GitHub Authentication
7. Configure Git Identity
8. Connect VS Code to GitHub
   • Option A – OAuth (1-click sign-in)
   • Option B – Personal-Access-Token (PAT)
9. Everyday Workflow
10. Best Practices
11. Cheat-Sheet
12. Collaboration Example — "wing + fuselage"

Why Git?#

• Time-machine: Revert any file or the whole project to a previous state.
• Collaboration: Multiple people work in parallel with branches.
• Traceability: Commit history shows who changed what and why.

Semantic Commits (SemVer-friendly)#

Use Conventional Commits from day one so release tagging and versioning can be automated later.

Important distinction:

• Semantic Versioning (SemVer) is for release numbers (MAJOR.MINOR.PATCH).
• Conventional Commits is for commit message format.
• Conventional Commit history can be used to compute SemVer bumps automatically.

Commit message format:

type(scope): short summary

What scope means (very important for beginners):

• scope = the main area you changed (module, folder, or feature).
• Keep it short: usually 1 word, sometimes 2 (first_steps, git_workflow, training).
• Use lowercase and no spaces (use _ if needed).
• Pick the dominant change only. If unsure, use general.

Recommended type values:

• feat: new functionality
• fix: bug fix
• docs: documentation change
• refactor: code restructure without behavior change
• test: tests added/updated
• chore: tooling/maintenance

Examples:

feat(data): add CSV loader for tensile tests
fix(training): handle empty validation split
docs(onboarding): clarify Obsidian vault root
chore(general): update dev dependencies

SemVer mapping (used when creating releases):

• fix: -> PATCH bump
• feat: -> MINOR bump
• feat!: or BREAKING CHANGE: footer -> MAJOR bump

Prerequisites#

Run git --version in a terminal to verify install.

Create / Upgrade Your GitHub Account#

1. Sign up at https://github.com/ or sign in.
2. Enable MFA and store recovery codes in an approved password manager.
3. Accept the IDEAL Lab organization/repository invitation.
4. Confirm you can open the private repository in the browser before cloning.

For the recommended no-cost AI-agent route, apply for or confirm GitHub Education after the browser-access check:

5. Open https://github.com/settings/education/benefits.
6. Add and verify your ETH email if GitHub requests it.
7. Complete GitHub's current student-verification process.
8. After approval, activate GitHub Copilot Student from the benefits page.

GitHub Education is not required to read or clone an IDEAL Lab repository, but it is required for the no-cost Copilot Student benefit. Verification can take time. Continue the manual Git workflow while waiting; do not purchase Copilot or another AI plan merely to complete onboarding. Follow the canonical Copilot Student setup only after the manual FirstSteps change.

Install Git#

Windows#

1. Run the Git for Windows installer.
2. Keep defaults — especially “Git from the command line and 3rd-party software”.
3. Open Git Bash or PowerShell → git --version.

macOS / Linux#

• macOS: Just run git --version - macOS will automatically prompt you to install Xcode Command Line Tools (includes Git)
• Ubuntu: sudo apt update && sudo apt install git.
• Fedora: sudo dnf install git.

Set Up GitHub Authentication#

Goal: authenticate without teaching unsafe token habits.

Recommended order:

1. VS Code OAuth for beginners working mostly inside VS Code.
2. GitHub CLI for terminal users: gh auth login.
3. SSH keys for repeated development and remote machines.
4. Fine-grained PATs only when OAuth, CLI, or SSH are not suitable.

Option A: VS Code OAuth#

1. VS Code → Accounts icon → Sign in with GitHub.
2. Browser opens → approve access.
3. Clone private repositories from VS Code or the terminal.

This is the safest beginner default because VS Code stores credentials in the operating-system credential store.

Option B: GitHub CLI#

Install GitHub CLI from https://cli.github.com/ and run:

gh auth login
gh auth status

Choose GitHub.com, HTTPS or SSH, and follow the browser login. This avoids copying tokens into terminals, chats, or notes.

Option C: SSH Keys#

Use SSH for repeated Git operations when it fits the machine and network. Follow GitHub's current SSH key procedure, which includes checking for existing keys before generating one. Add only the public key to GitHub. Never share, upload, or commit the private key.

Do not copy a laptop private key to Euler. Authentication from Euler requires a separate approved choice such as GitHub CLI on Euler or deliberately configured agent forwarding; ask the project owner when unsure.

Option D: Fine-Grained PATs#

Use a fine-grained personal access token only when required by a specific tool. Make it short-lived, repository-limited, and permission-limited. Paste it only into the tool's credential prompt, never into an AI chat or Markdown file.

Avoid broad classic PATs unless a platform limitation truly requires one.

Configure Git Identity#

git config --global user.name  "Your Real Name"
git config --global user.email "your-verified-email@example.org"
git config --global core.editor "code --wait"   # VS Code as default editor

Connect VS Code to GitHub#

VS Code ships with the GitHub auth extension built-in.

Option A – OAuth (1-click sign-in)#

1. VS Code → click the Accounts icon (bottom-left).
2. Choose Sign in with GitHub.
3. Browser opens → approve access → VS Code refreshes.
4. Token saved in OS keychain / credential manager.

Option B – Personal Access Token (PAT)#

1. GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens.
2. Select only the repository or organization you need.
3. Grant the minimum required permissions, usually Contents: read/write and Metadata: read for Git operations.
4. Set an expiration date and copy the token (shown once!).
5. VS Code → Accounts icon → Sign in with GitHub → Paste authentication token.

Use PATs only if OAuth, GitHub CLI, or SSH are blocked on shared / VM environments. Never paste a PAT into an AI chat, notebook, Markdown file, or screenshot.

Everyday Workflow#

Clone a Repository#

1. Copy repo URL from GitHub (https://github.com/org/project.git).
2. VS Code → ⌘/Ctrl + ⇧ + P → Git: Clone → paste URL.
3. Choose local folder → open workspace when prompted.

Create & Switch Branches#

• Status bar (bottom-left) shows current branch → click → Create new branch… (e.g. feature/my-analysis).
• Pick any branch in the list to switch.

Stage → Commit → Push#

1. Change files → open Source Control (sidebar).
2. + beside file or Stage All.
3. Write a Conventional Commit message (for example fix(parser): handle empty rows) → Commit (✓).
4. Click Push/Synchronize (↥) in the status bar.

Safer command-line equivalent while learning. Replace the two example paths with files shown by your own git status:

git status --short
git diff
git add -- src/module.py tests/test_module.py
git diff --cached
git commit -m "type(scope): short summary"
git push -u origin HEAD

AI Prompt for Commit Messages#

If you use Copilot/LLM tools, prompt like this:

From my staged git diff, write exactly ONE Conventional Commit message.
Rules: use type(scope): summary, where type is feat|fix|docs|refactor|test|chore;
scope must be the main changed area (module/folder/feature), lowercase, no spaces,
use general if unclear; imperative mood; max 72 chars; no trailing period;
output only the message.

Then paste the result into:

git commit -m "fix(scope): describe the verified change"

Before committing, run git diff --staged and check that the message matches the actual change. Do not let an agent invent scope or tests that did not happen.

Pull / Sync Changes#

• Click Pull (↧) or ⌘/Ctrl + ⇧ + P → Git: Pull.
• VS Code auto-merges or prompts on conflicts.

Open a Pull-Request#

1. After pushing branch, VS Code shows Create Pull Request.
2. Fill title / description → target main.
3. Supervisor reviews & merges.

AI-Assisted PR Summary and Review#

Use agents to make review easier, not to bypass review.

Good prompt:

From my branch diff against main, draft a PR summary.
Include: what changed, why, interfaces or users affected, risk areas, and
verification I actually ran.
Do not invent tests or claim checks passed unless they appear in my terminal output.

Good review prompt:

Review this diff for bugs, missing tests, secret leaks, and over-broad changes.
Prioritize correctness and safety over style.
Return findings with file/line references where possible.

Human checklist before merge:

• You understand every file changed.
• You identified affected interfaces and downstream users, or stated None.
• You requested review from the owner of an affected interface when applicable.
• Generated code has tests or a smoke check.
• No secrets, datasets, checkpoints, or local config were added.
• The PR description lists real verification output.

Best Practices#

• Branch per task: feature/..., bugfix/..., doc/....
• Atomic commits: one logical change each.
• Use Conventional Commits always: type(scope): short summary.
• .gitignore: exclude large data & secrets.
• Fetch and inspect shared changes: synchronize deliberately before merge.
• Never commit directly to main: always PR.
• Review AI diffs carefully: the model can be fluent and wrong.
• Give agents constraints: files to inspect, files not to touch, checks to run.
• Never paste secrets into prompts: use OAuth, SSH, gh auth login, or credential prompts.

Cheat-Sheet#

Collaboration Example — “wing + fuselage”#

🧠 Concept#

• You develop on branch wing
• Colleague develops on fuselage
• Integration branch integrate-wing-fuselage is where both sets of work meet for testing.
• Git handles merging — no manual file copies.

🚀 Step-by-Step in VS Code#

💡 Extra Tips#

• Pull first, merge later — sync integration branch before merging feature branches.
• Use VS Code conflict helpers: Accept Current, Accept Incoming, Accept Both.
• Open draft PRs early to share progress and trigger CI.
• Delete branches after they’re merged to keep the repo tidy.

Expected Result And Verification#

• git status --short --branch names a task branch, not main.
• git diff --cached contains only intended changes.
• The commit uses type(scope): summary and matches the diff.
• The PR lists only verification actually performed.
• No credential, data, checkpoint, local environment, or generated result is present.

Common Failures And Safe Recovery#

• Private clone fails: confirm browser access and authentication; do not put a token in the URL.
• Wrong file staged: run git restore --staged <path> to keep the local edit but remove it from the staged diff.
• Unwanted unstaged agent edit: inspect git diff, then restore only the specific unwanted path. Do not use git reset --hard.
• Secret committed: revoke it immediately, notify the repository owner, and coordinate any history cleanup.
• Push rejected: fetch and inspect the remote branch; do not force-push a shared branch without explicit coordination.

Ask For Help When#

Recovery would rewrite shared history, authentication requires a token you do not understand, a secret entered history, or merge conflicts include unfamiliar project changes.

Verified: 2026-08-26. Review by: 2026-11-26. Owner: lab software maintainer.