{"id":34307501,"url":"https://github.com/rathrio/punch","last_synced_at":"2025-12-17T08:50:01.486Z","repository":{"id":24069408,"uuid":"27455764","full_name":"rathrio/punch","owner":"rathrio","description":"A CLI for file based time tracking","archived":false,"fork":false,"pushed_at":"2025-10-25T18:25:53.000Z","size":326,"stargazers_count":4,"open_issues_count":1,"forks_count":1,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-10-25T20:29:45.836Z","etag":null,"topics":["cli","ruby","time-tracker"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rathrio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2014-12-02T22:01:52.000Z","updated_at":"2025-10-25T18:25:57.000Z","dependencies_parsed_at":"2025-10-25T20:20:36.627Z","dependency_job_id":"33298730-24f6-4c12-a0d4-686e94c81a39","html_url":"https://github.com/rathrio/punch","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/rathrio/punch","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rathrio%2Fpunch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rathrio%2Fpunch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rathrio%2Fpunch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rathrio%2Fpunch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rathrio","download_url":"https://codeload.github.com/rathrio/punch/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rathrio%2Fpunch/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":27780620,"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","status":"online","status_checked_at":"2025-12-17T02:00:08.291Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["cli","ruby","time-tracker"],"created_at":"2025-12-17T08:50:00.929Z","updated_at":"2025-12-17T08:50:01.480Z","avatar_url":"https://github.com/rathrio.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"$ punch\n=======\n\n[![Build Status](https://travis-ci.org/rathrio/punch.svg?branch=master)](https://travis-ci.org/rathrio/punch) [![Coverage Status](https://coveralls.io/repos/rathrio/punch/badge.svg?branch=master\u0026service=github)](https://coveralls.io/github/rathrio/punch?branch=master) [![Inline docs](http://inch-ci.org/github/rathrio/punch.svg?branch=master)](http://inch-ci.org/github/rathrio/punch)\n\nPunch is a CLI for tracking your monthly hours in plain text files, e.g.:\n\n```\nNovember 2014\n\n20.11.14   08:00-12:00   12:30-18:30   Total: 10:00\n22.11.14   14:00-16:00                 Total: 02:00\n\nTotal: 12:00\n```\n\nRecommended Installation\n------------------------\n\nClone this repo and run `rake install` to create a symlink to `/usr/local/bin`.\n\n```bash\n# Clone the repo.\ngit clone git@github.com:rathrio/punch.git ~/wherever/you/like/punch\n\n# Change into punch directory.\ncd ~/wherever/you/like/punch\n\n# Create the symlink.\nsudo rake install\n```\n\nYou should now be able to run `punch` from anywhere.\n\nAlternatively, instead of running `rake install`, you could manually create a\nsymlink or an alias that runs the executable `punch.rb` in the repo's root\nfolder.\n\n```bash\n# Example alias.\nalias punch='./wherever/you/like/punch/punch.rb'\n```\n\n### Tab completion\n\nBash tab completion can be enabled by sourcing `punch-completion.bash`. Zsh\ncompletion is currently provided\n[here](https://github.com/rathrio/punch-zsh-completion).\n\n### Uninstallation\n\nTo remove any links to punch in `/usr/local/bin` run `rake uninstall`.\n\nHelp and Documentation\n----------------------\n\nAn exhaustive list of flags and switches can be found in `help.txt`, which will\nalso be printed via the `--help` (`-h`) switch. The most important features are\ndocumented below in more detail.\n\nTo browse the docs locally, make sure you have the\n[`yard`](https://github.com/lsegal/yard) gem installed and run `punch --doc`.\nThis will open them up in your default web browser.\n\nUsage\n-----\n\nPunch saves your working hours in a plain text file. Each file represents one\nmonth and new files will be automatically generated as time goes by. To display\nthe month, execute `punch` without any arguments:\n\n```\n$ punch\n\nKrusty Krab - Mai 2015 - Spongebob Squarepants\n\n10.05.15\n\nTotal: 00:00\n```\n\nThe first line is the header, which contains a title, the current month name and\nyour full name. The following lines list the days you have worked on on a\nseparate line each. The last line shows the monthly total.\n\nThe current day is always visible, even if you haven't added any blocks to it\nyet. That's why you only see the current date in an empty month. For the\nfollowing examples the current day will 10.05.15 (DD.MM.YY).\n\n### Adding blocks\n\nA block is a time span with a start and an end time and you can add them to the\ncurrent day like this:\n\n```\n$ punch 08:00-12:30\n\nKrusty Krab - Mai 2015 - Spongebob Squarepants\n\n10.05.15   08:00-12:30   Total: 04:30\n\nTotal: 04:30\n```\n\nLeading zeros and minutes may be omitted, thus `punch 8-12:30` is equivalent to\n`punch 08:00-12:30`. The colon can be omitted for 3+ digits.\n\nYou can pass multiple blocks to add them all to the current day:\n\n```\n$ punch 8-12:30 13:15-18\n\nKrusty Krab - Mai 2015 - Spongebob Squarepants\n\n10.05.15   08:00-12:30   13:15-18:00   Total: 09:15\n\nTotal: 09:15\n```\n\n### Adding blocks to past days\n\n#### `--yesterday`\n\nYou forgot to punch your time yesterday? Use the `--yesterday` (`-y`) switch:\n\n```\n$ punch -y 8-10\n\nKrusty Krab - Mai 2015 - Spongebob Squarepants\n\n09.05.15   08:00-10:00                 Total: 02:00\n10.05.15   08:00-12:30   13:15-18:00   Total: 09:15\n\nTotal: 11:15\n```\n\n#### `--day`\n\nIf yesterday is not far enough in the past, you can pass a date to add blocks to with the\n`--day` (`-d`) flag:\n\n```\n$ punch -d 08.05.15 21:45-22\n\nKrusty Krab - Mai 2015 - Spongebob Squarepants\n\n08.05.15   21:45-22:00                 Total: 00:15\n10.05.15   08:00-12:30   13:15-18:00   Total: 09:15\n\nTotal: 09:30\n```\n\n#### `--edit` and `--format`\n\nSometimes you mess up or you just want to manually edit the text file. For\nscenarios like these, the `--edit` (`-e`) switch will open up the current text\nfile with your default text editor. You don't have to worry about the totals or\nindentation when manually editing the file. Punch will automatically format the\nfile the next time you add some blocks. To trigger formatting by hand, use the\n`--format` (`-f`) switch.\n\n### Overlaps\n\nPunch will automatically merge blocks together should you add one that overlaps\nwith others on the same day. So running `punch 12-15` and `punch 13-18` results\nin `12-18`.\n\n```\n$ punch 12-15\n\nKrusty Krab - Mai 2015 - Spongebob Squarepants\n\n10.05.15   12:00-15:00   Total: 03:00\n\nTotal: 03:00\n\n$ punch 13-18\n\nKrusty Krab - Mai 2015 - Spongebob Squarepants\n\n10.05.15   12:00-18:00   Total: 06:00\n\nTotal: 06:00\n```\n\nThis behaviour can be used to append, prepend and overwrite blocks.\n\n#### Caveats\n\nA block belongs to the current day if the block's start time is on the current\nday. This means that blocks that span over midnight are not split up, but belong\nto the day they start at. Adding blocks on the following day that overlap with\nthese over-midnight blocks are currently not handled correctly.\n\n```\n$ punch\n\nKrusty Krab - Mai 2015 - Spongebob Squarepants\n\n09.05.15   23:00-02:00   Total: 03:00\n\nTotal: 03:00\n\n$ punch 1-4\n\nKrusty Krab - Mai 2015 - Spongebob Squarepants\n\n09.05.15   23:00-02:00   Total: 03:00\n10.05.15   01:00-04:00   Total: 03:00\n\nTotal: 06:00\n```\n\n### Removing blocks\n\nTo remove blocks, use `punch --remove` (`-r`). It can also be used to \"cut\nholes\" into existing blocks, e.g. a lunch break:\n\n```\n$ punch 8-17\n\nKrusty Krab - Mai 2015 - Spongebob Squarepants\n\n30.10.20   08:00-17:00   Total: 09:00\n\nTotal: 09:00\n\n$ punch -r 12-13\n\nKrusty Krab - Mai 2015 - Spongebob Squarepants\n\n30.10.20   08:00-12:00   13:00-17:00   Total: 08:00\n\nTotal: 08:00\n```\n\n\nConfiguration\n-------------\n\nA lot of behaviour can be configured in `~/.punchrc`. Run `punch --config` to\nedit that file.\n\nUpdating\n--------\n\nRun `punch --update` to pull in the latest changes from the remote master.\n\nRun `punch --config-update` to update `.punchrc` from time to time, so that it\nalways knows about all available options.\n\nDevelopment\n-----------\n\nRun `bundle install` to install development dependencies.\n\nRun `rake test` to run the test suite.\n\nPlease setup and configure [Rubocop](https://github.com/rubocop-hq/rubocop) to\nrespect the rules in `.rubocop.yml` in this repository's root and lint your\nchanges.\n\nPunch tries to remain free of third party runtime dependencies so that it can\nrun on any system with just Ruby installed. The gems listed in `Gemfile` are\nloaded for development purposes only.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frathrio%2Fpunch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frathrio%2Fpunch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frathrio%2Fpunch/lists"}