This article provides an overview of Git and GitHub and the workflows you might use when contributing to open source.
Table of ContentsPermalink to “Table of Contents”
- Basic workflows to contribute to open source using Git and GitHub
- Advanced Git and GitHub workflows
- ⭐ Getting the most out of your GitHub profile
- 💡 Resources to learn Git and GitHub
DefinitionsPermalink to “Definitions”
What is Git?Permalink to “What is Git?”
We like this Git definition from Amazon Web Services:
Git is a distributed, open-source version control system (VCS) that enables you to store code, track revision history, merge code changes, and revert to earlier code version when needed.
What is GitHub?Permalink to “What is GitHub?”
Like GitLab and Bitbucket, GitHub is a platform for hosting, sharing, and collaborating on Git repositories.
You can interact with GitHub through the web GUI on their website, and there is also a GitHub CLI if you prefer working with the command line.
Basic workflows to contribute to open source using Git and GitHubPermalink to “Basic workflows to contribute to open source using Git and GitHub”
Forking a repositoryPermalink to “Forking a repository”
Suppose you want to contribute to an open source project. In that case, the first step is to fork the repository to your own GitHub account. Most open sources do not allow you to make and push changes directly in their repository. That's why you want to fork the repository.
Forking means you create a copy of the repository in your GitHub account to make changes without having to push commits directly to the project's original repository.
The steps to do so are:
- Click the "Fork" button on the project's repository page on GitHub.
- GitHub will redirect you to the "Create a new fork" page. Click the "Create fork" button.
By convention, this forked repository is called the
Authenticating with GitHubPermalink to “Authenticating with GitHub”
Suppose you work for the first time with GitHub locally. In that case, you want to know about authenticating your local Git with GitHub before starting cloning a repository.
You must provide your email and credential whenever you clone a repository, commit and push changes, or do other Git activities related to GitHub locally. That is a way for GitHub to authenticate you as the user. But you can set up your credentials locally, so you don't have to input them every time you do a Git activity.
There are three ways to clone a repository:
HTTPS is the most common one to use. You must create a Personal Access Token to enter when GitHub prompts your password.
SSH provides an encrypted way to exchange information safely. You can read here to generate a new SSH key on GitHub.
- GitHub CLI
If you use GitHub CLI, you can copy and run the command in your terminal.
Cloning a repositoryPermalink to “Cloning a repository”
When you want to start working on a change, you want to clone the project's repository after you fork it. That way, you can work on it in the local environment.
To do this:
Go to your forked repository page on GitHub and click the green "Code" button.
Then, you can choose how you want to clone it. Through HTTPS, SSH, or GitHub CLI. For this example, we will use HTTPS.
Copy the URL.
In your terminal, run:
git clone repo-url
repo-urlto the copied URL of the forked repository.
Running this command will set up a copy of the repository on your local computer for you to work with.
Adding an Permalink to “Adding an upstream remote repository”
upstream remote repository
Even though you've cloned the forked repository, you may also want to add the original repository as one of your remote repositories.
This original repository is conventionally called
upstream. By doing this, you can pull other people's changes into your local repository whenever you need.
To add an
upstream repository, run this command:
git remote add upstream repo-url
repo-url with the URL of the original repository.
Check the added remote repositoriesPermalink to “Check the added remote repositories”
Now you have the
upstream as your remote repositories. You can check if they've been appropriately added by running this command:
git remote -v
Running this command will give you a list of your remote repositories.
Create a new branchPermalink to “Create a new branch”
Now you're ready to work on the changes. Always ensure that you work on changes in a new branch and not directly in the
And this new branch is what you will later push to the remote repository.
To create a new branch, run this command in your terminal:
git checkout -b new-branch-name
new-branch-name to whatever you want.
Add and commit changesPermalink to “Add and commit changes”
Say that you've finished making changes, and now you're ready to push your changes to GitHub. You first need to add and commit your changes.
git add . to add all new and modified files to the Git staging area.
git add path if you want to add a specific directory or file.
path to the path of the file that you want to add. For example:
git add styles/header.css
Now you can 'save' your changes by committing with this command:
git commit -m "Your message"
Your message into a short description of what changes you've made. For example:
git commit -m "Add a header to the homepage"
You can check if your changes have been added or committed by running the
git status command in your terminal.
This command will let you know the status of your working git.
Fetching Permalink to “Fetching upstream changes”
Sometimes, someone works in the same file as you. And maybe, that person already pushed their changes and got their pull request merged into the
main branch on the
upstream repository while you are working on yours locally.
So you always want to ensure that your fork is up to date with the
- Go to your forked repository on GitHub.
- Click the "Sync fork" button under the green "Code" button.
- If the buttons are inactive, the repository has no changes. In that case, you can push your changes and make a pull request.
But when the button is green with "Update branch" stated, you want to click it.
Now your fork has the same update as the
Synchronizing changes locallyPermalink to “Synchronizing changes locally”
Now that your
origin repository is in sync with the
upstream, you want to synchronize these changes on your local as well. That way, you already have the most updated content when you push your changes.
You want to fetch and merge the latest update into your working branch. In your terminal, make sure that you're in your working branch. Then run:
git pull origin main
master if the repository uses
master as the name of its default branch.
The command fetches the updated
main branch from the
origin repo and merges that branch into your local working branch.
In this step, you might first need to resolve some conflicts, if any.
Resolve conflictsPermalink to “Resolve conflicts”
It's common to encounter git conflicts when contributing to open source. Conflicts usually occur when changes are on the same line(s), in the same file(s), from 2 different branches.
Say you forget or haven't fetched the
upstream and synchronized it with the
origin and local repositories before pushing your changes.
When you're about to create a pull request on GitHub, you will get notified about the conflicts, if any.
There are two ways to resolve conflicts:
Directly on GitHub
You will get a notification prompt that your branch has conflicts that must be resolved.
Click on the "Resolve conflict" button to fix the conflicts.
However, the best way is to resolve them in your local environment.
In the local environment
Select one of the options:
- Accept Current Change — when you only want to keep your change.
- Accept Incoming Change — when you only want to keep the incoming change.
- Accept Both Changes — when you want to keep both your and the incoming changes.
After resolving the conflicts, if necessary, you can fix and adjust the codes. Then add and commit the changes.
Push changesPermalink to “Push changes”
You have already fetched and synchronized updates and added and committed the changes. Now you can push your changes to the remote repository.
Remember that you will push these changes to the
To do so, run this command in your terminal:
git push origin branch-name
branch-name to your working branch name.
Making a pull requestPermalink to “Making a pull request”
Once you have pushed your changes to the
origin repository, you can submit the changes to the
upstream repository by making a pull request.
Creating a pull request allows the maintainers to review your work, comment, and request any necessary changes. They will then decide to merge your changes into the project codebase or otherwise.
The steps to make a pull request:
- Go to the
upstreamrepository at GitHub and click the green "New pull request" button. If you have recently pushed changes to GitHub, you should see a banner at the top of the page with a "Compare and pull request" button that you can click on.
- You will then get taken to the "Open pull request" form, where you can create a description of your pull request. Here you should check out the project's Contributing guidelines and follow any conventions described. Many projects provide a pull request template within the form to help you get it right.
- Once you are ready, click the "Create pull request" button.
Congratulations! You have made your pull request 🎉!
If a maintainer requests changes, you can make the requested changes and push new commits to the same branch. They will automatically be added to the pull request.
Advanced Git and GitHub workflowsPermalink to “Advanced Git and GitHub workflows”
The following workflows are helpful when collaborating with another person in open source.
Asynchronous collaborating on a shared branch between two different forksPermalink to “Asynchronous collaborating on a shared branch between two different forks”
Let's assume you and your teammate, Alice, forked a project repository. You will collaborate on the same issue in the same file asynchronously. Each of you will do the same steps.
In this example, we will walk you through your point of view.
Add a remote repository
Add Alice's fork as a remote on your local repository by running this command in your terminal:
git remote add alice repo-url
repo-url to the URL of Alice's fork.
alice as the name of the remote repository as an example because we add Alice's fork as one of our remote repositories. But you can name this anything you want.
Fetch Alice's branches by running this command:
git fetch alice
Go to the target branch
git checkout branch-name
branch-name to the target branch name at Alice's fork.
Pull the changes
Pull the changes pushed by Alice with this command:
git pull alice branch-name
Now you have the updated branch version, with the changes from your teammate.
Either you or Alice can submit the pull request once you both have all the work done. Each commit will automatically contain either your or Alice's name. So, both of your contributions are identified.
Synchronous collaborationPermalink to “Synchronous collaboration”
Say sometimes you work synchronously with Alice on the same issue. All steps are the same as the asynchronous collaboration above. But in sync collaboration, you might want to include them in your commit message, so you can commit together.
git commit -m "Add new feature > > Co-authored-by: Alice <email@example.com>"
- Because you are the one who commits the changes, you don't need to include your name in the commit message.
- Always give two empty spaces before writing the line "Co-authored-by".
- Do not close the commit message with double quotes (") before you add the "Co-authored-by:".
- Close the commit message with double quotes (") at the last line of "Co-authored-by:".
- Use the email address associated with your teammate's GitHub account.
⭐ Getting the most out of your GitHub profilePermalink to “⭐ Getting the most out of your GitHub profile”
Do you know that you can customize your GitHub profile? You can add a short bio, website, social media links and customize your pinned repositories to showcase the work you most want the world to see. It would be like a mini portfolio of your own!
How does it work?Permalink to “How does it work?”
To customize your profile, you need to create a repository in your account with the same name as your GitHub username and pop in a README. The contents of that README file will get rendered on your profile page. You can add all kinds of cool integrations to this README to do awesome things on your profile.
These articles can give you some inspiration:
- Creating a Killer GitHub Profile README — Braydon Coyer
- How to create beautiful Github profile README.md — Indrajeet Nikam
💡 Resources to learn Git and GitHubPermalink to “💡 Resources to learn Git and GitHub”
Check out our discussions board if you know of resources we should add to this section! We'd love to hear from you!