Skip to content

Replace git ls-files with Dir globs in gemspec#126

Open
ogajduse wants to merge 1 commit intomdub:masterfrom
ogajduse:proper-gemspec-files-using-dir
Open

Replace git ls-files with Dir globs in gemspec#126
ogajduse wants to merge 1 commit intomdub:masterfrom
ogajduse:proper-gemspec-files-using-dir

Conversation

@ogajduse
Copy link

Summary

This PR replaces git ls-files with explicit Dir globs in the gemspec, following Ruby packaging best practices.

Fixes #125

Changes

Modified clamp.gemspec line 23:

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

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

Why This Change?

Using git ls-files in gemspecs is considered bad practice by the Ruby community:

Problem 1: Git dependency breaks builds

  • Package builds: Fails in Debian/RPM clean environments without git
  • Docker: Breaks in minimal production images
  • Git archives: Fails with GitHub release tarballs (no .git/ directory)

Problem 2: Includes unnecessary files

Current gem includes development files that bloat the package:

  • .github/workflows/ci.yml
  • .rubocop.yml, .rspec, .autotest, .editorconfig
  • CODEOWNERS, Guardfile

Benefits

No git dependency - Works in all build environments
Explicit file list - Clear, maintainable, intentional
Cleaner gems - Production-ready files only
Simpler downstream packaging - No manual exclusion lists needed
No breaking changes - All necessary files still included

Verification

Tested locally by building and unpacking the gem:

gem build clamp.gemspec
gem unpack clamp-1.4.0.gem
ls -la clamp-1.4.0/  # ✓ No .github/, no dotfiles

Files included (clean):

  • lib/ (source code)
  • examples/ (examples)
  • spec/ (tests)
  • CHANGES.md, README.md (documentation)
  • LICENSE, Rakefile, Gemfile, clamp.gemspec

Files excluded (as intended):

  • .github/, .rubocop.yml, .rspec, .autotest, etc.
  • CODEOWNERS, Guardfile

Community Recommendations

This approach is recommended by:

Real-world Impact

This issue was discovered during RPM packaging for the Foreman project, where the Travis CI → GitHub Actions migration broke builds because the spec file couldn't keep up with upstream changes.

This change eliminates that maintenance burden for all downstream packagers.

Replace 'git ls-files' with explicit Dir globs to follow Ruby
packaging best practices and avoid git dependency.

Problems with git ls-files:
- Includes all development files (.github/, .rubocop.yml, etc.)
- Requires git to be installed (breaks in Docker, package builds)
- Fails with git archive tarballs (no .git/ directory)

Benefits of Dir approach:
- No git dependency - works everywhere
- Explicit file list - clear and maintainable
- Excludes development files automatically
- Recommended by Ruby Packaging Style Guide

Files now included (production-ready):
- lib/**/* (source code)
- examples/**/* (examples)
- spec/**/* (tests for development)
- *.md (documentation)
- LICENSE, Rakefile, Gemfile, gemspec

Files automatically excluded:
- .github/, .rubocop.yml, .rspec, .autotest, etc.
- CODEOWNERS, Guardfile
- Any other dotfiles or dev configs

References:
- rubygems/bundler#2287
- jfelchner/ruby-progressbar#54
- https://packaging.rubystyle.guide/
- https://docs.rubocop.org/rubocop-packaging/cops_packaging.html
@ogajduse ogajduse requested a review from mdub as a code owner February 18, 2026 09:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

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

1 participant

Comments