hg4j User Manual

dependencies {
    implementation 'io.github.search5.hg4j:hg4j:1.0.1'
}

        HgRepository repository = Hg.init()
                .setDirectory(new File("/path/to/repo"))
                .call();

        HgRepository repository = Hg.cloneRepository()
                .setSource("https://example.com/hg/some-project")
                .setDirectory(new File("/path/to/local-clone"))
                .call();

        try (Hg hg = Hg.open("/path/to/repo")) {
            HgRepository repository = hg.getRepository();
            // ... run commands via hg.xxx().call() ...
        }

        try (Hg hg = Hg.wrap(repository)) {
            // ... run commands via hg.xxx().call() ...
        }

            hg.add()
                    .addFile("README.md")
                    .addFile("src/main/java/App.java")
                    .call();

            Status status = hg.status().call();
            status.getAdded();      // newly tracked, not yet committed
            status.getModified();   // tracked and changed since the last commit
            status.getRemoved();    // tracked but deleted (hg remove/rm)
            status.getUntracked();  // present on disk but not tracked at all

            byte[] newNodeId = hg.commit()
                    .setMessage("Add initial application skeleton")
                    .setAuthor("Jane Doe <jane@example.com>")
                    .call();

            List<HgCommit> history = hg.log().call();
            for (HgCommit commit : history) {
                System.out.printf("%s %s %s%n",
                        commit.getNodeId().toHex().substring(0, 12),
                        commit.getAuthor(),
                        commit.getMessage());
            }

            // With no revisions set, diffs the tip against its parent.
            List<DiffEntry> changes = hg.diff().call();
            for (DiffEntry entry : changes) {
                System.out.println(entry.getPath() + " (" + entry.getChangeType() + ")");
                System.out.println(entry.getDiffContent());
            }

            // Marks the working copy so the NEXT commit records this branch name.
            hg.branch().setBranchName("feature/payments").call();
            // With no argument, reports the working copy's current branch instead.
            String currentBranch = hg.branch().call();

            // Creates (or moves) a bookmark to point at the working copy's current parent.
            hg.bookmark().setBookmarkName("release-1.0").call();

            // Lists every bookmark as a name -> hex-node-id map.
            hg.bookmark().call().forEach((name, nodeHex) ->
                    System.out.println(name + " -> " + nodeHex));

            // Deletes a bookmark.
            hg.bookmark().setBookmarkName("release-1.0").setDelete(true).call();

            // setRevision() accepts "tip", a revision number, a hex node id (or unambiguous
            // prefix), or a named branch name -- NOT a bookmark name, so a bookmark must be
            // resolved to its node id first.
            hg.update().setRevision("feature/payments").call();

            String bookmarkNodeHex = hg.bookmark().call().get("release-1.0");
            hg.update().setRevision(bookmarkNodeHex).call();

            // One entry per named branch's head -- closed branches are excluded by default.
            List<BranchHead> heads = hg.branches().call();
            for (BranchHead head : heads) {
                System.out.printf("%s %d:%s%n", head.getBranch(), head.getRev(), head.isActive());
            }

            // Include closed branches too.
            List<BranchHead> allHeads = hg.branches().setIncludeClosed(true).call();

            List<String> headHexes = hg.heads().call();
            // Merge some other head into the working copy's current parent.
            byte[] otherHead = NodeId.fromHex(headHexes.get(1)).getBytes();
            MergeResult result = hg.merge().setNodeId(otherHead).call();

            if (result.isConflicted()) {
                for (String conflictedPath : result.getConflicts()) {
                    // Each conflicted file already has <<<<<<< / ======= / >>>>>>> markers
                    // written to disk -- resolve them, then commit like a normal merge commit.
                    System.out.println("Unresolved: " + conflictedPath);
                }
            } else {
                hg.commit().setMessage("Merge").call();
            }

            List<String> headHexes = hg.heads().call();
            byte[] source = NodeId.fromHex(headHexes.get(0)).getBytes();
            byte[] target = NodeId.fromHex(headHexes.get(1)).getBytes();

            // Cherry-picks `source` (and its descendants) onto `target`. The original revisions
            // stay readable via `hg log --hidden`; only an obsolescence marker records that
            // they were superseded -- nothing is physically stripped.
            hg.rebase().setSource(source).setTarget(target).call();

            String result = hg.push()
                    .setDestination("https://example.com/hg/some-project")
                    .call();
            System.out.println(result);

            // Pulls new changesets from the remote into the local repository, WITHOUT touching
            // the working copy -- follow with hg.update() to actually check out the new tip.
            List<byte[]> importedNodeIds = hg.pull()
                    .setSource("https://example.com/hg/some-project")
                    .call();

            // Like pull(), but also synchronizes bookmarks and phases atomically with the
            // remote. Neither pull() nor fetch() touches the working copy -- both still need a
            // separate hg.update() call to check the new tip out.
            List<byte[]> importedNodeIds = hg.fetch()
                    .setSource("https://example.com/hg/some-project")
                    .call();

            // The [paths] aliases (e.g. "default", "default-push") from .hg/hgrc, alphabetically
            // ordered by alias name. Empty if the repository has no [paths] section configured.
            Map<String, String> paths = hg.paths().call();
            String defaultUrl = paths.get("default");

            // Untracks the file AND deletes it from disk (matching plain `hg remove`).
            hg.remove().setFile("obsolete/OldService.java").call();

            // Restores a file's working-copy content back to the current parent revision. A
            // dirty file gets its pre-revert bytes backed up to "<file>.orig" first.
            hg.revert().setFile("src/main/java/App.java").call();

            // Or revert to a specific historical revision instead of the current parent.
            hg.revert().setFile("src/main/java/App.java").setRevision("42").call();

            // Creates a tag pointing at the working copy's current parent and commits the
            // updated .hgtags file (like plain `hg tag`).
            hg.tag().setTagName("v1.0.0").call();

            // A local tag is written to .hg/localtags instead, and is never committed.
            hg.tag().setTagName("wip-checkpoint").setLocal(true).call();

            List<Tag> tags = hg.tags().call();
            for (Tag t : tags) {
                System.out.printf("%-20s %5d:%s%n", t.getName(), t.getRev(), t.isLocal());
            }

            try {
                hg.commit().setMessage("Automated checkpoint").call();
            } catch (HgLockException e) {
                // Another process (or another Hg instance) currently holds .hg/wlock or
                // .hg/store/lock -- retry after a delay, or surface it to the caller as
                // "repository is locked by another process".
                System.err.println("Repository busy, try again later: " + e.getMessage());
            }

            try {
                hg.graft().setSource("42").call();
            } catch (HgMergeConflictException e) {
                // The graft/rebase/backout is paused; the conflicting files already have
                // <<<<<<< / ======= / >>>>>>> markers written to disk. Resolve them by hand
                // (or via ResolveCommand), then call the same command's continue-style method.
                for (String conflictedPath : e.getConflictPaths()) {
                    System.err.println("Unresolved: " + conflictedPath);
                }
            }

            String rootPath = hg.root().call();
            System.out.println("Repository root: " + rootPath);

            byte[] tipNode = hg.tip().call();
            int tipRevisionNumber = hg.tip().getRevisionNumber();
            if (tipNode != null) {
                System.out.println("Tip revision: " + tipRevisionNumber);
            }

            // One entry in the common case, two while an uncommitted merge is in progress,
            // and zero only for a brand-new empty repository.
            List<String> parentHexes = hg.parents().call();
            for (String hex : parentHexes) {
                System.out.println("Parent: " + hex);
            }

            SummaryInfo summary = hg.summary().call();
            for (ParentInfo parent : summary.parents()) {
                System.out.println("parent: " + parent.node() + " " + parent.description());
            }
            System.out.println("branch: " + summary.branch());
            System.out.println("bookmark: " + summary.activeBookmark());
            System.out.println("phase: " + summary.currentPhase());
            if (summary.mergeInProgress()) {
                System.out.println("An uncommitted merge is in progress.");
            }

            // Working copy's own parent(s): a trailing "+" marks a dirty working copy.
            String workingCopyIdentity = hg.identify().call();
            System.out.println(workingCopyIdentity);

            // A fixed revision instead: no dirty marker is ever appended here.
            String tipIdentity = hg.identify().setRevision("tip").call();
            System.out.println(tipIdentity);

            // Plain hg heads: every named branch's own open head(s).
            List<String> heads = hg.heads().call();

            // hg heads --topo: pure repo-wide topological leaves, ignoring branches.
            List<String> topoHeads = hg.heads().setTopo(true).call();

            // hg heads <branch>: only that branch's own heads.
            List<String> featureHeads = hg.heads().setBranch("feature").call();

            // "<tag>-<distance>-g<shortnode>" relative to the nearest ancestral tag,
            // or just "<tag>" when the working copy's parent IS a tagged revision.
            String description = hg.describe().call();
            System.out.println(description);

            List<BlameLine> lines = hg.annotate()
                    .setPath("src/main/java/App.java")
                    .call();
            for (BlameLine line : lines) {
                System.out.printf("%4d rev %-4d %-20s %s%n",
                        line.getLineNumber(), line.getRevision(), line.getAuthor(), line.getContent());
            }

            byte[] content = hg.cat()
                    .setFile("README.md")
                    .setRevision("tip")
                    .call();
            System.out.println(new String(content, java.nio.charset.StandardCharsets.UTF_8));

            // With no revision set, this reflects the working copy's dirstate (added-but-
            // uncommitted files included, removed-but-uncommitted files excluded).
            List<String> trackedFiles = hg.files().call();

            // Restrict to files matching a glob pattern.
            List<String> javaFiles = hg.files().setPattern("src/main/java/**/*.java").call();

            // Unlike files(), locate() searches the dirstate directly and still reports
            // files marked removed (hg rm'd) but not yet committed.
            List<String> matches = hg.locate().setPattern("*.md").call();

            // With no revision set, this lists the working directory's first parent.
            List<ManifestEntry> entries = hg.manifest().setRevision("tip").call();
            for (ManifestEntry entry : entries) {
                System.out.println(entry.getPath() + " " + entry.getNodeHex()
                        + (entry.isExecutable() ? " (executable)" : "")
                        + (entry.isSymlink() ? " (symlink)" : ""));
            }

            // With no revision set, tree() defaults to the tip.
            List<TreeEntry> entries = hg.tree().call();
            for (TreeEntry entry : entries) {
                System.out.printf("%06o %s %s%n", entry.getMode(), entry.getNodeId(), entry.getPath());
            }

            // Searches every historical revision of every tracked filelog, not just the
            // working copy or tip.
            List<GrepResult> matches = hg.grep()
                    .setQuery("TODO")
                    .setCaseInsensitive(true)
                    .call();
            for (GrepResult match : matches) {
                System.out.printf("%s:%d [%s] %s%n",
                        match.path, match.lineNumber, match.hexNode.substring(0, 12), match.lineContent);
            }

            List<String> allRevisions = hg.revset().setExpression("all()").call();
            List<String> tipParents = hg.revset().setExpression("parents(tip)").call();

            // 0 = public, 1 = draft, 2 = secret.
            int phase = hg.phase().setRevision("tip").call();

            // Moving towards public (a lower number) is unconditional; moving towards
            // secret (a higher number) requires setForce(true), like real hg's --force gate.
            int newPhase = hg.phase().setRevision("tip").setPhase(0).call();

            // Duplicates a tracked file: the source is left untouched and still tracked, and the
            // destination is added as a new file with copy-source metadata recorded in the
            // dirstate, so `hg log --follow`/`hg annotate` on the destination follows through to
            // the source's own history.
            hg.copy().setSource("src/main/resources/app.properties")
                    .setDestination("src/main/resources/app-staging.properties")
                    .call();

            // Refused by default if the destination already exists on disk; setForce(true)
            // overwrites it, mirroring `hg copy --force`.
            hg.copy().setSource("src/main/resources/app.properties")
                    .setDestination("src/main/resources/app-staging.properties")
                    .setForce(true)
                    .call();

            // Moves a tracked file on disk, marks the old path removed, and records the new path
            // as a copy-of-the-old-path in the dirstate copyMap -- equivalent to plain `hg rename`
            // (`hg mv`), which is itself just `hg copy` + `hg remove` in one step.
            hg.rename().setSource("src/main/java/App.java")
                    .setTarget("src/main/java/Application.java")
                    .call();

            // Scans the working copy in one pass: every untracked file is added, and every
            // tracked file that is missing on disk is marked removed. Returns status-style lines
            // ("A path" / "R path") describing exactly what changed.
            List<String> affected = hg.addremove().call();
            for (String line : affected) {
                System.out.println(line);
            }

            // Stops tracking a file WITHOUT touching it on disk -- the opposite of remove(), which
            // both untracks and deletes. A file that was never committed is simply dropped from
            // the dirstate; an already-committed file is instead recorded as removed at the next
            // commit, while the working copy keeps its content untouched.
            hg.forget().setFile("secrets/local-only.env").call();

            // Deletes every untracked, non-ignored file plus the empty directories left behind --
            // matching plain `hg purge`'s own default scope. Ignored files (matched by
            // .hgignore) are NEVER touched, and a declared subrepo's own working copy is treated
            // as an opaque boundary and never walked into.
            hg.purge().call();

            // setPurgeDirectories(false) restricts the sweep to files only, leaving any leftover
            // empty untracked directories in place.
            hg.purge().setPurgeDirectories(false).call();

            // Compacts and re-deltas every revlog in the store, rebuilds fncache, and removes
            // orphaned temp/backup files -- a housekeeping pass with no equivalent single stock
            // `hg` command, closer to `hg debugupgraderepo`/manual store maintenance in spirit.
            String summary = hg.gc().call();
            System.out.println(summary);

            // Saves every modified/added/removed working-copy file under the given name, then
            // reverts the working copy back to its parent commit -- a clean slate to switch tasks
            // on. A plain call() with no setName() shelves under the name "default".
            hg.shelve().setName("wip-feature").call();

            try {
                // Restores a previously shelved set of changes as pending, uncommitted edits.
                // Internally this replays the shelve as a throwaway commit and rebases it onto
                // whatever the working copy's parent has become in the meantime (a no-op if
                // nothing has landed there since the shelve was taken); every trace of that
                // throwaway commit is erased once the restore succeeds.
                hg.shelve().setName("wip-feature").setUnshelve(true).call();
            } catch (HgMergeConflictException e) {
                // Paused exactly like `hg rebase` on a real conflict: resolve the reported files
                // (see resolveConflicts() below), then continue or abandon the attempt. A fresh
                // ShelveCommand instance is fine for either call -- both are driven purely by
                // persisted on-disk state, not by anything held in this object.
                hg.shelve().unshelveContinue();
                // Or, to give up and restore the pre-unshelve state while keeping the shelve
                // itself intact for a later attempt:
                // hg.shelve().unshelveAbort();
            }

            // Creates a second working copy backed by the SAME shared store as this repository
            // (Mercurial's `hg share`, exposed here under a more Git-familiar name) -- commits
            // made from either working copy are immediately visible to the other, since there is
            // only one store underneath. The target directory must be empty or not yet exist.
            HgRepository worktreeRepo = hg.worktree()
                    .setNewWorktreeDir(new File("/path/to/repo-worktree-hotfix"))
                    .call();

            // After a merge()/graft()/rebase()/backout() leaves conflict markers on disk (see
            // the error-handling and merging chapters), list() reports every file's resolution
            // state without changing anything.
            Map<String, Boolean> states = hg.resolve().list(true).call();
            for (Map.Entry<String, Boolean> entry : states.entrySet()) {
                if (!entry.getValue()) {
                    System.out.println("Still unresolved: " + entry.getKey());
                }
            }

            // Once a conflicting file's content has been hand-edited (or overwritten by some
            // other tool) to remove its <<<<<<< / ======= / >>>>>>> markers, mark it resolved so
            // the merge/rebase/graft can be committed or continued.
            hg.resolve().setFile("src/main/java/Config.java").markResolved(true).call();

            // Replaces the tip commit with a new one on the SAME parent(s) (a sibling, not a
            // child) -- anything not explicitly overridden here (author, close-branch state)
            // is copied from the amended-away commit itself.
            byte[] amendedNode = hg.amend().setMessage("Fixed typo in commit message").call();

            // Rules are replayed in order, OLDEST revision first -- like an interactive rebase
            // "todo list". Here two adjacent commits are squashed into one (their file changes
            // are combined and their commit messages concatenated), and the newest commit is
            // recommitted as-is right after.
            String oldestOfRange = "aaaa1111aaaa1111aaaa1111aaaa1111aaaa1111";
            String middleCommit = "bbbb2222bbbb2222bbbb2222bbbb2222bbbb2222";
            String newestCommit = "cccc3333cccc3333cccc3333cccc3333cccc3333";

            hg.histedit()
                    .addRule(HisteditCommand.Action.PICK, oldestOfRange)
                    .addRule(HisteditCommand.Action.FOLD, middleCommit)
                    .addRule(HisteditCommand.Action.PICK, newestCommit)
                    .call();

            // Copies revision "42"'s changes onto the working copy's current parent, as a
            // brand-new commit. Unlike amend()/histedit(), graft() writes no obsolescence
            // marker -- the source revision stays fully visible in a plain `hg log` afterward.
            String graftedHex = hg.graft().setSource("42").call();
            System.out.println("Grafted as: " + graftedHex);

            // After resolving every conflicted path reported by the HgMergeConflictException
            // (see the error-handling chapter) and re-staging the resolved content on disk,
            // finish the paused commit:
            String graftedHex = hg.graft().continueGraft();
            System.out.println("Grafted as: " + graftedHex);

            // Or, to give up on the paused graft entirely and restore the pre-graft working copy:
            // hg.graft().abort();

            // Creates a brand-new commit that reverses revision 17's changes -- history itself
            // is untouched (no obsolescence marker, no strip). Backing out the working copy's
            // own parent (the common case) can never conflict; backing out an older ancestor
            // performs a genuine 3-way merge and can throw HgMergeConflictException just like
            // graft/rebase (see the error-handling chapter) -- but unlike those commands there
            // is no backout --continue: resolve the conflicted files by hand, then just commit
            // normally.
            byte[] backoutNode = hg.backout().setRevision("17").setMessage("Revert regression from rev 17").call();

            List<String> headHexes = hg.heads().call();
            byte[] ours = NodeId.fromHex(headHexes.get(0)).getBytes();
            byte[] theirs = NodeId.fromHex(headHexes.get(1)).getBytes();

            // Computes the merge purely from the changelog/manifest/filelog store -- the
            // working directory and dirstate are never touched.
            TreeMergeCommand.TreeMergeResult result = hg.treeMerge().setOurs(ours).setTheirs(theirs).call();

            if (result.isConflicted()) {
                for (String conflictedPath : result.getConflicts()) {
                    System.out.println("Would conflict: " + conflictedPath);
                }
            } else {
                // Writes the result directly as a new two-parent changeset -- again without
                // ever checking anything out. Bookmarks are not moved automatically; use
                // bookmark() afterward if the merge should advance one.
                byte[] mergeCommitNode = hg.mergeCommit()
                        .setParents(ours, theirs)
                        .setTreeMergeResult(result)
                        .setMessage("Merge (server-side, no checkout)")
                        .call();
            }

            // Physically truncates revision 23 and every descendant out of the changelog/
            // manifest/filelog revlogs. Unlike rebase()/histedit() (which only ever record an
            // obsolescence marker, leaving the originals visible via `hg log --hidden`), a
            // stripped revision is gone from the store entirely and cannot be recovered through
            // this library. A successful strip also invalidates any pending rollback() -- see
            // below.
            hg.strip().setRevision("23").call();

            // A plain method, NOT a builder -- there is no rollback().call(). Undoes only the
            // MOST RECENT commit or pull, using the undo.* files that transaction left behind;
            // a second commit (or a strip()) overwrites/erases that undo information, after
            // which rollback() throws IllegalStateException ("no rollback information
            // available") instead of reaching further back.
            hg.rollback();

            // censor() targets one exact FILE revision, identified by its own filelog node hex
            // -- not the changeset's commit hash. Resolve it via manifest() at the offending
            // changeset first.
            List<ManifestCommand.ManifestEntry> entries = hg.manifest().setRevision("55").call();
            String fileNodeHex = entries.stream()
                    .filter(e -> e.getPath().equals("config/secrets.properties"))
                    .findFirst()
                    .orElseThrow()
                    .getNodeHex();

            // Scrubs just that one revision's content (replacing it with a tombstone) while
            // keeping its node identity, parents, and linkrev intact -- history shape is
            // unaffected, and other revisions of the same file are untouched. Refuses (unless
            // setCheckHeads(false)) if this exact content is still live at a head or a
            // working-directory parent.
            hg.censor()
                    .setFile("config/secrets.properties")
                    .setRevision(fileNodeHex)
                    .setTombstone("removed leaked credentials")
                    .call();

            // A known-good revision (here, simply the oldest commit -- in practice this would
            // usually be a known-good tag or release) and a known-bad one (the current tip,
            // where the regression is visible).
            List<HgCommit> history = hg.log().call(); // newest first
            byte[] goodNode = history.get(history.size() - 1).getNodeId().getBytes();
            byte[] badNode = history.get(0).getNodeId().getBytes();

            // next() picks the revision that best splits the good..bad range in half, AND
            // checks it out into the working directory -- there is no separate update() call
            // needed before building/testing it.
            byte[] candidate = hg.bisect()
                    .setGood(goodNode)
                    .setBad(badNode)
                    .next();
            System.out.println("Now build/test the working copy, then mark it good or bad.");

            List<HgCommit> history = hg.log().call();
            HgCommit goodCommit = history.get(history.size() - 1);
            HgCommit badCommit = history.get(0);

            byte[] good = goodCommit.getNodeId().getBytes();
            byte[] bad = badCommit.getNodeId().getBytes();
            int goodRev = goodCommit.getRevision();
            int badRev = badCommit.getRevision();

            // BisectCommand keeps no state of its own on disk (unlike real hg's
            // ".hg/bisect.state") -- every next() call is a fresh good/bad split computed from
            // whatever nodes you pass it, so the CALLER tracks the current good/bad range across
            // iterations, exactly as this loop does. Bisection is done once good and bad become
            // adjacent revisions: at that point "bad" itself is the culprit.
            while (badRev - goodRev > 1) {
                byte[] candidate = hg.bisect().setGood(good).setBad(bad).next();
                int candidateRev = findRevisionNumber(history, candidate);

                boolean isGood = testCurrentCheckout(); // e.g. run the project's test suite
                if (isGood) {
                    good = candidate;
                    goodRev = candidateRev;
                } else {
                    bad = candidate;
                    badRev = candidateRev;
                }
            }
            System.out.println("First bad revision: " + badRev);

            // Produces a classic (non---git) unified-diff patch with "# HG changeset patch"
            // headers, matching hg export's default output format -- a plain text FILE you could
            // email or store next to the repo, not a binary changegroup (see bundle() below for
            // that).
            String patchText = hg.export().setRevision("tip").call();
            Files.writeString(Path.of("/tmp/my-change.patch"), patchText);

            // Applies a unified-diff patch (as produced by export()/hg export/hg diff) to the
            // working directory and commits it on top of the CURRENT dirstate parent -- like real
            // "hg import" without --exact, the patch's own "# Node ID"/"# Parent" headers are
            // read for author/date only, never used to pick where the patch is applied.
            String patchText = Files.readString(Path.of("/tmp/my-change.patch"));
            hg.importPatch().setPatchText(patchText).call();

            // Equivalent of "hg bundle --all out.hg": writes every changeset as a binary
            // changegroup FILE -- a different format from export()'s patch text, and the base
            // revision is required (pass the "null" sentinel, matching hg's own --base null/-a,
            // to mean "no known ancestor, bundle everything").
            File outputFile = new File("/tmp/full-repo.hg");
            int changesetCount = hg.bundle()
                    .setOutputFile(outputFile)
                    .setBaseRevision("null")
                    .call();
            System.out.println("Bundled " + changesetCount + " changesets");

            // Equivalent of "hg bundle --base 0 out.hg": excludes revision 0 and all of its
            // ancestors from the bundle, useful for shipping only the delta to a peer already
            // known to have everything up to that point. NOTE: setBaseRevision()/setRevision()
            // resolve only a revision number, a hex node prefix, or "tip" -- NOT a tag or
            // bookmark name, so a tag has to be resolved to its target revision first.
            File outputFile = new File("/tmp/incremental.hg");
            int changesetCount = hg.bundle()
                    .setOutputFile(outputFile)
                    .setBaseRevision("0")
                    .setType(BundleCommand.BundleType.GZIP_V1)
                    .call();
            System.out.println("Bundled " + changesetCount + " changesets since revision 0");

            // Applies a local bundle FILE (from bundle(), or received out of band) to this
            // repository -- decodes the HG10UN/HG10GZ/HG10BZ and bundle2/HG20 container formats
            // automatically.
            List<byte[]> importedNodeIds = hg.unbundle()
                    .setBundleFile(new File("/tmp/full-repo.hg"))
                    .call();
            System.out.println("Applied " + importedNodeIds.size() + " changesets from the bundle");

            // NOTE: unlike every other command in this manual, this is Hg.clonebundle(url)
            // called directly -- not a *Command obtained via a no-arg factory method and a
            // separate call(). It downloads the bundle at "url" with a plain HTTP(S) GET and
            // applies it in one step.
            List<byte[]> importedNodeIds = hg.clonebundle("https://example.com/hg/bundles/full.hg");

            // Real hg's own clonebundles mechanism still expects a normal pull afterward, to
            // catch up on anything committed to the origin since the bundle was generated.
            hg.pull().setSource("https://example.com/hg/some-project").call();

            // Equivalent of "hg incoming": contacts the remote and reports changesets it has
            // that this repository does not, WITHOUT pulling them. Returns pre-formatted display
            // lines (a single "no incoming changes found" line when there is nothing new), not
            // structured changeset objects.
            List<String> incomingLines = hg.incoming()
                    .setSource("https://example.com/hg/some-project")
                    .call();
            incomingLines.forEach(System.out::println);

            // Equivalent of "hg outgoing": reports local changesets the remote does not have yet,
            // WITHOUT pushing them.
            List<String> outgoingLines = hg.outgoing()
                    .setDestination("https://example.com/hg/some-project")
                    .call();
            outgoingLines.forEach(System.out::println);

            // Writes an unversioned snapshot of "tip" (no .hg metadata, just a
            // .hg_archival.txt provenance file) -- the archive type is auto-detected from the
            // destination's extension here (.tar.gz -> gzip-compressed tar).
            hg.archive()
                    .setRevision("tip")
                    .setDestination(new File("/tmp/release-snapshot.tar.gz"))
                    .call();

            List<String> errors = hg.verify().call();
            if (errors.isEmpty()) {
                System.out.println("repository is healthy");
            } else {
                errors.forEach(System.out::println);
            }

            // setVerify(true) additionally runs VerifyCommand, but only when a journal was
            // actually found and successfully rolled back.
            RecoverCommand.RecoverResult result = hg.recover().setVerify(true).call();
            if (!result.wasInterrupted()) {
                // Nothing to do -- matches real hg's "no interrupted transaction available".
                System.out.println("nothing to recover");
            } else if (result.isSuccess()) {
                System.out.println("rolled back an interrupted transaction");
                List<String> verifyErrors = result.getVerifyErrors();
                if (verifyErrors != null) {
                    verifyErrors.forEach(System.out::println);
                }
            } else {
                // The journal is left on disk for a future retry.
                System.out.println("rollback did not complete, journal retained");
            }

            // config() merges system hgrc, user hgrc, and .hg/hgrc, in that priority order.
            HgRcConfig cfg = hg.config();
            String username = cfg.getUsername();
            String defaultRemote = cfg.getPath("default");

            // Enumerate every configured remote, in the order they were parsed.
            Map<String, String> paths = cfg.getSection("paths");
            paths.forEach((name, url) -> System.out.println(name + " -> " + url));

            // Registers a new entry in .hgsub/.hgsubstate, pinned to a specific revision.
            hg.subrepo()
                    .setAction("add")
                    .setSubrepoPath("libs/vendor")
                    .setSubrepoUrl("https://example.com/hg/vendor-lib")
                    .setRevision("a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2")
                    .call();

            // Clones/updates every subrepo listed in .hgsub to its .hgsubstate-pinned revision --
            // safe to call again later to bring existing subrepo checkouts back in line after
            // .hgsubstate changes (e.g. a pull that advanced the pinned revision).
            hg.subrepo().setAction("update").call();

        // Hg.narrowClone() is static, like Hg.init()/Hg.cloneRepository() -- it creates a new
        // repository, so there is no existing Hg instance to call it on.
        try (Hg hg = Hg.narrowClone()
                .setSource("https://example.com/hg/monorepo")
                .setDirectory(new File("/path/to/narrow-clone"))
                .addIncludePath("services/billing")
                .addExcludePath("services/billing/vendor")
                .call()) {
            HgRepository repository = hg.getRepository();
            // ... the working copy only contains services/billing, minus its vendor/ subtree ...
            repository.getDirectory();
        }

            // Resolves .hg/sparse (including any %include-referenced profile files, read from
            // the given changelog revision's manifest) into the effective include/exclude rules.
            SparseConfig sparse = hg.sparseConfig(0);
            System.out.println("includes: " + sparse.includes);
            System.out.println("excludes: " + sparse.excludes);

            // Turns the resolved rules into a reusable PathFilter, e.g. to restrict a
            // walkWorkingDir()/walkTree() traversal to the active sparse profile.
            boolean included = sparse.toPathFilter().accept("services/billing/pom.xml");

            ManifestWalk walk = hg.walkManifest("tip");
            while (walk.next()) {
                ManifestWalk.Entry entry = walk.getEntry();
                System.out.println(entry.getPath() + " -> " + entry.getNodeIdHex()
                        + (entry.isExecutable() ? " (executable)" : "")
                        + (entry.isSymlink() ? " (symlink)" : ""));
            }

            // Merges tracked (dirstate) and untracked paths into one sorted walk, so every
            // relevant working-copy path is visited regardless of whether it is already tracked.
            WorkingDirWalk walk = hg.walkWorkingDir();
            while (walk.next()) {
                WorkingDirWalk.Entry entry = walk.getEntry();
                // State is a dirstate character: 'n' (normal), 'a' (added), 'r' (removed),
                // 'm' (merged), or '?' for an untracked path.
                System.out.println(entry.getState() + " " + entry.getPath()
                        + " (" + entry.getSize() + " bytes)");
            }

            HgRepository repository = hg.getRepository();

            // Each added tree is indexed in add order -- that index is what isTracked()/
            // getNodeId()/getState() take below. ManifestTreeIterator resolves "tip" or a
            // revision number/hex node id, exactly like walkManifest(String).
            TreeWalk tw = hg.walkTree();
            tw.addTree(new ManifestTreeIterator(repository, "0")); // tree 0: revision 0
            tw.addTree(new ManifestTreeIterator(repository, "tip")); // tree 1: tip

            while (tw.next()) {
                String path = tw.getPath();
                boolean inOld = tw.isTracked(0);
                boolean inNew = tw.isTracked(1);

                if (inOld && !inNew) {
                    System.out.println("removed: " + path);
                } else if (!inOld && inNew) {
                    System.out.println("added: " + path);
                } else if (tw.getState(1) != tw.getState(0)
                        || !java.util.Arrays.equals(tw.getNodeId(0), tw.getNodeId(1))) {
                    System.out.println("modified: " + path);
                }
            }

            TreeWalk tw = hg.walkTree();
            tw.addTree(new ManifestTreeIterator(repository, "tip"));

            // Restricts the walk to one subtree.
            tw.setFilter(path -> path.equals("services/billing") || path.startsWith("services/billing/"));

            while (tw.next()) {
                System.out.println(tw.getPath());
            }

            // With no filter set, setRecursive(false) restricts the walk to paths with no "/"
            // at all -- i.e. files directly at the repository root, not inside any subdirectory.
            TreeWalk tw = hg.walkTree();
            tw.addTree(new ManifestTreeIterator(repository, "tip"));
            tw.setRecursive(false);

            while (tw.next()) {
                System.out.println(tw.getPath()); // e.g. "README.md", never "src/Main.java"
            }