Copy Files Automatically to Another Repo

Deleted Files

The copier app does not automatically delete files in the destination repository. If your PR deletes a file in the source repository, the copier app adds that filepath to a deprecated_examples.json that lives in the source repository. But the file itself remains in the destination repository.

Your team can set a process to manually remove the file from the destination repository, which might include updating any docs links that refer to that file before deleting it. This is to prevent breaking changes in the destination repository, including any links to the file.

Available Workflow Properties

Global Defaults

You can define global defaults in the .copier/config.yaml file. These defaults apply to all workflows unless overridden in an individual workflow.

Define the Workflow and Destination

To define a workflow, you must specify the following information in the .copier/config.yaml file in the root of your source repository:

workflows:
- name: "my-workflow"
    destination:
      repo: "mongodb/destination-repo"
      branch: "main"

• name: A unique name for the workflow.

• destination: The repository and branch to copy files to:

  • repo: Owner or name for the git repository to copy the files to.

  • branch: Branch to copy the files to, either to open a PR against or to commit to directly. Defaults to main.

workflows:
- name: "copy-to-docs" # Workflow name 1
    destination:
      repo: "mongodb/docs" # Destination repository 1
    transformations:
    - move: { from: "examples", to: "code" }
- name: "copy-to-website" # Workflow name 2
    destination:
      repo: "mongodb/website" # Destination repository 2
    transformations:
    - move: { from: "examples", to: "static/examples" }

Transform Files

To define the source files to copy and where to copy them to, use the transformation block. You can also transform files (for example, change the file path, name, or extension) as they are copied to the destination repository.

Supported transformations include basic moves and copies, as well as more complex transformations that use glob and regex patterns.

transformations:
  - move:
      from: "examples/go"
      to: "code/go"

transformations:
  - copy:
      from: "README.md"
      to: "docs/README.md"

transformations:
  - glob:
      pattern: "examples/**/*.go"
      transform: "code/${relative_path}"

transformations:
  - regex:
      pattern: "^examples/(?P<lang>[^/]+)/(?P<file>.+)$"
      transform: "code/${lang}/${file}"

Exclude Files

Use the exclude block to prevent certain files from being copied:

workflows:
 - name: "my-workflow"
   destination:
     repo: "mongodb/destination-repo"
     branch: "main"
   transformations:
     - move: { from: "src", to: "dest" }
   exclude:
     - "**/.env"
     - "**/node_modules/**"
     - "**/*.test.js"

The following are common files to exclude:

• Environment files: **/.env

• Dependencies: **/node_modules/**

• Build artifacts: **/dist/**, **/build/**

• Test files: **/*.test.*, **/tests/**

• System files: **/.DS_Store, **/Thumbs.db

Define the Commit Strategy

To define how the copier app commits changes to the destination repository, add a commit_strategy block to the workflow.

There are three strategies available:

• Pull request with manual merge (default)

• Pull request with auto-merge

• Direct commit

If you don't include a commit_strategy section, the copier app uses the default strategy, which is a pull request with manual merge.

commit_strategy:
type: "pull_request"
pr_title: "Update examples from ${source_repo}"
pr_body: |
    Automated update from source repository.
    Source PR: #${pr_number}
    Commit: ${commit_sha}
auto_merge: false  # Requires manual review and merge

commit_strategy:
type: "pull_request"
auto_merge: true  # Automatically merges if no conflicts

commit_strategy:
type: "direct"
commit_message: "Update examples from ${source_repo}"

Customize Pull Request Details

You can customize the PR title, body, and commit message to include relevant information.

workflows:
  - name: "my-workflow"
    destination:
      repo: "mongodb/destination-repo"
      branch: "main"
    transformations:
      - move: { from: "src", to: "dest" }
    commit_strategy:
      type: "pull_request"
      pr_title: "Update examples from ${source_repo}"
      pr_body: |
        Automated update from source repository.
        Source PR: #${pr_number}
        Commit: ${commit_sha}
      auto_merge: false

workflows:
  - name: "my-workflow"
    destination:
      repo: "mongodb/destination-repo"
      branch: "main"
    transformations:
      - move: { from: "src", to: "dest" }
    commit_strategy:
      type: "pull_request"
      use_pr_template: true

My files weren't copied

Verify:

• Was the PR merged to main? The PR must be merged (not closed) to the correct branch to trigger the copier.

• Do the changed files match your transformation patterns? The filepaths must match at least one workflow pattern to be copied.

• Is the copier installed in the destination repository? Verify with the DevDocs team to confirm.

• Are your files being excluded due to your exclude patterns?

Files are being copied to the wrong location

Verify:

• Is the destination repository and branch correct?

• Your filepaths:

  • Are your paths relative to repository root? Filepaths must be relative to repository root, not relative to config file location. For example, to copy files from the examples/go directory in the source repository, use from: "examples/go" instead of from: "../examples/go".

  • If you're using glob or regex transform types, is your pattern correct? Are your variables used correctly?

  • If you're using move or copy transform types, are your to paths correct?