Setting up a Repo for a New Project

Every project starts the same way: a clean repository with the right foundation. This tutorial walks through setting up a Git repo from scratch with all the essentials.

Prerequisites

Before you start, make sure you have:

A GitHub account (you can sign in and create repos)
Git installed (git --version)
A way to authenticate to GitHub from your computer
- HTTPS: you'll sign in when pushing (often with a Personal Access Token instead of a password)
- SSH: you've added an SSH key to your GitHub account (recommended if you do this a lot)
A project folder on your machine, and you can navigate to it in Terminal/PowerShell

What the heck is a repo?

A repository is just a folder that stores your stuff, that Git tracks. Usually it contains code files, in whatever language you choose to work. Often, it will also include images as well, especially when the repo is for a website or an app with a user interface. So it's natural that the first step in a new project is to create the folder which will eventually house the files we need for the final product.

Setting up the repo

Pick a name and create your project folder on your own computer, wherever you normally store project folders. So for me, my new folder would be ~/Documents/Projects/new-project-name. Keep names lowercase with hyphens -- it makes URLs and paths easier to work with.

Now we'll set up a github repo. Github is just a cloud-based platform where people store their code. I'll explain more about what that means in just a moment.

Go to https://github.com and sign in.
Once you're in your account home, hit the + button on the top right and select New Repository.
Give it a name (again, lowercase with only dashes) and decide whether you want it to be visible to anyone or private only to you and whoever you explicitly share it with. Optionally, provide a description for anyone examining the repo among a listing of them.
Hit Create Repository.

Now we have to mess with the command line interface. I realize this can be intimidating for those who have never worked with it. But I promise you, the basics are super easy to learn, and that's all you need. I suggest you google "How to navigate folders in the command line interface", and come back when you have the hang of it. For those who are already familiar, open PowerShell (PC) or Terminal (Mac) and navigate to your repo, or create it with mkdir and then cd (the command to have your terminal prompt change directory) into it. Then run:

git init
git remote add origin https://github.com/your-username/new-project-name.git

What did we just do?

We told git that the folder we're in (~/Documents/Projects/new-project-name) is a code repository. Once it knows that, git starts to track every time it changes, whether that's you deleting a period or adding a GB of video files to it.
Then we told git to add a remote repository - your folder's brother from another mother, if you will. In this case, it's on github.com where we created the new project to start all this. So by running this command pointing it to the url of our new github project and adding the .git at the end, we essentially link the folder on our computer with the folder stored on github's computers. Now it's known as origin and to move our local files there we "push to origin"

You now have an empty repo with no commits.

Create a README.md

A README markdown file is usually where you store basic information about the contents or purpose of the code in the repository. In this case, we just want it so that we have something we can commit and push to origin, so we'll just create an empty README.md file.

touch README.md
git add .
git branch -M main
git commit -m "Initial commit"
git push -u origin main

Windows note: if touch doesn't work, use New-Item README.md -ItemType File in PowerShell.

Ok, so what'd we do on this one?

touch README.md = we created an empty README.md file. Now we have something to send to our remote repo
git add . = We added all files (in this case, just the README.md) to the staging area. This is where files go when we want to send them to their brother's house, but we have to pack them all in a car first.
git branch -M main = We told the driver to take the quickest way there - the main route. We're actually just renaming the default branch (version) from master to main, because for some reason every programmer decided that's what it should be called but no one has ever updated git itself to default to main.
git commit -m "Initial commit" = This is where you buckle their seatbelts and hand them a message to take to their stepmom. The message can't be mean this time though, because anyone who looks at your repo will see it. We commit the files to the repo and prepare them for their journey.
git push origin main = We close the car door and send the kids off to their stepmom's house. And then smile a glorious freedom smile and go make mac n' cheese to eat straight from the pot.

And that's it! You just created a repo and initialized your local codebase to link it with github. Time for a nap, my friend.

