Git Course 0%

Create a project in the web UI

Intermediate GitLab UI GitHub UI Git CLI ≈ 8 min

Before this lesson

What you will learn

  • What each field on the new-project form decides
  • Why an empty project is the right choice when you already have a folder
  • How to connect an existing local repository to a new remote

After this lesson you can

  • I can create a project and push an existing folder into it without errors

Why this matters

Creating a project is a one-minute form, and two of its checkboxes decide whether your first push succeeds or fails with a message about unrelated histories. Knowing what the fields mean saves the ten minutes of confusion that usually follows.

The fields

Both platforms ask the same things under slightly different names.

Field What it decides Advice
Name The project's display name and, usually, its URL Lowercase with hyphens is safest; the URL slug is generated from it
Namespace / owner Whether it belongs to you or to a group or organization Team projects go in the group, so that access follows the group's members
Visibility Who can see it: Private, Internal (GitLab: signed-in company members), Public Private unless you have a reason; you can widen it later, but you cannot un-publish what people already cloned
Initialize with a README Whether the project starts with one commit Leave it off when you already have a local folder to push
.gitignore template Adds a starter .gitignore for a language Convenient for a brand-new project; skip it if your folder already has one
Licence Adds a LICENSE file Matters for public projects; ask before choosing one at work

Why "initialize with a README" matters so much

If the server creates a first commit and your computer already has its own first commit, the two histories share no ancestor. Git will not join unrelated histories without being told, and your first push is refused:

Output
To https://gitlab.com/you/trailguide.git
 ! [rejected]        main -> main (fetch first)
error: failed to push some refs to 'https://gitlab.com/you/trailguide.git'
hint: Updates were rejected because the remote contains work that you do not
hint: have locally. This is usually caused by another repository pushing to
hint: the same ref. If you want to integrate the remote changes, use
hint: 'git pull' before pushing again.

Following the hint gives the second half of the trap:

Output
fatal: refusing to merge unrelated histories

Two ways out. The clean one: delete the project and create it again with nothing in it. The quick one: git pull origin main --allow-unrelated-histories, resolve any conflict in the README, then push. Choosing an empty project avoids both.

The rule is simple. Starting from nothing? Let the platform create the README; then clone. Already have a folder? Create the project empty and push into it.

Connecting an existing folder

The platform shows these commands on the empty project's page; they are worth recognizing:

Terminal
$ cd ~/git-practice/trailguide
$ git remote add origin https://gitlab.com/you/trailguide.git
$ git push -u origin main
To https://gitlab.com/you/trailguide.git
 * [new branch]      main -> main
branch 'main' set up to track 'origin/main'.

git remote add writes the URL into .git/config under the name origin; git push -u sends the commits and links the branches (lesson 6.4). Lab 2 walks the whole sequence with checkpoints.

How to do it

There is no Git command that creates a project on GitLab or GitHub: the repository on the server has to exist first, and that is a platform action. What the terminal does is connect to it:

Terminal
$ git remote add origin <url>
$ git push -u origin main

If you added the wrong URL, correct it rather than adding a second remote:

Terminal
$ git remote set-url origin <correct-url>

Common mistakes

  • Ticking the README when you already have a folder. The rejected push and the "unrelated histories" message follow. Recreate the project empty, or use --allow-unrelated-histories once.
  • Creating the project in your personal namespace when it belongs to the team. Access then has to be granted person by person. Both platforms can transfer a project later, but it changes the URL.
  • Public when you meant private. Check the visibility before pressing create, and remember that anything that was public may already have been cloned.
  • error: remote origin already exists. A remote is configured; use git remote set-url origin <url> instead of add.

Try it yourself

Goal: create an empty project and connect a folder you already have.

  1. On GitLab or GitHub, create a private project called trailguide-practice, with no README, no .gitignore and no licence.
  2. On your computer, copy the playground to a new folder and make it a repository: cp -R ~/git-practice/trailguide ~/git-practice/trailguide-practice, then inside it rm -rf .git, git init, git add ., git commit -m "Initial import".
  3. Connect and push with the two commands from the project page.
  4. Refresh the project page.

Expected result: the push prints * [new branch] and set up to track, and the files appear on the website.

Show solution

Removing the copied .git in step 2 is what makes it a fresh repository rather than a second clone pointing at your first project; without it, git remote -v would still show the original origin. Delete the practice project on the website when you have finished with it.

Check yourself

1. You have a local repository with commits and are creating the project on GitLab. Should you tick "Initialize repository with a README"?
2. error: remote origin already exists. What now?
3. Which visibility should a new work project usually have?

Key terms

Repository (repo) Remote origin Push

Related