Help us shape the future of Go! Take the 2026 Go Developer Survey

files

package
v3.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 30, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package files implements MCP tools for GitLab repository file operations.

The package wraps the GitLab Repository files API:

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ActionSpecs 

func ActionSpecs(client *gitlabclient.Client) []toolutil.ActionSpec

ActionSpecs returns canonical specs for repository file actions.

func Delete 

func Delete(ctx context.Context, client *gitlabclient.Client, input DeleteInput) error

Delete deletes a file from a GitLab repository.

func FormatBlameMarkdown 

func FormatBlameMarkdown(out BlameOutput) string

FormatBlameMarkdown renders the blame of a file: one section per range, each naming the commit that last touched it and fencing the lines themselves.

func FormatFileInfoMarkdown 

func FormatFileInfoMarkdown(out FileInfoOutput) string

FormatFileInfoMarkdown renders the commit a file create, update or delete produced as the card of that result.

func FormatMetaDataMarkdown 

func FormatMetaDataMarkdown(out MetaDataOutput) string

FormatMetaDataMarkdown renders a file's metadata as a card, with no body.

func FormatOutputMarkdown 

func FormatOutputMarkdown(f Output) string

FormatOutputMarkdown renders one repository file as a card: its metadata, then its body.

A text file's body is fenced here rather than dropped: the card used to fall through its content-category switch with nothing for a file that is neither an image nor binary, which is every ordinary source file this action is asked for.

func FormatRawBinaryMarkdown 

func FormatRawBinaryMarkdown(out RawOutput) string

FormatRawBinaryMarkdown renders the metadata of a raw binary file, whose content is not viewable as text.

func FormatRawImageMarkdown 

func FormatRawImageMarkdown(out RawOutput) string

FormatRawImageMarkdown renders the metadata of a raw image file; the bytes themselves are attached to the result.

func FormatRawMarkdown 

func FormatRawMarkdown(out RawOutput) string

FormatRawMarkdown renders raw file content as a card whose body is fenced.

Types

type BlameInput 

type BlameInput struct {
	ProjectID  toolutil.StringOrInt `json:"project_id"            jsonschema:"Project ID or URL-encoded path,required"`
	FilePath   string               `json:"file_path"             jsonschema:"Full path of the file in the repository, as written (e.g. src/main.go),required"`
	Ref        string               `json:"ref,omitempty"         jsonschema:"Branch, tag, or commit SHA,required"`
	RangeStart int                  `json:"range_start,omitempty" jsonschema:"Start line number for blame range"`
	RangeEnd   int                  `json:"range_end,omitempty"   jsonschema:"End line number for blame range"`
}

BlameInput defines parameters for retrieving file blame information.

type BlameOutput 

type BlameOutput struct {
	toolutil.HintableOutput
	FilePath string             `json:"file_path"`
	Ranges   []BlameRangeOutput `json:"ranges"`
}

BlameOutput holds blame information for a file.

func Blame 

func Blame(ctx context.Context, client *gitlabclient.Client, input BlameInput) (BlameOutput, error)

Blame retrieves blame information for a file in a GitLab repository.

type BlameRangeCommitOutput 

type BlameRangeCommitOutput struct {
	ID            string `json:"id"`
	Message       string `json:"message"`
	AuthorName    string `json:"author_name"`
	AuthorEmail   string `json:"author_email"`
	AuthoredDate  string `json:"authored_date,omitempty"`
	CommittedDate string `json:"committed_date,omitempty"`
}

BlameRangeCommitOutput represents the commit info for a blame range.

type BlameRangeOutput 

type BlameRangeOutput struct {
	Commit BlameRangeCommitOutput `json:"commit"`
	Lines  []string               `json:"lines"`
}

BlameRangeOutput represents one blame range with commit and lines.

type CreateInput 

type CreateInput struct {
	ProjectID       toolutil.StringOrInt `json:"project_id"              jsonschema:"Project ID or URL-encoded path,required"`
	FilePath        string               `` /* 127-byte string literal not displayed */
	Branch          string               `json:"branch"                  jsonschema:"Branch to create the file on,required"`
	Content         string               `json:"content"                 jsonschema:"File content,required"`
	CommitMessage   string               `json:"commit_message"          jsonschema:"Commit message,required"`
	StartBranch     string               `json:"start_branch,omitempty"  jsonschema:"Branch to start from (creates new branch if different from branch)"`
	Encoding        string               `json:"encoding,omitempty"      jsonschema:"Content encoding: text or base64 (default: text)"`
	AuthorEmail     string               `json:"author_email,omitempty"  jsonschema:"Commit author email"`
	AuthorName      string               `json:"author_name,omitempty"   jsonschema:"Commit author name"`
	ExecuteFilemode *bool                `json:"execute_filemode,omitempty" jsonschema:"Enable execute permission on the file"`
}

