Documentation
¶
Overview ¶
Package sitesync syncs Creght site code between a local directory and the platform: the pull, diff, push, resolve and version list of the creght CLI, as a library. The CLI's own commands run through this package, so the two never drift apart.
A directory synced with this package is an ordinary creght workspace — .creght/state.json, the recorded base under .creght/base/, conflict markers (<<<<<<< local / ======= / >>>>>>> remote) and .creghtignore are exactly what the CLI reads and writes — so the CLI and this package can take turns on the same directory.
The package never starts a process and never touches the CLI's config.json: the caller names the API host and supplies the token.
c, err := sitesync.New(sitesync.Options{
Host: "https://creght.cn",
Token: func(ctx context.Context) (string, error) { return oauth.AccessToken(ctx) },
Log: os.Stderr,
})
site, _ := sitesync.ParseSite("p9ok3myl0ne6/p9ok3mzxgpzm")
res, err := c.Pull(ctx, "./site", site, sitesync.PullOptions{})
diff, err := c.Diff(ctx, "./site", sitesync.DiffOptions{Delete: true})
pushed, err := c.Push(ctx, "./site", sitesync.PushOptions{Delete: true})
Index ¶
- Variables
- func Conflicts(dir string) ([]string, error)
- func IsUnauthorized(err error) bool
- func Resolve(dir string, path string, side Side) (int, error)
- type Client
- func (c *Client) Diff(ctx context.Context, dir string, opts DiffOptions) (DiffResult, error)
- func (c *Client) Host() string
- func (c *Client) Pull(ctx context.Context, dir string, site Site, opts PullOptions) (PullResult, error)
- func (c *Client) Push(ctx context.Context, dir string, opts PushOptions) (PushResult, error)
- func (c *Client) Versions(ctx context.Context, site Site) (PublishState, error)
- type DiffEntry
- type DiffOptions
- type DiffResult
- type FileChange
- type Options
- type PublishState
- type PullOptions
- type PullResult
- type PushOptions
- type PushResult
- type Side
- type Site
- type Snapshot
- type Version
- type Workspace
Constants ¶
This section is empty.
Variables ¶
ErrUnauthorized matches (with errors.Is) an error from a request the platform answered with 401: the token is missing, expired or revoked.
Functions ¶
func Conflicts ¶
Conflicts lists the files of the workspace in dir that still hold conflict markers, as site paths such as /page/Index.tsx (creght resolve --list).
func IsUnauthorized ¶
IsUnauthorized reports whether err came from a 401.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client syncs workspaces against one Creght deployment.
func (*Client) Diff ¶
func (c *Client) Diff(ctx context.Context, dir string, opts DiffOptions) (DiffResult, error)
Diff compares the workspace in dir with the remote site against the recorded base, without changing anything (creght diff --json). A conflict does not make it fail; check DiffResult.HasConflicts.
func (*Client) Pull ¶
func (c *Client) Pull(ctx context.Context, dir string, site Site, opts PullOptions) (PullResult, error)
Pull brings the site into dir: a new directory, or a workspace of the same site, whose local edits are three-way merged with the remote ones against the recorded base (creght pull). With opts.VersionNo it pulls a read-only version snapshot instead.
func (*Client) Push ¶
func (c *Client) Push(ctx context.Context, dir string, opts PushOptions) (PushResult, error)
Push uploads the workspace in dir (creght push). Without Force it refuses when a file changed both locally and remotely since the last pull — pull first to merge — unless SkipConflicts is set.
type DiffEntry ¶
DiffEntry is one file of a DiffResult. Status is one of
local-change push would upload it; Action is file_create, file_update or file_delete conflict changed on both sides (or still holds conflict markers); push refuses remote-only changed only remotely; pull brings it in no-base differs from the remote with no recorded base ignored-remote hidden by .creghtignore but still on the site
type DiffOptions ¶
type DiffOptions struct {
// Delete plans remote deletions for files removed locally (diff --delete).
Delete bool
}
DiffOptions are diff's flags.
type DiffResult ¶
type DiffResult = workspace.DiffResult
DiffResult is the change plan, exactly as creght diff --json prints it.
type FileChange ¶
type FileChange = workspace.FileChange
FileChange is one change made to the remote site. Action is file_create, file_update or file_delete.
type Options ¶
type Options struct {
// Host is the API host of the Creght deployment, e.g. https://creght.cn.
Host string
// Token returns the access token to send. It is called before every
// request, so a caller that refreshes its token can return the fresh one.
// A nil Token sends no token, which only public reads accept.
Token func(ctx context.Context) (string, error)
// Log receives the progress and plan lines the CLI prints (merged files,
// conflicts, "synced N files"). Nil discards them.
Log io.Writer
}
Options configures a Client.
type PublishState ¶
type PublishState = creght.SitePublishState
PublishState is a site's versions and publish targets, exactly as creght version list --json prints it. For a reader of a public-copy project that is not a member, ReadOnly is set and only the versions and the live version are filled.
type PullOptions ¶
type PullOptions struct {
// VersionNo, when set, pulls that site version as a read-only snapshot
// (pull --version_no): the directory is made to match the version
// exactly, deleting everything else except .git and .creght at its root,
// and push, diff and resolve refuse to run there. The directory must be
// new, empty, or already a snapshot.
VersionNo int64
// Force overwrites local files with the remote workspace instead of
// merging (pull --force); overwritten local work is backed up under
// .creght/backup/. Ignored with VersionNo.
Force bool
// SkipAgentsFile leaves out the AGENTS.md a pull writes into a workspace
// that has none. Ignored with VersionNo.
SkipAgentsFile bool
}
PullOptions are pull's flags.
type PullResult ¶
type PullResult struct {
Dir string
Changed int
// Merged are files changed on both sides whose edits merged cleanly.
Merged []string
// Conflicted are files changed on both sides with overlapping edits; they
// now hold conflict markers. Pull still succeeds — the CLI turns a
// non-empty Conflicted into a failing exit — and push refuses until each
// is edited or settled with Resolve.
Conflicted []string
// BackupDir is where overwritten local work was saved, if anything was.
BackupDir string
AgentsFileCreated bool
// Snapshot is set for a VersionNo pull.
Snapshot *Snapshot
}
PullResult reports what Pull did.
type PushOptions ¶
type PushOptions struct {
// Delete deletes remote files removed locally (push --delete).
Delete bool
// Force overwrites the remote site with the local workspace without the
// three-way check (push --force). It uploads every differing file and
// deletes every remote file missing locally whether or not Delete is set;
// remote edits it overwrites are backed up under .creght/backup/.
Force bool
// SkipConflicts pushes everything else when some files conflict, leaving
// those for a later pull (push --skip-conflicts).
SkipConflicts bool
}
PushOptions are push's flags.
type PushResult ¶
type PushResult struct {
Changes []FileChange
// SkippedConflicts are the files SkipConflicts left out.
SkippedConflicts []string
}
PushResult reports what Push changed.
type Site ¶
Site names one site of a project.
type Snapshot ¶
type Snapshot struct {
VersionNo int64
// VersionID and Note are labels from the publish state; zero or empty
// when it could not be read.
VersionID int64
Note string
// Files is how many files the version has; Removed is how many files the
// directory held that the version does not, and were deleted.
Files int
Removed int
}
Snapshot describes a version pulled with PullOptions.VersionNo.
type Workspace ¶
type Workspace struct {
Dir string
Site Site
// APIHost is the deployment the workspace was pulled from; empty for
// workspaces pulled by old CLI versions.
APIHost string
// SnapshotVersionNo is set when the directory holds a read-only version
// snapshot (pulled with PullOptions.VersionNo) rather than a workspace.
SnapshotVersionNo int64
}
Workspace is what .creght/state.json records about a directory.
func OpenWorkspace ¶
OpenWorkspace reads dir's .creght/state.json. dir must be the workspace root.