diff options
author | Justin Tobler <jtobler@gitlab.com> | 2023-11-01 01:59:20 +0300 |
---|---|---|
committer | Justin Tobler <jtobler@gitlab.com> | 2023-11-16 21:49:57 +0300 |
commit | ee85c8b62f7f3df6bda69ff0a84937fa6c35bf8b (patch) | |
tree | 341e56593ebfab1b314d086f0f461ca5598eb1f1 | |
parent | eeddf4f0bb6496b7d73a4fa4eb6494b663b0568c (diff) |
proto: Add documentation for `RefService`
Some of the RPC definitions and protobuf message types in the
`RefService` lack documentation. Add the missing documentation.
-rw-r--r-- | proto/go/gitalypb/ref.pb.go | 149 | ||||
-rw-r--r-- | proto/go/gitalypb/ref_grpc.pb.go | 62 | ||||
-rw-r--r-- | proto/ref.proto | 186 |
3 files changed, 222 insertions, 175 deletions
diff --git a/proto/go/gitalypb/ref.pb.go b/proto/go/gitalypb/ref.pb.go index faffe2ea4..d2f715bdb 100644 --- a/proto/go/gitalypb/ref.pb.go +++ b/proto/go/gitalypb/ref.pb.go @@ -20,15 +20,16 @@ const ( _ = protoimpl.EnforceVersion(protoimpl.MaxVersion - 20) ) -// SortBy ... +// SortBy defines the allowed field names which references can be sorted by. +// https://git-scm.com/docs/git-for-each-ref#Documentation/git-for-each-ref.txt---sortltkeygt type FindLocalBranchesRequest_SortBy int32 const ( - // NAME ... + // NAME is for the `--sort=refname` option and is the default option. FindLocalBranchesRequest_NAME FindLocalBranchesRequest_SortBy = 0 // protolint:disable:this ENUM_FIELD_NAMES_PREFIX ENUM_FIELD_NAMES_ZERO_VALUE_END_WITH - // UPDATED_ASC ... + // UPDATED_ASC is for the `--sort=committerdate` option. FindLocalBranchesRequest_UPDATED_ASC FindLocalBranchesRequest_SortBy = 1 // protolint:disable:this ENUM_FIELD_NAMES_PREFIX - // UPDATED_DESC ... + // UPDATED_DESC is for the `--sort=-committerdate` option. FindLocalBranchesRequest_UPDATED_DESC FindLocalBranchesRequest_SortBy = 2 // protolint:disable:this ENUM_FIELD_NAMES_PREFIX ) @@ -77,9 +78,9 @@ func (FindLocalBranchesRequest_SortBy) EnumDescriptor() ([]byte, []int) { type FindAllTagsRequest_SortBy_Key int32 const ( - // REFNAME ... + // REFNAME is for the `refname` field and is the default option. FindAllTagsRequest_SortBy_REFNAME FindAllTagsRequest_SortBy_Key = 0 // protolint:disable:this ENUM_FIELD_NAMES_PREFIX ENUM_FIELD_NAMES_ZERO_VALUE_END_WITH - // CREATORDATE ... + // CREATORDATE is for the `creatordate` field. FindAllTagsRequest_SortBy_CREATORDATE FindAllTagsRequest_SortBy_Key = 1 // protolint:disable:this ENUM_FIELD_NAMES_PREFIX // VERSION_REFNAME sorts tags by their semantic versions (https://semver.org/). // tag names that are not semantic versions are sorted lexicographically. They come before @@ -129,17 +130,18 @@ func (FindAllTagsRequest_SortBy_Key) EnumDescriptor() ([]byte, []int) { return file_ref_proto_rawDescGZIP(), []int{9, 0, 0} } -// Key ... +// Key is a key used for sorting. +// https://git-scm.com/docs/git-for-each-ref#Documentation/git-for-each-ref.txt---sortltkeygt type ListRefsRequest_SortBy_Key int32 const ( - // REFNAME ... + // REFNAME is for the `refname` field and is the default option. ListRefsRequest_SortBy_REFNAME ListRefsRequest_SortBy_Key = 0 // protolint:disable:this ENUM_FIELD_NAMES_PREFIX ENUM_FIELD_NAMES_ZERO_VALUE_END_WITH - // CREATORDATE ... + // CREATORDATE is for the `creatordate` field. ListRefsRequest_SortBy_CREATORDATE ListRefsRequest_SortBy_Key = 1 // protolint:disable:this ENUM_FIELD_NAMES_PREFIX - // AUTHORDATE ... + // AUTHORDATE is for the `authordate` field. ListRefsRequest_SortBy_AUTHORDATE ListRefsRequest_SortBy_Key = 2 // protolint:disable:this ENUM_FIELD_NAMES_PREFIX - // COMMITTERDATE ... + // COMMITTERDATE is for the `committerdate` field. ListRefsRequest_SortBy_COMMITTERDATE ListRefsRequest_SortBy_Key = 3 // protolint:disable:this ENUM_FIELD_NAMES_PREFIX ) @@ -186,7 +188,7 @@ func (ListRefsRequest_SortBy_Key) EnumDescriptor() ([]byte, []int) { return file_ref_proto_rawDescGZIP(), []int{31, 0, 0} } -// FindDefaultBranchNameRequest is the request for the FindDefaultBranchName RPC. +// FindDefaultBranchNameRequest is a request for the FindDefaultBranchName RPC. type FindDefaultBranchNameRequest struct { state protoimpl.MessageState sizeCache protoimpl.SizeCache @@ -245,7 +247,7 @@ func (x *FindDefaultBranchNameRequest) GetHeadOnly() bool { return false } -// FindDefaultBranchNameResponse is the response for the FindDefaultBranchName RPC. +// FindDefaultBranchNameResponse is a response for the FindDefaultBranchName RPC. type FindDefaultBranchNameResponse struct { state protoimpl.MessageState sizeCache protoimpl.SizeCache @@ -294,15 +296,15 @@ func (x *FindDefaultBranchNameResponse) GetName() []byte { return nil } -// FindLocalBranchesRequest ... +// FindLocalBranchesRequest is a request for the FindLocalBranches RPC. type FindLocalBranchesRequest struct { state protoimpl.MessageState sizeCache protoimpl.SizeCache unknownFields protoimpl.UnknownFields - // repository ... + // repository is the repository to find the branch in. Repository *Repository `protobuf:"bytes,1,opt,name=repository,proto3" json:"repository,omitempty"` - // sort_by ... + // sort_by sets which field the returned branches are sorted by. SortBy FindLocalBranchesRequest_SortBy `protobuf:"varint,2,opt,name=sort_by,json=sortBy,proto3,enum=gitaly.FindLocalBranchesRequest_SortBy" json:"sort_by,omitempty"` // pagination_params controls paging. Refer to PaginationParameter documentation for // further info. @@ -362,13 +364,13 @@ func (x *FindLocalBranchesRequest) GetPaginationParams() *PaginationParameter { return nil } -// FindLocalBranchesResponse ... +// FindLocalBranchesResponse is a response for the FindLocalBranches RPC. type FindLocalBranchesResponse struct { state protoimpl.MessageState sizeCache protoimpl.SizeCache unknownFields protoimpl.UnknownFields - // local_branches ... + // local_branches is a list of local branches found in the repository. LocalBranches []*Branch `protobuf:"bytes,2,rep,name=local_branches,json=localBranches,proto3" json:"local_branches,omitempty"` } @@ -411,13 +413,13 @@ func (x *FindLocalBranchesResponse) GetLocalBranches() []*Branch { return nil } -// FindAllBranchesRequest ... +// FindAllBranchesRequest is a request for the FindAllBranches RPC. type FindAllBranchesRequest struct { state protoimpl.MessageState sizeCache protoimpl.SizeCache unknownFields protoimpl.UnknownFields - // repository ... + // repository is the repository to find the branch in. Repository *Repository `protobuf:"bytes,1,opt,name=repository,proto3" json:"repository,omitempty"` // merged_only if set, will only return branches that are merged into root ref. MergedOnly bool `protobuf:"varint,2,opt,name=merged_only,json=mergedOnly,proto3" json:"merged_only,omitempty"` @@ -479,13 +481,13 @@ func (x *FindAllBranchesRequest) GetMergedBranches() [][]byte { return nil } -// FindAllBranchesResponse ... +// FindAllBranchesResponse is a response for the FindAllBranches RPC. type FindAllBranchesResponse struct { state protoimpl.MessageState sizeCache protoimpl.SizeCache unknownFields protoimpl.UnknownFields - // branches ... + // branches is a list of branches found in the repository. Branches []*FindAllBranchesResponse_Branch `protobuf:"bytes,1,rep,name=branches,proto3" json:"branches,omitempty"` } @@ -707,13 +709,13 @@ type FindTagError_TagNotFound struct { func (*FindTagError_TagNotFound) isFindTagError_Error() {} -// FindAllTagsRequest ... +// FindAllTagsRequest is a request for the FindAllTags RPC. type FindAllTagsRequest struct { state protoimpl.MessageState sizeCache protoimpl.SizeCache unknownFields protoimpl.UnknownFields - // repository ... + // repository is the repository to look up the tags in. Repository *Repository `protobuf:"bytes,1,opt,name=repository,proto3" json:"repository,omitempty"` // sort_by allows to request tags in particular order. SortBy *FindAllTagsRequest_SortBy `protobuf:"bytes,2,opt,name=sort_by,json=sortBy,proto3" json:"sort_by,omitempty"` @@ -775,13 +777,13 @@ func (x *FindAllTagsRequest) GetPaginationParams() *PaginationParameter { return nil } -// FindAllTagsResponse ... +// FindAllTagsResponse is a response for the FindAllTags RPC. type FindAllTagsResponse struct { state protoimpl.MessageState sizeCache protoimpl.SizeCache unknownFields protoimpl.UnknownFields - // tags ... + // tags is a list of the found tags. Tags []*Tag `protobuf:"bytes,1,rep,name=tags,proto3" json:"tags,omitempty"` } @@ -824,13 +826,13 @@ func (x *FindAllTagsResponse) GetTags() []*Tag { return nil } -// RefExistsRequest ... +// RefExistsRequest is a request for the RefExists RPC. type RefExistsRequest struct { state protoimpl.MessageState sizeCache protoimpl.SizeCache unknownFields protoimpl.UnknownFields - // repository ... + // repository is the repository to check if the reference exists in. Repository *Repository `protobuf:"bytes,1,opt,name=repository,proto3" json:"repository,omitempty"` // ref denotes any ref, e.g. 'refs/heads/master' or 'refs/tags/v1.0.1'. // Must start with 'refs/'. @@ -883,13 +885,13 @@ func (x *RefExistsRequest) GetRef() []byte { return nil } -// RefExistsResponse ... +// RefExistsResponse is a response for the RefExists RPC. type RefExistsResponse struct { state protoimpl.MessageState sizeCache protoimpl.SizeCache unknownFields protoimpl.UnknownFields - // value ... + // value represents if the reference exists. Value bool `protobuf:"varint,1,opt,name=value,proto3" json:"value,omitempty"` } @@ -932,7 +934,7 @@ func (x *RefExistsResponse) GetValue() bool { return false } -// FindBranchRequest ... +// FindBranchRequest is a request for the FindBranch RPC. type FindBranchRequest struct { state protoimpl.MessageState sizeCache protoimpl.SizeCache @@ -991,13 +993,13 @@ func (x *FindBranchRequest) GetName() []byte { return nil } -// FindBranchResponse ... +// FindBranchResponse is a response for the FindBranch RPC. type FindBranchResponse struct { state protoimpl.MessageState sizeCache protoimpl.SizeCache unknownFields protoimpl.UnknownFields - // branch ... + // branch is the found branch. Branch *Branch `protobuf:"bytes,1,opt,name=branch,proto3" json:"branch,omitempty"` } @@ -1241,18 +1243,20 @@ func (*UpdateReferencesError_ReferencesLocked) isUpdateReferencesError_Error() { func (*UpdateReferencesError_ReferenceStateMismatch) isUpdateReferencesError_Error() {} -// DeleteRefsRequest ... +// DeleteRefsRequest is a request for the DeleteRefs RPC. type DeleteRefsRequest struct { state protoimpl.MessageState sizeCache protoimpl.SizeCache unknownFields protoimpl.UnknownFields - // repository ... + // repository is the repository that reference is deleted from. Repository *Repository `protobuf:"bytes,1,opt,name=repository,proto3" json:"repository,omitempty"` - // except_with_prefix ... - // The following two fields are mutually exclusive + // except_with_prefix is the prefix used to determine which references to exclude from being deleted. + // This field can not be set in combination with the refs field. If the refs field is not set, except_with_prefix + // must contain at least one prefix as deleting all references in not allowed. ExceptWithPrefix [][]byte `protobuf:"bytes,2,rep,name=except_with_prefix,json=exceptWithPrefix,proto3" json:"except_with_prefix,omitempty"` // protolint:disable:this REPEATED_FIELD_NAMES_PLURALIZED - // refs ... + // refs is the list of references to be deleted. This field can not be set in combination with except_with_prefix + // and cannot be empty if except_with_prefix is also empty. Refs [][]byte `protobuf:"bytes,3,rep,name=refs,proto3" json:"refs,omitempty"` } @@ -1309,13 +1313,13 @@ func (x *DeleteRefsRequest) GetRefs() [][]byte { return nil } -// DeleteRefsResponse ... +// DeleteRefsResponse is a response for the DeleteRefs RPC. type DeleteRefsResponse struct { state protoimpl.MessageState sizeCache protoimpl.SizeCache unknownFields protoimpl.UnknownFields - // git_error ... + // git_error is a Git error returned by the RPC. Is empty if no error occurs. GitError string `protobuf:"bytes,1,opt,name=git_error,json=gitError,proto3" json:"git_error,omitempty"` } @@ -1444,15 +1448,15 @@ func (*DeleteRefsError_InvalidFormat) isDeleteRefsError_Error() {} func (*DeleteRefsError_ReferencesLocked) isDeleteRefsError_Error() {} -// ListBranchNamesContainingCommitRequest ... +// ListBranchNamesContainingCommitRequest is a request for the ListBranchNamesContainingCommit RPC. type ListBranchNamesContainingCommitRequest struct { state protoimpl.MessageState sizeCache protoimpl.SizeCache unknownFields protoimpl.UnknownFields - // repository ... + // repository is the repository to find branches with the specified commit in. Repository *Repository `protobuf:"bytes,1,opt,name=repository,proto3" json:"repository,omitempty"` - // commit_id ... + // commit_id is the commit ID used to find branches. CommitId string `protobuf:"bytes,2,opt,name=commit_id,json=commitId,proto3" json:"commit_id,omitempty"` // limit the number of tag names to be returned // If the limit is set to zero, all items will be returned @@ -1512,13 +1516,13 @@ func (x *ListBranchNamesContainingCommitRequest) GetLimit() uint32 { return 0 } -// ListBranchNamesContainingCommitResponse ... +// ListBranchNamesContainingCommitResponse is a response for the ListBranchNamesContainingCommit RPC. type ListBranchNamesContainingCommitResponse struct { state protoimpl.MessageState sizeCache protoimpl.SizeCache unknownFields protoimpl.UnknownFields - // branch_names ... + // branch_names contains a list of found branch names. BranchNames [][]byte `protobuf:"bytes,2,rep,name=branch_names,json=branchNames,proto3" json:"branch_names,omitempty"` } @@ -1561,15 +1565,15 @@ func (x *ListBranchNamesContainingCommitResponse) GetBranchNames() [][]byte { return nil } -// ListTagNamesContainingCommitRequest ... +// ListTagNamesContainingCommitRequest is a request for the ListTagNamesContainingCommit RPC. type ListTagNamesContainingCommitRequest struct { state protoimpl.MessageState sizeCache protoimpl.SizeCache unknownFields protoimpl.UnknownFields - // repository ... + // repository is the repository to find tags with the specified commit in. Repository *Repository `protobuf:"bytes,1,opt,name=repository,proto3" json:"repository,omitempty"` - // commit_id ... + // commit_id is the commit ID used to find tags. CommitId string `protobuf:"bytes,2,opt,name=commit_id,json=commitId,proto3" json:"commit_id,omitempty"` // limit the number of tag names to be returned // If the limit is set to zero, all items will be returned @@ -1629,13 +1633,13 @@ func (x *ListTagNamesContainingCommitRequest) GetLimit() uint32 { return 0 } -// ListTagNamesContainingCommitResponse ... +// ListTagNamesContainingCommitResponse is a response for the ListTagNamesContainingCommit RPC. type ListTagNamesContainingCommitResponse struct { state protoimpl.MessageState sizeCache protoimpl.SizeCache unknownFields protoimpl.UnknownFields - // tag_names ... + // tag_names contains a list of tag names found. TagNames [][]byte `protobuf:"bytes,2,rep,name=tag_names,json=tagNames,proto3" json:"tag_names,omitempty"` } @@ -1789,15 +1793,15 @@ func (x *GetTagSignaturesResponse) GetSignatures() []*GetTagSignaturesResponse_T return nil } -// GetTagMessagesRequest ... +// GetTagMessagesRequest is a request for the GetTagMessages RPC. type GetTagMessagesRequest struct { state protoimpl.MessageState sizeCache protoimpl.SizeCache unknownFields protoimpl.UnknownFields - // repository ... + // repository is the repository to get tag messages from. Repository *Repository `protobuf:"bytes,1,opt,name=repository,proto3" json:"repository,omitempty"` - // tag_ids ... + // tag_ids is the list of annotated tag IDs used to get the tag messages. TagIds []string `protobuf:"bytes,3,rep,name=tag_ids,json=tagIds,proto3" json:"tag_ids,omitempty"` } @@ -1847,16 +1851,19 @@ func (x *GetTagMessagesRequest) GetTagIds() []string { return nil } -// GetTagMessagesResponse ... +// GetTagMessagesResponse is a response for the GetTagMessages RPC. Annotated tag messages are +// chunked and streamed back to the client across multiple response messages sequentially. Each +// series of responses for a given tag begins with a response that contains only the associated tag +// ID and is subsequently followed by responses containing the tag message contents. This is +// repeated for each annotated tag included as part of the response stream. type GetTagMessagesResponse struct { state protoimpl.MessageState sizeCache protoimpl.SizeCache unknownFields protoimpl.UnknownFields - // message ... + // message content from the annotated tag message. Message []byte `protobuf:"bytes,2,opt,name=message,proto3" json:"message,omitempty"` - // tag_id ... - // Only present for a new tag message. + // tag_id is the ID of the tag for which the message belongs. TagId string `protobuf:"bytes,3,opt,name=tag_id,json=tagId,proto3" json:"tag_id,omitempty"` } @@ -1906,15 +1913,15 @@ func (x *GetTagMessagesResponse) GetTagId() string { return "" } -// FindAllRemoteBranchesRequest ... +// FindAllRemoteBranchesRequest is a request for the FindAllRemoteBranches RPC. type FindAllRemoteBranchesRequest struct { state protoimpl.MessageState sizeCache protoimpl.SizeCache unknownFields protoimpl.UnknownFields - // repository ... + // repository is the repository to find remote branches from. Repository *Repository `protobuf:"bytes,1,opt,name=repository,proto3" json:"repository,omitempty"` - // remote_name ... + // remote_name is the name of the remote repository. RemoteName string `protobuf:"bytes,2,opt,name=remote_name,json=remoteName,proto3" json:"remote_name,omitempty"` } @@ -1964,13 +1971,13 @@ func (x *FindAllRemoteBranchesRequest) GetRemoteName() string { return "" } -// FindAllRemoteBranchesResponse ... +// FindAllRemoteBranchesResponse is a request for the FindAllRemoteBranches RPC. type FindAllRemoteBranchesResponse struct { state protoimpl.MessageState sizeCache protoimpl.SizeCache unknownFields protoimpl.UnknownFields - // branches ... + // branches contains a list of found remote branches. Branches []*Branch `protobuf:"bytes,1,rep,name=branches,proto3" json:"branches,omitempty"` } @@ -2163,7 +2170,7 @@ func (x *ListRefsResponse) GetReferences() []*ListRefsResponse_Reference { return nil } -// FindRefsByOIDRequest ... +// FindRefsByOIDRequest is a request for the FindRefsByOID RPC. type FindRefsByOIDRequest struct { state protoimpl.MessageState sizeCache protoimpl.SizeCache @@ -2251,7 +2258,7 @@ func (x *FindRefsByOIDRequest) GetLimit() uint32 { return 0 } -// FindRefsByOIDResponse ... +// FindRefsByOIDResponse is a response for the FindRefsByOID RPC. type FindRefsByOIDResponse struct { state protoimpl.MessageState sizeCache protoimpl.SizeCache @@ -2300,15 +2307,15 @@ func (x *FindRefsByOIDResponse) GetRefs() []string { return nil } -// Branch ... +// Branch is a branch found in the repository. type FindAllBranchesResponse_Branch struct { state protoimpl.MessageState sizeCache protoimpl.SizeCache unknownFields protoimpl.UnknownFields - // name ... + // name is the name of the branch. Name []byte `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"` - // target ... + // target is the commit referenced by the branch. Target *GitCommit `protobuf:"bytes,2,opt,name=target,proto3" json:"target,omitempty"` } @@ -2364,9 +2371,9 @@ type FindAllTagsRequest_SortBy struct { sizeCache protoimpl.SizeCache unknownFields protoimpl.UnknownFields - // key ... + // key is the key that tags are sorted by. Key FindAllTagsRequest_SortBy_Key `protobuf:"varint,1,opt,name=key,proto3,enum=gitaly.FindAllTagsRequest_SortBy_Key" json:"key,omitempty"` - // direction ... + // direction is the direction that tags should be sorted in. Direction SortDirection `protobuf:"varint,2,opt,name=direction,proto3,enum=gitaly.SortDirection" json:"direction,omitempty"` } @@ -2559,7 +2566,7 @@ func (x *GetTagSignaturesResponse_TagSignature) GetContent() []byte { return nil } -// SortBy ... +// SortBy defines the field to sort on and its direction. type ListRefsRequest_SortBy struct { state protoimpl.MessageState sizeCache protoimpl.SizeCache @@ -2567,7 +2574,7 @@ type ListRefsRequest_SortBy struct { // key is a key used for sorting. Key ListRefsRequest_SortBy_Key `protobuf:"varint,1,opt,name=key,proto3,enum=gitaly.ListRefsRequest_SortBy_Key" json:"key,omitempty"` - // direction ... + // direction is the direction that tags should be sorted in. Direction SortDirection `protobuf:"varint,2,opt,name=direction,proto3,enum=gitaly.SortDirection" json:"direction,omitempty"` } diff --git a/proto/go/gitalypb/ref_grpc.pb.go b/proto/go/gitalypb/ref_grpc.pb.go index e9d5cfa62..5a7228a14 100644 --- a/proto/go/gitalypb/ref_grpc.pb.go +++ b/proto/go/gitalypb/ref_grpc.pb.go @@ -32,20 +32,23 @@ type RefServiceClient interface { // 5. If a branch exists named refs/heads/master, return refs/heads/master. // 6. Return the first branch (as per default ordering by git). FindDefaultBranchName(ctx context.Context, in *FindDefaultBranchNameRequest, opts ...grpc.CallOption) (*FindDefaultBranchNameResponse, error) - // FindLocalBranches ... - // Return a stream so we can divide the response in chunks of branches + // FindLocalBranches finds all the local branches under `refs/heads/` for the specified repository. + // The response is streamed back to the client to divide the list of branches into chunks. FindLocalBranches(ctx context.Context, in *FindLocalBranchesRequest, opts ...grpc.CallOption) (RefService_FindLocalBranchesClient, error) - // FindAllBranches ... + // FindAllBranches finds all branches under `refs/heads/` and `refs/remotes/` for the specified repository. + // The response is streamed back to the client to divide the list of branches into chunks. FindAllBranches(ctx context.Context, in *FindAllBranchesRequest, opts ...grpc.CallOption) (RefService_FindAllBranchesClient, error) - // FindAllTags returns a stream of tags repository has. + // FindAllTags finds all tags under `refs/tags/` for the specified repository. + // The response is streamed back to the client to divide the list of tags into chunks. FindAllTags(ctx context.Context, in *FindAllTagsRequest, opts ...grpc.CallOption) (RefService_FindAllTagsClient, error) // FindTag looks up a tag by its name and returns it to the caller if it exists. This RPC supports // both lightweight and annotated tags. Note: this RPC returns an `Internal` error if the tag was // not found. FindTag(ctx context.Context, in *FindTagRequest, opts ...grpc.CallOption) (*FindTagResponse, error) - // FindAllRemoteBranches ... + // FindAllRemoteBranches finds all the remote branches under `refs/remotes/` for the specified repository. + // The response is streamed back to the client to divide the list of branches into chunks. FindAllRemoteBranches(ctx context.Context, in *FindAllRemoteBranchesRequest, opts ...grpc.CallOption) (RefService_FindAllRemoteBranchesClient, error) - // RefExists ... + // RefExists checks if the specified reference exists. The reference must be fully qualified. RefExists(ctx context.Context, in *RefExistsRequest, opts ...grpc.CallOption) (*RefExistsResponse, error) // FindBranch finds a branch by its unqualified name (like "master") and // returns the commit it currently points to. @@ -55,18 +58,26 @@ type RefServiceClient interface { // // Updating symbolic references with this RPC is not allowed. UpdateReferences(ctx context.Context, opts ...grpc.CallOption) (RefService_UpdateReferencesClient, error) - // DeleteRefs ... + // DeleteRefs deletes the specified references from its repository. Attempting to delete an + // non-existent reference does not result in an error. It is recommended to instead use the + // UpdateReferences RPC because it can delete references in a raceless manner via the expected old + // object ID. DeleteRefs(ctx context.Context, in *DeleteRefsRequest, opts ...grpc.CallOption) (*DeleteRefsResponse, error) - // ListBranchNamesContainingCommit ... + // ListBranchNamesContainingCommit finds all branches under `refs/heads/` that contain the specified commit. + // The response is streamed back to the client to divide the list of branches into chunks. ListBranchNamesContainingCommit(ctx context.Context, in *ListBranchNamesContainingCommitRequest, opts ...grpc.CallOption) (RefService_ListBranchNamesContainingCommitClient, error) - // ListTagNamesContainingCommit ... + // ListTagNamesContainingCommit finds all tags under `refs/tags/` that contain the specified commit. + // The response is streamed back to the client to divide the list of tags into chunks. ListTagNamesContainingCommit(ctx context.Context, in *ListTagNamesContainingCommitRequest, opts ...grpc.CallOption) (RefService_ListTagNamesContainingCommitClient, error) // GetTagSignatures returns signatures for annotated tags resolved from a set of revisions. Revisions // which don't resolve to an annotated tag are silently discarded. Revisions which cannot be resolved // result in an error. Tags which are annotated but not signed will return a TagSignature response // which has no signature, but its unsigned contents will still be returned. GetTagSignatures(ctx context.Context, in *GetTagSignaturesRequest, opts ...grpc.CallOption) (RefService_GetTagSignaturesClient, error) - // GetTagMessages ... + // GetTagMessages returns tag messages for the annotated tags identified via the given revisions. + // The response is streamed back to the client with a response message containing the tag ID + // always preceding one or more messages containing the tag message contents. This is repeated for + // all tags in the response. GetTagMessages(ctx context.Context, in *GetTagMessagesRequest, opts ...grpc.CallOption) (RefService_GetTagMessagesClient, error) // ListRefs returns a stream of all references in the repository. By default, pseudo-revisions like HEAD // will not be returned by this RPC. Any symbolic references will be resolved to the object ID it is @@ -476,20 +487,23 @@ type RefServiceServer interface { // 5. If a branch exists named refs/heads/master, return refs/heads/master. // 6. Return the first branch (as per default ordering by git). FindDefaultBranchName(context.Context, *FindDefaultBranchNameRequest) (*FindDefaultBranchNameResponse, error) - // FindLocalBranches ... - // Return a stream so we can divide the response in chunks of branches + // FindLocalBranches finds all the local branches under `refs/heads/` for the specified repository. + // The response is streamed back to the client to divide the list of branches into chunks. FindLocalBranches(*FindLocalBranchesRequest, RefService_FindLocalBranchesServer) error - // FindAllBranches ... + // FindAllBranches finds all branches under `refs/heads/` and `refs/remotes/` for the specified repository. + // The response is streamed back to the client to divide the list of branches into chunks. FindAllBranches(*FindAllBranchesRequest, RefService_FindAllBranchesServer) error - // FindAllTags returns a stream of tags repository has. + // FindAllTags finds all tags under `refs/tags/` for the specified repository. + // The response is streamed back to the client to divide the list of tags into chunks. FindAllTags(*FindAllTagsRequest, RefService_FindAllTagsServer) error // FindTag looks up a tag by its name and returns it to the caller if it exists. This RPC supports // both lightweight and annotated tags. Note: this RPC returns an `Internal` error if the tag was // not found. FindTag(context.Context, *FindTagRequest) (*FindTagResponse, error) - // FindAllRemoteBranches ... + // FindAllRemoteBranches finds all the remote branches under `refs/remotes/` for the specified repository. + // The response is streamed back to the client to divide the list of branches into chunks. FindAllRemoteBranches(*FindAllRemoteBranchesRequest, RefService_FindAllRemoteBranchesServer) error - // RefExists ... + // RefExists checks if the specified reference exists. The reference must be fully qualified. RefExists(context.Context, *RefExistsRequest) (*RefExistsResponse, error) // FindBranch finds a branch by its unqualified name (like "master") and // returns the commit it currently points to. @@ -499,18 +513,26 @@ type RefServiceServer interface { // // Updating symbolic references with this RPC is not allowed. UpdateReferences(RefService_UpdateReferencesServer) error - // DeleteRefs ... + // DeleteRefs deletes the specified references from its repository. Attempting to delete an + // non-existent reference does not result in an error. It is recommended to instead use the + // UpdateReferences RPC because it can delete references in a raceless manner via the expected old + // object ID. DeleteRefs(context.Context, *DeleteRefsRequest) (*DeleteRefsResponse, error) - // ListBranchNamesContainingCommit ... + // ListBranchNamesContainingCommit finds all branches under `refs/heads/` that contain the specified commit. + // The response is streamed back to the client to divide the list of branches into chunks. ListBranchNamesContainingCommit(*ListBranchNamesContainingCommitRequest, RefService_ListBranchNamesContainingCommitServer) error - // ListTagNamesContainingCommit ... + // ListTagNamesContainingCommit finds all tags under `refs/tags/` that contain the specified commit. + // The response is streamed back to the client to divide the list of tags into chunks. ListTagNamesContainingCommit(*ListTagNamesContainingCommitRequest, RefService_ListTagNamesContainingCommitServer) error // GetTagSignatures returns signatures for annotated tags resolved from a set of revisions. Revisions // which don't resolve to an annotated tag are silently discarded. Revisions which cannot be resolved // result in an error. Tags which are annotated but not signed will return a TagSignature response // which has no signature, but its unsigned contents will still be returned. GetTagSignatures(*GetTagSignaturesRequest, RefService_GetTagSignaturesServer) error - // GetTagMessages ... + // GetTagMessages returns tag messages for the annotated tags identified via the given revisions. + // The response is streamed back to the client with a response message containing the tag ID + // always preceding one or more messages containing the tag message contents. This is repeated for + // all tags in the response. GetTagMessages(*GetTagMessagesRequest, RefService_GetTagMessagesServer) error // ListRefs returns a stream of all references in the repository. By default, pseudo-revisions like HEAD // will not be returned by this RPC. Any symbolic references will be resolved to the object ID it is diff --git a/proto/ref.proto b/proto/ref.proto index e9316be40..aefcb9a19 100644 --- a/proto/ref.proto +++ b/proto/ref.proto @@ -26,22 +26,24 @@ service RefService { }; } - // FindLocalBranches ... - // Return a stream so we can divide the response in chunks of branches + // FindLocalBranches finds all the local branches under `refs/heads/` for the specified repository. + // The response is streamed back to the client to divide the list of branches into chunks. rpc FindLocalBranches(FindLocalBranchesRequest) returns (stream FindLocalBranchesResponse) { option (op_type) = { op: ACCESSOR }; } - // FindAllBranches ... + // FindAllBranches finds all branches under `refs/heads/` and `refs/remotes/` for the specified repository. + // The response is streamed back to the client to divide the list of branches into chunks. rpc FindAllBranches(FindAllBranchesRequest) returns (stream FindAllBranchesResponse) { option (op_type) = { op: ACCESSOR }; } - // FindAllTags returns a stream of tags repository has. + // FindAllTags finds all tags under `refs/tags/` for the specified repository. + // The response is streamed back to the client to divide the list of tags into chunks. rpc FindAllTags(FindAllTagsRequest) returns (stream FindAllTagsResponse) { option (op_type) = { op: ACCESSOR @@ -57,14 +59,15 @@ service RefService { }; } - // FindAllRemoteBranches ... + // FindAllRemoteBranches finds all the remote branches under `refs/remotes/` for the specified repository. + // The response is streamed back to the client to divide the list of branches into chunks. rpc FindAllRemoteBranches(FindAllRemoteBranchesRequest) returns (stream FindAllRemoteBranchesResponse) { option (op_type) = { op: ACCESSOR }; } - // RefExists ... + // RefExists checks if the specified reference exists. The reference must be fully qualified. rpc RefExists(RefExistsRequest) returns (RefExistsResponse) { option (op_type) = { op: ACCESSOR @@ -89,21 +92,26 @@ service RefService { }; } - // DeleteRefs ... + // DeleteRefs deletes the specified references from its repository. Attempting to delete an + // non-existent reference does not result in an error. It is recommended to instead use the + // UpdateReferences RPC because it can delete references in a raceless manner via the expected old + // object ID. rpc DeleteRefs(DeleteRefsRequest) returns (DeleteRefsResponse) { option (op_type) = { op: MUTATOR }; } - // ListBranchNamesContainingCommit ... + // ListBranchNamesContainingCommit finds all branches under `refs/heads/` that contain the specified commit. + // The response is streamed back to the client to divide the list of branches into chunks. rpc ListBranchNamesContainingCommit(ListBranchNamesContainingCommitRequest) returns (stream ListBranchNamesContainingCommitResponse) { option (op_type) = { op: ACCESSOR }; } - // ListTagNamesContainingCommit ... + // ListTagNamesContainingCommit finds all tags under `refs/tags/` that contain the specified commit. + // The response is streamed back to the client to divide the list of tags into chunks. rpc ListTagNamesContainingCommit(ListTagNamesContainingCommitRequest) returns (stream ListTagNamesContainingCommitResponse) { option (op_type) = { op: ACCESSOR @@ -120,7 +128,10 @@ service RefService { }; } - // GetTagMessages ... + // GetTagMessages returns tag messages for the annotated tags identified via the given revisions. + // The response is streamed back to the client with a response message containing the tag ID + // always preceding one or more messages containing the tag message contents. This is repeated for + // all tags in the response. rpc GetTagMessages(GetTagMessagesRequest) returns (stream GetTagMessagesResponse) { option (op_type) = { op: ACCESSOR @@ -147,7 +158,7 @@ service RefService { } -// FindDefaultBranchNameRequest is the request for the FindDefaultBranchName RPC. +// FindDefaultBranchNameRequest is a request for the FindDefaultBranchName RPC. message FindDefaultBranchNameRequest { // repository is the repository to find the default branch from. Repository repository = 1 [(target_repository)=true]; @@ -156,46 +167,47 @@ message FindDefaultBranchNameRequest { bool head_only = 2; } -// FindDefaultBranchNameResponse is the response for the FindDefaultBranchName RPC. +// FindDefaultBranchNameResponse is a response for the FindDefaultBranchName RPC. message FindDefaultBranchNameResponse { // name is the fully qualified default branch name. bytes name = 1; } -// FindLocalBranchesRequest ... +// FindLocalBranchesRequest is a request for the FindLocalBranches RPC. message FindLocalBranchesRequest { - // SortBy ... + // SortBy defines the allowed field names which references can be sorted by. + // https://git-scm.com/docs/git-for-each-ref#Documentation/git-for-each-ref.txt---sortltkeygt enum SortBy { - // NAME ... + // NAME is for the `--sort=refname` option and is the default option. NAME = 0; // protolint:disable:this ENUM_FIELD_NAMES_PREFIX ENUM_FIELD_NAMES_ZERO_VALUE_END_WITH - // UPDATED_ASC ... + // UPDATED_ASC is for the `--sort=committerdate` option. UPDATED_ASC = 1; // protolint:disable:this ENUM_FIELD_NAMES_PREFIX - // UPDATED_DESC ... + // UPDATED_DESC is for the `--sort=-committerdate` option. UPDATED_DESC = 2; // protolint:disable:this ENUM_FIELD_NAMES_PREFIX } - // repository ... + // repository is the repository to find the branch in. Repository repository = 1 [(target_repository)=true]; - // sort_by ... + // sort_by sets which field the returned branches are sorted by. SortBy sort_by = 2; // pagination_params controls paging. Refer to PaginationParameter documentation for // further info. PaginationParameter pagination_params = 3; } -// FindLocalBranchesResponse ... +// FindLocalBranchesResponse is a response for the FindLocalBranches RPC. message FindLocalBranchesResponse { // The field Branches has been removed in favor of LocalBranches. // Issue: https://gitlab.com/gitlab-org/gitaly/-/issues/1294 reserved "branches"; reserved 1; - // local_branches ... + // local_branches is a list of local branches found in the repository. repeated Branch local_branches = 2; } -// FindAllBranchesRequest ... +// FindAllBranchesRequest is a request for the FindAllBranches RPC. message FindAllBranchesRequest { - // repository ... + // repository is the repository to find the branch in. Repository repository = 1 [(target_repository)=true]; // merged_only if set, will only return branches that are merged into root ref. bool merged_only = 2; @@ -204,17 +216,17 @@ message FindAllBranchesRequest { repeated bytes merged_branches = 3; } -// FindAllBranchesResponse ... +// FindAllBranchesResponse is a response for the FindAllBranches RPC. message FindAllBranchesResponse { - // Branch ... + // Branch is a branch found in the repository. message Branch { - // name ... + // name is the name of the branch. bytes name = 1; - // target ... + // target is the commit referenced by the branch. GitCommit target = 2; } - // branches ... + // branches is a list of branches found in the repository. repeated Branch branches = 1; } @@ -243,15 +255,15 @@ message FindTagError { } } -// FindAllTagsRequest ... +// FindAllTagsRequest is a request for the FindAllTags RPC. message FindAllTagsRequest { // SortBy allows to specify desired order of the elements. message SortBy { // Key is a key used for sorting. enum Key { - // REFNAME ... - REFNAME = 0; // protolint:disable:this ENUM_FIELD_NAMES_PREFIX ENUM_FIELD_NAMES_ZERO_VALUE_END_WITH - // CREATORDATE ... + // REFNAME is for the `refname` field and is the default option. + REFNAME = 0; // protolint:disable:this ENUM_FIELD_NAMES_PREFIX ENUM_FIELD_NAMES_ZERO_VALUE_END_WITH + // CREATORDATE is for the `creatordate` field. CREATORDATE = 1; // protolint:disable:this ENUM_FIELD_NAMES_PREFIX // VERSION_REFNAME sorts tags by their semantic versions (https://semver.org/). // tag names that are not semantic versions are sorted lexicographically. They come before @@ -260,13 +272,13 @@ message FindAllTagsRequest { VERSION_REFNAME = 2; // protolint:disable:this ENUM_FIELD_NAMES_PREFIX } - // key ... - Key key = 1; - // direction ... + // key is the key that tags are sorted by. + Key key = 1; + // direction is the direction that tags should be sorted in. SortDirection direction = 2; } - // repository ... + // repository is the repository to look up the tags in. Repository repository = 1 [(target_repository)=true]; // sort_by allows to request tags in particular order. SortBy sort_by = 2; @@ -275,28 +287,28 @@ message FindAllTagsRequest { PaginationParameter pagination_params = 3; } -// FindAllTagsResponse ... +// FindAllTagsResponse is a response for the FindAllTags RPC. message FindAllTagsResponse { - // tags ... + // tags is a list of the found tags. repeated Tag tags = 1; } -// RefExistsRequest ... +// RefExistsRequest is a request for the RefExists RPC. message RefExistsRequest { - // repository ... + // repository is the repository to check if the reference exists in. Repository repository = 1 [(target_repository)=true]; // ref denotes any ref, e.g. 'refs/heads/master' or 'refs/tags/v1.0.1'. // Must start with 'refs/'. bytes ref = 2; } -// RefExistsResponse ... +// RefExistsResponse is a response for the RefExists RPC. message RefExistsResponse { - // value ... + // value represents if the reference exists. bool value = 1; } -// FindBranchRequest ... +// FindBranchRequest is a request for the FindBranch RPC. message FindBranchRequest { // repository is the repository in which the branch should be looked up. Repository repository = 1 [(target_repository)=true]; @@ -305,9 +317,9 @@ message FindBranchRequest { bytes name = 2; } -// FindBranchResponse ... +// FindBranchResponse is a response for the FindBranch RPC. message FindBranchResponse { - // branch ... + // branch is the found branch. Branch branch = 1; } @@ -358,20 +370,22 @@ message UpdateReferencesError { } } -// DeleteRefsRequest ... +// DeleteRefsRequest is a request for the DeleteRefs RPC. message DeleteRefsRequest{ - // repository ... + // repository is the repository that reference is deleted from. Repository repository = 1 [(target_repository)=true]; - // except_with_prefix ... - // The following two fields are mutually exclusive + // except_with_prefix is the prefix used to determine which references to exclude from being deleted. + // This field can not be set in combination with the refs field. If the refs field is not set, except_with_prefix + // must contain at least one prefix as deleting all references in not allowed. repeated bytes except_with_prefix = 2; // protolint:disable:this REPEATED_FIELD_NAMES_PLURALIZED - // refs ... + // refs is the list of references to be deleted. This field can not be set in combination with except_with_prefix + // and cannot be empty if except_with_prefix is also empty. repeated bytes refs = 3; } -// DeleteRefsResponse ... +// DeleteRefsResponse is a response for the DeleteRefs RPC. message DeleteRefsResponse { - // git_error ... + // git_error is a Git error returned by the RPC. Is empty if no error occurs. string git_error = 1; } @@ -387,39 +401,39 @@ message DeleteRefsError { } } -// ListBranchNamesContainingCommitRequest ... +// ListBranchNamesContainingCommitRequest is a request for the ListBranchNamesContainingCommit RPC. message ListBranchNamesContainingCommitRequest { - // repository ... + // repository is the repository to find branches with the specified commit in. Repository repository = 1 [(target_repository)=true]; - // commit_id ... + // commit_id is the commit ID used to find branches. string commit_id = 2; // limit the number of tag names to be returned // If the limit is set to zero, all items will be returned uint32 limit = 3; } -// ListBranchNamesContainingCommitResponse ... +// ListBranchNamesContainingCommitResponse is a response for the ListBranchNamesContainingCommit RPC. message ListBranchNamesContainingCommitResponse { reserved 1; - // branch_names ... + // branch_names contains a list of found branch names. repeated bytes branch_names = 2; } -// ListTagNamesContainingCommitRequest ... +// ListTagNamesContainingCommitRequest is a request for the ListTagNamesContainingCommit RPC. message ListTagNamesContainingCommitRequest { - // repository ... + // repository is the repository to find tags with the specified commit in. Repository repository = 1 [(target_repository)=true]; - // commit_id ... + // commit_id is the commit ID used to find tags. string commit_id = 2; // limit the number of tag names to be returned // If the limit is set to zero, all items will be returned uint32 limit = 3; } -// ListTagNamesContainingCommitResponse ... +// ListTagNamesContainingCommitResponse is a response for the ListTagNamesContainingCommit RPC. message ListTagNamesContainingCommitResponse { reserved 1; - // tag_names ... + // tag_names contains a list of tag names found. repeated bytes tag_names = 2; } @@ -454,62 +468,66 @@ message GetTagSignaturesResponse { repeated TagSignature signatures = 1; } -// GetTagMessagesRequest ... +// GetTagMessagesRequest is a request for the GetTagMessages RPC. message GetTagMessagesRequest { reserved 2; reserved "tag_names"; - // repository ... + // repository is the repository to get tag messages from. Repository repository = 1 [(target_repository)=true]; - // tag_ids ... + // tag_ids is the list of annotated tag IDs used to get the tag messages. repeated string tag_ids = 3; } -// GetTagMessagesResponse ... +// GetTagMessagesResponse is a response for the GetTagMessages RPC. Annotated tag messages are +// chunked and streamed back to the client across multiple response messages sequentially. Each +// series of responses for a given tag begins with a response that contains only the associated tag +// ID and is subsequently followed by responses containing the tag message contents. This is +// repeated for each annotated tag included as part of the response stream. message GetTagMessagesResponse { reserved 1; reserved "tag_name"; - // message ... + // message content from the annotated tag message. bytes message = 2; - // tag_id ... - // Only present for a new tag message. + // tag_id is the ID of the tag for which the message belongs. string tag_id = 3; } -// FindAllRemoteBranchesRequest ... +// FindAllRemoteBranchesRequest is a request for the FindAllRemoteBranches RPC. message FindAllRemoteBranchesRequest { - // repository ... + // repository is the repository to find remote branches from. Repository repository = 1 [(target_repository)=true]; - // remote_name ... + // remote_name is the name of the remote repository. string remote_name = 2; } -// FindAllRemoteBranchesResponse ... +// FindAllRemoteBranchesResponse is a request for the FindAllRemoteBranches RPC. message FindAllRemoteBranchesResponse { - // branches ... + // branches contains a list of found remote branches. repeated Branch branches = 1; } // ListRefsRequest is a request for the ListRefs RPC. message ListRefsRequest { - // SortBy ... + // SortBy defines the field to sort on and its direction. message SortBy { - // Key ... + // Key is a key used for sorting. + // https://git-scm.com/docs/git-for-each-ref#Documentation/git-for-each-ref.txt---sortltkeygt enum Key { - // REFNAME ... + // REFNAME is for the `refname` field and is the default option. REFNAME = 0; // protolint:disable:this ENUM_FIELD_NAMES_PREFIX ENUM_FIELD_NAMES_ZERO_VALUE_END_WITH - // CREATORDATE ... + // CREATORDATE is for the `creatordate` field. CREATORDATE = 1; // protolint:disable:this ENUM_FIELD_NAMES_PREFIX - // AUTHORDATE ... + // AUTHORDATE is for the `authordate` field. AUTHORDATE = 2; // protolint:disable:this ENUM_FIELD_NAMES_PREFIX - // COMMITTERDATE ... + // COMMITTERDATE is for the `committerdate` field. COMMITTERDATE = 3; // protolint:disable:this ENUM_FIELD_NAMES_PREFIX } // key is a key used for sorting. - Key key = 1; - // direction ... + Key key = 1; + // direction is the direction that tags should be sorted in. SortDirection direction = 2; } @@ -551,7 +569,7 @@ message ListRefsResponse{ repeated Reference references = 1; } -// FindRefsByOIDRequest ... +// FindRefsByOIDRequest is a request for the FindRefsByOID RPC. message FindRefsByOIDRequest { // repository is the repository in which references will be looked for. Repository repository = 1 [(target_repository)=true]; @@ -568,7 +586,7 @@ message FindRefsByOIDRequest { uint32 limit = 5; } -// FindRefsByOIDResponse ... +// FindRefsByOIDResponse is a response for the FindRefsByOID RPC. message FindRefsByOIDResponse { // refs is the set of fully-qualified references which have been found. repeated string refs = 1; |