Skip to content

troubleshooting.md

Latest commit

 

History

History
396 lines (289 loc) · 6.74 KB

troubleshooting.md

File metadata and controls

396 lines (289 loc) · 6.74 KB

Troubleshooting Guide

This guide helps you resolve common issues with CopyTree.

Installation Issues

Command Not Found

Problem: copytree: command not found after installation

Solutions:

  1. Check npm global bin path:

    npm bin -g
# Add this path to your PATH environment variable

  2. Add to PATH (add to ~/.bashrc or ~/.zshrc):

    export PATH="$(npm bin -g):$PATH"
source ~/.bashrc  # or ~/.zshrc

  3. Verify installation:

    npm list -g copytree

  4. Use npx instead:

    npx copytree

Permission Errors (EACCES)

Problem: Permission denied during global installation

Solutions:

  1. Configure npm prefix:

    mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g copytree

  2. Use local installation:

    npm install copytree
npx copytree

Node.js Version Issues

Problem: Incompatible Node.js version

Solution:

# Check current version
node --version

# Install Node Version Manager (nvm)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Install Node.js 20+
nvm install 20
nvm use 20

Configuration Problems

Configuration Validation

Problem: Configuration errors or validation failures

Solutions:

  1. Validate configuration:

    copytree config:validate

  2. Inspect effective configuration:

    copytree config:inspect

Configuration File Not Found

Problem: CopyTree can't find configuration

Solutions:

  1. Check config location:

    ls -la ~/.copytree/

  2. Configuration is optional:

    # CopyTree works with built-in defaults
# Configuration files are optional
copytree --version

Output Issues

Nothing Copied to Clipboard

Problem: Command completes but clipboard is empty

Solutions:

  1. Check clipboard functionality:

    echo "test" | pbcopy  # macOS
echo "test" | xclip -selection clipboard  # Linux

  2. Use display mode to verify:

    copytree --display

  3. Save to file instead:

    copytree --output test.xml

  4. Use dry-run to check for errors:

    copytree --dry-run

Output Too Large

Problem: Output exceeds clipboard or memory limits

Solutions:

  1. Use file output:

    copytree --output large-project.xml

  2. Limit content:

    copytree --head 100 --char-limit 5000

  3. Use specific profile:

    copytree --profile minimal

  4. Stream output:

    copytree --stream > project.xml

Wrong Format

Problem: Output format not as expected

Solution:

# Specify format explicitly
copytree --format json
copytree --format xml
copytree --format tree

File Selection Problems

No Files Selected

Problem: "No files found matching criteria"

Solutions:

  1. Check current directory:

    pwd
ls -la

  2. Use less restrictive profile:

    copytree --profile full

  3. Debug file selection:

    copytree --dry-run

  4. Check .copytreeignore:

    cat .copytreeignore

Too Many Files Selected

Problem: Selecting entire node_modules or unwanted files

Solutions:

  1. Use specific profile:

    copytree --profile minimal

  2. Add exclusions:

    # Create .copytreeignore
echo "node_modules/" > .copytreeignore
echo "dist/" >> .copytreeignore

  3. Use filters:

    copytree --filter "src/**/*.js"

Git Integration Not Working

Problem: --modified or --changes not finding files

Solutions:

  1. Verify Git repository:

    git status

  2. Check Git installation:

    git --version

  3. Ensure changes exist:

    git diff --name-only
git diff --name-only main..HEAD

Performance Issues

Slow Execution

Problem: CopyTree takes too long to run

Solutions:

  1. Use specific profile:

    copytree --profile api  # Instead of --profile full

  2. Use filters to limit scope:

    copytree --filter "src/**/*.js"

  3. Exclude large directories:

    echo "coverage/" >> .copytreeignore
echo "build/" >> .copytreeignore

High Memory Usage

Problem: Process uses too much memory

Solutions:

  1. Stream output:

    copytree --stream > output.xml

  2. Limit files processed:

    copytree src/ --head 1000

  3. Increase Node.js memory:

    NODE_OPTIONS="--max-old-space-size=4096" copytree

Platform-Specific Issues

macOS Issues

Clipboard not working:

# Test pbcopy
echo "test" | pbcopy
pbpaste  # Should output "test"

File permissions:

# Reset permissions
chmod -R 755 ~/.copytree

Linux Issues

Missing clipboard support:

# Install clipboard utilities
sudo apt-get install xclip  # Debian/Ubuntu
sudo yum install xclip      # RedHat/CentOS

Path issues:

# Add to ~/.bashrc
export PATH="$HOME/.npm-global/bin:$PATH"

Windows (WSL) Issues

Line ending problems:

# Configure Git
git config --global core.autocrlf input

Path translation:

# Use WSL paths
copytree /mnt/c/Users/username/project

Getting Help

Debug Information

Collect debug information for bug reports:

# Version info
copytree --version
node --version
npm --version

# Configuration check
copytree config:validate

# Debug run
DEBUG=copytree:* copytree --dry-run

Logs and Cache

# Clear cache (clears all caches by default)
copytree cache:clear

# Clear specific cache types
copytree cache:clear --transformations
copytree cache:clear --git
copytree cache:clear --profiles

# Check cache location
ls -la ~/.copytree/cache/

Community Support

  • GitHub Issues: Report bugs and request features
  • Documentation: Check other guides in this documentation
  • Examples: Review the profile examples for common patterns

Common Error Messages

"Profile not found"

  • Check profile name spelling
  • Ensure profile file exists in .copytree/ or ~/.copytree/profiles/
  • Check with ls .copytree/ or ls ~/.copytree/profiles/

"No files found matching criteria"

  • Current directory might be empty
  • Profile rules might be too restrictive
  • Check .gitignore and .copytreeignore

"Invalid configuration"

  • Run copytree config:validate
  • Check JSON syntax in config files
  • Ensure all required fields are present