
guitone - a Qt-Frontend for monotone
====================================

Guitone is a frontend to the monotone revision control system. It aims towards
a full implementation of the monotone automation interface and is especially
targeted at beginners. Guitone is copylefted under the terms of the GNU General
Public License Version 3, or, at your option, any later version of this license.

You need Qt >= 4.3.4 to - legally (*) - build and monotone >= 0.39
(or a monotone with an interface version of 7.0 or greater) to run guitone.
Earlier versions do not have all the infrastructure for certain functionalities
available, but might still work in some areas. (You have to lower the
requirements in the project file and rebuild monotone before you can
actually make it work with older versions - but this is not recommended.)

To build under Linux / Mac OS X, just do

 $ cd /path/to/guitone
 $ lrelease guitone.pro
 $ qmake -config release
 $ make

On Mac OS X you need the Sparkle framework (http://sparkle.andymatuschak.org/)
installed to build guitone. Make sure it does reside outside
/System/Library/Frameworks if you plan to build with the univsersal SDK
(the default).
You can also build guitone with Xcode on Mac OS X. You should have a recent
version of Xcode installed (>= 2.2 because of gcc bugs) which is usually
found somewhere on the installation DVD. Then you can create a Xcode
project file with

 $ qmake -spec macx-xcode

and open this with Xcode. If you need to tweak settings (i.e. architecture)
in the Qt project file (guitone.pro), remember to redo this step.

The created binary can be found in bin/.

If you like to build on Windows, all you need is a working version of
Qt 4.2.x. Please check the docs at trolltech.com for assistance how to
build Qt on Windows.
After that get the sources of guitone, unpack them into some directory
and run qmake in it. Then start your favourite make tool and you're done.

The most recent version can always be obtained from the guitone
repository at thomaskeller.biz. guitone is located in the branch
net.venge.monotone.guitone:

 $ mtn db init -d guitone.mtn
 $ mtn pull -d guitone.mtn thomaskeller.biz "net.venge.monotone.guitone"


Program Notes
=============

* If you encounter crashes, make sure that you've cleaned out any old
  settings directory, usually under .config/GUITONE or (in newer versions)
  under .config/Thomas\ Keller. Newer versions of guitone save their
  settings according to the underlying platform, ie. as config file
  under MacOS X (~/Library/Preferences/biz.thomaskeller.guitone.conf) or
  in the registry under Windows.

* If you still encounter crashes try to enable the file log in the
  Preferences dialog. The log is usually saved in your home directory,
  as "guitone.log". Please send this file, together with a description
  what you've done and (optionally) a gdb backtrace to the author.

* If column sizes in the file diff dialog aren't properly sized and
  any resize attempts are not remembered, please open guitone's
  configuration and remove any entry for 'diffView_header' manually.
  You can find the configuration in 
    $HOME/.config/Thomas\ Keller/guitone.conf
  on Linux / Unix, in
    $HOME/Library/Preferences/biz.thomaskeller.guitone.plist
  on Mac OS X and finally in the registry under
    HKEY_CURRENT_USER\Software\Thomas Keller\guitone
  if you're using a Windows build.

* mtn 0.40 has a serious bug in automate identify which makes guitone
  crash. If you encounter this problem, please upgrade to a newer
  version where this problem has been fixed (0.41, f.e.) or do not
  use the "find unaccounted renames" functionality

* On Mac OS X, Qt up until 4.4 is unable to watch bigger numbers of paths
  for changes in parallel, so you might get spurious outputs like
  the following in your console / logfile:

    warning: QFileSystemWatcher: failed to add paths: /path/to/file

  You can usually ignore them, but you should note that guitone's workspace
  view might then not always be up to date, so you should refresh the view
  by hand if you're uncertain. 


Platform Notes
==============

* If you like to compile guitone on Mac OS X, make sure you've
  updated your gcc to 4.0.1 or newer which comes with XCode
  2.2 or later. Otherwise you'll get a "Bus error" on runtime
  due to a bug in gcc 4.0.0

* If you encounter segfaults and other weird crashs on Linux when
  closing dialogs please ensure you've a recent enought Qt version.
  Apparently in 4.2.2 the problem is no longer present.

* On Qt 4.3.3 and earlier the generation of a valid Xcode project fails
  because of problems with escaped characters in the project file. This has
  been reported to Trolltech - in the meantime you should do

  $ qmake -spec macx-xcode guitone.pro
  $ cd guitone.xcodeproj
  $ sed -e 's/\\\\\"/\\\"/g' < project.pbxproj > project.pbxproj.new \
    && mv project.pbxproj.new project.pbxproj


Known Bugs
==========

* Most of the workspace commands (add, drop, update, rename, ...) haven't been
  implemented because the monotone automation interface does not yet have
  support for them. This will eventually be changed in the future on either
  side (i.e. either I will implement the functionality directly in monotone or
  I'll use the normal command line interface to trigger the commands), but
  this heavily depends on my workload and mood...
  The Update Workspace dialog and the right-click actions in the workspace
  view are therefore just stubs and won't do anything.

* If you enable "read workspace incrementally" in the preferences and work with
  a monotone version below 0.40 you might encounter weird problems in the
  workspace view. This is because the interpretation of the --depth option in mtn
  has been changed and guitone only supports the new interpretation of version
  0.40 or higher. So if you're still on 0.39 its better to leave this unchecked.

* If your problem is not described here, take a look at the task list on
  http://guitone.thomaskeller.biz/g/tracker


Author
======

Thomas "TommyD" Keller <me AT thomaskeller DOT biz>

Contributions are very welcome, I'm usually hanging around in the monotone
IRC at irc://irc.oftc.net/#monotone so don't hesitate to contact me!


Former Contributors
===================

Ingo "Slinky" Maindorfer <ingo AT liquidcooling DOT de>
Jean-Louis "Ganwell" Fuchs <ganwell AT fangorn DOT ch>

(*) Trolltech re-licensed Qt 4.3.4 and Qt 4.4 under the terms of the GNU
General Public License Version 3, so while earlier versions of the 4.3 series
technically just work the same, they should not be linked and / or
distributed with those older binaries.
