catfs

Documentation

Index

• Variables
• type Change
• type Commit
• type Config
• type Diff
• type DiffPair
• type ErrNoSuchHash
  • func (eh ErrNoSuchHash) Error() string
• type ExplicitPin
• type FS
  • func NewFilesystem(backend FsBackend, dbPath string, owner string, cfg *Config) (*FS, error)
  • func (fs *FS) Cat(path string) (mio.Stream, error)
  • func (fs *FS) Checkout(rev string, force bool) error
  • func (fs *FS) ClearExplicitPins(prefix, fromRef, toRef string) (int, error)
  • func (fs *FS) Close() error
  • func (fs *FS) Copy(src, dst string) error
  • func (fs *FS) Export(w io.Writer) error
  • func (fs *FS) FilesByContent(contents []h.Hash) (map[string]StatInfo, error)
  • func (fs *FS) Head() (string, error)
  • func (fs *FS) History(path string) ([]Change, error)
  • func (fs *FS) Import(r io.Reader) error
  • func (fs *FS) IsPinned(path string) (bool, bool, error)
  • func (fs *FS) List(root string, maxDepth int) ([]*StatInfo, error)
  • func (fs *FS) ListExplicitPins(prefix, fromRef, toRef string) ([]ExplicitPin, error)
  • func (fs *FS) Log() ([]Commit, error)
  • func (fs *FS) MakeCommit(msg string) error
  • func (fs *FS) MakeDiff(remote *FS, headRevOwn, headRevRemote string) (*Diff, error)
  • func (fs *FS) Mkdir(path string, createParents bool) error
  • func (fs *FS) Move(src, dst string) error
  • func (fs *FS) Open(path string) (*Handle, error)
  • func (fs *FS) Pin(path string) error
  • func (fs *FS) Remove(path string) error
  • func (fs *FS) RemoveTag(name string) error
  • func (fs *FS) Reset(path, rev string) error
  • func (fs *FS) ScheduleGCRun()
  • func (fs *FS) SetExplicitPin(prefix, fromRef, toRef string) (int, error)
  • func (fs *FS) Stage(path string, r io.Reader) error
  • func (fs *FS) Stat(path string) (*StatInfo, error)
  • func (fs *FS) Sync(remote *FS) error
  • func (fs *FS) Tag(rev, name string) error
  • func (fs *FS) Touch(path string) error
  • func (fs *FS) Truncate(path string, size uint64) error
  • func (fs *FS) Unpin(path string) error
• type FsBackend
• type Handle
  • func (hdl *Handle) Close() error
  • func (hdl *Handle) Flush() error
  • func (hdl *Handle) Path() string
  • func (hdl *Handle) Read(buf []byte) (int, error)
  • func (hdl *Handle) Seek(offset int64, whence int) (int64, error)
  • func (hdl *Handle) Truncate(size uint64) error
  • func (hdl *Handle) Write(buf []byte) (int, error)
• type MemFsBackend
  • func NewMemFsBackend() *MemFsBackend
  • func (mb *MemFsBackend) Add(r io.Reader) (h.Hash, error)
  • func (mb *MemFsBackend) Cat(hash h.Hash) (mio.Stream, error)
  • func (mb *MemFsBackend) IsPinned(hash h.Hash) (bool, bool, error)
  • func (mb *MemFsBackend) Pin(hash h.Hash, explicit bool) error
  • func (mb *MemFsBackend) Unpin(hash h.Hash, explicit bool) error
• type StatInfo

Variables

var DefaultConfig = &Config{}

DefaultConfig is a Config with sane default values

var (
	ErrIsClosed = errors.New("File handle is closed")
)

Types

type Change

type Change struct {
	Path    string
	Change  string
	ReferTo string
	Head    *Commit
	Next    *Commit
}

type Commit

type Commit struct {
	Hash h.Hash
	Msg  string
	Tags []string
	Date time.Time
}

Commit gives information about a single commit. TODO: Decide on naming: rev(ision), refname or tag.

type Config

type Config struct {
	IO struct {
		CompressAlgo string
	}

	// Special options for the sync algorithm:
	Sync struct {
		IgnoreRemoved    bool
		ConflictStrategy string
	}
}

Config can be used to control specific bevhaviours of the filesystem implementation. It's designed to be a human readable configuration, that mwill be parsed when instancing the filesystem.

type Diff

type Diff struct {
	Added   []StatInfo
	Removed []StatInfo
	Ignored []StatInfo
	Missing []StatInfo

	Moved    []DiffPair
	Merged   []DiffPair
	Conflict []DiffPair
}

