Skip to content

Clarify zero-argument repository inference from local Git remotes #2

@shbernal

Description

@shbernal

Context

It would be convenient if running gitpulse with no positional repository
argument inside a local Git checkout could run the normal repository report for
that checkout's GitHub repository.

This is not the same as adding remote search to the root command. The candidate
repository would come from local Git remote configuration, so the behavior can
remain deterministic and local-first.

Decisions to clarify first

Before implementing this, we should explicitly decide the precedence and failure
behavior:

  • Which remotes should be considered?
  • Should origin always win when it points to GitHub?
  • Should upstream ever win over origin, or only be used when origin is not
    a GitHub remote?
  • How should a remote named fork be treated?
  • If there is no origin or upstream, but exactly one GitHub remote exists,
    should Gitpulse use it or fail?
  • If multiple GitHub remotes exist and none has a preferred name, should
    Gitpulse fail with an ambiguity message?
  • Outside a Git checkout, or inside a checkout with no GitHub remote, should
    bare gitpulse keep showing help or print a specific inference failure?

The fork workflow makes this especially important. Some users name their
personal fork origin and the canonical repository upstream; others name the
canonical repository origin and their personal fork fork. For example:

fork   https://github.com/shbernal/yay.git
origin https://github.com/Jguer/yay.git

In that setup, reporting origin is the desired behavior because it represents
the canonical project being evaluated, while fork is only the user's writable
remote.

Tentative direction

A conservative first pass could be:

  1. Only apply this behavior when the root command receives zero repository
    arguments.
  2. Inspect local Git remotes only; do not call GitHub to discover fork parents
    or search repositories.
  3. Prefer a GitHub origin remote.
  4. Otherwise prefer a GitHub upstream remote.
  5. Otherwise use the only GitHub remote if there is exactly one.
  6. Otherwise fail with a clear ambiguity message listing the GitHub remotes and
    asking the user to pass owner/name.
  7. Route the inferred owner/name through the normal single-repository report
    path, preserving existing cache, JSON, refresh, offline, and history behavior.

This needs a short product/spec update before implementation so the root command
contract stays clear and does not weaken the local-only deterministic shorthand
boundary.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions