A simple Git guide and cheat sheet for open source contributors

Contributing to open source projects is a rewarding way to learn, share knowledge, and build experience. But if you‘re new to Git and GitHub, the process can seem daunting at first.

This step-by-step guide will walk you through the entire workflow, from forking a repository to submitting your first pull request. It also serves as a handy reference with a cheat sheet of key Git commands. Let‘s get started!

Prerequisites

Before you can start contributing, make sure you have:

1. A GitHub account
2. Git installed on your local machine (installation guide)
3. A text editor or IDE for coding

Key concepts

Here are some key Git terms to understand:

• Repository (repo): The project folder that contains all the files and revision history
• Fork: A copy of a repository in your own GitHub account
• Clone: Downloading the repository files to your local machine
• Branch: An independent line of development, so you can work without messing with the "master" branch
• Commit: Saving your changes to the local repository
• Push: Uploading your local commits to a remote repository, like your fork on GitHub
• Pull request (PR): Proposing your changes to be merged into the original repository

Step 1: Fork the repository

Go to the repository you want to contribute to on GitHub and click the "Fork" button in the top right corner. This will create a copy of the repo in your own GitHub account that you can freely experiment with.

Step 2: Clone your fork locally

Next, you‘ll download a local copy of your fork to work on. On the main page of your forked repo, copy the URL for cloning. Then open your terminal and run:

git clone https://github.com/your-username/repository-name.git

Replace the URL with the one you copied from your fork. This will create a local directory with all the repository files.

Step 3: Add upstream remote

To keep your fork in sync with the original repository, add it as a "remote" called upstream:

git remote add upstream https://github.com/original-owner/repository-name.git

You can verify it was added by running:

git remote -v

Step 4: Create a branch

Rather than making changes on the default "master" branch, create a new branch for each contribution you make. This keeps your master branch clean and allows you to work on multiple contributions at once.

To create a branch and switch to it:

git checkout -b branch-name

Choose a concise, descriptive name for your branch, like "fix-typo-in-readme".

Step 5: Make your changes

Now you can open the files in your favorite editor and make the necessary changes to fix a bug, add a new feature, improve documentation, etc.

Step 6: Commit your changes

After making changes, you need to "commit" them to your local repo. First, see which files were changed:

git status

Review the list to make sure you‘re only committing what you intend to. Then stage the files to be committed:

git add path/to/file1 path/to/file2

You can also use git add . to stage all changed files at once, but be careful not to include unwanted changes.

Commit the staged files with a meaningful message describing what you changed:

git commit -m "Fix typo in introduction paragraph"

Step 7: Pull latest changes from upstream

Before pushing your local changes to your fork, pull down any new changes that were merged into the original repo in the meantime:

git pull upstream master

If there are any merge conflicts, Git will alert you and add markers in the affected files to show the conflicting changes. Edit the files to resolve the conflicts, then commit the result.

Step 8: Push to your fork

With your local branch up to date, you can push your commits to the corresponding branch on your GitHub fork:

git push origin branch-name

Step 9: Open a pull request

Now that your changed branch is pushed to your fork, you can propose those changes to the original repository through a pull request.

On your fork‘s page on GitHub, you should see a "Compare & pull request" button. Click it, then fill out the title and description fields to explain what you changed and why. Lastly, click "Create pull request" to submit it for review.

Step 10: Respond to code review

Project maintainers and other contributors will review your pull request and may request changes before merging it. Check back on the PR page and respond to any comments.

If you need to make more changes, simply commit them to your local branch and push to your fork again. The new commits will automatically get added to the existing PR.

Step 11: Clean up

After your pull request is merged, you can delete the branch on GitHub and locally:

git checkout master
git push -d origin branch-name  
git branch -d branch-name

Then sync your local master branch and fork with the latest changes in upstream:

git pull upstream master
git push origin master

Cheat sheet

Here‘s a quick reference for the most used Git commands in this workflow:

git clone url                # Clone a repository
git checkout -b name         # Create a branch and switch to it
git status                   # See what files changed  
git diff                     # See changes in unstaged files
git add path/to/file         # Stage a file
git commit -m "message"      # Commit staged files
git pull remote branch       # Pull changes from a remote branch
git push remote branch       # Push local commits to remote branch  
git log                      # View commit history
git reset file               # Unstage a file
git stash                    # Stash uncommitted changes

With practice, this workflow will become second nature. The open source community is very welcoming of new contributors, so don‘t be afraid to dive in! Always be respectful and follow each project‘s code of conduct and contribution guidelines. Happy coding!