Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 9 additions & 4 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ released together and consumed separately.
|---|---|---|
| `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` |
| `git-store` | Repository registry, typed configuration, codec interface, outcome list and result, service interfaces with provider selection; write path: reference layout, drafts, explicit save with lease, conflicts and change detection, draft expiry | `git-core` |

Planned but not yet created: `git-forms`, `git-timestamp`, `git-directory` (see
`doc/concepts/module-structure.adoc` for the order and the dependency graph).
Expand All @@ -51,10 +51,15 @@ fixtures. `git-store` exports `de.cuioss.git.document.store` with the foundation
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
`StoreConfiguration.from` from an already-parsed nested map, over the package-private reader `ConfigurationTree`), the
`StoreConfiguration.from` from an already-parsed nested map, over the package-private reader `ConfigurationTree`; its
sections include `commit`, the record `Commit` with `commit.email`), the
service interfaces `SigningKeySource`, `AnchorProvider` and `PersonDirectory` with `PersonEntry` and `Membership`, the
provider selection `StoreProviders` through `ServiceLoader`, and the `LogRecord` holder `GitStoreLogMessages`; its
tests run on the class path against the `git-testing` fixtures. Add an `exports` directive together with the first
provider selection `StoreProviders` through `ServiceLoader`, and the `LogRecord` holder `GitStoreLogMessages`; and the
write path: `StoreWriter` (drafts, listing, explicit save with lease, draft expiry with garbage collection) with
`StoreReferences`, `DocumentCollection`, `DocumentKey`, `Ulid`, `Draft`, `SaveResult`, `TechnicalUser` and `Author`,
over the package-private `DraftReferences`, `ExplicitSave`, `DraftExpiry`, `CommitIdentities` and `RepositoryGuard`;
the commits it writes are unsigned and carry no trailers until GDR-STORE-12/13. Its tests run on the class path against
the `git-testing` fixtures. Add an `exports` directive together with the first
public class of a package: javac rejects exporting a package that contains only `package-info.java`.

The build guards GDR-GEN-1 (`doc/specification/general.adoc`) with the `maven-enforcer-plugin` that `cui-parent-pom`
Expand Down
16 changes: 11 additions & 5 deletions doc/README.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -121,9 +121,14 @@ xref:specification/git-core.adoc#GDR-CORE-10[GDR-CORE-10], xref:specification/gi
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-store.adoc#GDR-STORE-1[GDR-STORE-1],
xref:specification/git-store.adoc#GDR-STORE-11[GDR-STORE-11] and the write path
xref:specification/git-store.adoc#GDR-STORE-2[GDR-STORE-2], xref:specification/git-store.adoc#GDR-STORE-3[GDR-STORE-3],
xref:specification/git-store.adoc#GDR-STORE-4[GDR-STORE-4], xref:specification/git-store.adoc#GDR-STORE-5[GDR-STORE-5],
xref:specification/git-store.adoc#GDR-STORE-7[GDR-STORE-7] and
xref:specification/git-store.adoc#GDR-STORE-8[GDR-STORE-8] of `git-store`, together with its configuration, its
outcome list and its service interfaces; xref:specification/general.adoc#GDR-NFR-2[GDR-NFR-2] and the write-path part
of xref:specification/general.adoc#GDR-NFR-3[GDR-NFR-3] are covered by tests of `git-store`.
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, covering its
Expand All @@ -145,8 +150,9 @@ of a branch reservation
|Repository fixtures and the credential generator

|xref:specification/git-store.adoc[git-store]
|Registry, outcome list, drafts, saving, release, identity, index, listeners, codecs, signature, verification,
anchoring, own timestamp, person directory interface, configuration
|Registry, outcome list, the write path (drafts, explicit save with lease, conflicts and change detection, draft
expiry), release, identity, index, listeners, codecs, signature, verification, anchoring, own timestamp, person
directory interface, configuration

|xref:specification/git-forms.adoc[git-forms]
|Kinds of documents, schema validation, data layout, generated output, workflow, deadlines, step-up, links, running
Expand Down
3 changes: 2 additions & 1 deletion doc/concepts/module-structure.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,8 @@ reading, notes, working trees
|Drafts, saving, release, commit signature and identity trailers, index, post-commit listeners, anchoring with the own
timestamp (xref:storage-engine.adoc[Storage Engine], xref:identity-and-signing.adoc[Identity and Signing])
|implemented: repository registry, typed configuration, codec interface, outcome list and result, service interfaces
and provider selection; planned: drafts, saving, release, signature, trailers, index, listeners, anchoring
and provider selection, drafts, explicit save with lease, conflicts and change detection, draft expiry; planned:
release, signature, trailers, index, listeners, anchoring

