diff --git a/AGENTS.md b/AGENTS.md index b1e06f1..e0adefb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -25,8 +25,7 @@ released together and consumed separately. | Module | Purpose | Depends on | |---|---|---| -| `git-core` | Hardened repositories, remote policy, commit and reference identity, results, transport, reading, cache repository, in-core writing, compare-and-swap, in-core merge, notes | - | -| `git-worktrees` | Linked working trees, commit from a working tree, working-tree status | `git-core` | +| `git-core` | Hardened repositories, remote policy, commit and reference identity, results, transport, reading, cache repository, in-core writing, compare-and-swap, in-core merge, notes; linked working trees, commit from a working tree, working-tree status (package `worktrees`) | - | | `git-testing` | Generators and fixtures: local and in-memory repositories, a local remote | - | | `git-store` | Repository registry, typed configuration, codec interface, outcome list and result, service interfaces with provider selection | `git-core` | @@ -43,12 +42,12 @@ compare-and-swap: `InCoreWriter` with `TreeEdit`, `CommitMetadata` and `CommitSi `TreeOperation` (compare-and-swap and compare-and-delete of a reference), and with in-core merge, reading and notes: `InCoreMerger` with the sealed `MergeResult` (the merged tree, or the conflicting paths as data), `RepositoryReader` (snapshot, path history, changed paths) and `GitNotes` (read and write a note under a caller-named notes reference, -by compare-and-swap); its tests run on the class path against the `git-testing` fixtures. `git-worktrees` exports `de.cuioss.git.document.worktrees` with the worktree part -taken over from `pm-provider-git`: `WorktreeOperations` with `JGitWorktreeOperations` (add, list and remove linked -working trees, commit from a working tree, working-tree status `WorktreeStatus`, release of a branch reservation left -by an ended process), the package-private -`LinkedWorktrees` and the `LogRecord` holder `GitWorktreesLogMessages`; its tests run on the class path against the -`git-testing` fixtures. `git-store` exports `de.cuioss.git.document.store` with the foundation of the store: the +by compare-and-swap). `git-core` also exports `de.cuioss.git.document.core.worktrees` with the worktree part taken +over from `pm-provider-git`: `WorktreeOperations` with `JGitWorktreeOperations` (add, list and remove linked working +trees, commit from a working tree, working-tree status `WorktreeStatus`, release of a branch reservation left by an +ended process) and the package-private `LinkedWorktrees`; its log messages are declared in `GitCoreLogMessages`, the +single `LogRecord` holder of `git-core`. The tests of both packages run on the class path against the `git-testing` +fixtures. `git-store` exports `de.cuioss.git.document.store` with the foundation of the store: the closed outcome list `StoreOutcome` and the result `StoreResult` (whose outcome is a `StoreOutcome` or a non-success Git outcome passed on as `StoreResult.PassedOn`), the codec interface `Codec`, the repository registry `RepositoryRegistry` with `StoreRepository`, the typed configuration `StoreConfiguration` (built by @@ -60,12 +59,12 @@ public class of a package: javac rejects exporting a package that contains only The build guards GDR-GEN-1 (`doc/specification/general.adoc`) with the `maven-enforcer-plugin` that `cui-parent-pom` already binds: the execution `module-layering` of the root `pom.xml` bans every reactor dependency outside the module -graph (`git-worktrees` and `git-store` each append their one edge, `git-core`), and the execution `consumer-isolation` of `git-core/pom.xml` bans every compile or runtime artifact outside the -closure a consumer of `git-core` alone receives. `DomainTermAbsenceTest` in each module (`git-core`, `git-worktrees`, -`git-testing` and `git-store`) asserts that no public type carries a domain term. `git-core` ships native-image -metadata (`reflect-config.json`, `resource-config.json` under `META-INF/native-image/de.cuioss/git-core/`, checked by -`NativeImageMetadataTest`) for the JGit translation bundle it reaches; `git-worktrees` and `git-store` ship none and -rely on that of `git-core` (GDR-NFR-4). +graph (`git-store` is the only module that appends an edge, `git-core`), and the execution `consumer-isolation` of +`git-core/pom.xml` bans every compile or runtime artifact outside the closure a consumer of `git-core` alone receives. +`DomainTermAbsenceTest` in each module (`git-core`, `git-testing` and `git-store`) asserts that no public type carries +a domain term. `git-core` ships native-image metadata (`reflect-config.json`, `resource-config.json` under +`META-INF/native-image/de.cuioss/git-core/`, checked by `NativeImageMetadataTest`) for the JGit translation bundle it +reaches, its worktrees package included; `git-store` ships none and relies on that of `git-core` (GDR-NFR-4). ## Build @@ -98,7 +97,7 @@ These follow the conventions of the foundation code that moves into this reposit the dependencies of `git-store`, `git-forms` or `git-timestamp`. - **Never add a dependency without the owner's approval**, JGit included. - A new module adds its allowed reactor edges to the `module-layering` rule: one `` per edge of the module - graph, in its own POM (see `git-worktrees/pom.xml`). + graph, in its own POM (see `git-store/pom.xml`). - A new compile dependency of `git-core` is added to the `consumer-isolation` rule of `git-core/pom.xml` only after the owner's approval; until then the build fails. - Documentation is AsciiDoc; Javadoc on every public type and method. diff --git a/README.adoc b/README.adoc index e3917e3..67e30b3 100644 --- a/README.adoc +++ b/README.adoc @@ -29,10 +29,7 @@ The repository is a multi-module Maven reactor whose modules are released togeth |`git-core` |Hardened repositories, remote policy, identity, results, transport, reading, cache repository, in-core writing, -compare-and-swap, in-core merge, notes. - -|`git-worktrees` -|Linked working trees, commit from a working tree, working-tree status. Depends on `git-core` only. +compare-and-swap, in-core merge, notes; linked working trees, commit from a working tree, working-tree status. |`git-testing` |Generators and fixtures: local and in-memory repositories, a local remote. @@ -44,9 +41,9 @@ selection. Depends on `git-core` only. `git-core` holds the repository part taken over from its first client: hardening, remote policy, identity, results, repository operations and the cache repository, plus in-core writing, compare-and-swap reference updates, in-core -merge, reading (snapshot, path history, changed paths) and notes. `git-worktrees` holds the worktree part taken over -from the same client: adding, listing and removing linked working trees and the commit from a working tree, plus a new -working-tree status. `git-testing` holds its credential generator and its repository fixtures (see +merge, reading (snapshot, path history, changed paths) and notes. Its package `de.cuioss.git.document.core.worktrees` +holds the worktree part taken over from the same client: adding, listing and removing linked working trees and the +commit from a working tree, plus a new working-tree status. `git-testing` holds its credential generator and its repository fixtures (see link:doc/concepts/module-structure.adoc[Module Structure] and link:doc/clients/pm-mcp-core.adoc[Client: `pm-mcp-core`]). `git-store` holds the foundation of the document store: the registry of its repositories, the typed configuration checked at start, the codec interface, its own outcome list and result, and the service interfaces for signing keys, @@ -56,8 +53,7 @@ them. The build guards the layering and the consumer closure of `git-core`: a module that declares a dependency on another module outside the module graph fails the build, and so does a compile or runtime artifact outside the closure a consumer of `git-core` alone receives. -`git-core` ships the GraalVM native-image metadata for the JGit classes it reaches; `git-worktrees` and `git-store` -rely on it (see +`git-core` ships the GraalVM native-image metadata for the JGit classes it reaches; `git-store` relies on it (see link:doc/specification/general.adoc[General Requirements], GDR-GEN-1 and GDR-NFR-4). === Maven Coordinates diff --git a/doc/README.adoc b/doc/README.adoc index 23e2b98..6d5547a 100644 --- a/doc/README.adoc +++ b/doc/README.adoc @@ -117,17 +117,17 @@ xref:specification/git-core.adoc#GDR-CORE-2[GDR-CORE-2], xref:specification/git- xref:specification/git-core.adoc#GDR-CORE-4[GDR-CORE-4], xref:specification/git-core.adoc#GDR-CORE-5[GDR-CORE-5], xref:specification/git-core.adoc#GDR-CORE-6[GDR-CORE-6], xref:specification/git-core.adoc#GDR-CORE-7[GDR-CORE-7], xref:specification/git-core.adoc#GDR-CORE-8[GDR-CORE-8], xref:specification/git-core.adoc#GDR-CORE-9[GDR-CORE-9], -xref:specification/git-core.adoc#GDR-CORE-10[GDR-CORE-10] and -xref:specification/git-core.adoc#GDR-CORE-11[GDR-CORE-11] of `git-core`, and -xref:specification/git-worktrees.adoc#GDR-WT-1[GDR-WT-1], xref:specification/git-worktrees.adoc#GDR-WT-2[GDR-WT-2], -xref:specification/git-worktrees.adoc#GDR-WT-3[GDR-WT-3] and xref:specification/git-worktrees.adoc#GDR-WT-4[GDR-WT-4] -of `git-worktrees`, and xref:specification/git-store.adoc#GDR-STORE-1[GDR-STORE-1] and +xref:specification/git-core.adoc#GDR-CORE-10[GDR-CORE-10], xref:specification/git-core.adoc#GDR-CORE-11[GDR-CORE-11], +xref:specification/git-core.adoc#GDR-CORE-12[GDR-CORE-12], xref:specification/git-core.adoc#GDR-CORE-13[GDR-CORE-13], +xref:specification/git-core.adoc#GDR-CORE-14[GDR-CORE-14] and +xref:specification/git-core.adoc#GDR-CORE-15[GDR-CORE-15] of `git-core`, and +xref:specification/git-store.adoc#GDR-STORE-1[GDR-STORE-1] and xref:specification/git-store.adoc#GDR-STORE-11[GDR-STORE-11] of `git-store`, together with its configuration, its outcome list and its service interfaces. xref:specification/git-core.adoc#GDR-CORE-1[GDR-CORE-1] is met with one limit: the JVM-wide process start of JGit's `SystemReader` is closed only when the embedding application installs `RefusingFS.systemReader`, the recommended -setup. For xref:specification/general.adoc#GDR-NFR-4[GDR-NFR-4], `git-core` ships its native-image metadata and -`git-worktrees` and `git-store` rely on it; this repository does not verify the requirement yet. Every other requirement is planned. +setup. For xref:specification/general.adoc#GDR-NFR-4[GDR-NFR-4], `git-core` ships its native-image metadata, covering its +worktrees package, and `git-store` relies on it; this repository does not verify the requirement yet. Every other requirement is planned. [cols="1,3"] |=== @@ -138,10 +138,8 @@ setup. For xref:specification/general.adoc#GDR-NFR-4[GDR-NFR-4], `git-core` ship |xref:specification/git-core.adoc[git-core] |Hardened repositories, remote policy, bare clone, in-core writing, compare-and-swap, merge, transport, cache -repository, reading, notes, identity - -|xref:specification/git-worktrees.adoc[git-worktrees] -|Linked working trees, commit from a working tree, working-tree status, release of a branch reservation +repository, reading, notes, identity, linked working trees, commit from a working tree, working-tree status, release +of a branch reservation |xref:specification/git-testing.adoc[git-testing] |Repository fixtures and the credential generator diff --git a/doc/adr/0001-Documents_are_written_in_core_without_working_trees_and_references_move_by_compare-and-swap.adoc b/doc/adr/0001-Documents_are_written_in_core_without_working_trees_and_references_move_by_compare-and-swap.adoc index bd21a97..9769dd4 100644 --- a/doc/adr/0001-Documents_are_written_in_core_without_working_trees_and_references_move_by_compare-and-swap.adoc +++ b/doc/adr/0001-Documents_are_written_in_core_without_working_trees_and_references_move_by_compare-and-swap.adoc @@ -49,7 +49,8 @@ The document store writes through linked working trees, like clients whose agent *Rejected because* no tool of the document store works on files, and JGit can read linked working trees but has no command that creates one (see xref:../concepts/storage-engine.adoc#_no_working_trees[Storage Engine, No Working -Trees]). `git-worktrees` stays available for consumers that need files. +Trees]). The working-tree operations of `git-core` (package `de.cuioss.git.document.core.worktrees`) stay available +for consumers that need files. === A lock per document instead of compare-and-swap diff --git a/doc/adr/0004-The_libraries_are_one_reactor_of_separately_consumed_modules_and_the_JGit_foundation_is_shared_with_its_clients.adoc b/doc/adr/0004-The_libraries_are_one_reactor_of_separately_consumed_modules_and_the_JGit_foundation_is_shared_with_its_clients.adoc index 3216045..9088b33 100644 --- a/doc/adr/0004-The_libraries_are_one_reactor_of_separately_consumed_modules_and_the_JGit_foundation_is_shared_with_its_clients.adoc +++ b/doc/adr/0004-The_libraries_are_one_reactor_of_separately_consumed_modules_and_the_JGit_foundation_is_shared_with_its_clients.adoc @@ -6,9 +6,9 @@ :source-highlighter: highlight.js // adr-metadata -// summary: git-document-repository is a multi-module reactor released together; the generic, hardened JGit code becomes the foundation modules git-core, git-worktrees and git-testing, shared by the document store and other clients; the aspects of the document store are modules of their own, each carrying its own third-party dependencies. +// summary: git-document-repository is a multi-module reactor released together; the generic, hardened JGit code becomes the foundation modules git-core and git-testing, shared by the document store and other clients, and the working-tree operations are a package of git-core; the aspects of the document store are modules of their own, each carrying its own third-party dependencies. // tags: modules, layering, dependencies, release, foundation, jgit -// affects: git-core, git-worktrees, git-testing, git-store, git-forms, git-timestamp, git-directory +// affects: git-core, git-testing, git-store, git-forms, git-timestamp, git-directory // supersedes: // end-adr-metadata @@ -26,8 +26,11 @@ how the code is cut into artifacts, and whether the store copies the hardened co *The decision:* one repository, one Maven reactor, released together to Maven Central. Every module is consumed separately: -* `git-core`, `git-worktrees`, `git-testing` -- the JGit foundation, taken over from its first client and shared by - every client, the document store included; what is specific to a client stays with that client; +* `git-core`, `git-testing` -- the JGit foundation, taken over from its first client and shared by every client, the + document store included; what is specific to a client stays with that client. The working-tree operations (linked + working trees, commit from a working tree, working-tree status) are the package + `de.cuioss.git.document.core.worktrees` of `git-core`, not a module of their own: their only edge is `git-core`, + they add no third-party dependency, and they are released together with it; * `git-store` -- drafts, saving, signature, index, anchoring; * `git-forms` -- schema-driven documents; * `git-timestamp`, `git-directory` -- optional aspects. diff --git a/doc/clients/pm-mcp-core.adoc b/doc/clients/pm-mcp-core.adoc index 2cdfec9..4d647e4 100644 --- a/doc/clients/pm-mcp-core.adoc +++ b/doc/clients/pm-mcp-core.adoc @@ -5,9 +5,9 @@ :sectnums: :source-highlighter: highlight.js -`pm-mcp-core` is the core repository of the product PM-MCP. It is a client of the foundation modules `git-core`, -`git-worktrees` and `git-testing`, not a part of these libraries. Its module `pm-provider-git` holds the hardened JGit -code from which the foundation is taken, and after the switch-over it depends on `git-core` and `git-worktrees`. +`pm-mcp-core` is the core repository of the product PM-MCP. It is a client of the foundation modules `git-core` and +`git-testing`, not a part of these libraries. Its module `pm-provider-git` holds the hardened JGit code from which the +foundation is taken, and after the switch-over it depends on `git-core`, including its working-tree package. This document collects everything that concerns this client: why the foundation is shared with it, the inventory of `pm-provider-git`, what moves where, what changes in `pm-mcp-core`, and the order of the switch-over. The library @@ -101,29 +101,30 @@ policy, a file read at that commit. `GitOperations`/`JGitOperations` the repository part as `RepositoryOperations`/`JGitRepositoryOperations`: open and init, the log, fetch and push (with credentials and lease), and the cache repository. The list of `GitOutcome` is reconciled with the outcomes the requirements of the libraries name (see <<_what_git_core_took_and_changed>>). -* *`git-worktrees`* takes `LinkedWorktrees`, adding, listing and removing working trees, and the commit from a working - tree, and offers the working-tree status on which `WorktreeShaDigest` builds. +* *The package `de.cuioss.git.document.core.worktrees` of `git-core`* takes `LinkedWorktrees`, adding, listing and + removing working trees, and the commit from a working tree, and offers the working-tree status on which + `WorktreeShaDigest` builds. * *`git-testing`* takes the generator of the transport credential (`GitCredentialGenerator`, `GitGenerators`, which lie in the test artifact `pm-provider-git:tests`). * *`pm-provider-git` keeps* `JGitSourceRepository`, `WorktreeShaDigest` with its ported tests and fixtures (its - framing is a contract of PM-MCP; it then builds on the working-tree status of `git-worktrees`), and `GitOperations` + framing is a contract of PM-MCP; it then builds on the working-tree status of `git-core`), and `GitOperations` as a facade over the two new interfaces, so the assembly keeps its interface for the first step. Every class is taken over as a plain copy without history (owner's decision, 2026-11-17): the commit that brings it names `pm-mcp-core`, the source path and the commit it was copied from. `git-core` holds the copy of `pm-providers/pm-provider-git/src/main/java/de/planmarshall/provider/git/` at commit `287e1a86`, package-renamed to -`de.cuioss.git.document.core`; `git-worktrees` holds `LinkedWorktrees` from the same path and commit, -package-renamed to `de.cuioss.git.document.worktrees` and since changed (see -<<_what_git_worktrees_took_and_changed>>); `git-testing` holds the copy of the generator. The taken-over +`de.cuioss.git.document.core`; its package `de.cuioss.git.document.core.worktrees` holds `LinkedWorktrees` from +the same path and commit, package-renamed and since changed (see +<<_what_the_worktrees_package_took_and_changed>>); `git-testing` holds the copy of the generator. The taken-over code is released under the Apache License 2.0 of `git-document-repository`. The tests move with the classes they test. Test classes that cover both sides (`JGitOperationsTest`, `GitOperationsContractTest`, `GitOperationsRecordsTest`, `AbsenceContractsTest`) are split along the interfaces. The repository part of each moves to `git-core`, rewritten onto the fixtures of `git-testing`; its commits are written through an `ObjectInserter` (the helper `TestCommits`) instead of from a working tree. `GitOperationsContractTest` -tests only the source's `GitCredential` record, which neither `git-core` nor `git-worktrees` takes, so no part of it -moves. The worktree part of `JGitOperationsTest`, `GitOperationsRecordsTest` and `AbsenceContractsTest` moves to -`git-worktrees`, likewise rewritten onto the fixtures; the main working tree of its tests is a clone of a fixture +tests only the source's `GitCredential` record, which `git-core` does not take, so no part of it moves. The worktree +part of `JGitOperationsTest`, `GitOperationsRecordsTest` and `AbsenceContractsTest` moves to the package +`de.cuioss.git.document.core.worktrees` of `git-core`, likewise rewritten onto the fixtures; the main working tree of its tests is a clone of a fixture repository. [cols="1,2"] @@ -137,7 +138,7 @@ secrets check), `RepositoryOperationsRecordsTest` (the repository part of `GitOp `AbsenceContractsTest` (its repository part); `JGitCacheRepositoryTest` and `UnservedWantTest` (both test the cache repository); `TransportFailuresTest` (new: the classification of a refused authentication) -|`git-worktrees` +|`git-core`, package `worktrees` |`LinkedWorktreesTest`; `JGitWorktreeOperationsTest` (the worktree part of `JGitOperationsTest`: add, list, remove and commit with every outcome, and the secrets check), `WorktreeOperationsRecordsTest` (the worktree part of `GitOperationsRecordsTest`), `AbsenceContractsTest` (its worktree part); `WorktreeStatusTest` (new: the working-tree @@ -186,12 +187,12 @@ switch-over: |none |new: `CONFLICT`, `UNREACHABLE`, `CREDENTIALS_INVALID`, `UNSERVED`, `FAILED` |=== -[[_what_git_worktrees_took_and_changed]] -=== What `git-worktrees` Took and Changed +[[_what_the_worktrees_package_took_and_changed]] +=== What the Worktrees Package Took and Changed -`git-worktrees` changed the copied code where the requirements of the libraries demand it -(xref:../specification/git-worktrees.adoc[`git-worktrees`]); the facade of `pm-provider-git` maps the differences at -the switch-over: +The package `de.cuioss.git.document.core.worktrees` of `git-core` changed the copied code where the requirements of +the libraries demand it (xref:../specification/git-core.adoc#working-trees[`git-core`, Working Trees]); the facade of +`pm-provider-git` maps the differences at the switch-over: * *Outcomes.* The worktree operations report the constants of `GitOutcome` of `git-core`, so the mapping of the table above applies to them as well; an unexpected failure is `FAILED` with the failure class as detail. @@ -205,7 +206,7 @@ the switch-over: existing one, until the new working tree names it; a refused or failed addition removes only what it created, a branch it created only while the branch still points at the start. An unknown start point is not found, also for an existing branch. `releaseBranchReservation` is new: it releases a reservation an ended process left behind - (xref:../specification/git-worktrees.adoc#GDR-WT-4[GDR-WT-4]). + (xref:../specification/git-core.adoc#GDR-CORE-15[GDR-CORE-15]). * *Removal.* `worktreeRemove` ends `WORKTREE_NOT_FOUND`, no longer `IDENTITY_MISMATCH`, for a repository at the root that is not the registered working tree, compares the registered paths as real paths and removes a prunable working tree by its administration directory only. @@ -214,7 +215,7 @@ the switch-over: commit in a linked working tree to that working tree's own log; a reflog entry that cannot be written keeps the created commit `OK`. * *Log messages.* The INFO messages carry no path and no administrative name; the add message names the start commit, - and the release of a branch reservation is logged without an argument. The WARN message `GIT_WORKTREES-101` names + and the release of a branch reservation is logged without an argument. The WARN message `GIT_CORE-103` names the commit id of a commit whose reflog entry was not written. * *Status.* The working-tree status `worktreeStatus` is new: the three path sets `changed`, `untracked` and `deleted` mapped from JGit's `Status`, whose union is the path union the source's `worktreeSha` reads; the digest itself stays @@ -226,7 +227,7 @@ Each item is part of the work package that switches `pm-provider-git` over: . *The dependency decision* for the new artifacts, by the owner of `pm-mcp-core`; their version comes from its root POM's `dependencyManagement`. -. *The Module Structure Specification* of PM-MCP: `pm-provider-git` may depend on `git-core` and `git-worktrees`. +. *The Module Structure Specification* of PM-MCP: `pm-provider-git` may depend on `git-core`. . *The enforcer rules of the root POM* name the new artifacts, and `BuildGuardsIT` proves the changed rule. JGit stays a dependency of `pm-provider-git` through `git-core`; `pm-core` and `pm-workflow` stay without JGit. . *The registry.* Artifacts under `de.cuioss` from Maven Central need no change of the group filter in `.mvn/rrf`. @@ -241,11 +242,11 @@ the size. == Order of the Switch-Over -. Fill `git-core`, `git-worktrees` and `git-testing`: copy the classes and their tests into `git-core` and - `git-worktrees`, and the generator into `git-testing`, each as a plain copy without history whose commit names the - source (owner's decision, 2026-11-17); build and release a first version. `git-core`, `git-worktrees` and - `git-testing` are filled; the first release follows. -. Work package in `pm-mcp-core`: switch `pm-provider-git` onto the two modules and reduce it to facade, adapter and +. Fill `git-core` and `git-testing`: copy the classes and their tests into `git-core` (the worktree part into its + package `de.cuioss.git.document.core.worktrees`), and the generator into `git-testing`, each as a plain copy without + history whose commit names the source (owner's decision, 2026-11-17); build and release a first version. `git-core` + and `git-testing` are filled; the first release follows. +. Work package in `pm-mcp-core`: switch `pm-provider-git` onto `git-core` and reduce it to facade, adapter and digest, with the changes listed above. The aspect modules of the document store (`git-store` and the modules above it) change nothing in `pm-mcp-core`. diff --git a/doc/concepts/module-structure.adoc b/doc/concepts/module-structure.adoc index b5bb267..0cf9226 100644 --- a/doc/concepts/module-structure.adoc +++ b/doc/concepts/module-structure.adoc @@ -39,14 +39,11 @@ image::../resources/diagrams/module-dependency-graph.svg["Module dependency grap |`git-core` |Hardened repositories, remote policy, commit and reference identity, results, transport, reading, cache repository, -in-core writing, compare-and-swap, in-core merge, notes +in-core writing, compare-and-swap, in-core merge, notes; in the package `de.cuioss.git.document.core.worktrees` +linked working trees, commit from a working tree, working-tree status |implemented: hardening (with the one limit of xref:../specification/git-core.adoc#GDR-CORE-1[GDR-CORE-1]), remote policy, identity, results, repository operations, cache repository, in-core writing, compare-and-swap, in-core merge, -reading, notes - -|`git-worktrees` -|Linked working trees, commit from a working tree, working-tree status -|implemented +reading, notes, working trees |`git-testing` |Generators and fixtures: local and in-memory repositories, a local remote @@ -74,13 +71,13 @@ Stores, The Anchor]) |planned |=== -The first three modules are the extended JGit functionality with its helper classes. The others are the aspects of +The first two modules are the extended JGit functionality with its helper classes. The others are the aspects of the document store. An application with its kinds of documents and its user interface is not part of this repository; its kinds of documents are configuration of `git-forms`. === Dependencies and Third-Party Isolation -`git-worktrees` and `git-store` build on `git-core`; `git-forms` and `git-timestamp` build on `git-store`; +`git-store` builds on `git-core`; `git-forms` and `git-timestamp` build on `git-store`; `git-directory` builds on `git-forms`. `git-testing` depends on no other module of the reactor; it declares JGit directly, since its fixtures create JGit repositories. @@ -104,8 +101,8 @@ JGit is managed in the root POM; every other one of these dependencies needs the == The Foundation Modules -`git-core`, `git-worktrees` and `git-testing` form the foundation: generic Git functionality on JGit that carries no -term of a domain, so it serves the document store and every other client that works with Git repositories. +`git-core` and `git-testing` form the foundation: generic Git functionality on JGit that carries no term of a domain, +so it serves the document store and every other client that works with Git repositories. * *`git-core`* holds the hardening (a file system that refuses hooks and process starts, a remote policy checked before every fetch and push), commit and reference identity, the result type with the closed list of Git outcomes, @@ -113,13 +110,15 @@ term of a domain, so it serves the document store and every other client that wo compare-and-swap, in-core merge and `git notes` (xref:../specification/git-core.adoc[`git-core`]). Each aspect module defines its own closed list of outcomes in the same result shape, so adding an aspect module changes nothing in `git-core` (xref:../specification/general.adoc#GDR-GEN-3[GDR-GEN-3]). -* *`git-worktrees`* holds the linked working trees (administration files in git's own layout, readable by +* *The working-tree operations* are the package `de.cuioss.git.document.core.worktrees` of `git-core`, not a module of + their own (xref:../adr/0004-The_libraries_are_one_reactor_of_separately_consumed_modules_and_the_JGit_foundation_is_shared_with_its_clients.adoc[ADR-0004]). + The package holds the linked working trees (administration files in git's own layout, readable by `git worktree list` and written natively, because JGit has no command that adds or removes a linked working tree; see xref:storage-engine.adoc#_no_working_trees[Storage Engine, No Working Trees]): adding, listing and removing working trees, the commit from a working tree, and a working-tree status as a generic primitive (the path sets of changed, untracked and deleted files), on which a client builds its own digest - (xref:../specification/git-worktrees.adoc[`git-worktrees`]). The document store does not need this module; clients - that work on files on disk do. + (xref:../specification/git-core.adoc#working-trees[`git-core`, Working Trees]). The document store does not use this + package; clients that work on files on disk do. * *`git-testing`* holds a generator of transport credentials and fixtures for local and in-memory repositories and a local remote (xref:../specification/git-testing.adoc[`git-testing`]). @@ -135,11 +134,12 @@ and the changes on the client's side are described in xref:../clients/pm-mcp-cor == Order -. Fill `git-core`, `git-worktrees` and `git-testing` with the foundation code and its tests; build and release a - first version. The code is taken over as a plain copy without history, whose commit names the source repository, - the source path and the commit it was copied from (owner's decision, 2026-11-17); the taken-over code is released - under the Apache License 2.0. `git-core` holds the repository part of `pm-provider-git` copied this way, - `git-worktrees` its worktree part, and `git-testing` the generator copied this way and fixtures written new. +. Fill `git-core` and `git-testing` with the foundation code and its tests; build and release a first version. The + code is taken over as a plain copy without history, whose commit names the source repository, the source path and + the commit it was copied from (owner's decision, 2026-11-17); the taken-over code is released under the Apache + License 2.0. `git-core` holds the repository part of `pm-provider-git` copied this way and, in its package + `de.cuioss.git.document.core.worktrees`, the worktree part; `git-testing` holds the generator copied this way and + fixtures written new. . Switch the first client over to the foundation (see xref:../clients/pm-mcp-core.adoc#_order_of_the_switch_over[Client: `pm-mcp-core`, Order of the Switch-Over]). . Add the aspect modules as the document store needs them: `git-store` first, then `git-forms`, `git-directory` diff --git a/doc/resources/diagrams/module-dependency-graph.svg b/doc/resources/diagrams/module-dependency-graph.svg index 64520ac..31c8a77 100644 --- a/doc/resources/diagrams/module-dependency-graph.svg +++ b/doc/resources/diagrams/module-dependency-graph.svg @@ -10,7 +10,7 @@ role="img" aria-labelledby="title desc" font-family="ui-sans-serif, -apple-system, system-ui, 'Segoe UI', sans-serif"> Module dependency graph of git-document-repository - Seven modules in four layers. Four modules exist and are drawn solid: git-core, git-worktrees, git-testing and git-store. Three modules are planned and drawn dashed: git-forms, git-timestamp and git-directory; of these, git-timestamp and git-directory are optional modules a consumer may leave out. git-worktrees and git-store depend on git-core. git-forms and git-timestamp depend on git-store. git-directory depends on git-forms. git-testing depends on no module of the reactor and is consumed in test scope. + Six modules in four layers. Three modules exist and are drawn solid: git-core, which includes the working-tree operations, git-testing and git-store. Three modules are planned and drawn dashed: git-forms, git-timestamp and git-directory; of these, git-timestamp and git-directory are optional modules a consumer may leave out. git-store depends on git-core. git-forms and git-timestamp depend on git-store. git-directory depends on git-forms. git-testing depends on no module of the reactor and is consumed in test scope. @@ -56,12 +56,10 @@ signatures · own timestamp - - git-worktrees - linked working trees - git-core - JGit level + git-core + JGit level + linked working trees git-testing fixtures · generators @@ -72,7 +70,6 @@ - Arrows point from a module to the module it depends on. Third-party dependencies stay in the module that needs them. diff --git a/doc/specification/general.adoc b/doc/specification/general.adoc index 4024be2..95cd69d 100644 --- a/doc/specification/general.adoc +++ b/doc/specification/general.adoc @@ -9,8 +9,9 @@ non-functional limits. Rationale: xref:../concepts/module-structure.adoc[Module its requirements (xref:git-testing.adoc#GDR-TEST-1[GDR-TEST-1], xref:git-testing.adoc#GDR-TEST-2[GDR-TEST-2]), `git-core` implements its own (xref:git-core.adoc[`git-core`]: hardening, remote policy, identity, results, repository operations, cache repository, in-core writing, compare-and-swap, in-core merge, reading and notes; the hardening with -the one limit xref:git-core.adoc#GDR-CORE-1[GDR-CORE-1] states), `git-worktrees` -implements all of its own (xref:git-worktrees.adoc[`git-worktrees`]), and `git-store` is created: it implements +the one limit xref:git-core.adoc#GDR-CORE-1[GDR-CORE-1] states; and the working-tree operations of its package +`de.cuioss.git.document.core.worktrees`, xref:git-core.adoc#working-trees[`git-core`, Working Trees]), and +`git-store` is created: it implements xref:git-store.adoc#GDR-STORE-1[GDR-STORE-1] and xref:git-store.adoc#GDR-STORE-11[GDR-STORE-11] and its configuration, and defines its three service interfaces, whose providers are planned (xref:git-store.adoc[`git-store`]). Of the requirements below, <> is implemented, and for <> `git-core` ships its native-image metadata, @@ -20,8 +21,8 @@ are not yet created. [#GDR-GEN-1] == GDR-GEN-1: Module Layering and Dependency Isolation -* Once all planned modules exist, the reactor must consist of the modules `git-core`, `git-worktrees`, `git-testing`, - `git-store`, `git-forms`, `git-timestamp` and `git-directory`, released together under one version. +* Once all planned modules exist, the reactor must consist of the modules `git-core`, `git-testing`, `git-store`, + `git-forms`, `git-timestamp` and `git-directory`, released together under one version. * A module must depend only on the modules the dependency graph of the module structure allows; the build must fail when a module declares another dependency on a module of the reactor. * A consumer that depends on `git-core` alone must receive no third-party dependency of the modules above it @@ -41,8 +42,8 @@ dependency. Three checks realise the requirement: * The execution `module-layering` of the root POM (phase `validate`, declared dependencies only) bans every dependency on an artifact `de.cuioss:git-*` except `git-testing` in scope `test`, against which every module may test. Each module lists its allowed edges in its own POM, one `` per edge, appended to the rule with - `combine.children="append"` in an execution of the same id: `git-worktrees` and `git-store` each list `git-core`; - `git-core` and `git-testing` list none. A new module adds exactly the edges the graph names. + `combine.children="append"` in an execution of the same id: `git-store` lists `git-core`; `git-core` and + `git-testing` list none. A new module adds exactly the edges the graph names. * The execution `consumer-isolation` of `git-core` (phase `validate`, transitive) bans every artifact in scope `compile` or `runtime` outside the closure a consumer of `git-core` alone receives: `org.jspecify:jspecify`, JGit with the compile dependencies its 7.8.0 POM declares (`com.googlecode.javaewah:JavaEWAH`, `org.slf4j:slf4j-api`, @@ -55,18 +56,19 @@ dependency. Three checks realise the requirement: runtime closure a consumer of `git-core` alone resolves, publishes nothing extra, and needs no new plugin or dependency, where a consumer project would be a new module of the reactor that needs a test harness or a parser of its dependency tree. A new compile dependency of `git-core` is added to the rule only after the owner's approval. -* `DomainTermAbsenceTest` of `git-core`, `git-worktrees`, `git-testing` and `git-store` loads the classes of the - module's main - output and fails when the simple name or the package name of a public type contains `assessment`, `threat`, - `incident` or `risk`, compared case-insensitively, or when the scan finds no public type. +* `DomainTermAbsenceTest` of `git-core`, `git-testing` and `git-store` loads the classes of the module's main output + and fails when the simple name or the package name of a public type contains `assessment`, `threat`, `incident` or + `risk`, compared case-insensitively, or when the scan finds no public type. The test of `git-core` also reads the + exported packages from the compiled `module-info.class` of its main output and fails when an exported package holds + no public type of the scan, so both packages of `git-core` are checked. The third-party dependencies declared are `org.jspecify:jspecify`, in every module (scope `compile` as managed by `cui-java-parent`, `requires static org.jspecify` in every `module-info.java`; see <>); JGit, `cui-test-generator` and JUnit 5 in `git-testing`; JGit, `cui-java-tools` and Lombok in `git-core`, with `git-testing`, JUnit 5, `cui-test-generator`, `cui-test-juli-logger` and `cui-test-mockwebserver-junit5` in its test scope; and -`cui-java-tools` and Lombok in `git-worktrees` and in `git-store`, each with `git-testing`, JUnit 5, -`cui-test-generator` and `cui-test-juli-logger` in its test scope. The owner approved JGit 7.8.0, `cui-java-tools`, Lombok, +`cui-java-tools` and Lombok in `git-store`, with `git-testing`, JUnit 5, `cui-test-generator` and +`cui-test-juli-logger` in its test scope. The owner approved JGit 7.8.0, `cui-java-tools`, Lombok, `cui-test-generator`, JUnit 5, EasyMock and `cui-test-juli-logger` on 2026-11-17, and `de.cuioss.test:cui-test-mockwebserver-junit5` (the CUI MockWebServer, test scope of `git-core` only, for the end-to-end redirect test of xref:git-core.adoc#GDR-CORE-2[GDR-CORE-2]) on 2026-11-19; it brings OkHttp's @@ -82,8 +84,6 @@ approval before it is added: |`git-core` |JGit (`requires transitive`), `cui-java-tools` for `CuiLogger`, Lombok (scope `provided`); in test scope `cui-test-juli-logger` for the log capture of <>, `cui-test-mockwebserver-junit5` for the end-to-end redirect test, `cui-test-generator` and JUnit 5 (each declared) -|`git-worktrees` |JGit through `git-core`, `cui-java-tools` for `CuiLogger`, Lombok (scope `provided`); in test scope -`git-testing`, `cui-test-juli-logger`, `cui-test-generator` and JUnit 5 (each declared) |`git-testing` |JGit (declared directly, because `git-testing` depends on no module of the reactor), `cui-test-generator`, JUnit 5 (each declared, in scope `compile`) |`git-store` |JGit through `git-core`, `cui-java-tools` for `CuiLogger`, Lombok (scope `provided`); in test scope @@ -102,7 +102,8 @@ redirect test, `cui-test-generator` and JUnit 5 (each declared) * Every package must be annotated `@NullMarked` (JSpecify); a value that may be absent must be typed `@Nullable`. * The modules must compile with target Java 21 and their tests must pass on Java 21 and Java 25. -The suffixes are `core`, `worktrees`, `testing`, `store`, `forms`, `timestamp` and `directory`. An `exports` +The suffixes are `core`, `testing`, `store`, `forms`, `timestamp` and `directory`; the module `core` holds a second +package, `de.cuioss.git.document.core.worktrees`. An `exports` directive is added together with the first public class of a package. `org.jspecify` is `requires static`. [#GDR-GEN-3] @@ -124,8 +125,8 @@ therefore changes nothing in `git-core`. must name its paths, therefore returns `MergeResult`, a result of the same shape (outcome and detail) that carries the conflicting paths as data in its variant `Conflicting`, never in the detail. -`GitOutcome` (`git-core`), the outcomes of `git-worktrees` included; the first column names the constant, and the -table lists exactly the constants of `GitOutcome`: +`GitOutcome` (`git-core`), the outcomes of its working-tree operations included; the first column names the +constant, and the table lists exactly the constants of `GitOutcome`: [cols="2,2,4"] |=== @@ -142,28 +143,29 @@ attempt the draft |`CREDENTIALS_INVALID` |credentials expired or invalid |fetch, push, bare clone, save |`REFUSED_BY_POLICY` |refused by policy |remote policy, refused capability (hook or process start); the detail names -the refused remote or capability; an invalid branch name (`git-worktrees`: a new working tree or a reservation -release) or notes reference (notes), the detail naming the field only; `git-store`: a registered remote the policy -does not permit, the detail naming the alias +the refused remote or capability; an invalid branch name (working-tree operations: a new working tree or a +reservation release) or notes reference (notes), the detail naming the field only; `git-store`: a registered remote +the policy does not permit, the detail naming the alias |`NOT_FOUND` |not found |an unknown revision, reference, remote or path, an abbreviated commit id given as identity: log, reading (snapshot, path history, changed paths), push, cache repository, in-core writing on a missing reference, in-core merge and notes on an id that is no commit, notes on a missing notes reference or note; a branch without a -reservation to release (`git-worktrees`); the detail names which +reservation to release (working-tree operations); the detail names which |`UNSERVED` |unserved |cache repository: the remote does not serve the commit |`AMBIGUOUS` |ambiguous |identity resolution; the detail lists the candidates |`NOT_A_REPOSITORY` |not a repository |every operation on a path that holds no repository, or no bare repository where one is required |`IDENTITY_MISMATCH` |identity mismatch |a pinned full commit id that reaches another commit; an existing branch not -at the pinned commit (`git-worktrees`: `worktreeAdd`) +at the pinned commit (working-tree operations: `worktreeAdd`) |`FAILED` |failed |every operation, for an unexpected I/O failure outside the outcomes above -|`NOTHING_TO_COMMIT` |nothing to commit |`git-worktrees`: commit from a working tree with nothing changed -|`ALREADY_EXISTS` |already exists |`git-worktrees`: the path or the branch of a new working tree exists -|`BRANCH_CHECKED_OUT` |branch checked out |`git-worktrees`: the branch is checked out in another working tree -|`WORKTREE_NOT_FOUND` |working tree not found |`git-worktrees`: no linked working tree at that path, or another -repository at the registered path -|`WORKTREE_DIRTY` |working tree dirty |`git-worktrees`: uncommitted or untracked changes -|`WORKTREE_LOCKED` |working tree locked |`git-worktrees`: the working tree is locked -|`PATH_REFUSED` |path refused |`git-worktrees`: a derived path outside the permitted root, or the main working tree +|`NOTHING_TO_COMMIT` |nothing to commit |working-tree operations: commit from a working tree with nothing changed +|`ALREADY_EXISTS` |already exists |working-tree operations: the path or the branch of a new working tree exists +|`BRANCH_CHECKED_OUT` |branch checked out |working-tree operations: the branch is checked out in another working tree +|`WORKTREE_NOT_FOUND` |working tree not found |working-tree operations: no linked working tree at that path, or +another repository at the registered path +|`WORKTREE_DIRTY` |working tree dirty |working-tree operations: uncommitted or untracked changes +|`WORKTREE_LOCKED` |working tree locked |working-tree operations: the working tree is locked +|`PATH_REFUSED` |path refused |working-tree operations: a derived path outside the permitted root, or the main working +tree |=== `StoreOutcome` (`git-store`) is the outcome list of `git-store`, used by `git-timestamp` for its provider and by every @@ -273,8 +275,8 @@ read from the application's configuration for the call; never stored, logged, co entry; never in the metadata of a commit (author, committer, message, trailers), a document or a log |=== -Tests are to assert the rules with a JUL log capture (`cui-test-juli-logger`, declared in the test scope of `git-core`, -`git-worktrees` and `git-store`, see <>) and with checks of result details. +Tests are to assert the rules with a JUL log capture (`cui-test-juli-logger`, declared in the test scope of `git-core` +and `git-store`, see <>) and with checks of result details. [#GDR-NFR-4] == GDR-NFR-4: Native Image @@ -293,22 +295,20 @@ the public fields of a translation class reflectively from the resource bundle o 7.8.0, `TranslationBundle`]). The one translation class the code paths of `git-core` reach is `org.eclipse.jgit.internal.JGitText`: `reflect-config.json` lists it with all public fields and its public no-argument constructor, `resource-config.json` lists its resource bundle. The classes of `git-core` itself use no reflection and -are not listed. `NativeImageMetadataTest` of `git-core` asserts that both files are on the class path, that every -listed class loads and that every listed bundle resolves, so a JGit upgrade that moves or renames an entry fails this -build instead of the native image of a consumer. +are not listed; the main code of the package `de.cuioss.git.document.core.worktrees` has no reflection, resource or +resource-bundle access either, so the metadata of `git-core` covers both its packages. `NativeImageMetadataTest` of +`git-core` asserts that both files are on the class path, that every listed class loads and that every listed bundle +resolves, so a JGit upgrade that moves or renames an entry fails this build instead of the native image of a consumer. -`git-worktrees` ships no native-image metadata (owner's decision after research, 2026-11-20): GraalVM reads the -metadata under `META-INF/native-image` from every entry of the class path +`git-store` ships no native-image metadata, on the grounds of the owner's decision after research (2026-11-20): GraalVM +reads the metadata under `META-INF/native-image` from every entry of the class path (link:https://www.graalvm.org/latest/reference-manual/native-image/metadata/[GraalVM, Reachability Metadata]), so a -consumer of `git-worktrees` receives the metadata of `git-core` through the dependency; the main code of -`git-worktrees` itself has no reflection, resource or resource-bundle access; and GraalVM recommends no empty +consumer of `git-store` receives the metadata of `git-core` through the dependency, and GraalVM recommends no empty placeholder file, where an empty array would not even be a valid `resource-config.json`, which its schema requires to be an object (link:https://github.com/oracle/graal/blob/master/docs/reference-manual/native-image/assets/resource-config-schema-v1.1.0.json[GraalVM, -`resource-config-schema-v1.1.0.json`]). - -`git-store` ships no native-image metadata either, on the same grounds as `git-worktrees`: its main code has no -reflection, resource or resource-bundle access of its own; the JGit translation class it reaches, `JGitText` through +`resource-config-schema-v1.1.0.json`]). The main code of `git-store` has no reflection, resource or resource-bundle +access of its own; the JGit translation class it reaches, `JGitText` through `URIish` (which imports it in JGit 7.8.0, link:https://github.com/eclipse-jgit/jgit/blob/v7.8.0.202609011348-r/org.eclipse.jgit/src/org/eclipse/jgit/transport/URIish.java[JGit 7.8.0, `URIish`]), is covered by the metadata of `git-core`. The provider lookup of `StoreProviders` through diff --git a/doc/specification/git-core.adoc b/doc/specification/git-core.adoc index 0c7f08f..78ac20b 100644 --- a/doc/specification/git-core.adoc +++ b/doc/specification/git-core.adoc @@ -4,13 +4,14 @@ :toc-title: Table of Contents :source-highlighter: highlight.js -`git-core` is the JGit level of the reactor: module and package `de.cuioss.git.document.core`. It depends on no other +`git-core` is the JGit level of the reactor: module and package `de.cuioss.git.document.core`, with the package +`de.cuioss.git.document.core.worktrees` for the linked working trees (<>). It depends on no other module of the reactor. Its third-party dependencies are JGit (`requires transitive org.eclipse.jgit`, because JGit types such as `Repository`, `URIish`, `FS` and `CredentialsProvider` are part of its API), `cui-java-tools` for `CuiLogger`, Lombok (scope `provided`, `requires static`) and `org.jspecify:jspecify` (`requires static`); see xref:general.adoc#GDR-GEN-1[GDR-GEN-1]. The code is a plain copy of the repository part of `pm-provider-git` (xref:../clients/pm-mcp-core.adoc#_what_moves_where[Client: `pm-mcp-core`, What Moves Where]). -<> to <> are implemented. <> is met except the one JVM-wide process start of +<> to <> are implemented. <> is met except the one JVM-wide process start of JGit's `SystemReader`, which `git-core` does not prevent by itself; installing `RefusingFS.systemReader` closes it and is the recommended setup of an embedding application. The JGit APIs named here are checked against JGit 7.8.0 (tag `v7.8.0.202609011348-r` of https://github.com/eclipse-jgit/jgit). Rationale: xref:../concepts/module-structure.adoc#_the_foundation_modules[Module Structure, The Foundation Modules] and @@ -605,6 +606,258 @@ link:https://github.com/eclipse-jgit/jgit/blob/v7.8.0.202609011348-r/org.eclipse so none of them reaches it. A full commit id absent from the repository is `NOT_FOUND`, not `FAILED`; a full commit id that reaches another commit is `IDENTITY_MISMATCH`. +[#working-trees] +== Working Trees + +The package `de.cuioss.git.document.core.worktrees` of `git-core` holds the linked working trees. It builds on the +package `de.cuioss.git.document.core` and adds no third-party dependency to those of `git-core`, see +xref:general.adoc#GDR-GEN-1[GDR-GEN-1]. The document store does not use it; clients that work on files on disk do. +<>, <>, <> and <> are implemented. The JGit APIs named here are +checked against JGit 7.8.0 (tag `v7.8.0.202609011348-r` of https://github.com/eclipse-jgit/jgit). JGit 7.8.0 has no +command that creates a linked working tree: its `api` package holds no worktree command +(link:https://github.com/eclipse-jgit/jgit/tree/v7.8.0.202609011348-r/org.eclipse.jgit/src/org/eclipse/jgit/api[JGit 7.8.0 `api` package]), +so the package reads and writes Git's administration files of linked working trees itself. `LinkedWorktrees` is taken +from `pm-provider-git` and changed where <> demands it +(xref:../clients/pm-mcp-core.adoc#_what_the_worktrees_package_took_and_changed[Client: `pm-mcp-core`, What the +Worktrees Package Took and Changed]). Rationale: +xref:../concepts/module-structure.adoc#_the_foundation_modules[Module Structure, The Foundation Modules]. + +[cols="1,3"] +|=== +|Type |Role + +|`WorktreeOperations` |The working-tree operations below (`worktreeAdd`, `worktreeList`, `worktreeRemove`, `commit`, +`worktreeStatus` and `releaseBranchReservation`) and their input and value records (`Worktree`, `WorktreeAddInput`, +`CommitInput`, `WorktreeStatus`) +|`JGitWorktreeOperations` |The implementation of `WorktreeOperations` on JGit, in process and without a `git` +installation; every repository it opens is built on `RefusingFS` +|`LinkedWorktrees` |The administration files of Git's linked working trees, read and written natively (package-private) +|=== + +The log messages of the working-tree operations are records of `GitCoreLogMessages`, catalogued in +`git-core/doc/LogMessages.adoc` (xref:general.adoc#GDR-GEN-4[GDR-GEN-4]). + +Every operation returns a `GitResult` with one constant of `GitOutcome` +(xref:general.adoc#GDR-GEN-3[GDR-GEN-3]). A refused capability (a present hook, a filter driver that would start a +process) is `REFUSED_BY_POLICY` with the capability as detail; every other unexpected failure is `FAILED` with the +failure class only. No operation starts a process through the repository's `RefusingFS`; that the library starts no +process at all holds under the condition of <>: JGit reads the configuration through its process-wide +`SystemReader`, which the operations do not replace, and the default reader runs `git` once per JVM, so no process +starts only where the application installed `RefusingFS.systemReader(SystemReader)` before any JGit use. No detail and +no log message carries an author or committer name, an e-mail address or a commit message, and no log message carries +a path or an administrative name derived from it (xref:general.adoc#GDR-NFR-3[GDR-NFR-3]). + +[#GDR-CORE-12] +=== GDR-CORE-12: Linked Working Trees + +* The library must add, list and remove linked working trees. +* The administration files must follow Git's own layout, so that `git worktree list` of a Git installation lists the + working trees the library created. + +`worktreeAdd` creates a linked working tree for a branch, or detached at a commit, at a path inside the main working +tree and writes the administration directory `$GIT_DIR/worktrees//` with `gitdir` (the absolute path back to the +working tree's `.git` file), `commondir` (the path of the main repository's `$GIT_DIR`) and `HEAD`, and in the working +tree the `.git` file holding `gitdir: ` that points to the administration directory +(link:https://git-scm.com/docs/gitrepository-layout[gitrepository-layout(5)], entries `worktrees`, +`worktrees//gitdir` and `commondir`; link:https://git-scm.com/docs/git-worktree[git-worktree(1)], DETAILS). The +start point and the branch are classified by `GitIdentity` (<>): only `HEAD`, exactly one reference or a +full commit id is resolved, an abbreviated or unknown start point never, also not for an existing branch. + +Before an addition claims anything it is guarded in this order: the root must be the main working tree, not a linked +one (`PATH_REFUSED`); the branch, new or existing, must form a valid reference name `refs/heads/` by JGit 7.8.0 +`Repository.isValidRefName` (`REFUSED_BY_POLICY`, the detail naming the field, never the string); the target must lie +inside the root, outside the common directory with its administration area `worktrees/` and outside every registered +linked working tree, compared by real paths (`PATH_REFUSED`). Only then is the start point classified and the target +claimed. + +Concurrent additions on one repository do not interfere: + +* The target is claimed exclusively: a missing target directory is created with `Files.createDirectory`, and in it, or + in a caller-supplied empty directory, the `.git` file is created with `Files.createFile`; a lost claim ends + `ALREADY_EXISTS`. +* Every branch, a new one like an existing one, is reserved before it is checked, by the reservation file + `worktree-branch-.lock` in the common directory, created with `Files.createFile`, until + the new working tree is checked out and unlocked, or, for a refused or failed addition, until its rollback has + deleted the branch it created; a branch another addition reserved ends `BRANCH_CHECKED_OUT`. A new branch is + created by a compare-and-swap from the zero id. A reservation left by a process that ended during an addition stays + until <> releases it. +* The administration directory is claimed atomically under the next free numeric suffix; its files are written + completely before they appear under their names, `HEAD` last, and it stays locked while the start commit is checked + out. +* A refused or failed addition removes what it created and nothing else: the target directory it created or what it + wrote into a caller-supplied one, its administration directory, its reservation, and the branch it created, the + latter only while it still points at the start commit, so a retry succeeds. JGit 7.8.0 `RefUpdate.delete` returns + `LOCK_FAILURE` both for a held reference lock and for a branch no longer at the expected commit, so after a lock + failure or a rejection the branch is read again: an absent branch was deleted, a branch at another commit was + advanced by another writer and is kept, and a branch still at the start commit is left behind and reported as an + incomplete rollback, logged as `GIT_CORE-104`, never silently. An unchecked exception during an addition is + rolled back in the same way and ends as a result, `FAILED` with the failure class. + +`worktreeList` skips an administration directory whose `gitdir` or `HEAD` is not present, one being initialized or +removed, so it does not fail the list or the removal of another working tree; a locked working tree with complete files +is listed. A relative `gitdir` is resolved against the administration directory. + +[cols="1,3"] +|=== +|Operation |Outcomes + +|`worktreeAdd` |`OK` with the new working tree; `ALREADY_EXISTS` for a non-empty path, a target claimed by another +addition or an existing branch to create; `BRANCH_CHECKED_OUT` for a branch checked out in the main or another linked +working tree, also for a branch another addition reserved; `NOT_FOUND` for an unknown branch or an unknown, absent or +abbreviated start point; `AMBIGUOUS` with the candidates; `IDENTITY_MISMATCH` for a full commit id the existing branch +is not at, or one that reaches another commit; `PATH_REFUSED` for a path outside the main working tree or the main +working tree itself, for a root that is a linked working tree, and for a target inside the common directory, its +administration area or another linked working tree; `REFUSED_BY_POLICY` for a branch name that is no valid branch name +and for a refused capability; `NOT_A_REPOSITORY`; `FAILED`. A refused or failed checkout leaves neither the working +tree nor its administration directory behind. +|`worktreeList` |`OK` with the main working tree first, then the linked working trees by administrative name, each with +its branch, its `HEAD` where recorded as a commit id, and whether it is locked or prunable; `NOT_A_REPOSITORY`; +`FAILED`, also for a repository without a working tree +|`worktreeRemove` |`OK` with the removed root, deleting the clean working tree and its administration directory, a +prunable one by its administration directory only, so a directory that reuses its path is kept; `WORKTREE_NOT_FOUND`, +also when the repository at the registered path is not the registered working tree; `WORKTREE_DIRTY`; +`WORKTREE_LOCKED`; `PATH_REFUSED` for the main working tree; `REFUSED_BY_POLICY`; `NOT_A_REPOSITORY`; `FAILED`, also +for a repository without a working tree. The registered paths are compared as real paths, and a working tree +registered through a symbolic link is deleted at its real root. The removal is never forced. +|=== + +The caller of `worktreeRemove` guarantees exclusive use of the working tree until the call returns: the check that the +working tree is clean and its deletion cannot be made one atomic step, so a change written in between is deleted with +it. + +`JGitWorktreeOperationsTest` covers every outcome of the three operations, the guards (`invalidBranchNameRefused`, +`linkedRootRefused`, `targetInsideAdministrationRefused`), the reservation of new and existing branches +(`reservedBranchCheckedOut`, `concurrentAdditions`), the comparison by real paths (`removeThroughSymlink`, +`replacedRepositoryAndReusedPath`) and the result contract (`bareRepositoryFails`, `uncheckedFailureRolledBack`, +`branchDeletionResultRead`, `reservationOutlivesRollback`, `heldRefLockReported`). `GitWorktreeListCompatibilityTest` +asserts that `git worktree list --porcelain` of an installed Git lists the added working trees with path, branch and +`HEAD`, a locked one `locked` and one whose directory is gone `prunable`, and that `git worktree remove` removes a +working tree the library added. It is skipped through a JUnit assumption when no `git` binary is found; only this test +starts a process, never the library. + +[#GDR-CORE-13] +=== GDR-CORE-13: Commit from a Working Tree + +* The library must stage every change of a working tree (changed, untracked and deleted files) and commit it in one + operation, with caller-supplied author, committer and message. + +`commit` stages every addition, modification and deletion of the main or a linked working tree and commits it on the +working tree's branch, never signed, whatever the repository configuration asks. Its outcomes are `OK` with the commit, +`NOTHING_TO_COMMIT`, `REFUSED_BY_POLICY` for a present hook, which is never run (`RefusingFS`), `NOT_A_REPOSITORY` and +`FAILED`, also for a repository without a working tree. + +* *Hooks.* JGit 7.8.0 `CommitCommand` runs the `post-commit` hook after it updated the branch and only logs its + failure + (link:https://github.com/eclipse-jgit/jgit/blob/v7.8.0.202609011348-r/org.eclipse.jgit/src/org/eclipse/jgit/api/CommitCommand.java[JGit 7.8.0 `CommitCommand`]), + so `commit` looks up the `pre-commit`, `commit-msg` and `post-commit` hooks first, with `FS.findHook` of the + repository's `RefusingFS`, and a present one ends `REFUSED_BY_POLICY` before anything is staged; `RefusingFS` stays + the guard against running one. +* *Linked roots.* JGit 7.8.0 `FileTreeIterator` reports a directory holding a `.git` entry as a gitlink, which + `AddCommand` stages + (link:https://github.com/eclipse-jgit/jgit/blob/v7.8.0.202609011348-r/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/FileTreeIterator.java[JGit 7.8.0 `FileTreeIterator`]), + so `commit` removes the root of every registered linked working tree inside the committing one from its index + before the commit. +* *Reflog.* JGit 7.8.0 `RefDirectory.logFor("HEAD")` resolves to the `logs/HEAD` of the common directory + (link:https://github.com/eclipse-jgit/jgit/blob/v7.8.0.202609011348-r/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/RefDirectory.java[JGit 7.8.0 `RefDirectory`]), + the reflog of the main working tree, so a commit in a linked working tree runs without JGit's reflog and writes its + `HEAD` entry to `logs/HEAD` of the linked working tree's own git directory and its branch entry to the branch's log + in the common directory: `HEAD` is a ref of each working tree, the branches are shared + (link:https://git-scm.com/docs/git-worktree[git-worktree(1)], REFS). The commit and its branch are stored before + these entries are appended, so an entry that cannot be written does not fail the created commit: the result stays + `OK` with the commit, and the omission is logged as `GIT_CORE-103` with the commit id only. An invalid + `core.logAllRefUpdates` value is such a case: JGit 7.8.0 `Config.getEnum` throws `IllegalArgumentException` for a + value that names no constant of `CoreConfig.LogRefUpdates`. + +The commit tests of `JGitWorktreeOperationsTest` cover each outcome, `reflogFailureKeepsCommit` and +`invalidLogAllRefUpdatesKeepsCommit` the reflog choice, and its secrets test asserts with a JUL log capture and on the +result details that no author or committer name, e-mail address or message reaches a log message or a detail, and no +raw working-tree path an INFO message. + +[#GDR-CORE-14] +=== GDR-CORE-14: Working-Tree Status + +* The library must report the status of a working tree as three path sets: `changed` (tracked and modified), + `untracked` (present and not tracked) and `deleted` (tracked and missing). +* The status must consist of these three path sets and nothing else. + +`worktreeStatus` returns the record `WorktreeStatus(changed, untracked, deleted)`: three unmodifiable sets of +repository-relative paths with `/` separators, sorted by path; its outcomes are `OK`, `REFUSED_BY_POLICY`, +`NOT_A_REPOSITORY` and `FAILED`, also for a repository without a working tree. `REFUSED_BY_POLICY` follows from the +`RefusingFS` guarantee: the repository is opened on `RefusingFS`, so a capability the policy refuses, such as a process +start, reaches the caller as `REFUSED_BY_POLICY` with the capability as detail (<>). The sets are mapped +from JGit's `Status` by its definitions in JGit 7.8.0 +(link:https://github.com/eclipse-jgit/jgit/blob/v7.8.0.202609011348-r/org.eclipse.jgit/src/org/eclipse/jgit/api/Status.java[`org.eclipse.jgit.api.Status`]): + +[cols="1,3"] +|=== +|Set |JGit `Status` categories + +|`changed` |`getAdded` (in the index, not in `HEAD`), `getChanged` (changed from `HEAD` to the index), `getModified` +(modified on disk relative to the index), `getConflicting` (in conflict) +|`deleted` |`getRemoved` (in `HEAD`, not in the index), `getMissing` (in the index, not on disk) +|`untracked` |`getUntracked` (neither ignored nor in the index) +|=== + +Ignored files are in no set. The sets are not disjoint: a file removed from the index but still on disk is both removed +and untracked, so it is in `deleted` and in `untracked`. The union of the three sets is the path union of the seven +categories, the digest input a consumer such as `WorktreeShaDigest` of `pm-provider-git` builds on. + +Two behaviours of JGit 7.8.0 are settled by observation, each pinned by a test of `WorktreeStatusTest`: + +* *Clean filter.* `StatusCommand` runs the clean filter of a driver configured through the repository's own + `.gitattributes` when it compares the content of a tracked file whose modification time no longer matches the + index, so the refusal of its process is reachable through `worktreeStatus`: the status ends `REFUSED_BY_POLICY` + with `process_execution` (`cleanFilterRefused`). +* *Nested linked root.* For a linked working tree registered inside the main working tree, `worktreeStatus` of the + main working tree lists the linked root as untracked, since `FileTreeIterator` reports it as a gitlink, while + `commit` of the main working tree removes every registered linked root from the index (<>) and ends + `NOTHING_TO_COMMIT` (`nestedLinkedRootStatusAgainstCommit`). The divergence is accepted: the status reports the + working tree as JGit sees it, and leaving the linked roots out is a rule of the commit alone. + +`WorktreeStatusTest` covers one scenario per category and the union; `WorktreeOperationsRecordsTest` covers the +record's null checks, its equality over the paths, its defensive copy and its immutability. + +[#GDR-CORE-15] +=== GDR-CORE-15: Release of a Branch Reservation + +* The library must release the reservation of a branch left by an addition that did not finish, deleting the + reservation and nothing else. +* The release must start no process (<>). + +An addition reserves its branch with the reservation file `worktree-branch-.lock` in +the common directory (<>); the name is the hash of `refs/heads/`, so no caller string forms a file +name. A process that ends between the reservation and its release leaves the file behind, and every later addition of +that branch ends `BRANCH_CHECKED_OUT` although no working tree has it checked out. + +`releaseBranchReservation(root, branch)` takes any working-tree root of the repository and the short branch name as +given to `worktreeAdd`; both are required. It opens the repository on `RefusingFS`, guards the branch name before any +path is derived from it, and deletes the reservation file in the real common directory with one atomic `Files.delete`, +so of two concurrent releases exactly one reports it. + +[cols="1,3"] +|=== +|Outcome |When + +|`OK` |The reservation was deleted; the value is the full branch name `refs/heads/` +|`NOT_FOUND` |The branch has no reservation; the detail is `branch: no reservation` +|`REFUSED_BY_POLICY` |The branch name is no valid branch name by JGit 7.8.0 `Repository.isValidRefName`; the detail +names the field only, and no file is deleted +|`NOT_A_REPOSITORY` |The root holds no repository +|`FAILED` |An I/O failure, also a repository without a working tree, with the failure class only +|=== + +The caller guarantees that no addition of that branch runs, in any process, from the call until it returns. This is a +precondition rather than a check: a reservation held by a running addition cannot be told apart from one a crashed +process left without inspecting processes, which the library does not do, so releasing a live reservation would let a +second addition of the branch past its check. A release is logged as `GIT_CORE-4`, which carries no argument, neither +the branch name nor a path (xref:general.adoc#GDR-NFR-3[GDR-NFR-3]). + +The nested test group `ReleaseBranchReservation` of `JGitWorktreeOperationsTest` covers the crashed-process scenario +(`crashedProcessRecovered`: the left reservation blocks the addition, the release returns `OK`, the addition succeeds +again, and the log carries `GIT_CORE-4` without branch name or path), `noReservation`, `invalidBranchNameRefused`, +`notARepository`, `bareRepositoryFails`, the release from a linked root (`fromLinkedRoot`) and the release of the +named reservation only (`onlyNamedReservation`). + [#tests] == Tests diff --git a/doc/specification/git-worktrees.adoc b/doc/specification/git-worktrees.adoc deleted file mode 100644 index efa62db..0000000 --- a/doc/specification/git-worktrees.adoc +++ /dev/null @@ -1,255 +0,0 @@ -= git-document-repository: `git-worktrees` -:toc: left -:toclevels: 2 -:toc-title: Table of Contents -:source-highlighter: highlight.js - -`git-worktrees` holds the linked working trees: module and package `de.cuioss.git.document.worktrees`. It depends on -`git-core` alone; its third-party dependencies are `cui-java-tools` for `CuiLogger`, Lombok (scope `provided`) and -`org.jspecify:jspecify`, see xref:general.adoc#GDR-GEN-1[GDR-GEN-1]. The document store does not use it; clients that -work on files on disk do. <>, <>, <> and <> are implemented. The JGit APIs -named here are -checked against JGit 7.8.0 (tag `v7.8.0.202609011348-r` of https://github.com/eclipse-jgit/jgit). JGit 7.8.0 has no -command that creates a linked working tree: its `api` package holds no worktree command -(link:https://github.com/eclipse-jgit/jgit/tree/v7.8.0.202609011348-r/org.eclipse.jgit/src/org/eclipse/jgit/api[JGit 7.8.0 `api` package]), -so the module reads and writes Git's administration files of linked working trees itself. `LinkedWorktrees` is taken -from `pm-provider-git` and changed where <> demands it -(xref:../clients/pm-mcp-core.adoc#_what_git_worktrees_took_and_changed[Client: `pm-mcp-core`, What `git-worktrees` -Took and Changed]). Rationale: -xref:../concepts/module-structure.adoc#_the_foundation_modules[Module Structure, The Foundation Modules]. - -[cols="1,3"] -|=== -|Type |Role - -|`WorktreeOperations` |The working-tree operations below (`worktreeAdd`, `worktreeList`, `worktreeRemove`, `commit`, -`worktreeStatus` and `releaseBranchReservation`) and their input and value records (`Worktree`, `WorktreeAddInput`, -`CommitInput`, `WorktreeStatus`) -|`JGitWorktreeOperations` |The implementation of `WorktreeOperations` on JGit, in process and without a `git` -installation; every repository it opens is built on `RefusingFS` of `git-core` -|`LinkedWorktrees` |The administration files of Git's linked working trees, read and written natively (package-private) -|`GitWorktreesLogMessages` |The `LogRecord` holder of the module, catalogued in `git-worktrees/doc/LogMessages.adoc` -(xref:general.adoc#GDR-GEN-4[GDR-GEN-4]) -|=== - -Every operation returns a `GitResult` with one constant of `GitOutcome` of `git-core` -(xref:general.adoc#GDR-GEN-3[GDR-GEN-3]). A refused capability (a present hook, a filter driver that would start a -process) is `REFUSED_BY_POLICY` with the capability as detail; every other unexpected failure is `FAILED` with the -failure class only. No operation starts a process through the repository's `RefusingFS`; that the library starts no -process at all holds under the condition of xref:git-core.adoc#GDR-CORE-1[GDR-CORE-1]: JGit reads the configuration -through its process-wide `SystemReader`, which the operations do not replace, and the default reader runs `git` once -per JVM, so no process starts only where the application installed `RefusingFS.systemReader(SystemReader)` before any -JGit use. No detail and no log message carries an author or committer name, an e-mail address or a commit message, -and no log message carries a path or an administrative name derived from it -(xref:general.adoc#GDR-NFR-3[GDR-NFR-3]). - -[#GDR-WT-1] -== GDR-WT-1: Linked Working Trees - -* The library must add, list and remove linked working trees. -* The administration files must follow Git's own layout, so that `git worktree list` of a Git installation lists the - working trees the library created. - -`worktreeAdd` creates a linked working tree for a branch, or detached at a commit, at a path inside the main working -tree and writes the administration directory `$GIT_DIR/worktrees//` with `gitdir` (the absolute path back to the -working tree's `.git` file), `commondir` (the path of the main repository's `$GIT_DIR`) and `HEAD`, and in the working -tree the `.git` file holding `gitdir: ` that points to the administration directory -(link:https://git-scm.com/docs/gitrepository-layout[gitrepository-layout(5)], entries `worktrees`, -`worktrees//gitdir` and `commondir`; link:https://git-scm.com/docs/git-worktree[git-worktree(1)], DETAILS). The -start point and the branch are classified by `GitIdentity` of `git-core`: only `HEAD`, exactly one reference or a full -commit id is resolved, an abbreviated or unknown start point never, also not for an existing branch. - -Before an addition claims anything it is guarded in this order: the root must be the main working tree, not a linked -one (`PATH_REFUSED`); the branch, new or existing, must form a valid reference name `refs/heads/` by JGit 7.8.0 -`Repository.isValidRefName` (`REFUSED_BY_POLICY`, the detail naming the field, never the string); the target must lie -inside the root, outside the common directory with its administration area `worktrees/` and outside every registered -linked working tree, compared by real paths (`PATH_REFUSED`). Only then is the start point classified and the target -claimed. - -Concurrent additions on one repository do not interfere: - -* The target is claimed exclusively: a missing target directory is created with `Files.createDirectory`, and in it, or - in a caller-supplied empty directory, the `.git` file is created with `Files.createFile`; a lost claim ends - `ALREADY_EXISTS`. -* Every branch, a new one like an existing one, is reserved before it is checked, by the reservation file - `worktree-branch-.lock` in the common directory, created with `Files.createFile`, until - the new working tree is checked out and unlocked, or, for a refused or failed addition, until its rollback has - deleted the branch it created; a branch another addition reserved ends `BRANCH_CHECKED_OUT`. A new branch is - created by a compare-and-swap from the zero id. A reservation left by a process that ended during an addition stays - until <> releases it. -* The administration directory is claimed atomically under the next free numeric suffix; its files are written - completely before they appear under their names, `HEAD` last, and it stays locked while the start commit is checked - out. -* A refused or failed addition removes what it created and nothing else: the target directory it created or what it - wrote into a caller-supplied one, its administration directory, its reservation, and the branch it created, the - latter only while it still points at the start commit, so a retry succeeds. JGit 7.8.0 `RefUpdate.delete` returns - `LOCK_FAILURE` both for a held reference lock and for a branch no longer at the expected commit, so after a lock - failure or a rejection the branch is read again: an absent branch was deleted, a branch at another commit was - advanced by another writer and is kept, and a branch still at the start commit is left behind and reported as an - incomplete rollback, logged as `GIT_WORKTREES-102`, never silently. An unchecked exception during an addition is - rolled back in the same way and ends as a result, `FAILED` with the failure class. - -`worktreeList` skips an administration directory whose `gitdir` or `HEAD` is not present, one being initialized or -removed, so it does not fail the list or the removal of another working tree; a locked working tree with complete files -is listed. A relative `gitdir` is resolved against the administration directory. - -[cols="1,3"] -|=== -|Operation |Outcomes - -|`worktreeAdd` |`OK` with the new working tree; `ALREADY_EXISTS` for a non-empty path, a target claimed by another -addition or an existing branch to create; `BRANCH_CHECKED_OUT` for a branch checked out in the main or another linked -working tree, also for a branch another addition reserved; `NOT_FOUND` for an unknown branch or an unknown, absent or -abbreviated start point; `AMBIGUOUS` with the candidates; `IDENTITY_MISMATCH` for a full commit id the existing branch -is not at, or one that reaches another commit; `PATH_REFUSED` for a path outside the main working tree or the main -working tree itself, for a root that is a linked working tree, and for a target inside the common directory, its -administration area or another linked working tree; `REFUSED_BY_POLICY` for a branch name that is no valid branch name -and for a refused capability; `NOT_A_REPOSITORY`; `FAILED`. A refused or failed checkout leaves neither the working -tree nor its administration directory behind. -|`worktreeList` |`OK` with the main working tree first, then the linked working trees by administrative name, each with -its branch, its `HEAD` where recorded as a commit id, and whether it is locked or prunable; `NOT_A_REPOSITORY`; -`FAILED`, also for a repository without a working tree -|`worktreeRemove` |`OK` with the removed root, deleting the clean working tree and its administration directory, a -prunable one by its administration directory only, so a directory that reuses its path is kept; `WORKTREE_NOT_FOUND`, -also when the repository at the registered path is not the registered working tree; `WORKTREE_DIRTY`; -`WORKTREE_LOCKED`; `PATH_REFUSED` for the main working tree; `REFUSED_BY_POLICY`; `NOT_A_REPOSITORY`; `FAILED`, also -for a repository without a working tree. The registered paths are compared as real paths, and a working tree -registered through a symbolic link is deleted at its real root. The removal is never forced. -|=== - -The caller of `worktreeRemove` guarantees exclusive use of the working tree until the call returns: the check that the -working tree is clean and its deletion cannot be made one atomic step, so a change written in between is deleted with -it. - -`JGitWorktreeOperationsTest` covers every outcome of the three operations, the guards (`invalidBranchNameRefused`, -`linkedRootRefused`, `targetInsideAdministrationRefused`), the reservation of new and existing branches -(`reservedBranchCheckedOut`, `concurrentAdditions`), the comparison by real paths (`removeThroughSymlink`, -`replacedRepositoryAndReusedPath`) and the result contract (`bareRepositoryFails`, `uncheckedFailureRolledBack`, -`branchDeletionResultRead`, `reservationOutlivesRollback`, `heldRefLockReported`). `GitWorktreeListCompatibilityTest` asserts that `git worktree list --porcelain` of an -installed Git lists the added working trees with path, branch and `HEAD`, a locked one `locked` and one whose directory -is gone `prunable`, and that `git worktree remove` removes a working tree the library added. It is skipped through a -JUnit assumption when no `git` binary is found; only this test starts a process, never the library. - -[#GDR-WT-2] -== GDR-WT-2: Commit from a Working Tree - -* The library must stage every change of a working tree (changed, untracked and deleted files) and commit it in one - operation, with caller-supplied author, committer and message. - -`commit` stages every addition, modification and deletion of the main or a linked working tree and commits it on the -working tree's branch, never signed, whatever the repository configuration asks. Its outcomes are `OK` with the commit, -`NOTHING_TO_COMMIT`, `REFUSED_BY_POLICY` for a present hook, which is never run (`RefusingFS` of `git-core`), -`NOT_A_REPOSITORY` and `FAILED`, also for a repository without a working tree. - -* *Hooks.* JGit 7.8.0 `CommitCommand` runs the `post-commit` hook after it updated the branch and only logs its - failure - (link:https://github.com/eclipse-jgit/jgit/blob/v7.8.0.202609011348-r/org.eclipse.jgit/src/org/eclipse/jgit/api/CommitCommand.java[JGit 7.8.0 `CommitCommand`]), - so `commit` looks up the `pre-commit`, `commit-msg` and `post-commit` hooks first, with `FS.findHook` of the - repository's `RefusingFS`, and a present one ends `REFUSED_BY_POLICY` before anything is staged; `RefusingFS` stays - the guard against running one. -* *Linked roots.* JGit 7.8.0 `FileTreeIterator` reports a directory holding a `.git` entry as a gitlink, which - `AddCommand` stages - (link:https://github.com/eclipse-jgit/jgit/blob/v7.8.0.202609011348-r/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/FileTreeIterator.java[JGit 7.8.0 `FileTreeIterator`]), - so `commit` removes the root of every registered linked working tree inside the committing one from its index - before the commit. -* *Reflog.* JGit 7.8.0 `RefDirectory.logFor("HEAD")` resolves to the `logs/HEAD` of the common directory - (link:https://github.com/eclipse-jgit/jgit/blob/v7.8.0.202609011348-r/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/RefDirectory.java[JGit 7.8.0 `RefDirectory`]), - the reflog of the main working tree, so a commit in a linked working tree runs without JGit's reflog and writes its - `HEAD` entry to `logs/HEAD` of the linked working tree's own git directory and its branch entry to the branch's log - in the common directory: `HEAD` is a ref of each working tree, the branches are shared - (link:https://git-scm.com/docs/git-worktree[git-worktree(1)], REFS). The commit and its branch are stored before - these entries are appended, so an entry that cannot be written does not fail the created commit: the result stays - `OK` with the commit, and the omission is logged as `GIT_WORKTREES-101` with the commit id only. An invalid - `core.logAllRefUpdates` value is such a case: JGit 7.8.0 `Config.getEnum` throws `IllegalArgumentException` for a - value that names no constant of `CoreConfig.LogRefUpdates`. - -The commit tests of `JGitWorktreeOperationsTest` cover each outcome, `reflogFailureKeepsCommit` and -`invalidLogAllRefUpdatesKeepsCommit` the reflog choice, and -its secrets test asserts with a JUL log -capture and on the result details that no author or committer name, e-mail address or message reaches a log message or -a detail, and no raw working-tree path an INFO message. - -[#GDR-WT-3] -== GDR-WT-3: Working-Tree Status - -* The library must report the status of a working tree as three path sets: `changed` (tracked and modified), - `untracked` (present and not tracked) and `deleted` (tracked and missing). -* The status must consist of these three path sets and nothing else. - -`worktreeStatus` returns the record `WorktreeStatus(changed, untracked, deleted)`: three unmodifiable sets of -repository-relative paths with `/` separators, sorted by path; its outcomes are `OK`, `REFUSED_BY_POLICY`, -`NOT_A_REPOSITORY` and `FAILED`, also for a repository without a working tree. `REFUSED_BY_POLICY` follows from the -`RefusingFS` guarantee: the repository is opened on `RefusingFS`, so a capability the policy refuses, such as a process -start, reaches the caller as `REFUSED_BY_POLICY` with the capability as detail -(xref:git-core.adoc#GDR-CORE-1[GDR-CORE-1]). The sets are mapped from JGit's `Status` by its definitions in JGit 7.8.0 -(link:https://github.com/eclipse-jgit/jgit/blob/v7.8.0.202609011348-r/org.eclipse.jgit/src/org/eclipse/jgit/api/Status.java[`org.eclipse.jgit.api.Status`]): - -[cols="1,3"] -|=== -|Set |JGit `Status` categories - -|`changed` |`getAdded` (in the index, not in `HEAD`), `getChanged` (changed from `HEAD` to the index), `getModified` -(modified on disk relative to the index), `getConflicting` (in conflict) -|`deleted` |`getRemoved` (in `HEAD`, not in the index), `getMissing` (in the index, not on disk) -|`untracked` |`getUntracked` (neither ignored nor in the index) -|=== - -Ignored files are in no set. The sets are not disjoint: a file removed from the index but still on disk is both removed -and untracked, so it is in `deleted` and in `untracked`. The union of the three sets is the path union of the seven -categories, the digest input a consumer such as `WorktreeShaDigest` of `pm-provider-git` builds on. - -Two behaviours of JGit 7.8.0 are settled by observation, each pinned by a test of `WorktreeStatusTest`: - -* *Clean filter.* `StatusCommand` runs the clean filter of a driver configured through the repository's own - `.gitattributes` when it compares the content of a tracked file whose modification time no longer matches the - index, so the refusal of its process is reachable through `worktreeStatus`: the status ends `REFUSED_BY_POLICY` - with `process_execution` (`cleanFilterRefused`). -* *Nested linked root.* For a linked working tree registered inside the main working tree, `worktreeStatus` of the - main working tree lists the linked root as untracked, since `FileTreeIterator` reports it as a gitlink, while - `commit` of the main working tree removes every registered linked root from the index (<>) and ends - `NOTHING_TO_COMMIT` (`nestedLinkedRootStatusAgainstCommit`). The divergence is accepted: the status reports the - working tree as JGit sees it, and leaving the linked roots out is a rule of the commit alone. - -`WorktreeStatusTest` covers one scenario per category and the union; `WorktreeOperationsRecordsTest` covers the -record's null checks, its equality over the paths, its defensive copy and its immutability. - -[#GDR-WT-4] -== GDR-WT-4: Release of a Branch Reservation - -* The library must release the reservation of a branch left by an addition that did not finish, deleting the - reservation and nothing else. -* The release must start no process (xref:git-core.adoc#GDR-CORE-1[GDR-CORE-1]). - -An addition reserves its branch with the reservation file `worktree-branch-.lock` in -the common directory (<>); the name is the hash of `refs/heads/`, so no caller string forms a file -name. A process that ends between the reservation and its release leaves the file behind, and every later addition of -that branch ends `BRANCH_CHECKED_OUT` although no working tree has it checked out. - -`releaseBranchReservation(root, branch)` takes any working-tree root of the repository and the short branch name as -given to `worktreeAdd`; both are required. It opens the repository on `RefusingFS`, guards the branch name before any -path is derived from it, and deletes the reservation file in the real common directory with one atomic `Files.delete`, -so of two concurrent releases exactly one reports it. - -[cols="1,3"] -|=== -|Outcome |When - -|`OK` |The reservation was deleted; the value is the full branch name `refs/heads/` -|`NOT_FOUND` |The branch has no reservation; the detail is `branch: no reservation` -|`REFUSED_BY_POLICY` |The branch name is no valid branch name by JGit 7.8.0 `Repository.isValidRefName`; the detail -names the field only, and no file is deleted -|`NOT_A_REPOSITORY` |The root holds no repository -|`FAILED` |An I/O failure, also a repository without a working tree, with the failure class only -|=== - -The caller guarantees that no addition of that branch runs, in any process, from the call until it returns. This is a -precondition rather than a check: a reservation held by a running addition cannot be told apart from one a crashed -process left without inspecting processes, which the library does not do, so releasing a live reservation would let a -second addition of the branch past its check. A release is logged as `GIT_WORKTREES-3`, which carries no argument, -neither the branch name nor a path (xref:general.adoc#GDR-NFR-3[GDR-NFR-3]). - -The nested test group `ReleaseBranchReservation` of `JGitWorktreeOperationsTest` covers the crashed-process scenario -(`crashedProcessRecovered`: the left reservation blocks the addition, the release returns `OK`, the addition succeeds -again, and the log carries `GIT_WORKTREES-3` without branch name or path), `noReservation`, `invalidBranchNameRefused`, -`notARepository`, `bareRepositoryFails`, the release from a linked root (`fromLinkedRoot`) and the release of the -named reservation only (`onlyNamedReservation`). diff --git a/git-core/doc/LogMessages.adoc b/git-core/doc/LogMessages.adoc index e6c1087..26602f2 100644 --- a/git-core/doc/LogMessages.adoc +++ b/git-core/doc/LogMessages.adoc @@ -5,13 +5,16 @@ == Overview The log-message catalogue of `git-core` -(xref:../../doc/specification/general.adoc#GDR-GEN-4[GDR-GEN-4]). Every message at level INFO, WARN or ERROR carries a -stable identifier of the form `GIT_CORE-`, rendered by `LogRecord#resolveIdentifierString()` without -leading zeros; the identifiers follow the CUI `LogRecord` ranges (INFO 1-99, -WARN 100-199, ERROR 200-299). The messages are declared in `de.cuioss.git.document.core.GitCoreLogMessages`. +(xref:../../doc/specification/general.adoc#GDR-GEN-4[GDR-GEN-4]), for both its packages: the repository part in +`de.cuioss.git.document.core` and the working-tree part in `de.cuioss.git.document.core.worktrees`. Every message at +level INFO, WARN or ERROR carries a stable identifier of the form `GIT_CORE-`, rendered by +`LogRecord#resolveIdentifierString()` without leading zeros; the identifiers follow the CUI `LogRecord` ranges (INFO +1-99, WARN 100-199, ERROR 200-299). The messages are declared in `de.cuioss.git.document.core.GitCoreLogMessages`. No message carries anything xref:../../doc/specification/general.adoc#GDR-NFR-3[GDR-NFR-3] forbids: a URL is rendered -without user information, and neither a credential nor a JGit message that may carry one is logged. Debug and trace +without user information, and neither a credential nor a JGit message that may carry one is logged. A message of the +working-tree part names a commit id or a refused capability, never a path, an administrative name derived from the +caller's path, a branch name, an author or committer name, an e-mail address or a commit message. Debug and trace messages carry no identifier and are not listed. == INFO Level (1-99) @@ -21,6 +24,12 @@ messages carry no identifier and are not listed. |ID |Component |Message |Description |GIT_CORE-1 |GIT_CORE |Created bare clone at %s from %s |Logged when `cloneIfMissing` created a bare clone: the git directory and the URL of the remote without user information. +|GIT_CORE-2 |GIT_CORE |Added a linked working tree at commit %s |Logged when `worktreeAdd` created a linked working +tree: the commit id it starts at. +|GIT_CORE-3 |GIT_CORE |Removed a linked working tree |Logged when `worktreeRemove` removed a linked working tree or +the administration files of a prunable one; the message carries no argument. +|GIT_CORE-4 |GIT_CORE |Released a branch reservation |Logged when `releaseBranchReservation` deleted the reservation +file of a branch; the message carries no argument, neither the branch name nor a path. |=== == WARN Level (100-199) @@ -33,6 +42,16 @@ before any contact because the remote policy does not admit the URL (shown witho `REFUSED_BY_POLICY`. |GIT_CORE-101 |GIT_CORE |Refused capability %s |Logged when the refusing file system refused a capability, a present hook (`repository_hook`) or a process start (`process_execution`); the result is `REFUSED_BY_POLICY`. +|GIT_CORE-102 |GIT_CORE |Refused capability %s |Logged when the refusing file system refused a capability during a +working-tree operation, a present hook (`repository_hook`) or a process start (`process_execution`); the result is +`REFUSED_BY_POLICY`. +|GIT_CORE-103 |GIT_CORE |Created commit %s, its reflog entry was not written |Logged when `commit` created a commit in +a linked working tree but could not append its reflog entries: the commit id only. The commit and its branch are +stored, so the result stays `OK` with the commit. +|GIT_CORE-104 |GIT_CORE |The rollback of a failed working-tree addition is incomplete |Logged when the rollback of a +refused or failed `worktreeAdd` could not undo everything the addition created, for example a created branch still at +its start commit that could not be deleted; the message carries no argument, neither the branch name nor a path. The +addition ends `FAILED` or with the outcome of the failure it rolled back. |=== == ERROR Level (200-299) diff --git a/git-core/pom.xml b/git-core/pom.xml index 20b1d3d..bb44c17 100644 --- a/git-core/pom.xml +++ b/git-core/pom.xml @@ -11,7 +11,7 @@ git-core jar git-core - Hardened Git repositories, remote policy, identity, results, transport, reading, cache repository and in-core writing on JGit. + Hardened Git repositories, remote policy, identity, results, transport, reading, cache repository and in-core writing on JGit, linked working trees, commit from a working tree and working-tree status. de.cuioss.git.document.core diff --git a/git-core/src/main/java/de/cuioss/git/document/core/GitCoreLogMessages.java b/git-core/src/main/java/de/cuioss/git/document/core/GitCoreLogMessages.java index 91d21f1..c6f47dd 100644 --- a/git-core/src/main/java/de/cuioss/git/document/core/GitCoreLogMessages.java +++ b/git-core/src/main/java/de/cuioss/git/document/core/GitCoreLogMessages.java @@ -20,11 +20,15 @@ import lombok.experimental.UtilityClass; /** - * The {@link LogRecord} holder of {@code git-core} (GDR-GEN-4). Identifiers carry the prefix {@value #PREFIX} and - * follow the CUI ranges: INFO 1-99, WARN 100-199, ERROR 200-299. The catalogue is {@code git-core/doc/LogMessages.adoc}. + * The {@link LogRecord} holder of {@code git-core} (GDR-GEN-4), for both its packages: the repository part in + * {@code de.cuioss.git.document.core} and the working-tree part in {@code de.cuioss.git.document.core.worktrees}. + * Identifiers carry the prefix {@value #PREFIX} and follow the CUI ranges: INFO 1-99, WARN 100-199, ERROR 200-299. The + * catalogue is {@code git-core/doc/LogMessages.adoc}. *

* No message carries anything GDR-NFR-3 forbids: a URL is rendered without user information, and neither a - * credential nor a JGit message that may carry one is logged. + * credential nor a JGit message that may carry one is logged. A message of the working-tree part names a commit id or + * a refused capability, never a path, an administrative name derived from the caller's path, a branch name, an author + * or committer name, an e-mail address or a commit message. * * @since 0.1 */ @@ -48,6 +52,29 @@ public static final class INFO { .prefix(PREFIX) .identifier(1) .build(); + + /** A linked working tree was added: the commit it starts at. */ + public static final LogRecord WORKTREE_ADDED = LogRecordModel.builder() + .template("Added a linked working tree at commit %s") + .prefix(PREFIX) + .identifier(2) + .build(); + + /** A linked working tree was removed; the message carries no argument. */ + public static final LogRecord WORKTREE_REMOVED = LogRecordModel.builder() + .template("Removed a linked working tree") + .prefix(PREFIX) + .identifier(3) + .build(); + + /** + * A branch reservation was released; the message carries no argument, neither the branch name nor a path. + */ + public static final LogRecord BRANCH_RESERVATION_RELEASED = LogRecordModel.builder() + .template("Released a branch reservation") + .prefix(PREFIX) + .identifier(4) + .build(); } /** @@ -71,5 +98,32 @@ public static final class WARN { .prefix(PREFIX) .identifier(101) .build(); + + /** + * A capability was refused by the refusing file system during a working-tree operation: the refused + * capability. + */ + public static final LogRecord WORKTREE_CAPABILITY_REFUSED = LogRecordModel.builder() + .template("Refused capability %s") + .prefix(PREFIX) + .identifier(102) + .build(); + + /** A commit was created in a linked working tree but its reflog entry was not written: the commit id. */ + public static final LogRecord REFLOG_NOT_WRITTEN = LogRecordModel.builder() + .template("Created commit %s, its reflog entry was not written") + .prefix(PREFIX) + .identifier(103) + .build(); + + /** + * The rollback of a refused or failed addition did not undo everything it created, for example a created + * branch it could not delete; the message carries no argument, neither the branch name nor a path. + */ + public static final LogRecord ROLLBACK_INCOMPLETE = LogRecordModel.builder() + .template("The rollback of a failed working-tree addition is incomplete") + .prefix(PREFIX) + .identifier(104) + .build(); } } diff --git a/git-core/src/main/java/de/cuioss/git/document/core/GitOutcome.java b/git-core/src/main/java/de/cuioss/git/document/core/GitOutcome.java index 058d5c0..f8f6bb5 100644 --- a/git-core/src/main/java/de/cuioss/git/document/core/GitOutcome.java +++ b/git-core/src/main/java/de/cuioss/git/document/core/GitOutcome.java @@ -20,8 +20,8 @@ *

* Every operation of the foundation whose expected outcomes include a non-success reports one of these constants in * a {@link GitResult}; an expected non-success is never signalled by an exception. The list holds Git outcomes only - * and carries no domain term; it includes the outcomes raised by {@code git-worktrees}. {@link #FAILED} is an I/O - * failure outside the other outcomes. + * and carries no domain term; it includes the outcomes raised by the {@code worktrees} package. {@link #FAILED} is an + * I/O failure outside the other outcomes. * * @since 0.1 */ @@ -95,27 +95,38 @@ public enum GitOutcome { /** Failed: an I/O failure outside the outcomes above. Raised by every operation. */ FAILED, - /** Nothing to commit: a commit from a working tree with nothing staged or changed. Raised by {@code git-worktrees}. */ + /** + * Nothing to commit: a commit from a working tree with nothing staged or changed. Raised by the {@code worktrees} + * package. + */ NOTHING_TO_COMMIT, - /** Already exists: the target path or the branch of a new working tree exists. Raised by {@code git-worktrees}. */ + /** + * Already exists: the target path or the branch of a new working tree exists. Raised by the {@code worktrees} + * package. + */ ALREADY_EXISTS, - /** Branch checked out: the branch is checked out in another working tree. Raised by {@code git-worktrees}. */ + /** + * Branch checked out: the branch is checked out in another working tree. Raised by the {@code worktrees} package. + */ BRANCH_CHECKED_OUT, - /** Working tree not found: no linked working tree at that path. Raised by {@code git-worktrees}. */ + /** Working tree not found: no linked working tree at that path. Raised by the {@code worktrees} package. */ WORKTREE_NOT_FOUND, - /** Working tree dirty: the working tree has uncommitted or untracked changes. Raised by {@code git-worktrees}. */ + /** + * Working tree dirty: the working tree has uncommitted or untracked changes. Raised by the {@code worktrees} + * package. + */ WORKTREE_DIRTY, - /** Working tree locked: the working tree is locked. Raised by {@code git-worktrees}. */ + /** Working tree locked: the working tree is locked. Raised by the {@code worktrees} package. */ WORKTREE_LOCKED, /** - * Path refused: a derived path lies outside the permitted root or is the main working tree. Raised by - * {@code git-worktrees}. + * Path refused: a derived path lies outside the permitted root or is the main working tree. Raised by the + * {@code worktrees} package. */ PATH_REFUSED } diff --git a/git-worktrees/src/main/java/de/cuioss/git/document/worktrees/JGitWorktreeOperations.java b/git-core/src/main/java/de/cuioss/git/document/core/worktrees/JGitWorktreeOperations.java similarity index 98% rename from git-worktrees/src/main/java/de/cuioss/git/document/worktrees/JGitWorktreeOperations.java rename to git-core/src/main/java/de/cuioss/git/document/core/worktrees/JGitWorktreeOperations.java index fde8747..edd6ba7 100644 --- a/git-worktrees/src/main/java/de/cuioss/git/document/worktrees/JGitWorktreeOperations.java +++ b/git-core/src/main/java/de/cuioss/git/document/core/worktrees/JGitWorktreeOperations.java @@ -13,10 +13,10 @@ * See the License for the specific language governing permissions and * limitations under the License. */ -package de.cuioss.git.document.worktrees; +package de.cuioss.git.document.core.worktrees; -import static de.cuioss.git.document.worktrees.GitWorktreesLogMessages.INFO; -import static de.cuioss.git.document.worktrees.GitWorktreesLogMessages.WARN; +import static de.cuioss.git.document.core.GitCoreLogMessages.INFO; +import static de.cuioss.git.document.core.GitCoreLogMessages.WARN; import java.io.File; import java.io.IOException; @@ -80,7 +80,7 @@ * JGit has no command that adds or removes a linked working tree, so the administration files are read and written * natively in git's own layout ({@link LinkedWorktrees}). Every repository is opened with a {@link RefusingFS}, so no * operation starts a process through the repository's file system; an operation that would run a present hook or a - * filter driver ends {@link GitOutcome#REFUSED_BY_POLICY} with the refused capability in the detail (GDR-WT-2). The + * filter driver ends {@link GitOutcome#REFUSED_BY_POLICY} with the refused capability in the detail (GDR-CORE-13). The * one process start outside it is JGit's process-wide {@code SystemReader}, which the operations leave untouched; it * is prevented only where the application installed {@link RefusingFS#systemReader} before any JGit use. Commits are * never signed. @@ -491,13 +491,14 @@ private static StartPoint existingBranchStart(Repository main, Path commonDir, S return StartPoint.refused(GitOutcome.AMBIGUOUS, candidates(BRANCH, lookup)); } Ref existing = lookup.resolution() == GitIdentity.Resolution.REF ? main.exactRef(branchRef) : null; - if (existing == null || existing.getObjectId() == null) { + ObjectId existingId = existing == null ? null : existing.getObjectId(); + if (existingId == null) { return StartPoint.refused(GitOutcome.NOT_FOUND, BRANCH + NOT_FOUND_SUFFIX); } if (checkedOut(main, commonDir, branch)) { return StartPoint.refused(GitOutcome.BRANCH_CHECKED_OUT, CHECKED_OUT); } - return StartPoint.of(existing.getObjectId()); + return StartPoint.of(existingId); } /** @@ -962,7 +963,7 @@ private static boolean isEmptyDirectory(Path path) throws IOException { private static GitResult failure(Exception e) { for (Throwable current = e; current != null; current = current.getCause()) { if (current instanceof CapabilityRefusedException refusal) { - LOGGER.warn(WARN.CAPABILITY_REFUSED, refusal.getReason()); + LOGGER.warn(WARN.WORKTREE_CAPABILITY_REFUSED, refusal.getReason()); return GitResult.of(GitOutcome.REFUSED_BY_POLICY, refusal.getReason()); } } diff --git a/git-worktrees/src/main/java/de/cuioss/git/document/worktrees/LinkedWorktrees.java b/git-core/src/main/java/de/cuioss/git/document/core/worktrees/LinkedWorktrees.java similarity index 99% rename from git-worktrees/src/main/java/de/cuioss/git/document/worktrees/LinkedWorktrees.java rename to git-core/src/main/java/de/cuioss/git/document/core/worktrees/LinkedWorktrees.java index 164b108..763d010 100644 --- a/git-worktrees/src/main/java/de/cuioss/git/document/worktrees/LinkedWorktrees.java +++ b/git-core/src/main/java/de/cuioss/git/document/core/worktrees/LinkedWorktrees.java @@ -13,7 +13,7 @@ * See the License for the specific language governing permissions and * limitations under the License. */ -package de.cuioss.git.document.worktrees; +package de.cuioss.git.document.core.worktrees; import java.io.IOException; import java.nio.charset.StandardCharsets; @@ -32,7 +32,7 @@ import java.util.Optional; -import de.cuioss.git.document.worktrees.WorktreeOperations.Worktree; +import de.cuioss.git.document.core.worktrees.WorktreeOperations.Worktree; import lombok.experimental.UtilityClass; import org.eclipse.jgit.lib.Constants; import org.eclipse.jgit.lib.ObjectId; diff --git a/git-worktrees/src/main/java/de/cuioss/git/document/worktrees/WorktreeOperations.java b/git-core/src/main/java/de/cuioss/git/document/core/worktrees/WorktreeOperations.java similarity index 96% rename from git-worktrees/src/main/java/de/cuioss/git/document/worktrees/WorktreeOperations.java rename to git-core/src/main/java/de/cuioss/git/document/core/worktrees/WorktreeOperations.java index 15e7d66..158e2a0 100644 --- a/git-worktrees/src/main/java/de/cuioss/git/document/worktrees/WorktreeOperations.java +++ b/git-core/src/main/java/de/cuioss/git/document/core/worktrees/WorktreeOperations.java @@ -13,7 +13,7 @@ * See the License for the specific language governing permissions and * limitations under the License. */ -package de.cuioss.git.document.worktrees; +package de.cuioss.git.document.core.worktrees; import java.nio.file.Path; import java.util.Collections; @@ -32,10 +32,10 @@ import org.jspecify.annotations.Nullable; /** - * The operations on the working trees of a repository: adding, listing and removing linked working trees (GDR-WT-1), - * the commit from a working tree (GDR-WT-2), the status of a working tree and the release of a branch reservation left - * by an ended process (GDR-WT-4). One method per operation, typed inputs, and results carrying the closed - * {@link GitOutcome} of {@code git-core} (GDR-GEN-3). + * The operations on the working trees of a repository: adding, listing and removing linked working trees + * (GDR-CORE-12), the commit from a working tree (GDR-CORE-13), the status of a working tree and the release of a branch + * reservation left by an ended process (GDR-CORE-15). One method per operation, typed inputs, and results carrying the + * closed {@link GitOutcome} of {@code git-core} (GDR-GEN-3). *

* Every repository an implementation opens is built on {@link RefusingFS}, so no operation starts a process through * the repository's file system; an operation that would run a hook ends {@link GitOutcome#REFUSED_BY_POLICY} with the @@ -130,7 +130,7 @@ public interface WorktreeOperations { GitResult worktreeStatus(Path root); /** - * Releases the reservation of a branch (GDR-WT-4). An addition reserves its branch, a new one like an existing one, + * Releases the reservation of a branch (GDR-CORE-15). An addition reserves its branch, a new one like an existing one, * with a reservation file in the common git directory, {@code worktree-branch-.lock}, * and deletes it once the new working tree is registered or the addition ended. A process that ends between the two * leaves the reservation behind, and every later addition of that branch ends diff --git a/git-worktrees/src/main/java/de/cuioss/git/document/worktrees/package-info.java b/git-core/src/main/java/de/cuioss/git/document/core/worktrees/package-info.java similarity index 94% rename from git-worktrees/src/main/java/de/cuioss/git/document/worktrees/package-info.java rename to git-core/src/main/java/de/cuioss/git/document/core/worktrees/package-info.java index a96c362..82585bd 100644 --- a/git-worktrees/src/main/java/de/cuioss/git/document/worktrees/package-info.java +++ b/git-core/src/main/java/de/cuioss/git/document/core/worktrees/package-info.java @@ -17,6 +17,6 @@ * Linked working trees, commit from a working tree and working-tree status. */ @NullMarked -package de.cuioss.git.document.worktrees; +package de.cuioss.git.document.core.worktrees; import org.jspecify.annotations.NullMarked; diff --git a/git-core/src/main/java/module-info.java b/git-core/src/main/java/module-info.java index 558fac1..7e1b193 100644 --- a/git-core/src/main/java/module-info.java +++ b/git-core/src/main/java/module-info.java @@ -17,10 +17,12 @@ * Hardened Git repositories, remote policy, identity, results, transport, cache repository, in-core writing, * compare-and-swap, in-core merge (with its {@code MergeResult}), reading (a file of a cached commit, and with * {@code RepositoryReader} the snapshot of a commit, the history of a path and the paths changed between two commits) - * and notes ({@code GitNotes}) on JGit. + * and notes ({@code GitNotes}) on JGit, and in the package {@code de.cuioss.git.document.core.worktrees} linked + * working trees, commit from a working tree and working-tree status. */ module de.cuioss.git.document.core { exports de.cuioss.git.document.core; + exports de.cuioss.git.document.core.worktrees; requires transitive org.eclipse.jgit; requires de.cuioss.java.tools; diff --git a/git-core/src/test/java/de/cuioss/git/document/core/DomainTermAbsenceTest.java b/git-core/src/test/java/de/cuioss/git/document/core/DomainTermAbsenceTest.java index a68c002..b778113 100644 --- a/git-core/src/test/java/de/cuioss/git/document/core/DomainTermAbsenceTest.java +++ b/git-core/src/test/java/de/cuioss/git/document/core/DomainTermAbsenceTest.java @@ -19,6 +19,8 @@ import static org.junit.jupiter.api.Assertions.assertFalse; import java.io.IOException; +import java.io.InputStream; +import java.lang.module.ModuleDescriptor; import java.lang.reflect.Modifier; import java.net.URISyntaxException; import java.nio.file.Files; @@ -26,6 +28,9 @@ import java.util.ArrayList; import java.util.List; import java.util.Locale; +import java.util.Set; +import java.util.TreeSet; +import java.util.stream.Collectors; import java.util.stream.Stream; @@ -33,10 +38,13 @@ import org.junit.jupiter.api.Test; /** - * GDR-GEN-1: the libraries carry no domain term. No public type of {@code git-core}, by its simple name or its package - * name, contains one of the domain terms of the application, compared case-insensitively. The scan reads the main - * output directory of the module, located through the code source of {@link GitResult}, and loads each class without - * initialising it. + * GDR-GEN-1: the libraries carry no domain term. No public type of {@code git-core}, in its packages + * {@code de.cuioss.git.document.core} and {@code de.cuioss.git.document.core.worktrees}, by its simple name or its + * package name, contains one of the domain terms of the application, compared case-insensitively. The scan reads the + * main output directory of the module, located through the code source of {@link GitResult}, and loads each class + * without initialising it. Every package the compiled {@code module-info.class} of that directory exports must hold at + * least one of the public types found, so an exported package the scan does not reach fails the test instead of + * passing it unexamined. */ @DisplayName("git-core public types carry no domain term (GDR-GEN-1)") class DomainTermAbsenceTest { @@ -47,10 +55,14 @@ class DomainTermAbsenceTest { /** The file suffix of a compiled class. */ private static final String CLASS_SUFFIX = ".class"; + /** The compiled module descriptor of the main output directory. */ + private static final String MODULE_INFO = "module-info"; + @Test @DisplayName("Should find public types and none of them names a domain term") void shouldCarryNoDomainTermInPublicTypes() throws Exception { - var publicTypes = publicTypesOfMainOutput(); + var root = mainOutput(); + var publicTypes = publicTypesOf(root); var violations = new ArrayList(); for (Class type : publicTypes) { @@ -62,19 +74,47 @@ void shouldCarryNoDomainTermInPublicTypes() throws Exception { } } } + var exportedPackages = exportedPackagesOf(root); + var scannedPackages = publicTypes.stream().map(Class::getPackageName).collect(Collectors.toSet()); + var unscannedExports = new TreeSet<>(exportedPackages); + unscannedExports.removeAll(scannedPackages); assertFalse(publicTypes.isEmpty(), "The scan must find at least one public type of git-core"); + assertFalse(exportedPackages.isEmpty(), "The module descriptor of git-core must export at least one package"); + assertEquals(Set.of(), unscannedExports, "Every package git-core exports must hold a public type of the scan"); assertEquals(List.of(), violations, "Public types of git-core must not carry a domain term of GDR-GEN-1"); } + /** + * The main output directory of the module, located through the code source of {@link GitResult}. + * + * @return the main output directory, never {@code null} + */ + private static Path mainOutput() throws URISyntaxException { + return Path.of(GitResult.class.getProtectionDomain().getCodeSource().getLocation().toURI()); + } + + /** + * Reads the packages the compiled module descriptor of the main output directory exports. + * + * @param root the main output directory + * @return the exported packages, never {@code null} + */ + private static Set exportedPackagesOf(Path root) throws IOException { + try (InputStream descriptor = Files.newInputStream(root.resolve(MODULE_INFO + CLASS_SUFFIX))) { + return ModuleDescriptor.read(descriptor).exports().stream() + .map(ModuleDescriptor.Exports::source) + .collect(Collectors.toCollection(TreeSet::new)); + } + } + /** * Loads every class of the main output directory without initialising it and keeps the public ones. * + * @param root the main output directory * @return the public types of the main output directory, never {@code null} */ - private static List> publicTypesOfMainOutput() - throws IOException, URISyntaxException, ClassNotFoundException { - var root = Path.of(GitResult.class.getProtectionDomain().getCodeSource().getLocation().toURI()); + private static List> publicTypesOf(Path root) throws IOException, ClassNotFoundException { var loader = GitResult.class.getClassLoader(); List classNames; try (Stream files = Files.walk(root)) { @@ -83,7 +123,7 @@ private static List> publicTypesOfMainOutput() .map(Path::toString) .filter(name -> name.endsWith(CLASS_SUFFIX)) .map(name -> name.substring(0, name.length() - CLASS_SUFFIX.length())) - .filter(name -> !name.endsWith("module-info") && !name.endsWith("package-info")) + .filter(name -> !name.endsWith(MODULE_INFO) && !name.endsWith("package-info")) .map(name -> name.replace(root.getFileSystem().getSeparator(), ".")) .toList(); } diff --git a/git-worktrees/src/test/java/de/cuioss/git/document/worktrees/AbsenceContractsTest.java b/git-core/src/test/java/de/cuioss/git/document/core/worktrees/AbsenceContractsTest.java similarity index 97% rename from git-worktrees/src/test/java/de/cuioss/git/document/worktrees/AbsenceContractsTest.java rename to git-core/src/test/java/de/cuioss/git/document/core/worktrees/AbsenceContractsTest.java index 25fa803..1b5fb2f 100644 --- a/git-worktrees/src/test/java/de/cuioss/git/document/worktrees/AbsenceContractsTest.java +++ b/git-core/src/test/java/de/cuioss/git/document/core/worktrees/AbsenceContractsTest.java @@ -13,7 +13,7 @@ * See the License for the specific language governing permissions and * limitations under the License. */ -package de.cuioss.git.document.worktrees; +package de.cuioss.git.document.core.worktrees; import static org.junit.jupiter.api.Assertions.assertAll; import static org.junit.jupiter.api.Assertions.assertEquals; @@ -27,8 +27,8 @@ import de.cuioss.git.document.core.GitOutcome; +import de.cuioss.git.document.core.worktrees.WorktreeOperations.WorktreeAddInput; import de.cuioss.git.document.testing.LocalRepository; -import de.cuioss.git.document.worktrees.WorktreeOperations.WorktreeAddInput; import de.cuioss.test.generator.junit.EnableGeneratorController; import org.eclipse.jgit.api.Git; import org.eclipse.jgit.lib.Repository; diff --git a/git-worktrees/src/test/java/de/cuioss/git/document/worktrees/GitWorktreeListCompatibilityTest.java b/git-core/src/test/java/de/cuioss/git/document/core/worktrees/GitWorktreeListCompatibilityTest.java similarity index 94% rename from git-worktrees/src/test/java/de/cuioss/git/document/worktrees/GitWorktreeListCompatibilityTest.java rename to git-core/src/test/java/de/cuioss/git/document/core/worktrees/GitWorktreeListCompatibilityTest.java index 5e31833..82b4be4 100644 --- a/git-worktrees/src/test/java/de/cuioss/git/document/worktrees/GitWorktreeListCompatibilityTest.java +++ b/git-core/src/test/java/de/cuioss/git/document/core/worktrees/GitWorktreeListCompatibilityTest.java @@ -13,7 +13,7 @@ * See the License for the specific language governing permissions and * limitations under the License. */ -package de.cuioss.git.document.worktrees; +package de.cuioss.git.document.core.worktrees; import static org.junit.jupiter.api.Assertions.assertAll; import static org.junit.jupiter.api.Assertions.assertEquals; @@ -33,9 +33,9 @@ import java.util.concurrent.TimeUnit; +import de.cuioss.git.document.core.worktrees.WorktreeOperations.Worktree; +import de.cuioss.git.document.core.worktrees.WorktreeOperations.WorktreeAddInput; import de.cuioss.git.document.testing.LocalRepository; -import de.cuioss.git.document.worktrees.WorktreeOperations.Worktree; -import de.cuioss.git.document.worktrees.WorktreeOperations.WorktreeAddInput; import de.cuioss.test.generator.junit.EnableGeneratorController; import org.eclipse.jgit.lib.Constants; import org.eclipse.jgit.lib.Repository; @@ -46,7 +46,7 @@ /** * The working trees {@link JGitWorktreeOperations#worktreeAdd} creates are read by an installed git: {@code git worktree * list --porcelain} lists each with its path, its branch and its {@code HEAD}, a locked one {@code locked} and one - * whose directory is gone {@code prunable}, and {@code git worktree remove} removes one (GDR-WT-1). The tests are + * whose directory is gone {@code prunable}, and {@code git worktree remove} removes one (GDR-CORE-12). The tests are * skipped through a JUnit assumption when no {@code git} binary is found. Only this test starts a process, never the * library. The porcelain keys ({@code worktree}, {@code HEAD}, {@code branch}, {@code detached}, {@code locked}, * {@code prunable}) are git's own vocabulary. @@ -62,7 +62,7 @@ class GitWorktreeListCompatibilityTest { Path temp; @Test - @DisplayName("GDR-WT-1: git worktree list --porcelain lists the added working trees with path, branch and HEAD") + @DisplayName("GDR-CORE-12: git worktree list --porcelain lists the added working trees with path, branch and HEAD") void installedGitListsAddedWorktrees(@LocalRepository Repository source) throws Exception { assumeTrue(gitInstalled(), "a git binary is installed"); var main = JGitWorktreeOperationsTest.mainTree(source, temp); @@ -89,7 +89,7 @@ void installedGitListsAddedWorktrees(@LocalRepository Repository source) throws } @Test - @DisplayName("GDR-WT-1: git worktree list --porcelain lists a locked tree locked and one whose directory is gone " + @DisplayName("GDR-CORE-12: git worktree list --porcelain lists a locked tree locked and one whose directory is gone " + "prunable") void installedGitListsLockedAndPrunable(@LocalRepository Repository source) throws Exception { assumeTrue(gitInstalled(), "a git binary is installed"); @@ -114,7 +114,7 @@ void installedGitListsLockedAndPrunable(@LocalRepository Repository source) thro } @Test - @DisplayName("GDR-WT-1: git worktree remove removes a working tree the library added") + @DisplayName("GDR-CORE-12: git worktree remove removes a working tree the library added") void installedGitRemovesAddedWorktree(@LocalRepository Repository source) throws Exception { assumeTrue(gitInstalled(), "a git binary is installed"); var main = JGitWorktreeOperationsTest.mainTree(source, temp); diff --git a/git-worktrees/src/test/java/de/cuioss/git/document/worktrees/JGitWorktreeOperationsTest.java b/git-core/src/test/java/de/cuioss/git/document/core/worktrees/JGitWorktreeOperationsTest.java similarity index 93% rename from git-worktrees/src/test/java/de/cuioss/git/document/worktrees/JGitWorktreeOperationsTest.java rename to git-core/src/test/java/de/cuioss/git/document/core/worktrees/JGitWorktreeOperationsTest.java index 49fdf99..b705be9 100644 --- a/git-worktrees/src/test/java/de/cuioss/git/document/worktrees/JGitWorktreeOperationsTest.java +++ b/git-core/src/test/java/de/cuioss/git/document/core/worktrees/JGitWorktreeOperationsTest.java @@ -13,7 +13,7 @@ * See the License for the specific language governing permissions and * limitations under the License. */ -package de.cuioss.git.document.worktrees; +package de.cuioss.git.document.core.worktrees; import static org.junit.jupiter.api.Assertions.assertAll; import static org.junit.jupiter.api.Assertions.assertEquals; @@ -48,14 +48,15 @@ import java.util.stream.Stream; +import de.cuioss.git.document.core.GitCoreLogMessages; import de.cuioss.git.document.core.GitOutcome; import de.cuioss.git.document.core.GitResult; import de.cuioss.git.document.core.RefusingFS; import de.cuioss.git.document.core.RepositoryOperations.Identity; +import de.cuioss.git.document.core.worktrees.WorktreeOperations.CommitInput; +import de.cuioss.git.document.core.worktrees.WorktreeOperations.Worktree; +import de.cuioss.git.document.core.worktrees.WorktreeOperations.WorktreeAddInput; import de.cuioss.git.document.testing.LocalRepository; -import de.cuioss.git.document.worktrees.WorktreeOperations.CommitInput; -import de.cuioss.git.document.worktrees.WorktreeOperations.Worktree; -import de.cuioss.git.document.worktrees.WorktreeOperations.WorktreeAddInput; import de.cuioss.test.generator.Generators; import de.cuioss.test.generator.TypedGenerator; import de.cuioss.test.generator.junit.EnableGeneratorController; @@ -89,7 +90,7 @@ /** * The working-tree operations on JGit: add, list, remove and commit against a main working tree cloned from a - * {@code git-testing} fixture repository, with every outcome of each operation (GDR-WT-1, GDR-WT-2), and the absence of + * {@code git-testing} fixture repository, with every outcome of each operation (GDR-CORE-12, GDR-CORE-13), and the absence of * author and committer names, e-mail addresses and commit messages from every log message and every result detail * (GDR-NFR-3). *

@@ -338,7 +339,7 @@ private static CommitInput commitInput(Path root) { class Add { @Test - @DisplayName("GDR-WT-1: a working tree on a new branch is created in git's layout, checked out and listed") + @DisplayName("GDR-CORE-12: a working tree on a new branch is created in git's layout, checked out and listed") void onNewBranchAtHead(@LocalRepository Repository source) throws Exception { var main = mainTree(source, temp); var branch = name(); @@ -368,11 +369,11 @@ void onNewBranchAtHead(@LocalRepository Repository source) throws Exception { "the new working tree is listed after the main one"), () -> assertEquals(branch, all.get(1).branch(), "the listed working tree is on the branch")); LogAsserts.assertSingleLogMessagePresentContaining(TestLogLevel.INFO, - GitWorktreesLogMessages.INFO.WORKTREE_ADDED.resolveIdentifierString()); + GitCoreLogMessages.INFO.WORKTREE_ADDED.resolveIdentifierString()); } @Test - @DisplayName("GDR-WT-1: a detached working tree at a full commit id has no branch and records the commit") + @DisplayName("GDR-CORE-12: a detached working tree at a full commit id has no branch and records the commit") void detachedAtFullCommitId(@LocalRepository Repository source) throws Exception { var main = mainTree(source, temp); var path = main.root().resolve(name()); @@ -391,7 +392,7 @@ void detachedAtFullCommitId(@LocalRepository Repository source) throws Exception } @Test - @DisplayName("GDR-WT-1: a working tree on an existing branch checks out the branch's commit") + @DisplayName("GDR-CORE-12: a working tree on an existing branch checks out the branch's commit") void existingBranchAtItsCommit(@LocalRepository Repository source) throws Exception { var main = mainTree(source, temp); var branch = name(); @@ -414,7 +415,7 @@ void existingBranchAtItsCommit(@LocalRepository Repository source) throws Except } @Test - @DisplayName("GDR-WT-1: an empty directory is taken, a non-empty one or an existing new branch already exists") + @DisplayName("GDR-CORE-12: an empty directory is taken, a non-empty one or an existing new branch already exists") void alreadyExists(@LocalRepository Repository source) throws Exception { var main = mainTree(source, temp); var empty = Files.createDirectories(main.root().resolve(name())); @@ -440,7 +441,7 @@ void alreadyExists(@LocalRepository Repository source) throws Exception { } @Test - @DisplayName("GDR-WT-1: a branch checked out in the main or in a linked working tree is refused") + @DisplayName("GDR-CORE-12: a branch checked out in the main or in a linked working tree is refused") void branchCheckedOut(@LocalRepository Repository source) throws Exception { var main = mainTree(source, temp); var linkedBranch = name(); @@ -463,7 +464,7 @@ void branchCheckedOut(@LocalRepository Repository source) throws Exception { } @Test - @DisplayName("GDR-WT-1: an unknown branch, an unknown, abbreviated or absent start point is not found") + @DisplayName("GDR-CORE-12: an unknown branch, an unknown, abbreviated or absent start point is not found") void notFound(@LocalRepository Repository source) throws Exception { var main = mainTree(source, temp); var absent = ObjectId.fromRaw(Generators.letterStrings(20, 20).next() @@ -492,7 +493,7 @@ void notFound(@LocalRepository Repository source) throws Exception { } @Test - @DisplayName("GDR-WT-1: a start point naming a branch and a tag is ambiguous and lists both") + @DisplayName("GDR-CORE-12: a start point naming a branch and a tag is ambiguous and lists both") void ambiguous(@LocalRepository Repository source) throws Exception { var main = mainTree(source, temp); var tag = Constants.R_TAGS + main.branch(); @@ -510,7 +511,7 @@ void ambiguous(@LocalRepository Repository source) throws Exception { } @Test - @DisplayName("GDR-WT-1: a pin the branch is not at, or that reaches another commit, is an identity mismatch") + @DisplayName("GDR-CORE-12: a pin the branch is not at, or that reaches another commit, is an identity mismatch") void identityMismatch(@LocalRepository Repository source) throws Exception { var main = mainTree(source, temp); var branch = name(); @@ -547,7 +548,7 @@ void identityMismatch(@LocalRepository Repository source) throws Exception { } @Test - @DisplayName("GDR-WT-1: a path outside the main working tree or the main working tree itself is refused") + @DisplayName("GDR-CORE-12: a path outside the main working tree or the main working tree itself is refused") void pathRefused(@LocalRepository Repository source) throws Exception { var main = mainTree(source, temp); var outside = temp.resolve(name()); @@ -562,7 +563,7 @@ void pathRefused(@LocalRepository Repository source) throws Exception { } @Test - @DisplayName("GDR-WT-1: a branch name that is no valid reference name is refused before anything is written") + @DisplayName("GDR-CORE-12: a branch name that is no valid reference name is refused before anything is written") void invalidBranchNameRefused(@LocalRepository Repository source) throws Exception { var main = mainTree(source, temp); var escape = name(); @@ -605,7 +606,7 @@ void invalidBranchNameRefused(@LocalRepository Repository source) throws Excepti } @Test - @DisplayName("GDR-WT-1: a linked working tree as root is refused and nothing is created") + @DisplayName("GDR-CORE-12: a linked working tree as root is refused and nothing is created") void linkedRootRefused(@LocalRepository Repository source) throws Exception { var main = mainTree(source, temp); var linked = added(main, name()); @@ -625,7 +626,7 @@ void linkedRootRefused(@LocalRepository Repository source) throws Exception { } @Test - @DisplayName("GDR-WT-1: a target inside the git directory, its administration area or another linked working " + @DisplayName("GDR-CORE-12: a target inside the git directory, its administration area or another linked working " + "tree is refused") void targetInsideAdministrationRefused(@LocalRepository Repository source) throws Exception { var main = mainTree(source, temp); @@ -655,7 +656,7 @@ void targetInsideAdministrationRefused(@LocalRepository Repository source) throw } @Test - @DisplayName("GDR-WT-1: a root outside any repository is not a repository") + @DisplayName("GDR-CORE-12: a root outside any repository is not a repository") void notARepository() throws Exception { var plain = Files.createDirectories(temp.resolve(name())).toRealPath(); @@ -666,7 +667,7 @@ void notARepository() throws Exception { } @Test - @DisplayName("GDR-WT-2: a checkout that would run a filter driver is refused and leaves no working tree") + @DisplayName("GDR-CORE-13: a checkout that would run a filter driver is refused and leaves no working tree") void filterDriverRefused(@LocalRepository Repository source) throws Exception { var main = mainTree(source, temp); configureFilter(main, "smudge"); @@ -681,11 +682,11 @@ void filterDriverRefused(@LocalRepository Repository source) throws Exception { () -> assertFalse(Files.exists(main.admin(path.getFileName().toString())), "the administration directory is removed again")); LogAsserts.assertSingleLogMessagePresentContaining(TestLogLevel.WARN, - GitWorktreesLogMessages.WARN.CAPABILITY_REFUSED.resolveIdentifierString()); + GitCoreLogMessages.WARN.WORKTREE_CAPABILITY_REFUSED.resolveIdentifierString()); } @Test - @DisplayName("GDR-WT-1: unreadable administration files fail the add with the failure class only") + @DisplayName("GDR-CORE-12: unreadable administration files fail the add with the failure class only") void failed(@LocalRepository Repository source) throws Exception { var main = mainTree(source, temp); var branch = name(); @@ -701,7 +702,7 @@ void failed(@LocalRepository Repository source) throws Exception { } @Test - @DisplayName("GDR-WT-1: a refused checkout removes the branch it created, keeps an existing one, a retry succeeds") + @DisplayName("GDR-CORE-12: a refused checkout removes the branch it created, keeps an existing one, a retry succeeds") void refusedCheckoutRollsBackBranch(@LocalRepository Repository source) throws Exception { var main = mainTree(source, temp); var existing = name(); @@ -735,7 +736,7 @@ void refusedCheckoutRollsBackBranch(@LocalRepository Repository source) throws E } @Test - @DisplayName("GDR-WT-1: of concurrent additions for one target or one unused branch exactly one succeeds") + @DisplayName("GDR-CORE-12: of concurrent additions for one target or one unused branch exactly one succeeds") void concurrentAdditions(@LocalRepository Repository source) throws Exception { var main = mainTree(source, temp); int attempts = 4; @@ -784,7 +785,7 @@ void concurrentAdditions(@LocalRepository Repository source) throws Exception { } @Test - @DisplayName("GDR-WT-1: an unknown start point is not found for an existing branch, HEAD selects its tip") + @DisplayName("GDR-CORE-12: an unknown start point is not found for an existing branch, HEAD selects its tip") void unknownStartPointForExistingBranch(@LocalRepository Repository source) throws Exception { var main = mainTree(source, temp); var branch = name(); @@ -810,7 +811,7 @@ void unknownStartPointForExistingBranch(@LocalRepository Repository source) thro class ListWorktrees { @Test - @DisplayName("GDR-WT-1: the main working tree comes first, then the linked ones by name, from any root") + @DisplayName("GDR-CORE-12: the main working tree comes first, then the linked ones by name, from any root") void mainFirstThenByName(@LocalRepository Repository source) throws Exception { var main = mainTree(source, temp); var first = added(main, name()); @@ -834,7 +835,7 @@ void mainFirstThenByName(@LocalRepository Repository source) throws Exception { } @Test - @DisplayName("GDR-WT-1: a locked working tree is listed locked, one whose directory is gone prunable") + @DisplayName("GDR-CORE-12: a locked working tree is listed locked, one whose directory is gone prunable") void lockedAndPrunable(@LocalRepository Repository source) throws Exception { var main = mainTree(source, temp); var locked = added(main, name()); @@ -855,7 +856,7 @@ void lockedAndPrunable(@LocalRepository Repository source) throws Exception { } @Test - @DisplayName("GDR-WT-1: a directory outside any repository is not a repository") + @DisplayName("GDR-CORE-12: a directory outside any repository is not a repository") void notARepository() throws Exception { var plain = Files.createDirectories(temp.resolve(name())); @@ -864,7 +865,7 @@ void notARepository() throws Exception { } @Test - @DisplayName("GDR-WT-1: unreadable administration files fail the list with the failure class only") + @DisplayName("GDR-CORE-12: unreadable administration files fail the list with the failure class only") void failed(@LocalRepository Repository source) throws Exception { var main = mainTree(source, temp); corruptAdministration(main); @@ -877,7 +878,7 @@ void failed(@LocalRepository Repository source) throws Exception { } @Test - @DisplayName("GDR-WT-1: an entry still being initialized fails neither the list nor another removal") + @DisplayName("GDR-CORE-12: an entry still being initialized fails neither the list nor another removal") void incompleteEntrySkipped(@LocalRepository Repository source) throws Exception { var main = mainTree(source, temp); var worktree = added(main, name()); @@ -903,7 +904,7 @@ void incompleteEntrySkipped(@LocalRepository Repository source) throws Exception class Remove { @Test - @DisplayName("GDR-WT-1: a clean linked working tree is removed with its administration directory") + @DisplayName("GDR-CORE-12: a clean linked working tree is removed with its administration directory") void removesClean(@LocalRepository Repository source) throws Exception { var main = mainTree(source, temp); var worktree = added(main, name()); @@ -918,11 +919,11 @@ void removesClean(@LocalRepository Repository source) throws Exception { () -> assertEquals(List.of(main.root()), listed(main).stream().map(Worktree::path).toList(), "only the main working tree is listed")); LogAsserts.assertSingleLogMessagePresentContaining(TestLogLevel.INFO, - GitWorktreesLogMessages.INFO.WORKTREE_REMOVED.resolveIdentifierString()); + GitCoreLogMessages.INFO.WORKTREE_REMOVED.resolveIdentifierString()); } @Test - @DisplayName("GDR-WT-1: a prunable working tree is removed by its administration directory") + @DisplayName("GDR-CORE-12: a prunable working tree is removed by its administration directory") void removesPrunable(@LocalRepository Repository source) throws Exception { var main = mainTree(source, temp); var worktree = added(main, name()); @@ -937,7 +938,7 @@ void removesPrunable(@LocalRepository Repository source) throws Exception { } @Test - @DisplayName("GDR-WT-1: a dirty or a locked working tree is kept, the removal is never forced") + @DisplayName("GDR-CORE-12: a dirty or a locked working tree is kept, the removal is never forced") void dirtyAndLocked(@LocalRepository Repository source) throws Exception { var main = mainTree(source, temp); var dirty = added(main, name()); @@ -958,7 +959,7 @@ void dirtyAndLocked(@LocalRepository Repository source) throws Exception { } @Test - @DisplayName("GDR-WT-1: the main working tree is refused and an unknown root is not found") + @DisplayName("GDR-CORE-12: the main working tree is refused and an unknown root is not found") void mainRefusedUnknownNotFound(@LocalRepository Repository source) throws Exception { var main = mainTree(source, temp); var unknown = main.root().resolve(name()); @@ -977,7 +978,7 @@ void mainRefusedUnknownNotFound(@LocalRepository Repository source) throws Excep } @Test - @DisplayName("GDR-WT-1: a dirty check that would run a filter driver is refused and keeps the working tree") + @DisplayName("GDR-CORE-12: a dirty check that would run a filter driver is refused and keeps the working tree") void filterDriverRefused(@LocalRepository Repository source) throws Exception { var main = mainTree(source, temp); var worktree = added(main, name()); @@ -995,7 +996,7 @@ void filterDriverRefused(@LocalRepository Repository source) throws Exception { } @Test - @DisplayName("GDR-WT-1: a root outside any repository is not a repository, unreadable administration fails") + @DisplayName("GDR-CORE-12: a root outside any repository is not a repository, unreadable administration fails") void notARepositoryAndFailed(@LocalRepository Repository source) throws Exception { var plain = Files.createDirectories(temp.resolve(name())); var main = mainTree(source, temp); @@ -1013,7 +1014,7 @@ void notARepositoryAndFailed(@LocalRepository Repository source) throws Exceptio } @Test - @DisplayName("GDR-WT-1: a replaced repository at the root is not found, a reused prunable path is kept") + @DisplayName("GDR-CORE-12: a replaced repository at the root is not found, a reused prunable path is kept") void replacedRepositoryAndReusedPath(@LocalRepository Repository source) throws Exception { var main = mainTree(source, temp); var replaced = added(main, name()); @@ -1050,7 +1051,7 @@ void replacedRepositoryAndReusedPath(@LocalRepository Repository source) throws class Commit { @Test - @DisplayName("GDR-WT-2: every addition, modification and deletion is committed unsigned on the tree's branch") + @DisplayName("GDR-CORE-13: every addition, modification and deletion is committed unsigned on the tree's branch") void commitsEveryChange(@LocalRepository Repository source) throws Exception { var main = mainTree(source, temp); try (Repository repository = open(main.root())) { @@ -1097,7 +1098,7 @@ void commitsEveryChange(@LocalRepository Repository source) throws Exception { } @Test - @DisplayName("GDR-WT-2: a commit from the main working tree moves its branch") + @DisplayName("GDR-CORE-13: a commit from the main working tree moves its branch") void commitsInMain(@LocalRepository Repository source) throws Exception { var main = mainTree(source, temp); Files.writeString(main.root().resolve(name()), content()); @@ -1110,7 +1111,7 @@ void commitsInMain(@LocalRepository Repository source) throws Exception { } @Test - @DisplayName("GDR-WT-2: a clean working tree has nothing to commit") + @DisplayName("GDR-CORE-13: a clean working tree has nothing to commit") void nothingToCommit(@LocalRepository Repository source) throws Exception { var main = mainTree(source, temp); var branch = name(); @@ -1126,7 +1127,7 @@ void nothingToCommit(@LocalRepository Repository source) throws Exception { } @Test - @DisplayName("GDR-WT-2: a hook present in the repository is refused and never run") + @DisplayName("GDR-CORE-13: a hook present in the repository is refused and never run") void hookRefused(@LocalRepository Repository source) throws Exception { assumeTrue(FileSystems.getDefault().supportedFileAttributeViews().contains("posix"), "The default file system supports the posix file attribute view"); @@ -1146,11 +1147,11 @@ void hookRefused(@LocalRepository Repository source) throws Exception { "nothing is committed"), () -> assertFalse(Files.exists(marker), "the hook is never run")); LogAsserts.assertSingleLogMessagePresentContaining(TestLogLevel.WARN, - GitWorktreesLogMessages.WARN.CAPABILITY_REFUSED.resolveIdentifierString()); + GitCoreLogMessages.WARN.WORKTREE_CAPABILITY_REFUSED.resolveIdentifierString()); } @Test - @DisplayName("GDR-WT-2: a present post-commit hook is refused before anything is staged or committed") + @DisplayName("GDR-CORE-13: a present post-commit hook is refused before anything is staged or committed") void postCommitHookRefused(@LocalRepository Repository source) throws Exception { assumeTrue(FileSystems.getDefault().supportedFileAttributeViews().contains("posix"), "The default file system supports the posix file attribute view"); @@ -1175,7 +1176,7 @@ void postCommitHookRefused(@LocalRepository Repository source) throws Exception } @Test - @DisplayName("GDR-WT-2: a commit in the main working tree does not stage the root of a linked working tree") + @DisplayName("GDR-CORE-13: a commit in the main working tree does not stage the root of a linked working tree") void linkedRootNotStaged(@LocalRepository Repository source) throws Exception { var main = mainTree(source, temp); var linked = added(main, name()); @@ -1201,7 +1202,7 @@ void linkedRootNotStaged(@LocalRepository Repository source) throws Exception { } @Test - @DisplayName("GDR-WT-2: a commit in a linked working tree writes its HEAD reflog there, not into the main one") + @DisplayName("GDR-CORE-13: a commit in a linked working tree writes its HEAD reflog there, not into the main one") void linkedReflog(@LocalRepository Repository source) throws Exception { var main = mainTree(source, temp); var branch = name(); @@ -1226,7 +1227,7 @@ void linkedReflog(@LocalRepository Repository source) throws Exception { } @Test - @DisplayName("GDR-WT-2: a root outside any repository is not a repository, a locked index fails the commit") + @DisplayName("GDR-CORE-13: a root outside any repository is not a repository, a locked index fails the commit") void notARepositoryAndFailed(@LocalRepository Repository source) throws Exception { var plain = Files.createDirectories(temp.resolve(name())); var main = mainTree(source, temp); @@ -1275,7 +1276,7 @@ private Path registerThroughSymlink(MainTree main, Worktree worktree) throws IOE class RegisteredIdentity { @Test - @DisplayName("GDR-WT-1: a new or an existing branch whose reservation another addition holds is checked out") + @DisplayName("GDR-CORE-12: a new or an existing branch whose reservation another addition holds is checked out") void reservedBranchCheckedOut(@LocalRepository Repository source) throws Exception { var main = mainTree(source, temp); var commonDir = main.root().resolve(Constants.DOT_GIT); @@ -1312,7 +1313,7 @@ void reservedBranchCheckedOut(@LocalRepository Repository source) throws Excepti } @Test - @DisplayName("GDR-WT-1: a working tree registered through a symbolic link is found and removed by its real path") + @DisplayName("GDR-CORE-12: a working tree registered through a symbolic link is found and removed by its real path") void removeThroughSymlink(@LocalRepository Repository source) throws Exception { var main = mainTree(source, temp); var worktree = added(main, name()); @@ -1331,7 +1332,7 @@ void removeThroughSymlink(@LocalRepository Repository source) throws Exception { } @Test - @DisplayName("GDR-WT-2: a commit in the main working tree stages no root registered through a symbolic link") + @DisplayName("GDR-CORE-13: a commit in the main working tree stages no root registered through a symbolic link") void linkedRootThroughSymlinkNotStaged(@LocalRepository Repository source) throws Exception { var main = mainTree(source, temp); var linked = added(main, name()); @@ -1411,7 +1412,7 @@ private Path commonDir(MainTree main) { } @Test - @DisplayName("GDR-WT-4: a reservation a crashed process left is released, and the addition succeeds again") + @DisplayName("GDR-CORE-15: a reservation a crashed process left is released, and the addition succeeds again") void crashedProcessRecovered(@LocalRepository Repository source) throws Exception { var main = mainTree(source, temp); var branch = name(); @@ -1441,11 +1442,11 @@ void crashedProcessRecovered(@LocalRepository Repository source) throws Exceptio () -> assertTrue(handler.resolveLogMessagesContaining(TestLogLevel.INFO, main.root().toString()).isEmpty(), "no INFO message carries a path")); LogAsserts.assertSingleLogMessagePresentContaining(TestLogLevel.INFO, - GitWorktreesLogMessages.INFO.BRANCH_RESERVATION_RELEASED.resolveIdentifierString()); + GitCoreLogMessages.INFO.BRANCH_RESERVATION_RELEASED.resolveIdentifierString()); } @Test - @DisplayName("GDR-WT-4: a branch without a reservation is not found") + @DisplayName("GDR-CORE-15: a branch without a reservation is not found") void noReservation(@LocalRepository Repository source) throws Exception { var main = mainTree(source, temp); @@ -1459,7 +1460,7 @@ void noReservation(@LocalRepository Repository source) throws Exception { } @Test - @DisplayName("GDR-WT-4: an invalid branch name is refused and deletes nothing in or outside the common directory") + @DisplayName("GDR-CORE-15: an invalid branch name is refused and deletes nothing in or outside the common directory") void invalidBranchNameRefused(@LocalRepository Repository source) throws Exception { var main = mainTree(source, temp); var escape = name(); @@ -1480,7 +1481,7 @@ void invalidBranchNameRefused(@LocalRepository Repository source) throws Excepti } @Test - @DisplayName("GDR-WT-4: a path without a repository is not a repository") + @DisplayName("GDR-CORE-15: a path without a repository is not a repository") void notARepository() throws Exception { var plain = Files.createDirectories(temp.resolve(name())); @@ -1492,7 +1493,7 @@ void notARepository() throws Exception { } @Test - @DisplayName("GDR-WT-4: a repository without a working tree fails as a result") + @DisplayName("GDR-CORE-15: a repository without a working tree fails as a result") void bareRepositoryFails() throws Exception { var bare = temp.resolve(name()); Git.init().setBare(true).setDirectory(bare.toFile()).call().close(); @@ -1508,7 +1509,7 @@ void bareRepositoryFails() throws Exception { } @Test - @DisplayName("GDR-WT-4: called from a linked working tree it releases the reservation in the common directory") + @DisplayName("GDR-CORE-15: called from a linked working tree it releases the reservation in the common directory") void fromLinkedRoot(@LocalRepository Repository source) throws Exception { var main = mainTree(source, temp); var linked = added(main, name()); @@ -1526,7 +1527,7 @@ void fromLinkedRoot(@LocalRepository Repository source) throws Exception { } @Test - @DisplayName("GDR-WT-4: the release deletes only the named branch's reservation") + @DisplayName("GDR-CORE-15: the release deletes only the named branch's reservation") void onlyNamedReservation(@LocalRepository Repository source) throws Exception { var main = mainTree(source, temp); var branch = name(); @@ -1568,7 +1569,7 @@ void bareRepositoryFails() throws Exception { } @Test - @DisplayName("GDR-WT-1: an unchecked failure of the addition is a result and leaves nothing behind") + @DisplayName("GDR-CORE-12: an unchecked failure of the addition is a result and leaves nothing behind") void uncheckedFailureRolledBack(@LocalRepository Repository source) throws Exception { var main = mainTree(source, temp); var branch = name(); @@ -1604,7 +1605,7 @@ void uncheckedFailureRolledBack(@LocalRepository Repository source) throws Excep } @Test - @DisplayName("GDR-WT-1: a created branch another writer advanced is kept, one that cannot be deleted stays") + @DisplayName("GDR-CORE-12: a created branch another writer advanced is kept, one that cannot be deleted stays") void branchDeletionResultRead(@LocalRepository Repository source) throws Exception { var main = mainTree(source, temp); var advancedBranch = name(); @@ -1644,7 +1645,7 @@ void branchDeletionResultRead(@LocalRepository Repository source) throws Excepti } @Test - @DisplayName("GDR-WT-1: the branch stays reserved until the rollback of a failed addition has deleted it") + @DisplayName("GDR-CORE-12: the branch stays reserved until the rollback of a failed addition has deleted it") void reservationOutlivesRollback(@LocalRepository Repository source) throws Exception { var main = mainTree(source, temp); var branch = name(); @@ -1672,7 +1673,7 @@ void reservationOutlivesRollback(@LocalRepository Repository source) throws Exce } @Test - @DisplayName("GDR-WT-1: a created branch a held reference lock keeps at its start commit is reported") + @DisplayName("GDR-CORE-12: a created branch a held reference lock keeps at its start commit is reported") void heldRefLockReported(@LocalRepository Repository source) throws Exception { var main = mainTree(source, temp); var branch = name(); @@ -1692,11 +1693,11 @@ void heldRefLockReported(@LocalRepository Repository source) throws Exception { () -> assertFalse(Files.exists(path), "the target is removed again"), () -> assertEquals(List.of(), reservations(main), "no branch reservation is left")); LogAsserts.assertSingleLogMessagePresentContaining(TestLogLevel.WARN, - GitWorktreesLogMessages.WARN.ROLLBACK_INCOMPLETE.resolveIdentifierString()); + GitCoreLogMessages.WARN.ROLLBACK_INCOMPLETE.resolveIdentifierString()); } @Test - @DisplayName("GDR-WT-2: a reflog entry that cannot be written does not fail the created commit") + @DisplayName("GDR-CORE-13: a reflog entry that cannot be written does not fail the created commit") void reflogFailureKeepsCommit(@LocalRepository Repository source) throws Exception { var upper = Generators.strings("ABCDEFGHIJKLMNOPQRSTUVWXYZ", 12, 20); var main = mainTree(source, temp); @@ -1727,11 +1728,11 @@ void reflogFailureKeepsCommit(@LocalRepository Repository source) throws Excepti () -> assertAll(forbidden.stream().map(value -> () -> assertFalse( logs.contains(value), "no log message carries " + value)))); LogAsserts.assertSingleLogMessagePresentContaining(TestLogLevel.WARN, - GitWorktreesLogMessages.WARN.REFLOG_NOT_WRITTEN.resolveIdentifierString()); + GitCoreLogMessages.WARN.REFLOG_NOT_WRITTEN.resolveIdentifierString()); } @Test - @DisplayName("GDR-WT-2: an invalid core.logAllRefUpdates value does not fail the created commit") + @DisplayName("GDR-CORE-13: an invalid core.logAllRefUpdates value does not fail the created commit") void invalidLogAllRefUpdatesKeepsCommit(@LocalRepository Repository source) throws Exception { var main = mainTree(source, temp); var branch = name(); @@ -1756,7 +1757,7 @@ void invalidLogAllRefUpdatesKeepsCommit(@LocalRepository Repository source) thro () -> assertTrue(TestLoggerFactory.getTestHandler().getRecordsAsString().contains(info.id()), "the warning names the commit id")); LogAsserts.assertSingleLogMessagePresentContaining(TestLogLevel.WARN, - GitWorktreesLogMessages.WARN.REFLOG_NOT_WRITTEN.resolveIdentifierString()); + GitCoreLogMessages.WARN.REFLOG_NOT_WRITTEN.resolveIdentifierString()); } } @@ -1797,7 +1798,7 @@ void noPersonalDataInLogsOrDetails(@LocalRepository Repository source) throws Ex var forbidden = List.of(author.name(), author.email(), committer.name(), committer.email(), message); assertAll( () -> assertEquals(2, handler.resolveLogMessagesContaining(TestLogLevel.INFO, - GitWorktreesLogMessages.PREFIX).size(), "the add and the remove are logged at INFO"), + GitCoreLogMessages.PREFIX).size(), "the add and the remove are logged at INFO"), () -> assertTrue(handler.resolveLogMessagesContaining(TestLogLevel.INFO, worktree.path().toString()).isEmpty(), "no INFO message carries the working-tree path"), () -> assertTrue(handler.resolveLogMessagesContaining(TestLogLevel.INFO, diff --git a/git-worktrees/src/test/java/de/cuioss/git/document/worktrees/LinkedWorktreesTest.java b/git-core/src/test/java/de/cuioss/git/document/core/worktrees/LinkedWorktreesTest.java similarity index 97% rename from git-worktrees/src/test/java/de/cuioss/git/document/worktrees/LinkedWorktreesTest.java rename to git-core/src/test/java/de/cuioss/git/document/core/worktrees/LinkedWorktreesTest.java index 7fda39c..1506711 100644 --- a/git-worktrees/src/test/java/de/cuioss/git/document/worktrees/LinkedWorktreesTest.java +++ b/git-core/src/test/java/de/cuioss/git/document/core/worktrees/LinkedWorktreesTest.java @@ -13,7 +13,7 @@ * See the License for the specific language governing permissions and * limitations under the License. */ -package de.cuioss.git.document.worktrees; +package de.cuioss.git.document.core.worktrees; import static org.junit.jupiter.api.Assertions.assertAll; import static org.junit.jupiter.api.Assertions.assertDoesNotThrow; @@ -198,7 +198,7 @@ void concurrentCreationsClaimDistinctDirectories(@LocalRepository Repository rep } @Test - @DisplayName("GDR-WT-1: a failed initialization write leaves no administration directory and keeps the worktree") + @DisplayName("GDR-CORE-12: a failed initialization write leaves no administration directory and keeps the worktree") void failedCreationRemovesAdministration(@LocalRepository Repository repository) throws Exception { var name = name(); var worktree = worktreeRoot(name); @@ -222,7 +222,7 @@ void failedCreationRemovesAdministration(@LocalRepository Repository repository) } @Test - @DisplayName("GDR-WT-1: an entry without gitdir or HEAD is skipped, a complete locked one is listed") + @DisplayName("GDR-CORE-12: an entry without gitdir or HEAD is skipped, a complete locked one is listed") void incompleteEntriesSkipped(@LocalRepository Repository repository) throws Exception { var worktree = worktreeRoot(name()); var complete = LinkedWorktrees.create(commonDir(repository), worktree, Constants.R_HEADS + name()); @@ -243,7 +243,7 @@ void incompleteEntriesSkipped(@LocalRepository Repository repository) throws Exc } @Test - @DisplayName("GDR-WT-1: a relative gitdir entry resolves against the administration directory") + @DisplayName("GDR-CORE-12: a relative gitdir entry resolves against the administration directory") void relativeGitdirResolved(@LocalRepository Repository repository) throws Exception { var worktree = worktreeRoot(name()); var admin = LinkedWorktrees.create(commonDir(repository), worktree, Constants.R_HEADS + name()); @@ -259,7 +259,7 @@ void relativeGitdirResolved(@LocalRepository Repository repository) throws Excep } @Test - @DisplayName("GDR-WT-1: a branch is reserved for one creation at a time and free again once released") + @DisplayName("GDR-CORE-12: a branch is reserved for one creation at a time and free again once released") void branchReservation(@LocalRepository Repository repository) throws Exception { var branch = Constants.R_HEADS + name(); diff --git a/git-worktrees/src/test/java/de/cuioss/git/document/worktrees/WorktreeOperationsRecordsTest.java b/git-core/src/test/java/de/cuioss/git/document/core/worktrees/WorktreeOperationsRecordsTest.java similarity index 94% rename from git-worktrees/src/test/java/de/cuioss/git/document/worktrees/WorktreeOperationsRecordsTest.java rename to git-core/src/test/java/de/cuioss/git/document/core/worktrees/WorktreeOperationsRecordsTest.java index f11e64d..6051d39 100644 --- a/git-worktrees/src/test/java/de/cuioss/git/document/worktrees/WorktreeOperationsRecordsTest.java +++ b/git-core/src/test/java/de/cuioss/git/document/core/worktrees/WorktreeOperationsRecordsTest.java @@ -13,7 +13,7 @@ * See the License for the specific language governing permissions and * limitations under the License. */ -package de.cuioss.git.document.worktrees; +package de.cuioss.git.document.core.worktrees; import static org.junit.jupiter.api.Assertions.assertAll; import static org.junit.jupiter.api.Assertions.assertEquals; @@ -29,10 +29,10 @@ import de.cuioss.git.document.core.RepositoryOperations.Identity; -import de.cuioss.git.document.worktrees.WorktreeOperations.CommitInput; -import de.cuioss.git.document.worktrees.WorktreeOperations.Worktree; -import de.cuioss.git.document.worktrees.WorktreeOperations.WorktreeAddInput; -import de.cuioss.git.document.worktrees.WorktreeOperations.WorktreeStatus; +import de.cuioss.git.document.core.worktrees.WorktreeOperations.CommitInput; +import de.cuioss.git.document.core.worktrees.WorktreeOperations.Worktree; +import de.cuioss.git.document.core.worktrees.WorktreeOperations.WorktreeAddInput; +import de.cuioss.git.document.core.worktrees.WorktreeOperations.WorktreeStatus; import de.cuioss.test.generator.Generators; import de.cuioss.test.generator.junit.EnableGeneratorController; import org.junit.jupiter.api.DisplayName; @@ -93,7 +93,7 @@ void worktreeEqualsOverEveryComponent() { } @Test - @DisplayName("GDR-WT-3: statuses with the same paths are equal whatever the order or type of the input sets") + @DisplayName("GDR-CORE-14: statuses with the same paths are equal whatever the order or type of the input sets") void worktreeStatusEqualsOverPaths() { var paths = new HashSet(); while (paths.size() < 3) { @@ -177,7 +177,7 @@ void worktreeAddInputRefusesMissingPathAndStartPoint() { } @Test - @DisplayName("GDR-WT-3: the working-tree status refuses every missing set and every missing path") + @DisplayName("GDR-CORE-14: the working-tree status refuses every missing set and every missing path") void worktreeStatusRefusesMissingSets() { var paths = Set.of(text()); var withNull = new HashSet(); @@ -199,7 +199,7 @@ void worktreeStatusRefusesMissingSets() { } @Test - @DisplayName("GDR-WT-3: the working-tree status keeps a sorted copy that neither the caller nor a reader changes") + @DisplayName("GDR-CORE-14: the working-tree status keeps a sorted copy that neither the caller nor a reader changes") void worktreeStatusCopiesSortedAndUnmodifiable() { var changed = new HashSet(); while (changed.size() < 3) { diff --git a/git-worktrees/src/test/java/de/cuioss/git/document/worktrees/WorktreeStatusTest.java b/git-core/src/test/java/de/cuioss/git/document/core/worktrees/WorktreeStatusTest.java similarity index 93% rename from git-worktrees/src/test/java/de/cuioss/git/document/worktrees/WorktreeStatusTest.java rename to git-core/src/test/java/de/cuioss/git/document/core/worktrees/WorktreeStatusTest.java index 7c81611..aff53d2 100644 --- a/git-worktrees/src/test/java/de/cuioss/git/document/worktrees/WorktreeStatusTest.java +++ b/git-core/src/test/java/de/cuioss/git/document/core/worktrees/WorktreeStatusTest.java @@ -13,9 +13,9 @@ * See the License for the specific language governing permissions and * limitations under the License. */ -package de.cuioss.git.document.worktrees; +package de.cuioss.git.document.core.worktrees; -import static de.cuioss.git.document.worktrees.JGitWorktreeOperationsTest.name; +import static de.cuioss.git.document.core.worktrees.JGitWorktreeOperationsTest.name; import static org.junit.jupiter.api.Assertions.assertAll; import static org.junit.jupiter.api.Assertions.assertEquals; @@ -29,9 +29,9 @@ import de.cuioss.git.document.core.GitOutcome; import de.cuioss.git.document.core.RepositoryOperations.Identity; +import de.cuioss.git.document.core.worktrees.WorktreeOperations.WorktreeAddInput; +import de.cuioss.git.document.core.worktrees.WorktreeOperations.WorktreeStatus; import de.cuioss.git.document.testing.LocalRepository; -import de.cuioss.git.document.worktrees.WorktreeOperations.WorktreeAddInput; -import de.cuioss.git.document.worktrees.WorktreeOperations.WorktreeStatus; import de.cuioss.test.generator.Generators; import de.cuioss.test.generator.junit.EnableGeneratorController; import org.eclipse.jgit.api.Git; @@ -48,7 +48,7 @@ import org.junit.jupiter.params.provider.EnumSource; /** - * The status of a working tree mapped from JGit's {@code Status} (JGit 7.8.0, GDR-WT-3): one scenario per JGit + * The status of a working tree mapped from JGit's {@code Status} (JGit 7.8.0, GDR-CORE-14): one scenario per JGit * category on a main working tree cloned from a {@code git-testing} fixture repository, each asserting the exact * three sets, and the union of the three sets against the path union of the seven JGit categories the source * {@code worktreeSha} reads. The working trees are prepared with JGit's porcelain API in the test, never through the @@ -185,9 +185,9 @@ private WorktreeStatus status(Path root) { return Objects.requireNonNull(result.value(), "the status is read: " + result.detail()); } - @ParameterizedTest(name = "GDR-WT-3: {0}") + @ParameterizedTest(name = "GDR-CORE-14: {0}") @EnumSource(Scenario.class) - @DisplayName("GDR-WT-3: each JGit category lands in exactly the documented sets") + @DisplayName("GDR-CORE-14: each JGit category lands in exactly the documented sets") void mapsEachCategory(Scenario scenario, @LocalRepository Repository source) throws Exception { var main = JGitWorktreeOperationsTest.mainTree(source, temp); var path = apply(scenario, main); @@ -200,9 +200,9 @@ void mapsEachCategory(Scenario scenario, @LocalRepository Repository source) thr () -> assertEquals(expected(scenario.deleted, path), status.deleted(), "the deleted paths")); } - @ParameterizedTest(name = "GDR-WT-3: the union equals the JGit path union when {0}") + @ParameterizedTest(name = "GDR-CORE-14: the union equals the JGit path union when {0}") @EnumSource(Scenario.class) - @DisplayName("GDR-WT-3: the union of the three sets is the path union of the seven JGit categories") + @DisplayName("GDR-CORE-14: the union of the three sets is the path union of the seven JGit categories") void unionEqualsJGitUnion(Scenario scenario, @LocalRepository Repository source) throws Exception { var main = JGitWorktreeOperationsTest.mainTree(source, temp); apply(scenario, main); @@ -230,7 +230,7 @@ void unionEqualsJGitUnion(Scenario scenario, @LocalRepository Repository source) } @Test - @DisplayName("GDR-WT-3: the status of a linked working tree is its own, not the main one's") + @DisplayName("GDR-CORE-14: the status of a linked working tree is its own, not the main one's") void linkedWorktree(@LocalRepository Repository source) throws Exception { var main = JGitWorktreeOperationsTest.mainTree(source, temp); var added = operations.worktreeAdd(WorktreeAddInput.builder().root(main.root()) @@ -255,7 +255,7 @@ void linkedWorktree(@LocalRepository Repository source) throws Exception { * and therefore has nothing to commit. The two operations deliberately disagree on that one path. */ @Test - @DisplayName("GDR-WT-3: a nested linked root is untracked in the main status, but commit has nothing to commit") + @DisplayName("GDR-CORE-14: a nested linked root is untracked in the main status, but commit has nothing to commit") void nestedLinkedRootStatusAgainstCommit(@LocalRepository Repository source) throws Exception { var main = JGitWorktreeOperationsTest.mainTree(source, temp); var added = operations.worktreeAdd(WorktreeAddInput.builder().root(main.root()) @@ -285,7 +285,7 @@ void nestedLinkedRootStatusAgainstCommit(@LocalRepository Repository source) thr * {@code process_execution}. The attribute and configuration keys are git's own vocabulary. */ @Test - @DisplayName("GDR-WT-3: a clean filter in .gitattributes is run by the status and refused") + @DisplayName("GDR-CORE-14: a clean filter in .gitattributes is run by the status and refused") void cleanFilterRefused(@LocalRepository Repository source) throws Exception { var main = JGitWorktreeOperationsTest.mainTree(source, temp); var driver = name(); @@ -312,7 +312,7 @@ private static Identity identity() { } @Test - @DisplayName("GDR-WT-3: a plain directory is not a repository, a repository without working tree fails") + @DisplayName("GDR-CORE-14: a plain directory is not a repository, a repository without working tree fails") void notARepositoryAndFailed(@LocalRepository Repository bare) throws Exception { var plain = Files.createDirectories(temp.resolve(name())); diff --git a/git-worktrees/doc/LogMessages.adoc b/git-worktrees/doc/LogMessages.adoc deleted file mode 100644 index b62abfc..0000000 --- a/git-worktrees/doc/LogMessages.adoc +++ /dev/null @@ -1,50 +0,0 @@ -= Log Messages for git-worktrees -:toc: left -:toclevels: 2 - -== Overview - -The log-message catalogue of `git-worktrees` -(xref:../../doc/specification/general.adoc#GDR-GEN-4[GDR-GEN-4]). Every message at level INFO, WARN or ERROR carries a -stable identifier of the form `GIT_WORKTREES-`, rendered by `LogRecord#resolveIdentifierString()` without -leading zeros; the identifiers follow the CUI `LogRecord` ranges (INFO 1-99, -WARN 100-199, ERROR 200-299). The messages are declared in -`de.cuioss.git.document.worktrees.GitWorktreesLogMessages`. - -No message carries anything xref:../../doc/specification/general.adoc#GDR-NFR-3[GDR-NFR-3] forbids: a message names a -commit id or a refused capability, never a path, an administrative name derived from the caller's path, a branch name, -an author or committer name, an e-mail address or a commit message. -Debug and trace messages carry no identifier and are not listed. - -== INFO Level (1-99) - -[cols="1,1,2,2", options="header"] -|=== -|ID |Component |Message |Description -|GIT_WORKTREES-1 |GIT_WORKTREES |Added a linked working tree at commit %s |Logged when `worktreeAdd` created a -linked working tree: the commit id it starts at. -|GIT_WORKTREES-2 |GIT_WORKTREES |Removed a linked working tree |Logged when `worktreeRemove` removed a linked working -tree or the administration files of a prunable one; the message carries no argument. -|GIT_WORKTREES-3 |GIT_WORKTREES |Released a branch reservation |Logged when `releaseBranchReservation` deleted the -reservation file of a branch; the message carries no argument, neither the branch name nor a path. -|=== - -== WARN Level (100-199) - -[cols="1,1,2,2", options="header"] -|=== -|ID |Component |Message |Description -|GIT_WORKTREES-100 |GIT_WORKTREES |Refused capability %s |Logged when the refusing file system refused a capability, -a present hook (`repository_hook`) or a process start (`process_execution`); the result is `REFUSED_BY_POLICY`. -|GIT_WORKTREES-101 |GIT_WORKTREES |Created commit %s, its reflog entry was not written |Logged when `commit` created -a commit in a linked working tree but could not append its reflog entries: the commit id only. The commit and its -branch are stored, so the result stays `OK` with the commit. -|GIT_WORKTREES-102 |GIT_WORKTREES |The rollback of a failed working-tree addition is incomplete |Logged when the -rollback of a refused or failed `worktreeAdd` could not undo everything the addition created, for example a created -branch still at its start commit that could not be deleted; the message carries no argument, neither the branch name -nor a path. The addition ends `FAILED` or with the outcome of the failure it rolled back. -|=== - -== ERROR Level (200-299) - -`git-worktrees` logs no message at level ERROR: an unexpected failure is returned as the outcome `FAILED`. diff --git a/git-worktrees/pom.xml b/git-worktrees/pom.xml deleted file mode 100644 index 6f844d6..0000000 --- a/git-worktrees/pom.xml +++ /dev/null @@ -1,117 +0,0 @@ - - - 4.0.0 - - de.cuioss - git-document-repository - 0.1.0-SNAPSHOT - - git-worktrees - jar - git-worktrees - Linked working trees, commit from a working tree and working-tree status. - - de.cuioss.git.document.worktrees - - - - ${project.groupId} - git-core - ${project.version} - - - org.jspecify - jspecify - - - de.cuioss - cui-java-tools - - - org.projectlombok - lombok - provided - - - de.cuioss - git-testing - ${project.version} - test - - - org.junit.jupiter - junit-jupiter-api - test - - - org.junit.jupiter - junit-jupiter-params - test - - - org.junit.jupiter - junit-jupiter-engine - test - - - de.cuioss.test - cui-test-generator - test - - - de.cuioss.test - cui-test-juli-logger - test - - - - - - - org.apache.maven.plugins - maven-enforcer-plugin - - - module-layering - - - - - de.cuioss:git-core - - - - - - - - - - org.apache.maven.plugins - maven-surefire-plugin - - false - - - - org.apache.maven.plugins - maven-compiler-plugin - - - - org.projectlombok - lombok - - - - - - - diff --git a/git-worktrees/src/main/java/de/cuioss/git/document/worktrees/GitWorktreesLogMessages.java b/git-worktrees/src/main/java/de/cuioss/git/document/worktrees/GitWorktreesLogMessages.java deleted file mode 100644 index 6e99872..0000000 --- a/git-worktrees/src/main/java/de/cuioss/git/document/worktrees/GitWorktreesLogMessages.java +++ /dev/null @@ -1,103 +0,0 @@ -/* - * Copyright © 2026-present CUI-OpenSource-Software (info@cuioss.de) - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ -package de.cuioss.git.document.worktrees; - -import de.cuioss.tools.logging.LogRecord; -import de.cuioss.tools.logging.LogRecordModel; -import lombok.experimental.UtilityClass; - -/** - * The {@link LogRecord} holder of {@code git-worktrees} (GDR-GEN-4). Identifiers carry the prefix {@value #PREFIX} and - * follow the CUI ranges: INFO 1-99, WARN 100-199, ERROR 200-299. The catalogue is - * {@code git-worktrees/doc/LogMessages.adoc}. - *

- * No message carries anything GDR-NFR-3 forbids: a message names a commit id or a refused capability, never a path, an - * administrative name derived from the caller's path, a branch name, an author or committer name, an e-mail address or - * a commit message. - * - * @since 0.1 - */ -@UtilityClass -public final class GitWorktreesLogMessages { - - /** The prefix of every identifier of {@code git-worktrees}. */ - public static final String PREFIX = "GIT_WORKTREES"; - - /** - * Messages at level INFO. - * - * @since 0.1 - */ - @UtilityClass - public static final class INFO { - - /** A linked working tree was added: the commit it starts at. */ - public static final LogRecord WORKTREE_ADDED = LogRecordModel.builder() - .template("Added a linked working tree at commit %s") - .prefix(PREFIX) - .identifier(1) - .build(); - - /** A linked working tree was removed; the message carries no argument. */ - public static final LogRecord WORKTREE_REMOVED = LogRecordModel.builder() - .template("Removed a linked working tree") - .prefix(PREFIX) - .identifier(2) - .build(); - - /** - * A branch reservation was released; the message carries no argument, neither the branch name nor a path. - */ - public static final LogRecord BRANCH_RESERVATION_RELEASED = LogRecordModel.builder() - .template("Released a branch reservation") - .prefix(PREFIX) - .identifier(3) - .build(); - } - - /** - * Messages at level WARN. - * - * @since 0.1 - */ - @UtilityClass - public static final class WARN { - - /** A capability was refused by the refusing file system: the refused capability. */ - public static final LogRecord CAPABILITY_REFUSED = LogRecordModel.builder() - .template("Refused capability %s") - .prefix(PREFIX) - .identifier(100) - .build(); - - /** A commit was created in a linked working tree but its reflog entry was not written: the commit id. */ - public static final LogRecord REFLOG_NOT_WRITTEN = LogRecordModel.builder() - .template("Created commit %s, its reflog entry was not written") - .prefix(PREFIX) - .identifier(101) - .build(); - - /** - * The rollback of a refused or failed addition did not undo everything it created, for example a created - * branch it could not delete; the message carries no argument, neither the branch name nor a path. - */ - public static final LogRecord ROLLBACK_INCOMPLETE = LogRecordModel.builder() - .template("The rollback of a failed working-tree addition is incomplete") - .prefix(PREFIX) - .identifier(102) - .build(); - } -} diff --git a/git-worktrees/src/main/java/module-info.java b/git-worktrees/src/main/java/module-info.java deleted file mode 100644 index 7420757..0000000 --- a/git-worktrees/src/main/java/module-info.java +++ /dev/null @@ -1,26 +0,0 @@ -/* - * Copyright © 2026-present CUI-OpenSource-Software (info@cuioss.de) - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ -/** - * Linked working trees, commit from a working tree and working-tree status. - */ -module de.cuioss.git.document.worktrees { - exports de.cuioss.git.document.worktrees; - - requires transitive de.cuioss.git.document.core; - requires de.cuioss.java.tools; - requires static lombok; - requires static org.jspecify; -} diff --git a/git-worktrees/src/test/java/de/cuioss/git/document/worktrees/DomainTermAbsenceTest.java b/git-worktrees/src/test/java/de/cuioss/git/document/worktrees/DomainTermAbsenceTest.java deleted file mode 100644 index efa858c..0000000 --- a/git-worktrees/src/test/java/de/cuioss/git/document/worktrees/DomainTermAbsenceTest.java +++ /dev/null @@ -1,99 +0,0 @@ -/* - * Copyright © 2026-present CUI-OpenSource-Software (info@cuioss.de) - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ -package de.cuioss.git.document.worktrees; - -import static org.junit.jupiter.api.Assertions.assertEquals; -import static org.junit.jupiter.api.Assertions.assertFalse; - -import java.io.IOException; -import java.lang.reflect.Modifier; -import java.net.URISyntaxException; -import java.nio.file.Files; -import java.nio.file.Path; -import java.util.ArrayList; -import java.util.List; -import java.util.Locale; -import java.util.stream.Stream; - - -import org.junit.jupiter.api.DisplayName; -import org.junit.jupiter.api.Test; - -/** - * GDR-GEN-1: the libraries carry no domain term. No public type of {@code git-worktrees}, by its simple name or its - * package name, contains one of the domain terms of the application, compared case-insensitively. The scan reads the - * main output directory of the module, located through the code source of {@link WorktreeOperations}, and loads each - * class without initialising it. - */ -@DisplayName("git-worktrees public types carry no domain term (GDR-GEN-1)") -class DomainTermAbsenceTest { - - /** The domain terms of GDR-GEN-1, in lower case. */ - private static final List DOMAIN_TERMS = List.of("assessment", "threat", "incident", "risk"); - - /** The file suffix of a compiled class. */ - private static final String CLASS_SUFFIX = ".class"; - - @Test - @DisplayName("Should find public types and none of them names a domain term") - void shouldCarryNoDomainTermInPublicTypes() throws Exception { - var publicTypes = publicTypesOfMainOutput(); - - var violations = new ArrayList(); - for (Class type : publicTypes) { - var simpleName = type.getSimpleName().toLowerCase(Locale.ROOT); - var packageName = type.getPackageName().toLowerCase(Locale.ROOT); - for (String term : DOMAIN_TERMS) { - if (simpleName.contains(term) || packageName.contains(term)) { - violations.add(type.getName() + " contains '" + term + "'"); - } - } - } - - assertFalse(publicTypes.isEmpty(), "The scan must find at least one public type of git-worktrees"); - assertEquals(List.of(), violations, "Public types of git-worktrees must not carry a domain term of GDR-GEN-1"); - } - - /** - * Loads every class of the main output directory without initialising it and keeps the public ones. - * - * @return the public types of the main output directory, never {@code null} - */ - private static List> publicTypesOfMainOutput() - throws IOException, URISyntaxException, ClassNotFoundException { - var root = Path.of(WorktreeOperations.class.getProtectionDomain().getCodeSource().getLocation().toURI()); - var loader = WorktreeOperations.class.getClassLoader(); - List classNames; - try (Stream files = Files.walk(root)) { - classNames = files.filter(Files::isRegularFile) - .map(root::relativize) - .map(Path::toString) - .filter(name -> name.endsWith(CLASS_SUFFIX)) - .map(name -> name.substring(0, name.length() - CLASS_SUFFIX.length())) - .filter(name -> !name.endsWith("module-info") && !name.endsWith("package-info")) - .map(name -> name.replace(root.getFileSystem().getSeparator(), ".")) - .toList(); - } - var publicTypes = new ArrayList>(); - for (String className : classNames) { - Class type = Class.forName(className, false, loader); - if (Modifier.isPublic(type.getModifiers())) { - publicTypes.add(type); - } - } - return publicTypes; - } -} diff --git a/pom.xml b/pom.xml index a95ad27..38cf72b 100644 --- a/pom.xml +++ b/pom.xml @@ -49,7 +49,6 @@ git-core - git-worktrees git-store git-testing