Git for contributors
You might be used to working with source control either alone or with others. Working with a fork and making sure we can merge swiftly brings some additional challenges. This page aims to help you out with the things you might get asked to do but may be outside your comfort zone.
Sit back, relax and maybe bring a brew.
If you're not comfortable using Git from the CLI, we advise using GitKraken. GitKraken is a great GUI for version control and is very useful for beginners and advanced developers alike.
I didn't stick to the conventional commit guidelines¶
Some projects have specific guidelines and conventions for commits and pull requests. Sometimes we make a mistake and forget to follow those conventions.
I only have one commit¶
To reword the last commit, we can use Git's
--amend switch to add something to our latest commit (code, changes, rewording). Use the following commands to rephrase the last commit and get that change merged!
I added more than one commit¶
Suppose all of your commits need to go to
main because it makes sense to treat these as atomic units. In that case, you can use Git's interactive rebase functionality to reword any commit between
main and your
HEAD. To start an interactive rebase, type:
This will open your
$EDITOR, and you can mark the commits you want to reword with
r) rather than pick. Exiting that file will start the rebase and spawn your
$EDITOR to alter the commit message for each commit you marked as reword.
Once done, use
git push --force to bring the changes to the pull request.
For VSCode users.
The latest version of VSCode has a built-in GUI to help you select
reword or any other action on a commit. Select the right ones and press Start Rebase to continue.
My branch is out of date with the remote¶
This means the main branch of the project you are working on contains commits your branch does not (could be your
main branch or the branch you created to work on). To fix this, we need to rebase (add the new commits of the project's main branch underneath your new commits), so the pull request can get merged.
The first thing to do is add the project codebase as a
remote to your local git repository. By default, your fork is a standalone copy of the project with its own remote on GitHub that's not connected to the upstream project codebase. Forks and Pull Requests are a feature GitHub introduced on top of git functionality, so we need to mimic that situation ourselves.
Follow these steps:
Add the remote to your local git repository
git remote add upstream email@example.com:<org>/project.git
Make sure to replace the organisation or user and repo accordingly.
Update the remote repository (now called
git fetch upstream
Rebase the branch onto
1 2 3 4 5 6
# go to the feature branch git checkout my-feature # make a backup in case you mess up git branch tmp my-feature # rebase on the upstream main branch git rebase upstream/main
Push your changes and remove the backup branch:
1 2 3
git push --force # delete back up git branch -D tmp
I have messed something up¶
Sometimes, you mess up merges or rebases. Luckily, in Git it is relatively straightforward to recover from such mistakes.
If you mess up during a rebase, you need to type the following command:
If you only noticed the mistake after the rebase
If you forgot to make a backup branch during the rebase:
1 2 3 4 5 6 7 8 9 10
If you didn't mess up, but there are merge conflicts, you need to resolve those. This can be one of the trickier things to get right. For a good description of how to do this, see this article on merging conflicts or this tutorial.
Delete a branch¶
Maybe your branch has been merged into
main, and you no longer need it. To delete a branch, you need to:
1 2 3 4 5
You might also want to check this StackOverflow answer on how to delete local and remote branches.
Additional Git resources¶
- github help has an excellent series of how-to guides.
- learn. github has an excellent series of tutorials
- The pro git book is a good in-depth book on Git.
- git ready - a nice series of tutorials
- GitFlow etiquette if you want to dive more into GitFlow and how to collaborate with others