{"id":13466362,"url":"https://github.com/projecthamster/hamster","last_synced_at":"2025-05-15T01:05:39.474Z","repository":{"id":4646354,"uuid":"5791555","full_name":"projecthamster/hamster","owner":"projecthamster","description":"GNOME time tracker","archived":false,"fork":false,"pushed_at":"2024-07-04T15:15:05.000Z","size":10929,"stargazers_count":1103,"open_issues_count":137,"forks_count":251,"subscribers_count":56,"default_branch":"master","last_synced_at":"2025-05-11T10:04:28.063Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://projecthamster.org","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/projecthamster.png","metadata":{"files":{"readme":"README.md","changelog":"NEWS.md","contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2012-09-13T07:49:10.000Z","updated_at":"2025-05-04T19:15:56.000Z","dependencies_parsed_at":"2022-06-25T21:36:00.716Z","dependency_job_id":"eb8abf47-d547-4e4b-baee-67cca7f5667a","html_url":"https://github.com/projecthamster/hamster","commit_stats":{"total_commits":3222,"total_committers":287,"mean_commits":"11.226480836236934","dds":0.6654252017380509,"last_synced_commit":"81be67e08a6c2a69f2f042df5459dba886cbd7de"},"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/projecthamster%2Fhamster","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/projecthamster%2Fhamster/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/projecthamster%2Fhamster/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/projecthamster%2Fhamster/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/projecthamster","download_url":"https://codeload.github.com/projecthamster/hamster/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254254039,"owners_count":22039792,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T15:00:42.962Z","updated_at":"2025-05-15T01:05:39.431Z","avatar_url":"https://github.com/projecthamster.png","language":"Python","funding_links":[],"categories":["Open-Source"],"sub_categories":[],"readme":"# Hamster - The Gnome Time Tracker\n\nHamster is time tracking for individuals. It helps you to keep track of how\nmuch time you have spent during the day on activities you choose to track.\n\nThis is the main repo. It is standalone (single module).  \nAll other repositories -`hamster-lib/dbus/cli/gtk`- are part of the separate rewrite effort.  \nMore context is given in the history section below.\n\nSome additional information is available in the\n[wiki](https://github.com/projecthamster/hamster/wiki).\n\n## Installation\n\n### Backup database\n\nThis legacy hamster should be stable, and keep database compatibility with previous versions.  \nIt should be possible to try a new version and smoothly roll back to the previous version if preferred.  \nNevertheless, things can always go wrong. It is strongly advised to backup the database before any version change !\n\n##### Locate the latest db\n\n```bash\nls --reverse -clt ~/.local/share/hamster*/*.db\n```\nBackup the last file in the list. \n\n\n### Kill hamster daemons\n\nWhen trying a different version, make sure to kill the running daemons:\n\n```bash\n# either step-by-step, totally safe\npkill -f hamster-service\npkill -f hamster-windows-service\n# check (should be empty)\npgrep -af hamster\n\n# or be bold and kill them all at once:\npkill -ef hamster\n```\n\n### Install from packages\n\n##### Debian and Ubuntu\n\nPackage status Debian: https://tracker.debian.org/pkg/hamster-time-tracker\nPackage status Ubuntu: https://launchpad.net/ubuntu/+source/hamster-time-tracker\n\nInstallation:\n```sudo apt install hamster-time-tracker```\n(or graphical package installer).\n\n##### OpenSUSE\nhttps://software.opensuse.org/package/hamster-time-tracker\n\n##### Fedora and EPEL\n\nPackage status: https://src.fedoraproject.org/rpms/hamster-time-tracker\n\nAs of November 2023, hamster has only been packaged up to fc30 (with hamster version 2.0).\n\nInstallation (on releases with existing package):\n```sudo dnf install hamster-time-tracker```\n(or graphical package installer).\n\nFor more recent releases, refer to compilation from sources above.\n\n##### Snap\n\nEasy installation on any distribution supporting snap:  \nhttps://snapcraft.io/hamster-snap\n\n##### Flatpak\n\n[Flatpak](https://flatpak.org/) enables you to install Hamster in a versioned\nenvironment and then run it inside a sandbox. It is a method independent from\nyour distribution-specific packaging system, ensuring that the application can\nalways be reproducibly built, even without hunting down all of the dependencies\nyourself. Debugging is made easier as every user has the exact same environment\nat runtime. Permissions are limited to what the application really needs to\nfunction properly.\n\nYou can install the Hamster Flatpak from [Flathub](https://flathub.org/apps/details/org.gnome.Hamster) via:\n\n```bash\nflatpak install flathub org.gnome.Hamster\n```\n\nIf you would like to install Hamster only for your user, simply pass the\n`--user` option to the above command.\n\nTo invoke Hamster from the command line, use:\n\n```bash\nflatpak run org.gnome.Hamster [args...]\n```\n\n### Install from sources\n\n#### Dependencies\nHamster needs python 3.6 or newer (not included in below install\ncommands). Older versions are not supported.\n\n##### Debian-based\n\n###### Ubuntu (tested in 19.04 and 18.04)\n\n```bash\nsudo 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\n# and for documentation\nsudo apt install itstool yelp\n```\n\n##### openSUSE\n\nLeap-15.0 and Leap-15.1:\n```bash\nsudo zypper install intltool python3-cairo python3-gobject-Gdk\nsudo zypper install itstool yelp\n```\n\n##### Fedora\n\n```bash\nsudo dnf install gettext intltool python3-pyxdg python3-cairo python3-gobject\nsudo dnf install python3-dbus itstool yelp\n```\n\n##### Help reader\nIf the hamster help pages are not accessible (\"unable to open `help:hamster-time-tracker`\"),\nthen a [Mallard](https://en.wikipedia.org/wiki/Mallard_(documentation))-capable help reader is required,\nsuch as [yelp](https://wiki.gnome.org/Apps/Yelp/).\n\n#### Download source\n\n##### Git clone\n\nIf familiar with github, just clone the repo and `cd` into it.\n\n##### Download\n\nOtherwise, to get the `master` development branch (intended to be quite stable):\n```bash\nwget https://github.com/projecthamster/hamster/archive/master.zip\nunzip master.zip\ncd hamster-master\n```\nor a specific [release](https://github.com/projecthamster/hamster/releases):\n```bash\n# replace 2.2.2 by the release version\nwget https://github.com/projecthamster/hamster/archive/v2.2.2.zip\nunzip v2.2.2.zip\ncd hamster-2.2.2\n```\n\n#### Build and install\n\n```bash\n./waf configure build\n# thanks to the parentheses the umask of your shell will not be changed\n( umask 0022 \u0026\u0026 sudo ./waf install; )\n```\nThe `umask 0022` is safe for all, but important for users with more restrictive umask,\nas discussed [here](https://github.com/projecthamster/hamster/pull/421#issuecomment-520167143).\n\nNow restart your panels/docks and you should be able to add Hamster!\n\n##### Flatpak\n\nAlternatively, you can also build a sandboxed\n[flatpak](https://www.flatpak.org/) yourself. You might need to install the\nGNOME SDK beforehand (an error will notify you about it, if needed). Execute:\n\n```bash\nflatpak-builder --force-clean --user --install \\\n    build/flatpak data/org.gnome.Hamster.flatpak.yml\n```\n\nThis creates a temporary flatpack build folder in the ``build/flatpak``\ndirectory. Once the app is installed, the whole ``build/flatpack/`` directory\ncan be removed.\n\n#### Uninstall\n\nTo undo the last install, just\n```bash\nsudo ./waf uninstall\n```\nAfterwards `find /usr -iname hamster` should only list unrelated files (if any).\nOtherwise, please see the [wiki section](https://github.com/projecthamster/hamster/wiki/Tips-and-Tricks#uninstall)\n\n##### Flatpak\n\nTo remove the installed flatpak, just run:\n\n```bash\nflatpak uninstall org.gnome.Hamster\n```\n\n#### Troubleshooting\n\n[wiki section](https://github.com/projecthamster/hamster/wiki/Tips-and-Tricks#troubleshooting)\n\n#### Development\n\nDuring development (As explained above, backup `hamster.db` first !),\nif only python files are changed \n(*deeper changes such as the migration to gsettings require a new install*)\nthe changes can be quickly tested by\n```\n# either\npgrep -af hamster\n# and kill them one by one\n# or be bold and kill all processes with \"hamster\" in their command line\npkill -ef hamster\npython3 src/hamster-service.py \u0026\npython3 src/hamster-cli.py\n```\nAdvantage: running uninstalled is detected, and windows are *not* called via\nD-Bus, so that all the traces are visible.\n\nNote: You'll need recent version of hamster installed on your system (or \n[this workaround](https://github.com/projecthamster/hamster/issues/552#issuecomment-585166000)).\n\n#### Running tests\n\nHamster has a limited test suite, that can be run using Python's builtin\nunittest module. From the top-level directory, just run:\n\n    python3 -m unittest\n\nThis will let unittest automatically find all testcases in all files\ncalled `test_*.py`, and runs them.\n\nTo run a subset of tests, specify the import path towards it. For\nexample, to run just a single test file, class or method respectively\nrun:\n\n    python3 -m unittest tests.test_stuff\n    python3 -m unittest tests.test_stuff.TestFactParsing\n    python3 -m unittest tests.test_stuff.TestFactParsing.test_plain_name\n\n##### Flatpak\n\nTo run the tests inside the flatpak, use:\n\n```bash\nflatpak-builder --run build/flatpak data/org.gnome.Hamster.flatpak.yml \\\n    python3 -m unittest\n```\n\n#### Migrating\n\n##### Migrating data to flatpak\n\nIf you would like to retain your data from a non-flatpak installation,\nyou can do so by running:\n\n```bash\ngio copy -b \\\n    ~/.local/share/hamster/hamster.db \\\n    ~/.var/app/org.gnome.Hamster/data/hamster/\n```\n\nAfter checking everything works, you can remove the original database.\n\n##### Migrating from hamster-applet\n\nPreviously Hamster was installed everywhere under `hamster-applet`. As\nthe applet is long gone, the paths and file names have changed to\n`hamster`. To clean up previous installs follow these steps:\n\n```bash\ngit checkout d140d45f105d4ca07d4e33bcec1fae30143959fe\n./waf configure build --prefix=/usr\nsudo ./waf uninstall\n```\n\n## Contributing\n\n1. [Fork](https://github.com/projecthamster/hamster/fork) this project\n2. Create a topic branch - `git checkout -b my_branch`\n3. Push to your branch - `git push origin my_branch`\n4. Submit a [Pull Request](https://github.com/projecthamster/hamster/pulls) with your branch\n5. That's it!\n\nSee [How to contribute](https://github.com/projecthamster/hamster/wiki/How-to-contribute) for more information.\n\n\n## History\n\nDuring the period 2015-2017 there was a major effort to\n[rewrite hamster](https://github.com/projecthamster/hamster-gtk)\n(repositories: `hamster-lib/dbus/cli/gtk`).\nUnfortunately, after considerable initial progress the work has remained in alpha state\nfor some time now. Hopefully the effort will be renewed in the future.\n\nIn the meantime, this sub-project aims to pursue development of the \"legacy\" Hamster\ncode base, maintaining database compatibility with the widely installed\n[v1.04](https://github.com/projecthamster/hamster/releases/tag/hamster-time-tracker-1.04),\nbut migrating to `Gtk3` and `python3`.  \nThis will allow package maintainers to provide\nnew packages for recent releases of mainstream Linux distributions for which the old\n1.04-based versions are no longer provided.\n\nWith respect to 1.04, some of the GUI ease of use has been lost, especially for handling\ntags, and the stats display is minimal now. So if you are happy with your hamster\napplication and it is still available for your distribution, upgrade is not recommended\nyet.\n\nIn the meantime recent (v2.2+) releases have good backward data compatibility and are\nreasonably usable. The aim is to provide a new stable v3.0 release in the coming\nmonths (i.e. early 2020).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprojecthamster%2Fhamster","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprojecthamster%2Fhamster","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprojecthamster%2Fhamster/lists"}