athityakumar / athityakumar/colorls

Installation documentation issue for openSUSE: Gem executable has version suffix

Open
#642 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
Ruby
Stars
5.1k
Forks
396
PR merge metrics
No merged PRs in 30d

Description

The current installation instructions do not account for a specific behavior of the Ruby packaging on openSUSE. When installing the `colorls` gem with `--user-install`, the generated executable file is not named `colorls`, but `colorls.rubyX.Y` (e.g., `colorls.ruby4.0`). This causes the command not to be found in the PATH, even when it is correctly set, leading to a confusing installation experience.

**Steps to Reproduce (on openSUSE Tumbleweed):**

1. Install Ruby: `sudo zypper install ruby ruby-devel gcc make`
2. Install colorls locally: `gem install --user-install colorls`
3. Add the gem's user directory to PATH (e.g., `export PATH="$HOME/.local/share/gem/ruby/x.y.z/bin:$PATH"`) and reload the shell.
4. Run colorls --version.
5. Result: The command is not found (`command not found: colorls`).
6. Inspection: Listing the installation directory (`ls -la ~/.local/share/gem/ruby/4.0.0/bin`) reveals the executable is named `colorls.rubyX.Y`, not `colorls`.

**Expected Behavior:**
The `colorls` command should be available in the shell after following the standard installation instructions and configuring the PATH.

**Actual Behavior:**
The installation succeeds, but the executable has a Ruby-version-specific suffix, preventing it from being invoked directly by the `colorls` command.

**Proposed Workaround:**
The issue can be resolved by forcing the gem to install without executable formatting. The following method worked reliably:

```
# Install colorls, directing plain executables to a standard user bin directory
gem install --user-install --bindir ~/.local/bin colorls --no-format-executable

# Ensure the target directory is in your PATH
export PATH="$HOME/.local/bin:$PATH"
# (Add this line to your ~/.bashrc or ~/.zshrc)
```

**Proposed Documentation Addition:**

> **Note for openSUSE Users:**
> openSUSE's Ruby packaging adds a version suffix (like .ruby4.0) to gem executables. If the colorls command is not found after installation, use the --no-format-executable flag and specify a bindir:
>
> ```
> gem install --user-install --bindir ~/.local/bin colorls --no-format-executable
> ```
> Then, add $HOME/.local/bin to your PATH in your shell configuration file.

**Environment:**

- OS: openSUSE Tumbleweed
- Ruby version: 4.0.0 (as per system package)
- Installation method: `gem install --user-install`

Contributor guide

Open the contributing guide

Research direction

Start by locating the current installation instructions and reproduce the openSUSE commands with Ruby's user-install path. Update that guidance with the documented --bindir and --no-format-executable workaround, then verify that the resulting colorls command is available after ~/.local/bin is added to PATH.

Written by the indexing model from the issue text.

Assessment

Tech stack
ruby
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.