Git - GnuCash

Git - GnuCash
Git
From GnuCash
Jump to:
Languages
עִברִית
Git
is a
distributed
version control system
(VCS). The GnuCash project uses Git to manage it's sources (code and bundles, docu and website).
If you are new to version control or to using git, you may find it useful to read
An Introduction to Git
for more information about specific git commands, how they are used in the process of modifying GnuCash, and how to submit changes for review using pull requests (preferred) instead of patches.
Contents
Introduction
1.1
Server
1.1.1
code.gnucash.org
1.1.2
GitHub
1.2
Repositories
1.3
Branches
1.3.1
Branch Policy
1.3.1.1
Git Flow
1.3.1.2
Beta Testing
1.3.2
Basics
1.3.2.1
One local repository and multiple working directories
1.3.2.2
Getting commits from other branches or repos
1.3.2.3
Patches
Using the Github Repository
2.1
User and "Normal" Contributors
2.1.1
Set-Up
2.1.1.1
GitHub Users
2.1.2
Pull Requests
2.1.3
Patches
2.2
Core Developers
2.2.1
About Write Access
2.2.2
Set up
2.2.2.1
Generate your ssh key pair
2.2.2.1.1
Under Linux or under Windows with MSYS
2.2.2.1.2
Under Windows with Putty for TortoiseGit
2.2.2.2
Clone the Repositories
2.2.2.2.1
TortoiseGit on Windows
2.2.3
Committing
2.2.4
Branching and Merging
2.2.5
Pushing onto another core developer branch
2.2.6
Bugs and New Features
2.2.6.1
Resolving Merge Conflicts
2.2.7
Link Bugzilla Entries
2.2.8
Patches and Pull Requests
2.2.8.1
Pull Request Notes
2.2.8.2
Advanced Pulling
Collaboration
Accessing GnuCash BugZilla from Git
Related Topics
Introduction
Server
While you enter most commands you are working on your
local
repository. To set it up, you need to connect it with one or more servers, which host the
remote
repositories and
clone
that onto
your local computer
or
fork
it into
your personal github repository
code.gnucash.org
code.gnucash.org
is the server that hosts the
canonical git repository
, this wiki,
Mailing Lists
IRC
logs
, the nightly builds of the
documentation and API docs
(via
Doxygen
) for important
branches
, and automated win32 builds. Write access to this repository is limited to core developers who have been given ssh keys; contributors without commit permissions will not access this repository directly.
GitHub
GitHub
is a web-based Git repository
hosting service
Our
public repositories
are mirrored on GitHub.
These are updated from the
primary repository
by commit hooks, so barring technical problems changes appear in these repositories within a few seconds of being committed to the primary.
Repositories
They host since 2014-02 all GnuCash repositories:
General Sources
gnucash.git
the program,
gnucash-docs
its user documentation,
gnucash-htdocs
our webserver; if you cloned/forked it before 2013-01 see
Htdocs Split
OS specific packages bundling all dependencies
gnucash-on-flatpak
Linux
Flatpak
gnucash-on-osx
Gtk-OSX moduleset, gtk-mac-bundler bundles, and ancillary files for creating GnuCash OSX Application Bundle.
gnucash-on-windows
Windows installer and build script moved here from gnucash/packaging.
See the full list at
github.com/Gnucash
Branches
Branch Policy
Git Flow
Gnucash uses a variation of the
Git Flow
process for managing changes. Think of
stable
as "lower",
unstable
as "intermediate" and
future
as "higher".
[1]
Branches are periodically merged "upwards", meaning that
stable
is merged into
future
. When
unstable
exists "upwards merging happens in three stages instead:
stable
is merged into
unstable
and
unstable
into
future
. Merges are done at least at every release but generally more often as it's much easier to manage merge conflicts when there are fewer commits. Developers are encouraged to merge upwards immediately after making a big change so that they can handle the merge conflicts with the new code fresh in their minds.
Beta Testing
When we get close to releasing a new stable series culminating the development on the
future
branch we make a new branch
unstable
from it and make releases with an odd minor number. For example,
before the next major release we (will) have a series 5.9xx,
leading up to the 2.6.0 release we had a release series 2.5.x.
This releases allow users to help test the program and to try out the new features.
unstable
is between
stable
and
future
in the Git Flow hierarchy, so
stable
is merged into
unstable
when it exists and
unstable
into
future
. When we decide that it's stable we do a final merge of
stable
into
unstable
and delete the
stable
branch then rename
unstable
to
stable
as it's the new stable branch.
Basics
There are 3 important branches in our more complex repositories for
program
and
documentation
future
Major new features
, dependencies, and their documentation should be based on this branch.
unstable
only exists when we're close to a new major release and will be used to make beta releases from. Anything required to get the beta code into shape for a release should be applied to this branch.
stable
is our default branch in git.
Bugfixes
minor new features
translations
, and
improvements
to the
documentation
or the
program
should usually be applied on this branch.
And you should create temporary
working branches
based on them for nontrivial patchsets:
git branch bugXXXXXX
In your
local working dir
you should checkout one of them, e.g.:
git checkout future
Later you should
recurrently
integrate remote changes, but usually only before you publish your changes i.e. by a PR:
git pull
In its default mode,
git pull
is shorthand for
git fetch
(update your
local repo
), followed by
git merge FETCH_HEAD
resulting in an update of your
current
branchs
working dir
One local repository and multiple working directories
After a normal
git clone
you will have
the main as your
source
directory and inside
the hidden
.git
directory with the metadata or administrative files.
Because it is time consuming to rebuild almost everything after you switched between different branches of the
program
, you can since Git 2.5
[1]
git clone --bare …
# to suppress the creation of the main worktree
# or
git clone --mirror …
# same, but also track remote branches,
# get informed about pull requests as refs
git worktree add

