Hamster - The Gnome Time Tracker

Hamster is time tracking for individuals. It helps you to keep track of how much time you have spent during the day on activities you choose to track.

This is the main repo. It is standalone (single module).
All other repositories -hamster-lib/dbus/cli/gtk- are part of the separate rewrite effort.
More context is given in the history section below.

Some additional information is available in the wiki.

Installation

Backup database

This legacy hamster should be stable, and keep database compatibility with previous versions.
It should be possible to try a new version and smoothly roll back to the previous version if preferred.
Nevertheless, things can always go wrong. It is strongly advised to backup the database before any version change !

Locate the latest db

ls --reverse -clt ~/.local/share/hamster*/*.db

Backup the last file in the list.

Kill hamster daemons

When trying a different version, make sure to kill the running daemons:

# either step-by-step, totally safe
pkill -f hamster-service
pkill -f hamster-windows-service
# check (should be empty)
pgrep -af hamster

# or be bold and kill them all at once:
pkill -ef hamster

Install from packages

Debian and Ubuntu

Package status Debian: https://tracker.debian.org/pkg/hamster-time-tracker Package status Ubuntu: https://launchpad.net/ubuntu/+source/hamster-time-tracker

Installation: sudo apt install hamster-time-tracker (or graphical package installer).

OpenSUSE

https://software.opensuse.org/package/hamster-time-tracker

Fedora and EPEL

Package status: https://src.fedoraproject.org/rpms/hamster-time-tracker

As of November 2023, hamster has only been packaged up to fc30 (with hamster version 2.0).

Installation (on releases with existing package): sudo dnf install hamster-time-tracker (or graphical package installer).

For more recent releases, refer to compilation from sources above.

Arch Linux

Project status: https://archlinux.org/packages/extra/any/hamster-time-tracker/

Installation: sudo pacman -S hamster-time-tracker

Snap

Easy installation on any distribution supporting snap:
https://snapcraft.io/hamster-snap

Flatpak

Flatpak enables you to install Hamster in a versioned environment and then run it inside a sandbox. It is a method independent from your distribution-specific packaging system, ensuring that the application can always be reproducibly built, even without hunting down all of the dependencies yourself. Debugging is made easier as every user has the exact same environment at runtime. Permissions are limited to what the application really needs to function properly.

You can install the Hamster Flatpak from Flathub via:

flatpak install flathub org.gnome.Hamster

If you would like to install Hamster only for your user, simply pass the --user option to the above command.

To invoke Hamster from the command line, use:

flatpak run org.gnome.Hamster [args...]

Install from sources

Dependencies

Hamster needs python 3.6 or newer (not included in below install commands). Older versions are not supported.

Debian-based

Ubuntu (tested in 19.04 and 18.04)

sudo apt install gettext intltool python3-gi python3-cairo python3-gi-cairo python3-distutils python3-dbus libglib2.0-dev libglib2.0-bin gir1.2-gtk-3.0 gtk-update-icon-cache
# and for documentation
sudo apt install itstool yelp

openSUSE

Leap-15.0 and Leap-15.1:

sudo zypper install intltool python3-cairo python3-gobject-Gdk
sudo zypper install itstool yelp

Fedora

sudo dnf install gettext intltool python3-pyxdg python3-cairo python3-gobject
sudo dnf install python3-dbus itstool yelp

Help reader

If the hamster help pages are not accessible ("unable to open help:hamster-time-tracker"), then a Mallard-capable help reader is required, such as yelp.

Download source

Git clone

If familiar with github, just clone the repo and cd into it.

Download

Otherwise, to get the master development branch (intended to be quite stable):

wget https://github.com/projecthamster/hamster/archive/master.zip
unzip master.zip
cd hamster-master

or a specific release:

# replace 2.2.2 by the release version
wget https://github.com/projecthamster/hamster/archive/v2.2.2.zip
unzip v2.2.2.zip
cd hamster-2.2.2

Build and install

./waf configure build
# thanks to the parentheses the umask of your shell will not be changed
( umask 0022 && sudo ./waf install; )

The umask 0022 is safe for all, but important for users with more restrictive umask, as discussed here.

Now restart your panels/docks and you should be able to add Hamster!

Flatpak

Alternatively, you can also build a sandboxed flatpak yourself. You might need to install the GNOME SDK beforehand (an error will notify you about it, if needed). Execute:

flatpak-builder --force-clean --user --install \
    build/flatpak data/org.gnome.Hamster.flatpak.yml

This creates a temporary flatpack build folder in the build/flatpak directory. Once the app is installed, the whole build/flatpack/ directory can be removed.

Uninstall

To undo the last install, just

sudo ./waf uninstall

Afterwards find /usr -iname hamster should only list unrelated files (if any). Otherwise, please see the wiki section

Flatpak

To remove the installed flatpak, just run:

flatpak uninstall org.gnome.Hamster

Troubleshooting

wiki section

Development

During development (As explained above, backup hamster.db first !), if only python files are changed (deeper changes such as the migration to gsettings require a new install) the changes can be quickly tested by

# either
pgrep -af hamster
# and kill them one by one
# or be bold and kill all processes with "hamster" in their command line
pkill -ef hamster
python3 src/hamster-service.py &
python3 src/hamster-cli.py

Advantage: running uninstalled is detected, and windows are not called via D-Bus, so that all the traces are visible.

Note: You'll need recent version of hamster installed on your system (or this workaround).

Running tests

Hamster has a limited test suite, that can be run using Python's builtin unittest module. From the top-level directory, just run:

python3 -m unittest

This will let unittest automatically find all testcases in all files called test_*.py, and runs them.

To run a subset of tests, specify the import path towards it. For example, to run just a single test file, class or method respectively run:

python3 -m unittest tests.test_stuff
python3 -m unittest tests.test_stuff.TestFactParsing
python3 -m unittest tests.test_stuff.TestFactParsing.test_plain_name

Flatpak

To run the tests inside the flatpak, use:

flatpak-builder --run build/flatpak data/org.gnome.Hamster.flatpak.yml \
    python3 -m unittest

Migrating

Migrating data to flatpak

If you would like to retain your data from a non-flatpak installation, you can do so by running:

gio copy -b \
    ~/.local/share/hamster/hamster.db \
    ~/.var/app/org.gnome.Hamster/data/hamster/

After checking everything works, you can remove the original database.

Migrating from hamster-applet

Previously Hamster was installed everywhere under hamster-applet. As the applet is long gone, the paths and file names have changed to hamster. To clean up previous installs follow these steps:

git checkout d140d45f105d4ca07d4e33bcec1fae30143959fe
./waf configure build --prefix=/usr
sudo ./waf uninstall

Contributing

1. Fork this project
2. Create a topic branch - git checkout -b my_branch
3. Push to your branch - git push origin my_branch
4. Submit a Pull Request with your branch
5. That's it!

See How to contribute for more information.

History

During the period 2015-2017 there was a major effort to rewrite hamster (repositories: hamster-lib/dbus/cli/gtk). Unfortunately, after considerable initial progress the work has remained in alpha state for some time now. Hopefully the effort will be renewed in the future.

In the meantime, this sub-project aims to pursue development of the "legacy" Hamster code base, maintaining database compatibility with the widely installed v1.04, but migrating to Gtk3 and python3.
This will allow package maintainers to provide new packages for recent releases of mainstream Linux distributions for which the old 1.04-based versions are no longer provided.

With respect to 1.04, some of the GUI ease of use has been lost, especially for handling tags, and the stats display is minimal now. So if you are happy with your hamster application and it is still available for your distribution, upgrade is not recommended yet.

In the meantime recent (v2.2+) releases have good backward data compatibility and are reasonably usable. The aim is to provide a new stable v3.0 release in the coming months (i.e. early 2020).