feat: define target alias/default resolution for the new :Forge CLI #147

New issue

Closed

opened 2026-04-11 19:09:17 +00:00 by barrettruth · 1 comment

barrettruth commented

2026-04-11 19:09:17 +00:00

Prerequisites

I have searched existing issues.

Problem

Issue #142 defines a canonical Ex-style :Forge command language, and #144 defines explicit repo/revision/location target parsing. But parsing explicit targets is only half of the problem.

Forge still needs a canonical policy for what happens when users do not specify a target.

This is where the real fork/upstream behavior is decided:

what repo=upstream means
whether aliases resolve before git remotes
what the default collaboration repo is
what ci list should target by default
what pr create should use for default head= and base=
how users configure aliases and target defaults

Without an explicit defaults/alias policy, the new CLI will still feel ambiguous even if the syntax is better.

Proposed solution

Define a dedicated target resolution policy for the new :Forge command language.

1. Alias resolution order

Resolve repo= and repo-bearing targets in this order:

configured alias
git remote name
explicit hosted repo path

This should be documented and tested.

2. Configurable aliases

Add user config for explicit target aliases.

Example shape:

vim.g.forge = {
  targets = {
    aliases = {
      upstream = 'remote:upstream',
      origin = 'remote:origin',
      work = 'github.com/barrettruth/forge.nvim',
    },
  },
}

The exact config shape can change, but the concept should be explicit and documented.

3. Explicit default policies

Define and document default target policy per command family.

At minimum:

PR list default repo
issue list default repo
release list default repo
CI default repo/revision
PR create default head=
PR create default base=
browse default target

4. Initial default recommendations

Recommended initial policy:

collaboration repo = configured default, else upstream, else origin
pr list / issue list / release list default to collaboration repo
ci list defaults to current branch revision with configurable repo policy
pr create head defaults to current branch in the current push context
pr create base defaults to collaboration repo default branch

5. Clear override model

Defaults are policy only. Any explicit address (repo=..., target=..., head=..., base=...) must override default policy cleanly.

Acceptance criteria

alias resolution order is defined and documented
alias config exists or is precisely specified
default target policy is defined per command family
fork/upstream defaults are decided explicitly rather than implicitly through origin
tests cover alias resolution and omitted-target defaults
docs explain defaults separately from explicit overrides

Alternatives considered

Leave defaults implicit and continue deriving them ad hoc from the current checkout. This preserves ambiguity and makes explicit targeting feel bolted on.
Hard-code upstream-first behavior without config. This is simple, but too rigid for users with different remote layouts or self-hosted forges.

## Prerequisites - [x] I have searched existing issues. ## Problem Issue #142 defines a canonical Ex-style `:Forge` command language, and #144 defines explicit repo/revision/location target parsing. But parsing explicit targets is only half of the problem. Forge still needs a canonical policy for what happens when users do **not** specify a target. This is where the real fork/upstream behavior is decided: - what `repo=upstream` means - whether aliases resolve before git remotes - what the default collaboration repo is - what `ci list` should target by default - what `pr create` should use for default `head=` and `base=` - how users configure aliases and target defaults Without an explicit defaults/alias policy, the new CLI will still feel ambiguous even if the syntax is better. ## Proposed solution Define a dedicated target resolution policy for the new `:Forge` command language. ### 1. Alias resolution order Resolve `repo=` and repo-bearing targets in this order: 1. configured alias 2. git remote name 3. explicit hosted repo path This should be documented and tested. ### 2. Configurable aliases Add user config for explicit target aliases. Example shape: ```lua vim.g.forge = { targets = { aliases = { upstream = 'remote:upstream', origin = 'remote:origin', work = 'github.com/barrettruth/forge.nvim', }, }, } ``` The exact config shape can change, but the concept should be explicit and documented. ### 3. Explicit default policies Define and document default target policy per command family. At minimum: - PR list default repo - issue list default repo - release list default repo - CI default repo/revision - PR create default `head=` - PR create default `base=` - browse default target ### 4. Initial default recommendations Recommended initial policy: - collaboration repo = configured default, else `upstream`, else `origin` - `pr list` / `issue list` / `release list` default to collaboration repo - `ci list` defaults to current branch revision with configurable repo policy - `pr create head` defaults to current branch in the current push context - `pr create base` defaults to collaboration repo default branch ### 5. Clear override model Defaults are policy only. Any explicit address (`repo=...`, `target=...`, `head=...`, `base=...`) must override default policy cleanly. ### Acceptance criteria - [ ] alias resolution order is defined and documented - [ ] alias config exists or is precisely specified - [ ] default target policy is defined per command family - [ ] fork/upstream defaults are decided explicitly rather than implicitly through `origin` - [ ] tests cover alias resolution and omitted-target defaults - [ ] docs explain defaults separately from explicit overrides ## Alternatives considered - Leave defaults implicit and continue deriving them ad hoc from the current checkout. This preserves ambiguity and makes explicit targeting feel bolted on. - Hard-code `upstream`-first behavior without config. This is simple, but too rigid for users with different remote layouts or self-hosted forges.

barrettruth commented

2026-04-11 20:54:36 +00:00

Implemented in #151.