<commit_before>---
title: "Contributing code with git"
date: 2019-09-01
tags:
- dev
---
You want to contribute code. You use git. How to?

<p class="note note--info">
  This is a completely rewritten version of the article <a href="https://kleinfreund.de/contributing-code/">Contributing code: Besting git, but slowly</a> I published last year. You really don’t need to read it before this one.
</p>

Contributing code to an open source project you don’t own or maintain can be a daunting task if you haven’t done it before. What does contributing code even mean?

Let’s say there is this open source tool you use. It works well for the tasks you use it for, but it has this one flaw that annoys you. You think to yourself “Hey, what if I could make this right?”. You find the project’s repository online and look through its code. After a while, the faulty bit has been identified. You devise a solution, but what now? How do you fix the tool? How do you contribute your code to the project?

In git land, code contributions are commonly done by submitting a pull request. In non-technical terms, a pull request says “Hey, that thing of yours is a bit broken”, and “I’ve made some changes to it”, and finally asks “Do you want to use these changes in your project?”. In this article, we’re going through the process of contributing code to an open source project with git step by step.



## Table of contents

- [The scenario](#the-scenario)
- [Setting up](#setting-up)
- [Doing work](#doing-work)
- [Losing touch](#losing-touch)
- [Keeping a fork up-to-date](#keeping-a-fork-up-to-date)
  - [Updating the local repository](#updating-the-local-repository)
  - [Updating the fork](#updating-the-fork)



## The scenario

First, let’s clarify some terms that I’m going to use. I’ll keep it short and use simplified definitions.

- **Repository**: A directory of files that belong to a project.
- **Remote repository**: A repository that is stored somewhere online.
- **Fork**: A copy of a repository that you manage. You can change things in it.
- **Original**: The original project repository you want to contribute to. You can’t change things in it.
- **Commit**: A commit is a collection of changes that has a unique identifier.
- **Branch**: A repository can have multiple branches. They allow you to work on various things in isolation. You can think of branches as copies of your files.

Now, what _is_ the scenario? You want to contribute code to the original repository. To do that, you create a fork of the original. You manage this copy of the original repository, so you can make changes to it as you wish. You will use this copy later to show your changes to the maintainers of the original repository. To make your changes in the fork, you download a copy of the fork that you can work on locally. In this scenario, there are three different repositories one can talk about: the original (remote), the fork (remote), and the copy of the fork (local).



## Setting up

I will use the repository [github.com/kleinfreund/poll](https://github.com/kleinfreund/poll) as an example for a project to contribute to.

1. Fork the [original repository](https://github.com/kleinfreund/poll).
2. Download the fork. Replace the repository URL below with the one of the fork you just created.

    ```sh
    git clone https://github.com/<YOUR-USERNAME>/poll.git
    ```

3. Navigate to the repository.

    ```sh
    cd poll
    ```

4. Add a reference to the original repository.

    ```sh
    git remote add original https://github.com/kleinfreund/poll.git
    ```

5. Rename the reference to the fork.

    ```sh
    git remote rename origin fork
    ```

    This step is not necessary. I only do that to avoid confusion between the terms “original” and “origin”.

You now have a local copy of the fork. Your local copy knows about the two remote repositories, original and fork, which you can verify by running `git remote -v`:

```sh
$ git remote --verbose
fork    https://github.com/<YOUR-USERNAME>/poll.git (fetch)
fork    https://github.com/<YOUR-USERNAME>/poll.git (push)
original            https://github.com/kleinfreund/poll.git (fetch)
original            https://github.com/kleinfreund/poll.git (push)
```

There, git lists names of remote repositories and their respective repository URLs.



## Doing work

Before you start changing anything, you should create a new branch that contains your work. This is a very useful habit to develop right away. It creates a kind of checkpoint marking the state of your repository before you changed anything. You can create multiple branches from the main branch of your repository to work on multiple things in isolation. Also, it allows you to go back to the repository’s main branch and start over if you messed something up along the line.<commit_msg>Remove incorrect code block language<commit_after>---
title: "Contributing code with git"
date: 2019-09-01
tags:
- dev
---
You want to contribute code. You use git. How to?

<p class="note note--info">
  This is a completely rewritten version of the article <a href="https://kleinfreund.de/contributing-code/">Contributing code: Besting git, but slowly</a> I published last year. You really don’t need to read it before this one.
</p>

Contributing code to an open source project you don’t own or maintain can be a daunting task if you haven’t done it before. What does contributing code even mean?

Let’s say there is this open source tool you use. It works well for the tasks you use it for, but it has this one flaw that annoys you. You think to yourself “Hey, what if I could make this right?”. You find the project’s repository online and look through its code. After a while, the faulty bit has been identified. You devise a solution, but what now? How do you fix the tool? How do you contribute your code to the project?

In git land, code contributions are commonly done by submitting a pull request. In non-technical terms, a pull request says “Hey, that thing of yours is a bit broken”, and “I’ve made some changes to it”, and finally asks “Do you want to use these changes in your project?”. In this article, we’re going through the process of contributing code to an open source project with git step by step.



## Table of contents

- [The scenario](#the-scenario)
- [Setting up](#setting-up)
- [Doing work](#doing-work)
- [Losing touch](#losing-touch)
- [Keeping a fork up-to-date](#keeping-a-fork-up-to-date)
  - [Updating the local repository](#updating-the-local-repository)
  - [Updating the fork](#updating-the-fork)



## The scenario

First, let’s clarify some terms that I’m going to use. I’ll keep it short and use simplified definitions.

- **Repository**: A directory of files that belong to a project.
- **Remote repository**: A repository that is stored somewhere online.
- **Fork**: A copy of a repository that you manage. You can change things in it.
- **Original**: The original project repository you want to contribute to. You can’t change things in it.
- **Commit**: A commit is a collection of changes that has a unique identifier.
- **Branch**: A repository can have multiple branches. They allow you to work on various things in isolation. You can think of branches as copies of your files.

Now, what _is_ the scenario? You want to contribute code to the original repository. To do that, you create a fork of the original. You manage this copy of the original repository, so you can make changes to it as you wish. You will use this copy later to show your changes to the maintainers of the original repository. To make your changes in the fork, you download a copy of the fork that you can work on locally. In this scenario, there are three different repositories one can talk about: the original (remote), the fork (remote), and the copy of the fork (local).



## Setting up

I will use the repository [github.com/kleinfreund/poll](https://github.com/kleinfreund/poll) as an example for a project to contribute to.

1. Fork the [original repository](https://github.com/kleinfreund/poll).
2. Download the fork. Replace the repository URL below with the one of the fork you just created.

    ```sh
    git clone https://github.com/<YOUR-USERNAME>/poll.git
    ```

3. Navigate to the repository.

    ```sh
    cd poll
    ```

4. Add a reference to the original repository.

    ```sh
    git remote add original https://github.com/kleinfreund/poll.git
    ```

5. Rename the reference to the fork.

    ```sh
    git remote rename origin fork
    ```

    This step is not necessary. I only do that to avoid confusion between the terms “original” and “origin”.

You now have a local copy of the fork. Your local copy knows about the two remote repositories, original and fork, which you can verify by running `git remote -v`:

```
$ git remote --verbose
fork    https://github.com/<YOUR-USERNAME>/poll.git (fetch)
fork    https://github.com/<YOUR-USERNAME>/poll.git (push)
original            https://github.com/kleinfreund/poll.git (fetch)
original            https://github.com/kleinfreund/poll.git (push)
```

There, git lists names of remote repositories and their respective repository URLs.



## Doing work

Before you start changing anything, you should create a new branch that contains your work. This is a very useful habit to develop right away. It creates a kind of checkpoint marking the state of your repository before you changed anything. You can create multiple branches from the main branch of your repository to work on multiple things in isolation. Also, it allows you to go back to the repository’s main branch and start over if you messed something up along the line.
{'fraction_non_alphanumeric': 0.07881364720522659, 'fraction_numerical': 0.0026962563517577516, 'mean_word_length': 3.753080335140463, 'pattern_counts': {'":': 0, '<': 17, '<?xml version=': 0, '>': 17, 'https://': 18, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3743407', 'n_tokens_mistral': 2605, 'n_tokens_neox': 2504, 'n_words': 1426}