Remotes, push, and pull

Why it matters

So far your repository lives only on your computer. A remote is a copy of the repository hosted somewhere else, usually GitHub. Pushing to a remote backs up your work, lets you work from several machines, and is the starting point for collaborating: teammates pull your commits and you pull theirs. A public GitHub profile with real projects is also one of the best things to show an employer.

Key terms

• Remote: a named link to another copy of the repo. By convention the main one is called origin.
• Push: send your new commits to the remote (git push).
• Fetch: download new commits from the remote without changing your files (git fetch).
• Pull: fetch and then merge them into your current branch (git pull).
• Clone: copy a remote repository to your computer, with full history (git clone <url>).

Step 1: a GitHub account and an empty repository

1. Sign up at github.com (free). Turn on two-factor authentication in Settings > Password and authentication.
2. Click New repository. Name it field-notes. Choose Private if you are unsure; you can make it public later.
3. Leave "Add a README", ".gitignore" and "license" unticked, because your local repo already has history. GitHub then shows the commands to push an existing repository.

Step 2: authenticate

GitHub no longer accepts your account password for Git over HTTPS. Use one of these:

• GitHub CLI: install gh from cli.github.com and run gh auth login; it sets up Git credentials for you.
• Git Credential Manager: included with Git for Windows; on first push a browser window asks you to sign in.
• SSH keys: generate a key with ssh-keygen -t ed25519 -C "you@example.com", add the public key (the .pub file) in Settings > SSH and GPG keys, and use the SSH URL (git@github.com:you/field-notes.git).

Never share your private key or paste tokens into files in the repository.

Step 3: connect and push

$ cd ~/cli-practice/field-notes
$ git remote add origin https://github.com/<your-username>/field-notes.git
$ git remote -v
origin  https://github.com/<your-username>/field-notes.git (fetch)
origin  https://github.com/<your-username>/field-notes.git (push)
$ git branch -M main               # make sure the branch is called main
$ git push -u origin main

-u sets origin/main as the upstream of your local main, so from now on plain git push and git pull know where to go. Refresh the GitHub page and your files and commit history are there.

Step 4: pull a change made elsewhere

Edit a file directly on GitHub (open README.md, click the pencil icon, change a line, Commit changes). Your local copy does not know yet:

$ git status
Your branch is up to date with 'origin/main'.    # it has not checked the remote
$ git fetch
$ git status
Your branch is behind 'origin/main' by 1 commit, and can be fast-forwarded.
$ git pull
Fast-forward
 README.md | 2 +-

Habit: pull before you start work each day, and push when you finish a piece of work.

When a push is rejected

! [rejected]        main -> main (fetch first)
error: failed to push some refs
hint: Updates were rejected because the remote contains work that you do not have locally.

Someone (maybe you on GitHub) pushed commits you do not have. Run git pull, resolve any conflicts as in the last lesson, then git push again.

You will see advice to use git push --force. It overwrites the remote history and can destroy teammates' work. Do not use it on shared branches.

Cloning

To get a repository onto a new machine, or to start from someone else's project:

$ cd ~/cli-practice
$ git clone https://github.com/<your-username>/field-notes.git field-notes-copy

The clone already has origin set up.

Common mistakes

• Ticking "Add a README" when creating the GitHub repo, then getting "unrelated histories" on the first push. Create it empty.
• Typing your GitHub password when Git asks for one over HTTPS. Use gh auth login, the credential manager, or SSH.
• Pushing secrets or private data to a public repository. Check git status and git diff --staged before committing.
• Not pulling for days, then facing a huge conflict.

Quick recap

• A remote (origin) is a hosted copy; git remote -v lists remotes.
• git push -u origin main the first time; then git push and git pull.
• fetch downloads, pull downloads and merges; a rejected push means pull first.
• Authenticate with the GitHub CLI, the credential manager or SSH keys; never force push shared branches.

Try it

Open the Do tab to put your repository on GitHub.