How to Push an Existing Project to GitHub (Step by Step)

You have a project on your computer and want it on GitHub. This lesson gives you the exact commands for a new or existing Git repository, explains each step, and fixes the errors people hit most often on their first push.

---

🎯 The Goal

You already have a project on your computer, for example a Playwright test framework or a Python script folder, and you want it on GitHub. This lesson shows the exact steps, for a folder that is not yet a Git repository and for one that already is.

---

🧭 Step 1: Create an Empty Repository on GitHub

1. On GitHub, click + (top right), then New repository.
2. Enter a name (for example playwright-framework), an optional description, and choose Public or Private.
3. Do not tick “Add a README file”, “.gitignore” or “license”. Your local project will provide these, and an empty repository avoids a conflict on the first push.
4. Click Create repository and copy the HTTPS or SSH URL shown on the next page.

---

📁 Step 2: Prepare the Local Project

Open a terminal in your project folder. First add a .gitignore so dependencies, reports and secrets are not uploaded:

node_modules/
test-results/
playwright-report/
.env

---

🚀 Step 3: Commit and Push (Folder Not Yet Using Git)

git init
git add .
git status                       # check that only the right files are staged
git commit -m "Initial commit: Playwright framework"
git branch -M main               # make sure the branch is called main
git remote add origin git@github.com:asha-verma-qa/playwright-framework.git
git push -u origin main

Refresh the GitHub page: your files and commit are there.

Command	Why
git init	Turns the folder into a repository (first repository)
git add . and git commit	Creates the first snapshot
git branch -M main	Renames the current branch to main (some setups default to master)
git remote add origin <url>	Connects to the GitHub repository (remotes)
git push -u origin main	Uploads and sets upstream tracking (push)

---

🔁 Step 3 (Alternative): Folder Already Using Git

If the project already has commits, you only need to add the remote and push:

git remote -v                     # check: is there already an origin?
git remote add origin git@github.com:asha-verma-qa/playwright-framework.git
git push -u origin main

If origin already points somewhere else, change it: git remote set-url origin <new-url>. To push every local branch and tag: git push -u origin --all and git push origin --tags.

---

⚠️ If You Already Created a README on GitHub

Then GitHub has a commit your local repository does not, and the first push is rejected. Merge the two histories once:

git pull origin main --allow-unrelated-histories
# resolve conflicts if any (often in README.md), then:
git push -u origin main

--allow-unrelated-histories is needed because the two repositories have no common starting commit.

---

⚡ Shortcut: GitHub CLI

With the GitHub CLI you can create the GitHub repository and push in one command from your project folder:

gh repo create playwright-framework --private --source=. --remote=origin --push

---

✅ After the First Push

• Add a good README with setup and run instructions (Markdown and README).
• Add a description and topics (for example playwright, typescript, test-automation) on the repository page so people can find it.
• Add a CI workflow so tests run on every push (Playwright in GitHub Actions).

---

🐞 Troubleshooting

Error	Fix
error: remote origin already exists	Use git remote set-url origin <url> instead of add
src refspec main does not match any	No commit yet, or the branch is named differently: commit first, or git branch -M main
! [rejected] main -> main (fetch first)	GitHub has a README or other commits: use the “unrelated histories” steps above
fatal: refusing to merge unrelated histories	Add --allow-unrelated-histories to the pull
Huge upload or node_modules on GitHub	Add a .gitignore, run git rm -r --cached node_modules, commit and push

---

📝 Assignment

1. Take any existing project folder on your computer (or create one with a few files) and add a .gitignore.
2. Create an empty repository on GitHub and push the project with the commands in Step 3.
3. Create a second GitHub repository with a README, then push another local project to it using --allow-unrelated-histories.
4. Add a description, topics and a README to your repository on GitHub.
5. Bonus: install the GitHub CLI and create and push a repository with gh repo create.

---

❓ FAQ

🤔 How do I push an existing project to GitHub?

Create an empty repository on GitHub, then in your project folder run git init, git add ., git commit -m "Initial commit", git branch -M main, git remote add origin <url> and git push -u origin main.

🤔 Why should I not add a README when creating the GitHub repository?

It creates a commit on GitHub that your local repository does not have, so your first push is rejected until you merge the two histories.

🤔 What does git branch -M main do?

It renames the current branch to main, overwriting any existing branch with that name.

🤔 How do I fix “remote origin already exists”?

Change the URL with git remote set-url origin <url>, or remove it with git remote remove origin and add it again.

🤔 What does –allow-unrelated-histories mean?

It lets Git merge two repositories that do not share a common first commit, such as a local project and a GitHub repository created with a README.

---

🎯 Next Steps

• 🌿 Git Branches: Create, Switch, Rename and Delete
• 📝 Markdown and Writing a Great README
• 📘 Git and GitHub Tutorial: full course