repository·master·Indexed 26 days ago
https://github.com/mutagen-io/mutagenA remote development tool providing high-performance, real-time file synchronization and flexible network forwarding between local systems, SSH-accessible remote locations, and Docker containers.
Mutagen is a remote development tool designed to allow local development tools to work with code in remote environments (such as cloud servers or containers). It provides two primary capabilities:
Supported transport types include:
Mutagen can be built locally for testing and development using a specialized build script. Note that using go get or go install will result in an incomplete installation because Mutagen requires a bundle of cross-compiled agent binaries.
To perform a normalized build that manages cross-compiled builds and agent bundle creation, use the provided build script. By default, running the script performs a slim build (supporting a selection of common platforms). Artifacts are placed in the build directory at the root of the source tree. Artifacts for your current platform are placed in the root of the build directory for easy access.
Mutagen uses Protocol Buffers and requires Go code generation from .proto files. While generated code is checked into the repository, you must regenerate it if .proto files are modified.
To regenerate the code, run go generate ./pkg/... from the root of the Mutagen source tree.
Requirements:
protoc compiler (with support for Protocol Buffers 3) must be available in your PATH.go generate ./pkg/...Mutagen is a CLI tool used for fast file synchronization and network forwarding for remote development. The primary entry point is the mutagen command.
Available command groups include:
sync: For managing file synchronization sessions.forward: For managing network forwarding.project: For managing Mutagen projects.daemon: For managing the Mutagen daemon.version: To check the installed version.legal: To view legal information.generate: To generate configuration or other assets.You can automate tasks during the project pause lifecycle by defining shell commands in your project configuration file. Mutagen will execute these commands in order:
BeforePause: Commands executed before the forwarding and synchronization sessions are paused.AfterPause: Commands executed after the sessions have been successfully paused.If any command in these sequences fails, the pause process will stop and return an error.
You can automate tasks before or after the resumption of project sessions by using the BeforeResume and AfterResume keys in your Mutagen project configuration file. These commands are executed in a shell.
BeforeResume: Commands executed after the project lock is acquired but before sessions are resumed.AfterResume: Commands executed after all sessions have been successfully resumed.To prevent the Mutagen CLI from automatically attempting to start the daemon if it is not already running, set the following environment variable:
MUTAGEN_DISABLE_AUTOSTART=1
The Mutagen build script (scripts/build.go) supports four build types:
local: Builds support for the local system only.slim: The default build type; supports a selection of common platforms used in testing.release: Generates complete release artifacts. Note: Currently, only macOS supports release builds because macOS binaries require cgo support for filesystem monitoring.release-slim: Generates complete release artifacts for a selection of common platforms used in testing.You can view all available options by running the script with the --help flag.
go run scripts/build.go --helpThe Mutagen CLI and client tools connect to a background daemon via an IPC endpoint. You can control the connection behavior using the following mechanisms:
If the daemon is not running, Mutagen can attempt to start it automatically. This behavior can be disabled by:
MUTAGEN_DISABLE_AUTOSTART=1.external.DisableDaemonAutostart flag.If autostart is enabled, the client will attempt to start the daemon and retry the connection up to 10 times with a 100ms interval between attempts.
When connecting, you can optionally enforce that the daemon's version matches the client's version. If enforceVersionMatch is enabled, the client queries the daemon's version and returns an error if there is a mismatch in Major, Minor, Patch, or Tag versions.
connection timed out (is the daemon running?).client/daemon version mismatch (daemon restart recommended).Use NewEndpoint to create a synchronization.Endpoint that acts as a proxy for a remotely hosted endpoint. This function performs a compression handshake, sets up Protocol Buffer encoding/decoding, and sends an initial synchronization request to the remote host.
Parameters:
logger: A *logging.Logger for diagnostics.stream: An io.ReadWriteCloser representing the underlying communication channel.root: The root path for the synchronization.session: The session identifier.version: The synchronization.Version to use.configuration: A *synchronization.Configuration object.alpha: A boolean indicating if alpha features are enabled.Note: If initialization fails, the provided stream is closed. Once successfully established, the endpoint owns the stream and will close it when Shutdown() is called.
func NewEndpoint(
logger *logging.Logger,
stream io.ReadWriteCloser,
root string,
session string,
version synchronization.Version,
configuration *synchronization.Configuration,
alpha bool,
) (synchronization.Endpoint, error)