Reference · /learn/
ISSUE 05Basecamp covered why this project needs two machines and what connects them. This page is that connection, built for real — installing git, making the first commit, creating the GitHub repo, hitting the exact error almost everyone hits on their first push, fixing it properly, and then doing the whole thing a second time on a machine that can’t even open a browser.
Where this is going: Six stops: installing the tools, the first commit (and what ‘staged’ actually means), creating the GitHub side, the password error and the real fix, proving the connection actually works, and doing it all again on the server — where the same error shows up a second time, for a reason worth understanding rather than just re-fixing on autopilot.
PART B — THE HOW
01Part B
Three things get installed or set once, ever. Knowing which is which saves repeating all of them.
Started on the MacBook, with Homebrew already installed:
$ brew install git
One real stumble worth recording exactly because it’s such an easy one to repeat: an early attempt failed because a docs example got copy-pasted including the literal $ at the start of the line. That $ isn’t part of the command — it’s just how terminal instructions mark ‘this is a command you type,’ the same way a recipe might write ‘1. Preheat oven’ without expecting you to type the number. Once that $ was left out, the install ran cleanly.
Then, once — and only once, ever, on this machine:
$ git config --global user.name "Alice Paumelle" $ git config --global user.email "apaumelle@icloud.com"
That’s git’s permanent identity for every project on this machine. Nothing about this step needs repeating, here or on any future project — it’s stored globally, not per-project.
Three different things get confused under ‘git setup,’ and they behave completely differently: Homebrew and git itself are installed once per machine, ever. Identity config (name/email) is set once per machine, ever. GitHub authentication (coming up shortly) is also once per machine — but needs doing separately again on any second machine, because nothing here carries over automatically between them.
$ is the prompt, not part of the command.02Part B
A folder becomes a project the moment you say so, and not a second before.
A folder isn’t a git project until you tell it to be one:
$ mkdir ~/currency-portfolio-tool $ cd ~/currency-portfolio-tool $ git init
git init only works inside the folder you actually want tracked — run it from the wrong place and git says so plainly: fatal: not a git repository.
Then the first real file:
$ echo "# Currency-Adjusted Portfolio Performance Tool" > README.md
A commit needs something to actually commit — an empty folder gives git nothing to record. A README is the standard first file for exactly this reason, and it’s genuinely useful anyway: it’s the description anyone sees first when they land on the repo.
Before the actual commit commands, worth being precise about a word that gets thrown around loosely: ‘staged.’ Git tracks a file through three real states, and they map cleanly onto making a s’more:
The ingredients sitting separately, unassembled. This is any file with changes that exist on disk but haven’t been told to git yet.
Assembled on the stick, held over the fire, about to go in. This is git add — marking specific changes as ‘yes, include this in the next commit.’
Toasted and sealed together, a real s’more now. This is git commit — the change is now permanently part of the project’s history.
Shared around the fire with everyone else. This is git push — sending committed history up to GitHub, where the other machine can reach it.
The commands, in order:
$ git add . $ git commit -m "Initial commit"
git add doesn’t touch the file itself — it only marks which changes go into the next commit. You can stage something, change your mind, and unstage it, the same way you can pull the marshmallow back off the stick before it goes anywhere near the fire.
git add . then git commit -m "…"03Part B
Everything works right up until the moment it asks for a password.
On github.com: New repository → currency-portfolio-tool → Private (reasoning for that choice lives back on the Basecamp page) → deliberately not initialized with a README, since that would conflict with the one already sitting locally.
Then connecting the local folder to that new GitHub repo:
$ git remote add origin https://github.com/AlicePaumelle/currency-portfolio-tool.git $ git branch -M main $ git push -u origin main
And immediately:
remote: Invalid username or token. Password authentication is not remote: supported for Git operations. fatal: Authentication failed
This isn’t a mistake — it’s expected. GitHub disabled plain password login for git operations years ago, for security. Typing a GitHub or Apple ID password at that prompt was never going to work, for anyone, ever again.
This exact error is close to a rite of passage — genuinely one of the most-hit errors for anyone’s first-ever git push. Knowing it’s not personal, and not a sign of doing something wrong, is most of what makes it not-frustrating the second time.
04Part B
A browser login, once, and the machine never asks again.
The fix is the GitHub CLI (gh) — it handles login through an actual browser, not a password prompt:
$ brew install gh $ gh auth login
Prompts, answered in order: Account → GitHub.com. Protocol → HTTPS. Authenticate Git with GitHub credentials → Yes. Method → Login with a web browser.
That gave a one-time code, opened a browser, the code went in, done. This also quietly configures git itself to use this login automatically from now on — no more manual auth on this machine, ever, for this account.
$ git push -u origin main
Succeeded — ‘new branch main -> main.’ Confirmed properly by loading the repo on github.com and actually seeing the README rendered there, not just trusting the terminal’s word for it.
gh auth login authenticates through a browser, once.05Part B
Belief isn’t verification.
Four commands, each proving something slightly different, in order of what they actually establish:
| Command | What it actually proves |
|---|---|
| gh auth status | Is this machine authenticated to GitHub at all? |
| git remote -v | Is this folder linked to the right GitHub repo? |
| git fetch | Can it actually reach GitHub right now? |
| git ls-remote | Does GitHub confirm it has the exact same commit? |
The strongest of the four is the last one — git ls-remote returning the same commit hash (7961d18…) as the local git log means GitHub itself is confirming what it’s actually storing, not just that a connection technically exists.
Steps 1 and 2 here (Homebrew/git install, identity config) never need repeating on this machine. The only thing that resets every new terminal session is location — every session starts back at the home folder, and cd back into the project is needed fresh each time.
git ls-remote — GitHub confirms the hash itself.06Part B
Same wall, same fix, second machine. Nothing crosses over on its own.
Claude Code doesn’t live on the Mac — it lives on the server. Getting there:
$ ssh alice
Landing in alice@alice-playground:~/projects. First attempt to bring the project here hit the exact same password-auth wall as before — because gh had never been authenticated on this machine. Nothing from the Mac’s setup carries over automatically. Each machine needs its own independent gh login, every time, with no exceptions.
Same fix, same shape:
$ gh --version # already installed here $ gh auth login # GitHub.com → HTTPS → Yes → web browser
One real difference on a headless server: it can’t open a browser itself. Instead of launching one, it printed a URL and a one-time code and waited — the code went in via a browser on the Mac instead, and the terminal picked up completion on its own.
One thing worth flagging rather than fixing: gh warned that authentication credentials were being saved in plain text on the server. Expected for a headless machine without a full desktop credential manager — not urgent on a private personal server, but a genuinely weaker storage method than the Mac’s encrypted keyring. Noted, not solved today.
Final commands:
$ cd ~/projects $ git clone https://github.com/AlicePaumelle/currency-portfolio-tool.git $ cd currency-portfolio-tool
Clean clone, same commit that was pushed from the Mac, confirmed pulled down correctly.
Dear Camper,
One minor slip along the way, worth keeping rather than editing out: a second git clone got run on the Mac while already standing inside ~/currency-portfolio-tool, which created a nested duplicate folder inside itself. Harmless, just clutter — the lesson is that clone only belongs in a fresh, empty location, never inside a folder that’s already the repo.
— noted at the trailhead
Dispatch postedPart B, cut and dated.
Both machines can now reach the same project, independently, through GitHub. Nothing has actually been built yet — that starts next, along with a mistake that got caught one command before it happened.