Git bootcamp and cheat sheet#

Note

This section provides instructions on common tasks in CPython’s workflow. It’s designed to assist new contributors who have some familiarity with Git and GitHub.

If you are new to Git and GitHub, please become comfortable with these instructions before submitting a pull request. As there are several ways to accomplish these tasks using Git and GitHub, this section reflects one method suitable for new contributors. Experienced contributors may desire a different approach.

In this section, we will go over some commonly used Git commands that are relevant to CPython’s workflow.

Note

Setting up Git aliases for common tasks can be useful to you. You can get more information about that in Git documentation

Forking CPython GitHub repository#

You will only need to do this once.

  1. Go to https://github.com/python/cpython.

  2. Press Fork on the top right.

  3. When asked where to fork the repository, choose to fork it to your username.

  4. Your forked CPython repository will be created at https://github.com/<username>/cpython.

Cloning a forked CPython repository#

You will only need to do this once per machine. From your command line:

git clone git@github.com:<username>/cpython.git

It is also recommended to configure an upstream remote repository:

cd cpython
git remote add upstream https://github.com/python/cpython

You can also use SSH-based or HTTPS-based URLs.

Configure the remotes#

Configure git to pull main from the upstream remote:

git config --local branch.main.remote upstream

Since one should never attempt to push to upstream, configure git to push always to origin:

git remote set-url --push upstream git@github.com:<username>/cpython.git

Listing the remote repositories#

To list the remote repositories that are configured, along with their URLs:

git remote -v

You should have two remote repositories: origin pointing to your forked CPython repository, and upstream pointing to the official CPython repository:

origin  git@github.com:<username>/cpython.git (fetch)
origin  git@github.com:<username>/cpython.git (push)
upstream        https://github.com/python/cpython (fetch)
upstream        git@github.com:<username>/cpython.git (push)

To verify the upstream for main:

git config branch.main.remote

It should emit upstream, indicating to track/pull changes for main from the upstream remote.

Setting up your name and email address#

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

The --global flag sets these parameters globally while the --local flag sets them only for the current project.

Enabling autocrlf on Windows#

The autocrlf option will fix automatically any Windows-specific line endings. This should be enabled on Windows, since the public repository has a hook which will reject all changesets having the wrong line endings:

git config --global core.autocrlf input

Creating and switching branches#

Important

Never commit directly to the main branch.

Create a new branch from main and switch to it:

git switch -c <branch-name> main

This is equivalent to:

# create a new branch from main
git branch <branch-name> main
# switch to the new branch
git switch <branch-name>

To find the branch you are currently on:

git branch

The current branch will have an asterisk next to the branch name. Note, this will only list all of your local branches.

To list all the branches, including the remote branches:

git branch -a

To switch to a different branch:

git switch <another-branch-name>

Other releases are just branches in the repository. For example, to work on the 2.7 release from the upstream remote:

git switch -c 2.7 upstream/2.7

Deleting branches#

To delete a local branch that you no longer need:

git switch main
git branch -D <branch-name>

To delete a remote branch:

git push origin -d <branch-name>

You may specify more than one branch for deletion.