Latest revision as of 22:06, 6 January 2024

This page is for explaining the use of git in the development process to programmers, documenters or translators who are not familiar with git.

Alternatives

For really trivial patches like fixing a typo you can also follow Simple Pull Request without installing Git.

Git contains a few more technical details and tricks..

Developers who have write (commit) access to the official (canonical) GnuCash git repositories are often termed Committers. This page is for Non-Committers.

These instructions are only an unofficial suggested methodology. Git is a very powerful tool and there are often many different ways to do something. If you know of a better way, please feel free to update this page.

What is Git?

Git is a distributed version control system (VCS) originally developed by Linus Torvalds for managing Linux source code without requiring a central server. You can get the latest version for your system and read a rich variety of online documentation at Git's Home. In particular, Pro Git by Scott Chacon is available in several languages for free online reading at Git Book.

If you know nothing about version control, read Getting Started - About Version Control.

Another good place to start is Good Resources for Learning Git and GitHub - especially if you want to use GitHub for #Pull Requests.

On the command line

git help

will give you the list of commands and

git help $COMMAND

will show you the manual page of that command.

Tools

While pure git has only a command line interace (CLI) there are several graphical user interfaces (GUI)s available for git, for example:

• git gui
• gitk (shows the history)

  Windows or Mac only

  • GitHub Desktop
  • SourceTree, and
• most IDEs have plugins for it.

What does that have to do with Gnucash?

We manage our code and documentation sources in Git.

Our public repositories are mirrored on Github: for

the program

gnucash,

its documentation

gnucash-docs,

several OS dependent installer packages

gnucash-on-OS, and

our website

gnucash-htdocs.

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 repository.

Using the Github Repository

Branches

Program and Documentation

can have 3 important branches in our repositories^[1]:

stable

is the default branch in git. Bugfixes, translations, and improvements to the documentation should usually be applied on this branch.

future

will be created when the first New feature preferrable from Release_Schedule#Goals_for_6.0 gets implemented.

unstable

will only appear in the beta testing phase with 5.9xx releases.

Packaging Repos gnucash-on-…

have only a master branch,

Website

additional a beta branch for test purposes.

Non-Committers should always work in their own working branch specific to the bug or feature being worked on. Name your working branch after the bug or feature - e.g. bug-12345 or invoice-new-button.

Patches or Pull Requests?

There are 2 main ways to submit bug fixes, modifications or enhancements for review:

GitHub pull requests

These are preferred by the developers due to rich GitHub code review functionality, but are slightly more complicated to create than patches.

Proceed to #Pull Requests.

Patches

A patch is essentially a specially formatted file containing a list of the files that have been changed, and for each file, before and after listings of the changed lines.

Patches

Set-Up

Create the directory you wish to hold your repository or repositories in and make it current.

mkdir ~/git
cd ~/git

git clone https://github.com/Gnucash/gnucash.git

other URLs

https://github.com/Gnucash/gnucash-docs.git (documentation)

https://github.com/Gnucash/gnucash-htdocs.git (website)

See https://github.com/Gnucash for further repos e.g. with OS/distro specific build scripts.

The clone example above will create the local repository ~/github/gnucash/ and also defines a remote named origin pointing to the cloned from repository which you can use in future as a shortcut instead of the full URL.

cd gnucash

Only the default branch master will have been cloned.

git branch --track stable origin/stable

Create a working-branch (Patches)

• Open a bug in Bugzilla to attach your patch to if one doesn't already exist.
• 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.
• Create a local (on your PC) branch to work in:

Bug fixes should branch from stable unless the bug applies only to the unstable or future version.

New features must branch from future.

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

git checkout stable

Note

checkout prepares your local repositories working directory ready for work on a particular branch by resetting all files back to how they were at the time they were last committed.

It is much easier if you only checkout a branch after committing all changes you have made to the current branch.

You will get a warning if you try to change branches and there are uncommitted changes.

It is not wise to leave a file open in an editor while checking out a branch as you may accidentally save a version from another branch.

git branch working-branch        # Creates branch ''working-branch'' from the current branch
git checkout working-branch	 # make working-branch current
# OR
git checkout -b working-branch   # create ''working-branch'' from the current branch and check it out in one step

You are now ready to make and test your changes in your local working branch.

Commit

See Documentation Improvement#Commit Your Changes

Sync your local stable or future from origin (Patches)

After you have completed your changes, to minimize the chances of your future patch conflicting with any changes that may have been committed to the official GnuCash repositories while you were working:

• Update the local stable or future branch (depending on which your working branch was created from) in your local repository from origin:

  git checkout stable
  git pull origin stable
  # or
  git checkout future
  git pull origin future
  

• Rebase your working branch commits based on the updated stable or future:

  git rebase stable working-branch
  

You can update both stable and future if you wish but you only need to update the branch on which your working branch was based.

• Test again to make sure everything works with the rebased code

Create Patch(es)

A patch file is created for each commit.

