clock-rs

A modern, digital clock that effortlessly runs in your terminal.

Table of Contents

• Introduction
• Installation
  • Using Cargo
  • Using a package manager
  • Building from source
• Usage
• Configuration
  • Fields
  • Example
• Contributing
• License

Introduction

clock-rs is a terminal-based clock written in Rust, designed to be a new alternative to tty-clock.
It supports all major platforms and offers several improvements, which include:

• The use of a single configuration file to manage its settings, with the ability to override them through the command line,
• Many additional features such as a timer and a stopwatch,
• And greater flexibility as well as better user experience!

Installation

Using Cargo

To install clock-rs globally using Cargo, simply run the following command:

$ cargo install clock-rs

You can then run the executable via the clock-rs command.

Using a package manager

Arch Linux

A package is available from the AUR (Arch User Repository). To install it, use your preferred AUR manager:

$ yay -S clock-rs-git

or manually clone from the AUR:

$ git clone https://aur.archlinux.org/clock-rs-git.git && cd clock-rs-git && makepkg -si

NetBSD

A package is available from the official repositories. To install it, simply run:

# pkgin install clock-rs

NixOS

clock-rs is available in the Nixpkgs repository. To install it on NixOS, use the following command:

$ nix-env -iA nixos.clock-rs

If you use Nix on a different operating system, use either of the following commands:

$ nix-env -iA nixpkgs.clock-rs # Without flakes 
$ nix profile install nixpkgs#clock-rs # With flakes

[!CAUTION] Using nix-env is generally unrecommended, since it requires you to manually manage installed packages. Consider using $ nix-shell -p clock-rs to make the application temporarily available instead.

You could also add the following to your configuration.nix:

environment.systemPackages = with pkgs; [
    clock-rs
    # ...
];

If you use Home-Manager to configure your dotfiles, you can use the following to set up clock-rs declaratively:

programs.clock-rs = {
  enable = true;

  settings = {
    general = {
      color = "magenta";
      interval = 250;
      blink = true;
      bold = true;
    };

    position = {
      horizontal = "center";
      vertical = "center";
    };

    date = {
      fmt = "%A, %B %d, %Y";
      use_12h = true;
      utc = true;
      hide_seconds = true;
    };
  };
};

Building from source

If you prefer installing clock-rs from source, follow these steps:

1. Download the repository from the releases page or clone it using $ git clone https://github.com/Oughie/clock-rs.

2. Depending on your platform, extract the archive and navigate into its directory.

3. Inside the directory, run $ cargo build --release to build the application manually. This will place the executable inside the clock-rs/target/release directory. However, if you want to install it globally instead, run $ cargo install --path ..

Usage

Usage: clock-rs [OPTIONS] [COMMAND]

Commands:
  clock      Display the current time (default)
  timer      Create a timer (5 minutes if no time is specified)
  stopwatch  Start a stopwatch
  help       Print this message or the help of the given subcommand(s)

Options:
  -c, --color <COLOR>        Specify the clock color
  -x, --x-pos <X_POS>        Set the position along the horizontal axis
  -y, --y-pos <Y_POS>        Set the position along the vertical axis
      --fmt <FMT>            Set the date format
  -t                         Use the 12h format
  -i, --interval <INTERVAL>  Set the polling interval in milliseconds
      --utc                  Use UTC time
  -s, --hide-seconds         Do not show seconds
  -B, --blink                Set the colon to blink
  -b, --bold                 Use bold text
  -h, --help                 Print help
  -V, --version              Print version

Create a timer (5 minutes if no time is specified)

Usage: clock-rs timer [OPTIONS]

Options:
  -S, --seconds <SECONDS>  Add seconds to the timer
  -M, --minutes <MINUTES>  Add minutes to the timer
  -H, --hours <HOURS>      Add hours to the timer
  -k, --kill               Terminate the application when the timer finishes
  -h, --help               Print help

Start a stopwatch

Usage: clock-rs stopwatch

Options:
  -h, --help  Print help

Press P to toggle the pause on the timer or stopwatch, and R to restart.
To exit the application, press Escape, Q, or Ctrl + C.

[!NOTE] If no command is specified, the clock command is used by default.
Therefore, running $ clock-rs clock or simply $ clock-rs will both display the current time.

Configuration

clock-rs uses the TOML file format for its settings. By default, the configuration file is named conf.toml and is stored in the OS configuration directory, within the clock-rs subdirectory.

You can change this path by setting the CONF_PATH environment variable.
If you wish to run the application without automatically using the existing conf.toml file, you can set CONF_PATH to None.

Any argument passed in the command line will override the settings inside the conf.toml file.

Fields

Here's a list of the available fields inside the conf.toml file.

Example

The conf.toml file could look like this:

[general]
color = "magenta"
interval = 250
blink = true
bold = true

[position]
horizontal = "center"
vertical = "center"

[date]
fmt = "%A, %B %d, %Y"
use_12h = true
utc = true
hide_seconds = true

The default configuration can be found here.

Contributing

Feel free to report bugs, suggest features or contribute code.
Any help is appreciated!

License

Copyright © 2024 Oughie

This repository is licensed under the Apache License 2.0 - See here for more information.