Submit your first patch
The GIMP project uses Gitlab’s issue tracker to coordinate bug reports and contributed fixes. Gitlab is also used for enhancement requests and the preferred way to submit patches for GIMP is to make a merge request .
On www.gimp.org you can find a document describing how to report GIMP Bugs . If this is what you were interested in, stop there. The below instructions will go further and explain you what to do to contribute your own code changes.
The instructions in this page also apply for GEGL, babl and other repositories hosted by the GIMP project .
The first step is to get the latest source code and build GIMP. For this, you will be interested by the Setting up your developer environment section.
GIMP relies on various technologies, and if our tutorials are not enough, you should try to document yourself on the proper upstream documentation. Such technologies include:
This may seem obvious but is apparently a big problem for many first-time contributors: what to work on?
The most common advice is: if you use GIMP, did you never encounter a bug or annoyance you wanted to see fixed? This is most often the best tip, because then you have personal reasons to see your contribution through and feel extra rewarded at the end (and each time you use GIMP and the feature you fixed!). Most of us started this way, often with very simple patches on some little issue we had.
Of course, a second good tip is to not necessarily see too big for your first patch, or at least to contribute according to your experience. A total beginner in development trying to implement a very important core feature might just exhaust oneself.
If you have absolutely no such problem of your own, below is a list of links to get you started:
- List of Open Reports
- List of Open Reports tagged for “Newcomers”
- List of Open Bugs (excluding enhancement requests)
To checkout the source of GIMP open the command line and type
git clone https://gitlab.gnome.org/GNOME/gimp
Note: of course, replace the GIT URL and branch names if you want to contribute to another GIMP-hosted project , such as GEGL or babl. From now on, it will be assumed you understood you have to tweak these instructions depending on the actual target project. This is the last time we repeat ourselves about this.
Depending on whether you want to contribute for the stable version only
or the development version, you will have to checkout a specific branch.
GIMP branch naming scheme is that our stable branch is in the form
gimp-<major>-<minor>. Development version is in the historically named
So say you want to fix a bug which happens only in the GIMP 2.10 stable branch, then checkout the branch this way:
git checkout gimp-2-10
On the other hand, to work on the main development branch:
git checkout master
For simplicity sake, in the remnant of this tutorial, we will use the
$BASE_BRANCH to mean either
origin/master depending on the branch you chose here. Each time you
see this variable, remember it means you need to use your own chosen
🔊 For new features or bugs which affect all branches, we request that
you first contribute them on the
master branch. Once it is reviewed
and merged, you are more than welcome to backport the fix or the feature
The reason is pretty simple: if you fix or improve something in a stable
version, then disappear, it creates a regression bug on the development
version (an issue which used to be fixed and not anymore). And that
makes more work for maintainers. So always work on
master first for
anything touching both codebases.
Finally don’t forget you should always work on latest code in your branch, hence pull:
git pull origin
It’s time to write code. By the way, do not forget to read our Coding Style document before writing any code. Having to spend a lot of time on style in the review can feel a waste of time for both you and the reviewer. Ideally you read and follow our guidelines from the start.
We advise to create a local branch for your modifications, as it will make it easier for you to track your work and won’t pollute your main branch (which will be annoying in particular when you want to work on several topics at once).
So first choose a branch name. It can be anything, but a naming scheme
we like in GIMP is naming it like
wip/<your-username>/<meaningful-name>. E.g. imagine you work on fixing
a segfault when doing abc, then I (Jehan) could name my branch
And finally I would create the branch, based on the
codebase (remember: replace
origin/gimp-2-10 if you work for GIMP 2.10 only, as explained
git checkout -b wip/Jehan/fixing-abc-segfault $BASE_BRANCH
This branch will now contain your source. Do changes while on this branch, commit often (this will NOT affect other people’s repository).
ℹ️ At any time, if you forget what is the name of your branch, type
git branch to see which branch you are working on).
To see the status of your branch (which files were changed/added/removed) run:
In order to have a graphical user interface to browse the current state
of the branch, and to see the exact changes you made to specific files,
you can use graphical
git frontends, such as
In order to commit your changes (i.e. save the current state of the source) do:
git commit -a -m "Message"
(replace “Message” with your own message, describing the current commit)
Note that if you have a long commit message (longer than 80 characters), then you should brake it into a summary line (of up to 80 characters) and description lines (directly after the summary) which describe the commit with more details (again, each of the lines should not be more than 80 characters long).
When finished (and committed code one final time), since some time may have passed and you must always submit patches based on the newest code, run:
git rebase $BASE_BRANCH
Fix any merge errors and test your code again (after finishing this,
git rebase $BASE_BRANCH again if it took you long to fix the
Nowadays most people just create merge requests. The process is as follow:
Go on our main repository page: https://gitlab.gnome.org/GNOME/gimp
If you are not logged-in, click the “Sign in / Register” button on the top-right. Create an account if necessary. You may either create an account from scratch with a login and password, or sign in with an existing account from another supported platform (Gitlab.com, OpenID, Github and Google accounts at time of writing).
Once logged, you will see a new “Fork” button (still top-right, but below the “Sign in / Register” button, right next to the “Star” one) with a number next to it. Click this button, then follow the instructions.
Once your fork is created, click the blue “Clone” button to choose one of the clone URLs (SSH or HTTPS). Copy the chosen URL. Let’s say the copied URL is now
Add a remote in your
gitrepository with the following command:
git remote add mine $MY_GIMP_CLONE
mineis just a random name you set for this remote. This is a naming scheme I personally use to differenciate with the
originremote, which is the name I usually keep for the upstream repository.
Now you are free to name it however you want. Some people even do the opposite as they fork first, then clone their own repository (which is called
originby default) and name the upstream repository something else (e.g.
upstream). It’s all up to your workflow choices.
Now push your branch to your repository this way:
git push -u mine wip/Jehan/fixing-abc-segfault
Note: remember that
wip/Jehan/fixing-abc-segfaultis how we named our hypothetical branch. Yours would be called something else.
Once you did all this, go again to GIMP repository web page . Chances are that you will see a green banner at the top saying something like this:
✅ You pushed to wip/Jehan/fixing-abc-segfault at Jehan / gimp 10 minutes ago
Click the “Create merge request” button in the banner.
If you don’t see this green banner (possibly too much time has passed since you pushed), just go to the merge requests page, click “New merge request”, select the source repository (yours) and branch (
wip/Jehan/fixing-abc-segfault), as well as the target repository (
GNOME/gimp) and branch (whatever was
$BASE_BRANCH), then click “Compare branches and continue”.
Fill the various fields appropriately:
- Proper title and description explaining well what your patch is supposed to fix and why.
- Mention a bug report number if it exists.
- Are there any known problems with the patch? It’s alright to send not totally complete patch, for instance if you want to advertize you are working on a bug (avoiding work duplication by other developers), or you feel blocked and need some advices and opinions on your current work-in-progress. When this is the case, explain this clearly in the description and mark the merge request as “Draft” by clicking the “Start the title with Draft:” link just below the “Title” field.
Click “Create merge request”.
Done! You made your first contribution, congratulation!
As an alternative method, we still accept simple patch files, as was done since the dawn of times (or nearly! 🤭).
The command to create a patch in
git is extra easy:
git format-patch $BASE_BRANCH
This will give you patch files in the form of git commits with names
For each one of your commits which is not in
$BASE_BRANCH, a patch
file will be created in the directory (the patch files will be numbered
by the order of the commits). If you want to avoid polluting your
current working directory with many patch files, you can use the
-o <output-folder> option (replacing
<output-folder> with the folder
where you want the patch files to be created of course).
Alternatively if your fix is made in several commits, you may prefer to
have a single file. It is possible by redirecting the output to
then to a file with this command:
git format-patch --stdout $BASE_BRANCH > fixing-abc-segfault.patch
Now, all you have to do is to upload the patch file(s) to the bug report discussing the bug you were fixing or feature you were implementing.
Have proper authorship set up in
Create relevant commit messages.
We are not against multi-commit merge requests/patches. Quite the opposite even! If your code is long and complex, we prefer well compartimented and organized work.
You could have for instance a commit adding a new function in
libgimpand another commit using this new API in plug-ins. Or you could some core concept introduced in
app/core, without any GUI, in a first commit; then create some new fancy widget manipulating this new concept in
app/widgets/, implemented in its own commit; and finally actually use the new widget from
app/dialogs/in a further commit. And so on.
You should avoid just updating your merge request with micro fix commits. I.e. when we review your code and tell you to fix coding style, don’t add a commit “Fix coding style”. Or a commit “Fix a typo”. Even actual bugs, if we see a bug in a commit, just fix the bug within the commit, not separately, so that when we actually merge it, every individual commit is bugless (hopefully!). Therefore you are expected to amend your existing commits with either
git commit --amend(if you just fix your last commit) or
git rebase --interactive(when you need to rebase one or more older commits). We want to merge only clean commits if possible.
Now we understand that this is harder, and it can show more challenging to total beginners as it can feel advanced
gitusage (especially the interactive rebase). This is when we will squash your commits, so don’t worry too much.
On the other hand, if you are an experienced developer and rebasing your branch doesn’t scare you, just feel free to reorganize your commits into nice logical commit units. This is exactly what we like, and don’t mind at all merging a 10-commit merge request if they are all perfectly logical units which a future developer can look at and find useful information for debugging or understanding the original idea of a change.