View source for Version Control Using Git

<b>Version Control for Koha using Git:</b> So you want to contribute code to Koha, that's great! First off, welcome to the community, we're glad to have you. 

First I want to say a word about version control. Why use version control at all? It may be tempting if you download Koha and install it for your library to just edit the files to customize it for your local needs outside the context of a version control system.

But spending a few minutes learning how to use a version control system will open up a whole new set of ways you can interact with the Koha community, and will make it easy to update your production system, easy to test revisions, and easy to contribute those back to the main project. So if you're going to write or customize Koha code, take a few minutes to familiarize yourself with the primary tool us Koha developers use for version control.

<b>This should be considered a working document, as we all get used to using Git, and we get more developers on board, our workflow is likely to change.</b>

Our goal is to make it as easy as possible to integrate patches from the community, and to make it as easy as possible for all developers to work with the project repositories as well as the features they are developing for their libraries/customers

'''motto''' ''"Every time a patch falls on the floor, a kitten dies"''

== Roles ==

{| class="wikitable"
! Role !! Description
|-
! Release Manager
| Responsible for feature freezes, scheduling a release.
|-
! QA Manager + QA Team
| Responsible for defining coding practices and ensuring that code conforms to coding practices.
|-
! Developers
| Write code, document it, push it out. :-)
|-
! Public
| Do you want to be updated with the last changes without writing code.
|}

== Get Git ==

On Debian 6: 

 sudo apt-get install git-core

On Ubuntu (git-core has been superceded since 10.10) or Debian 7 (Wheezy):

 sudo apt-get install git git-email

For your documentation needs, Scott Chacon over their way wrote this:
* http://git-scm.com/book

== Browse Git ==

The project's public repository, including commit logs, diff viewing, and searching, can be browsed on the Web at
* http://git.koha-community.org/

== Getting Started with Git ==

=== Fill some parameters ===

==== Set your name & mail address ====

 git config --global user.name "your NAME"
 git config --global user.email "your@mail.com"

==== Set up a SMTP server ====

If necessary, set up a SMTP server

 git config --global sendemail.smtpserver "smtp.address.com"
 git config --global sendemail.smtpuser "login@email.address.com"
 git config --global sendemail.smtppass "password"
 git config --global sendemail.smtpssl "true"

For example, to set up using your GMail account as your SMTP server:

 git config --global sendemail.smtpserver smtp.gmail.com
 git config --global sendemail.smtpserverport 587
 git config --global sendemail.smtpencryption tls
 git config --global sendemail.smtpuser your_email@gmail.com
 git config --global sendemail.smtppass your_password

<b>Note:</b> This configuration should also work if your email is hosted on a Gmail platform. Just use your hosted email address in the sendmail.smtpuser slot. If your password contains characters that have special meaning to the shell, you may need to escape them with \ when setting sendemail.smtppass (e.g., typing \! is necessary if ! is in your password).

=== Automatically fix whitespace errors in patches ===

