Preview and package source code, documentation, logs, and configuration files — locally, with a desktop app or a scriptable CLI.
Opening 40 files just to share the useful parts of a project shouldn't take 40 copy-and-paste operations.
File Extractor Pro walks a directory tree, selects the text files you care about, and combines them into one clearly labeled document. Inspect the selection first with a read-only preview, work interactively in Tkinter, or run the same extraction engine in a CLI for repeatable tasks.
No account, API key, cloud upload, or third-party runtime package is required.
Requirements: Python 3.9+; Tkinter is additionally required for the desktop interface.
Install from source (no PyPI release is required):
git clone https://github.com/cortega26/File-Extractor-Pro.git
cd File-Extractor-Pro
python -m pip install .Installation provides two commands you can run from any directory:
file-extractor-pro for the CLI and file-extractor-pro-gui for the desktop app.
The CLI has no Tkinter requirement.
1. Preview a folder without writing an output file:
file-extractor-pro /path/to/my-project \
--extensions py md json yaml \
--exclude-folders node_modules .venv build dist \
--dry-run2. Extract those files and generate a JSON report: remove --dry-run and give the output an explicit destination.
file-extractor-pro /path/to/my-project \
--extensions py md json yaml \
--exclude-folders node_modules .venv build dist \
--output ./project-context.txt \
--report ./extraction-report.jsonPrefer a desktop window?
file-extractor-pro-guiChoose a folder, tune inclusion/exclusion rules, and select Extract. The interface shows progress, supports cancellation, and can generate a report.
Without installing? Run
python -m services.cli /path/to/project --dry-runorpython file_extractor.pydirectly from the cloned repository. Replace/path/to/my-projectwith your own folder. Example output paths are illustrative.pip install .installs this checkout locally; it does not imply that a package has been published to PyPI.
Suppose your source tree looks like this:
my-project/
├── README.md
├── src/
│ ├── app.py
│ └── settings.py
├── node_modules/
└── .venv/
Preview the selection:
file-extractor-pro /path/to/my-project \
--extensions md py \
--exclude-folders node_modules .venv \
--dry-runThe output is a readable inventory of selected file paths and source byte sizes:
File Extractor Pro — read-only preview
Source: /absolute/path/to/my-project
Output: extraction.txt
Selected: 3 files, ... source bytes
README.md (... bytes)
src/app.py (... bytes)
src/settings.py (... bytes)
Illustrative display; paths and sizes depend on your files.
Run the same command without --dry-run and with --output project-context.txt to generate a combined UTF-8 text file:
my-project/README.md:
# My project
...
my-project/src/app.py:
def main():
...
my-project/src/settings.py:
...
Each section keeps its source path so readers can identify where its content came from. Source files are read during traversal; choose a separate output path to avoid replacing a source file.
| Capability | Why it matters |
|---|---|
| Preview before extraction | See selected paths, source sizes, totals, and an existing-output warning without writing the extraction or report files. |
| Fine-grained selection | Include or exclude extensions, files, folders, and hidden entries. |
| Readable combined output | Concatenate UTF-8 text with clear source-path separators. |
| Optional JSON report | Inspect per-file sizes, extensions, processing timestamps, and SHA-256 hashes of processed text. |
| Safe completion behavior | Output is staged in a temporary sibling file and atomically replaced after successful extraction. |
| Predictable ordering | Deterministic directory/file traversal; eligible top-level README/specification files come first. |
| Works at a desk or in automation | Tkinter GUI and headless CLI share the extraction service. |
| Built for large folder trees | Chunked reading, soft size warnings, cooperative cancellation, and progress/throughput metrics. |
- Code reviews and AI-assisted development: hand a reviewer a controlled text snapshot rather than an entire directory.
- Documentation handoffs: consolidate Markdown, text notes, and configuration samples.
- Incident investigation: gather relevant text logs or config files from nested folders.
- Reproducible automation: use the CLI and JSON report in scripts or scheduled workflows.
It packages context; it does not interpret, summarize, or analyze it with AI.
Launch with file-extractor-pro-gui. The GUI includes:
- Folder picker and recently used folders
- Inclusion/exclusion modes and custom extensions
- Hidden-file controls and filename/folder patterns
- Light/dark themes and a resizable layout
- Background extraction, live progress, cancellation, and JSON reports
Keyboard shortcuts
| Shortcut | Action |
|---|---|
Alt+E or F5 |
Start extraction |
Alt+C or Esc |
Cancel |
Alt+G |
Generate report |
The read-only preview is currently a CLI feature, not a GUI button.
The installed executable runs from any directory. Run file-extractor-pro --help for the current CLI help.
CLI options
| Argument | Default | Purpose |
|---|---|---|
folder |
Required | Root directory |
--mode inclusion|exclusion |
inclusion |
Include or exclude listed extensions |
--extensions py md |
Common extension set | Extensions to include or exclude; comma-separated values also work |
--exclude-files PATTERN ... |
None | Skip matching filenames |
--exclude-folders PATTERN ... |
None | Skip matching folder names |
--include-hidden |
Off | Consider hidden files and directories |
--dry-run |
Off | Preview selection without writing output/report |
--preview-format text|json |
text |
Preview formatting (--dry-run only) |
--output PATH |
extraction.txt |
Combined text output |
--report PATH |
None | Optional JSON report after extraction |
--max-file-size-mb N |
Automatic | Soft warning threshold; not a hard rejection limit |
--poll-interval SECONDS |
0.1 |
Status polling interval |
--log-level LEVEL |
INFO |
Logging verbosity |
Get a JSON preview for another tool to consume
file-extractor-pro /path/to/my-project \
--extensions py md json \
--dry-run --preview-format json > selection.jsonThis writes selection.json through your shell's redirection, not through the extractor. The extractor does not create its configured output/report in dry-run mode.
Package only Python and Markdown
file-extractor-pro /path/to/my-project \
--extensions py md \
--output ./code-review.txtUse explicit directory and file exclusions
file-extractor-pro /path/to/my-project \
--extensions py md yaml \
--exclude-folders node_modules .venv dist build \
--exclude-files "*.generated.py" "*.min.js" \
--output ./filtered-context.txtCollect text while excluding certain extension types
file-extractor-pro /path/to/my-project \
--mode exclusion --extensions log db \
--exclude-folders node_modules .venv \
--output ./filtered-files.txtInspect every candidate filename, including hidden ones
file-extractor-pro /path/to/my-project \
--extensions "*" --include-hidden \
--exclude-folders .git node_modules .venv \
--dry-runThis last command is intentionally broad. It may select secrets or binary files; inspect the result carefully before extraction.
A clear understanding of the current boundaries is part of a trustworthy extraction workflow.
| Behavior | Important detail |
|---|---|
| Text only | The extractor reads UTF-8 text. Undecodable or binary files are skipped with diagnostics; it does not parse PDFs, DOCX, images, archives, or OCR. |
| Preview ≠ content validation | Dry-run checks selection and file sizes, not encoding, readability, security, or LLM token count. |
No automatic .gitignore parsing |
Supply explicit --exclude-files and --exclude-folders patterns. CLI exclusion lists are empty by default; GUI configuration has its own defaults. |
| No secret scanning | Be careful with credentials, personal information, and hidden config files; review before sharing output. |
| Symlinks | Symlinked files are skipped to avoid unintentionally reading content outside the selected tree. |
| Output replacement | Failed or cancelled runs preserve an existing destination. Successful runs replace it, rather than creating a backup. |
| Source files | Extraction reads selected sources; the configured output path is a write target. Do not point it at a file you want to preserve. |
Patterns currently match file/folder names, not full Git-style path rules. For a large repository, use explicit exclusions for dependency directories, generated artifacts, and other irrelevant content.
Request a report using --report extraction-report.json. The structure resembles:
{
"timestamp": "2026-10-12T10:30:00",
"total_files": 1,
"total_size": 19,
"extension_summary": {
".py": { "count": 1, "total_size": 19 }
},
"file_details": {
"my-project/src/app.py": {
"size": 19,
"hash": "<sha256>",
"extension": ".py",
"processed_time": "<timestamp>"
}
}
}Illustrative values. The report records processed files and SHA-256 hashes of the text streamed into the output (not necessarily raw on-disk byte hashes if newline decoding changes the bytes). This is useful for auditability, but is not a cryptographic attestation of a complete repository.
Runtime dependencies are limited to the Python standard library (with Tkinter available for the GUI). The project is packaged with setuptools for local installation, not automatically published to PyPI. To work on the code:
python -m pip install -e .
python -m pip install -r requirements-dev.txt
python -m pytest -q
python tools/coverage_gate.pyDevelopment tooling requires Python 3.11+. The test suite and development tooling need Python 3.11 or newer —
tests/test_dependencies.pyimportstomllibandmypy.inisetspython_version = 3.11— while the application itself continues to run on Python 3.9+.
GitHub Actions runs the pytest suite on pull requests and main, with an 80% overall coverage requirement. Separate development scripts under tools/ provide additional coverage, security, and type-check checks; these are not all part of the current CI workflow.
Repository map
file_extractor.py Desktop entry point
ui.py Tkinter interface
processor.py Discovery, filtering, streaming, metrics
config_manager.py Validated desktop preferences
services/
cli.py Headless commands
preview.py Read-only selection planning
extractor_service.py Background lifecycle and reports
ui_support/ Theme, layout, keyboard, status helpers
tests/ Automated regression tests
tools/ Local validation utilities
.github/workflows/ CI test workflow
Found an issue, a file-selection edge case, or an opportunity to make the workflow simpler? Open an issue. Small, test-backed changes are especially welcome.
Distributed under the MIT License.
Turn scattered files into a useful, inspectable handoff.
Part of Tooltician.