• Use git rebase -i as necessary to make a clean series of patches for complex changes.
• Use git format-patch to create the actual patches from your commits:

  cd ~/github/gncucash
  git format-patch origin/stable..stable
  # or
  git diff  # to prepare them.
  

• Attach the resulting patch(es) to the bug report. It is not necessary to email anyone as the relevant people are automatically emailed when you attach a patch to a bug.
• 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.

Cleanup

git checkout stable
git branch -D working-branch
#  E.g.
git branch -D bug-99999	# delete local branch bug-99999

If you no longer require your local repository, you can just delete the folder on your PC and its sub-folders.

Prepare for your next patch

Follow the instructions in #Sync your local stable or future from origin (Patches), then #Create a working-branch (Patches).

Pull Requests

If you prefer, you can use a GitHub Pull Request (PR) instead of attaching a patch to a bug. Once set up, submitting changes using PRs is very straightforward and easy.

See Setup for Pull Requests for more information on how to create a development environment for PRs.

Create a working-branch (Pull Requests)

• Create a branch to work in:

Bug fixes should branch from stable unless the bug applies only to the future version.

New features must branch from future.

• Open a bug in Bugzilla to enable your work to be tracked if one doesn't already exist.

The following example is for a bugfix and therefore uses stable; substitute stable by future if you're creating a new feature.

• Use a particular working branch for only one bug or feature. This will make it much easier to make changes should that prove necessary.

  git checkout stable              # Checkout the branch (stable or future) on which your new ''working-branch'' will be based
  
  git branch working-branch        # Create branch ''working-branch'' from the current branch
  git checkout working-branch
  #  OR
  git checkout -b working-branch   # create ''working-branch'' from the current branch and check it out in one step
  

Note

checkout prepares your local repositories working directory for work on a particular branch by resetting all files back to how they were at the time that branch was last committed.

It is much easier if you only checkout a branch after committing all changes you have made to the current branch.

It is not wise to leave a file open in an editor while checking out a branch as you may accidentally save a version from another branch.

You are now ready to make and test your changes in your local working branch.

Commit

See Documentation_Update_Instructions#Commit_Your_Changes

Sync your local stable or future branch from upstream (Pull Requests)

After you have completed and tested your changes, to minimize the chances of your future pull request conflicting with any changes that may have been committed to the official GnuCash repositories while you were working:

• Check if remote upstream is already defined

 git remote -v

• If upstream is not already defined, create it. For example

  # to use ssh
  git remote add upstream ssh://git@github.com/Gnucash/gnucash
  # or if you don't want to set up ssh keys, use https
  git remote add upstream https://github.com/Gnucash/gnucash.git

• Update the local stable or future branch (depending on which your working branch is based) in your local repository from upstream:

 git checkout stable
 git pull upstream stable
 or
 git checkout future
 git pull upstream future

• Update stable or future in your personal GitHub repository (origin) from your local repository:

 git push origin stable

• Rebase your working branch commits based on the updated stable or future:

 git rebase stable working-branch

• Test again to make sure everything works with the rebased code.

You can update both stable or future if you wish but you only need to update the branch on which your working branch was based.

Push Back To Your Personal Repository

If you followed these instructions and cloned to your local working-branch from your personal github repository, then the remote name origin already points to your personal remote github

$ git remote -v

 origin	git@github.com:<YOUR-GITHUB-USERNAME>/gnucash-docs.git (fetch)
 origin	git@github.com:<YOUR-GITHUB-USERNAME>/gnucash-docs.git (push)
 upstream  https://github.com/gnucash/gnucash-docs (fetch)
 upstream  https://github.com/gnucash/gnucash-docs (push)

so you can push your working-branch to your remote personal github repository by:

 # Note: no need to checkout your working-branch first
 git push origin working-branch
 E.g.
 git push origin bug-99999

git push '''--force''' origin working-branch

If you already made a pull request before the amendment, your reviewers have to refresh their browser to display your recent changes correctly on the PR page.

If your remote named origin does not point to your personal github repository but you have another remote which does, then substitute your remote name for origin in the above.

If you don't have a remote name that points to your personal github repository,

# add a remote name that does, E.g. to add remote named '''mygithub''':
git remote add mygithub ssh://git@github.com/<YOUR-GITHUB-USERNAME>/gnucash
# and push
git push mygithub working-branch

Create a Pull Request

1. Now log in to your GitHub account, go to your forked gnucash repository, select working-branch from the branch pick list, and click pull request. It's above the "last commit" line on the right in the directory view.
2. 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.
3. Click the Send Pull Request button to the right of the description block.
4. 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!

Cleanup

• Once the pull request has been reviewed and either merged or rejected, you can delete the branch.

From your local computer

git branch -D ${WORKING_BRANCH}
# Example:
git branch -D bug-99999	# delete local branch bug-99999

From your personal remote github mirror

git push $REMOTE :${WORKING_BRANCH}  # note space before :working-branch
# Example:
git push origin :bug-99999

If you no longer require your local repository, you can just delete the folder on your PC and it's sub-folders.

Prepare for your next working branch