As Chris pointed out in [http://blog.bigballofwax.co.nz/2011/12/15/fixing-whitespace-when-apply-patches-with-git/ his blog], the following lines make Git automatically fix trailing whitespaces

 git config --global core.whitespace trailing-space,space-before-tab
 git config --global apply.whitespace fix

=== Set Syntax Highlighting/Colour UI ===

It can be difficult to scan through content in Git when all the text is grey on black. Enabling this option will change the colours of some of the text to make separations of content more meaningful. This is especially noticeable when using commands such as "git show".

 git config --global color.ui auto

=== More information on Git configuration ===

For more information on customizing your Git configuration, consult sites such as this one: http://git-scm.com/book/en/Customizing-Git-Git-Configuration

== Getting Koha using Git ==

=== Clone the public repository ===

Clone the public repository:

 git clone https://git.koha-community.org/Koha-community/Koha.git kohaclone

You're gonna get a bunch of stuff that looks like:

 $ git clone git://git.koha-community.org/Koha-community/Koha.git kohaclone
   
   remote: Generating pack...
   remote: Done counting 16310 objects.
   remote: Deltifying 16310 objects.
   remote:  100% (16310/16310) done
   Indexing 16310 objects.
   remote: Total 16310, written 16310 (delta 10657), reused 12014 (delta 7834)
   100% (16310/16310) done
   Resolving 10657 deltas.
   100% (10657/10657) done
   Checking files out...
   100% (3429/3429) done

=== Cloning over HTTP ===

To clone the repository using the Git protocol (git:), you need to be able to connect to port 9418 on [http://git.koha-community.org git.koha-community.org]. If for some reason you have a restrictive firewall that cannot be changed, and using SSH port forwarding is not an option, it is possible to clone the repository using HTTP:

 git clone https://git.koha-community.org/Koha-community/Koha.git kohaclone

Other Git operations such as "git fetch" and "git rebase" will work normally after you clone using HTTP.

Note that because this requires a cronjob (git-update-server-info) that is set to run every 10 minutes, cloning or fetching over HTTP can result in a repository that's slightly out of date with respect to the public repository. As a general note, unless you absolutely have to use HTTP because of restrictive firewall rules, using the Git protocol is more efficient, both for you and the server that hosts the repository.

== Doing work on Koha with Git ==

You will want to create a branch to work on.  

If you want to track the current development version, which is on the master branch's HEAD, do this:

 $ <b>cd kohaclone</b>
 $ <b>git checkout -b mywork origin</b>

If you want to track the maintenance branch of an earlier version of Koha (e.g., 3.0.x), you can do the following:

 $ <b>cd kohaclone</b>
 $ <b>git branch -r</b>
  origin/3.0.x
  origin/HEAD
  origin/master

The ''origin/3.0.x'' branch is the name of the maintenance branch for Koha 3.0, including future bugfix releases such as 3.0.1.  To make a local (to your repository) branch to track this (remote, from git.koha-community.org) branch, you can do the following:

 $ <b>git branch --track 3.0.x origin/3.0.x</b>
 $ <b>git checkout 3.0.x</b>

If, after doing this, you want to create a branch on top of the 3.0.x branch in order to do some work, you can do this:

 $ <b>git checkout -b my-3.0-work</b>

If you're still confused read this slightly modified IRC log:

 nengard: got a question - how do i checkout a branch from git - i want just the 3.2 branch not head
 [1:17pm] owen: http://wiki.koha-community.org/wiki/Version_Control_Using_Git
 [1:19pm] owen: nengard: Although I guess that gets you 3.2.x, not official 3.2
 [1:19pm] jcamins: You can also check out by tag.
 [1:21pm] chris: git checkout -b my_3.2.x origin/3.2.x
 [1:21pm] owen: And that gets the 3.2.x development branch right? Not the official release
 [1:21pm] chris: makes it and checks it out
 [1:21pm] chris: if you want the release, you need to check out the tag
 [1:21pm] owen: What about: git checkout v3.02.01
 [1:22pm] chris: owen that will work, but you wont be on a local branch
 [1:22pm] chris: which is totally fine
 [1:22pm] chris: unless you want to make changes and change to another branch

=== Do some work ===

OK, now you've got your own clone, you're ready to get to work. Lets say you're a template designer who works for the Nelsonville Public Library and you're working on some improvements to the templates in Koha Version 3.0. 

So at this point, you're ready to do some work. You'll be able to work within this 'clone' you've created, with version control, so you'll have a complete history of your work, without affecting the rest of the project; and you'll also have a simple way to notify others of the work you've done so they can test it out.

If you've used CVS before, this next bit is gonna be pretty standard. After you've made some changes to a file, simply go:

 $ <b>git commit file</b>

You can also just commit a bunch of files with:

 $ <b>git commit -a</b>

You'll be asked to enter a comment for your patch. The first line of your commit message should be the bug number and title, which you can copy from Bugzilla. '''However''', the hyphen should be replaced with a colon.

[[File:Bugzilla-title-for-commit-message.png]]

==== Commit message ====

Detailed guidelines on writing commit messages can be found at the wiki page on [[Commit messages]].

 <nowiki>
Bug [bug number]: [bug title]

Full description of what the patch does

A detailed test plan, including steps to reproduce the error if necessary.
 </nowiki>

You can see how your recent commit fits into the context of all other commits
in this branch/clone with the log command:

 $ git log

If your work requires changes in the mySQL database, then look at [http://wiki.koha-community.org/wiki/Tutorial_for_Updating_Database_Files http://wiki.koha-community.org/wiki/Tutorial_for_Updating_Database_Files]

=== Update your Git install of Koha ===

Sometimes you'll be working on something on a branch that needs to be updated to the latest 'origin'. Running the following commands will grab all the changes since you last pulled and merge them with your current changes: 

 $ <b>git fetch</b>
 $ <b>git rebase origin/master</b>

If you are working on a branch derived from the 3.0.x branch, you should rebase against ''origin/3.0.x'': 

 $ <b>git rebase origin/3.0.x</b>

===== Using git stash =====

If you have made changes to your copy of Koha and are not ready to commit them just yet you can still update. Simply do this: 

 $ <b>git stash save</b>
 $ <b>git fetch</b>
 $ <b>git rebase origin/master</b>
 $ <b>git stash apply</b>

=== Share with the rest of the world ===

So now we're happy with our work, and we're ready to show it to the world.

The way we do this is the same way as the way the developers for the Linux kernel work. We use the tools in Git to format a patch and upload it as an attachement on Bugzilla. Once that patch has been signed off and checked by the QA Team, it is pushed on to the Release Manager who has final say on where the patch will be applied.

Please make sure your install is up to date with current origin (or the release you are working on) before submitting.

To create a patch and send it to Bugzilla, you can use [http://www.kernel.org/pub/software/scm/git/docs/git-format-patch.html git-format-patch], but we recommend using [[git bz configuration|git bz]].

For creating the patch manually, do:

 $ <b>git format-patch origin</b>

If you are working on a branch derived from the 3.0.x branch, you should 'git format-patch' against ''origin/3.0.x'':

 $ <b>git format-patch origin/3.0.x</b>

It will produce a numbered series of files in the current directory, one for each patch in the current branch but not in origin/HEAD.
 
Now you have to attach your patch file or files to the relevant bug in [http://bugs.koha-community.org Bugzilla]. You can do this manually or by using [http://wiki.koha-community.org/wiki/Git_bz_configuration git-bz]. Git bz has the advantage of allowing you to create the patch files and upload them to Bugzilla in one simple command, saving a lot of the extra steps described above.

=== Delete your Branch ===

To delete a branch:

 git branch -D branchname

To delete multiple branches at once:

 git branch | grep "^  bug_" | xargs git branch -D

N.B. Change "bug_" to whatever branchname pattern that you want to match on for branches to delete

== Koha Revision Control Overview for Release Managers ==

=== Applying Patches ===

Ok, the release manager has received some patches and wants to apply them.

Git also provides a tool called git-am (am stands for "apply mailbox"), for importing such an emailed series of patches. Just save all of the patch-containing messages, in order, into a single mailbox file, say "patches.mbox", then run

 $ <b>git am -3 -i -s -u patches.mbox</b>

Git will apply each patch in order; if any conflicts are found, it will stop, and you can fix the conflicts as described in "Resolving a merge". (The "-3" option tells git to perform a merge; if you would prefer it just to abort and leave your tree and index untouched, you may omit that option.)

Once the index is updated with the results of the conflict resolution, instead of creating a new commit, just run

 $ <b>git am --resolved</b>

and git will create the commit for you and continue applying the remaining patches from the mailbox.

The final result will be a series of commits, one for each patch in the original mailbox, with authorship and commit log message each taken from the message containing each patch.

=== Pushing changes to a public repository ===

Now they want to update the public repository so the rest of the world can get the new code.

The simplest way to do this is using git-push and ssh; to update the remote branch named "master" with the latest state of your branch named "master", run

 $ <b>git push ssh://yourserver.com/~you/proj.git master:master</b>

or just

 $ <b>git push ssh://yourserver.com/~you/proj.git master</b>

As with git-fetch, git-push will complain if this does not result in a fast forward. Normally this is a sign of something wrong. However, if you are sure you know what you're doing, you may force git-push to perform the update anyway by proceeding the branch name by a plus sign:

 $ <b>git push ssh://yourserver.com/~you/proj.git +master</b>

Note that the target of a "push" is normally a bare repository. You can also push to a repository that has a checked-out working tree, but the working tree will not be updated by the push. This may lead to unexpected results if the branch you push to is the currently checked-out branch!

As with git-fetch, you may also set up configuration options to save typing; so, for example, after
 
 $ <b>cat >>.git/config <<EOF
 [remote "public-repo"]
   url = ssh://yourserver.com/~you/proj.git
 EOF</b>
 
you should be able to perform the above push with just

 $ <b>git push public-repo master</b>

See the explanations of the remote.<name>.url, branch.<name>.remote, and remote.<name>.push options in [http://www.kernel.org/pub/software/scm/git/docs/git-config.html git-config] for details.

== Koha Revision Control Overview for QA Manager ==

The QA manager will receive patches and will want to either apply them and then push them upstream to the RM's repo or escalate the patch for the RM to view.

=== Dealing with Patches ===

The QA manager needs to check if the patch is a bugfix or a new feature. If it is a bugfix they then need to check that it confirms to the coding guidelines.  If it does they can then apply the patch (the same way as the RM does). Then they do a git-push to push this back to the RM's repository.
If they are new features, the QA Manager will forward them to the Release Manager to look at.

For example

* Check mail
* Look at new patch email, its a bug fix, looks good, save to a file ''to_apply''
* git-am  to_apply 
* git push
* Let the RM know.

OR 
  
* Check mail
* Look at new patch email, ooh a neat new feature, forward to RM Manager

== Koha Revision Control for the public ==

Clone the public repository

 git clone git://git.koha-community.org/koha.git whateveryouwanttocallyourrepo 

You're gonna get a bunch of stuff that looks like:

 git clone git://git.koha-community.org/koha.git kohaclone 

   remote: Generating pack...
   remote: Done counting 16310 objects.
   remote: Deltifying 16310 objects.
   remote:  100% (16310/16310) done
   Indexing 16310 objects.
   remote: Total 16310, written 16310 (delta 10657), reused 12014 (delta 7834)
   100% (16310/16310) done
   Resolving 10657 deltas.
   100% (10657/10657) done
   Checking files out...
   100% (3429/3429) done

To update the files in your machine:

 cd /your path/kohaclone
 git pull

You're gonna get a bunch of stuff that looks like:

 $ <b>git pull</b>
   Updating a4d6314..3d41470
   Fast forward
   C4/Biblio.pm                                       |  209 +-
   C4/Branch.pm                                       |   16 +-
   C4/Breeding.pm                                     |    7 +-
   C4/Circulation.pm                                  |   48 +-
   C4/Context.pm                                      |    3 +-
   C4/Items.pm                                        |    6 +-
   C4/Koha.pm                                         |  550 +-
   C4/Languages.pm                                    |   38 +-
   C4/Output.pm                                       |   19 +-
   C4/Reports.pm                                      |   51 +-
   C4/SIP/ILS/Transaction/Checkout.pm                 |    5 +-
   C4/SIP/ILS/Transaction/Renew.pm                    |    3 +-
   INSTALL.debian                                     |    7 +-
   Makefile.PL                                        |    3 +
   admin/cities.pl                                    |   12 +-
   admin/letter.pl                                    |   15 +-
   admin/printers.pl                                  |   13 +-
   admin/roadtype.pl                                  |   12 +-
   .../intranet-tmpl/prog/en/includes/help-bottom.inc |   11 +-
   .../intranet-tmpl/prog/en/includes/help-top.inc    |    4 +-
   .../prog/en/includes/reports-menu.inc              |    6 +
   .../prog/en/includes/sysprefs-menu.inc             |    2 +-
   t/Accounts.t                                       |    3 +

After you have successfully pulled a new 'Koha' repo and you want to rewind your repo back to the Release-Candicate-1 tag (as it's currently at HEAD) for a nice safe install,  try this...

 $ <b>git fetch --tags</b>
 $ <b>git reset --hard v3.00.00-stableRC1</b>

== Notes ==

If you want to mail the diffs, put the following in the post-receive file:

 echo "Summary of changes:"
    git diff-tree --stat --summary --find-copies-harder $oldrev..$newrev
    git diff $oldrev $newrev

French tutorial / doc : 

I (Paul) have found that http://wiki.archlinux.fr/howto:production:git is very clear and useful.

'''NOTE''' if you get this error:

    Environment problem:
    Your name cannot be determined from your system services (gecos).
    You would need to set GIT_AUTHOR_NAME and GIT_COMMITTER_NAME 
    environment variables; otherwise you won't be able to perform
    certain operations because of "empty ident" errors.
    Alternatively, you can use user.name configuration variable.
    
    fatal: empty ident  <your@email.com> not allowed

You're probably using a slightly older version of git that needs you to export some
variables:

 $ export GIT_AUTHOR_NAME="whatever"

 $ export GIT_COMMITER_NAME="whatever"

This could easily also be called "How to Submit a Patch". I'm mucking about here so that'll come up on a search. ;)

== Tips and tricks ==

You can also find some tips and tricks for advanced user at the [[tips_and_tricks]]

== Further reading ==

* Git - http://git-scm.com/ - the home page of the git package
* The git tutorial - http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html - a good starting place
* Git For Designers - http://hoth.entp.com/output/git_for_designers.html - an introduction to the concepts behind git
* Git in a Nutshell - http://jonas.iki.fi/git_guides/HTML/git_guide/ - a clearly written introduction to the use of git
* Git man pages - http://www.kernel.org/pub/software/scm/git/docs/ - the official git documentation, intended for technically-oriented users
* Git Reference - http://gitref.org/ - crash course in using git
* Pro Git - http://progit.org/book/ - an entire book on using git better
* Git From the Bottom Up - http://ftp.newartisans.com/pub/git.from.bottom.up.pdf - a clearly-written article on the theory behind git
* GitHub documentation - http://help.github.com/ - although specific to GitHub, this documentation can be useful if you want to share your code via GitHub
* BitBucket documentation - http://confluence.atlassian.com/display/BITBUCKET/bitbucket+Documentation+Home - although specific to BitBucket, this documentation can be useful if you want to share your code via BitBucket
* Streamline your git workflow with aliases - http://robots.thoughtbot.com/post/4747482956/streamline-your-git-workflow-with-aliases - a very cool guide to reducing the number of keystrokes required for commonly repeated tasks

{{DevBook}}

[[Category:Git]]
[[Category:Documentation]]