Simplifying Python Development: A Step-by-Step Guide to Setting up a Python Project with Git and GitHub
Tags: python, tutorial, beginners
Published: 2023-01-11 13:41:55

The purpose of this article is to provide a clear path and understanding of how you would set up a Python environment on your machine.

Keep in mind that the following content is written thinking on a Linux environment. If you use another OS, make the necessary changes.

## Install Python

### Install pyenv

[GitHub - pyenv/pyenv: Simple Python version management](https://github.com/pyenv/pyenv#simple-python-version-management-pyenv)

This allows you to simply choose the Python version you want to use. It allows you to set the global version for the system or a local version for specific projects or directories.

### Use `pyenv` to install Python

Once `pyenv` is installed, you can use it to install the version of Python you want to use.

You can also use **`pyenv local`** command to set a local version of Python for a specific directory, this way you can have a different version of Python for different projects.

To test your installation, you can open a terminal and run the following command:

```bash
python --version
```

This should print the version of Python you have installed, which should be the version you set using **`pyenv`**.

### **Install pip**

**`pip`** is a package manager for Python that makes it easy to install and manage packages. It is included with Python 3.4 and later, so you don't need to install it separately.

If your python version is less than 3.4 then you need to install pip separately

### **Create and activate a virtual environment**

A virtual environment is an isolated environment where you can install packages without interfering with the system-wide packages. To create a virtual environment, you can use the **`venv`** package.

In your project’s directory, run the following command:

```bash
python -m venv venv
```

This will create a new directory called `venv` on your current working directory, where you can install your packages.

To activate your virtual environment, you need to run the following command:

```bash
source venv/bin/activate
```

Once your virtual environment is active, you should see the name of the environment in the terminal prompt, indicating that it is active. Any packages you install while the environment is active will be installed in the **`venv`** directory and will not affect other projects or your system Python installation.

## Use Git to manage your project

### Install Git

The process to install Git on Linux can vary depending on the distribution you are using. You can use the package manager specific to your distribution to install Git.

For example, on Ubuntu or Debian, you can use the **`apt-get`** command:

```bash
sudo apt-get install git
```

On Fedora or CentOS, you can use the **`yum`** command:

```bash
sudo yum install git
```

Once Git is installed, you can check its version running:

```bash
git --version
```

This should print the version of Git installed on your machine.

### Start a local Git repository

To start a local Git repository for your project, you can follow these steps:

```bash
git init
```

This command will create a new **`.git`** directory in your project, which will store all the information about your repository, such as the history of commits and the current state of the project.

### Add Python’s `.gitgnore`

You can download Python’s .gitignore from Github by entering this command on your terminal:

```bash
wget https://raw.githubusercontent.com/github/gitignore/master/Python.gitignore -O .gitignore
```

Now we can stage and commit the **`.gitignore`** file to our local repository by running these commands:

```bash
git add .gitignore
git commit -m "chore: add .gitignore"
```

It's also a good practice to review the contents of the .gitignore file downloaded from Github and modify it as per your specific use case.

You can also add additional files or directories that you want to ignore in your project by modifying the contents of the **`.gitignore`** file and then committing the changes to the repository. This way, you can ensure that the files you want to ignore are consistently excluded from your Git repository in all branches.

You can use conventional commits in your Git repository to make it easier to understand and track the changes that have been made to the code.

[Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)

### Install `black` to code formatting

Black can be installed by running `pip install black`. It requires Python 3.7+ to run.

#### VS Code

If you use VS Code, you can add to your configuration file the following:

```json
{
    "python.formatting.provider": "black",
    "editor.formatOnSave": true
}
```

Don’t forget to also install the recommended Python extensions.

### Create a `requirements.txt` file

To create a **`requirements.txt`** file, you can use the following command:

```bash
pip freeze > requirements.txt
```

This will create a file called **`requirements.txt`** in the current directory and list all the packages with versions that are installed in your environment.

Add the **`requirements.txt`** file to the repository by running **`git add requirements.txt`**

Commit the file to the repository by running **`git commit -m "chore: add requirements.txt"`**

## Create a GitHub repository

Go to the GitHub website (**[https://github.com/](https://github.com/)**) and sign in to your account.

Click on the "+" button in the top right corner of the page, and select "New repository" from the menu. Give a name to your repository and an optional description and choose whether you want your repository to be public or private.

Add the remote repository on GitHub using the command:

**`git remote add origin git@github.com:yourusername/easy_python_project.git`**, replace **`yourusername`** with your github username.

Finally, push your local repository to the newly created GitHub repository by running:

**`git push -u origin main`** or any other branch name you want to push.

## Conclusion

In conclusion, setting up a Python project with Git and GitHub is relatively easy to do.

By following the steps outlined in this article, you'll be able to set up a clean and organized environment for your Python projects, regardless of the operating system you're using.

The important thing to keep in mind is to review the steps and make any necessary adjustments depending on the operating system you are using.

If you have any questions, suggestions or just want to say hi, feel free to reach out to me!

Follow me on [Twitter](https://twitter.com/joaofmaranhao)!