Add sources to enable other types of local dependencies (#2313)

* Add sources to enable other types of local dependencies that do not impact artifact dependencies.

* Fix formatting issues

* Wire up sources to environment creation

* Fix editable path source subdirectory handling and index-source lock resolution, and add per-environment source overrides, the HATCH_NO_SOURCES kill switch, and a hatch dep show sources command.

* Fix type errors

* Fix inheritance and address PR comments

* address bad anchor

Author: cjames23

docs/config/dependency.md

@@ -274,3 +274,18 @@ pkg[feature1,feature2] @ <REFERENCE> ; python_version < "3.7"
 ```
 
 Note that the space before the semicolon is required.
+
+
+## Sources
+
+Dependencies may be redirected to a local checkout, a Git branch, a URL, an alternate index, or a workspace member at install time, without changing the metadata your project publishes:
+
+```toml config-example
+[project]
+dependencies = ["foo"]
+
+[tool.hatch.sources]
+foo = "./packages/foo"
+```
+
+Sources are environment configuration, so each environment can redirect a dependency differently. See [environment sources](environment/sources.md) for the full reference.

docs/config/environment/overview.md

@@ -86,6 +86,9 @@ extra-dependencies = [
 !!! tip
     Hatch uses [pip](https://github.com/pypa/pip) to install dependencies so any [configuration](https://pip.pypa.io/en/stable/topics/configuration/) it supports Hatch does as well. For example, if you wanted to only use a private repository you could set the `PIP_INDEX_URL` [environment variable](#environment-variables).
 
+!!! tip
+    To redirect a dependency to a local path, Git repository, URL, alternate index, or workspace member without altering your published metadata, see [sources](sources.md). Each environment inherits the sources of its template and may override individual entries, and all sources can be disabled by setting the `HATCH_NO_SOURCES` environment variable.
+
 ## Installation
 
 ### Features (extras) ### {: #features }

docs/config/environment/sources.md

@@ -0,0 +1,154 @@
+# Environment sources
+
+-----
+
+The `sources` table of an environment redirects dependencies to alternative origins at install time without changing your project's published metadata. This is useful during development when you want to consume a dependency from a local checkout, a Git branch, a private index, or another workspace member, while keeping the released wheel pointing at the version you ship.
+
+A source is matched against your dependencies by name, after [PEP 503 normalization](https://peps.python.org/pep-0503/#normalized-names). Both [project dependencies](../metadata.md#dependencies) and [environment dependencies](overview.md#dependencies) are eligible for redirection.
+
+```toml config-example
+[project]
+dependencies = ["foo"]
+
+[tool.hatch.envs.default.sources]
+foo = "./packages/foo"
+```
+
+The top-level `[tool.hatch.sources]` table is an alias for the `default` environment, so the following is equivalent:
+
+```toml config-example
+[tool.hatch.sources]
+foo = "./packages/foo"
+```
+
+!!! note
+    Sources only affect installs performed by Hatch when it manages an environment. They do not influence the metadata of wheels you build with `hatch build`.
+
+## Inheritance
+
+Sources follow the usual [inheritance](overview.md#inheritance) rules, merging entry by entry so that an environment can redirect a single dependency differently while every other entry it inherits stays in place:
+
+```toml config-example
+[tool.hatch.sources]
+foo = "./packages/foo"
+bar = "./packages/bar"
+
+[tool.hatch.envs.test-upstream.sources]
+foo = { git = "https://github.com/example/foo", branch = "main" }
+```
+
+Here every environment installs both `foo` and `bar` from the local checkouts, except `test-upstream`, which keeps the local `bar` but tracks the upstream development branch of `foo`.
+
+An environment that does not inherit from `default`, such as a [detached](overview.md#detached-environments) one, receives no sources.
+
+## Path
+
+Use a relative or absolute path to a wheel, source distribution, or project directory:
+
+```toml config-example
+[tool.hatch.sources]
+foo = "./packages/foo"
+```
+
+The shorthand above is equivalent to the full form:
+
+```toml config-example
+[tool.hatch.sources]
+foo = { path = "./packages/foo", editable = true }
+```
+
+`editable` defaults to `true` to match Hatch's existing handling of local installs. Set `editable = false` for a non-editable install. If the package lives below the path root, set `subdirectory`:
+
+```toml config-example
+[tool.hatch.sources]
+foo = { path = "./monorepo", subdirectory = "packages/foo" }
+```
+
+For editable installs the subdirectory is resolved into the path itself (equivalent to `path = "./monorepo/packages/foo"`), since installers expect a bare project directory. For non-editable installs the subdirectory is passed as a URL fragment, which also supports archives.
+
+## Git
+
+Pull from a Git repository:
+
+```toml config-example
+[tool.hatch.sources]
+foo = { git = "https://github.com/example/foo" }
+```
+
+Pin to a specific revision with one of `rev`, `tag`, or `branch` (mutually exclusive):
+
+```toml config-example
+[tool.hatch.sources]
+foo = { git = "https://github.com/example/foo", rev = "abc1234" }
+bar = { git = "https://github.com/example/bar", tag = "v1.0" }
+baz = { git = "https://github.com/example/baz", branch = "main" }
+```
+
+Use `subdirectory` when the Python package is not at the repository root.
+
+## URL
+
+Install a wheel or source archive from a URL:
+
+```toml config-example
+[tool.hatch.sources]
+foo = { url = "https://files.example.com/foo-1.0.tar.gz" }
+```
+
+`subdirectory` is also supported for archives where the package is not at the root.
+
+## Index
+
+Resolve the dependency from a specific package index:
+
+```toml config-example
+[tool.hatch.sources]
+foo = { index = "https://pypi.example.com/simple" }
+```
+
+The index URL is passed to the installer as `--extra-index-url`, so the default index (PyPI) remains the primary source. Multiple index sources are deduplicated and order-preserving.
+
+## Workspace
+
+Resolve the dependency from a [workspace](../../how-to/environment/workspace.md) member:
+
+```toml config-example
+[tool.hatch.sources]
+my-pkg = { workspace = true }
+```
+
+The actual install path is determined by the matching member in `tool.hatch.envs.<ENV_NAME>.workspace.members`. This lets you declare workspace membership in one place and reference it from many environments.
+
+## Precedence
+
+A dependency that already uses a [PEP 508 direct reference](../dependency.md#direct-references) is left untouched — the explicit URL on the dependency wins over a configured source.
+
+## Disabling sources
+
+Setting the `HATCH_NO_SOURCES` environment variable to any non-empty value disables all sources. This is useful in CI to verify that your published metadata resolves on its own, without local redirections:
+
+```
+HATCH_NO_SOURCES=1 hatch env create
+```
+
+## Inspecting sources
+
+The [`dep show sources`](../../cli/reference.md#hatch-dep-show) command displays each configured source, its target, and the dependencies of the active environment that it redirects. Sources that match no dependencies are reported with a warning, which helps catch typos in source names since unmatched sources are otherwise silently ignored.
+
+## Installer translation
+
+Sources produce installer-agnostic instructions that Hatch renders into the right flags for the configured installer:
+
+| Source | Per-dependency form | Global flags |
+| --- | --- | --- |
+| `path` (editable) | `--editable <resolved>` | none |
+| `path` (non-editable) | `name @ file://<resolved>` | none |
+| `git` | `name @ git+<url>[@<ref>]` | none |
+| `url` | `name @ <url>` | none |
+| `index` | unchanged | `--extra-index-url <url>` |
+| `workspace` | resolved through `workspace.members` | none |
+
+Both [`installer = "pip"`](overview.md#dependencies) and `installer = "uv"` accept the same flag forms, so the same source configuration works for either. When an environment is [`locked`](overview.md#locked), sources also apply during lock resolution: rewritten requirements flow into the lock inputs and index sources are passed to the resolver as `--extra-index-url`.
+
+!!! note
+    Sources do not apply to [build requirements](../build.md#build-system) (`build-system.requires` or build target dependencies). Build environments always resolve from declared metadata so that builds remain reproducible.

docs/history/hatch.md

@@ -10,6 +10,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ***Added:***
 
+- Add the `sources` environment option, which redirects dependencies to a local path, Git repository, URL, alternate index, or workspace member at install time without altering published metadata. The top-level `[tool.hatch.sources]` table is an alias for the `default` environment, environments inherit sources entry by entry, the `HATCH_NO_SOURCES` environment variable disables them, and `hatch dep show sources` reports what each source redirects
+
 - Add the `--all`/`-a` flag to the `build` command to build the workspace root and every workspace member defined by the selected environment, consolidating artifacts in the workspace root's `dist` directory by default. A root that does not define a `project` table is skipped so that a top-level `pyproject.toml` may only contain workspace configuration
 
 ***Fixed:***

docs/plugins/environment/reference.md

@@ -74,6 +74,8 @@ All environment types should [offer support](#hatch.env.plugin.interface.Environ
       - platform
       - environment_dependencies
       - dependencies
+      - sources
+      - get_source_install_args
       - env_vars
       - env_include
       - env_exclude

docs/plugins/utilities.md

@@ -69,3 +69,27 @@
       - local_path
       - env_path
       - join
+
+::: hatch.project.sources.Source
+    options:
+      show_source: false
+
+::: hatch.project.sources.PathSource
+    options:
+      show_source: false
+
+::: hatch.project.sources.GitSource
+    options:
+      show_source: false
+
+::: hatch.project.sources.UrlSource
+    options:
+      show_source: false
+
+::: hatch.project.sources.IndexSource
+    options:
+      show_source: false
+
+::: hatch.project.sources.WorkspaceSource
+    options:
+      show_source: false

mkdocs.yml

@@ -73,6 +73,7 @@ nav:
     - Build: config/build.md
     - Environments:
       - Overview: config/environment/overview.md
+      - Sources: config/environment/sources.md
       - Advanced: config/environment/advanced.md
     - Internal:
       - Testing: config/internal/testing.md

src/hatch/cli/dep/__init__.py

@@ -161,6 +161,52 @@ def table(app, project_only, env_only, show_lines, force_ascii):
         )
 
 
+@show.command("sources", short_help="Show dependency source redirections for the active environment")
+@click.option("--lines", "-l", "show_lines", is_flag=True, help="Whether or not to show lines between table rows")
+@click.option("--ascii", "force_ascii", is_flag=True, help="Whether or not to only use ASCII characters")
+@click.pass_obj
+def show_sources(app, show_lines, force_ascii):
+    """
+    Show each configured dependency source, what it points at, and which
+    dependencies of the active environment it redirects.
+    """
+    app.ensure_environment_plugin_dependencies()
+
+    from hatch.project.sources import describe_source, source_applied
+    from hatch.utils.metadata import normalize_project_name
+
+    environment = app.project.get_environment()
+    configured = environment.sources
+    if not configured:
+        app.display(f"No sources defined for environment `{app.env}`")
+        return
+
+    root = str(environment.root)
+    workspace_members = environment.source_workspace_members
+    matched = {name: [] for name in configured}
+    for dependency in environment.dependencies_complex:
+        normalized = normalize_project_name(dependency.name)
+        if normalized in matched and source_applied(dependency, configured[normalized], root, workspace_members):
+            matched[normalized].append(str(dependency))
+
+    columns = {"Source": {}, "Type": {}, "Target": {}, "Dependencies": {}}
+    for i, (name, source) in enumerate(sorted(configured.items())):
+        source_type, target = describe_source(source)
+        columns["Source"][i] = name
+        columns["Type"][i] = source_type
+        columns["Target"][i] = target
+        columns["Dependencies"][i] = "\n".join(matched[name]) if matched[name] else "none"
+
+    column_options = {"Source": {"no_wrap": True}, "Type": {"no_wrap": True}}
+    app.display_table(
+        f"Sources: {app.env}", columns, show_lines=show_lines, column_options=column_options, force_ascii=force_ascii
+    )
+
+    unused = sorted(name for name, deps in matched.items() if not deps)
+    if unused:
+        app.display_warning(f"Sources matched no dependencies of environment `{app.env}`: {', '.join(unused)}")
+
+
 @show.command(short_help="Enumerate dependencies as a list of requirements")
 @click.option("--project-only", "-p", is_flag=True, help="Whether or not to exclude environment dependencies")
 @click.option("--env-only", "-e", is_flag=True, help="Whether or not to exclude project dependencies")

src/hatch/config/constants.py

@@ -10,6 +10,7 @@ class AppEnvVars:
     NO_COLOR = "NO_COLOR"
     FORCE_COLOR = "FORCE_COLOR"
     KEEP_ENV = "HATCH_KEEP_ENV"
+    NO_SOURCES = "HATCH_NO_SOURCES"
 
 
 class ConfigEnvVars:

src/hatch/dep/core.py

@@ -35,5 +35,23 @@ def path(self) -> Path | None:
         uri = hyperlink.parse(self.url)
         if uri.scheme != "file":
             return None
-        decoded_url = unquote(self.url)
+        # The fragment (e.g. `#subdirectory=...`) is not part of the filesystem path
+        decoded_url = unquote(self.url.split("#", 1)[0])
         return Path.from_uri(decoded_url)
+
+    @cached_property
+    def subdirectory(self) -> str | None:
+        """
+        The `subdirectory` component of the URL fragment, if any.
+        """
+        from urllib.parse import parse_qs, urlsplit
+
+        if self.url is None:
+            return None
+
+        fragment = urlsplit(self.url).fragment
+        if not fragment:
+            return None
+
+        subdirectories = parse_qs(fragment).get("subdirectory")
+        return subdirectories[0] if subdirectories else None