R-touch 🦀

The drop-in replacement that has its own date time parser as a library in crates.io, independently logs successes, failures, and time-modifications that we all've been waiting for, because it's well known that touch is the only tool separating us from world peace, and ruining our workflows! oh c'mon now, we all know you wanted a Rust-written improvement for the GNU touch...

Why did I even create R-touch?

I thought about it:

Problem:

“I need to create an empty file.”

Existing solution:

touch file.txt

Jacob Dayan (R-touch founder & developer):

"Interesting. But what if we built a cross-platform Rust implementation with a custom date parser, audit logging, directory handling, customizable & configurable with toml, multiple licensing models, benchmarking, and a reusable library?"

then I started working on R-touch as a main project. Well, it was actually my first project, that's why you can see commits like "Removed Cargo.lock; unnecessary file - it's being created automatically" from the early days.

Jokes aside, R-touch is a fast, modern, and slightly opinionated recreation of the classic Unix touch command, built from scratch in Rust.

Unlike the classic touch that silently fails or acts weirdly when encountering directories, R-touch actually talks to you, manages its own system logs safely, and ensures you don't accidentally trash your system layout.

"Why did the developer use R-touch? Because standard touch was giving them some boundary issues." (Sorry, we promised only semi-decent jokes).

---

Features

• GNU Touch Parity (-a, -m, -d): Selectively update access time (-a), modification time (-m), or both. Set custom timestamps using -d / --date with support for standard dates, GNU touch format, and human-readable relative expressions.
• Flexible Date & Time Interpreter: Supports ISO 8601, RFC 2822/3339, GNU touch syntax ([[CC]YY]MMDDhhmm[.ss]), and human expressions like now, yesterday, tomorrow, 2 days ago, +3 hours, -15 minutes, next tuesday, and today 14:30 — with clear and helpful error diagnostics if an invalid date is provided.
• Smart Directory Handling: If you try to create a file where a directory already exists, R-touch stops and asks you what to do instead of blowing up.
• Parent Directory Creation (-p / --parents): Need to touch deep/nested/folder/file.txt? Use -p or --parents and let R-touch build the directory tree for you.
• Automatic Logging: Logs successes and errors into your system or user state directory (~/.local/state/R-touch on Linux/macOS or %LocalAppData%\R-touch\logs on Windows, or /var/log/R-touch when running as root) so you always have an audit trail. Can be disabled with --no-log.
• Platform-Friendly: Built-in Windows path separator normalization (because backslashes shouldn't be your problem).

---

Quick Start: Check out QUICK-START.md for a rapid 5-minute walkthrough of commands, logging options, and configuration examples.

---

CLI Options & Usage

Usage: rtouch [OPTIONS] <PATHS>...

Arguments:
  <PATHS>...  File paths to touch or create

Options:
  -p, --parents                        Create parent directories if they do not exist
  -r, --replace-directory              Replace an existing directory with an empty file
  -f, --force                          Force deletion of a non-empty directory when replacing it
  -a, --atime, --access-time          Change only the access time
  -m, --mtime, --modification-time    Change only the modification time
  -d, --date <DATE>                    Parse date string expression and use it instead of current time
      --no-log                         Disable logging to log files
      --log                            Force enable logging to log files (overrides config)
      --log-dir <DIR>                  Custom directory to store log files
      --install-completion [SHELL]     Automatically install shell completion script [alias: --completion]
  -h, --help                           Print help
  -V, --version                        Print version

Examples

1. Basic File Touch / Creation

# Create a new file or update timestamps of an existing file
rtouch file.txt

# Touch multiple files at once
rtouch file1.txt file2.txt file3.rs

2. Create Parent Directories (-p, --parents)

# Automatically create missing parent directories
rtouch -p src/components/button/index.tsx

3. Change Only Access Time (-a, --atime, --access-time)

# Updates only atime; preserves mtime on existing files
rtouch -a document.pdf

4. Change Only Modification Time (-m, --mtime, --modification-time)

# Updates only mtime; preserves atime on existing files
rtouch -m document.pdf

5. Custom Timestamps with -d / --date

R-touch supports rich date/time expressions:

• Relative Time Expressions:

  rtouch -d "yesterday" file.txt
  rtouch -d "yesterday 14:30" file.txt
  rtouch -d "2 days ago" file.txt
  rtouch -d "1 week ago 10:00" file.txt
  rtouch -d "tomorrow" file.txt
  rtouch -d "tomorrow 09:00" file.txt
  rtouch -d "+3 hours" file.txt
  rtouch -d "-30 minutes" file.txt
  rtouch -d "next friday 18:00" file.txt
  rtouch -d "last month" file.txt
  rtouch -d "today 14:30" file.txt

• Standard ISO / RFC Formats:

  rtouch -d "2026-08-19 14:30:00" file.txt
  rtouch -d "2026-08-19T14:30:00Z" file.txt
  rtouch -d "2026-08-19" file.txt

• GNU Touch Timestamp Syntax ([[CC]YY]MMDDhhmm[.ss]):

  rtouch -d "202608191430.00" file.txt
  rtouch -d "2608191430" file.txt
  rtouch -d "08191430" file.txt

6. Combining Flags & Compact Syntax

R-touch supports chaining short options together (e.g., combining -a, -m, and -d "..." into -amd "...") as well as passing values directly attached to the flag without a space:

# Combine flags into a single short option group
rtouch -amd "yesterday" report.docx

# Pass date/time directly attached to the flag
rtouch -dyesterday file.txt

# Combine flags with attached date value
rtouch -amdyesterday archive.tar.gz
rtouch -pad"2 days ago" deep/nested/dir/log.txt

# Combine with long options
rtouch -am --no-log -dyesterday file.txt

7. Automatic Shell Completions (--install-completion / --completion)

On first startup, rtouch asks if you want shell completions installed (hit Enter or anything other than n/no to say yes).

You can also install or update completions anytime:

# Auto-detect current shell and install completion file automatically
rtouch --install-completion

# Or specify a target shell (bash, zsh, fish, powershell, pwsh, elvish)
rtouch --completion zsh
rtouch --completion fish
rtouch --completion pwsh

(Completions are automatically placed in standard user completion directories such as ~/.local/share/bash-completion/completions/rtouch, ~/.config/fish/completions/rtouch.fish, or PowerShell/WindowsPowerShell profile directories).

8. Configuration File (config.toml)

rtouch reads configuration from ~/.config/R-touch/config.toml (or %APPDATA%\R-touch\config.toml on Windows). On first run, a default config file is generated automatically:

# ~/.config/R-touch/config.toml

# Whether shell completions should be enabled
completions = true

# Default logging behavior (override per-invocation with --log or --no-log)
should-log = true

# Custom log directory (optional; defaults to ~/.local/state/R-touch on Unix, %LOCALAPPDATA%\R-touch\logs on Windows, or /var/log/R-touch if root)
# Can also be set via R_TOUCH_LOG_DIR (or RTOUCH_LOG_DIR) environment variable or --log-dir CLI flag
# log-dir = "/path/to/custom/logs"

[time-modify]
# Also update access time when updating modification time with -m (default: false)
atime-on-mtime = false

# Also update modification time when updating access time with -a (default: false)
mtime-on-atime = false

---

Installation

Make sure you have Rust and Cargo installed on your machine.

Installing from crates.io (one command)

cargo install rtouch

Building from source

1. Clone this repository:

   git clone https://github.com/Jacob-Dayan/r-touch.git
   cd r-touch

Unix/Linux

If you are on Unix or Unix-like (e.g. Linux, macOS) OS:

chmod +x ./scripts/build/build-unix.sh
./scripts/build/build-unix.sh

Windows

If you are on Windows (user-level installation):

.\scripts\build\build-user.ps1

And for machine-level Windows installation (makes the executable available to all users on the machine, recommended):

.\scripts\build\build-system.ps1

---

Running Tests & Examples

To run the full suite of unit tests, integration tests, and examples:

Unit & Integration Tests

cargo test

End-to-End CLI & Library Examples

• Unix / Linux / macOS / WSL (Bash):

  chmod +x ./scripts/test_all_examples.sh
  ./scripts/test_all_examples.sh

---

Compatibility

• Linux 🐧
• macOS 🍎💻
• Windows 🪟
• Windows Subsystem For Linux (I don't have an emoji for that)

---

License

This project is double licensed under GPL-3.0-or-later and Apache-2.0 OR MIT:

• The R-touch-cli (src/main.rs) program is licensed under the GPL-3.0-or-later
• The R-touch library (src/lib.rs) is licensed under the Apache-2.0 OR MIT; which are both GPL-compatible: you can use it in projects licensed under either license

Note on Release Timestamps & Tags

Notice: Due to a tag migration script refactoring (R-touch-* to v*), GitHub Release publication dates were reset. The underlying code history, original commit dates, and Git tags remain fully preserved in the repository tree.