hamster-tools/README.md

# hamster-tools

Manipulate [hamster-time-tracker](https://github.com/projecthamster/) data
from the command-line, including:

 - find duplicate activities
 - list, move and delete categories, activities and facts

Merging, renaming and otherwise tidying-up the database used to be possible in
the Hamster GUI, but currently (as of version 2.0.0.16) doesn't work for me, so
I wrote this script to fill in the gap until the [shiny new version of
hamster](https://github.com/projecthamster/hamster-lib) is ready.

    $ pip install .

    $ hamster-tools categories --help
    Usage: hamster-tools categories [OPTIONS] COMMAND [ARGS]...

    Options:
      --help  Show this message and exit.

    Commands:
      activities  Show activities for categories specified by IDS
      delete      Delete categories specified by IDS
      list        List / search categories
      tidy        Delete empty categories

    $ hamster-tools activities --help
    Usage: hamster-tools activities [OPTIONS] COMMAND [ARGS]...

    Options:
      --help  Show this message and exit.

    Commands:
      delete           Delete activities specified by IDS
      find-duplicates  Show activities which are not unique in their categories
      list             List / search activities
      list-facts       Show facts for activities
      move             Move activities to another category
      move-facts       Move facts from one activity to another

    $ hamster-tools export 
    Usage: hamster-tools export [OPTIONS] COMMAND [ARGS]...

    Options:
      --help  Show this message and exit.

    Commands:
      kimai  Export time tracking data in Kimai format

## Importing into Kimai

1. Run `python -m hamstertools activities list --csv` to get a dump of all activities
2. Review the export to check for any duplicates, typoes, etc. 
3. Use e.g. `python -m hamstertools activities move-facts ...` to clean them up
4. Run `python -m hamstertools kimai import --mapping-path data/mapping.2023.kimai.csv --show-missing --after 2023-09-07 --category-search auto 3wordchant` to find entries in your time tracking which don't yet have a mapping to Kimai. You might notice some extra tidying needed here.
5. Run `python -m hamstertools kimai sync --mapping-path data/mapping.2023.kimai.csv --just-errors --ignore-activities 3wordchant $(pass users/calix/logins/kimai.autonomic.zone/api)` to find items in your mapping file which don't exist on Kimai
5. Run `python -m hamstertools kimai import --mapping-path data/mapping.2023.kimai.csv --after 2023-09-07 --category-search auto 3wordchant --output data/kimai_$(date +%F).csv` to generate a CSV of your time entries
6. Review your timesheet -- NB it might not be sorted in date order by default - to make sure it has the expected entries, and remove any entries already in Kimai.