proto/shared.proto

syntax = "proto3";

package gitaly;

import "google/protobuf/timestamp.proto";
import "lint.proto";

option go_package = "gitlab.com/gitlab-org/gitaly/v16/proto/go/gitalypb";

// ObjectType ...
enum ObjectType {
  // UNKNOWN ...
  UNKNOWN = 0; // protolint:disable:this ENUM_FIELD_NAMES_PREFIX ENUM_FIELD_NAMES_ZERO_VALUE_END_WITH
  // COMMIT ...
  COMMIT = 1; // protolint:disable:this ENUM_FIELD_NAMES_PREFIX
  // BLOB ...
  BLOB = 2; // protolint:disable:this ENUM_FIELD_NAMES_PREFIX
  // TREE ...
  TREE = 3; // protolint:disable:this ENUM_FIELD_NAMES_PREFIX
  // TAG ...
  TAG = 4; // protolint:disable:this ENUM_FIELD_NAMES_PREFIX
}

// ObjectFormat is the object format that a Git repository can use.
enum ObjectFormat {
  // OBJECT_FORMAT_UNSPECIFIED is the default object type when it has not been explicitly requested
  // by the client. Defaults to OBJECT_FORMAT_SHA1.
  OBJECT_FORMAT_UNSPECIFIED = 0;
  // OBJECT_FORMAT_SHA1 is the object format based on the SHA1 hash.
  OBJECT_FORMAT_SHA1 = 1;
  // OBJECT_FORMAT_SHA256 is the object format based on the SHA256 hash. This is experimental.
  OBJECT_FORMAT_SHA256 = 2;
}

// SignatureType ...
enum SignatureType {
  // NONE ...
  NONE = 0; // protolint:disable:this ENUM_FIELD_NAMES_PREFIX ENUM_FIELD_NAMES_ZERO_VALUE_END_WITH
  // PGP ...
  PGP = 1; // protolint:disable:this ENUM_FIELD_NAMES_PREFIX
  // X509 ...
  X509 = 2; // protolint:disable:this ENUM_FIELD_NAMES_PREFIX
  // SSH ...
  SSH = 3; // protolint:disable:this ENUM_FIELD_NAMES_PREFIX
  // maybe add X509+TSA or other combinations at a later step
}

// Repository ...
message Repository {
  // DEPRECATED: https://gitlab.com/gitlab-org/gitaly/issues/151
  reserved 1;
  reserved "path";

  // storage_name ...
  string storage_name = 2;
  // relative_path ...
  string relative_path = 3;
  // git_object_directory sets the GIT_OBJECT_DIRECTORY envvar on git commands to the value of this field.
  // It influences the object storage directory the SHA1 directories are created underneath.
  string git_object_directory = 4;
  // git_alternate_object_directories sets the GIT_ALTERNATE_OBJECT_DIRECTORIES envvar on git commands to
  // the values of this field. It influences the list of Git object directories which can be used to search
  // for Git objects.
  repeated string git_alternate_object_directories = 5;
  // gl_repository is used in callbacks to GitLab so that it knows what repository the event is
  // associated with. May be left empty on RPC's that do not perform callbacks.
  // During project creation, `gl_repository` may not be known.
  string gl_repository = 6;
  reserved 7;
  // gl_project_path is the human-readable GitLab project path (e.g. gitlab-org/gitlab-ce).
  // When hashed storage is use, this associates a project path with its
  // path on disk. The name can change over time (e.g. when a project is
  // renamed). This is primarily used for logging/debugging at the
  // moment.
  string gl_project_path = 8;
}

// CommitTrailer is a single Git trailer (https://git-scm.com/docs/git-interpret-trailers)
// key-value pair.
message CommitTrailer {
  // key is the key of the trailer, such as `Signed-off-by`.
  bytes key = 1;
  // value is the value of the trailer, such as `Alice <alice@gmail.com>`.
  bytes value = 2;
}

// CommitStatInfo includes the number of changed lines and files in the commit.
message CommitStatInfo {
  // additions is the number of line additions in the commit.
  int32 additions = 1;
  // deletions is the number of lines deleted in the commit.
  int32 deletions = 2;
  // changed_files is the number of files changed in the commit.
  int32 changed_files = 3;
}

