Development files included in gem distribution due to git ls-files usage

[ogajduse]

Development files included in gem distribution due to git ls-files usage

Problem

The current gemspec uses git ls-files to determine which files to include in the gem:

s.files = `git ls-files`.split("\n")

This approach has two major problems:

1. Includes unnecessary development files

All git-tracked files are included in the gem, even those that serve no purpose in production:

• .github/workflows/ci.yml (GitHub Actions CI configuration)
• .rubocop.yml (RuboCop linting configuration)
• .editorconfig (Editor configuration)
• .rspec (RSpec test configuration)
• .autotest (Autotest configuration)
• .gitignore (Git configuration)
• CODEOWNERS (GitHub repository feature)
• Guardfile (Guard file watching configuration)

These files bloat the gem package and can cause issues for downstream packagers (e.g., RPM, DEB packages).

2. Git dependency breaks builds in many environments

Using git ls-files in gemspecs is considered bad practice in the Ruby community because it breaks in environments without git:

• Package builds: Debian/RPM packages are built in clean environments without git → build fails (source)
• Docker containers: Minimal production images without git → "No such file or directory - git" errors
• Git archives: GitHub release tarballs created with git archive don't contain .git/ directory → git ls-files fails (source)

Real-world Impact

This issue was discovered while packaging clamp 1.4.0 as an RPM for the Foreman project. The migration from Travis CI to GitHub Actions caused RPM builds to fail:

1. Spec file referenced .travis.yml (removed upstream) → "file not found" error
2. Spec file didn't exclude .github/workflows/ci.yml (newly added) → "unpackaged files" error

Downstream packagers must maintain explicit exclusion lists that break whenever upstream adds new development files.

Proposed Solution

Replace git ls-files with pure Ruby Dir globs, as recommended by:

• Ruby Packaging Style Guide
• RuboCop Packaging cops
• Bundler issue #2287: "git ls-files in gemspec template is bad practice"
• ruby-progressbar issue #54: "Don't rely on git ls-files in gemspec file"

Change:

# Before (problematic)
s.files = `git ls-files`.split("\n")

# After (recommended)
s.files = Dir["lib/**/*", "examples/**/*", "spec/**/*", "*.md", "LICENSE", "Rakefile", "Gemfile", "#{s.name}.gemspec"]

Benefits

✅ No git dependency - Works in Docker, package builds, CI environments
✅ Explicit file list - Clear what's included, maintainable
✅ Cleaner gems - Only production-relevant files
✅ Simpler downstream packaging - No need for manual exclusion lists
✅ No breaking changes - All necessary files still included

Additional Context

Note on .gitattributes approach: While .gitattributes with export-ignore works for git archive, it does NOT work with git ls-files (source). Since gemspecs execute git ls-files directly, .gitattributes won't solve this problem.

Ruby community consensus: The Ruby packaging community recommends avoiding any git commands in gemspecs in favor of pure Ruby alternatives (Bundler #2287, RubyGems #4047).

References

• Using git ls-files in gemspec template is bad practice
• Don't rely on git ls-files in gemspec file
• Pure ruby replacement for git ls-files
• The Packaging Style Guide
• RuboCop Packaging cops documentation
• Avoid using git to declare files in gemspec
• Excluding files from git archive (why .gitattributes doesn't help here)
• Foreman packaging issue that discovered this

[AlexWayfer]

I agree that it's better to not include development (and test) files in the final gem.

But I can highlight disadvantages of Dir[] vs git ls: when your working directory has .backup files, non-staged files, etc. They will be included in the final gem.

Probably we should mix and combine these approaches. Something like git ls + excluding.

[ogajduse]

@AlexWayfer Thanks for the feedback! The .backup file concern is valid for local builds, but doesn't apply to modern release workflows:

Modern gem releases use CI/CD from clean checkouts:
Example: foreman_remote_execution release workflow uses voxpupuli/ruby-release@v0
Workflow runs in fresh GitHub Actions environment with only git-tracked files, no .backup files, no untracked junk.

I've looked up a few projects from the Foreman ecosystem, and I found that all of them use the Dir[] approach, combined with releases through CI/CD.

Foreman plugin gemspec examples:

1. foreman_remote_execution
2. foreman_ansible
3. katello
4. foreman_puppet
5. foreman_openscap
6. foreman_templates

I'd like to highlight the fact that the Ruby community recommends against git ls-files, see the links in the issue description.

Use Dir[] (follows community guidelines) + CI/CD releases (already best practice). If someone releases locally with a messy checkout, that's user error, not a design problem.

Thoughts?

I recognize clamp doesn't currently have CI/CD set up for releases. I'm happy to help set up a GitHub Actions workflow similar to the Foreman projects, though this would require maintainer engagement to configure RubyGems publishing credentials.