How to Connect an Existing Local Git Project to a New GitHub Repository
Connecting an Existing Local Git Project to a New GitHub Repository
When moving an existing local project to a newly created GitHub repository, two Git issues can commonly appear: authentication prompts and rejected pushes caused by different commit histories.
This guide documents the complete solution, using generic repository and account names so it can be reused for other projects.
1. The Situation
Suppose you already have a project on your computer:
my-project/
├── assets/
├── content/
├── layouts/
├── static/
├── package.json
└── ...
You then create a new GitHub repository:
https://github.com/example-user/example-project.git
Your goal is:
Local project
│
│ git push
▼
GitHub repository
However, two problems can occur.
Problem 1: GitHub Asks for a Password
You may run:
git push -u origin main
and receive:
Username for 'https://github.com':
Password for 'https://github.com':
If your other GitHub repositories don’t ask for credentials, this is an important clue.
Check the remote URL
Run:
git remote -v
You may see:
origin https://github.com/example-user/example-project.git (fetch)
origin https://github.com/example-user/example-project.git (push)
This repository is using HTTPS.
Your other repositories may instead be using SSH:
origin git@github.com:example-user/another-project.git (fetch)
origin git@github.com:example-user/another-project.git (push)
That explains the different behavior.
Solution: Change the Repository to SSH
If your SSH authentication is already configured for GitHub, you don’t need to create another token or change your existing authentication setup.
First remove the HTTPS remote:
git remote remove origin
Then add the GitHub repository using SSH:
git remote add origin git@github.com:example-user/example-project.git
Verify it:
git remote -v
You should now see:
origin git@github.com:example-user/example-project.git (fetch)
origin git@github.com:example-user/example-project.git (push)
Test the SSH Connection
Run:
ssh -T git@github.com
If SSH authentication is correctly configured, GitHub should respond with a message indicating that authentication succeeded.
The exact message can vary, but the important part is that GitHub recognizes your SSH key.
You can then try:
git push -u origin main
At this point, the password prompt should no longer appear.
Problem 2: Push Rejected With “Fetch First”
After fixing authentication, you may get:
! [rejected] main -> main (fetch first)
error: failed to push some refs to 'github.com:example-user/example-project.git'
hint: Updates were rejected because the remote contains work
that you do not have locally.
This is a different problem.
It means GitHub already has commits that your local repository doesn’t have.
For example:
LOCAL REPOSITORY
A --- B --- C
while GitHub contains:
GITHUB
X --- Y
The histories are different:
B --- C
/
A ----
\
X --- Y
Git refuses to automatically overwrite the GitHub history.
Step 1: Fetch the Remote Repository
Before changing anything, fetch the GitHub history:
git fetch origin
This downloads the remote information without modifying your working files.
You can inspect the history with:
git log --oneline --graph --all --decorate
Step 2: Pull the GitHub History
Because the local and remote repositories were created independently, Git may report:
fatal: Need to specify how to reconcile divergent branches.
This happens because newer versions of Git require you to explicitly tell Git whether you want to merge or rebase divergent branches.
For this situation, use a merge.
Run:
git pull origin main --allow-unrelated-histories --no-rebase
There are two important options here.
--allow-unrelated-histories
This tells Git:
These repositories were created independently, but I want to combine their histories.
This is necessary when the local repository and GitHub repository don’t share a common initial commit.
--no-rebase
This tells Git to merge the histories instead of rewriting them through a rebase.
For an existing project being connected to a newly created repository, merging is usually the safer and simpler approach.
What Happens Next?
There are two possibilities.
Case A: Git merges successfully
Git may display:
Merge made by the 'ort' strategy.
Check the repository:
git status
Then push:
git push -u origin main
Your local project should now be on GitHub.
Case B: Git Reports Merge Conflicts
You might see:
CONFLICT (add/add): Merge conflict in README.md
Automatic merge failed; fix conflicts and then commit the result.
This means the same file exists in both repositories and Git cannot determine which version should be kept.
Check the affected files:
git status
Git will show something similar to:
both added: README.md
Open the conflicted file.
Git may place markers around the conflicting sections:
<<<<<<< HEAD
Your local version
=======
GitHub version
>>>>>>> origin/main
You need to decide which content should remain.
After resolving the file, stage it:
git add README.md
Then complete the merge:
git commit
Finally:
git push -u origin main
Complete Solution
The complete workflow is:
1. Enter the project
cd /path/to/my-project
2. Check the remote
git remote -v
3. If using HTTPS, change it to SSH
git remote remove origin
git remote add origin git@github.com:example-user/example-project.git
4. Verify SSH
ssh -T git@github.com
5. Fetch GitHub
git fetch origin
6. Merge the independent histories
git pull origin main --allow-unrelated-histories --no-rebase
7. If there are conflicts
git status
Resolve the files, then:
git add .
git commit
8. Push
git push -u origin main
Why We Didn’t Use Force Push
You may find advice online suggesting:
git push --force
This can make the push succeed, but it wasn’t the appropriate first solution.
A force push can replace the remote branch with your local history.
For example:
GitHub:
A --- B --- C
↑
existing work
A force push could effectively replace that history with:
Local:
X --- Y --- Z
Potentially losing commits that already exist on GitHub.
Instead, we used:
git pull origin main --allow-unrelated-histories --no-rebase
which combines the histories.
Recommended Workflow for Future Changes
Once the local repository and GitHub repository are properly connected, you shouldn’t need to repeat the setup.
For normal changes:
git status
git add .
git commit -m "Describe the change"
git push
For example:
git add .
git commit -m "Update website layout"
git push
Git will use the configured SSH remote:
git@github.com:example-user/example-project.git
so you shouldn’t receive the HTTPS username/password prompt.
Troubleshooting Reference
Git asks for a GitHub password
Check:
git remote -v
If you see:
https://github.com/...
and your other repositories use SSH, change the remote:
git remote remove origin
git remote add origin git@github.com:example-user/example-project.git
fetch first
If you see:
[rejected] main -> main (fetch first)
run:
git fetch origin
git pull origin main --allow-unrelated-histories --no-rebase
Need to specify how to reconcile divergent branches
Use:
git pull origin main --allow-unrelated-histories --no-rebase
Merge conflict
Run:
git status
Resolve the reported files, then:
git add .
git commit
git push
SSH authentication test
Run:
ssh -T git@github.com
If authentication fails, investigate your SSH key configuration before attempting to push again.
Final Architecture
After everything is correctly configured:
┌───────────────────────┐
│ Local Project │
│ │
│ Git repository │
└───────────┬───────────┘
│
│ SSH
│
▼
┌───────────────────────┐
│ GitHub │
│ │
│ example-user/ │
│ example-project │
└───────────────────────┘
The key lesson is that authentication and Git history are two separate problems.
Changing HTTPS to SSH solves the authentication prompt when your SSH setup is already working. The fetch first error is then resolved by fetching and merging the existing remote history rather than force-pushing over it.