Repository files navigation

our mascot, "Rucus"

rucat iscat reborn for the era of LLMs. A critical tool for every promptengineer.

Written in Rust. It goes beyond simple file concatenation, offering multipleoutput formats, line numbering, syntax-aware formatting, and clipboard support,making it an ideal tool for developers, system administrators, and anyone workingwith code or text files in the terminal.

In modern development, AI assistants are invaluable for complex tasks likedebugging, refactoring, or repository analysis. However, their effectivenesshinges on the quality and completeness of the context you provide. Manuallycopying and pasting from numerous files is slow and error-prone.

rucat excels at rapidly consolidating context from multiple files into asingle, well-structured block of text, perfect for an AI prompt.

If you're troubleshooting a complexgit history issue and need to provide anAI with the full state of your repository's refs and logs, you can run:

# Quickly gather all relevant git state files into one block$ rucat .git/{HEAD,config,info/exclude,logs/HEAD,logs/refs/heads/*}# Or copy directly to clipboard for pasting into AI chat$ rucat --copy .git/{HEAD,config,info/exclude,logs/HEAD,logs/refs/heads/*}

```---File: .git/HEAD---```ref: refs/heads/main```---File: .git/config---```[core]    repositoryformatversion = 0    filemode = true    bare = false    logallrefupdates = true    ignorecase = true    precomposeunicode = true[remote "origin"]    url = https://github.com/poundifdef/SmoothMQ    fetch = +refs/heads/*:refs/remotes/origin/*[branch "main"]    remote = origin    merge = refs/heads/main```---File: .git/info/exclude---```# git ls-files --others --exclude-from=.git/info/exclude# Lines that start with '#' are comments.# For a project mostly in C, the following would be a good set of# exclude patterns (uncomment them if you want to use them):# *.[oa]# *~```---File: .git/logs/HEAD---```0000000000000000000000000000000000000000 2770c4b21a3755e95652c24b71ac7cad87b532dc Brian 'redbeard' Harrington <redbeard@dead-city.org> 1718820643 -0700clone: from https://github.com/poundifdef/SmoothMQ```---File: .git/logs/refs/heads/main---```0000000000000000000000000000000000000000 2770c4b21a3755e95652c24b71ac7cad87b532dc Brian 'redbeard' Harrington <redbeard@dead-city.org> 1718820643 -0700clone: from https://github.com/poundifdef/SmoothMQ```

This command instantly generates a clean, markdown-formatted output, with eachfile's content neatly separated and labeled:

The resulting text can be piped to your clipboard and pasted directly into yourAI chat, delivering complete and unambiguous context in seconds. This makesrucat an essential tool for accelerating AI-driven development.

• Multiple Output Formats: Display content in various styles, including:
  • ansi: Nicely formatted with borders (width-configurable via--ansi-width).
  • utf8: Fancy UTF-8 box-drawing borders (width-configurable via--utf8-width).
  • markdown: GitHub-flavored Markdown code blocks, with automatic languagedetection from the file extension.
  • ascii: Simple=== file.txt === headers for easy separation.
  • xml: Structured XML output with file and line metadata.
  • json: A clean JSON array of file entries, perfect for scripting andprogrammatic use.
  • pretty: Syntax highlighting for a wide range of languages. Syntax ischosen based on: 1) the--pretty-syntax flag, 2) a Vim modeline in thefile (e.g.,vim: ft=rust), or 3) the file extension.
• Line Numbering: Prepend line numbers to every line with the-n or--numbers flag.
• Clipboard Support: Copy output directly to the system clipboard with the-c or--copy flag. Supports multiple clipboard providers:
  • Native clipboard on Windows, macOS, and Linux (X11/Wayland)
  • Terminal escape sequences (OSC 52 for tmux/SSH, OSC 5522 for Kitty)
  • Automatic provider detection based on your environment
• Flexible Input:
  • Process multiple files and directories.
  • Read fromstdin, allowing it to be used in shell pipelines.
  • Handle NUL-terminated file lists from commands likefind ... -print0 usingthe-0 or--null flag.
• Path Manipulation: Use--strip N to remove leading path components fromfile headers, cleaning up output for nested projects.
• Packaging:
  • Built-in support for generating.deb packages for Debian/Ubuntu systemsviacargo deb.
• Robust and Fast: Built with Rust for performance and memory safety.

If you are on macOS and have Homebrew installed, you can installrucat with a single command:

brew install brianredbeard/rucat/rucat

If you have the Rust toolchain installed, you can build and installrucatdirectly from source. From the root of the project repository:

cargo install --path.

To build without clipboard support (reduces dependencies):

cargo install --path. --no-default-features

This project is configured to build.deb packages using standard Cargotooling. First, ensure you have the necessary packaging subcommand installed:

cargo install cargo-deb

Then, you can build the package from the project root:

# Build .deb package (output in target/debian/)cargo deb

The binary will be placed in~/.cargo/bin.

When cross-compiling from macOS to Linux,rustc needs a C-language toolchainthat can link executables for the Linux target. The native macOS toolchaincannot do this. You can install the necessary toolchains using Homebrew, but itrequires adding a new formula tap first.

This is a one-time setup for your development machine. No changes are neededfor the project's code.