|`git-forms`
|Schema-driven documents: schema, template, workflow, deadlines, step-up for releases
Expand Down
24 changes: 16 additions & 8 deletions doc/specification/general.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -11,12 +11,15 @@ its requirements (xref:git-testing.adoc#GDR-TEST-1[GDR-TEST-1], xref:git-testing
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; 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, <<GDR-GEN-1>> is implemented, and for <<GDR-NFR-4>> `git-core` ships its native-image metadata,
which this repository does not verify yet; every other requirement of the libraries is planned, and the other modules
are not yet created.
`git-store` implements xref:git-store.adoc#GDR-STORE-1[GDR-STORE-1], xref:git-store.adoc#GDR-STORE-11[GDR-STORE-11]
and its configuration, and its write path: xref:git-store.adoc#GDR-STORE-2[GDR-STORE-2],
xref:git-store.adoc#GDR-STORE-3[GDR-STORE-3], xref:git-store.adoc#GDR-STORE-4[GDR-STORE-4],
xref:git-store.adoc#GDR-STORE-5[GDR-STORE-5], xref:git-store.adoc#GDR-STORE-7[GDR-STORE-7] and
xref:git-store.adoc#GDR-STORE-8[GDR-STORE-8]; it defines its three service interfaces, whose providers are planned
(xref:git-store.adoc[`git-store`]). Of the requirements below, <<GDR-GEN-1>> is implemented; <<GDR-NFR-2>> and the
write-path part of <<GDR-NFR-3>> are covered by tests of `git-store` (`ConcurrentWritersTest`,
`WritePathSecretsTest`); and for <<GDR-NFR-4>> `git-core` ships its native-image metadata, which this repository does
not verify yet. Every other requirement of the libraries is planned, and the other modules are not yet created.

[#GDR-GEN-1]
== GDR-GEN-1: Module Layering and Dependency Isolation
Expand Down Expand Up @@ -261,7 +264,10 @@ The test is to run the writers as threads against a local remote of `git-testing

* No token, password, private or secret key material, session id, `sub`, e-mail address or person name may appear in
a result detail, an exception message, a log message or the metadata of a commit (author, committer, message,
trailers); the person entry of the `git` directory is the one file that holds a name.
trailers); the person entry of the `git` directory is the one file that holds a name. The one exception: the e-mail
fields of author and committer may carry an address only when the operator sets `commit.email` to `true`
(xref:git-store.adoc#store-configuration[`git-store`, Configuration]); by default they stay empty, and an address
never appears in a result detail, an exception message, a log message, a commit message or a trailer.
* Public keys (commit-signing and anchor keys) are no secrets and may be stored.

[cols="1,2"]
Expand All @@ -272,7 +278,9 @@ The test is to run the writers as threads against a local remote of `git-testing
read from the application's configuration for the call; never stored, logged, committed or put into a detail
|signing and anchor keys |held by the key source or in memory; never written in clear text
|`sub`, e-mail address, person name |`sub` only as the subject hash of the person entry; the name only in the person
entry; never in the metadata of a commit (author, committer, message, trailers), a document or a log
entry; never in the metadata of a commit (author, committer, message, trailers), a document or a log, except an
address in the e-mail fields of author and committer when the operator sets `commit.email` to `true`
(xref:git-store.adoc#store-configuration[`git-store`, Configuration]); by default those fields stay empty
|===

Tests are to assert the rules with a JUL log capture (`cui-test-juli-logger`, declared in the test scope of `git-core`
Expand Down
15 changes: 14 additions & 1 deletion doc/specification/git-core.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -172,7 +172,12 @@ The operation is `cloneIfMissing`. An existing bare repository at the git direct
remote; a directory that holds anything else is `NOT_A_REPOSITORY`. Otherwise the URL is checked against the remote
policy (`REFUSED_BY_POLICY` without contact), a bare repository is initialised, and its remote `origin` is configured
and fetched. The fetch refspecs mirror the remote's branches, tags and notes into the clone:
`+refs/heads/*:refs/heads/*`, `+refs/tags/*:refs/tags/*` and `+refs/notes/*:refs/notes/*`.
`+refs/heads/*:refs/heads/*`, `+refs/tags/*:refs/tags/*` and `+refs/notes/*:refs/notes/*`. They are public as the
unmodifiable list `JGitRepositoryOperations.MIRROR_FETCH_REF_SPECS`, the one source of that set: a caller that prunes a
clone passes it to `fetch` explicitly, so the prune of <<GDR-CORE-7>> deletes only references below the mirrored
namespaces, whatever fetch refspecs the clone's configuration holds (JGit 7.8.0 `Transport.fetch` falls back to the
configured fetch refspecs only for an empty list, and `FetchProcess.deleteStaleTrackingRefs` deletes only references
matching the destination of a fetched refspec).

The stored origin carries no user information: the URL is configured without user name and password
(`URIish.setUser(null).setPass(null)`), so no credential reaches the persistent configuration of the clone; the
Expand Down Expand Up @@ -419,6 +424,14 @@ an update was not written
`LOCK_FAILURE`, `IO_FAILURE` and every other result end it `FAILED`. The detail names the local reference and the
result.

A fetch with `FetchInput.prune` set (`false` by default) also deletes every local reference that lies in the
destination of one of its reference specifications and whose source the remote no longer advertises, through
`FetchCommand.setRemoveDeletedRefs`; JGit 7.8.0 `FetchProcess.deleteStaleTrackingRefs` considers only the local
references that match a destination of the fetch's reference specifications, so a reference outside every
destination, such as a draft below `refs/drafts/` of `git-store`, is never deleted
(link:https://github.com/eclipse-jgit/jgit/blob/v7.8.0.202609011348-r/org.eclipse.jgit/src/org/eclipse/jgit/transport/FetchProcess.java[JGit
7.8.0 `FetchProcess`]).

Every transport of a clone, a fetch and a push runs with a compiled timeout of 60 seconds
(`JGitRepositoryOperations.TRANSPORT_TIMEOUT_SECONDS`, set through `TransportCommand.setTimeout`;
link:https://github.com/eclipse-jgit/jgit/blob/v7.8.0.202609011348-r/org.eclipse.jgit/src/org/eclipse/jgit/api/TransportCommand.java[JGit
Expand Down
Loading
Loading