README

This command line tool allows you to copy the entire structure of a directory or GitHub repository, including file contents, to your clipboard. This is particularly useful for quickly sharing the contents and structure of your files in a readable format, such as during code reviews, collaborative debugging sessions, or when working with AI assistants.

Features

Copy directory structure and file contents to clipboard, ready to paste into chatbots like Claude or ChatGPT
Support for copying directly from GitHub repositories using URLs
Flexible ruleset system for including/excluding files
Support for multiple rulesets to target different parts of your project
Support for custom, predefined, and auto-detected rulesets
Output to clipboard, console, or file
Cross-platform support (Linux, macOS, Windows)

Quick Start

After installation, you can quickly copy the current directory structure to your clipboard:

ctree

Or copy from a GitHub repository:

ctree https://github.com/username/repo/tree/main/src

You can get command help with:

ctree --help

If you're in a Laravel or SvelteKit project, the automatic rules will work out of the box. Otherwise, you'll need to specify a custom ruleset.

Documentation

For more detailed information on using Ctree, please refer to the following documentation:

Ruleset Examples: Various examples of rulesets for different project types
Writing Rulesets: Detailed guide on how to write and structure rulesets
Fields and Operations Reference: Complete list of available fields and operations for rulesets
Using Multiple Rulesets: Guide on using multiple rulesets in a single project

For a quick overview of the ruleset system, see the Ruleset System section below.

Prerequisites

Before installing and using copy-tree, make sure to have the necessary utilities installed on your system:

Git: Required for GitHub repository support
Linux: Install xclip which is used by the tool to access the clipboard
```
sudo apt-get update && sudo apt-get install -y xclip
```
macOS: macOS comes with pbcopy preinstalled, so no additional installation is necessary
Windows: Windows has the clip command available by default, so no additional installation is required

Installation

You can install the package via Composer:

composer require gregpriday/copy-tree

Usage

After installation, you can run the ctree command directly from your terminal. Here's how you can use the command:

# Display the help information
ctree --help

# Copy current directory to clipboard
ctree

# Copy from a GitHub repository
ctree https://github.com/username/repo/tree/main/src

# Clear GitHub repository cache
ctree --clear-cache

# Specify a local directory path
ctree /path/to/directory

# Display the output in the console
ctree --display

# Output to a file instead of clipboard
ctree --output=output.txt

# Use a specific ruleset
ctree --ruleset=laravel

# Include only the directory tree in the output, not the file contents
ctree --only-tree

# Filter files using a glob pattern on the relative path
ctree --filter="*.php"

Command Arguments and Options

path: (Optional) The directory path or GitHub URL to copy. If not specified, the current working directory is used
--depth, -d: (Optional) Maximum depth of the tree. Default is 10
--output, -o: (Optional) Outputs to a file instead of the clipboard
--display, -i: Display the output in the console
--ruleset, -r: Ruleset to apply. Available options include 'auto', 'laravel', 'sveltekit', and any custom rulesets. Default is 'auto'
--only-tree, -t: Include only the directory tree in the output, not the file contents
--filter, -f: Filter files using a glob pattern on the relative path
--clear-cache: Clear the GitHub repository cache

GitHub Repository Support

Ctree can copy files directly from GitHub repositories using URLs. The supported URL format is:

https://github.com/username/repository/tree/branch/path

Examples:

# Copy the entire repository
ctree https://github.com/username/repo

# Copy a specific branch
ctree https://github.com/username/repo/tree/develop

# Copy a specific directory
ctree https://github.com/username/repo/tree/main/src

# Clear the repository cache
ctree --clear-cache

The tool maintains a local cache of cloned repositories to improve performance. Use the --clear-cache option to remove all cached repositories.

Global Installation and Usage

Install copy-tree globally with Composer to use the ctree command from anywhere in your terminal:

composer global require gregpriday/copy-tree

Run the same command to upgrade to the latest version.

Ensure the Composer global bin directory is in your PATH. Typically, this is ~/.composer/vendor/bin or ~/.config/composer/vendor/bin for Unix systems. Add this to your .bashrc or .zshrc:

export PATH="$PATH:$HOME/.composer/vendor/bin"

Reload your configuration:

