README
¶
gitrepofs
A Go fs.FS git repository file system to easily access a repository at a specific tag (or other git reference).
The main envisioned use case is for go generate-based updates from upstream
repositories to fetch the latest C definitions without the need to integrate
upstream C libraries.
remoteURL := "https://gohub.org/froozle/baduzle"
latest, latestref, err := version.LatestReleaseTag(context.Background(),
remoteURL, version.SemverMatcher)
gfs, err := NewForRevision(context.Background(), remoteURL, latestref)
contents, err := fs.ReadFile(gfs, "some/useful/file.h")
Other Implementations
-
@hairyhenderson/go-fsimpl includes a git file system implementation (beside others). It uses the neat trick of cloning a repository into a local work tree in memory (instead of on "disk") and then serves from this memory-based file system. This design requires files to be present twice: once in the in-memory cloned repository and another time in the memory-based file system. Actively maintained at the time of this writing, as well as equiped with lots of unit tests.
-
@ear7h/go-git-fs serves directly from an in-memory git repository clone without a work tree. It doesn't come with any unit tests and hasn't been maintained since May 2021. The code does the fs.ValidPath checks but then adds an unnecessary path.Clean because
fs.ValidPathblocks all the things thatpath.Cleanis supposed to sanitize. -
out of competition: @posener/gitfs tackles http.FileSystem instead.
Supported Go Versions
gitrepofs supports versions of Go that are noted by the Go release policy,
that is, major versions N and N-1 (where N is the current major version).
Copyright and License
gitrepofs is Copyright 2023 Harald Albrecht, and licensed under the Apache
License, Version 2.0.
Documentation
¶
Overview ¶
package gitrepofs provides a fs.FS interface onto a remote git repository at a specific tag.
The main envisioned use case is for “go generate”-based updates from upstream repositories to fetch the latest C definitions without the need to integrate upstream C libraries.
remoteURL := "https://gohub.org/froozle/baduzle"
latest, latestref, err := version.LatestReleaseTag(context.Background(),
remoteURL, version.SemverMatcher)
gfs, err := NewForRevision(context.Background(), remoteURL, latestref)
contents, err := fs.ReadFile(gfs, "some/useful/file.h")
The fs.FS Zoo ¶
The number of interfaces and their relationships in fs.FS look like a (small) zoo and it is easy to get lost in what returns what, or extends that, or whatever. So here's our own little fs.FS Zoo map. For whatever reason, there's no cafeteria and no rest rooms (unless counting in runtime.GC).
fs.FS provides access to a hierarchical file system. Additional optional interfaces (discussed next) then offer more functionality.
- fs.FS.Open opens not only files, but also directories, returning an fs.File. However, in order to successfully open directories, either the file system itself must additionally implement the interface fs.ReadDirFS, or the fs.File returned must also implement fs.ReadDirFile.
fs.File provides access to a single file or directory; for directories, the additional interface fs.ReadDirFiles should also be implemented (Golang soundbite). We implement regular and executable file access in the File type and directory access in the Directory type.
- fs.File.Stat returns an fs.FileInfo.
- fs.File.Read reads the file contents; it doesn't return anything for directories.
- fs.File.Close closes the fs.File.
fs.FileInfo describes a file or directory and is returned by fs.File.Stat, but can also be returned from fs.DirEntry.Info. We implement the fs.FileInfo interface in our aptly named FileInfo type.
- Name
- Size
- Mode: file mode bits.
- ModTime
- IsDir
- Sys: underlying data source of nil.
Next on to fs.ReadDirFile: it provides fs.File operations and on top of it reading a directory. We implemented this interface in the Directory type.
- fs.ReadDirFile.ReadDir returns a bunch of fs.DirEntry objects. To complicate things, callers are allowed to read only piecemeal wise.
fs.DirEntry is an entry from a directory. These entries also have fs.FileInfo objects attached to them. We implement the interface in the DirEntry type.
- Name
- IsDir
- Type: file mode bits.
- fs.DirEntry.Info: returns an fs.FileInfo about this directory entry.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func New ¶
New returns a fs.FS for the specified tree of the git repository object, and using the specified modification time.
func NewForRevision ¶
NewForRevision returns a fs.FS git repository file system object that provides read access to the files in the remote repository at the specified tag. The repository gets downloaded into memory only, so there is no need for handling and cleaning up any temporary directories on the file system.
revision can be (as supported by github.com/go-git/go-git/v5/Repository.ResolveRevision):
- HEAD
- branch
- tag
- ...
Types ¶
type DirEntry ¶
type DirEntry struct {
// contains filtered or unexported fields
}
DirEntry represents an entry read from a directory. They are returned by fs.ReadDir and fs.ReadDirFile.ReadDir. DirEntry objects also contain fs.FileInfo objects.
func NewDirEntry ¶
NewDirEntry returns a new DirEntry object for a file or directory entry.
func (*DirEntry) Info ¶
Info returns the FileInfo for the file or subdirectory described by the entry. The returned FileInfo may be from the time of the original directory read or from the time of the call to Info. If the file has been removed or renamed since the directory read, Info may return an error satisfying errors.Is(err, ErrNotExist). If the entry denotes a symbolic link, Info reports the information about the link itself, not the link's target.
func (*DirEntry) Name ¶
Name returns the name of the file (or subdirectory) described by the entry. This name is only the final element of the path (the base name), not the entire path. For example, Name would return "hello.go" not "home/gopher/hello.go".
func (*DirEntry) Type ¶
Type returns the type bits for the entry. The type bits are a subset of the usual fs.FileMode bits, those returned by the fs.FileMode.Type method.
type Directory ¶
type Directory struct {
// contains filtered or unexported fields
}
Directory represents completely unexpectedly a git directory.
func NewDirectory ¶
NewDirectory returns a new Directory object representing a git tree.
type FS ¶
type FS struct {
// contains filtered or unexported fields
}
FS provides a view into a specific git tree.
func (*FS) Open ¶
Open opens the named file or directory. The name must conform to the rules implemented in fs.ValidPath:
- unrooted, slash-separated path elements, like “x/y/z”, but not “/x/y/z”. Double slashes as separators are invlid.
- the root (top-level) directory on its own is named “.”.
- otherwise, neither “.” nor “..' are allowed.
- finally, the empty name “” isn't allowed either.
Please note that fs.ReadDir uses fs.ReadDirFS.ReadDir when available, but otherwise falls back to fs.FS.Open.
When Open returns an error, it is of type *fs.PathError with the Op field set to "open", the Path field set to name, and the Err field describing the problem.
Open rejects attempts to open names that do not satisfy fs.ValidPath(name), returning a [*fs.PathError with Err set to fs.ErrInvalid or fs.ErrNotExist.
type File ¶
type File struct {
// contains filtered or unexported fields
}
File represents a git regular or executable file. It never represents a directory, that is served by Directory instead.
func NewFile ¶
NewFile returns a new File object, given a file information object and the file's contents blob.
type FileInfo ¶
type FileInfo struct {
// contains filtered or unexported fields
}
FileInfo implements fs.FileInfo for both a git (regular/executable) file blob as well as a directory.
According to the “fs.FS Zoo” FileInfo objects are returned from:
- fs.File.Stat
- directory entries: fs.DirEntry.Info
func NewFileInfo ¶
NewFileInfo returns a new FileInfo object, given a git tree entry, file size and modification time stamp.
The size can (and must) be determined beforehand given a tree object and then calling object.Tree.Size with the correct path.
func NewFileInfoFromTree ¶
NewFileInfoFromTree returns a new FileInfo object that represents the specified tree as a directory itself.
func (*FileInfo) Name ¶
Name returns the name of a file (that can actually also happened to be a directory).
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
test
|
|
|
helpers
Package helpers supports unit tests with a few cute little helpers (such as dealing with just the return value of a value+error returning function).
|
Package helpers supports unit tests with a few cute little helpers (such as dealing with just the return value of a value+error returning function). |
|
localremote
Package localremote aids (go-)git-related unit tests by managing temporary git repositories in the file system.
|
Package localremote aids (go-)git-related unit tests by managing temporary git repositories in the file system. |
|
Package version implements finding the latest and greatest tagged version in a remote git repository.
|
Package version implements finding the latest and greatest tagged version in a remote git repository. |