to create separate working directories for different branches.
Example
mkdir gnucash
cd
gnucash
git clone --mirror https://github.com/Gnucash/gnucash.git .git
git worktree add stable stable
git worktree add future future
git worktree list
# show list of worktrees
Getting commits from other branches or repos
The simple form
git cherry-pick
options
...
will apply the changes from one or more commits on your
current clean branch
. This is very handy if you want to reorder your patches or amend an older patch than the last.
Before you publish your branch you should often run
git rebase
options
. This will inserts new commits
from remote
or one of your other branches
in front of your commits
(rewriting the deltas (diffs) of your commits).
Because the diffs will be rewritten, the hash/ID of the commits change and it should not be used on already published branches. Although, if the core developers agree, it can be used together with a
forced push
Finally usually core developers will
git merge
options
your published working branch into the official branch.
Patches
When you have patches in
future
, use
git format-patch origin/future..future
or
git diff
in the root directory of your local working directory to prepare them; then add the patchfile as an attachment to the appropriate bug report.
Using the Github Repository
User and "Normal" Contributors
If you are new to using git, you may find it useful to read
An Introduction to Git
for more information about specific git commands and how they are used in the process of modifying GnuCash.
Set-Up
Just clone the repository as usual:
git clone https://github.com/Gnucash/gnucash.git
other URLs
(documentation)
(website)
See
for further repos e.g. with OS/distro specific build scripts.
Note
Because of some major source directory restructuring in
2017 in GnuCash or
2022 in gnucash-docs
you should increase the
merge.renamelimit
from its default of
1000
in your gnucash repository:
git config merge.renameLimit
3000
Else the history gets broken and rebasing future on stable will produce strange results.
GitHub Users
If you have a Github account or wish to send
#Pull Requests
, you can use Github's
fork
feature to set up a
clone
of the one of the GnuCash repositories. Then, you would clone from that repository instead (note that this is your personal
read-write enabled
clone):
git clone git@github.com:/gnucash.git
. Note that this clone command takes the
URL in a different format
With this, you will be able to push your local changes to your forked repository:
git push origin future
. Later, you can issue a
#Pull Request
to have your changes incorporated into the project.
Depending on your access rights you might continue with ...
#Pull Requests
#Core Developers
Pull Requests
If you prefer, you can use a GitHub Pull Request instead of attaching a patch to a bug.
Fork the Gnucash/gnucash or Gnucash/gnucash-docs repo on GitHub. You'll need to create a GitHub account if you haven't got one already and set it up for ssh access. In the example below, we'll assume a GitHub userid of "Me". Substitute your real id.
Add that branch as a remote in your local repository and push your working branch to it:
git remote add github ssh://git@github.com/Me/gnucash
git branch -u github working-branch
apply your changes and
git push
Now log in to your GitHub account, go to your forked gnucash repository, select
working-branch
from the pick list, and click
pull request
. It's above the "last commit" line on the right in the directory view.
In the resulting form, give your pull request a title and describe its motivation. If it's associated with a bug, use the bug number and title for your title and paste the bug URL into the description. Note that GitHub descriptions use Markdown and that there's a preview tab to help you make sure that everything looks the way you want it.
Click the
Send Pull Request
button to the right of the description block.
If a developer
requires changes
to your pull request, you can either
add
further commits and
push
or
amend
your commits as necessary and
force-push
your branch.
Don't make any changes to that working branch that aren't associated with the pull request!
Once the pull request has been either merged or rejected, you can delete the branch:
git branch -D working-branch
git push github :working-branch
If you want to continue in between with something else create another branch.
Patches
If you're going to be submitting patches:
Create a branch to work in:
Bug fixes
and
Minor new features
should branch off of
stable
unless the bug applies only to the future branch.
Major new features
must branch off of
future
The following example is for a major new feature;
substitute
stable
for
future
if you're doing a bug-fix or a minor new feature
Use a particular working branch for
only one
bug or feature. This will make it much easier to make changes and generate new patches should that prove necessary.
git checkout -b working-branch stable
Rebase your working branch onto the target branch often so that you stay in sync:
git rebase stable working-branch
Open a bug in Bugzilla to attach your patch to if one doesn't already exist.
Write good commit messages in which the bug number and summary are the first line. Skip one line, then describe the patch. For example:
[Bug 673193] - Possible Register migration to TreeView
Update the old register rewrite branch to work with the currently-released Gtk2.
Use
git rebase -i
interactive
) as necessary to make a clean series of patches for complex changes.
Be sure to do a fresh rebase from the target branch and a make check to ensure that everything works
Use
git format-patch
to create the actual patches from your commits:
git rebase future working-branch
git format-patch future
Attach the resulting patch(es) to the bug report.
If a committer asks you to make changes, revise your original commit and make a new patch. Don't submit a patch to be applied on top of an old one.
git-rebase
-i
can be very helpful if you have a series of patches.
Core Developers
About Write Access
While it is possible for new developers to get write access, the project is quite conservative with giving out new SSH write accounts. For occasional changes, people are encouraged to use the procedures outlined above. People can get added as developers if they stick around, supply lots of patches, become highly involved in the project, hang out on IRC, and generally show some level of clue and prove some level of trust.
Set up
Note
: this set up presumes you already have commit access to the GnuCash repositories on code.gnucash.org. If you don't but believe you should, ask for this on the gnucash-devel mailing list.
Generate your ssh key pair
Under Linux or under Windows with MSYS
To set up ssh with the MSYS client, proceed exactly as here.
You'll need to generate a key-pair and provide the public half to the GnuCash repository administrator. To generate a key pair use
ssh-keygen -t rsa -b
1024
-f gnucash-key
Notes
You can use any name you like instead of "gnucash-key".
You will also be prompted for a
passphrase,
with the option to leave it blank. If you provide a passphrase, you will be prompted to provide it every time you use your private key. If you don't, anyone who gains access to your private key can connect to whatever servers you protect with it.
You will find your
private
gnucash-key
and
public
gnucash-key.pub
keys in
~/.ssh/
Warning
If something goes wrong with the next command, your IP will get blocked
from all services
running on code.gnucash.org for one hour.
Once you have the key configured correctly and have provided it to the GnuCash repository administrator, try
ssh -i gnucash-key git@code.gnucash.org
You'll get the usual ssh question about the
fingerprint
for a new host. It should be
20:23:3d:df:f3:13:34:c1:32:ca:11:77:24:21:98:01
. If it is, answer "yes" to add it to your known hosts file. If you get a message followed by a list of repositories, your setup is correct and you can proceed.
Next, you'll want to to configure your local ssh client to always provide this key when connecting to code.gnucash.org. In addition, ssh should always connect as user 'git'.
On linux, you can set this up by adding the following lines in your
ssh config file
(~/.ssh/config):
Host code.gnucash.org
IdentityFile ~/.ssh/gnucash-key
User git
Then you can shorten the call from above to
ssh code.gnucash.org
(Continue with
#Clone the Repositories
Under Windows with Putty for TortoiseGit
For [
TortoiseGit
], you'll also need PuttyGen and Putty from [
PuTTY
].
Setting up Pageant to work with TortoiseGit is a bit involved, so we'll go through it step-by-step:
1. Use PuttyGen to convert your private key into Putty format. Launch puttygen, click the "load" button and select your private key file, then click the "save private key" button to save it in putty format.
2. Set up a Putty profile: Start Putty.
Set the Host URL to code.gnucash.org, port 22 on the Session page
Open Connection:SSH:Auth and at the bottom of the panel, for "Private key file for authentication" browse for the converted keyfile you made in the previous step.
Open Connection:Data and enter 'git' in the "Autologin username" text entry.
Return to the Session panel, enter a name (if you use
code.gnucash.org
configuring TortoiseGit will be less confusing) in the text entry named "Saved Sessions" and click the "save" button.
Click "open". If everything is done correctly, a command window will open and you'll see that message about terminal sessions not being allowed. If you are instead prompted for a password, you have messed up the username or key somehow and will need to contact the server admin to get your IP address unblocked.
(Continue with
#TortoiseGit on Windows
Clone the Repositories
Now clone the Github repository the same way as
#Non-Committers
. Since changes should not be pushed to the github repository, a good way to make sure that this doesn't happen by mistake is to use the same read-only URI given above for non-committers. Alternatively, fork the Gnucash repository to your Github account and clone that (use the read-write URI in that case).
Next add the repository on code.gnucash.org as a second remote, for example as 'upstream'.
git remote add upstream git@code.gnucash.org:gnucash
Perhaps a better approach is to replace the push url:
git remote set-url --push origin git@code.gnucash.org:gnucash
Note
This is, when pushing to upstream, it will push to code (which will in turn push to github/Gnucash on your behalf). And when pulling it will pull (read-only) from github/Gnucash.
The primary advantage of this configuration is you can't accidentally push to github/Gnucash instead of code.gnucash.org. And as a side effect you save a few fetches.
The primary disadvantage is this makes it slightly more difficult to detect/recover from a divergence between code and github/Gnucash. Fortunately that rarely happens and to fix that is sufficces to temporarily define one or two extra remotes to separate out the combined upstream.
That's it.
(Continue with
#Committing
TortoiseGit on Windows
Right-click a folder in Windows™ Explorer and select TortoiseGit:Settings. At the bottom of the Network panel of the resulting dialog box, click the "Browse" button for SSH Client and navigate to
C:\Program Files\TortoiseGit\bin\TortoisePlink.exe
, click "open" in the file chooser, the "OK" to dismiss the Settings box.
Right-click on a folder into which you want to check out (or already have checked out) Gnucash. If it's a fresh checkout, select TortoiseGit Checkout; otherwise select TortoiseGit:Relocate. Enter the URL as
ssh://the-putty-session-name/gnucash
. (Remember earlier where we said it would be less confusing if you use
code.gnucash.org
for the session name? That's because if you did the URL will be
ssh://code.gnucash.orgrepo/gnucash
.)
You should now be able to commit changes via TortoiseGit.
Committing
Committing is simple:
after editing
git add
# Tell Git which files to include in the commit
# Important, use this instead of your OSes commands. Else you will loose their history:
git mv
# Rename or move files
git rm
# Remove files from your repo
git commit
These above commands are used to record your changes
locally
git push upstream local-branch:remote-branch
Will push your changes
back to the future
repository.
Branching and Merging
The "canonical" repositories at code.gnucash.org and their public mirrors at github.com/Gnucash have 2 active branches:
future
is the
development branch
. All
major new features
should be committed to this branch and this branch only. Unstable releases during the beta period leading up to a new stable release series will be tagged on this branch and the tarballs generated from the tag commits. Bugs reported against an unstable release should be checked to see if they exist on the stable release; if they do they should be reassigned to the stable release and fixed on
stable
, then merged.
N.B.
If for some reason a change is committed to
future
that should have been done in
stable
cherry-pick
that commit to
stable
. Merging
future
->
stable
would add all of the development changes into
stable
, which would be bad.
stable
is the
current stable release branch
. All
bugs reported on the released version
should have the fixes committed to this branch and then
merged
into
future
. Stable releases will be tagged on this branch and the tarballs generated from the tag commits.
There are also
archival branches
, one for each stable release series no longer under development. Note that before 2.6 we used Subversion or CVS for version control and the practices were different, so you'll see different commit patterns when looking at historical branches.
The gnucash repository contains an
archive
branch which tracks
future
up to the point that the last subversion feature branch (webkit, if you're curious) was merged, except that new merge commits have been added to link the feature branch merges. It shows the merge points in the right order, but the merge commit dates are all from early 2014. It is of historical interest only.
There are several
abandoned feature branches
which were never integrated into GnuCash. They are also present for historical interest only.
Pushing onto another core developer branch
It is possible for a developer (Alice) to push to another developer (Bob)'s github branch 'bob-dev'. We *assume* that 'bob-dev' is based on stable.
Alice will create a branch that mirrors Bob's branch.
# Same as test-building a PR branch.
git fetch
git checkout -b bob-dev stable
git pull https://github.com/bob/gnucash bob-dev
# Edit and commit, then push:
git push git@github.com:bob/gnucash bob-dev
Bugs and New Features
To repeat the policy in the description of the active branches:
Bug fixes
and
improvements
should always be applied to the
stable
branch then merged to
future
unless either they don't affect
stable
or they are not going to be fixed on
stable
because the required changes are complex enough that it would risk making
stable
unstable.
New Features
may be merged into
stable
if they are
minor
features and
future
if they are
major
Major new features
are ones that significantly change
existing
UI or add substantial new UI, add (not upgrade) a dependency, change the database schema, or are sufficiently complex that they require significant user testing before they can be considered stable. Substantial new UI means adding more than a single assistant, dialog box, or menu item. Everything else is
minor
Improvements
are changes that enhance existing UI or behavior to account for new use-cases or to make the correct use easier to do or to understand.
When and how to use branches depends on the complexity of the changes:
Small changes
, which can be completed quickly and in a single commit, do not require a feature branch.
Larger changes
, which
might
require
more than one commit
or
take
more than a few hours
to write and test
should be done on a private branch which is
rebased
onto the appropriate main branch before pushing the changes to the main repository. This helps keep the main branch's history linear, which in turn makes it easier to read and displays better in a graphical tool.
Major changes
which are completed in
stages which are made public
in parts or
which for any reason are best
visualized as standing apart from the main branch
should be merged with
--no-ff
to prevent them from fast-forwarding the main branch.
Bug Fix Feature Branch Example
git checkout -b my-bug-fix stable
# make changes, commit, test, fix, etc.
git checkout stable
git pull --rebase
git rebase stable my-bug-fix
# make && make check to ensure that you're not pushing a broken build!
git push upstream stable
git checkout future
git pull --rebase
git merge stable
# rebuild and make check again
git push upstream future
Major Feature Branch Example
git checkout -b my-new-feature future
# write and test the first phase of your feature, committing often.
git checkout future
git pull --rebase
git merge --no-ff my-new-feature
# rebuild and make check for safety
git push upstream future
git checkout my-new-feature
# write the next phase and repeat until done.
Caution:
When
switching the branch
you should cleanup your build dir to avoid "strange behavior". At least you should run
make distclean
before, but better might be
cd

rm -rf *
&&
../configure
$YOUR_PARAMETERS
&&
make
&&
make check
after switching. In case you are building intree you can run
git clean -fdx -e /.project -e /.cproject -e /.autotools -e /.settings/
instead to remove everything not in the repository with a few exceptions (-e ...). Above exceptions are files, where
Eclipse
stores its settings.
Resolving Merge Conflicts
Sometimes, e.g. after a new release, the first merge in gnucash-docs will result in an conflict about the version number:
git status
On branch future
You have unmerged paths.
fix conflicts and run
"git commit"
Changes to be committed:
Unmerged paths:
use
"git add ..."
to mark resolution
both modified: configure.ac
configure.ac will now contain a section
<<<<<<< HEAD
AC_INIT(gnucash-docs, 2.6.99)
=======
AC_INIT(gnucash-docs, 2.6.4)
>>>>>>> stable
Just remove the markers and the wrong section with your preferred editor.
Don't forget to run
git commit -a
to tell git, you are ready!
Note
Do not confuse
-a
--all
with
--amend
Link Bugzilla Entries
Often commits are related to
Bugzilla
entries. In this case the commit message should contain
Bug


Specify it as the first line if the commit fully fixes the related bugzilla issue, or mention it in the body of the commit message otherwise. Simply copying the title line from the bug page and pasting it will match the format. We use a regular expression to detect and segregate bug fixes in the release notes so please adhere precisely to this format.
Adding these references will make it easier for committers to use the
git bz
command while manipulating the commits.
Patches and Pull Requests
Warning
Because of our configuration with code.gnucash.org as canonical repository it is
strongly discouraged
to
apply any changes directly to the mirror repositories
on Github.
Never use GitHubs merge or edit tools!
A common committer duty is handling patches and pull requests from non-committers. The procedure for both is:
Review the code for formatting, style, good coding practice, good commit message, etc. Make comments and get the submitter to make any necessary changes.
Download and apply the patch to the appropriate branch. If the change is complex you may want to make a local branch to work in.
Build and test. Discuss any problems with the submitter and get the patch in good shape, ready to commit.
If the patch is on the
stable
branch, do a test merge onto
future
. Resolve any merge issues with the submitter; if necessary, get a "patch to the patch" to resolve the merge conflicts.
Once everything is ready, merge your working branch into
future
or
stable
Reset your local
stable
and/or
future
branches to remove any test merges.
Pull them to get any commits others might have pushed while you're working.
Apply the final patches or merge your working branch. When applying take care the patches are committed with the appropriate authorship.
If the patches were created with
git format-patch
and hence applied using
git am
this should be ok.
Also if the patches are in another repository or branch and you use
git pull
to apply them the author should be ok as well.
If the patches came as ordinary diff files to be applied with
git apply
, you should commit these changes with
git commit --author "name "
with the proper author name and e-mail filled in.
Merge
stable
into
future
if required; if there's a "patch to the patch" to handle conflicts between
stable
and
future
, use
--strategy=theirs
to the merge, then apply the repair patch and commit '
amending
the merge commit:
git checkout future
git merge --strategy
theirs stable
git apply patch-to-the-patch
git commit -a --amend
Push the results
Close the pull request or mark the patches "Committed" in Bugzilla.
Pull Request Notes
If there have been changes in the same files that the PR changes there will be
conflicts
when you pull in the PR branch. Github will usually indicate that by replacing the green merge button with a warning "This branch has conflicts that must be resolved". There are three ways to resolve the conflicts:
Require the author to rebase their branch and resolve the conflicts themselves, then force-push the branch.
Pull the PR branch into a local branch that's current and resolve the conflicts in the resulting merge commit.
Go to the first commit in the PR and note the parent hash. Branch from there, pull the PR into that branch (it will fast-forward), build and test, then merge that branch into HEAD and resolve the conflicts at that time.
Forced Pushes
After the PR author has force-pushed changes to the PR branch git will refuse to fetch it because the history has changed. The safest way to deal with that is to reset your local branch to the last mainline commit and re-pull. You can also use
git pull -f ...
but if you do check the result carefully to be sure that it did the right thing.
Code review comments
They can be made inline from the
Files Changed
tab of the pull request page on GitHub: click on the commit, which displays the diff-patch, and hover over the code snippet which will bring out a '+' button to add a comment for a particular line.
Advanced Pulling
Adding a remote only to apply a pull request is not really necessary. Instead pull the branch from the PR directly into your local repo using "git pull". It takes some shuffling of the information provided by the PR:
For example, if you get a PR against the gnucash repo with the following message (taken from
the real PR#163):
0-wiz-0 [1]wants to merge 2 commits into Gnucash:future from 0-wiz-0:future
I would locally run this command (with future being checked out and fully up to date with future on code.gnucash.org):
git pull https://github.com/0-wiz-0/Gnucash future
If future on code.gnucash.org has diverged from 0-wiz-0's future branch, this will trigger a merge action, otherwise it would be a fast-forward.
Sidenote
I used to rebase non-fast-forward PR's to avoid the merge but have stopped doing so for all but the most trivial PRs. By
not
rebasing github will automatically close the PR as as soon as the merge result is pushed into the primary repo. After a rebase however one needs to manually close the PR on github. Also a rebase makes it harder for the author of the PR to sync his local repo with our primary one after the PR is pulled.
Here is a breakdown of the relevant info in the PR message compared to the git pull command:
github-user
] wants to merge x commits into Gnucash:[
target-branch
] from [
github-user
]: [
source-branch
There's an implicit bit of information as well, namely which [
repo
] the PR is targetting. Obviously
you should work in a
local
repo
for the same source
base as in github. So if the PR is against
gnucash-docs, you need to do the git-pull in your local gnucash-docs repo. I mention this, because you need this bit of information in your git-pull command as well.
So the above translates into
go to the proper local
repo
depending on the complexity:
simple PR: check out [
target-branch
] (future in the example, but can be stable as well for other PR's)
complex PR: create [
source-branch
] based on target-branch
make sure this branch is up to date with code.gnucash.org (using 'git pull' without any arguments, assuming you don't have local, non-pushed work on your primary branches. You don't, right?)
then formulate the pull from another remote (from the [
github-user
]'s repo):
git pull https://github.com/
$github
-user"
$repo
$source
-branch"
Hint
If it asks for a password you might have mistyped something.
Additional step for complex PRs: After checking the correctness and potential fixes, merge the source-brancch in the target-branch.
It's slightly more typing than clicking the fancy button on github, but avoids the need to make each new repo in a PR a remote.
Another approach
is to add "fetch = +refs/pull/*/head:refs/pull/origin/*" to [remote "origin"] in your
.git/config
After a
git fetch origin
you can i.e.
git checkout -b PR
${
PRNR
pull/origin/
${
PRNR
# ${PRNR}: Number of the pull request
to get a pull request branch based on its number.
(from
Pro
This is still possible, after the branch at github.com/"$github-user" was accidently deleted.
Con
It is not possible to push a patch onto github.com/"$github-user"'s PR.
Final note
This technique can be used to pull from any other repository (online or not) as long as the git command can reach the other repository. So the repository URL can be a github url (
...), but equally a url to another online site that hosts repositories, or even a file path to another repo on your own PC. For more info search the git help information on repo urls.
Collaboration
With rare exceptions we don't want to clutter the future repository with feature branches, so how can two developers collaborate on one?
There are several ways to go about it: You can pass patches between you over email, chat, or carrier pigeon; Git is designed to handle that easily (except for carrier pigeon transport, as that requires retyping the patch, which is a pain [
Really?
]). You can arrange for all of your repositories to be available on the net, and
git pull
amongst yourselves. Or you can use one of the public repositories like Github or Gitorious to manage your changes.
Accessing GnuCash BugZilla from Git
There is a plugin, called git-bz, written for Git that allows it to talk to BugZilla and do things with bugs like attach patches, add comments, mark as fixed, etc.–all from the command line. See the
git-bz
page for details.
Related Topics
An Introduction to Git
has basic suggested work flow for modifying GnuCash and more details about what each git command does for those new to git.
Documentation_Update_Instructions
focuses specifically on documentation updates.
GitHub Help
in particular
fork-a-repo
Git vs Svn
has some background on conceptual differences between svn and git. This may help people with a strong svn background to make the switch to git.
Purely for historical interest:
Htdocs Split
: the gnucash-htdocs repository has been used to store both the website and a compiled version of our documentation ...
Git Migration
tracked the required changes to our infrastructure and support code before we were able to switch to a pure git based workflow.
GnuCash has been maintaining its source code in a hybrid svn-git system for a while. It has now moved on to a pure git environment. We had some documentation for this hybrid setup as well. The current page's history will reveal how a user had to configure her local setup,
Git_Svn_Mirror
explains what was needed on the server side.
Other options exists as well; feel free to edit this wiki page.
Back to Development Process
Before version 5.0
stable
was named
maint
and
future
master
Discussion
and
Announcement
Retrieved from "
Categories
Development
Git
Gnucash Version
Navigation menu
Personal tools
Request account
Namespaces
Page
Discussion
Variants
Views
Read
View source
View history
More
GnuCash
Recent changes
Help
Related Sites
GnuCash Website
GnuCash at GitHub
GnuCash Bugzilla
Contributing
General
donations
Tools
What links here
Related changes
Special pages
Printable version
Permanent link
Page information
This page was last edited on 8 March 2026, at 10:17.
This page has been accessed 1,192,762 times.
Content is available under
GNU Free Documentation License 1.2
unless otherwise noted.
About GnuCash
Disclaimers