Class GitSource

java.lang.Object
network.ike.docs.plugin.diff.GitSource
All Implemented Interfaces:
AutoCloseable
public final class GitSource extends Object implements AutoCloseable
Read-only access to both sides of a doc-diff comparison (ike-issues#649): any two commits, or a commit and the working tree.

The to side accepts the pseudo-ref WORKTREE, meaning the uncommitted working tree — the default review case. Rename detection is on, so a moved fragment is compared across the move rather than reported as delete-plus-add.

All paths are repository-relative with forward slashes, as JGit reports them.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static final record 
    GitSource.Change
    One changed file between the two sides.
    static final record 
    GitSource.CommitMeta
    Metadata of one commit in a compared range, for change-entity derivation from trailers (ike-issues#652) and stamp endnotes (ike-issues#656).

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    UNCOMMITTED
    Attribution value for working-tree lines not yet committed.
    static final String
    WORKTREE
    Pseudo-ref naming the uncommitted working tree as a side.

  • Method Summary

    Modifier and Type
    Method
    Description
    List<String>
    blameInRange(String toRef, String path, Set<String> rangeCommitIds)
    Attribute each line of a file's to-side text to the range commit that introduced it (ike-issues#656).
    String
    branch()
    The current branch name — the git-era analogue of the STAMP path coordinate.
    List<GitSource.Change>
    changes(String fromRef, String toRef, String pathPrefix, String suffix)
    List the files that differ between the two sides, with rename detection, filtered to a path prefix and suffix.
    void
    close()
     
    List<GitSource.CommitMeta>
    commitsBetween(String fromRef, String toRef)
    Walk the commits reachable from toRef and not from fromRef (i.e.
    String
    findPath(String ref, String suffix)
    Find the first path on a side that ends with the given suffix — used to discover the topic-registry source root from an assembly module (ike-issues#649 subproject scoping).
    List<String>
    listYaml(String ref, String dir)
    List the immediate .yaml children of a directory on a side — used to enumerate per-domain registry files on both sides of the comparison.
    static GitSource
    open(Path within)
    Open the repository that contains the given directory, walking upward to find the git dir (a module's basedir is typically below the repository root).
    String
    read(String ref, String path)
    Read one file's text from a side.
    String
    userName()
    The configured user name, used as the author of uncommitted (working-tree) stamps.
    Path
    workTree()
    The repository's working-tree root.

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • WORKTREE

      public static final String WORKTREE
      Pseudo-ref naming the uncommitted working tree as a side.
      See Also:

    • UNCOMMITTED

      public static final String UNCOMMITTED
      Attribution value for working-tree lines not yet committed.
      See Also:

  • Method Details

    • open

      public static GitSource open(Path within) throws IOException
      Open the repository that contains the given directory, walking upward to find the git dir (a module's basedir is typically below the repository root).
      Parameters:
      within - a directory inside the repository
      Returns:
      an open source; close it when done
      Throws:
      IOException - when no repository contains the directory

    • workTree

      public Path workTree()
      The repository's working-tree root.
      Returns:
      the working-tree root path

    • changes

      public List<GitSource.Change> changes(String fromRef, String toRef, String pathPrefix, String suffix) throws IOException
      List the files that differ between the two sides, with rename detection, filtered to a path prefix and suffix.
      Parameters:
      fromRef - the from-side ref (any committish)
      toRef - the to-side ref, or WORKTREE
      pathPrefix - repository-relative prefix filter (may be empty)
      suffix - file-name suffix filter, e.g. .adoc (may be empty)
      Returns:
      the matching changes in path order
      Throws:
      IOException - on repository access failure

    • read

      public String read(String ref, String path) throws IOException
      Read one file's text from a side.
      Parameters:
      ref - a committish, or WORKTREE
      path - the repository-relative path
      Returns:
      the file text, or null when absent on that side
      Throws:
      IOException - on repository access failure

    • listYaml

      public List<String> listYaml(String ref, String dir) throws IOException
      List the immediate .yaml children of a directory on a side — used to enumerate per-domain registry files on both sides of the comparison.
      Parameters:
      ref - a committish, or WORKTREE
      dir - the repository-relative directory
      Returns:
      the repository-relative file paths found
      Throws:
      IOException - on repository access failure

    • findPath

      public String findPath(String ref, String suffix) throws IOException
      Find the first path on a side that ends with the given suffix — used to discover the topic-registry source root from an assembly module (ike-issues#649 subproject scoping).
      Parameters:
      ref - a committish, or WORKTREE
      suffix - the path suffix to match, e.g. src/docs/asciidoc/topic-registry.yaml
      Returns:
      the first matching repository-relative path in walk order, or null when none matches
      Throws:
      IOException - on repository access failure

    • branch

      public String branch() throws IOException
      The current branch name — the git-era analogue of the STAMP path coordinate.
      Returns:
      the branch name, or the abbreviated detached-head id
      Throws:
      IOException - on repository access failure

    • userName

      public String userName()
      The configured user name, used as the author of uncommitted (working-tree) stamps.
      Returns:
      the configured user.name, or "(local)"

    • blameInRange

      public List<String> blameInRange(String toRef, String path, Set<String> rangeCommitIds) throws IOException
      Attribute each line of a file's to-side text to the range commit that introduced it (ike-issues#656). Lines introduced before fromRef map to null (unmarked context never asks for a stamp); working-tree lines not yet committed map to UNCOMMITTED.
      Parameters:
      toRef - the to side (WORKTREE or committish)
      path - the repository-relative file path
      rangeCommitIds - abbreviated ids of the commits in range
      Returns:
      one attribution per to-side line: an abbreviated commit id, UNCOMMITTED, or null
      Throws:
      IOException - on repository access failure

    • commitsBetween

      public List<GitSource.CommitMeta> commitsBetween(String fromRef, String toRef) throws IOException
      Walk the commits reachable from toRef and not from fromRef (i.e. fromRef..toRef), oldest first, with each commit's touched files.
      Parameters:
      fromRef - the exclusive lower bound (committish)
      toRef - the inclusive upper bound (committish; not WORKTREE)
      Returns:
      commit metadata, oldest first
      Throws:
      IOException - on repository access failure

    • close

      public void close()
      Specified by:
      close in interface AutoCloseable