Skip to content

first-profile.md

Latest commit

 

History

History
429 lines (310 loc) · 8.63 KB

first-profile.md

File metadata and controls

429 lines (310 loc) · 8.63 KB

Creating Your First Custom Profile

Learn how to create custom profiles to tailor CopyTree's file selection for your specific needs.

Why Create a Custom Profile?

The default profile works great for general use, but you might want a custom profile to:

  • Focus on specific features or modules (e.g., only authentication code)
  • Apply transformers (extract text from PDFs, run OCR on images)
  • Include external sources (GitHub repos, other directories)
  • Override default exclusions (include lock files, test files, etc.)
  • Share team configurations (commit profiles to version control)

Profile Basics

A profile is a YAML file that tells CopyTree:

  • Which files to include
  • Which files to exclude
  • Which transformers to apply
  • Where to find external sources

Your First Profile

Let's create a profile that focuses on your project's documentation.

Step 1: Create Profile Directory

Profiles can be stored in three locations, with this search order:

  1. Project: .copytree/ (committed with your code)
  2. User: ~/.copytree/profiles/ (personal, available globally)
  3. Built-in: profiles/ (comes with CopyTree)

For this tutorial, we'll create a project profile:

# In your project root
mkdir -p .copytree

# Create the profile file
touch .copytree/docs-only.yml

Step 2: Define Basic Structure

Edit .copytree/docs-only.yml:

name: docs-only
description: Include only documentation files
version: 1.0.0

# Include patterns (glob syntax)
include:
  - "**/*.md"           # All Markdown files
  - "docs/**/*"         # Everything in docs directory
  - "README*"           # README files
  - "CHANGELOG*"        # Changelog files

# Exclude patterns
exclude:
  - "node_modules/**"   # Never include dependencies
  - "**/test/**"        # Skip test documentation

Step 3: Test Your Profile

Preview what files will be selected:

copytree --profile docs-only --dry-run

This shows which files match your rules without actually copying.

Step 4: Use Your Profile

# Copy to clipboard
copytree --profile docs-only

# Display in terminal
copytree --profile docs-only --display

# Save to file
copytree --profile docs-only --output documentation.md

Success! You've created and used your first custom profile.

Common Profile Patterns

Pattern 1: Source Code Only

Focus on implementation files:

name: source-only
description: Source code without tests or config

include:
  - "src/**/*.{js,jsx,ts,tsx}"
  - "lib/**/*.{js,ts}"
  - "*.{js,ts}"

exclude:
  - "**/*.test.{js,ts}"
  - "**/*.spec.{js,ts}"
  - "**/__tests__/**"
  - "**/*.config.{js,ts}"

always:
  - "package.json"
  - "tsconfig.json"

Pattern 2: API Documentation

API endpoints and schemas:

name: api-docs
description: API routes, controllers, and schemas

include:
  - "src/routes/**/*"
  - "src/controllers/**/*"
  - "src/models/**/*"
  - "src/middleware/**/*"
  - "**/*.swagger.{yml,yaml,json}"
  - "**/*.openapi.{yml,yaml,json}"

exclude:
  - "**/*.test.*"

always:
  - "package.json"
  - "README.md"

Pattern 3: Frontend Components

React/Vue components:

name: components
description: Frontend components and styles

include:
  - "src/components/**/*"
  - "src/pages/**/*"
  - "src/styles/**/*"
  - "**/*.{jsx,tsx,vue}"
  - "**/*.{css,scss,sass}"

exclude:
  - "**/*.test.{jsx,tsx}"
  - "**/*.spec.{jsx,tsx}"
  - "**/*.stories.{jsx,tsx}"

always:
  - "package.json"
  - "tailwind.config.js"

Advanced Features

Using Transformers

Add transformers to handle file loading:

name: with-transformers
description: Profile with file loading

include:
  - "**/*.{md,txt,js,ts}"
  - "docs/**/*"

transformers:
  # Load file content
  file-loader:
    enabled: true

Built-in transformers:

  • file-loader: Loads text file content
  • binary: Handles binary files (placeholder or base64)
  • streaming-file-loader: Streams large files (>10MB)

