https://github.com/rathrio/punch
A CLI for file based time tracking
https://github.com/rathrio/punch
cli ruby time-tracker
Last synced: 6 months ago
JSON representation
A CLI for file based time tracking
- Host: GitHub
- URL: https://github.com/rathrio/punch
- Owner: rathrio
- License: mit
- Created: 2014-12-02T22:01:52.000Z (over 11 years ago)
- Default Branch: master
- Last Pushed: 2025-10-25T18:25:53.000Z (8 months ago)
- Last Synced: 2025-10-25T20:29:45.836Z (8 months ago)
- Topics: cli, ruby, time-tracker
- Language: Ruby
- Homepage:
- Size: 318 KB
- Stars: 4
- Watchers: 4
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
$ punch
=======
[](https://travis-ci.org/rathrio/punch) [](https://coveralls.io/github/rathrio/punch?branch=master) [](http://inch-ci.org/github/rathrio/punch)
Punch is a CLI for tracking your monthly hours in plain text files, e.g.:
```
November 2014
20.11.14 08:00-12:00 12:30-18:30 Total: 10:00
22.11.14 14:00-16:00 Total: 02:00
Total: 12:00
```
Recommended Installation
------------------------
Clone this repo and run `rake install` to create a symlink to `/usr/local/bin`.
```bash
# Clone the repo.
git clone git@github.com:rathrio/punch.git ~/wherever/you/like/punch
# Change into punch directory.
cd ~/wherever/you/like/punch
# Create the symlink.
sudo rake install
```
You should now be able to run `punch` from anywhere.
Alternatively, instead of running `rake install`, you could manually create a
symlink or an alias that runs the executable `punch.rb` in the repo's root
folder.
```bash
# Example alias.
alias punch='./wherever/you/like/punch/punch.rb'
```
### Tab completion
Bash tab completion can be enabled by sourcing `punch-completion.bash`. Zsh
completion is currently provided
[here](https://github.com/rathrio/punch-zsh-completion).
### Uninstallation
To remove any links to punch in `/usr/local/bin` run `rake uninstall`.
Help and Documentation
----------------------
An exhaustive list of flags and switches can be found in `help.txt`, which will
also be printed via the `--help` (`-h`) switch. The most important features are
documented below in more detail.
To browse the docs locally, make sure you have the
[`yard`](https://github.com/lsegal/yard) gem installed and run `punch --doc`.
This will open them up in your default web browser.
Usage
-----
Punch saves your working hours in a plain text file. Each file represents one
month and new files will be automatically generated as time goes by. To display
the month, execute `punch` without any arguments:
```
$ punch
Krusty Krab - Mai 2015 - Spongebob Squarepants
10.05.15
Total: 00:00
```
The first line is the header, which contains a title, the current month name and
your full name. The following lines list the days you have worked on on a
separate line each. The last line shows the monthly total.
The current day is always visible, even if you haven't added any blocks to it
yet. That's why you only see the current date in an empty month. For the
following examples the current day will 10.05.15 (DD.MM.YY).
### Adding blocks
A block is a time span with a start and an end time and you can add them to the
current day like this:
```
$ punch 08:00-12:30
Krusty Krab - Mai 2015 - Spongebob Squarepants
10.05.15 08:00-12:30 Total: 04:30
Total: 04:30
```
Leading zeros and minutes may be omitted, thus `punch 8-12:30` is equivalent to
`punch 08:00-12:30`. The colon can be omitted for 3+ digits.
You can pass multiple blocks to add them all to the current day:
```
$ punch 8-12:30 13:15-18
Krusty Krab - Mai 2015 - Spongebob Squarepants
10.05.15 08:00-12:30 13:15-18:00 Total: 09:15
Total: 09:15
```
### Adding blocks to past days
#### `--yesterday`
You forgot to punch your time yesterday? Use the `--yesterday` (`-y`) switch:
```
$ punch -y 8-10
Krusty Krab - Mai 2015 - Spongebob Squarepants
09.05.15 08:00-10:00 Total: 02:00
10.05.15 08:00-12:30 13:15-18:00 Total: 09:15
Total: 11:15
```
#### `--day`
If yesterday is not far enough in the past, you can pass a date to add blocks to with the
`--day` (`-d`) flag:
```
$ punch -d 08.05.15 21:45-22
Krusty Krab - Mai 2015 - Spongebob Squarepants
08.05.15 21:45-22:00 Total: 00:15
10.05.15 08:00-12:30 13:15-18:00 Total: 09:15
Total: 09:30
```
#### `--edit` and `--format`
Sometimes you mess up or you just want to manually edit the text file. For
scenarios like these, the `--edit` (`-e`) switch will open up the current text
file with your default text editor. You don't have to worry about the totals or
indentation when manually editing the file. Punch will automatically format the
file the next time you add some blocks. To trigger formatting by hand, use the
`--format` (`-f`) switch.
### Overlaps
Punch will automatically merge blocks together should you add one that overlaps
with others on the same day. So running `punch 12-15` and `punch 13-18` results
in `12-18`.
```
$ punch 12-15
Krusty Krab - Mai 2015 - Spongebob Squarepants
10.05.15 12:00-15:00 Total: 03:00
Total: 03:00
$ punch 13-18
Krusty Krab - Mai 2015 - Spongebob Squarepants
10.05.15 12:00-18:00 Total: 06:00
Total: 06:00
```
This behaviour can be used to append, prepend and overwrite blocks.
#### Caveats
A block belongs to the current day if the block's start time is on the current
day. This means that blocks that span over midnight are not split up, but belong
to the day they start at. Adding blocks on the following day that overlap with
these over-midnight blocks are currently not handled correctly.
```
$ punch
Krusty Krab - Mai 2015 - Spongebob Squarepants
09.05.15 23:00-02:00 Total: 03:00
Total: 03:00
$ punch 1-4
Krusty Krab - Mai 2015 - Spongebob Squarepants
09.05.15 23:00-02:00 Total: 03:00
10.05.15 01:00-04:00 Total: 03:00
Total: 06:00
```
### Removing blocks
To remove blocks, use `punch --remove` (`-r`). It can also be used to "cut
holes" into existing blocks, e.g. a lunch break:
```
$ punch 8-17
Krusty Krab - Mai 2015 - Spongebob Squarepants
30.10.20 08:00-17:00 Total: 09:00
Total: 09:00
$ punch -r 12-13
Krusty Krab - Mai 2015 - Spongebob Squarepants
30.10.20 08:00-12:00 13:00-17:00 Total: 08:00
Total: 08:00
```
Configuration
-------------
A lot of behaviour can be configured in `~/.punchrc`. Run `punch --config` to
edit that file.
Updating
--------
Run `punch --update` to pull in the latest changes from the remote master.
Run `punch --config-update` to update `.punchrc` from time to time, so that it
always knows about all available options.
Development
-----------
Run `bundle install` to install development dependencies.
Run `rake test` to run the test suite.
Please setup and configure [Rubocop](https://github.com/rubocop-hq/rubocop) to
respect the rules in `.rubocop.yml` in this repository's root and lint your
changes.
Punch tries to remain free of third party runtime dependencies so that it can
run on any system with just Ruby installed. The gems listed in `Gemfile` are
loaded for development purposes only.