athityakumar / athityakumar/colorls
Installation documentation issue for openSUSE: Gem executable has version suffix
- 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
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