Difference between revisions of "Git"

From GnuCash
Jump to: navigation, search
m (Fixing Git_For_Newbies link typo)
(Committing: Improve comments)
 
(103 intermediate revisions by 6 users not shown)
Line 1: Line 1:
= What is Git? =
+
{| class="wikitable" style="margin: auto;"
 +
! scope="row"|Languages
 +
| | [[He/{{PAGENAME:גיט}}|עִברִית]]
 +
|}
 +
 
 +
[https://git-scm.com/ Git] is a ''[{{URL:wp}}Distributed_version_control distributed]'' '''[{{URL:wp}}Version_control 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.
 +
 
 +
[[Category:Development]] [[Category:Git]]
 +
 
 +
== 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 [[#Set-up|clone]] that onto ''your local computer'' or [[#GitHub Users|fork]] it into ''your personal github repository''.
 +
 
 +
==== {{BuildServer}} ====
 +
<tt>{{BuildServer}}</tt> is the server that hosts the '''canonical git repository''', this wiki, [[Mailing Lists]], [[IRC]] [{{ListURL}}/logs logs], the nightly builds  of the [{{URL:Build}}docs/ documentation and API docs] (via [[Doxygen]]) for important [[#Branches|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.
  
[http://git-scm.com/ Git] is a ''[https://en.wikipedia.org/wiki/Distributed_version_control distributed]'' '''[https://en.wikipedia.org/wiki/Version_control version control system]''' (VCS) originally developed by Linus Torvalds for managing Linux source code without requiring a central server. It is also the primary VCS used by the [http://www.gnome.org Gnome] and [http://www.freedesktop.org Free Desktop] projects. You can get the latest version for your system and read a rich variety of online documentation at [http://git-scm.com/ Git's Home]. In particular, ''Pro Git'' by Scott Chacon is available in several languages for free online reading at [http://git-scm.com/book Git Book], where you can also download the English version as a PDF, ebook, or mobi.
+
==== GitHub ====
 +
'''GitHub''' is a web-based Git repository ''hosting service''.  
  
If you know nothing about version control, that doesn't matter. Just read [http://git-scm.com/book/en/v2/Getting-Started-About-Version-Control Getting Started - About Version Control]. There in the left column you can select your language.  
+
Our '''public repositories''' are mirrored on GitHub: for [https://github.com/Gnucash/gnucash code], [https://github.com/Gnucash/gnucash-docs documentation] and for the [https://github.com/Gnucash/gnucash-htdocs website]...
  
Another good place to start is [https://help.github.com/articles/good-resources-for-learning-git-and-github/ Good Resources for Learning Git and GitHub] - not only if you want to use GitHub for [[#Pull Requests]].
+
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.
  
git help
+
=== Repositories ===
will give you a list of usual commands and
+
They host since 2014-02 all GnuCash repositories:
git help <command>
+
* '''gnucash.git:''' the program,
will show you the manual page of that command.
+
* '''gnucash-docs:''' user documentation,
 +
* '''gnucash-htdocs:''' Webserver, if you cloned/forked it before 2013-01 see [[Htdocs Split]],
 +
* '''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 [https://github.com/Gnucash github.com/Gnucash].
  
There are several GUIs available for git, e.g.:
+
=== Branches ===
* git gui
 
* gitk (shows the history)
 
* [http://www.sourcetreeapp.com/ SourceTree] for Windows or Mac
 
and most IDEs have plugins for it.
 
  
= What has that to do with Gnucash? =
+
==== Branch Policy ====
 +
===== Git Flow =====
 +
Gnucash uses a variation of the [https://nvie.com/posts/a-successful-git-branching-model/ Git Flow] process for managing changes. Think of <tt>stable</tt> as "lower", <tt>unstable</tt> as "intermediate" and <tt>future</tt> as "higher".{{Git branchs rename.ref}} Branches are periodically merged "upwards", meaning that <tt>stable</tt> is merged into <tt>future</tt>. When <tt>unstable</tt> exists "upwards merging happens in three stages instead: <tt>stable</tt> is merged into <tt>unstable</tt> and <tt>unstable</tt> into <tt>future</tt>. 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.
  
We have converted from Subversion to Git in order to take advantage of its ''branching'' and ''merging'' facilities, which are much richer than those provided by Subversion.
+
===== Beta Testing =====
 +
When we get close to releasing a new stable series culminating the development on the <tt>future</tt> branch we make a new branch <tt>unstable</tt> from it and make releases with an odd minor number. For example,
 +
:before the next major release we (will) have a series {{BetaSeries}},
 +
: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. <tt>unstable</tt> is between <tt>stable</tt> and <tt>future</tt> in the Git Flow hierarchy, so <tt>stable</tt> is merged into <tt>unstable</tt> when it exists and <tt>unstable</tt> into <tt>future</tt>. When we decide that it's stable we do a final merge of <tt>stable</tt> into <tt>unstable</tt> and delete the <tt>stable</tt> branch then rename <tt>unstable</tt> to <tt>stable</tt> as it's the new stable branch.
  
Our '''public repositories''' are ''mirrored on Github'': for [https://github.com/Gnucash/gnucash code], [https://github.com/Gnucash/gnucash-docs documentation] and for the [https://github.com/Gnucash/gnucash-htdocs website]. 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.
+
==== Basics ====
 +
There are 3 important branches in our more complex repositories for ''program'' and ''documentation'':
 +
:;future: ''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'', ''translations'', improvements of the ''documentation'' should usually be applied on this branch.
 +
And you should create temporary '''working branches''' based on them for nontrivial patchsets:
 +
<code>git branch bugXXXXXX</code>
  
<tt>svn.gnucash.org</tt> is just another name for <tt>code.gnucash.org</tt>, the server that hosts the '''canonical git repository''', wiki, [[Mailing Lists]], automated win32 builds, and the nightly builds  of the [http://code.gnucash.org/docs/ documentation and API docs] (via [[Doxygen]]) for both [[#Branchs|branchs]]. The old SVN repository is there too and it is possible to check out from it but since it doesn't take commits there's no reason to do so.
+
* In your ''local working dir'' you should checkout one of them, e.g.: <syntaxhighlight lang="sh">
 +
git checkout future
 +
</syntaxhighlight>
 +
* Later you should ''recurrently'' integrate remote changes, but usually only before you publish your changes i.e. by a PR: <syntaxhighlight lang="sh">
 +
git pull
 +
</syntaxhighlight>
 +
:In its default mode, <code>git pull</code> is shorthand for <code>git fetch</code> (update your ''local repo''), followed by <code>git merge FETCH_HEAD</code> resulting in an update of your ''current'' branchs ''working dir''.
  
= Using the Github Repository =
+
===== One local repository and multiple working directories =====
 +
After a normal <code>git clone</code> you will have
 +
* the main <worktree> as your ''source'' directory and inside
 +
* the hidden <tt>.git</tt> 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 [https://stackoverflow.com/questions/6270193/multiple-working-directories-with-git/30185564#30185564]
 +
<syntaxhighlight lang="sh">
 +
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 <path> [<branch>]
 +
</SyntaxHighlight> to create separate working directories for different branches.
 +
;Example:<syntaxhighlight lang="sh">
 +
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
 +
</SyntaxHighlight>
  
== Non-Committers ==
+
===== Getting commits from other branches or repos =====
 +
* The simple form '''<syntaxhighlight lang="sh" inline>git cherry-pick [options] <commit>... </syntaxhighlight>''' 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.
  
If you are new to using git, you may find it useful to read [[Git_For_Newbies|Git For Newbies]] for more information about specific git commands and how they are used in the process of modifying GnuCash.
+
* Before you publish your branch you should often run '''<syntaxhighlight lang="sh" inline>git rebase [options]</syntaxhighlight>'''. 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''.
  
=== Set-Up ===
+
* Finally usually core developers will '''<syntaxhighlight lang="sh" inline>git merge [options]</syntaxhighlight>''' your published working branch into the official branch.
Just clone the repository as usual:
 
  
  git clone https://github.com/Gnucash/gnucash.git
+
===== Patches =====
:;other URLs: https://github.com/Gnucash/gnucash-docs (documentation)
+
* When you have patches in <tt>future</tt>, use <syntaxhighlight lang="sh">
::https://github.com/Gnucash/gnucash-htdocs (website)
+
git format-patch origin/future..future
::See https://github.com/Gnucash for further repos e.g. with OS/distro specific build scripts.
+
</syntaxhighlight>
 +
:or <syntaxhighlight lang="sh">
 +
git diff
 +
</syntaxhighlight>
 +
:in the root directory of your local working directory to prepare them; then add the patchfile as an attachment to the appropriate bug report.
  
==== Branches ====
+
== Using the Github Repository ==
There are 2 important branches in most of our repositories:
 
:;master: is the default branch in git. ''New features'' and their documentation should be based on this branch. In the old svn days this was <tt>trunk</tt>. For convenience for users migrating from svn a ''trunk'' branch has been set up as an alias for the master branch but you are encouraged to switch to master as your main branch.
 
:;maint: ''Bugfixes'', ''translations'', improvements of the ''documentation'' should usually be applied on this branch.
 
  
In your ''local working dir'' you should checkout one of them, e.g.:
+
=== User and "Normal" Contributors ===
git checkout master
 
  
When you have patches in master, use
+
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.
  
  git format-patch origin/master..master
+
==== Set-Up ====
 +
Just clone the repository as usual:
 +
<syntaxhighlight lang="sh">
 +
git clone https://github.com/Gnucash/gnucash.git
 +
</syntaxhighlight>
 +
:;other URLs: https://github.com/Gnucash/gnucash-docs (documentation)
 +
::https://github.com/Gnucash/gnucash-htdocs (website)
 +
::See https://github.com/Gnucash 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 <code>merge.renamelimit</code> from its default of <tt>1000</tt> in your gnucash repository:
 +
:<syntaxhighlight lang="sh">
 +
git config merge.renameLimit 3000
 +
</syntaxhighlight>
 +
:Else the history gets broken and rebasing future on stable will produce strange results.
  
(or <tt>git diff</tt>) in the root directory of your local repository to prepare them; then add the patchfile as an attachment to the appropriate bug report.
+
===== 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): <code>git clone git@github.com:<YOUR-GITHUB-USERNAME>/gnucash.git</code>. Note that this clone command takes the ''URL in a different format''.
  
==== GitHub ====
+
With this, you will be able to push your local changes to your forked repository: <pre>git push origin future</pre>. Later, you can issue a [[#Pull Request]] to have your changes incorporated into the project.
If you have a Github account, you could as well
 
# use Github's '''fork''' feature to set up a '''clone''' on GitHub. And then
 
# clone from that repository instead (note that this is your personal ''read-write enabled'' clone):
 
#: <pre>git clone git@github.com:<YOUR-GITHUB-USERNAME>/gnucash.git</pre>
 
#: Note that this clone command takes the ''URL in a different format''.
 
# With this form you will be able to push your local changes to your GitHub account as usual:
 
#: <pre>git push origin master</pre>
 
  
 
{|cellpadding="20"
 
{|cellpadding="20"
 
| Depending on your access rights you might continue with ...
 
| Depending on your access rights you might continue with ...
 
||[[#Pull Requests]]
 
||[[#Pull Requests]]
||[[#Committers]]
+
||[[#Core Developers]]
 
|}
 
|}
  
=== Patches ===
+
==== 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: <SyntaxHighlight lang="sh">
 +
git remote add github ssh://git@github.com/Me/gnucash
 +
git branch -u github working-branch
 +
</SyntaxHighlight>
 +
* apply your changes and <SyntaxHighlight lang="sh">
 +
git push
 +
</SyntaxHighlight>
 +
* Now log in to your GitHub account, go to your forked gnucash repository, select <tt>working-branch</tt> 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: <SyntaxHighlight lang="sh">
 +
git branch -D working-branch
 +
git push github :working-branch
 +
</SyntaxHighlight>
 +
* If you want to continue in between with something else create another branch.
 +
 
 +
==== Patches ====
 
If you're going to be submitting patches:
 
If you're going to be submitting patches:
 
* Create a branch to work in:
 
* Create a branch to work in:
** '''Bug fixes''' should branch off of ''maint'' unless the bug applies only to the unstable version.
+
** '''Bug fixes''' should branch off of ''stable'' unless the bug applies only to the unstable version.
** '''New features''' must branch off of ''master''.
+
** '''New features''' must branch off of ''future''.
The following example is for a new feature; ''substitute <tt>maint</tt> for <tt>master</tt> if you're doing a bug-fix''.
+
The following example is for a new feature; ''substitute <tt>stable</tt> for <tt>future</tt> if you're doing a bug-fix''.
* 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.
+
* 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. <SyntaxHighlight lang="sh">
  git checkout master
+
git checkout future
  git branch working-branch
+
git branch working-branch
* Rebase your working branch onto the target branch often so that you stay in sync:
+
</SyntaxHighlight>
  git rebase master working-branch
+
* Rebase your working branch onto the target branch often so that you stay in sync: <SyntaxHighlight lang="sh">
 +
git rebase future working-branch
 +
</SyntaxHighlight>
 
* Open a bug in Bugzilla to attach your patch to if one doesn't already exist.
 
* 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:
+
* Write good commit messages in which the bug number and summary are the first line. Skip one line, then describe the patch. For example: <SyntaxHighlight lang="Console">
  [Bug 673193] - Possible Register migration to TreeView
+
[Bug 673193] - Possible Register migration to TreeView
 
    
 
    
  Update the old register rewrite branch to work with the currently-released Gtk2.
+
Update the old register rewrite branch to work with the currently-released Gtk2.
* Use <tt>git rebase -i</tt> as necessary to make a clean series of patches for complex changes.
+
</SyntaxHighlight>
 +
* Use <tt>git rebase -i</tt> (''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
 
* Be sure to do a fresh rebase from the target branch and a make check to ensure that everything works
* Use <tt>git format-patch</tt> to create the actual patches from your commits:
+
* Use <tt>git format-patch</tt> to create the actual patches from your commits: <SyntaxHighlight lang="sh">
  git rebase master working-branch
+
git rebase future working-branch
  git format-patch master
+
git format-patch future
 +
</SyntaxHighlight>
 
* Attach the resulting patch(es) to the bug report.
 
* 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. <tt>[https://www.kernel.org/pub/software/scm/git/docs/git-rebase.html git-rebase] -i</tt> can be very helpful if you have a series of patches.
 
* 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. <tt>[https://www.kernel.org/pub/software/scm/git/docs/git-rebase.html git-rebase] -i</tt> can be very helpful if you have a series of patches.
  
=== Pull Requests ===
+
=== Core Developers ===
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
 
* Perhaps an easier approach is to replace the push url:
 
  git remote set-url --push origin git@github.com/Me/gnucash
 
  git branch working-branch
 
* apply your ammendments and
 
  git push
 
* Now log in to your GitHub account, go to your forked gnucash repository, select <tt>working-branch</tt> 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, 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.
 
  
== Committers ==
+
==== About Write Access ====
Since 2014-02 all GnuCash repositories are pure git repositories:
 
* gnucash
 
* gnucash-on-windows: windows installer and build script moved here from gnucash/packaging
 
* gnucash-docs
 
* gnucash-htdocs (see [[#Conversion Notice]])
 
  
===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.
  
FAQ: Is it possible to get write access?
+
==== Set up ====
 +
'''Note''': this set up presumes you already have commit access to the GnuCash repositories on {{BuildServer}}. If you don't but believe you should, ask for this on the gnucash-devel mailing list.
  
A: In principle yes, but we are quite conservative with giving out new SSH write accounts. For occasional changes people are encouraged to submit patches. We do add people 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. But in the meantime, ''patches in Bugzilla'' and ''pull requests on github'' are the suggested route, as has been stated at other places. --[[User:Cstim|Cstim]] 08:00, 8 January 2006 (EST)
+
===== Generate your ssh key pair =====
  
=== Set up ===
+
====== Under Linux or under Windows with MSYS ======
'''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.
+
To set up ssh with the MSYS client, proceed exactly as here.
  
==== Generate your ssh key pair ====
 
 
You'll need to generate a key-pair and provide the public half to the GnuCash repository administrator. To generate a key pair use
 
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
+
<SyntaxHighlight lang="sh">
 
+
ssh-keygen -t rsa -b 1024 -f gnucash-key
You can use any name you like instead of "gnucash-key".
+
</SyntaxHighlight>
 
+
;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 key. If you don't, anyone who gains access to your key can connect to whatever servers you protect with it.  
+
: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'' <tt>gnucash-key</tt> and ''public'' <tt>gnucash-key.pub</tt> keys in <code>~/.ssh/</code>.
 +
;Warning: If something goes wrong with the next command, your IP will get blocked ''from all services'' running on {{BuildServer}} for one hour.
  
 
Once you have the key configured correctly and have provided it to the GnuCash repository administrator, try  
 
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
+
<SyntaxHighlight lang="sh">
You'll get the usual ssh question about the fingerprint for a new host. It should be <tt>20:23:3d:df:f3:13:34:c1:32:ca:11:77:24:21:98:01</tt>. 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.
+
ssh -i gnucash-key git@code.gnucash.org
 +
</SyntaxHighlight>
 +
You'll get the usual ssh question about the '''fingerprint''' for a new host. It should be <tt>20:23:3d:df:f3:13:34:c1:32:ca:11:77:24:21:98:01</tt>. 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'.
+
Next, you'll want to to configure your local ssh client to always provide this key when connecting to {{BuildServer}}. 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):
+
On linux, you can set this up by adding the following lines in your '''ssh config file''' (~/.ssh/config):
Host code.gnucash.org
+
:<SyntaxHighlight lang="linux-config">
IdentityFile ~/.ssh/gnucash-key
+
Host code.gnucash.org
User git
+
IdentityFile ~/.ssh/gnucash-key
: (Continue with [[#Clone the Repositories]])
+
User git
 +
</SyntaxHighlight>
 +
:Then you can shorten the call from above to <SyntaxHighlight lang="sh">
 +
ssh code.gnucash.org
 +
</SyntaxHighlight>
 +
(Continue with [[#Clone the Repositories]])
  
===== Key generation under Windows =====
+
====== Under Windows with Putty for TortoiseGit ======
 
+
For [[https://code.google.com/p/tortoisegit/ TortoiseGit]], you'll also need PuttyGen and Putty from [[https://www.chiark.greenend.org.uk/~sgtatham/putty/ PuTTY]].  
====== With MSYS ======
 
To set up ssh with the MSYS client, proceed exactly as above.
 
 
 
====== With Putty for TortoiseGit ======
 
For [[http://code.google.com/p/tortoisegit/ TortoiseGit]], you'll also need PuttyGen and Putty from [[http://www.chiark.greenend.org.uk/~sgtatham/putty/ PuTTY]].  
 
 
Setting up Pageant to work with TortoiseGit is a bit involved, so we'll go through it step-by-step:
 
Setting up Pageant to work with TortoiseGit is a bit involved, so we'll go through it step-by-step:
  
Line 161: Line 234:
  
 
2. Set up a Putty profile: Start Putty.  
 
2. Set up a Putty profile: Start Putty.  
* Set the Host URL to code.gnucash.org, port 22 on the Session page
+
* Set the Host URL to {{BuildServer}}, 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: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.
 
* Open Connection:Data and enter 'git' in the "Autologin username" text entry.
* Return to the Session panel, enter a name (if you use <tt>code.gnucash.org</tt> configuring TortoiseGit will be less confusing) in the text entry named "Saved Sessions" and click the "save" button.
+
* Return to the Session panel, enter a name (if you use <tt>{{BuildServer}}</tt> 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.
 
* 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]])
 
: (Continue with [[#TortoiseGit on Windows]])
  
==== Clone the Repositories ====
+
===== 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).
 
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'.
+
Next add the repository on {{BuildServer}} as a second remote, for example as 'upstream'.
 
+
<SyntaxHighlight lang="sh">
  git remote add upstream git@code.gnucash.org:gnucash
+
git remote add upstream git@code.gnucash.org:gnucash
 +
</SyntaxHighlight>
  
 
Perhaps a better approach is to replace the push url:
 
Perhaps a better approach is to replace the push url:
git remote set-url --push origin git@code.gnucash.org:gnucash  
+
<SyntaxHighlight lang="sh">
That avoids confusion where to push and where to fetch.
+
git remote set-url --push origin git@code.gnucash.org:gnucash  
 
+
</SyntaxHighlight>
 +
;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 {{BuildServer}}. 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.
 
That's it.
 
: (Continue with [[#Committing]])
 
: (Continue with [[#Committing]])
  
===== TortoiseGit on Windows =====
+
====== 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 <tt>C:\Program Files\TortoiseGit\bin\TortoisePlink.exe</tt>, click "open" in the file chooser, the "OK" to dismiss the Settings box.
 
* 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 <tt>C:\Program Files\TortoiseGit\bin\TortoisePlink.exe</tt>, 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 <tt>ssh://the-putty-session-name/gnucash</tt>. (Remember earlier where we said it would be less confusing if you use <tt>code.gnucash.org</tt> for the session name? That's because if you did the URL will be <tt>ssh://code.gnucash.org/repo/gnucash</tt>.)
+
* 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 <tt>ssh://the-putty-session-name/gnucash</tt>. (Remember earlier where we said it would be less confusing if you use <tt>{{BuildServer}}</tt> for the session name? That's because if you did the URL will be <tt>ssh://{{BuildServer}}repo/gnucash</tt>.)
  
 
You should now be able to commit changes via TortoiseGit.
 
You should now be able to commit changes via TortoiseGit.
  
=== Committing ===
+
==== Committing ====
 
 
 
Committing is simple:
 
Committing is simple:
  git add
+
:after editing
  git commit
+
<syntaxhighlight lang="sh" highlight=4>
These two commands are used to record your changes ''locally''.
+
git add <list of new or modified files>      # Tell Git which files to include in the commit
 
+
# Important, use this instead of your OSes commands. Else you will loose their history:
  git push upstream local-branch:remote-branch
+
git mv <old name or path> <new name or path>  # Rename or move files
 +
git rm <list of obsolete files>              # Remove files from your repo
 +
git commit
 +
</syntaxhighlight>
 +
These above commands are used to record your changes ''locally''.
  
Will push your changes ''back to the master'' repository.
+
<syntaxhighlight lang="sh">
 +
git push upstream local-branch:remote-branch
 +
</syntaxhighlight>
 +
Will push your changes ''back to the future'' repository.
  
=== Branching and Merging ===
+
==== Branching and Merging ====
  
The "canonical" repositories at code.gnucash.org and their mirror at github.com/Gnucash have 2 active branches:
+
The "canonical" repositories at {{BuildServer}} and their public mirrors at github.com/Gnucash have 2 active branches:
  
'''master''' is the ''development branch''. All ''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 '''maint''', then merged. '''N.B.'''If for some reason a change is committed to '''master''' that should have been done in '''maint''', '''''cherry-pick''''' that commit to '''maint'''. Merging '''master'''->'''maint''' would add all of the development changes into '''maint''', which would be bad.
+
'''future''' is the ''development branch''. All ''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.
  
'''maint''' is the ''current stable release branch''. All ''bugs reported on the released version'' should have the fixes committed to this branch and then merged to '''master'''. Stable releases will be tagged on this branch and the tarballs generated from the tag commits.
+
'''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.
 
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 '''master''' 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.
+
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.
 
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.
 +
 +
<syntaxhighlight lang="sh">
 +
# 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
 +
</syntaxhighlight>
  
 
==== Bugs and New Features ====
 
==== Bugs and New Features ====
 
To repeat the policy in the description of the active branches:
 
To repeat the policy in the description of the active branches:
* '''Bug fixes''' should always be rebased onto the '''maint''' branch then merged to '''master''' unless either they don't affect '''maint''' or they are not going to be fixed on '''maint''' because the required changes are complex enough that it would risk making '''maint''' unstable.
+
* '''Bug fixes''' should always be rebased onto 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''' are '''''always''''' rebased or merged onto '''master'''. New features are '''not allowed''' on '''maint'''.
+
* '''New Features''' are '''''always''''' rebased or merged onto '''future'''. New features are '''not allowed''' on '''stable'''.
  
 
When and how to use branches depends on the complexity of the changes:
 
When and how to use branches depends on the complexity of the changes:
Line 230: Line 332:
  
 
'''Bug Fix Feature Branch Example'''
 
'''Bug Fix Feature Branch Example'''
  git checkout -b my-bug-fix maint
+
<syntaxhighlight lang="sh">
  # make changes, commit, test, fix, etc.
+
git checkout -b my-bug-fix stable
  git checkout maint
+
# make changes, commit, test, fix, etc.
  git pull --rebase
+
git checkout stable
  git rebase maint my-bug-fix
+
git pull --rebase
  # make && make check to ensure that you're not pushing a broken build!
+
git rebase stable my-bug-fix
  git push upstream maint
+
# make && make check to ensure that you're not pushing a broken build!
  git checkout master
+
git push upstream stable
  git pull --rebase
+
git checkout future
  git merge maint
+
git pull --rebase
  # rebuild and make check again
+
git merge stable
  git push upstream master
+
# rebuild and make check again
 +
git push upstream future
 +
</syntaxhighlight>
  
 
'''Major Feature Branch Example'''
 
'''Major Feature Branch Example'''
  git checkout -b my-new-feature master
+
<syntaxhighlight lang="sh">
  # write and test the first phase of your feature, committing often.
+
git checkout -b my-new-feature future
  git checkout master
+
# write and test the first phase of your feature, committing often.
  git pull --rebase
+
git checkout future
  git merge --no-ff my-new-feature
+
git pull --rebase
  # rebuild and make check for safety
+
git merge --no-ff my-new-feature
  git push upstream master
+
# rebuild and make check for safety
  git checkout my-new-feature
+
git push upstream future
  # write the next phase and repeat until done.
+
git checkout my-new-feature
 +
# write the next phase and repeat until done.
 +
</syntaxhighlight>
  
 
'''Caution:''' When ''switching the branch'' you should cleanup your build dir to avoid "strange behavior". At least you should run <tt>make distclean</tt> before, but better might be
 
'''Caution:''' When ''switching the branch'' you should cleanup your build dir to avoid "strange behavior". At least you should run <tt>make distclean</tt> before, but better might be
cd <yourbuild dir>
+
<syntaxhighlight lang="sh">
rm  -rf * && ../configure <your params> && make && make check
+
cd <yourbuild dir>
 +
rm  -rf * && ../configure "$YOUR_PARAMETERS" && make && make check
 +
</syntaxhighlight>
 
after switching. In case you are building intree you can run
 
after switching. In case you are building intree you can run
git clean -fdx -e /.project -e /.cproject -e /.autotools -e /.settings/
+
<syntaxhighlight lang="sh">
 +
git clean -fdx -e /.project -e /.cproject -e /.autotools -e /.settings/
 +
</syntaxhighlight>
 
instead to remove everything not in the repository with a few exceptions (-e ...). Above exceptions are files, where [[Eclipse]] stores its 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 =====
+
====== 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:
 
Sometimes, e.g. after a new release, the first merge in gnucash-docs will result in an conflict about the version number:
<pre>git status
+
<syntaxhighlight lang="console">
# On branch master
+
git status
 +
# On branch future
 
# You have unmerged paths.
 
# You have unmerged paths.
 
#  (fix conflicts and run "git commit")
 
#  (fix conflicts and run "git commit")
Line 276: Line 387:
 
#
 
#
 
#      both modified:      configure.ac
 
#      both modified:      configure.ac
:</pre>
+
:</syntaxhighlight>
  
 
configure.ac will now contain a section
 
configure.ac will now contain a section
Line 284: Line 395:
 
=======
 
=======
 
AC_INIT(gnucash-docs, 2.6.4)
 
AC_INIT(gnucash-docs, 2.6.4)
>>>>>>> maint</pre>
+
>>>>>>> stable</pre>
  
 
Just remove the markers and the wrong section with your preferred editor.
 
Just remove the markers and the wrong section with your preferred editor.
  
 
Don't forget to run <tt>git commit -a</tt> to tell git, you are ready!
 
Don't forget to run <tt>git commit -a</tt> to tell git, you are ready!
 +
;Note: Do not confuse <code>-a</code> = <code>--all</code> with <code>--amend</code>!
  
=== Link Bugzilla Entries ===
+
==== Link Bugzilla Entries ====
[FIXME:] While this worked with SVN/trac it seems not to work with github.
 
  
 
Often commits are related to [[Bugzilla]] entries. In this case the commit message should contain  
 
Often commits are related to [[Bugzilla]] entries. In this case the commit message should contain  
* '''<tt>Bug #</tt>''<bug number>''<tt>:</tt>''<bug title>''''' or
+
* '''<tt>Bug </tt>''<bug number>''<tt>:</tt>''<bug title>''''' or
* '''<tt>Bug #</tt>''<bug number>''<tt> - </tt>''<bug title>'''''.
+
* '''<tt>Bug </tt>''<bug number>''<tt> - </tt>''<bug title>'''''.
  
 
You can 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.
 
You can 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.
  
=== Patches and Pull Requests ===
+
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 {{BuildServer}} 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:
 
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.
 
* 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.
 
* 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.
 
* 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 ''maint'' branch, do a test merge onto ''master''. Resolve any merge issues with the submitter; if necessary, get a "patch to the patch" to resolve the merge conflicts.
+
* 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 ''master'' or ''maint'':
+
* Once everything is ready, merge your working branch into ''future'' or ''stable'':
** Reset your local ''maint'' and/or ''master'' branches to remove any test merges.
+
** 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.
 
** 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.
 
** Apply the final patches or merge your working branch. When applying take care the patches are committed with the appropriate authorship.
Line 312: Line 426:
 
*** 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.
 
*** 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 <email>"'' with the proper author name and e-mail filled in.
 
*** If the patches came as ordinary diff files to be applied with ''git apply'', you should commit these changes with ''git commit --author "name <email>"'' with the proper author name and e-mail filled in.
** Merge ''maint'' into ''master'' if required; if there's a "patch to the patch" to handle conflicts between ''maint'' and ''master'', use <tt>--strategy=theirs</tt> to the merge, then apply the repair patch and commit '''amending'' the merge commit:
+
** Merge ''stable'' into ''future'' if required; if there's a "patch to the patch" to handle conflicts between ''stable'' and ''future'', use <tt>--strategy=theirs</tt> to the merge, then apply the repair patch and commit '''amending'' the merge commit: <SyntaxHighlight lang="sh">
  git checkout master
+
git checkout future
  git merge --strategy=theirs maint
+
git merge --strategy=theirs stable
  git apply patch-to-the-patch
+
git apply patch-to-the-patch
  git commit -a --amend
+
git commit -a --amend
 +
</SyntaxHighlight>
 
* Push the results
 
* Push the results
 
* Close the pull request or mark the patches "Committed" in Bugzilla.
 
* Close the pull request or mark the patches "Committed" in Bugzilla.
  
'''Pull Request Notes:'''
+
===== Pull Request Notes =====
* When processing a pull request it's safest to download the pull request as a (series of) patch(es). When you pull from the submitter's GitHub repository branch you risk conflicts because it hasn't been rebased to match the current state of the branch you're pulling to, though you can avoid that by making a working branch from the main branch commit that's at the base of the submitter's working branch. There may also be problems if the submitter has made changes to the working branch after making the pull request.
+
: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:
* Note that code review comments can be made inline from the "Files Changed" tab of the pull request page on GitHub.
+
# 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 <code>git pull -f ... </code> 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 <tt>Files Changed</tt> 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:
  
Other options exists as well; feel free to edit this wiki page.
+
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 {{BuildServer}}):
 +
<syntaxhighlight lang="sh">
 +
git pull https://github.com/0-wiz-0/Gnucash future
 +
</syntaxhighlight>
  
[[Development_Process|Back to Development Process]]
+
If future on {{BuildServer}} has diverged from 0-wiz-0's future branch, this will trigger a merge action, otherwise it would be a fast-forward.
  
[[Category:Development]]
+
;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.
  
== Collaboration ==
+
Here is a breakdown of the relevant info in the PR message compared to the git pull command:
  
With rare exceptions we don't want to clutter the master repository with feature branches, so how can two developers collaborate on one?
+
['''github-user'''] wants to merge x commits into Gnucash:['''target-branch'''] from ['''github-user''']: ['''source-branch''']
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 [[http://en.wikipedia.org/wiki/B._F._Skinner#Pigeon-guided_missile Really?]]). You can arrange for all of your repositories to be available on the net, and <tt>git pull</tt> amongst yourselves. Or you can use one of the public repositories like Github or Gitorious to manage your changes.
+
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.
  
= Accessing GnuCash BugZilla from Git =
+
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 {{BuildServer}} (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): <syntaxhighlight lang="sh">
 +
git pull https://github.com/"$github-user"/"$repo" "$source-branch"
 +
</syntaxhighlight>
 +
:;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.
  
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.&ndash;all from the command line. See the [[git-bz]] page for details.
+
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.
  
= Htdocs Conversion Notice =
+
;Another approach: is to add "fetch = +refs/pull/*/head:refs/pull/origin/*" to [remote "origin"] in your <tt>.git/config</tt>.
For some time now the gnucash-htdocs repository has been used to store both the website and a compiled version of our documentation in html, pdf, ebup and mobi formats. The problem with this was that the ''compiled documentation'' is pretty large. The repository was finally over 800Mb in size and increasing with each release. That meant that over time a simple clone of the repository would cost increasingly more bandwidth, diskspace and users time.
+
:After a <code>git fetch origin</code> you can i.e. <Syntaxhighlight lang="sh">
 +
git checkout -b PR${PRNR} pull/origin/${PRNR}  # ${PRNR}: Number of the pull request
 +
</Syntaxhighlight> to get a pull request branch based on its number.
 +
:(from https://gist.github.com/Chaser324/ce0505fbed06b947d962#checking-out-and-testing-pull-requests)
 +
:;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.
  
People that wish to work on the website don't need this compiled documentation so the large download was an unnecessary burden. We have decided to fix this by splitting off the compiled documentation into a separate repository, which is only relevant for a release manager. After the split, the gnucash-htdocs repository has been regenerated without the docs history.
+
;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 (https://github.com/...), 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.
  
As we were doing maintenance on this repository we ''removed the "trunk" branch'' as well in favour of the more git-typical "master" branch.
+
== Collaboration ==
  
== Update your clones and forks ==
+
With rare exceptions we don't want to clutter the future repository with feature branches, so how can two developers collaborate on one?
If you have your own clone of the gnucash-htdocs git repository you will have to reclone the new repository if you want to enjoy the smaller footprint. If you have local changes you'll want to preserve them. So instead of deleting the directory rename it. For the examples we'll call it <tt>gnucash-htdocs-old</tt>, and we'll clone into <tt>gnucash-htdocs-new</tt>. That's just to make sure we don't forget which is which. After the import process is complete, you can remove <tt>gnucash-htdocs-old</tt> and rename <tt>gnucash-htdocs-new</tt>.
+
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 [[{{URL:wp}}B._F._Skinner#Pigeon-guided_missile Really?]]). You can arrange for all of your repositories to be available on the net, and <tt>git pull</tt> amongst yourselves. Or you can use one of the public repositories like Github or Gitorious to manage your changes.
  
You've been assiduous about always using <tt>git pull --rebase</tt>, right? No? You've got changes mixed into <tt>master</tt>? No matter. <tt>rebase</tt> to the rescue: (I'm using <tt>master</tt> as an example here, but it could be any tracking branch.)
+
== Accessing GnuCash BugZilla from Git ==
  cd gnucash-htdocs-old
 
  git pull --rebase
 
  git branch -m master foo #This is your new feature branch. You can call it anything you like
 
  git branch -t master origin/master
 
  git rebase master foo
 
There. Now all of your changes are in a nice feature branch. You might have to reconcile some conflicts, but better sooner than later, eh? If you already have feature branches -- we'll use <tt>foo</tt> for our example -- just make sure that it's up to date with its tracking branch:
 
  git checkout master
 
  git pull --rebase
 
  git rebase master foo
 
  
Now you're ready to export your changes. Do this one feature branch at the time. Create a set of patches for your feature branch:
+
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.&ndash;all from the command line. See the [[git-bz]] page for details.
  cd ../gnucash-htdocs-old
 
  git checkout foo
 
  git format-patch --stdout master > ../foo.mbox
 
  
And import your branch foo into the new repo:
+
== Related Topics ==
  cd ../gnucash-htdocs-new
 
  git checkout master
 
  git checkout -b foo
 
  git am ../foo.mbox
 
  
That's it. Repeat for each feature branch and tracking branch. When you're done and really, really sure that everything is properly set up,
+
* [[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.
you can delete <tt>gnucash-htdocs-old</tt> and any <tt>foo.mbox you created</tt>.
+
* [[Documentation_Update_Instructions]] focuses specifically on documentation updates.
 +
* [https://help.github.com/ GitHub Help] in particular [https://help.github.com/articles/fork-a-repo/ 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.
  
'''Note:''' When you run <tt>git checkout master</tt> in <tt>gnucash-htdocs-new</tt>, git ''should'' respond with
+
----
  Checking out files: 100% (1247/1247), done.
 
  Branch master set up to track remote branch master from origin.
 
  Switched to a new branch 'master'
 
''If it doesn't'', then it may have gotten confused. If
 
  git log --oneline -n 10
 
doesn't produce the expected results,
 
  git branch -D master
 
  git branch -t master origin/master
 
To get the proper master branch.
 
  
;Github Forks: If you have made a Github fork you will need to make sure that your local repo is current and then delete the fork and re-fork the regenerated repository, then proceed according to the instructions above, finally pushing any new branches back to your Github fork.
+
Other options exists as well; feel free to edit this wiki page.
  
= Related Topics =
+
[[Development_Process|Back to Development Process]]
 
 
* [https://help.github.com/ GitHub Help] in particular [https://help.github.com/articles/fork-a-repo/ fork-a-repo].
 
* [[Git Migration]] tracked the required changes to our infrastructure and support code before we were able to switch to a pure git based workflow.
 
* [[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: 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.
 
* [[Git For Newbies]] 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.
 

Latest revision as of 18:22, 6 January 2024

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.

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: for code, documentation and for the website...

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:

  • gnucash.git: the program,
  • gnucash-docs: user documentation,
  • gnucash-htdocs: Webserver, if you cloned/forked it before 2013-01 see Htdocs Split,
  • 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
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, translations, improvements of the documentation 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 <worktree> 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 <path> [<branch>]
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] <commit>... 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
https://github.com/Gnucash/gnucash-docs (documentation)
https://github.com/Gnucash/gnucash-htdocs (website)
See https://github.com/Gnucash 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:<YOUR-GITHUB-USERNAME>/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 should branch off of stable unless the bug applies only to the unstable version.
    • New features must branch off of future.

The following example is for a new feature; substitute stable for future if you're doing a bug-fix.

  • 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 future
    git branch working-branch
    
  • Rebase your working branch onto the target branch often so that you stay in sync:
    git rebase future 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 <list of new or modified files>       # 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 <old name or path> <new name or path>  # Rename or move files
git rm <list of obsolete files>               # 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 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 should always be rebased onto 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 are always rebased or merged onto future. New features are not allowed on stable.

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 <yourbuild dir>
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 <file>..." 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 <bug number>:<bug title> or
  • Bug <bug number> - <bug title>.

You can 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.

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 <email>" 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:
  1. Require the author to rebase their branch and resolve the conflicts themselves, then force-push the branch.
  2. Pull the PR branch into a local branch that's current and resolve the conflicts in the resulting merge commit.
  3. 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 https://gist.github.com/Chaser324/ce0505fbed06b947d962#checking-out-and-testing-pull-requests)
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 (https://github.com/...), 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
  1. Before version 5.0 stable was named maint and future master. Discussionand Announcement