Starting a new GitHub repository including having to merge

Wanting to create a new repository on GitHub, add in a few of the available options that can come with an initial repository such as:

• .gitignore for the platform you are building on
• README.md for detailed notes - particularly if the repository if public
• LICENSE - again important if the repository if public

However, once you add one or more of these items, you will need to merge the repository with your local environment.  This article walks through creating a new GitHub repository and merging the two environments, because your local environment already contains files.  If you are like me, then you don't just create a repository for every new project / idea.  Maybe I should but I don't.  I need to give it some time to see if the idea is worthy.

The key areas of this article are:

• Creating an account and making your first commit;
• Git merge issues and the respective errors - a walk through of possible you can encounter; and
• Steps without errors in relation to merging the repositories

Creating an account and making your first commit

Two environments

On your computer you have begun the basic foundation of your new project with the directory called example01.  Enough time has passed with your local project that you know it is time to created a new GitHub repository also named example01.   How do you bring the two together?

GitHub

As noted at the start, this article assumes you have created a repository named example01 in your GitHub account.  Make note of your GitHub username.

Terminal

Using terminal, go to the directory where your project has begun with the name example01.  For me, I have this project in a directory named Apps.  If you haven't created a directory you can do so using:

mkdir example01

Subsequently, the directory path is:

/Users/{yourname}/Apps/example01

Or as you will know you can go to the directory  using the following command:

cd /users/{yourname}/apps/example01

Add a basic file like readme to the directory so something can be committed

echo "# {file name}" >> README.md

Initialise the directory

git init

No files in directory

Add the README.md file 

git add README.md

You have files in the directory

What happens when you already have files in the directory as outlined in the introduction?

Remember that 

git add -A is the same as git add --all

git add -u is the same as git add --update

Committing 

Make for first commit

git commit -m "first commit"

git branch -M main

To perform the next step you will use your:

• github_username: GitHub username
• repository_name: GitHub repository name

Use the following command, replacing github_username and repository_name.

git remote add origin git@github.com:{github_username}/{repository_name}.git

Replace {repository_name} with the project name in this instance example01.  Also, remember to change the {github_username}

git remote add origin git@github.com:{github_username}/example01.git

Next, push the code on your computer to GitHub master branch.

git push -u origin main

That's it!

Well not quite.  Remember earlier that I mentioned what happens when you have two environments holding files?  This next section walks you through navigation merging the two environments.

Git merge issues and the respective errrors

What happens when you run git push -s origin main and rather than seeing success you receive the following error

! [rejected]          main -> main (fetch first)
error: failed to push some refs to 'your.github.account'
hint: Updates were rejected because the remote contains work that you do
hint: not have locally. This is usually caused by another repository pushing
hint: to the same ref. You may want to first integrate the remote changes
hint: (e.g., 'git pull ...') before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.

This occurs when both the GitHub repository and the local git directory that you are synchronising both contain data.  It can be as simple as in your local directory you have the files you want to push to git.  Whereas, the repository on GitHub you have created with a README.md, LICENSE and / or a .gitignore tailored to your project.

The clues regrading how to resolve this is in the error message.  Being fetch first.

git fetch

or 

git fetch && git checkout main

Then I attempted to 

git pull origin main

However, the error was now

* branch main -> FETCH_HEAD
fatal: refusing to merge unrelated histories

To merge unrelated histories

git push --set-upstream origin main

But not yet, instead an error

To github.com:your-repository
 ! [rejected]          main -> main (non-fast-forward)
error: failed to push some refs to 'your-github-account'
hint: Updates were rejected because the tip of your current branch is behind
hint: its remote counterpart. Integrate the remote changes (e.g.
hint: 'git pull ...') before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.

So I ran the checkout command 

git checkout --track -b origin/main

And pulled the data from GitHub

git pull --rebase

Once again I ran the command git pull also specifying the branch name (main)

git pull origin main

However, the unrelated histories error raised its head again

* branch              main       -> FETCH_HEAD
fatal: refusing to merge unrelated histories

Quick fix by running

git pull origin main --allow-unrelated-histories

Success, the three files on the GitHub repository were added to the local git project

* branch              main       -> FETCH_HEAD
Merge made by the 'recursive' strategy.
 .gitignore | 49 +++++++++++++++++++++++++++++++++++++++++++++++++
 LICENSE    | 21 +++++++++++++++++++++
 README.md  |  1 +
 3 files changed, 71 insertions(+)
 create mode 100644 .gitignore
 create mode 100644 LICENSE
 create mode 100644 README.md

Now to push the project back up to GitHub repository 

git push origin main

Counting objects: 32918, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (24877/24877), done.
Writing objects: 100% (32918/32918), 54.98 MiB | 1.23 MiB/s, done.
Total 32918 (delta 5889), reused 32915 (delta 5888)
remote: Resolving deltas: 100% (5889/5889), done.
To your-git-account
  main -> main

Error and requires a little force

If you apply the command

git push origin main

...and receive the following error:

hint: Updates were rejected because the tip of your current branch is behind
hint: its remote counterpart. Integrate the remote changes (e.g.
hint: 'git pull ...') before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.

Add the force (-f) variable to push this change

git push -f origin main

Steps without errors in relation to merging the repositories

The steps that worked for us without the above errors were:

git pull origin main --allow-unrelated-histories

git push -f origin main

Need to do a hard pull

git reset --hard HEAD

git pull