Documentation ¶
Overview ¶
Package libfastimport implements reading and writing of git fast-import streams.
The documentation here focuses on use of the package itself; it generally assumes a working understanding of the format. Documentation on the format itself can be found in the git-fast-import(1) man-page.
A program can write commands to a backend by wrapping the appropriate io.Writer with a Backend object.
A program can read commands from a frontend by wrapping the appropriate io.Reader with a Frontend object.
This is up-to-date with full syntax supported by git v2.30.0.
Index ¶
- Constants
- func PathEscape(path Path) string
- type Backend
- type Cmd
- type CmdAlias
- type CmdBlob
- type CmdCatBlob
- type CmdCheckpoint
- type CmdComment
- type CmdCommit
- type CmdCommitEnd
- type CmdDone
- type CmdFeature
- type CmdGetMark
- type CmdLs
- type CmdOption
- type CmdProgress
- type CmdReset
- type CmdTag
- type FileCopy
- type FileDelete
- type FileDeleteAll
- type FileModify
- type FileModifyInline
- type FileRename
- type Frontend
- type Ident
- type Mode
- type NoteModify
- type NoteModifyInline
- type Path
- type UnsupportedCommand
- Bugs
Constants ¶
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Backend ¶
type Backend struct {
// contains filtered or unexported fields
}
A Backend is something that consumes a fast-import stream; the Backend object provides methods for writing to it. A program that reads from a Backend would itself be a frontend.
You may think of a "Backend" object as a "Writer" object, though it was not given that name because the GetMark, CatBlob, and Ls methods actually provide 2-way communication.
func NewBackend ¶
NewBackend creates a new Backend object that writes to the given io.WriteCloser.
Optionally, you may also provide an io.Reader that responses to "cat-blob", "get-mark", and "ls" commands can be read from.
Optionally, you may also provide an onErr function that can be used to handle or transform errors when they are encountered.
func (*Backend) CatBlob ¶
func (b *Backend) CatBlob(cmd CmdCatBlob) (sha1 string, data string, err error)
CatBlob gets the SHA-1 and content of the specified blob from the Backend.
It is an error (panic) to call CatBlob if NewBackend did not have a cat-blob reader passed to it.
func (*Backend) Do ¶
Do tells the Backend to do the given command.
It is an error (panic) if Cmd is a type that may only be used in a commit but we aren't in a commit.
func (*Backend) GetMark ¶
func (b *Backend) GetMark(cmd CmdGetMark) (sha1 string, err error)
GetMark gets the SHA-1 referred to by the given mark from the Backend.
It is an error (panic) to call GetMark if NewBackend did not have a cat-blob reader passed to it.
type Cmd ¶
type Cmd interface {
// contains filtered or unexported methods
}
Cmd is a command that may be found in a fast-import stream.
type CmdAlias ¶
CmdAlias requests that the Backend record that a merk refers to a given object without first creating any new object.
type CmdBlob ¶
CmdBlob requests that the Backend write file revision. The blob can be later referred to by the specified Mark (if a Mark > 0 is given), or by pre-calculating the Git SHA-1 (though this is needlessly difficult, just specify a Mark).
type CmdCatBlob ¶
type CmdCatBlob struct {
DataRef string
}
CmdCatBlob requests that the Backend to report back (over the auxiliary cat-blob stream) with the SHA-1 and content of the requested blob. The blob can be specified either by a mark reference (":<idnum>") or by a full 40-byte SHA-1.
type CmdCheckpoint ¶
type CmdCheckpoint struct{}
CmdCheckpoint requests that the Backend flush already-sent data.
type CmdComment ¶
type CmdComment struct {
Comment string
}
CmdComment is a comment line; not a real command.
type CmdCommit ¶
type CmdCommit struct { Ref string Mark int // optional; < 1 for non-use OriginalOID string // optional Author *Ident Committer Ident Encoding string // optional Msg string From string Merge []string }
CmdCommit requests that the Backend creates or updates a branch with a new commit.
This command may be followed by zero or more "File" or "Note" commands to set the content of commit's tree. When reading from a Frontend, that sequence of "File" and "Note" commands will be terminated by a CmdCommitEnd command. It is not nescessary to manually emit a CmdCommitEnd when writing to a Backend.
type CmdCommitEnd ¶
type CmdCommitEnd struct{}
CmdCommitEnd indicates the Frontend will be sending no more "File" or "Note" commands that are "part of" the current CmdCommit.
This is a synthesized command to simplify reading from a Frontend; it is not really a command in the stream. It is thus not nescessary to send a CmdCommitEnd command when writing to a Backend.
type CmdDone ¶
type CmdDone struct{}
CmdDone indicates to the Backend that no more commands will be sent.
type CmdFeature ¶
CmdFeature requests that the Backend immediately aborts with an error if it does not support the specified feature.
type CmdGetMark ¶
type CmdGetMark struct {
Mark int
}
CmdGetMark requests that the Backend to report back (over the auxiliary cat-blob stream) with the SHA-1 corresponding to the given Mark.
type CmdLs ¶
CmdLs requests that the Backend to report back (over the auxiliary cat-blob stream) with information about the object at a path in the specified commit. If inside of a commit, specifying the commit is optional, and the ongoing commit is used. The commit can be specified either by a mark reference (":<idnum>") or by a full 40-byte SHA-1.
type CmdOption ¶
type CmdOption struct {
Option string
}
CmdOption requests that the Backend changes its settings.
type CmdProgress ¶
type CmdProgress struct {
Str string
}
CmdProgress requests that the Backend print the given string to its standard output channel.
type CmdReset ¶
CmdReset requests that the Backend creates (or recreates) the named ref (usually a branch), optionally starting from a specific revision.
type CmdTag ¶
type CmdTag struct { RefName string Mark int // optional; < 1 for non-use CommitIsh string OriginalOID string // optional Tagger Ident Data string }
CmdTag requests that the Backend creates an *annotated* tag referencing a specific commit.
Hint: Use CmdReset to create a *lightweight* tag.
type FileCopy ¶
FileCopy appears after a CmdCommit (and before a CmdCommitEnd), and causes the CmdCommit to recursively copy an existing file or subdirectory to a different location.
type FileDelete ¶
type FileDelete struct {
Path Path
}
FileDelete appears after a CmdCommit (and before a CmdCommitEnd), and causes the CmdCommit to recursively remove a file or directory.
type FileDeleteAll ¶
type FileDeleteAll struct{}
FileDeleteAll appears after a CmdCommit (and before a CmdCommitEnd), and removes all files and directories from the CmdCommit.
type FileModify ¶
FileModify appears after a CmdCommit (and before a CmdCommitEnd), and causes the CmdCommit to add a new file or change the content of an existing file. The content of the file is specified by giving either a mark reference (":<idnum>") or by a full 40-byte SHA-1.
To specify the full content of the file inline, use FileModifyInline instead.
type FileModifyInline ¶
FileModifyInline appears after a CmdCommit (and before a CmdCommitEnd), and causes the CmdCommit to add a new file or change the content of an existing file. The full content of the file are specified directly
To instead specify the content with a mark reference (":<idnum>") or with a full 40-byte SHA-1, use FileModify instead.
type FileRename ¶
FileRename appears after a CmdCommit (and before a CmdCommitEnd), and causes the CmdCommit to rename an existing file or subdirectory to a different location.
type Frontend ¶
type Frontend struct {
// contains filtered or unexported fields
}
A Frontend is something that produces a fast-import stream; the Frontend object provides methods for reading from it. A program that writes to a Frontend would itself be a backend.
You may think of a "Frontend" object as a "Reader" object, though it was not given that name because the RespondGetMark, RespondCatBlob, and RespondLs methods actually write information; it isn't a read-only object.
The parser is a bit more forgiving than git's own parser. It allows extra newlines anywhere it allows comments, whereas git's own parser is quite strict about newlines. It allows 'cat-blob' and 'get-mark' commands anywhere it allows comments, which git used to allow, but was made stricter in git v2.22.0.
func NewFrontend ¶
NewFrontend creates a new Frontend object that reads from the given io.Reader.
Optionally, you may also provide an io.Writer that responses to "cat-blob", "get-mark", and "ls" commands can be written to.
Optionally, you may also provide an onErr function that can bue used to handle or transform errors when they are encountered.
func (*Frontend) ReadCmd ¶
ReadCmd reads a command from the Frontend.
func (*Frontend) RespondCatBlob ¶
RespondCatBlob sends to the Frontend a response to a "cat-blob" command.
It is an error (panic) to call RespondCatBlob if NewFrontend did not have a cat-blob writer passed to it.
func (*Frontend) RespondGetMark ¶
RespondGetMark sends to the Frontend a response to a "get-mark" command.
It is an error (panic) to call RespondGetMark if NewFrontend did not have a cat-blob writer passed to it.
type Ident ¶
Ident is a tuple of a commiter's (or author's) name, email, and a timestamp with timezone.
BUG(lukeshu): Ident (and ParseIdent) only supports the "raw"/"raw-permissive" date format (not "rfc2822" or "now")
func ParseIdent ¶
ParseIdent parses a string containing an Ident.
The format of this string is
<name> SP LT <email> GT SP <time> SP <offutc>
Where <name> may contain a space, but not "<" or ">"; <time> is an integer number of seconds since the UNIX epoch (UTC); <offutc> is positive or negative 4-digit offset from UTC (for example, EST would be "-0500").
type NoteModify ¶
NoteModify appears after a CmdCommit (and before a CmdCommitEnd), and causes the CmdCommit to add a new note describing CommitIsh or change the content of an existing note describing CommitIsh. The content of the note is specified by giving either a mark reference (":<idnum>") or by a full 40-byte SHA-1.
To specify the full content of the note inline, use NoteModifyInline instead.
type NoteModifyInline ¶
NoteModifyInline appears after a CmdCommit (and before a CmdCommitEnd), and causes the CmdCommit to add a new note describing CommitIsh or change the content of an existing note describing CommitIsh. The full content of the note is specified directly.
To instead specify the content with a mark reference (":<idnum>") or with a full 40-byte SHA-1, use NoteModify instead.
type UnsupportedCommand ¶
type UnsupportedCommand string
func (UnsupportedCommand) Error ¶
func (e UnsupportedCommand) Error() string
Notes ¶
Bugs ¶
TODO: commit C not implemented
TODO: commit R not implemented
Ident (and ParseIdent) only supports the "raw"/"raw-permissive" date format (not "rfc2822" or "now")