Inspect changes in Gitaly c0b07ba36fc8fc40830f061cb55a5c951a166e1c
Upstream merge commit 1e350f9abd16 changes Gitaly server version from 251acb8c75aa66481893bf775a44cba669ccc3c9 to c0b07ba36fc8fc40830f061cb55a5c951a166e1c, with changes in protocol or one of the source subtrees currently under watch.
To further inspect, go to an up to date Gitaly source clone and run:
git diff 251acb8c75aa66481893bf775a44cba669ccc3c9..c0b07ba36fc8fc40830f061cb55a5c951a166e1c -- proto/*.proto internal/backup
Here is a preview, truncated at 500 lines:
diff --git a/proto/repository.proto b/proto/repository.proto
index 27c5ce666..0445ce3a4 100644
--- a/proto/repository.proto
+++ b/proto/repository.proto
@@ -10,7 +10,7 @@ option go_package = "gitlab.com/gitlab-org/gitaly/v16/proto/go/gitalypb";
// RepositoryService is a service providing RPCs accessing repositories as a whole.
service RepositoryService {
- // RepositoryExists ...
+ // RepositoryExists returns whether a given repository exists.
rpc RepositoryExists(RepositoryExistsRequest) returns (RepositoryExistsResponse) {
option (op_type) = {
op: ACCESSOR
@@ -78,28 +78,29 @@ service RepositoryService {
}
// FetchRemote fetches references from a remote repository into the local
- // repository.
+ // repository. The remote can be fetched via HTTP or SSH depending on the
+ // request options provided.
rpc FetchRemote(FetchRemoteRequest) returns (FetchRemoteResponse) {
option (op_type) = {
op: MUTATOR
};
}
- // CreateRepository ...
+ // CreateRepository creates a new empty repository.
rpc CreateRepository(CreateRepositoryRequest) returns (CreateRepositoryResponse) {
option (op_type) = {
op: MUTATOR
};
}
- // GetArchive ...
+ // GetArchive produces and returns an archive of a repository.
rpc GetArchive(GetArchiveRequest) returns (stream GetArchiveResponse) {
option (op_type) = {
op: ACCESSOR
};
}
- // HasLocalBranches ...
+ // HasLocalBranches returns whether the given repo contains any branches.
rpc HasLocalBranches(HasLocalBranchesRequest) returns (HasLocalBranchesResponse) {
option (op_type) = {
op: ACCESSOR
@@ -122,14 +123,15 @@ service RepositoryService {
};
}
- // WriteRef ...
+ // WriteRef creates or updates a ref in a repository to point to a new value.
rpc WriteRef(WriteRefRequest) returns (WriteRefResponse) {
option (op_type) = {
op: MUTATOR
};
}
- // FindMergeBase ...
+ // FindMergeBase returns the best common ancestor between two or more commits. Consult the man
+ // pages of git-merge-base(1) for more information on how this is calculated.
rpc FindMergeBase(FindMergeBaseRequest) returns (FindMergeBaseResponse) {
option (op_type) = {
op: ACCESSOR
@@ -149,7 +151,8 @@ service RepositoryService {
};
}
- // CreateRepositoryFromURL ...
+ // CreateRepositoryFromURL creates a new repo and seeds it with the contents of an existing Git repo
+ // reachable at the provided URL.
rpc CreateRepositoryFromURL(CreateRepositoryFromURLRequest) returns (CreateRepositoryFromURLResponse) {
option (op_type) = {
op: MUTATOR
@@ -213,42 +216,47 @@ service RepositoryService {
option deprecated = true;
}
- // CalculateChecksum ...
+ // CalculateChecksum returns a checksum of the repository by hashing its references. Refs
+ // outside of well-known namespaces are not considered when computing the checksum.
rpc CalculateChecksum(CalculateChecksumRequest) returns (CalculateChecksumResponse) {
option (op_type) = {
op: ACCESSOR
};
}
- // GetSnapshot ...
+ // GetSnapshot returns a snapshot of the repository. A snapshot comprises all Git references
+ // and objects required to recreate the state of a repository at a point in time.
rpc GetSnapshot(GetSnapshotRequest) returns (stream GetSnapshotResponse) {
option (op_type) = {
op: ACCESSOR
};
}
- // CreateRepositoryFromSnapshot ...
+ // CreateRepositoryFromSnapshot creates a new repository based on a snapshot created with
+ // the GetSnapshot RPC. The snapshot is fetched via HTTP.
rpc CreateRepositoryFromSnapshot(CreateRepositoryFromSnapshotRequest) returns (CreateRepositoryFromSnapshotResponse) {
option (op_type) = {
op: MUTATOR
};
}
- // GetRawChanges ...
+ // GetRawChanges returns metadata in raw format on the changes between two revisions.
rpc GetRawChanges(GetRawChangesRequest) returns (stream GetRawChangesResponse) {
option (op_type) = {
op: ACCESSOR
};
}
- // SearchFilesByContent ...
+ // SearchFilesByContent searches files in the repository using the provided grep pattern.
+ // For each result, the matched line is returned along with the two previous and next lines.
rpc SearchFilesByContent(SearchFilesByContentRequest) returns (stream SearchFilesByContentResponse) {
option (op_type) = {
op: ACCESSOR
};
}
- // SearchFilesByName ...
+ // SearchFilesByName searches files in the repository based on its name and an
+ // optional filter.
rpc SearchFilesByName(SearchFilesByNameRequest) returns (stream SearchFilesByNameResponse) {
option (op_type) = {
op: ACCESSOR
@@ -266,8 +274,8 @@ service RepositoryService {
}
// SetCustomHooks sets the git hooks for a repository. The hooks are sent in a
- // tar archive containing a `custom_hooks` directory. This directory is
- // ultimately extracted to the repository.
+ // tar archive containing a `custom_hooks` directory (i.e. the response from the
+ // GetCustomHooksResponse RPC. This directory will be extracted into the repository.
rpc SetCustomHooks(stream SetCustomHooksRequest) returns (SetCustomHooksResponse) {
option (op_type) = {
op: MUTATOR
@@ -293,7 +301,7 @@ service RepositoryService {
};
}
- // GetObjectDirectorySize ...
+ // GetObjectDirectorySize returns the size in kibibytes of the object directory of a repository.
rpc GetObjectDirectorySize(GetObjectDirectorySizeRequest) returns (GetObjectDirectorySizeResponse) {
option (op_type) = {
op: ACCESSOR
@@ -406,15 +414,15 @@ service RepositoryService {
}
}
-// RepositoryExistsRequest ...
+// RepositoryExistsRequest is a request for the RepositoryExists RPC.
message RepositoryExistsRequest {
- // repository ...
+ // repository is the repo to check. The storage_name and relative_path attributes must be provided.
Repository repository = 1 [(target_repository)=true];
}
-// RepositoryExistsResponse ...
+// RepositoryExistsResponse is a response for the RepositoryExists RPC.
message RepositoryExistsResponse {
- // exists ...
+ // exists indicates whether the repo exists.
bool exists = 1;
}
@@ -541,7 +549,7 @@ message ApplyGitattributesRequest {
message ApplyGitattributesResponse {
}
-// FetchBundleRequest ...
+// FetchBundleRequest is a request for the FetchBundle RPC.
message FetchBundleRequest {
// repository into which the reference shall be fetched.
Repository repository = 1 [(target_repository)=true];
@@ -553,13 +561,14 @@ message FetchBundleRequest {
bool update_head = 3;
}
-// FetchBundleResponse ...
+// FetchBundleResponse is a response for the FetchBundle RPC.
message FetchBundleResponse {
}
-// FetchRemoteRequest ...
+// FetchRemoteRequest is a request for the FetchRemote RPC.
message FetchRemoteRequest {
- // repository ...
+ // repository is the repository to fetch the remote into. The storage_name
+ // and relative_path attributes must be provided.
Repository repository = 1 [(target_repository)=true];
// force determines if references should be force-updated in case they have
// diverged.
@@ -568,9 +577,10 @@ message FetchRemoteRequest {
bool no_tags = 4;
// timeout specifies a timeout for the fetch.
int32 timeout = 5;
- // ssh_key ...
+ // ssh_key is an optional SSH key to use for fetching the remote.
string ssh_key = 6;
- // known_hosts ...
+ // known_hosts is the optional content of an SSH known-hosts file to use
+ // for the SSH session.
string known_hosts = 7;
reserved 8;
// no_prune will the fetch to not prune remote references which do not exist
@@ -587,7 +597,7 @@ message FetchRemoteRequest {
reserved "remote";
}
-// FetchRemoteResponse ...
+// FetchRemoteResponse is a response for the FetchRemote RPC.
message FetchRemoteResponse {
// tags_changed is set based to true if tags were changed or cannot be determined
// and false when no tags were change. It is only calculated when check_tags_changed
@@ -595,9 +605,9 @@ message FetchRemoteResponse {
bool tags_changed = 1;
}
-// CreateRepositoryRequest ...
+// CreateRepositoryRequest is a request for the CreateRepository RPC.
message CreateRepositoryRequest {
- // repository ...
+ // repository represents the repo to create. The storage_name and relative_path attributes must be provided.
Repository repository = 1 [(target_repository)=true];
// default_branch is the branch name to set as the default branch of the newly created
// repository. Note, this will be treated as the branch name and not a
@@ -609,35 +619,37 @@ message CreateRepositoryRequest {
ObjectFormat object_format = 3;
}
-// CreateRepositoryResponse ...
+// CreateRepositoryResponse is a response for the CreateRepository RPC. An empty
+// response denotes a successful request.
message CreateRepositoryResponse {
}
-// GetArchiveRequest ...
+// GetArchiveRequest is a request for the GetArchive RPC.
message GetArchiveRequest {
- // Format ...
+ // Format is the format which the archive should be packaged in.
enum Format {
- // ZIP ...
+ // ZIP
ZIP = 0; // protolint:disable:this ENUM_FIELD_NAMES_PREFIX ENUM_FIELD_NAMES_ZERO_VALUE_END_WITH
- // TAR ...
+ // TAR
TAR = 1; // protolint:disable:this ENUM_FIELD_NAMES_PREFIX
- // TAR_GZ ...
+ // TAR_GZ
TAR_GZ = 2; // protolint:disable:this ENUM_FIELD_NAMES_PREFIX
- // TAR_BZ2 ...
+ // TAR_BZ2
TAR_BZ2 = 3; // protolint:disable:this ENUM_FIELD_NAMES_PREFIX
}
- // repository ...
+ // repository is the repo to archive. The storage_name and relative_path attributes must be provided.
Repository repository = 1 [(target_repository)=true];
- // commit_id ...
+ // commit_id is the commit at which to perform the archive.
string commit_id = 2;
- // prefix ...
+ // prefix is an optional prefix to add to paths in the archive.
string prefix = 3;
- // format ...
+ // format is the archive format to stream in the response.
Format format = 4;
- // path ...
+ // path is the subdirectory of the repo to archive. Provide "." for the entire repo.
bytes path = 5;
- // exclude ...
+ // exclude is a set of paths to exclude from the archive. The paths must exist in the
+ // tree of the provided commit_id.
repeated bytes exclude = 6; // protolint:disable:this REPEATED_FIELD_NAMES_PLURALIZED
// elide_path whether to elide subdirectories. If it is true and `path` refers
// to a subdirectory, that subdirectory will be elided from archive entries.
@@ -646,29 +658,29 @@ message GetArchiveRequest {
// entry will be `README.md`. `elide_path` has no effect if `path` refers to the
// repository root. `elide_path = true` is not supported if `path` refers to a file.
bool elide_path = 7;
- // include_lfs_blobs ...
+ // include_lfs_blobs controls whether Git LFS Objects are included in the archive.
bool include_lfs_blobs = 8;
}
-// GetArchiveResponse ...
+// GetArchiveResponse is a response for the GetArchive RPC.
message GetArchiveResponse {
- // data ...
+ // data contains the archive in the requested format.
bytes data = 1;
}
-// HasLocalBranchesRequest ...
+// HasLocalBranchesRequest is a request for the HasLocalBranches RPC.
message HasLocalBranchesRequest {
- // repository ...
+ // repository is the repo to check. The storage_name and relative_path attributes must be provided.
Repository repository = 1 [(target_repository)=true];
}
-// HasLocalBranchesResponse ...
+// HasLocalBranchesResponse is a response for the HasLocalBranches RPC.
message HasLocalBranchesResponse {
- // value ...
+ // value indicates whether branches exist in the repo.
bool value = 1;
}
-// FetchSourceBranchRequest ...
+// FetchSourceBranchRequest is a request for the FetchSourceBranch RPC.
message FetchSourceBranchRequest {
// repository into which the reference shall be fetched. After a successful
// call, it should contain the target reference which points to the same
@@ -683,7 +695,7 @@ message FetchSourceBranchRequest {
bytes target_ref = 4;
}
-// FetchSourceBranchResponse ...
+// FetchSourceBranchResponse is a response for the FetchSourceBranch RPC.
message FetchSourceBranchResponse {
// result denotes if the source branch was successfully fetched into the target
// repository. It is false if resolving the remote reference or fetching it failed.
@@ -702,33 +714,39 @@ message FsckResponse {
bytes error = 1;
}
-// WriteRefRequest ...
+// WriteRefRequest is a request for the WriteRef RPC.
message WriteRefRequest {
- // repository ...
+ // repository is the repo in which to write a ref. The storage_name and relative_path
+ // attributes must be provided.
Repository repository = 1 [(target_repository)=true];
- // ref ...
+ // ref is the ref to create or update. It should be a fully-resolved value like refs/heads/main.
bytes ref = 2;
- // revision ...
+ // revision is the new value that the ref should point to.
bytes revision = 3;
- // old_revision ...
+ // old_revision is the previous value of the ref, used to prevent race conditions.
+ // If an all-zero object ID is provided, the ref will only be updated if it did not
+ // previously exist.
bytes old_revision = 4;
- // force ...
- bool force = 5;
+ // This was previously a no-op boolean for the user to indicate if the write
+ // should be forced.
+ reserved 5;
+ reserved "force";
// This used to be a boolean indicating whether or not to shell out or use
// the rugged implementation
reserved 6;
}
-// WriteRefResponse ...
+// WriteRefResponse is a response for the WriteRef RPC.
message WriteRefResponse {
// This used to contain an error message. Since we're shelling out
// all exceptions are wrapped in GRPC errors.
reserved 1;
}
-// FindMergeBaseRequest ...
+// FindMergeBaseRequest is a request for the FindMergeBase RPC.
message FindMergeBaseRequest {
- // repository ...
+ // repository is the repo to find the merge base in. The storage_name and
+ // relative_path attributes must be provided.
Repository repository = 1 [(target_repository)=true];
// revisions is the revisions to find the merge base for.
// We use a repeated field because rugged supports finding a base
@@ -737,9 +755,9 @@ message FindMergeBaseRequest {
repeated bytes revisions = 2;
}
-// FindMergeBaseResponse ...
+// FindMergeBaseResponse is a response for the FindMergeBase RPC.
message FindMergeBaseResponse {
- // base ...
+ // base is the commit ID of the best ancestor between the provided revisions.
string base = 1;
}
@@ -763,11 +781,12 @@ message CreateForkRequest {
message CreateForkResponse {
}
-// CreateRepositoryFromURLRequest ...
+// CreateRepositoryFromURLRequest is a request for the CreateRepositoryFromURL RPC.
message CreateRepositoryFromURLRequest {
- // repository ...
+ // repository represents where the repo should be created. The storage_name and
+ // relative_path attributes must be provided.
Repository repository = 1 [(target_repository)=true];
- // url ...
+ // url is the URL of the existing Git repository.
string url = 2;
// http_authorization_header is the HTTP header which can be added to
// the request in order to authenticate against the repository.
@@ -791,23 +810,24 @@ message CreateRepositoryFromURLRequest {
reserved "http_host";
}
-// CreateRepositoryFromURLResponse ...
+// CreateRepositoryFromURLResponse is a response for the CreateRepositoryFromURL RPC.
message CreateRepositoryFromURLResponse {
}
-// CreateBundleRequest ...
+// CreateBundleRequest is a request for the CreateBundle RPC.
message CreateBundleRequest {
- // repository ...
+ // repository is the repository to create a bundle from. The storage_name and
+ // relative_path attributes must be provided.
Repository repository = 1 [(target_repository)=true];
}
-// CreateBundleResponse ...
+// CreateBundleResponse is a response for the CreateBundle RPC.
message CreateBundleResponse {
- // data ...
+ // data contains the content of the created bundle.
bytes data = 1;
}
-// CreateBundleFromRefListRequest ...
+// CreateBundleFromRefListRequest is a request for the CreateBundleFromRefList RPC.
message CreateBundleFromRefListRequest {
// repository is the repository that the bundle is created from.
Repository repository = 1 [(target_repository)=true];
@@ -818,9 +838,9 @@ message CreateBundleFromRefListRequest {
repeated bytes patterns = 2;
}
-// CreateBundleFromRefListResponse ...
+// CreateBundleFromRefListResponse is a response for the CreateBundleFromRefList RPC.
message CreateBundleFromRefListResponse {
- // data ...
+ // data contains the content of the created bundle.
bytes data = 1;
}
@@ -845,11 +865,12 @@ message RestoreCustomHooksRequest {
bytes data = 2;
}
-// SetCustomHooksRequest ...
+// SetCustomHooksRequest is a request for the SetCustomHooks RPC.
message SetCustomHooksRequest {
- // repository ...
+ // repository is the repo to set the custom hooks in. The storage_name and relative_path
+ // attributes must be provided. The repository can be omitted in subsequent requests.
Repository repository = 1 [(target_repository)=true];
- // data ...
+ // data is a tarball containing a `custom_hooks` directory.
bytes data = 2;
}
@@ -857,7 +878,7 @@ message SetCustomHooksRequest {
message RestoreCustomHooksResponse {
}
-// SetCustomHooksResponse ...
+// SetCustomHooksResponse is a response for the SetCustomHooks RPC.
message SetCustomHooksResponse {
}
@@ -867,9 +888,10 @@ message BackupCustomHooksRequest {
Repository repository = 1 [(target_repository)=true];
}
-// GetCustomHooksRequest ...
+// GetCustomHooksRequest is a request for the GetCustomHooks RPC.
message GetCustomHooksRequest {
- // repository ...
+ // repository is the repo to retrieve custom hooks from. The storage_name and relative_path
+ // attributes must be provided.
Repository repository = 1 [(target_repository)=true];
}
@@ -879,9 +901,9 @@ message BackupCustomHooksResponse {
bytes data = 1;
}
-// GetCustomHooksResponse ...
+// GetCustomHooksResponse is a response for the GetCustomHooks RPC.
message GetCustomHooksResponse {
- // data ...
+ // data is the tarball containing the `custom_hooks` directory.
bytes data = 1;
}
@@ -937,37 +959,40 @@ message GetInfoAttributesResponse {
A merge request may have already been submitted, check that on the merge commit, as usually changes in Gitaly are not breaking, compliance becoming mandatory in the following development cycles.