Profile Inheritance

Extend existing profiles:

name: my-docs
description: Docs profile based on default
extends: default

# Additional includes (merged with parent)
include:
  - "examples/**/*"
  - "tutorials/**/*"

# Additional excludes (merged with parent)
exclude:
  - "**/*.draft.md"
  - "docs/archive/**"

External Sources

Include files from other locations:

name: with-external
description: Include files from external sources

include:
  - "src/**/*"

external:
  # Include from GitHub
  - source: https://github.com/user/shared-docs
    destination: external/shared
    rules:
      - include: "**/*.md"

  # Include from local directory
  - source: /path/to/shared/library
    destination: external/lib
    rules:
      - include: "**/*.js"
      - exclude: "**/node_modules/**"

Rule Processing Order

CopyTree processes rules in this order:

  1. Initial Discovery - Find all files in directory
  2. Exclude Rules - Remove excluded files
  3. Include Rules - Keep only included files
  4. Always Rules - Force-include specific files
  5. Transformers - Process files as configured

Important: always rules override all exclusions.

include:
  - "src/**/*.js"

exclude:
  - "src/legacy/**"

always:
  - "src/legacy/important.js"  # Included despite exclude rule

Profile Location Strategy

Choose where to store your profiles based on usage:

Project profiles (.copytree/):

  • Committed to version control
  • Shared with team members
  • Project-specific configurations
  • Override user and built-in profiles
# Create project profile
mkdir -p .copytree
vi .copytree/myproject.yml

User profiles (~/.copytree/profiles/):

  • Personal configurations
  • Available across all projects
  • Not committed to repositories
# Create user profile
mkdir -p ~/.copytree/profiles
vi ~/.copytree/profiles/personal.yml

Built-in profiles (package installation):

  • Shipped with CopyTree
  • Read-only (do not modify)
  • Used as base for inheritance

Best Practices

1. Start Specific, Expand as Needed

# Good - specific and focused
include:
  - "src/auth/**/*.{js,ts}"
  - "src/auth/**/*.test.{js,ts}"

# Avoid - too broad, then exclude
include:
  - "**/*"
exclude:
  - "everything/you/dont/want/**"

2. Use Meaningful Names

# Good names
name: react-components
name: api-documentation
name: test-files

# Avoid generic names
name: my-profile
name: custom
name: test

3. Document Your Profiles

Always include a description:

name: feature-payment
description: |
  Payment feature files including:
  - Stripe integration
  - Payment components
  - Related tests and docs
version: 1.0.0

4. Test Before Using

Always preview before copying:

# Preview selection
copytree --profile myprofile --dry-run

# View in terminal first
copytree --profile myprofile --display

5. Version Your Profiles

Include profiles in version control when appropriate:

# .gitignore - DO commit project profiles
# (don't add .copytree/ to .gitignore)

# Commit to share with team
git add .copytree/
git commit -m "Add CopyTree profiles for documentation and API"

Common Issues

"Profile not found"

Check search paths:

# Check specific locations
ls .copytree/                    # Project profiles
ls ~/.copytree/profiles/         # User profiles

"No files selected"

Rules might be too restrictive:

# Use dry-run mode to debug
copytree --profile myprofile --dry-run

# This shows:
# - Which rules matched
# - Which files were excluded
# - Final file count

"Validation failed"

Check YAML syntax:

# Common issues:
# - Incorrect indentation (use spaces, not tabs)
# - Missing colons after keys
# - Quotes in wrong places

Next Steps

Now that you can create custom profiles:

  1. Configuration Reference - Project-wide and global settings

  2. Basic Usage - Common workflows and patterns

  3. CLI Reference - All command-line options

Quick Reference

# Profile usage
copytree --profile <name> --dry-run         # Preview file selection

# Using profiles
copytree --profile myprofile                # Use custom profile
copytree --profile default                  # Explicit default
copytree                                    # Implicit default

# Profile locations
.copytree/                                  # Project profiles (committed)
~/.copytree/profiles/                       # User profiles (personal)
<install>/profiles/                         # Built-in profiles (read-only)

Well done! You now know how to create custom profiles to tailor CopyTree for any project or use case.