So, you've decided you’d like to contribute to an open source project – that’s awesome! To make that happen, you’re probably going to need to use a tool called Git. Git can be difficult to wrap your head around the first few times you use it, so this article will break down each step you’ll need to take to complete your first contribution.
About Git
Git is a distributed version control system – which means it’s a tool that lets a group of people collaborate on a shared collection of documents, or codebase, across the internet. It keeps track of every change that’s shared with the group, when it was made, and who made it. It’s sort of like the “track changes” functionality of a word processor, only shared across the internet, and tracking across many documents all at the same time.
A collection of documents managed with Git is called a repository (or repo for short). Frequently, Git repositories will include source code for an open source project, but they can also include plain text documents, HTML, and CSS documents for a website, or even binary format files like images or compiled software programs.
Git Clients
When collaborating on Open Source projects, people typically use Git in a “client-server” model, where there’s one master copy of the repository on an Internet-accessible server (frequently on a site like GitLab or GitHub), and everybody working on the project has their own local "working copy" of the repository on their computer. Changes flow from these local working copies back up to the master repo on the server, and then get sync’d back out to other working copies as people sync back up with the master. Sending changes back to the master copy is called pushing, and getting changes from the master copy into your local one is called pulling or fetching.
It is possible to use Git without a master repository. For example, you can have a local Git repository that’s only on your computer and that isn't shared with anybody else. Conversely, some open source software projects, such as the Linux kernel, have development workflows that involve multiple central servers, with experienced developers carefully syncing changes between them. Most open source projects use the “one master repo” model described above, so that's what we'll focus on while we’re getting started.
There are two kinds of Git clients: command-line (CLI) based, and graphical (GUI). In this article, we’ll focus on using the command-line client (called, unsurprisingly, git). There are a few reasons for starting with the CLI version, including that when you need to do a web search for further Git help (which you will probably need to do at some point!), you’ll likely find instructions that assume you're using the git CLI client. Most importantly, using the CLI client makes what’s happening at each step of the process more apparent.
If you prefer to use a GUI client, you can still follow the steps below, but obviously many details will be different. SourceTree and GitHub Desktop are both highly regarded GUI clients you may want to research and experiment with.
1. Configuring Git
Before you can start working with Git, you need to configure it with your name and email address. Any time you save your changes into your local working copy of a repository, Git will record your name and email as the author of the change. To configure this information, run git config --global --edit in a terminal. This will open up an editor window and provide some default values for your name and email. It should look something like this:
# This is Git's per-user configuration file. [user] # Please adapt and uncomment the following lines: # name = John SJ Anderson # email = genehack@phineas
The default values provided will be extracted from your local environment (phineas is the name of my laptop, for example) – update them to reflect your real email (and name if needed), remove the # character at the beginning of the name and email lines, and then save the file.
Note that by default, Git will use the Vim editor. If you’re not familiar with Vim, it can be a bit intimidating. If you run EDITOR=nano git config --global --edit, Git will use the more user-friendly nano editor instead.
2. Getting a Local Copy of a Repo
Once you've successfully configured Git with your name and email, the next step is to obtain a local copy of the repository of the project you’re interested in contributing to. Since you're trying to contribute to an open source project, it’s probably hosted at GitLab or GitHub. You’ll need to create an account on the site hosting the project you’re interested in, so if you haven't done that yet, take care of that now.
Once you have an account, visit the project on that site, and look for a button near the upper right corner of the screen labeled Fork. Click that to get your own copy (or fork) of the project.
After you have forked your project of interest, you still need to download – also known as cloning – a local working copy. To do that, you’ll need the cloning URL. That will look something like:
https://gitlab.com/infinity-interactive/eleventy-plugin-injector.git
or
git@github.com:genehack/app-gitgot.git
On the GitLab site, that’s available under a button labeled Clone, while on GitHub, it's available under a button labeled Code.
Once you have the cloning URL, you can obtain your local working copy by running git clone <url>. The output from that command should look something like this:
> git clone git@github.com:genehack/app-gitgot.git Cloning into 'app-gitgot'... remote: Enumerating objects: 112, done. remote: Counting objects: 100% (112/112), done. remote: Compressing objects: 100% (75/75), done. remote: Total 2743 (delta 54), reused 72 (delta 33), pack-reused 2631 Receiving objects: 100% (2743/2743), 1.95 MiB | 8.89 MiB/s, done. Resolving deltas: 100% (1318/1318), done.
(Obviously, the cloning URL, project name, and directory created will vary depending on the project you're checking out. Depending on your setup, you may be prompted to enter your password for GitLab or GitHub as well.)
Once you've got your working copy, before you start making any changes, take a look around the top level of the repository. If there are files such as README or CONTRIBUTING.md present, you should carefully review those – they may include important information about how the project maintainers want contributions to be proposed in advance of work being started, or how code contributions should be formatted.
3. Making a Branch
Once you've reviewed the project documentation and you’re ready to start working on your change, you may need to make what’s called a branch. You can think of a branch as a way to have a second version of all the files in your working copy. By switching between different branches, you can effectively have multiple copies of the codebase all within your one local working copy.
You can make a branch and switch your repo over to it using the command git checkout -b <branch-name>. The -b command-line flag will create the new branch, and then the checkout command will switch to that branch. Your repo can only have one branch checked out at any given time; when you want to switch to a different branch, use the checkout command by itself, like so: git checkout <bbranch-name>.
After all this setup, now you’re ready to make your actual contribution to the project! Go ahead and do that now – get a set of changes ready to go. Once you have that completed, you’ll be ready for the next step.
4. Staging Your Changes
To get your changes back into your local working copy, you first need to add them to something Git calls “the staging area.” As you become more experienced with Git, you’ll develop a better appreciation of some of the fancier things you can do with the staging area, but it does take a bit of getting used to at first.
The command you use to add files to the staging area is git add. There’s a special version of it that you’ll want to use at first, which adds all the existing changes in the repo to the staging area all at once: git add .. You should use this version of the command when you’re getting started.
Status Check
Git comes with a command that allows you to see what files in a repo have changes that haven’t been committed yet, and which changes are in the staging area ready to commit to the repository. This command is called git status. The output of this command will look something like this:
❯ git status
On branch main
Your branch is up to date with 'origin/main'.
Changes to be committed:
(use "git restore --staged <file>..." to unstage)
new file: intro-to-git/README.md
Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git restore <file>..." to discard changes in working directory)
modified: intro-to-git/index.md
Reading from the top of the output, you can see that our local working copy has been sync’d with the master repository, and there are two files with changes, intro-to-git/README.md and intro-to-git/index.md. The former has been added to the staging area and is ready to commit, or check-in, to the local repo. The latter has changes but hasn’t yet been added to the staging area, so it won't be part of the commit.
5. Making a Commit
When you make a git commit, the contents of the staging area will be added (sometimes called checked in or committed) to your local working copy. Each commit has a commit message associated with it, which should explain both what was changed, and why it was changed. Git commit messages are modeled on email messages, with a one-line initial subject, followed by a longer message if needed.
You can commit your staged changes with the command, git commit. By default, that will open up an editor window to allow you to type a commit message. Just like when you were setting up your configuration, by default, Git will use the vim editor. If you’d like something a bit easier to use, run EDITOR=nano git commit.
Finally, if you’d prefer to type your commit message directly into the command line, you can use the -m flag, like so: git commit -m "this is my change.".
When you run git commit, you should see output like this (albeit reflecting your commit message and the changes you’re committing):
> git commit -m"add README to intro-to-git" [main 20897ff] add README to intro-to-git 1 file changed, 10 insertions(+) create mode 100644 intro-to-git/README.md
6. Pushing
Now that your change has been committed to your local working copy, you need to sync that back up to your server. You do that with the git push command. The output from that will look something like this:
❯ git push Enumerating objects: 6, done. Counting objects: 100% (6/6), done. Delta compression using up to 4 threads Compressing objects: 100% (4/4), done. Writing objects: 100% (4/4), 674 bytes | 674.00 KiB/s, done. Total 4 (delta 1), reused 0 (delta 0), pack-reused 0 remote: . Processing 1 references remote: Processed 1 references in total To github.com:genehack/writing.git e0cbff8..20897ff master -> master
As always, some details – like the server, repo, and branch names – will be different. You may also be prompted for your GitLab or GitHub password at this point.
7. Creating a Pull Request
There’s one final step you need to complete to get your change in front of the folks who run the project you’re trying to contribute to. You need to create what’s called a pull request – asking the project to pull your changes from your fork of the project repository into the master, or upstream version of the repo.
This step will allow the maintainers of the project to review your change, provide feedback, and eventually incorporate your changes into the project (also known as merging). You may also need to sign a contributor agreement or copyright assignment – somebody from the project will let you know if that is required.
To create your pull request, you should visit the webpage for your fork of the project on GitLab or GitHub. Once you’ve pushed a change up to the site, there will be a button to let you create a pull request (or PR) that will be sent to the project maintainer.
Once your change is merged into the project, the next released version will include your contribution and you’ll officially be an open source contributor!
Comments