// GitCommit corresponds to Gitlab::Git::Commit
message GitCommit {
  // id ...
  string id = 1;
  // subject ...
  bytes subject = 2;
  // body ...
  bytes body = 3;
  // author ...
  CommitAuthor author = 4;
  // committer ...
  CommitAuthor committer = 5;
  // parent_ids ...
  repeated string parent_ids = 6;
  // body_size is the size of the commit body. If body exceeds a certain threshold,
  // it will be nullified, but its size will be set in body_size so we can know if
  // a commit had a body in the first place.
  int64 body_size = 7;
  // signature_type ...
  SignatureType signature_type = 8;
  // tree_id is the object ID of the tree. The tree ID will always be filled, even
  // if the tree is empty. In that case the value will be `4b825dc642cb6eb9a060e54bf8d69288fbee4904`.
  // That value is equivalent to `git hash-object -t tree /dev/null`.
  string tree_id = 9;
  // trailers is the list of Git trailers (https://git-scm.com/docs/git-interpret-trailers)
  // found in this commit's message. The number of trailers and their key/value
  // sizes are limited. If a trailer exceeds these size limits, it and any
  // trailers that follow it are not included.
  repeated CommitTrailer trailers = 10;
  // short_stats are the git stats including additions, deletions and changed_files,
  // they are only set when `include_shortstat == true`.
  CommitStatInfo  short_stats = 11;
  // referenced_by contains fully-qualified reference names (e.g refs/heads/main)
  // that point to the commit.
  repeated bytes referenced_by = 12; // protolint:disable:this REPEATED_FIELD_NAMES_PLURALIZED
  // encoding is the encoding of the commit message. This field will only be present if
  // `i18n.commitEncoding` was set to a value other than "UTF-8" at the time
  // this commit was made.
  // See: https://git-scm.com/docs/git-commit#_discussion
  string encoding = 13;
}

// CommitAuthor ...
message CommitAuthor {
  // name ...
  bytes name = 1;
  // email ...
  bytes email = 2;
  // date ...
  google.protobuf.Timestamp date = 3;
  // timezone ...
  bytes timezone = 4;
}

// ExitStatus ...
message ExitStatus {
  // value ...
  int32 value = 1;
}

// Branch corresponds to Gitlab::Git::Branch
message Branch {
  // name ...
  bytes name = 1;
  // target_commit ...
  GitCommit target_commit = 2;
}

// Tag ...
message Tag {
  // name ...
  bytes name = 1;
  // id ...
  string id = 2;
  // target_commit ...
  GitCommit target_commit = 3;
  // message is the message of the tag. If message exceeds a certain
  // threshold, it will be nullified, but its size will be set in
  // message_size so we can know if a tag had a message in the first place.
  bytes message = 4;
  // message_size ...
  int64 message_size = 5;
  // tagger ...
  CommitAuthor tagger = 6;
  // signature_type ...
  SignatureType signature_type = 7;
}

// User ...
message User {
  // gl_id ...
  string gl_id = 1;
  // name ...
  bytes name = 2;
  // email ...
  bytes email = 3;
  // gl_username ...
  string gl_username = 4;
  // timezone is the timezone as configured by the user in the web interface. This
  // timezone may be used when new commits are created via RPC calls.
  string timezone = 5;
}

// ObjectPool ...
message ObjectPool {
  // repository ...
  Repository repository = 1 [(gitaly.repository)=true];
}

// PaginationParameter controls pagination within RPCs.
message PaginationParameter {
  // page_token instructs pagination to start sending results after the provided page
  // token appears. A page token allows for a generic pattern to uniquely
  // identify a result or 'page'. Each paginated RPC may interpret a page
  // token differently.
  string page_token = 1;
  // limit is the maximum number of objects the client will receive. When fully consuming
  // the response the client will receive _at most_ `limit` number of resulting objects.
  // Note that the number of response messages might be much lower, as some response
  // messages already send multiple objects per message.
  // When the limit is smaller than 0, it will be normalized to 2147483647
  // on the server side. When limit is not set, it defaults to 0, and no
  // results are send in the response.
  int32 limit = 2;
}

// PaginationCursor defines the page token clients should use to fetch the next page.
message PaginationCursor {
  // next_cursor is an opaque token provided to the caller to indicate what the caller
  // should present as a page_token to get subsequent results.
  string next_cursor = 1;
}

// GlobalOptions are additional git options as defined at https://git-scm.com/docs/git/#_options.
message GlobalOptions {
  // literal_pathspecs should be set to treat pathspecs literally (i.e. no globbing, no pathspec magic).
  bool literal_pathspecs = 1;
}

// SortDirection defines the sort direction.
enum SortDirection {
  // ASCENDING sorts by the sort key in ascending order.
  ASCENDING = 0; // protolint:disable:this ENUM_FIELD_NAMES_PREFIX ENUM_FIELD_NAMES_ZERO_VALUE_END_WITH
  // DESCENDING sorts by the sort key in descending order.
  DESCENDING = 1; // protolint:disable:this ENUM_FIELD_NAMES_PREFIX
}

// Partition represents storage partition
message Partition {
  // id is the identifier of a partition within the storage
  string id = 1;
}