gitcal 0.1.2

A CLI tool for calendar visualization
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74

# gitcal

A CLI tool for calendar visualization

# Installation

```shell
cargo install gitcal --locked
```

# Usage

```shell
Usage: gitcal [OPTIONS]

Options:
      --username <NAME>       GitHub username (defaults to token owner)
      --block                 Use block icons
      --half                  Use block icons without spaces
      --circle                Use circle icons
      --base <HEX>            Set base color
      --text <HEX>            Set text color
      --color0 <HEX>          Set color for no contributions
      --color1 <HEX>          Set color for first quartile
      --color2 <HEX>          Set color for second quartile
      --color3 <HEX>          Set color for third quartile
      --color4 <HEX>          Set color for fourth quartile
      --timespan <TIME_SPAN>  Display data since given time span to current date
      --token <GITHUB_TOKEN>  GitHub PAT token (uses $GITHUB_TOKEN if not specified)
      --hide-days             Hide day-of-the-week string
      --hide-months           Hide months in header
  -h, --help                  Print help
```

## GitHub Token

To use this, you need an API token for GitHub. This can be created by going to GitHub, then `Settings > Developer Settings > Personal access tokens`. Current advice from GitHub recommends making a [`fine-grained token`](https://github.com/settings/tokens?type=beta). This token should be passed to `gitcal` via `--token` argument, or you can set the `$GITHUB_TOKEN` environment variable.


# Options

## Display Modes
There are several unicode characters which can be used to display the calendar information. See the images below for examples of each:

`(default)`
![](img/default.png)

`--block`
![](img/block.png)

`--circle`
![](img/circle.png)

`--half`
![](img/half.png)

## Colors
Custom colors can be used by passing them as hex strings to the respective CLI arguments. For example, `gitcal --base "#FFFFFF"` will make the background color white.

```
gitcal --base "#eff1f5" --text "#4c4f69" --color0 "#7287fd" --color1 "#179299" --color2 "#df8e1d" --color3 "#e64553" --color4 "#8839ef"
```
![](img/custom_colors.png)

## Hiding Headers
The `--hide-days` and `--hide-months` arguments can be used to hide the respective day column and month row.

## Time

By default, `gitcal` will display past 365 days of information. However, the `--timespan` argument can be used to input a human-readable timespan (as measured relative to the current date). See [`jiff`'s documentation](https://docs.rs/jiff/latest/jiff/fmt/friendly/index.html) for some examples of valid inputs. For example `--timespan '3 months'` will give you the past three months of data. I plan to eventually add start and end date arguments, if anyone wants to do it with a PR, feel free.

# See Also

Check out [ghfetch](https://github.com/SafarSoFar/ghfetch) for a similar command which also prints GitHub info in a `fetch`-style output!