1. Install Cross-Compilation Toolchains with Homebrew

   First, tap the repository that contains the toolchains. Then, install them.

   brew tap messense/macos-cross-toolchainsbrew install aarch64-unknown-linux-gnubrew install x86_64-unknown-linux-gnu

2. Configure Cargo to Use the New Linkers

   You must tell Cargo to use these newly installed linkers for the respectivetargets. Create or edit the file~/.cargo/config.toml (this is Cargo'sglobal configuration file in your home directory, not your project directory)and add the following content:

   [target.aarch64-unknown-linux-gnu]linker ="aarch64-unknown-linux-gnu-gcc"[target.x86_64-unknown-linux-gnu]linker ="x86_64-unknown-linux-gnu-gcc"

After completing these two steps, your system will be properly configured forcross-compilation, andmake cross-build-all should succeed.

rucat offers a rich set of command-line flags to customize its behavior. Flags can be placed before or after file arguments.

• FILES...
  • Description: One or more files or directories to process. If a directory is provided,rucat will recursively process all files within it. If no files are provided,rucat reads from standard input.
  • Example:rucat README.md src/

These flags control the appearance of the output.

• -f, --format <FORMAT>

  • Description: Sets the output format.
  • Values:
    • ansi: Formats output with ANSI box-drawing characters.
    • utf8: Formats output with fancy UTF-8 box-drawing characters.
    • markdown: (Default) Wraps each file's content in a GitHub-flavored Markdown code block.
    • ascii: Separates files with a simple=== file.txt === header.
    • xml: Produces structured XML output.
    • json: Produces a JSON array of file entries, ideal for scripting.
    • pretty: Applies syntax highlighting based on file type.
  • Example:rucat -f pretty src/main.rs

• -n, --numbers

  • Description: Adds a gutter with line numbers to the output.
  • Example:rucat -n Cargo.toml

• --ansi-width <WIDTH>

  • Description: Sets the minimum interior width for theansi formatter.
  • Default:80
  • Example:rucat -f ansi --ansi-width 120 src/lib.rs

• --utf8-width <WIDTH>

  • Description: Sets the minimum interior width for theutf8 formatter.
  • Default:80
  • Example:rucat -f utf8 --utf8-width 100 src/lib.rs

• --pretty-syntax <SYNTAX>

  • Description: Overrides syntax detection for thepretty formatter, forcing a specific language.
  • Example:echo "echo 'Hello'" | rucat -f pretty --pretty-syntax sh

These flags are used to display file metadata. They are most effective with formats likeascii,ansi, orutf8 that display headers.

• --stat

  • Description: Includes detailed file metadata (size, permissions, timestamps, etc.) in the output header for each file.
  • Example:rucat --stat /etc/hosts

• --show-binary-xattrs

  • Description: By default, binary extended attributes are hidden when using--stat. This flag forces them to be displayed.
  • Example:rucat --stat --show-binary-xattrs some_file_with_binary_xattrs

• --binary-format <FORMAT>

  • Description: Sets the display format for binary extended attributes when--show-binary-xattrs is used.
  • Values:
    • hexdump: (Default) Anxxd-style hexadecimal and ASCII view.
    • base64: Standard Base64 encoding.
    • intel-hex: The Intel HEX object file format.
    • raw-hex: A continuous string of hexadecimal characters with no spaces or headers.
  • Example:rucat --stat --show-binary-xattrs --binary-format base64 ...

• --hex-width <BYTES>

  • Description: Sets the number of bytes per line for thehexdump binary format.
  • Default:16
  • Example:rucat --stat --show-binary-xattrs --hex-width 32 ...

• --base64-width <CHARS>

  • Description: Sets the maximum number of characters per line for thebase64 binary format.
  • Default:76
  • Example:rucat --stat --show-binary-xattrs --binary-format base64 --base64-width 100 ...

These flags control howrucat reads input and handles output.

• -c, --copy

  • Description: Copies the entire output to the system clipboard while still printing it to standard output. Requires theclipboard feature.
  • Example:rucat -c src/main.rs

• -0, --null

  • Description: Reads a NUL-separated list of file paths from standard input. This is useful for safely handling filenames that contain whitespace or special characters, especially when used withfind -print0.
  • Example:find . -name "*.rs" -print0 | rcat -0

• --strip <N>

  • Description: RemovesN leading path components from filenames in the output headers.
  • Example:rucat --strip 2 src/formatters/ansi.rs will display the header foransi.rs.

rucat can be configured with a TOML file to set your preferred defaultoptions. Create a file at~/.config/rucat/config.toml (or the equivalent XDGconfig path on your OS).

Command-line arguments will always override settings from this file.

Exampleconfig.toml:

# Default output format.# Possible values: "ansi", "utf8", "markdown", "ascii", "xml", "json",# "pretty"format ="ansi"# Default to showing line numbers.numbers =true# Default number of path components to strip from filenames.strip =1# Default width for the "ansi" and "utf8" formatters.ansi_width =120utf8_width =120# Default syntax for the "pretty" formatter.pretty_syntax ="rust"

Contributions are welcome! If you have a feature request, bug report, or pullrequest, please feel free to open an issue or submit a PR.

This tool was proudly co-written usingAider

This project is licensed under the GNU General Public License v3.0.