type DiffPair

type DiffPair struct {
	Src StatInfo
	Dst StatInfo
}

type ErrNoSuchHash

type ErrNoSuchHash struct {
	// contains filtered or unexported fields
}

ErrNoSuchHash should be returned whenever the backend is unable to find an object referenced to by this hash.

func (ErrNoSuchHash) Error

func (eh ErrNoSuchHash) Error() string

type ExplicitPin

type ExplicitPin struct {
	Path   string
	Commit string
}

type FS

type FS struct {
	// contains filtered or unexported fields
}

FS (short for Filesystem) is the central API entry for everything related to paths. It exposes a POSIX-like interface where path are mapped to the actual underlying hashes and the associated metadata.

Additionally it supports version control commands like MakeCommit(), Checkout() etc. The API is file-centric, i.e. directories are created on the fly for some operations like Stage(). Empty directories can be created via Mkdir() though.

func NewFilesystem

func NewFilesystem(backend FsBackend, dbPath string, owner string, cfg *Config) (*FS, error)

func (*FS) Cat

func (fs *FS) Cat(path string) (mio.Stream, error)

Cat will open a file read-only and expose it's underlying data as stream. If no such path is known or it was deleted, nil is returned as stream.

func (*FS) Checkout

func (fs *FS) Checkout(rev string, force bool) error

func (*FS) ClearExplicitPins

func (fs *FS) ClearExplicitPins(prefix, fromRef, toRef string) (int, error)

func (*FS) Close

func (fs *FS) Close() error

func (*FS) Copy

func (fs *FS) Copy(src, dst string) error

func (*FS) Export

func (fs *FS) Export(w io.Writer) error

func (*FS) FilesByContent

func (fs *FS) FilesByContent(contents []h.Hash) (map[string]StatInfo, error)

func (*FS) Head

func (fs *FS) Head() (string, error)

func (*FS) History

func (fs *FS) History(path string) ([]Change, error)

History returns all modifications of a node with one entry per commit.

func (*FS) Import

func (fs *FS) Import(r io.Reader) error

func (*FS) IsPinned

func (fs *FS) IsPinned(path string) (bool, bool, error)

IsPinned returns true for files and directories that are pinned. A directory only counts as pinned if all files and directories in it are also pinned.

func (*FS) List

func (fs *FS) List(root string, maxDepth int) ([]*StatInfo, error)

List returns stat info for each node below (and including) root. Nodes deeper than maxDepth will not be shown. If maxDepth is a negative number, all nodes will be shown.

func (*FS) ListExplicitPins

func (fs *FS) ListExplicitPins(prefix, fromRef, toRef string) ([]ExplicitPin, error)

func (*FS) Log

func (fs *FS) Log() ([]Commit, error)

Log returns a list of commits starting with the staging commit until the initial commit. For each commit, metadata is collected.

func (*FS) MakeCommit

func (fs *FS) MakeCommit(msg string) error

MakeCommit bundles all staged changes into one commit described by `msg`. If no changes were made since the last call to MakeCommit() ErrNoConflict is returned.

func (*FS) MakeDiff

func (fs *FS) MakeDiff(remote *FS, headRevOwn, headRevRemote string) (*Diff, error)

func (*FS) Mkdir

func (fs *FS) Mkdir(path string, createParents bool) error

func (*FS) Move

func (fs *FS) Move(src, dst string) error

func (*FS) Open

func (fs *FS) Open(path string) (*Handle, error)

Open returns a file like object that can be used for modifying a file in memory. If you want to have seekable read-only stream, use Cat(), it has less overhead.

func (*FS) Pin

func (fs *FS) Pin(path string) error

TODO: PIN: Make pre fetch configurable.

func (*FS) Remove

func (fs *FS) Remove(path string) error

func (*FS) RemoveTag

func (fs *FS) RemoveTag(name string) error

RemoveTag removes a previously created tag.

func (*FS) Reset

func (fs *FS) Reset(path, rev string) error

func (*FS) ScheduleGCRun

func (fs *FS) ScheduleGCRun()

func (*FS) SetExplicitPin

func (fs *FS) SetExplicitPin(prefix, fromRef, toRef string) (int, error)

func (*FS) Stage

func (fs *FS) Stage(path string, r io.Reader) error

Stage reads all data from `r` and stores as content of the node at `path`. If `path` already exists, it will be updated.

func (*FS) Stat

