
Security News
Meet Socket at Black Hat and DEF CON 2025 in Las Vegas
Meet Socket at Black Hat & DEF CON 2025 for 1:1s, insider security talks at Allegiant Stadium, and a private dinner with top minds in software supply chain security.
Convert a directory structure and its contents into a single text file, including the tree output and file contents in structured XML format. It may be useful to chat with LLM about your code.
repo-to-text
converts a directory's structure and contents into a single text file. Run it from the terminal to generate a formatted text representation that includes the directory tree and file contents. This makes it easy to share code with LLMs for development and debugging.
pip install repo-to-text
ā install the packagecd <your-repo-dir>
ā navigate to the repository directoryrepo-to-text
ā run the command, result will be saved in the current directoryThe generated text file will include the directory structure and contents of each file, using XML tags for better structure:
<repo-to-text>
Directory: myproject
Directory Structure:
<directory_structure>
.
āāā .gitignore
āāā README.md
āāā src
āāā main.py
</directory_structure>
<content full_path="README.md">
# My Project
This is a simple project.
</content>
<content full_path="src/main.py">
def main():
print("Hello, World!")
if __name__ == "__main__":
main()
</content>
</repo-to-text>
For a full example, see the [example output for this repository](https://github.com/kirill-markin/repo-to-text/blob/main/examples/example_repo-to-text_2024-06-09-08-06-31-UTC.txt).
## Installation
### Using pip
To install `repo-to-text` via pip, run the following command:
```bash
pip install repo-to-text
To upgrade to the latest version, use the following command:
pip install --upgrade repo-to-text
After installation, you can use the repo-to-text
command in your terminal. Navigate to the directory you want to convert and run:
repo-to-text
or
flatten
This will create a file named repo-to-text_YYYY-MM-DD-HH-MM-SS-UTC.txt
in the current directory with the text representation of the repository. The contents of this file will also be copied to your clipboard for easy sharing.
You can customize the behavior of repo-to-text
with the following options:
--output-dir <path>
: Specify an output directory where the generated text file will be saved. For example:
repo-to-text --output-dir /path/to/output
This will save the file in the specified output directory instead of the current directory.
--create-settings
or --init
: Create a default .repo-to-text-settings.yaml
file with predefined settings. This is useful if you want to start with a template settings file and customize it according to your needs. To create the default settings file, run the following command in your terminal:
repo-to-text --create-settings
or
repo-to-text --init
This will create a file named .repo-to-text-settings.yaml
in the current directory. If the file already exists, an error will be raised to prevent overwriting.
--debug
: Enable DEBUG logging. By default, repo-to-text
runs with INFO logging level. To enable DEBUG logging, use the --debug
flag:
repo-to-text --debug
or to save the debug log to a file:
repo-to-text --debug > debug_log.txt 2>&1
input_dir
: Specify the directory to process. If not provided, the current directory (.
) will be used. For example:
repo-to-text /path/to/input_dir
--stdout
: Output the generated text to stdout instead of a file. This is useful for piping the output to another command or saving it to a file using shell redirection. For example:
repo-to-text --stdout > myfile.txt
This will write the output directly to myfile.txt
instead of creating a timestamped file.
Build the container:
docker compose build
Start a shell session:
docker compose run --rm repo-to-text
Once in the shell, you can run repo-to-text
:
Process current directory:
repo-to-text
Process specific directory:
repo-to-text /home/user/myproject
Use with options:
repo-to-text --output-dir /home/user/output
The container mounts your home directory at /home/user
, allowing access to all your projects.
repo-to-text
also supports configuration via a .repo-to-text-settings.yaml
file. By default, the tool works without this file, but you can use it to customize what gets included in the final text file.
To create a settings file, add a file named .repo-to-text-settings.yaml
at the root of your project with the following content:
# Syntax: gitignore rules
# Ignore files and directories for all sections from gitignore file
# Default: True
gitignore-import-and-ignore: True
# Ignore files and directories for tree
# and contents sections (<content full_path="...">...</content>)
ignore-tree-and-content:
- ".repo-to-text-settings.yaml"
- "examples/"
- "MANIFEST.in"
- "setup.py"
# Ignore files and directories for contents sections
ignore-content:
- "README.md"
- "LICENSE"
- "tests/"
You can copy this file from the existing example in the project and adjust it to your needs. This file allows you to specify rules for what should be ignored when creating the text representation of the repository.
.gitignore
for all sections.Using these settings, you can control which files and directories are included or excluded from the final text file.
output_filename_part_N.txt
, where N
is the part number.
Example:
# Optional: Maximum word count per output file.
# If set, the output will be split into multiple files if the total word count exceeds this.
# maximum_word_count_per_file: 10000
Using Wildcard Patterns
*.ext
: Matches any file ending with .ext in any directory.dir/*.ext
: Matches files ending with .ext in the specified directory dir/.**/*.ext
: Matches files ending with .ext in any subdirectory (recursive).If you want to include certain files that would otherwise be ignored, use the ! pattern:
ignore-tree-and-content:
- "*.txt"
- "!README.txt"
To ignore the generated text files, add the following lines to your .gitignore
file:
repo-to-text_*.txt
To install repo-to-text
locally for development, follow these steps:
Clone the repository:
git clone https://github.com/kirill-markin/repo-to-text
cd repo-to-text
Install the package with development dependencies:
pip install -e ".[dev]"
For development, additional packages are required:
To run the tests, use the following command:
pytest
To uninstall the package, run the following command from the directory where the repository is located:
pip uninstall repo-to-text
Contributions are welcome! If you have any suggestions or find a bug, please open an issue or submit a pull request.
This project is licensed under the MIT License - see the LICENSE file for details.
This project is maintained by Kirill Markin. For any inquiries or feedback, please contact markinkirill@gmail.com.
FAQs
Convert a directory structure and its contents into a single text file, including the tree output and file contents in structured XML format. It may be useful to chat with LLM about your code.
We found that repo-to-text demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago.Ā It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Meet Socket at Black Hat & DEF CON 2025 for 1:1s, insider security talks at Allegiant Stadium, and a private dinner with top minds in software supply chain security.
Security News
CAI is a new open source AI framework that automates penetration testing tasks like scanning and exploitation up to 3,600Ć faster than humans.
Security News
Deno 2.4 brings back bundling, improves dependency updates and telemetry, and makes the runtime more practical for real-world JavaScript projects.