{"id":24577731,"url":"https://github.com/kgruiz/concat-zsh","last_synced_at":"2026-05-20T19:04:22.793Z","repository":{"id":273608607,"uuid":"920276884","full_name":"kgruiz/concat-zsh","owner":"kgruiz","description":"A powerful Zsh script for merging file contents with advanced filtering, recursive search, and customizable output. Ideal for developers and LLM users needing efficient file management and context preparation.","archived":false,"fork":false,"pushed_at":"2025-03-11T19:37:36.000Z","size":84,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-11T20:32:35.836Z","etag":null,"topics":["automation","context","developer-tools","file-concatenation","file-management","llm","shell-scripting","zsh"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kgruiz.png","metadata":{"files":{"readme":"Docs/README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-01-21T21:37:55.000Z","updated_at":"2025-03-11T19:37:40.000Z","dependencies_parsed_at":"2025-01-21T23:23:13.658Z","dependency_job_id":"6511e2da-8ab1-44e0-8f09-80134e638826","html_url":"https://github.com/kgruiz/concat-zsh","commit_stats":null,"previous_names":["kgruiz/concat-zsh"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kgruiz%2Fconcat-zsh","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kgruiz%2Fconcat-zsh/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kgruiz%2Fconcat-zsh/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kgruiz%2Fconcat-zsh/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kgruiz","download_url":"https://codeload.github.com/kgruiz/concat-zsh/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244040699,"owners_count":20388109,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","context","developer-tools","file-concatenation","file-management","llm","shell-scripting","zsh"],"created_at":"2025-01-23T23:40:04.537Z","updated_at":"2026-05-20T19:04:17.750Z","avatar_url":"https://github.com/kgruiz.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# concat-zsh\n\n`concat` is a Zsh function designed to merge the contents of multiple files based on specified extensions and filtering criteria. Developed to aggregate files for use as context in Large Language Model (LLM) queries, `concat` is a useful tool for developers and system administrators seeking to organize and consolidate project files efficiently.\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Features](#features)\n- [Installation](#installation)\n  - [Method 1: Automatic Sourcing of All Custom Functions](#method-1-automatic-sourcing-of-all-custom-functions)\n  - [Method 2: Direct Sourcing of the `concat` Function](#method-2-direct-sourcing-of-the-concat-function)\n- [Quick Start](#quick-start)\n- [Usage](#usage)\n  - [Basic Syntax](#basic-syntax)\n  - [Options](#options)\n  - [Examples](#examples)\n- [Contributing](#contributing)\n  - [How to Contribute](#how-to-contribute)\n  - [Reporting Issues](#reporting-issues)\n- [Support](#support)\n- [License](#license)\n\n## Overview\n\n`concat` facilitates the combination of file contents by providing filtering and concatenation options. Whether preparing code snippets for LLMs, consolidating logs, or managing files within larger projects, this tool offers a straightforward and customizable approach.\n\n## Features\n\n- **Extension Filtering**: Select files by one or multiple extensions (e.g., `.py`, `.js`, `.txt`).\n- **Recursive Search**: Traverse directories recursively or limit the search to the top level.\n- **Exclusion Patterns**: Exclude specific files or directories using patterns or wildcards.\n- **Hidden Files Handling**: Option to include or exclude hidden files and directories.\n- **Python Cache Cleanup**: Automatically remove `__pycache__` directories and `.pyc` files.\n- **Directory Tree Overview**: Generate a tree structure of the target directory in the output.\n- **Verbose and Debug Modes**: Enable logging and execution tracing for troubleshooting.\n- **Binary File Exclusion**: Automatically skip unreadable or binary files if desired.\n- **Customizable Output**: Specify output file names and directories.\n- **LLM-Friendly Concatenation**: Organize file aggregation for compatibility with Large Language Models.\n\n## Installation\n\nIntegrate the `concat` function into your Zsh environment by selecting one of the following methods based on your preference and setup requirements.\n\n### Method 1: Automatic Sourcing of All Custom Functions\n\n**Suitable for users managing multiple custom Zsh functions.**\n\n1. **Create a Directory for Custom Functions**\n\n   Ensure a dedicated directory for your custom Zsh functions exists. If not, create one using the following command:\n\n   ```zsh\n   mkdir -p ~/.zsh_functions\n   ```\n\n2. **Add the `concat.zsh` File**\n\n   Move the `concat.zsh` file into the `~/.zsh_functions` directory:\n\n   ```zsh\n   mv /path/to/concat.zsh ~/.zsh_functions/concat.zsh\n   ```\n\n   *Replace `/path/to/concat.zsh` with the actual path to your `concat.zsh` file.*\n\n3. **Configure Your Zsh Profile**\n\n   Open your `~/.zshrc` file in your preferred text editor:\n\n   ```zsh\n   nano ~/.zshrc\n   ```\n\n   Append the following script to source all `.zsh` files within the `~/.zsh_functions` directory:\n\n   ```zsh\n   # Source all custom Zsh functions from ~/.zsh_functions\n   if [[ -d \"$HOME/.zsh_functions\" ]]; then\n       for func_file in \"$HOME/.zsh_functions\"/*.zsh; do\n           if [[ -f \"$func_file\" ]]; then\n               if ! source \"$func_file\" 2\u003e/dev/null; then\n                   echo \"Error: Failed to source $(basename \"$func_file\"). Please verify the file's path and integrity.\" \u003e\u00262\n               fi\n           else\n               echo \"Warning: '$func_file' is not a regular file or does not exist.\" \u003e\u00262\n           fi\n       done\n   else\n       echo \"Error: Directory '$HOME/.zsh_functions' does not exist. Please create it and add your function files.\" \u003e\u00262\n   fi\n   ```\n\n4. **Reload Your Zsh Configuration**\n\n   Apply the changes by sourcing your updated `~/.zshrc`:\n\n   ```zsh\n   source ~/.zshrc\n   ```\n\n### Method 2: Direct Sourcing of the `concat` Function\n\n**Recommended for users who prefer to source the `concat` function individually. Creating a directory for functions is optional but recommended for better organization.**\n\n1. **Create a Directory for Custom Functions (Optional but Recommended)**\n\n   While optional, organizing your custom functions in a dedicated directory enhances maintainability. Create one if you haven't already:\n\n   ```zsh\n   mkdir -p ~/.zsh_functions\n   ```\n\n2. **Add the `concat.zsh` File**\n\n   Move the `concat.zsh` file into the `~/.zsh_functions` directory:\n\n   ```zsh\n   mv /path/to/concat.zsh ~/.zsh_functions/concat.zsh\n   ```\n\n   *Replace `/path/to/concat.zsh` with the actual path to your `concat.zsh` file.*\n\n3. **Configure Your Zsh Profile**\n\n   Open your `~/.zshrc` file in your preferred text editor:\n\n   ```zsh\n   nano ~/.zshrc\n   ```\n\n   Append the following script to source the `concat.zsh` function directly:\n\n   ```zsh\n   # Source the concat function\n   CONCAT_FUNC_PATH=\"$HOME/.zsh_functions/concat.zsh\"\n\n   if [[ -f \"$CONCAT_FUNC_PATH\" ]]; then\n       if ! source \"$CONCAT_FUNC_PATH\" 2\u003e/dev/null; then\n           echo \"Error: Failed to source 'concat.zsh'. Please verify the file's path and integrity.\" \u003e\u00262\n       fi\n   else\n       echo \"Error: 'concat.zsh' not found in '$HOME/.zsh_functions/'. Please ensure the file exists.\" \u003e\u00262\n   fi\n   ```\n\n4. **Reload Your Zsh Configuration**\n\n   Apply the changes by sourcing your updated `~/.zshrc`:\n\n   ```zsh\n   source ~/.zshrc\n   ```\n\n   **Note:** Only error messages will appear if issues are encountered during sourcing.\n\n## Quick Start\n\nAfter installation, you can concatenate files by specifying the desired extensions. For example, to concatenate all Python files in the current directory:\n\n```zsh\nconcat .py\n```\n\n## Usage\n\nThe `concat` function offers various options to customize how files are merged. Below are detailed instructions on its usage.\n\n### Basic Syntax\n\n```zsh\nconcat [extensions] [OPTIONS]\n```\n\n**Arguments:**\n\n- `[extensions]`: Specify a single extension (e.g., `.py`) or a comma-separated list of extensions (e.g., `.py,.js` or `txt,md`). If omitted, all file extensions are included.\n\n### Options\n\n| Option                        | Short | Description                                                                                                                                          |\n|-------------------------------|-------|------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `--output-file \u003cfile\u003e`        | `-f`  | Name or path for the concatenated output file. Defaults to `concatOutput.txt`.                                                                       |\n| `--output-dir \u003cdir\u003e`          | `-d`  | Directory where the output file will be saved. Defaults to the current directory.                                                                    |\n| `--input-dir \u003cdir\u003e`           | `-i`  | Directory to search for files. Can be relative or absolute. Defaults to the current directory.                                                        |\n| `--exclude \u003cpatterns\u003e`        | `-e`  | Comma-separated list of file or directory paths/patterns to exclude. Supports wildcards.                                                             |\n| `--exclude-extensions \u003cexts\u003e` | `-X`  | Comma-separated list of file extensions to exclude (e.g., `txt,log`). Extensions can be prefixed with `.` or provided as plain text.                 |\n| `--recursive`                 | `-r`  | Recursively search subdirectories. Default is `true`.                                                                                                |\n| `--no-recursive`              |       | Disable recursive search.                                                                                                                            |\n| `--title`                     | `-t`  | Include a title line at the start of the output file. Default is `true`.                                                                             |\n| `--no-title`                  |       | Exclude the title line from the output file.                                                                                                         |\n| `--verbose`                   | `-v`  | Enable verbose output, showing matched files and other details.                                                                                      |\n| `--case-sensitive-extensions` | `-c`  | Match file extensions case-sensitively. Default is `false`.                                                                                          |\n| `--case-sensitive-excludes`   | `-s`  | Match exclude patterns case-sensitively. Default is `false`.                                                                                         |\n| `--case-sensitive-all`        | `-a`  | Enable case-sensitive matching for both extensions and exclude patterns, overriding the two options above. Default is `false`.                        |\n| `--tree`                      | `-T`  | Include a tree representation of directories in the output. Default is `true`.                                                                        |\n| `--no-tree`                   |       | Disable the tree representation in the output (overrides `--tree`).                                                                                   |\n| `--include-hidden`            | `-H`  | Include hidden files and directories in the search. Default is `false`.                                                                               |\n| `--no-include-hidden`         |       | Exclude hidden files and directories from the search.                                                                                                |\n| `--delPyCache`                | `-p`  | Automatically delete `__pycache__` folders and `.pyc` files. Default is `true`.                                                                       |\n| `--no-delPyCache`             |       | Disable automatic deletion of `__pycache__` and `.pyc` files.                                                                                        |\n| `--exclude-binary`            | `-B`  | Automatically exclude unreadable or binary files from concatenation. Default is `true`.                                                              |\n| `--no-exclude-binary`         |       | Do not exclude unreadable or binary files (overrides `--exclude-binary`).                                                                             |\n| `--debug`                     | `-x`  | Enable debug mode with verbose execution tracing.                                                                                                     |\n| `--help`                      | `-h`  | Display the help message and exit.                                                                                                                    |\n\n### Examples\n\n1. **Concatenate Python Files, Exclude `__init__.py`, and Specify Output File**\n\n    ```zsh\n    concat .py --output-file allPython.txt --exclude __init__.py\n    ```\n\n2. **Concatenate Python and JavaScript Files Recursively with Verbose Output**\n\n    ```zsh\n    concat py,js -r -v\n    ```\n\n3. **Concatenate Files Without Adding a Title, Specify Input and Output Directories**\n\n    ```zsh\n    concat --no-title --input-dir ~/project --output-dir ~/Desktop\n    ```\n\n4. **Exclude Specific Extensions and Include Hidden Files**\n\n    ```zsh\n    concat txt,md -X log,tmp -H\n    ```\n\n5. **Enable Debug Mode for Troubleshooting**\n\n    ```zsh\n    concat .sh --debug\n    ```\n\n6. **Disable Automatic Exclusion of Binary Files**\n\n    ```zsh\n    concat .sh --no-exclude-binary\n    ```\n\n## Contributing\n\nContributions are welcome! Whether you're reporting a bug, suggesting a feature, or submitting a pull request, your input helps improve `concat`.\n\n### How to Contribute\n\n1. **Fork the Repository**\n\n    Navigate to the repository page and click the \"Fork\" button to create your own copy.\n\n2. **Clone Your Fork**\n\n    ```zsh\n    git clone https://github.com/your-username/concat-zsh.git\n    cd concat-zsh\n    ```\n\n3. **Create a Feature Branch**\n\n    ```zsh\n    git checkout -b feature/YourFeatureName\n    ```\n\n4. **Make Your Changes**\n\n    Ensure your code adheres to the project's coding standards and includes necessary documentation.\n\n5. **Commit Your Changes**\n\n    ```zsh\n    git commit -m \"Add feature: YourFeatureName\"\n    ```\n\n6. **Push to Your Fork**\n\n    ```zsh\n    git push origin feature/YourFeatureName\n    ```\n\n7. **Open a Pull Request**\n\n    Navigate to the original repository and click \"New Pull Request.\" Provide a clear description of your changes and their purpose.\n\n### Reporting Issues\n\nIf you encounter any issues or have feature requests, please open an issue in the repository's [Issues](https://github.com/your-username/concat-zsh/issues) section. Include detailed information to help maintainers address the problem effectively.\n\n## Support\n\nFor support, please open an issue in the [Issues](https://github.com/your-username/concat-zsh/issues) section of the repository.\n\n## License\n\nThis project is licensed under the [GNU General Public License v3.0](LICENSE). You are free to use, modify, and distribute this software in accordance with the terms of the license.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkgruiz%2Fconcat-zsh","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkgruiz%2Fconcat-zsh","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkgruiz%2Fconcat-zsh/lists"}