App Development & Staff Augmentation Company India, USA

Creating a Repository on GitHub

There are two ways to start a project on GitHub: create the repository on the website first and clone an empty copy down, or initialise locally with git init and push it up later. Both work. The right one depends on whether the code already exists on your laptop. We will walk through both, end-to-end, with the exact commands.

The two paths at a glance

Situation	Easier path
Nothing exists yet — brand-new idea	Create on GitHub, then clone
Code already lives on your laptop	init locally, then push
Starting from a template repo	Use template button on GitHub
Migrating from another VCS (SVN, Mercurial)	Use GitHub Importer or git-svn

Path A — Create on GitHub, then clone

Go to github.com/new (or click the + in the top-right → New repository) and fill in the wizard.

Owner — your account, or an organisation you belong to.
Repository name — short, hyphen-separated, lowercase. Same naming rules as a folder.
Description — one sentence. Shows up in search and on the repo home page.
Visibility — Public (anyone can see) or Private (only collaborators).
Initialize with a README — usually yes, so the repo has at least one commit.
Add .gitignore — pick a template matching your stack (Node, Python, Java, etc.). You can always edit later.
Add a license — see the License page. Usually MIT or Apache-2.0 for OSS.

Clone the new (probably-empty) repo

Bash

# HTTPS
git clone https://github.com/you/my-app.git

# SSH (recommended once you've set up keys)
git clone git@github.com:you/my-app.git

cd my-app
# Start coding. Make commits. Push.
git add .
git commit -m "First feature"
git push

Path B — Init locally, then push

If you already have a folder of files on your laptop, do not start from GitHub. Init locally, then create an empty remote and push.

From local folder to GitHub

Bash

# In your project folder
cd ~/code/my-app
git init -b main          # -b main sets initial branch to main

# Create a sensible .gitignore (see the .gitignore page) and:
git add .
git commit -m "Initial commit"

# Create the empty remote. Easiest way: GitHub CLI.
gh repo create my-app --public --source=. --remote=origin --push

# Or manually: go to github.com/new, create EMPTY repo (no README,
# no license, no .gitignore), then:
git remote add origin git@github.com:you/my-app.git
git push -u origin main

Empty means empty

For Path B the GitHub-side repo must be truly empty — no README, no license, nothing. Otherwise your first push is rejected because the histories have no common ancestor, and you end up forcing or rebasing on day one. Annoying.

Public vs private — the decision

	Public	Private
Who can see code	The whole internet	You + collaborators
Cost	Free, unlimited	Free, unlimited
Actions minutes	Unlimited	2,000 min/month free
Required to use	Suitable license needed for reuse	Nothing, but no one else can use it
Searchable	Yes, by GitHub and Google	No
When to pick	OSS, demos, portfolio, blog code	Client work, secrets, WIP you are not ready to share

Creating from a template repository

If a repo has been marked as a template (Settings → check "Template repository"), users see a green Use this template button. Clicking it creates a brand-new repo whose first commit is "Initial commit from template" — not a fork, no shared history.

Use a template via the CLI

Bash

gh repo create my-new-app --template you/starter-template --public --clone

HTTPS vs SSH clone URLs

	HTTPS	SSH
URL shape	https://github.com/you/repo.git	git@github.com:you/repo.git
Authentication	Personal Access Token in credential helper	SSH key in ~/.ssh
Behind corporate proxy	Usually works	Often blocked
First-time setup	Generate PAT	Generate keypair + upload
Daily use	May prompt for token until cached	Silent, no prompts
Recommendation	OK for read-only or corp networks	Preferred for daily work

Importing from another VCS

GitHub used to offer a hosted "Importer" that pulled from SVN/Mercurial/TFS. It was retired in 2024. Today the recommended path is local conversion:

SVN to Git, then push to GitHub

Bash

# Convert SVN history to a Git repo
git svn clone https://svn.example.com/proj/trunk my-app
cd my-app

# Create empty GitHub repo, then:
git remote add origin git@github.com:you/my-app.git
git push -u origin main --tags

Mercurial to Git

Bash

pip install hg-fast-export
git init my-app
cd my-app
hg-fast-export -r /path/to/hg-repo
git push -u origin main

Settings to check on a new repo

Topics — Settings → top of the page. Add 3-6 keywords (react, cli, golang). Boosts discoverability and links to GitHub topic pages.
Social preview — Settings → Social preview. Upload a 1280×640 image. Shown when the URL is shared on Twitter/Slack/etc.
Default branch — usually main. Settings → Branches. Change if you have other conventions.
Branch protection — see Protected Branches page. Turn on for main before the team grows.
Issue templates and PR template — Settings → General → Features. Add .github/ISSUE_TEMPLATE/ and .github/pull_request_template.md.
Discussions — Settings → Features → Discussions. Turn on if you want long-form Q&A.
Pages — Settings → Pages. Enable if you want a project website (see GitHub Pages page).
Actions permissions — Settings → Actions → General. Restrict which actions can run if you have security concerns.

Common first-push errors

fatal: remote origin already exists — git remote remove origin and try again.
failed to push some refs ... fetch first — the GitHub repo already has commits. Either start with an empty repo or git pull --rebase origin main first.
Permission denied (publickey) — your SSH key isn't set up. See SSH Keys page.
Repository not found — typo in URL, or you don't have access, or the repo is private.
src refspec main does not match any — you haven't made any commits yet. git commit first.

The repo as a mental map

What lives where after creation

Text

github.com/you/my-app
+-- Code           README, source files, history
+-- Issues        bug reports, TODOs, discussions
+-- Pull requests proposed merges, code review
+-- Actions       CI workflows
+-- Projects      kanban boards
+-- Wiki          long-form docs
+-- Security      vuln advisories, dependabot
+-- Insights      stats, contributors, traffic
+-- Settings      everything above is configured here

Tip

Get in the habit of creating repos with the `gh` CLI. One command makes the repo, sets the remote, and pushes — much faster than the wizard once you know what you want.

A repo is forever, basically

Once a public repo has been cloned by anyone, the code is out there. Deleting the repo on GitHub does not erase clones on other people's laptops. Think before pushing secrets, private keys, or anything you would not put on a billboard. If you do leak something, treat it as compromised — rotate the secret, do not just rewrite history.