Bluestep JS Documentation
    Preparing search index...

    Class GitRepo

    A mounted git repository, pinned to one commit. Returned by B.git.repo.open(spec) and B.git.repo.from(source); the same handle can be mounted on an agent via B.ai.agent({repos: [...]}).

    Index
    alias diff grep log ls read ref sha show
    constructor

    • The name the model sees for this mount, or null when the spec named none. A repo without one can be read by the script but is refused by B.ai.agent(...).addRepo — the model cannot address a mount it has no name for.

      Returns string

    • Unified diff between two commits in this mount's history.

      Both ends must be reachable from the pinned commit; anything else is refused. The path, given or not, is narrowed by the mount's prefix — omitting it means the prefix, never the whole repository.

      Parameters

      • base: string

        The older end — a sha from log(), a branch, or a tag.

      • Optionaloptions: { head?: string; path?: string }

        head is the newer end (the pinned commit when omitted); path narrows the diff.

      Returns { diff: string; truncated: boolean }

    • Search file contents at the pinned commit.

      Returns {hits, shown, matchedSoFar, truncated, skippedNonText, treeTruncated}. skippedNonText is not a diagnostic: a search over many files cannot usefully fail because one of them is an image, so files that are not text are skipped — which means "no matches" and "no matches among the files I could read" are different answers, and the count is what tells them apart.

      Parameters

      • pattern: string

        A Java regular expression. Backreferences, lookaround, inline flags, and repeating a group that itself repeats or alternates are refused.

      • Optionaloptions: {
            contextLines?: number;
            glob?: string;
            ignoreCase?: boolean;
            maxMatches?: number;
            path?: string;
        }

        Restrict, filter, and cap the search. A bare glob matches at every depth.

      Returns {
          hits: {
              after: string[];
              before: string[];
              line: number;
              path: string;
              text: string;
          }[];
          matchedSoFar: number;
          shown: number;
          skippedNonText: number;
          treeTruncated: boolean;
          truncated: boolean;
      }

    • Commit history, newest first, ending at the pinned commit.

      There is no ref argument, and that is the enforcement rather than an omission: history always walks back from the pin, so this operation cannot leave the mount. A mount with no history — a snapshot of live content — refuses this outright.

      author and at are each absent where the forge reported none, rather than carrying a placeholder this surface invented. A commit made from an email address the forge holds no account for has no author name to give.

      Parameters

      • Optionaloptions: { limit?: number; path?: string }

        path restricts to commits touching a path; limit caps the commit count.

      Returns {
          commits: { at?: string; author?: string; sha: string; subject: string }[];
          truncated: boolean;
      }

    • List files at the pinned commit.

      Returns {entries: {path, size?, kind}[], shown, totalMatched, truncated, treeTruncated}. The two truncation flags say different things: truncated means this call clipped its own answer at the limit, and treeTruncated means the forge reported only part of the tree, so the answer was computed over a partial world.

      size is absent — not zero — on an entry whose forge does not report one; at least one dialect's tree listing carries no byte length. Test it with entry.size === undefined before doing arithmetic on it.

      Parameters

      • Optionaloptions: { glob?: string; limit?: number; path?: string }

        path restricts to a directory prefix (the mount root when omitted), glob filters (a bare glob matches at every depth: *.md matches README.md and docs/notes.md), limit caps the entry count.

      Returns {
          entries: { kind: string; path: string; size?: number }[];
          shown: number;
          totalMatched: number;
          treeTruncated: boolean;
          truncated: boolean;
      }

    • Read a file at the pinned commit, line-windowed.

      Decoding is strict: a file holding a NUL byte or any invalid UTF-8 sequence is refused rather than decoded with replacement characters, because replacement characters are silent corruption dressed as success. A symlink or submodule entry is refused too, naming what it is, rather than returning the link target as though it were file content.

      Parameters

      • path: string

        Repo-relative path, within this mount's prefix.

      • Optionaloptions: { limit?: number; offset?: number }

        offset is the first line, 1-based; limit caps the line count.

      Returns {
          firstLine: number;
          lineCount: number;
          linesSoFar: number;
          text: string;
          truncated: boolean;
      }

    • The ref as it was written when this repository was mounted — a branch, a tag, or a sha. sha() is what it resolved to.

      Returns string

    • The commit this repository is pinned to. Record it alongside any result computed from this mount: it is what makes that result reproducible.

      Returns string

    • Read a file as it existed at an earlier commit in this mount's history. The commit must be reachable from the pinned commit. Same result shape as read.

      Parameters

      • sha: string

        A commit sha from log(), or a ref that resolves to one.

      • path: string

        Repo-relative path, within this mount's prefix.

      • Optionaloptions: { limit?: number; offset?: number }

        offset is the first line, 1-based; limit caps the line count.

      Returns {
          firstLine: number;
          lineCount: number;
          linesSoFar: number;
          text: string;
          truncated: boolean;
      }

    Settings
    Member Visibility

    On This Page
    experimental
    Other