Guide to contributing on GitHub
This guide covers contributing to the GRASS source, specifically to the main branch. It assumes that you have some very basic knowledge of Git and GitHub.
First time setup
- Create an account on GitHub.
- Install Git on your computer.
- Set up Git with your name and email.
- Fork the repository (by clicking the
Fork
button in the upper right corner of the GitHub interface). - Clone your fork (use HTTPS or SSH URL, here we will use HTTPS):
git clone https://github.com/your_GH_account/grass.git
- Enter the directory:
cd grass/
- Add the main GRASS repository as "upstream" (use HTTPS URL):
git remote add upstream https://github.com/OSGeo/grass
- Your remotes now should be "origin" which is your fork and "upstream" which is this main GRASS repository. You can confirm that using:
git remote -v
- You should see something like:
origin https://github.com/your_GH_account/grass.git (fetch)
origin https://github.com/your_GH_account/grass.git (push)
upstream https://github.com/OSGeo/grass (fetch)
upstream https://github.com/OSGeo/grass (push)
For the following workflow, it is important that "upstream" points to the OSGeo/grass repository and "origin" to your fork (although generally, the naming is up to you).
Update before creating a feature branch
Make sure your are using the main branch to create the new branch:
git checkout main
Download updates from all branches from the upstream remote:
git fetch upstream
Update your local main branch to match the main branch in the upstream repository:
git rebase upstream/main
Notably, you should not make commits to your local main branch, so the above is then just a simple update (and no actual rebase or merge happens).
Creating a new feature branch
Now you have updated your local main branch, you can create a feature branch based on it.
Create a new feature branch and switch to it:
git switch -c new-feature
Committing
Add files to the commit (changed ones or new ones):
git add file1
git add file2
Commit the change. Write a meaningful commit message (first word is for example the tool name):
git commit -m "tool: added a new feature doing X"
Pushing changes to GitHub
Push your local feature branch to your fork:
git push origin new-feature
Creating a pull request
When you push, GitHub will respond back in the command line to tell
you what URL to use to create a pull request (PR). You can follow that URL
or you can go any time later to your fork on GitHub, display the
branch new-feature
, and GitHub will show you a button to create
a PR.
Alternatively, you can explore GitHub CLI tool (gh) which allows you
to do git push
and create a PR in one step with gh pr create -fw
.
Guidelines for writing a meaningful pull request
A well-written pull request clearly conveys the purpose and impact of the proposed changes.
PR Title
The title should be descriptive and clearly summarize the main purpose or change
in the pull request. Start the title with the tool name or a
keyword (e.g.:
tool name: Add functionality Y for Z
. Keep it short, i.e. aim for concise titles,
typically under 50-60 characters.
PR Content
A pull request requires an abstract, change details, and more. When you create the new PR, you are presented with a template to help standardize the content.
After creating a PR
GRASS maintainers will now review your PR. If needed, the maintainers will work with you to improve your changes.
Once the changes in the PR are ready to be accepted, the maintainers will usually squash all your commits into one commit and merge it to the main branch.
Once the PR is merged, it is a good time to update your local main branch in order to get the change you just contributed.
Further notes
Here we cover common situations and how to deal with them:
Update if you have local changes
Assumption is you are on the main branch and you are trying to update it.
If git rebase
fails with error: cannot rebase: You have unstaged changes...
,
then move your uncommitted local changes to "stash" using:
git stash
Now you can rebase:
git rebase upstream/main
Get the changes back from stash:
git stash pop
Updating your PR from main
Updating your PR from the main branch is often referred to as rebasing a PR. It comes into play in case there are changes in the main branch you need to incorporate into your (feature or fix) branch before the PR can be merged, you need to merge the upstream main into your branch:
git fetch upstream
git merge upstream/main
Git will ask you to edit the merge commit message, you can leave the default and close the editor. You may run into a conflict, in that case you need to resolve it.
Testing PRs from other contributors
For testing other contributors' PRs, we recommend using GitHub CLI. To checkout a specific PR, run:
gh pr checkout <PR number>
SOURCE CODE
Available at: github_guide source code
(history)
Latest change: Tuesday Jun 03 08:05:08 2025 in commit 7fd42d6