source ~/.bashrc
# Or, if using zsh
source ~/.zshrc

Now, you can use ctree from any directory:

# Copy the current directory to the clipboard
ctree

# Copy with specific depth and display output
ctree /path/to/directory --depth=2 --display

Ruleset System

Ctree uses a flexible ruleset system to determine which files and directories to include or exclude. The ruleset system works in the following order:

Custom rulesets in the current directory
Predefined rulesets
Auto-detection
Default ruleset

See the Laravel Ruleset for an example.

For a complete guide on writing rulesets, see the Writing Rulesets documentation.

For examples of rulesets for various project types, check out our Ruleset Examples.

Ruleset Format

Rulesets are defined in JSON format. Here's an overview of the structure:

{
    "rules": [
        [
            ["field", "operator", "value"],
            ["field", "operator", "value"]
        ]
    ],
    "globalExcludeRules": [
        ["field", "operator", "value"]
    ],
    "always": {
        "include": ["file1", "file2"],
        "exclude": ["file3", "file4"]
    }
}

rules: An array of rule sets. Each rule set is an array of rules that must all be true for a file to be included.
globalExcludeRules: An array of rules that, if any are true, will exclude a file.
always: Specifies files to always include or exclude, regardless of other rules.

Fields

Available fields include:

folder, path, dirname, basename, extension, filename, contents, contents_slice, size, mtime, mimeType

Operators

Available operators include:

>, >=, <, <=, =, !=, oneOf, regex, glob, fnmatch, contains, startsWith, endsWith, length, isAscii, isJson, isUlid, isUrl, isUuid

For a complete reference of the ruleset schema, see the schema.json file in the project repository.

All operators can be negated by prefixing them with 'not', e.g., notOneOf, notRegex, notStartsWith. This allows for more flexible exclusion rules.

Custom Rulesets

You can create a custom ruleset file named /.ctree/ruleset.json in your project directory. If this file exists, it will be used instead of any predefined or default rulesets.

You can also create named rulesets at /.ctree/example.json, which will be used for ctree -r example.

Multiple Rulesets

Ctree supports the use of multiple rulesets within a single project, allowing you to selectively share different parts of your codebase. This is particularly useful for large projects with distinct sections or modules.

To use multiple rulesets:

Create separate JSON files for each ruleset in the /.ctree directory of your project.
Name each file according to the desired ruleset name (e.g., /.ctree/frontend.json, /.ctree/backend.json).
Use the --ruleset or -r option to specify which ruleset to apply:

ctree --ruleset frontend
ctree --ruleset backend

This feature enables you to easily share specific parts of your project, such as only the frontend code or only the backend code, without having to modify your ruleset each time.

For more detailed information on using multiple rulesets, refer to the Using Multiple Rulesets documentation.

Predefined Rulesets

Ctree comes with predefined rulesets for common project types. Use them like this:

ctree --ruleset laravel   # Uses the predefined Laravel ruleset
ctree --ruleset sveltekit # Uses the predefined SvelteKit ruleset

Auto-detection

If no ruleset is specified, Ctree will attempt to auto-detect the project type and use an appropriate ruleset:

ctree  # Auto-detects project type and uses the most suitable ruleset

Default Ruleset

If no custom ruleset is found, no predefined ruleset is specified, and auto-detection fails, Ctree will use the default ruleset.

Troubleshooting

If you encounter issues with clipboard functionality:

Linux: Ensure xclip is installed and running.
macOS: Try running the command with sudo if you get permission errors.
Windows: Make sure you're running the command prompt as an administrator if you encounter permission issues.

If the output is truncated, try using the --output option to save to a file instead of copying to the clipboard.

Contributing

Contributions are welcome! Here's how you can contribute:

Fork the repository
Create a new branch (git checkout -b feature/amazing-feature)
Make your changes
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Please make sure to update tests as appropriate. For more details, see the CONTRIBUTING file.

Testing

Run the tests with:

composer test

Changelog

For details on recent changes, check out the CHANGELOG.

Security

If you discover any security related issues, please email greg@siteorigin.com instead of using the issue tracker.

Credits

License

The MIT License (MIT). Please see License File for more information.

gregpriday / copy-tree

Maintainers

Details