You don't need to type the same 6-8 commands every time. Here's a Claude Code command that does it all in one shot.

Prerequisites

Git installed
GitHub CLI installed and authenticated (gh auth login)
Claude Code installed

The Command

Just type the command, give the repo a name, and tell it whether you want it public or private:

/new-project <repo-name> <public|private>

Example:

/new-project hello-world public

That's it! The command will:

Initialize a git repo (if needed)
Create a README.md with the project name
Make an initial commit
Create the GitHub repo
Push everything up

Installing the Command

Save this script to ~/.claude/commands/new-project.md:

---
description: Create + initialize a GitHub repo from the current folder. Usage: /new-project <project-name> <public|private>
argument-hint: <project-name> <public|private>
allowed-tools: Bash
---
 
# /new-project
 
Run: `/new-project <project-name> <public|private>`
 
This command should do everything in **one Bash run** for speed.
 
`$ARGUMENTS` is a single string containing all arguments (e.g. `"my-repo public"`).
Use `read` to split it into positional variables.
 
Execute the following Bash script exactly, substituting `$ARGUMENTS` into the ARGS_RAW variable:
 
\`\`\`bash
set -euo pipefail
 
ARGS_RAW="$ARGUMENTS"
 
# Parse arguments by splitting the raw string
read -r REPO_NAME VISIBILITY_RAW EXTRA <<< "$ARGS_RAW" || true
 
if [ -z "${REPO_NAME:-}" ] || [ -z "${VISIBILITY_RAW:-}" ]; then
  echo "Usage: /new-project <project-name> <public|private>"
  exit 1
fi
 
if [ -n "${EXTRA:-}" ]; then
  echo "Too many arguments."
  echo "Usage: /new-project <project-name> <public|private>"
  exit 1
fi
 
# Normalize visibility to lowercase
VISIBILITY_RAW="$(printf "%s" "$VISIBILITY_RAW" | tr '[:upper:]' '[:lower:]')"
 
case "$VISIBILITY_RAW" in
  public)  GH_VIS="--public" ;;
  private) GH_VIS="--private" ;;
  *)
    echo "Visibility must be \"public\" or \"private\". Example: /new-project my-repo public"
    exit 1
    ;;
esac
 
# Preconditions
command -v git >/dev/null 2>&1 || { echo "Missing git. Install Git first."; exit 1; }
command -v gh  >/dev/null 2>&1 || { echo "Missing gh. Install GitHub CLI first."; exit 1; }
 
if ! gh auth status >/dev/null 2>&1; then
  echo "Not logged in to GitHub CLI. Run: gh auth login"
  exit 1
fi
 
# Ensure we can write here
if [ ! -w "." ]; then
  echo "Current directory is not writable: $(pwd)"
  exit 1
fi
 
# Init git repo if needed
if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
  git init >/dev/null
fi
 
# Ensure at least one commit (so push works)
if ! git rev-parse --verify HEAD >/dev/null 2>&1; then
  if [ ! -f README.md ]; then
    printf "# %s\n" "$REPO_NAME" > README.md
  fi
  git add -A
  git commit -m "Initial commit" >/dev/null
fi
 
# Ensure branch is main
git branch -M main >/dev/null
 
# Refuse to overwrite an existing origin
if git remote get-url origin >/dev/null 2>&1; then
  echo "Remote 'origin' already exists: $(git remote get-url origin)"
  echo "Remove it with: git remote remove origin"
  exit 1
fi
 
# Create repo + push (let gh fail fast if name is taken)
gh repo create "$REPO_NAME" "$GH_VIS" --source=. --remote=origin --push
 
# Print URL + done
gh repo view "$REPO_NAME" --json url -q .url
echo "Done. Repo created and pushed."
\`\`\`

Prerequisites

What the heck is a repo?

Setting up the repo

Create a README.md

Prerequisites

The Command

Installing the Command

Dan’s AI Assistant

Hi! I’m Dan’s AI Assistant