CreateInput defines parameters for creating a new file in a repository.

type DeleteInput 

type DeleteInput struct {
	ProjectID     toolutil.StringOrInt `json:"project_id"              jsonschema:"Project ID or URL-encoded path,required"`
	FilePath      string               `json:"file_path"               jsonschema:"Full path of the file to delete, as written (e.g. src/main.go),required"`
	Branch        string               `json:"branch"                  jsonschema:"Branch to delete the file from,required"`
	CommitMessage string               `json:"commit_message"          jsonschema:"Commit message,required"`
	StartBranch   string               `json:"start_branch,omitempty"  jsonschema:"Branch to start from"`
	AuthorEmail   string               `json:"author_email,omitempty"  jsonschema:"Commit author email"`
	AuthorName    string               `json:"author_name,omitempty"   jsonschema:"Commit author name"`
	LastCommitID  string               `json:"last_commit_id,omitempty" jsonschema:"Last known commit ID for optimistic locking"`
}

DeleteInput defines parameters for deleting a file from a repository.

type FileInfoOutput 

type FileInfoOutput struct {
	toolutil.HintableOutput
	FilePath     string `json:"file_path"`
	Branch       string `json:"branch"`
	CommitID     string `json:"commit_id,omitempty"`
	LastCommitID string `json:"last_commit_id,omitempty"`
}

FileInfoOutput represents the result of a file create or update operation.

func Create 

func Create(ctx context.Context, client *gitlabclient.Client, input CreateInput) (FileInfoOutput, error)

Create creates a new file in a GitLab repository.

func Update 

func Update(ctx context.Context, client *gitlabclient.Client, input UpdateInput) (FileInfoOutput, error)

Update updates an existing file in a GitLab repository.

type GetInput 

type GetInput struct {
	ProjectID toolutil.StringOrInt `json:"project_id" jsonschema:"Project ID or URL-encoded path,required"`
	FilePath  string               `json:"file_path"  jsonschema:"Full path of the file in the repository, as written (e.g. src/main.go),required"`
	Ref       string               `json:"ref,omitempty" jsonschema:"Branch name, tag, or commit SHA,required"`
}

GetInput defines parameters for retrieving a file from a repository.

type MetaDataInput 

type MetaDataInput struct {
	ProjectID toolutil.StringOrInt `json:"project_id" jsonschema:"Project ID or URL-encoded path,required"`
	FilePath  string               `json:"file_path"  jsonschema:"Full path of the file in the repository, as written (e.g. src/main.go),required"`
	Ref       string               `json:"ref,omitempty" jsonschema:"Branch, tag, or commit SHA,required"`
}

MetaDataInput defines parameters for retrieving file metadata (no content).

type MetaDataOutput 

type MetaDataOutput struct {
	toolutil.HintableOutput
	FileName        string `json:"file_name"`
	FilePath        string `json:"file_path"`
	Size            int64  `json:"size"`
	Encoding        string `json:"encoding"`
	Content         string `json:"content,omitempty"`
	Ref             string `json:"ref"`
	BlobID          string `json:"blob_id"`
	CommitID        string `json:"commit_id"`
	LastCommitID    string `json:"last_commit_id"`
	ExecuteFilemode bool   `json:"execute_filemode"`
	SHA256          string `json:"content_sha256"`
}

MetaDataOutput holds file metadata. The metadata endpoints use HEAD requests, so Content mirrors gl.File.Content but is normally empty; it is surfaced for 1:1 parity with the GitLab File representation.

func GetMetaData 

func GetMetaData(ctx context.Context, client *gitlabclient.Client, input MetaDataInput) (MetaDataOutput, error)

GetMetaData retrieves file metadata without content from a GitLab repository.

func GetRawFileMetaData 

func GetRawFileMetaData(ctx context.Context, client *gitlabclient.Client, input RawMetaDataInput) (MetaDataOutput, error)

GetRawFileMetaData retrieves file metadata from the raw file endpoint (HEAD request). Returns the same metadata as GetFileMetaData but uses a different API endpoint. Useful for checking file existence efficiently.

type Output 

