Brainforge Knowledge

00-how-to-use-github

6 min read

How to Use GitHub (Setup and Walkthrough)

GitHub is the shared online binder where Brainforge stores files so we can work together without overwriting each other.

We will use GitHub Desktop for Git actions (clone / fetch / pull / commit / push / merge) and Cursor to edit files.

This guide assumes:

  • You have a GitHub login
  • You have Cursor installed
  • You will connect using HTTPS (standard with GitHub Desktop sign-in)

No coding knowledge required.

What You Need to Know (3 Ideas)

1) Repo = a shared folder

Examples:

  • brainforge-platform/ (contains standards/ and knowledge/)
  • client-eden/
  • client-ABC/

2) Commit = save a snapshot + write a note

Examples:

  • add first SOW draft
  • update meeting notes
  • fix formatting in README

3) Push = upload your commits to GitHub

Until you push, your changes only exist on your computer.

PART 1 — ONE-TIME SETUP (PER COMPUTER)

1) Install GitHub Desktop

  1. Download and install GitHub Desktop.
  2. Open GitHub Desktop.
  1. In GitHub Desktop: File → Options (Windows) or GitHub Desktop → Settings (Mac)
  2. Go to Accounts
  3. Click Sign In and complete the browser login

This avoids manual passwords and makes HTTPS easy.

3) Set your default editor to Cursor

This makes GitHub Desktop open repos directly in Cursor.

In GitHub Desktop

  1. Open Options/Settings
  2. Go to Integrations
  3. Under External Editor, select Cursor if it appears

If Cursor doesn’t appear in the list

  • Choose Visual Studio Code (Cursor is VS Code-based; this often works), OR
  • Choose Other… and select the Cursor app:
    • Windows: locate Cursor.exe (often under C:\Users\<you>\AppData\Local\Programs\Cursor\Cursor.exe)
    • Mac: locate Cursor.app in Applications

4) Set your Git identity (name + email)

This controls what shows up on commits.

  1. In GitHub Desktop: Options/Settings → Git
  2. Set:
    • Name: your preferred name (e.g., “Gabe Lam”)
    • Email: the email tied to your GitHub account (recommended)

5) Create a “repos” folder on your computer

Create a folder like:

  • bf-repos/ or brainforge-projects/

This is where repos will be downloaded (“cloned”). Otherwise, it will default to Documents. This is all fine as long as you keep it in one place.

PART 2 — GET A REPO ONTO YOUR COMPUTER (CLONE)

There are two easy ways:

Option A (simplest): Clone from GitHub Desktop

  1. Open GitHub Desktop
  2. Click File → Clone repository…
  3. Choose one:
    • GitHub.com tab (if you have access, you’ll see org repos)
    • URL tab (paste the repo URL someone sends you)
  4. Set Local Path to your bf-repos/ folder
  5. Click Clone

Option B: “Open with GitHub Desktop” from GitHub.com

  1. Go to the repo page on GitHub.com
  2. Click the green Code button
  3. Select Open with GitHub Desktop
  4. Confirm the local folder, then Clone

PART 3 — DAILY WORKFLOW (THE ONLY LOOP YOU NEED)

Daily checklist

Before you start working (every time)

  1. Open GitHub Desktop
  2. Select the correct repo (top-left)
  3. Click Fetch origin
    • If updates exist, it will change to Pull origin → click Pull origin

While you work

  1. Click Open in Cursor (in GitHub Desktop)
  2. Edit or create files in Cursor
  3. Save your files normally

When you finish working

  1. Go back to GitHub Desktop
  2. Review changed files
  3. Write a commit message
  4. Click Commit to
  5. Click Push origin

STEP-BY-STEP WALKTHROUGHS (CORE ACTIONS)

A) Fetch (check if anyone else changed things)

Use when: you want to check for updates without changing your files yet.

  1. Open GitHub Desktop
  2. Select the repo
  3. Click Fetch origin (top toolbar)

What it does:

  • Downloads the “latest info” from GitHub
  • Does not change your local files yet

B) Pull (actually bring down other people’s changes)

Use when: you want your local repo updated to match GitHub.

  1. Click Fetch origin
  2. If there are updates, the button becomes Pull origin
  3. Click Pull origin

What it does:

  • Fetches updates and merges them into your current branch
  • If there are no conflicts, it “just works”

C) Commit (save your work as a clean snapshot)

Use when: you made changes you want to save and share.

  1. In GitHub Desktop, click the Changes tab (left sidebar)
  2. Click each changed file to review what changed
  3. In the bottom-left, fill in:
    • Summary (required): short message like update onboarding guide
    • Description (optional): extra context
  4. Click Commit to

Good commit messages:

  • Start with a verb: add, update, fix, remove
  • Describe what changed, not why you were doing it

D) Push (upload your commits to GitHub)

Use when: you want teammates to see your commits.

  1. After committing, click Push origin (top toolbar)

If you forget to push:

  • Your work is saved locally, but nobody else can see it yet

MERGE (2 COMMON MEANINGS) + HOW TO DO IT

1) “Merge” meaning: pulling updates into your branch

This is the most common day-to-day “merge.”

How it happens:

  • You click Pull origin
  • GitHub Desktop merges remote updates into your current branch automatically

If it succeeds:

  • You are done

If it doesn’t:

  • You have a merge conflict (see next section)

2) “Merge” meaning: combining a feature branch into main

Only do this if your team is using branches + PRs.

Typical flow:

  1. In GitHub Desktop: Current Branch → New Branch
  2. Name it something clear, like gabe/update-sow-template
  3. Make changes in Cursor
  4. Commit + push
  5. Click Create Pull Request (in GitHub Desktop)
  6. On GitHub.com, click Merge pull request (if you have permission)

If your team does not use PRs yet, skip this and stay on main.

WHAT TO DO IF YOU HIT A MERGE CONFLICT

A conflict means:

  • You and someone else changed the same lines in the same file

Conflict resolution (simple version)

  1. In GitHub Desktop, you’ll see a conflict warning after pulling
  2. Click Open in Cursor (or “Open in External Editor”)
  3. Cursor will show conflict markers in the file
  4. Choose the correct version (or combine both)
  5. Save the file
  6. Go back to GitHub Desktop
  7. Confirm the conflict is resolved
  8. Commit the merge/conflict resolution
  9. Push origin

Rule of thumb:

  • If you’re unsure which version is correct, do not guess—ask in Slack and include a screenshot of the conflict.

COMMON GOTCHAS (QUICK FIXES)

“Rejected / fetch first” when pushing

Cause: GitHub has new changes you don’t have locally.

Fix:

  1. Fetch origin
  2. Pull origin
  3. Then Push origin

“I don’t see my changes”

Checklist:

  • Did you save in Cursor?
  • Are you on the correct repo in GitHub Desktop?
  • Are you on the correct branch?

“Open in Cursor” doesn’t work

Fix:

  • Re-check Settings → Integrations → External Editor and set Cursor again

What You Don’t Need to Learn (Yet)

Ignore these unless you’re specifically asked:

  • Terminal Git commands
  • Advanced branching strategies
  • GitHub Actions
  • Rebasing

If you can Clone → Fetch/Pull → Commit → Push, you’re using GitHub correctly.

Graph View