Beginning with WebGUI 7.8.x development will be conducted and tracked through Git rather than Subversion.  The git repository is hosted on GitHub: http://github.com/plainblack/webgui

We realize not everyone is familiar with the use of Git.  This page has a brief guide on how to check out and use Git. For more information, use the git help command or read the tutorials and manuals on the Git documentation page.

INSTALLATION

On Linux, git should be available from your package manager.  If it is not, or if you are using a different operating system, binaries and source are available on the Git download page.

Getting started

The first thing to do is to set some configuration options for git.

# User information
$ git config --global user.name 'Your Full Name'
$ git config --global user.email 'Your Email'
# https://github.com/account - click 'Global Git Config' for these values
# optional, but used by various downloadable utilities
$ git config --global github.user 'your github user'
$ git config --global github.token 'your github token'

# Colorize output
$ git config --global color.ui auto

# Friendlier remote tracking
# Uses rebase for pulls, creating a cleaner history
# what rebase does:
http://blog.woobling.org/2009/08/git-rebase-for-impatient.html
# why we want to use it for pulls:
http://blog.woobling.org/2009/05/git-rebase-considered-awesome.html
$ git config --global branch.autosetuprebase remote

# Safer pushing - only push current tracking branch by default
$ git config --global push.default tracking

# Convenient aliases
$ git config --global alias.st status
$ git config --global alias.ci commit
$ git config --global alias.cp cherry-pick

# tell git to ignore various temp/backup files. make adjustments here as needed for your platform.
# these are global across all repositories
$ git config --global core.excludesfile ~/.gitignore
$ echo '*.swp' >> ~/.gitignore
$ echo '*~' >> ~/.gitignore
$ echo '*.bak' >> ~/.gitignore
$ echo '*.orig' >> ~/.gitignore
$ echo '*.rej' >> ~/.gitignore
$ echo '.DS_Store' >> ~/.gitignore

After setting the configuration options, the next step is to clone the git repository.  The command used depends on if you have contributor access to the repository.  If you do have contributor access:

$ cd /data
$ git clone git@github.com:plainblack/webgui.git WebGUI 

If you don't have contributor access:

$ cd /data
$ git clone git://github.com/plainblack/webgui.git WebGUI

This will download the entire WebGUI repository at its current state onto your computer.  It will also checkout the current development branch, called 'master'.  If you start without contributor access but later gain it, you can change the URL using the command:

$ git config remote.origin.url git@github.com:plainblack/webgui.git

Next, you can configure repository specific options.

$ cd WebGUI
# ensure info directory exists
$ mkdir .git/info
# ignore WebGUI config files
$ echo '/etc/*.conf' >> .git/info/exclude
# can add other patterns for files in the webgui directory to ignore

Once you have the clone, you can switch to other branches.  The first time you use a branch, you need to create a local tracking branch:

$ git checkout -b webgui-7.7 origin/webgui-7.7

After you've created your tracking branch, you can switch between branches just by giving it the branch name.

$ git checkout master
$ git checkout webgui-7.7

A list of your branches is available with the 'git branch' command.

$ git branch
* master
   webgui-7.7
$ git branch -a
* master
  webgui-7.7
  remotes/origin/DataTable
  remotes/origin/HEAD -> origin/master
  remotes/origin/WebGUI8
  remotes/origin/crypt
  remotes/origin/flux
  remotes/origin/gh-pages
  remotes/origin/master
  remotes/origin/memcached
  remotes/origin/template_usage
  remotes/origin/thingy_defaultView_maxEntries
  remotes/origin/webgui-7.5
  remotes/origin/webgui-7.6
  remotes/origin/webgui-7.7  

Keeping Updated

Everytime someone changes the Git repository, a new commit is created. In order to make sure you have the latest revision of the codebase, use the git pull command. 

$ cd /data/WebGUI
$ git pull

This will fetch available changes and update your working copy to the latest commit from the repository.

Saving Your Changes

Now you've changed some code in your working copy, fixed any bugs you might have made, run the regression tests, and are ready to add your changes to WebGUI. In order to add your code to the repository, you must commit your changes using git commit, and push them to the server with git push.

$ cd /data/WebGUI
$ git commit -a

This will launch a text editor for you to add some comments about what you are committing, for example:

fix: Fixed a bug in Collaboration Systems where dates were not properly formatted
rfe: Added ability for user to configure how Collaboration System dates are formatted
Updated some documentation for WebGUI::Session::Date

At the bottom of the text editor window, you'll see a list of the files that have been added or changed in your new commit.

Next, you will push your changes to the server:

$ git push

This will push your changes to the server.  If your local repository was not up to date, your push will be refused.  In this case, you will need to run git pull to bring your copy up to date before trying tp push again.

Making Patches

If you do not have permission to commit to the repository, but still want to fix a bug or implement an RFE, you can help by submitting a patch. You can create patches in the unified diff format using git diff. Follow the steps above for getting ready to save your changes (make sure there are no bugs, run the regression tests), but instead of committing,   do the following:

$ cd /data/WebGUI
$ git diff > patch.txt

You now have a unified diff at /data/WebGUI/patch.txt. You can apply this patch to other WebGUI instances by doing the following:

$ cd /data/WebGUI
$ patch -p1 < /data/WebGUI/patch.txt

Read man patch for more information on how to apply patches.

Comparing Revisions

Find the revisions that you want to compare using git log or the GitHub interface. Use the following:

$ git diff 20c1942 0cbc4ee

Repository Layout

There are a number of branches in the WebGUI repositiory.  The 'master' branch is where all new development takes place.  This the branch you would use if you are developing new features.  There also branches stable version development.  'webgui-7.7' is the branch for 7.7 bugfixes.  Other branches are feature branches for developing larger projects.

WRE Build files are at http://github.com/plainblack/wrebuild

Viewing the Revision Log

You can review the revision log online via GitHub's interface. Visit http://github.com/plainblack/webgui; find the directory that you are interested in then click on "history" at the top right of the file listing to view changes made to the directory and subdirectories.