type Output struct {
	toolutil.HintableOutput
	FileName        string `json:"file_name"`
	FilePath        string `json:"file_path"`
	Size            int64  `json:"size"`
	Encoding        string `json:"encoding"`
	Content         string `json:"content"`
	ContentCategory string `json:"content_category"`
	SHA256          string `json:"content_sha256"`
	Ref             string `json:"ref"`
	BlobID          string `json:"blob_id"`
	CommitID        string `json:"commit_id"`
	LastCommitID    string `json:"last_commit_id"`
	ExecuteFilemode bool   `json:"execute_filemode"`

	// ImageData holds raw image bytes for ImageContent responses (not serialized).
	ImageData []byte `json:"-"`
	// ImageMIMEType holds the MIME type for image files (not serialized).
	ImageMIMEType string `json:"-"`
}

Output represents a file retrieved from a repository.

func Get 

func Get(ctx context.Context, client *gitlabclient.Client, input GetInput) (Output, error)

Get retrieves a single file from a GitLab repository by its path and the ref (branch, tag, or commit SHA) GitLab requires. If the file content is base64-encoded by the API, it is automatically decoded to plain text. Returns an error if the file is not found or decoding fails.

type RawInput 

type RawInput struct {
	ProjectID toolutil.StringOrInt `json:"project_id" jsonschema:"Project ID or URL-encoded path,required"`
	FilePath  string               `json:"file_path"  jsonschema:"Full path of the file in the repository, as written (e.g. src/main.go),required"`
	Ref       string               `json:"ref,omitempty" jsonschema:"Branch, tag, or commit SHA (defaults to default branch)"`
	LFS       *bool                `json:"lfs,omitempty" jsonschema:"Fetch the target of an LFS pointer instead of the pointer file itself"`
}

RawInput defines parameters for retrieving raw file content.

type RawMetaDataInput 

type RawMetaDataInput struct {
	ProjectID toolutil.StringOrInt `json:"project_id" jsonschema:"Project ID or URL-encoded path,required"`
	FilePath  string               `json:"file_path"  jsonschema:"Full path of the file in the repository, as written (e.g. src/main.go),required"`
	Ref       string               `json:"ref,omitempty" jsonschema:"Branch, tag, or commit SHA (defaults to default branch)"`
	LFS       *bool                `json:"lfs,omitempty" jsonschema:"Fetch the target of an LFS pointer instead of the pointer file itself"`
}

RawMetaDataInput defines parameters for retrieving raw file metadata via HEAD request.

type RawOutput 

type RawOutput struct {
	toolutil.HintableOutput
	FilePath        string `json:"file_path"`
	Size            int    `json:"size"`
	Content         string `json:"content"`
	ContentCategory string `json:"content_category"`

	// ImageData holds raw image bytes for ImageContent responses (not serialized).
	ImageData []byte `json:"-"`
	// ImageMIMEType holds the MIME type for image files (not serialized).
	ImageMIMEType string `json:"-"`
}

RawOutput holds the raw content of a file.

func GetRaw 

func GetRaw(ctx context.Context, client *gitlabclient.Client, input RawInput) (RawOutput, error)

GetRaw retrieves the raw content of a file from a GitLab repository.

type UpdateInput 

type UpdateInput struct {
	ProjectID       toolutil.StringOrInt `json:"project_id"              jsonschema:"Project ID or URL-encoded path,required"`
	FilePath        string               `json:"file_path"               jsonschema:"Full path of the file to update, as written (e.g. src/main.go),required"`
	Branch          string               `json:"branch"                  jsonschema:"Branch to update the file on,required"`
	Content         string               `json:"content"                 jsonschema:"New file content,required"`
	CommitMessage   string               `json:"commit_message"          jsonschema:"Commit message,required"`
	StartBranch     string               `json:"start_branch,omitempty"  jsonschema:"Branch to start from"`
	Encoding        string               `json:"encoding,omitempty"      jsonschema:"Content encoding: text or base64 (default: text)"`
	AuthorEmail     string               `json:"author_email,omitempty"  jsonschema:"Commit author email"`
	AuthorName      string               `json:"author_name,omitempty"   jsonschema:"Commit author name"`
	LastCommitID    string               `json:"last_commit_id,omitempty" jsonschema:"Last known commit ID for optimistic locking"`
	ExecuteFilemode *bool                `json:"execute_filemode,omitempty" jsonschema:"Enable execute permission on the file"`
}

UpdateInput defines parameters for updating an existing file in a repository.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.