---
name: new-git-project
description: Bootstraps a brand-new local git repository and (optionally) publishes it to GitHub as a new remote repo, handling every prerequisite along the way — checking for git and the GitHub CLI (gh), installing gh if it's missing, walking the user through gh's browser-based login, setting a missing git identity, making the first commit, and creating+pushing the GitHub repo. Use this whenever the user wants to start a new project and get it under version control, e.g. "start a new git project", "set up a repo for this", "I want to put this on GitHub", "init git here and push it up", "create a new github repo for X", or "turn this folder into a git repo". Also trigger when the user has a GitHub account but says they don't have git/gh set up yet, or asks how to get code from their computer onto GitHub for the first time.
---

# New Git Project

Walks a user from "nothing" to a local git repo with an initial commit, optionally
pushed to a brand-new GitHub repository. Written for someone who may not have `git`
config or the GitHub CLI (`gh`) set up yet — treat that as the normal case, not an
edge case.

## Why this is structured as a checklist

Every step here mutates real state on the user's machine or their GitHub account:
installing software, authenticating a CLI with their identity, creating a public
record on GitHub. None of that should happen silently. The pattern throughout is:
**check → ask if something needs to change → act → verify**. Don't skip the "ask"
step just because the answer seems obvious — a repo that's created private when the
user wanted public (or vice versa) is annoying to fix after the fact, and installing
software without a heads-up is the kind of thing that erodes trust fast.

## Step 1 — Check what's already there

Run these checks up front so you only ask the user about things that actually need
deciding:

```bash
git --version                 # is git installed at all? (rare that it isn't)
which gh && gh --version      # is the GitHub CLI installed?
gh auth status                # is gh already logged in?
git config --global user.name
git config --global user.email
```

Most of the time on a dev machine, git is already present — it's `gh` and its auth
that tend to be missing, especially for someone who's used GitHub only through the
browser so far. Don't assume; just check.

## Step 2 — Install `gh` if it's missing

If `gh` isn't found, tell the user it's needed to create/link the GitHub repo from
the command line, and that you'll download the official installer. **Before
downloading anything, tell the user the filename, source, and approximate size, and
get a clear go-ahead** — this is a real download onto their machine, not a no-op.

Look up the current release rather than hardcoding a version, since `gh` ships
often:

```bash
curl -s https://api.github.com/repos/cli/cli/releases/latest | grep -E '"tag_name"|browser_download_url'
```

Then pick the right asset and install method **for the user's actual OS** — see
[references/gh-install.md](references/gh-install.md) for the per-OS commands
(macOS `.pkg`, Debian/Ubuntu `apt`, Fedora/RHEL `dnf`, Windows `winget`/`scoop`).
The reference file also covers the one thing that trips this up: on macOS the
installer needs the user's own password in the Installer GUI, and you should never
try to run it with `sudo` yourself or otherwise touch credentials — download it,
`open` it, and let them click through.

After install, re-run `gh --version` to confirm it actually landed before moving on.

## Step 3 — Authenticate `gh`

If `gh auth status` shows not logged in, start the web-based device flow:

```bash
gh auth login --hostname github.com --git-protocol https --web
```

This is interactive and will hang waiting for the browser step, so run it in the
background if your environment supports that, then read its output for the
one-time code and the `https://github.com/login/device` URL. Hand both to the user
plainly — e.g. "Your code is `XXXX-XXXX`, enter it at github.com/login/device" —
and wait for them to tell you they've done it. Don't try to open or drive the
browser yourself; this step exists specifically so the user authenticates directly
with GitHub, not through you.

Once they confirm, verify for yourself rather than taking their word for it:

```bash
gh auth status
```

Only proceed once this actually shows a logged-in account.

## Step 4 — Get the project details

Ask the user (don't guess):

- **Project name and location** — this becomes both the folder name and, if they
  want a GitHub repo, the repo name. If they haven't said where, a reasonable
  default is a dedicated projects folder in their home directory, but confirm
  rather than assuming.
- **Create the GitHub repo now, or just set up git locally?** Some people want to
  start coding before deciding on a repo name or visibility — that's fine, git
  works fine with no remote.
- **If creating on GitHub: public or private?** Default to private if they have no
  preference — it's the safer default and trivially easy to flip to public later
  from GitHub's settings, whereas going the other way after the fact means the code
  was briefly exposed.

## Step 5 — Set git identity if missing

If `git config --global user.name` / `user.email` came back empty in Step 1, git
will refuse to commit later without them. Ask the user what name and email to use
(their GitHub-associated email is a sensible suggestion, but let them choose — some
people intentionally commit under a different address than their primary email).

```bash
git config --global user.name "Their Name"
git config --global user.email "their@email.com"
```

This is a one-time, machine-wide setting — worth mentioning to the user so they're
not surprised it applies beyond this one project.

## Step 6 — Create the local repo

```bash
mkdir -p <path>
cd <path>
git init
```

Add a minimal starting point so the first commit isn't empty — a `README.md` with
just the project name, and a `.gitignore`. Keep the `.gitignore` minimal and
generic (e.g. `.DS_Store` on macOS) rather than guessing at a language/framework
the user hasn't mentioned yet; they can expand it once they know what the project
actually is.

```bash
git add README.md .gitignore
git commit -m "Initial commit"
```

## Step 7 — Create the GitHub repo and push (if the user opted in)

This is the step that publishes something — confirm once more, specifically,
before running it, even if the user already said "yes, create it on GitHub" back
in Step 4. Naming the exact repo name and visibility in the confirmation ("create
`github.com/<user>/<name>` as private and push?") gives them one last chance to
catch a typo or change their mind, and costs almost nothing.

```bash
gh repo create <name> --private --source=. --remote=origin --push
# or --public instead of --private
```

This single command creates the remote repo, wires it up as `origin`, and pushes
the current branch — confirm the resulting URL by checking the command's output
rather than assuming it succeeded.

## Step 8 — Summarize

Close with the repo URL (if one was created) and a short day-to-day reminder, since
this may be the user's first repo and the ongoing workflow isn't obvious yet:

```
cd <path>
# make changes
git add .
git commit -m "describe your change"
git push
```

Keep this final message short — a link and a few lines, not a tutorial.