Git keeps a complete history of your project, so you can see what changed, when, and why, and roll back when something breaks. GitHub stores a copy of that history online, which gives you a backup and a way to share or collaborate.
This guide takes you from nothing to a project on GitHub: install Git, make your first commit, push it, and sign in the way GitHub requires today. Then you'll learn branches and pulling, with a cheat sheet at the end.
What you need
- A Windows, macOS or Linux computer
- A free GitHub account
- A project folder (any folder of files works, even a single text file)
- A terminal: PowerShell or Git Bash on Windows, Terminal on macOS or Linux
Step 1: Install Git
Windows: download Git for Windows from git-scm.com/install/windows and run the installer. The default options are fine for beginners. It includes Git Credential Manager, which handles GitHub sign-in for you later. If you use winget, this works too:
winget install --id Git.Git -e --source wingetmacOS: the quickest route is Apple's Command Line Tools, which include Git. If you use Homebrew, brew install git works as well. See git-scm.com/install/mac.
xcode-select --installLinux: use your distribution's package manager (git-scm.com/install/linux):
# Debian or Ubuntu
sudo apt-get install git
# Fedora
sudo dnf install gitCheck that it worked:
git --versionStep 2: Tell Git who you are
Every commit records an author name and email. Set them once for your user account:
git config --global user.name "Your Name"
git config --global user.email "you@example.com"Run git config --global user.name with no value to check what's set.
Step 3: Create a repository
A repository ("repo") is just a folder that Git is tracking. Make one and move into it:
mkdir my-project
cd my-project
git initgit init creates a hidden .git folder where the history lives. Today, Git names the first branch master unless you've configured otherwise (Git 3.0 will switch the default to main). We'll rename it in Step 7, or you can make main your default for every new repo:
git config --global init.defaultBranch mainStep 4: Add a .gitignore file
Some files should never go into history: passwords, API keys, downloaded dependencies, editor clutter. List them in a file called .gitignore in the project's top folder:
# Secrets
.env
# Dependencies and build output
node_modules/
dist/
# System and log files
.DS_Store
*.logLines starting with # are comments, and a trailing / matches a folder.
Step 5: Make your first commit
Create a file to commit, such as README.md with a line describing the project. Then ask Git what it sees:
git statusNew files show as "untracked." Committing is a two-step process. First, git add stages the changes you want to save, and then git commit saves them as a snapshot with a message:
git add .
git commit -m "First commit"git add . stages everything in the current folder (except what .gitignore excludes). To stage one file, name it instead: git add README.md. Run git log --oneline to see your commit.
Step 6: Create an empty repository on GitHub
- Sign in to GitHub and open the + menu in the upper-right corner.
- Choose New repository.
- Pick the owner (your account) and type a name, such as
my-project. - Choose Public or Private visibility.
- Leave the README, license and .gitignore options off. Your local repo already has history, and adding files here can cause errors on your first push.
- Click Create repository.
GitHub then shows the repository's URL. Copy the HTTPS version, which looks like https://github.com/your-username/my-project.git.
Step 7: Connect and push
Back in your terminal, inside the project folder:
git remote add origin https://github.com/your-username/my-project.git
git remote -v
git branch -M main
git push -u origin maingit remote add origin ...saves GitHub's address under the short nameorigin.git remote -vshows the saved address so you can check it.git branch -M mainrenames your current branch tomain.git push -u origin mainuploads your commits and remembers that your localmaintracks GitHub'smain, so later you can just typegit pushandgit pull.
Step 8: Sign in the way GitHub requires
GitHub stopped accepting account passwords for Git operations on August 13, 2021. When Git asks you to sign in, use one of these instead:
- Git Credential Manager (easiest). It comes with Git for Windows. On your first push, it opens a browser window where you sign in to GitHub, then remembers you. On macOS, you can add it with
brew install --cask git-credential-manager. - GitHub CLI. If you've installed GitHub's
ghtool, rungh auth login, choose HTTPS, and agree to authenticate Git with your GitHub credentials. - Personal access token. Create one in your GitHub settings and paste it when Git asks for a password. GitHub recommends fine-grained tokens with an expiration date. Treat a token like a password, and keep it in a password manager such as Bitwarden.
- SSH key. If you already use SSH keys (see how to set up SSH keys), add your public key on GitHub under Settings > SSH and GPG keys > New SSH key, test it, and switch your remote to the SSH address:
ssh -T git@github.com
git remote set-url origin git@github.com:your-username/my-project.gitA successful test greets you by username and notes that GitHub doesn't provide shell access. That message is normal.
Step 9: Work on a branch
A branch lets you try changes without touching main. Create one and switch to it in a single step:
git switch -c add-contact-pageEdit files, then commit as before and push the new branch:
git add .
git commit -m "Add contact page"
git push -u origin add-contact-pageOn GitHub you can now open a pull request to review and merge the branch. To merge it locally instead:
git switch main
git merge add-contact-page
git pushgit switch - jumps back to the branch you were on before.
Step 10: Pull changes from GitHub
If you edit files on GitHub's website, or work from a second computer, bring those changes down before you start:
git pullgit pull fetches new commits from GitHub and integrates them into your current branch.
Commands cheat sheet
| Command | What it does |
|---|---|
git init |
Start tracking the current folder |
git status |
Show changed, staged and untracked files |
git add <file> / git add . |
Stage changes for the next commit |
git commit -m "message" |
Save staged changes as a snapshot |
git log --oneline |
List commits, one per line |
git remote add origin <url> |
Link the repo to GitHub |
git remote -v |
Show linked remote addresses |
git branch -M main |
Rename the current branch to main |
git push -u origin main |
Upload and set the tracking branch |
git push / git pull |
Upload / download changes after setup |
git switch -c <name> |
Create a branch and switch to it |
git switch <name> |
Switch to an existing branch |
git merge <name> |
Merge a branch into the current one |
git rm --cached <file> |
Stop tracking a file but keep it on disk |
If something goes wrong
- Your password is rejected when you push. That's expected. Use Git Credential Manager, the GitHub CLI, a token or SSH (Step 8).
- "remote origin already exists." You've already added a remote. Fix the address with
git remote set-url origin <correct-url>. - The push is rejected because GitHub has commits you don't. This usually means a README or license was added when the repo was created. For a brand-new project, the simplest fix is to delete that GitHub repository and create it again empty.
git pullsays your branches have diverged. Choose how to combine them:git pull --rebasereplays your commits on top of GitHub's, andgit pull --no-rebasecreates a merge commit.- "Permission denied (publickey)" with SSH. GitHub doesn't have your public key, or your agent isn't offering it. Run
ssh -vT git@github.comto see which keys are tried.
The bottom line
The everyday Git loop is short: change files, git add, git commit, git push. Set your name and email once, keep secrets out with .gitignore, create the GitHub repo empty, and sign in with Git Credential Manager, a token or SSH instead of your password. GitHub gives you an off-site copy, but it isn't a complete backup plan on its own; the 3-2-1 backup rule covers the rest.