# How to put your Python project on GitHub


This guide walks through the one-time setup to get a [uv](https://pydevtools.com/handbook/reference/uv.md)-based Python project into a Git repository and pushed to GitHub. It assumes the project already exists on your machine (see [Create your first Python project](https://pydevtools.com/handbook/tutorial/create-your-first-python-project.md) if it doesn't).

For background on what Git and GitHub are, see [Enough Git to Supervise Your AI Coding Agent](https://pydevtools.com/handbook/explanation/enough-git-to-supervise-your-ai-coding-agent.md).

### Install Git

macOS includes Git with the Xcode command-line tools. Install them if you haven't already:

```bash
xcode-select --install
```

On Linux, use your package manager:

```bash
# Debian/Ubuntu
sudo apt install git

# Fedora
sudo dnf install git
```

Download and run the installer from [git-scm.com](https://git-scm.com/download/win), or install with winget:

```powershell
winget install --id Git.Git -e --source winget
```

Verify the installation:

```console
$ git --version
git version 2.47.0
```

### Configure Git

Git labels every commit with your name and email. Set these once:

```bash
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"
```

Use the same email associated with your GitHub account so that commits are linked to your profile.

### Initialize the repository

Open a terminal in your project directory and run:

```bash
git init
```

This creates a hidden `.git` folder that tracks your project's history. The folder itself doesn't change how your project works.

### Review `.gitignore`

If the project was created with `uv init`, a `.gitignore` file already exists. Verify it includes entries for files that shouldn't be tracked:

```text
# Python-generated files
__pycache__/
*.py[oc]
build/
dist/
wheels/
*.egg-info

# Virtual environments
.venv
```

> [!IMPORTANT]
> Never commit secrets like API keys, `.env` files, or credentials. Add them to `.gitignore` before your first commit.

### Make your first commit

Stage all files and create the first commit:

```bash
git add .
git commit -m "Initial commit"
```

`git add .` stages every file not excluded by `.gitignore`. `git commit` saves the snapshot. For more on what staging and committing mean, see [the four states of your code](https://pydevtools.com/handbook/explanation/enough-git-to-supervise-your-ai-coding-agent.md#the-four-states-of-your-code).

### Create a GitHub repository

1. Go to [github.com/new](https://github.com/new)
2. Enter a repository name (typically matching your project folder name)
3. Choose public or private visibility
4. Do not check "Add a README file" or any other initialization options (your project already has files)
5. Click Create repository

GitHub will show a page with setup instructions. You need the repository URL, which looks like `https://github.com/your-username/your-project.git`.

### Connect and push

Link your local repository to GitHub and push:

```bash
git remote add origin https://github.com/your-username/your-project.git
git push -u origin main
```

GitHub may prompt for authentication. If you haven't authenticated before, follow [GitHub's instructions for setting up a personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) or use the [GitHub CLI](https://cli.github.com/) (`gh auth login`).

### Verify on GitHub

Open your repository's URL in a browser. Your project files should be visible, along with the commit message "Initial commit."

From here, your project is backed up on GitHub and ready for features that depend on it, like [GitHub Actions](https://pydevtools.com/handbook/tutorial/setting-up-github-actions-with-uv.md) or [pre-commit hooks](https://pydevtools.com/handbook/how-to/how-to-set-up-pre-commit-hooks-for-a-python-project.md).