| Name | repo-to-text JSON |
| Version |
0.5.4
JSON |
| download |
| home_page | None |
| Summary | Convert a directory structure and its contents into a single text file, including the tree output and file contents in markdown code blocks. It may be useful to chat with LLM about your code. |
| upload_time | 2024-12-17 16:28:20 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.6 |
| license | MIT |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Repository to Text Conversion: repo-to-text command
`repo-to-text` is an open-source project that converts the structure and contents of a directory (repository) into a single text file. By executing a simple command in the terminal, this tool generates a text representation of the directory, including the output of the `tree` command and the contents of each file, formatted for easy reading and sharing. This can be very useful for development and debugging with LLM.
## Example of Repository to Text Conversion
The generated text file will include the directory structure and contents of each file. 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).
The same text will appear in your clipboard. You can paste it into a dialog with the LLM and start communicating.
## Features
- Generates a text representation of a directory's structure.
- Includes the output of the `tree` command.
- Saves the contents of each file, encapsulated in markdown code blocks.
- Copies the generated text representation to the clipboard for easy sharing.
- Easy to install and use via `pip`.
## 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:
```bash
pip install --upgrade repo-to-text
```
## Usage
After installation, you can use the `repo-to-text` command in your terminal. Navigate to the directory you want to convert and run:
```bash
repo-to-text
```
or
```bash
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.
### Options
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:
```bash
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:
```bash
repo-to-text --create-settings
```
or
```bash
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:
```bash
repo-to-text --debug
```
or to save the debug log to a file:
```bash
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:
```bash
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:
```bash
repo-to-text --stdout > myfile.txt
```
This will write the output directly to `myfile.txt` instead of creating a timestamped file.
## Settings
`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.
### Creating the Settings 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:
```yaml
# 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 of ..." sections
ignore-tree-and-content:
- ".repo-to-text-settings.yaml"
- "examples/"
- "MANIFEST.in"
- "setup.py"
# Ignore files and directories for "Contents of ..." section
ignore-content:
- "README.md"
- "LICENSE"
- "tests/"
```
You can copy this file from the [existing example in the project](https://github.com/kirill-markin/repo-to-text/blob/main/.repo-to-text-settings.yaml) 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.
### Configuration Options
- **gitignore-import-and-ignore**: Ignore files and directories specified in `.gitignore` for all sections.
- **ignore-tree-and-content**: Ignore files and directories for the tree and "Contents of ..." sections.
- **ignore-content**: Ignore files and directories only for the "Contents of ..." section.
Using these settings, you can control which files and directories are included or excluded from the final text file.
### Wildcards and Inclusions
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:
```yaml
ignore-tree-and-content:
- "*.txt"
- "!README.txt"
```
## gitignore Rule to Ignore generated files
To ignore the generated text files, add the following lines to your `.gitignore` file:
```gitignore
repo-to-text_*.txt
```
## Install Locally
To install `repo-to-text` locally for development, follow these steps:
1. Clone the repository:
```bash
git clone https://github.com/kirill-markin/repo-to-text
cd repo-to-text
```
2. Install the package with development dependencies:
```bash
pip install -e ".[dev]"
```
### Requirements
- Python >= 3.6
- Core dependencies:
- setuptools >= 70.0.0
- pathspec >= 0.12.1
- argparse >= 1.4.0
- PyYAML >= 6.0.1
### Development Dependencies
For development, additional packages are required:
- pytest >= 8.2.2
- black
- mypy
- isort
- build
- twine
### Running Tests
To run the tests, use the following command:
```bash
pytest
```
## Uninstall
To uninstall the package, run the following command from the directory where the repository is located:
```bash
pip uninstall repo-to-text
```
## Contributing
Contributions are welcome! If you have any suggestions or find a bug, please open an issue or submit a pull request.
## License
This project is licensed under the MIT License - see the [LICENSE](https://github.com/kirill-markin/repo-to-text/blob/main/LICENSE) file for details.
## Contact
This project is maintained by [Kirill Markin](https://github.com/kirill-markin). For any inquiries or feedback, please contact [markinkirill@gmail.com](mailto:markinkirill@gmail.com).
Raw data
{
"_id": null,
"home_page": null,
"name": "repo-to-text",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": null,
"author": null,
"author_email": "Kirill Markin <markinkirill@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/73/2d/ffef4286a5b51f8fc6951e4314155b9df1f12dff1bfb8acecf5cbe8c42cf/repo_to_text-0.5.4.tar.gz",
"platform": null,
"description": "# Repository to Text Conversion: repo-to-text command\n\n`repo-to-text` is an open-source project that converts the structure and contents of a directory (repository) into a single text file. By executing a simple command in the terminal, this tool generates a text representation of the directory, including the output of the `tree` command and the contents of each file, formatted for easy reading and sharing. This can be very useful for development and debugging with LLM.\n\n## Example of Repository to Text Conversion\n\n\n\nThe generated text file will include the directory structure and contents of each file. 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).\n\nThe same text will appear in your clipboard. You can paste it into a dialog with the LLM and start communicating.\n\n## Features\n\n- Generates a text representation of a directory's structure.\n- Includes the output of the `tree` command.\n- Saves the contents of each file, encapsulated in markdown code blocks.\n- Copies the generated text representation to the clipboard for easy sharing.\n- Easy to install and use via `pip`.\n\n## Installation\n\n### Using pip\n\nTo install `repo-to-text` via pip, run the following command:\n\n```bash\npip install repo-to-text\n```\n\nTo upgrade to the latest version, use the following command:\n\n```bash\npip install --upgrade repo-to-text\n```\n\n## Usage\n\nAfter installation, you can use the `repo-to-text` command in your terminal. Navigate to the directory you want to convert and run:\n\n```bash\nrepo-to-text\n```\n\nor\n\n```bash\nflatten\n```\n\nThis 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.\n\n### Options\n\nYou can customize the behavior of `repo-to-text` with the following options:\n\n- `--output-dir <path>`: Specify an output directory where the generated text file will be saved. For example:\n\n ```bash\n repo-to-text --output-dir /path/to/output\n ```\n \n This will save the file in the specified output directory instead of the current directory.\n\n- `--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:\n\n ```bash\n repo-to-text --create-settings\n ```\n\n or\n\n ```bash\n repo-to-text --init\n ```\n\n 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.\n\n- `--debug`: Enable DEBUG logging. By default, `repo-to-text` runs with INFO logging level. To enable DEBUG logging, use the `--debug` flag:\n\n ```bash\n repo-to-text --debug\n ```\n\n or to save the debug log to a file:\n\n ```bash\n repo-to-text --debug > debug_log.txt 2>&1\n ```\n\n- `input_dir`: Specify the directory to process. If not provided, the current directory (`.`) will be used. For example:\n\n ```bash\n repo-to-text /path/to/input_dir\n ```\n\n- `--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:\n\n ```bash\n repo-to-text --stdout > myfile.txt\n ```\n\n This will write the output directly to `myfile.txt` instead of creating a timestamped file.\n\n## Settings\n\n`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.\n\n### Creating the Settings File\n\nTo create a settings file, add a file named `.repo-to-text-settings.yaml` at the root of your project with the following content:\n\n```yaml\n# Syntax: gitignore rules\n\n# Ignore files and directories for all sections from gitignore file\n# Default: True\ngitignore-import-and-ignore: True\n\n# Ignore files and directories for tree\n# and \"Contents of ...\" sections\nignore-tree-and-content:\n - \".repo-to-text-settings.yaml\"\n - \"examples/\"\n - \"MANIFEST.in\"\n - \"setup.py\"\n\n# Ignore files and directories for \"Contents of ...\" section\nignore-content:\n - \"README.md\"\n - \"LICENSE\"\n - \"tests/\"\n```\n\nYou can copy this file from the [existing example in the project](https://github.com/kirill-markin/repo-to-text/blob/main/.repo-to-text-settings.yaml) 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.\n\n### Configuration Options\n\n- **gitignore-import-and-ignore**: Ignore files and directories specified in `.gitignore` for all sections.\n- **ignore-tree-and-content**: Ignore files and directories for the tree and \"Contents of ...\" sections.\n- **ignore-content**: Ignore files and directories only for the \"Contents of ...\" section.\n\nUsing these settings, you can control which files and directories are included or excluded from the final text file.\n\n### Wildcards and Inclusions\n\nUsing Wildcard Patterns\n\n- `*.ext`: Matches any file ending with .ext in any directory.\n- `dir/*.ext`: Matches files ending with .ext in the specified directory dir/.\n- `**/*.ext`: Matches files ending with .ext in any subdirectory (recursive).\n\nIf you want to include certain files that would otherwise be ignored, use the ! pattern:\n\n```yaml\nignore-tree-and-content:\n - \"*.txt\"\n - \"!README.txt\"\n```\n\n## gitignore Rule to Ignore generated files\n\nTo ignore the generated text files, add the following lines to your `.gitignore` file:\n\n```gitignore\nrepo-to-text_*.txt\n```\n\n## Install Locally\n\nTo install `repo-to-text` locally for development, follow these steps:\n\n1. Clone the repository:\n\n ```bash\n git clone https://github.com/kirill-markin/repo-to-text\n cd repo-to-text\n ```\n\n2. Install the package with development dependencies:\n\n ```bash\n pip install -e \".[dev]\"\n ```\n\n### Requirements\n\n- Python >= 3.6\n- Core dependencies:\n - setuptools >= 70.0.0\n - pathspec >= 0.12.1\n - argparse >= 1.4.0\n - PyYAML >= 6.0.1\n\n### Development Dependencies\n\nFor development, additional packages are required:\n\n- pytest >= 8.2.2\n- black\n- mypy\n- isort\n- build\n- twine\n\n### Running Tests\n\nTo run the tests, use the following command:\n\n```bash\npytest\n```\n\n## Uninstall\n\nTo uninstall the package, run the following command from the directory where the repository is located:\n\n```bash\npip uninstall repo-to-text\n```\n\n## Contributing\n\nContributions are welcome! If you have any suggestions or find a bug, please open an issue or submit a pull request.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](https://github.com/kirill-markin/repo-to-text/blob/main/LICENSE) file for details.\n\n## Contact\n\nThis project is maintained by [Kirill Markin](https://github.com/kirill-markin). For any inquiries or feedback, please contact [markinkirill@gmail.com](mailto:markinkirill@gmail.com).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Convert a directory structure and its contents into a single text file, including the tree output and file contents in markdown code blocks. It may be useful to chat with LLM about your code.",
"version": "0.5.4",
"project_urls": {
"Homepage": "https://github.com/kirill-markin/repo-to-text",
"Repository": "https://github.com/kirill-markin/repo-to-text"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "012d2e1dcb3cae7af147c2d260c9ba133f21ac3e7f5778ef3df866242863b5b9",
"md5": "3c323aa0912283e3fbc213e53a192bf5",
"sha256": "cca9ef878aa84fd0b028e0e06dbebec71d8fc9216389c54137f205eb0aabdb3e"
},
"downloads": -1,
"filename": "repo_to_text-0.5.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3c323aa0912283e3fbc213e53a192bf5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 11639,
"upload_time": "2024-12-17T16:28:17",
"upload_time_iso_8601": "2024-12-17T16:28:17.096202Z",
"url": "https://files.pythonhosted.org/packages/01/2d/2e1dcb3cae7af147c2d260c9ba133f21ac3e7f5778ef3df866242863b5b9/repo_to_text-0.5.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "732dffef4286a5b51f8fc6951e4314155b9df1f12dff1bfb8acecf5cbe8c42cf",
"md5": "99d405cda0ca7fc26308b6de6e814e2a",
"sha256": "b4e2567de1257fb77633f559f50725ebc3fd09fc8827c575f0db556bbf267e51"
},
"downloads": -1,
"filename": "repo_to_text-0.5.4.tar.gz",
"has_sig": false,
"md5_digest": "99d405cda0ca7fc26308b6de6e814e2a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 124059,
"upload_time": "2024-12-17T16:28:20",
"upload_time_iso_8601": "2024-12-17T16:28:20.310098Z",
"url": "https://files.pythonhosted.org/packages/73/2d/ffef4286a5b51f8fc6951e4314155b9df1f12dff1bfb8acecf5cbe8c42cf/repo_to_text-0.5.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-17 16:28:20",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kirill-markin",
"github_project": "repo-to-text",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "repo-to-text"
}
