Poepod is a Ruby gem that streamlines the process of preparing code for analysis by Poe. It offers two main features: concatenating multiple files into a single text file, and wrapping gem contents including unstaged files. These features are particularly useful for developers who want to quickly gather code for review, analysis, or submission to AI-powered coding assistants.

Installation

Add this line to your application’s Gemfile:

gem 'poepod'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install poepod

Usage

After installation, you can use the poepod command line tool:

$ poepod help
Commands:
  poepod concat FILES [OUTPUT_FILE]  # Concatenate specified files into one text file
  poepod help [COMMAND]              # Describe available commands or one specific command
  poepod wrap GEMSPEC_PATH           # Wrap a gem based on its gemspec file

Global options

All options can be used for both wrap and concat commands:

  • --exclude: List of patterns to exclude (default: ["node_modules/", ".git/", ".gitignore$", ".DS_Store$", "^\\..+"])

  • --config: Path to configuration file

  • --include-binary: Include binary files (encoded in MIME format)

  • --include-dot-files: Include dot files

  • --output-file: Output path

  • --base-dir: Base directory for relative file paths in output

  • --include-unstaged: Include unstaged files from lib, spec, and test directories (for wrap command only)

$ poepod concat FILES [OUTPUT_FILE] --exclude PATTERNS --config PATH --include-binary --include-dot-files --output-file PATH --base-dir PATH
$ poepod wrap GEMSPEC_PATH --exclude PATTERNS --config PATH --include-binary --include-dot-files --output-file PATH --base-dir PATH --include-unstaged

Concatenating files

The concat command allows you to combine multiple files into a single text file.

This is particularly useful when you want to review or analyze code from multiple files in one place, or when preparing code submissions for AI-powered coding assistants.

By default, it excludes binary files, dot files, and certain patterns like node_modules/ and .git/.

$ poepod concat path/to/files/* output.txt

This will concatenate all non-binary, non-dot files from the specified path into output.txt.

Including dot files

By default, dot files (hidden files starting with a dot) are excluded.

To include them, use the --include-dot-files option:

$ poepod concat path/to/files/* output.txt --include-dot-files

Including binary files

By default, binary files are excluded to keep the output focused on readable code.

To include binary files (encoded in MIME format), use the --include-binary option:

$ poepod concat path/to/files/* output.txt --include-binary

This can be useful when you need to include binary assets or compiled files in your analysis.

Excluding patterns

You can exclude certain patterns using the --exclude option:

$ poepod concat path/to/files/* output.txt --exclude node_modules .git build test

This is helpful when you want to focus on specific parts of your codebase, excluding irrelevant or large directories.

Wrapping a gem

The wrap command creates a comprehensive snapshot of your gem, including all files specified in the gemspec and README files. This is particularly useful for gem developers who want to review their entire gem contents or prepare it for submission to code review tools.

$ poepod wrap path/to/your_gem.gemspec

This will create a file named your_gem_wrapped.txt containing all the files specified in the gemspec, including README files.

Handling unstaged files

By default, unstaged files in the lib/, spec/, and test/ directories are not included in the wrap, but they will be listed as a warning. This default behavior ensures that the wrapped content matches what’s currently tracked in your version control system.

However, there are cases where including unstaged files can be beneficial:

  1. When you’re actively developing and want to include recent changes that haven’t been committed yet.

  2. When you’re seeking feedback on work-in-progress code.

  3. When you want to ensure you’re not missing any important files in your commit.

To include these unstaged files in the wrap:

$ poepod wrap path/to/your_gem.gemspec --include-unstaged

This option allows you to capture a true snapshot of your gem’s current state, including any work in progress.

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to https://rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/riboseinc/poepod. Please adhere to the code of conduct.