This command line tool allows you to copy the entire structure of a directory, 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 or collaborative debugging sessions.
- Copy directory structure and file contents to clipboard, ready to paste into chatbots like Claude or ChatGPT.
- 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).
After installation, you can quickly copy the current directory structure to your clipboard:
ctree
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.
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.
Before installing and using copy-tree
, make sure to have the necessary clipboard utilities installed on your system:
- 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.
You can install the package via Composer:
composer require gregpriday/copy-tree
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
# Specify a 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"
path
: (Optional) The directory path 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.
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
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.
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.
Available fields include:
folder
,path
,dirname
,basename
,extension
,filename
,contents
,contents_slice
,size
,mtime
,mimeType
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.
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
.
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.
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
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
If no custom ruleset is found, no predefined ruleset is specified, and auto-detection fails, Ctree will use the default ruleset.
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.
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.
Run the tests with:
composer test
For details on recent changes, check out the CHANGELOG.
If you discover any security related issues, please email [email protected] instead of using the issue tracker.
The MIT License (MIT). Please see License File for more information.