func (fs *FS) Stat(path string) (*StatInfo, error)

func (*FS) Sync

func (fs *FS) Sync(remote *FS) error

Sync will synchronize the state of two filesystems. If one of filesystems have unstaged changes, they will be committted first. If our filesystem was changed by Sync(), a new merge commit will also be created.

func (*FS) Tag

func (fs *FS) Tag(rev, name string) error

Tag saves a human readable name for the revision pointed to by `rev`. There are three pre-defined tags available:

- HEAD: The last full commit. - CURR: The current commit (== staging commit) - INIT: the initial commit.

The tagname is case-insensitive.

func (*FS) Touch

func (fs *FS) Touch(path string) error

Touch creates an empty file at `path` if it does not exist yet. If it exists, it's mod time is being updated to the current time.

func (*FS) Truncate

func (fs *FS) Truncate(path string, size uint64) error

Truncate cuts of the output of the file at `path` to `size`. `size` should be between 0 and the size of the file, all other values will be ignored.

Note that this is not implemented as an actual IO operation. It is possible to go back to a bigger size until the actual content was changed via Stage().

func (*FS) Unpin

func (fs *FS) Unpin(path string) error

type FsBackend

type FsBackend interface {
	// Cat should find the object referenced to by `hash` and
	// make its data available as mio.Stream.
	Cat(hash h.Hash) (mio.Stream, error)

	// Add should read all data in `r` and return the hash under
	// which it can be accessed on later.
	Add(r io.Reader) (h.Hash, error)

	// Pin gives the object at `hash` a "pin".
	// (i.e. it marks the file to be stored indefinitely in local storage)
	// When pinning an explicit pin with an implicit pin, the explicit pin
	// will stay. Upgrading from implicit to explicit is possible though.
	Pin(hash h.Hash, explicit bool) error

	// Unpin removes a previously added pin.
	// If an object is already unpinned this is a no op.
	Unpin(hash h.Hash, explicit bool) error

	// IsPinned return two boolean values:
	// - If the first value is true, the file is pinned.
	// - If the second value is true, it was explicitly pinned by the user.
	IsPinned(hash h.Hash) (bool, bool, error)
}

FsBackend is the interface that needs to be implemented by the data management layer.

type Handle

type Handle struct {
	// contains filtered or unexported fields
}

func (*Handle) Close

func (hdl *Handle) Close() error

func (*Handle) Flush

func (hdl *Handle) Flush() error

func (*Handle) Path

func (hdl *Handle) Path() string

func (*Handle) Read

func (hdl *Handle) Read(buf []byte) (int, error)

func (*Handle) Seek

func (hdl *Handle) Seek(offset int64, whence int) (int64, error)

func (*Handle) Truncate

func (hdl *Handle) Truncate(size uint64) error

Truncate truncates the file to a specific length.

func (*Handle) Write

func (hdl *Handle) Write(buf []byte) (int, error)

type MemFsBackend

type MemFsBackend struct {
	// contains filtered or unexported fields
}

MemFsBackend is a mock structure that implements FsBackend.

func NewMemFsBackend

func NewMemFsBackend() *MemFsBackend

NewMemFsBackend returns a MemFsBackend (useful for writing tests)

func (*MemFsBackend) Add

func (mb *MemFsBackend) Add(r io.Reader) (h.Hash, error)

Add implements FsBackend.Add by storing the data in memory.

func (*MemFsBackend) Cat

func (mb *MemFsBackend) Cat(hash h.Hash) (mio.Stream, error)

Cat implements FsBackend.Cat by querying memory.

func (*MemFsBackend) IsPinned

func (mb *MemFsBackend) IsPinned(hash h.Hash) (bool, bool, error)

IsPinned implements FsBackend.IsPinned by querying a marker in memory.

func (*MemFsBackend) Pin

func (mb *MemFsBackend) Pin(hash h.Hash, explicit bool) error

Pin implements FsBackend.Pin by storing a marker in memory.

func (*MemFsBackend) Unpin

func (mb *MemFsBackend) Unpin(hash h.Hash, explicit bool) error

Unpin implements FsBackend.Unpin by removing a marker in memory.

type StatInfo

type StatInfo struct {
	Path       string
	Hash       h.Hash
	User       string
	Size       uint64
	Inode      uint64
	IsDir      bool
	Depth      int
	ModTime    time.Time
	IsPinned   bool
	IsExplicit bool
	Content    h.Hash
}

StatInfo describes the metadata of a single node. The concept is comparable to the POSIX stat() call.