Mappings

emend includes a built-in mapping store for cross-repo identifier mappings and module-to-repo mappings. The public CLI surface for this is emend map.

Overview

Two mapping kinds are supported:

1. Identifier mappings – relationships between identifiers in different systems, such as users.UserService.create -> POST /api/v1/users.

2. Module mappings – a module prefix that resolves into another repo or a local directory so selectors can jump across repositories.

Mappings are stored in emend’s project metadata and are also exposed through the MCP server’s mappings tool.

Identifier mappings

Use identifier mappings to record cross-service relationships.

emend map add \
    backend "users.UserService.create" \
    gateway "POST /api/v1/users" \
    --rel calls --src-kind function --tgt-kind endpoint

emend map search "UserService"
emend map lookup "users.UserService.create"
emend map rm "users.UserService.create"

Relationship kinds include equivalent, calls, implements, produces, and consumes.

Module mappings

Module mappings tell emend where another codebase lives.

emend map add-module payments --repo org/payments-service
emend map add-module gateway --repo org/gateway --branch v2 --subpath src/gateway
emend map add-module shared.utils --path /home/user/shared-utils

emend map list-modules
emend map update-module payments --branch release
emend map rm-module payments

Resolution

emend map resolve resolves a dotted symbol or module path into a local selector, taking mappings into account.

emend map resolve payments.models.Order
# /path/to/payments/models.py::Order

You can also use mapped resolution directly from find:

emend find --include-map payments.models.Order

Choosing the mapped path

The target path (or repo + subpath) should point to the directory or file that corresponds to the mapped prefix itself.

Examples:

• If the payments package lives at repo-root/payments/, map with --repo org/repo --subpath payments.

• If the payments package lives at repo-root/src/payments/, map with --repo org/repo --subpath src/payments.

• If the repo root is itself the package, use --repo org/repo with no subpath.

Repo checkout layout

When a module mapping points at GitHub, emend uses gh repo clone to create a bare clone, then creates git worktrees for requested refs:

~/.cache/emend/repo-checkouts/
└── org--payments-service/
    ├── contents/
    └── checkouts/
        ├── main/
        └── v2/

Set EMEND_CACHE_DIR to relocate this cache root.