Mutagen

https://mutagen.io/documentation
Admin
Mutagen is a development utility that provides high-performance file synchronization and network...
Tokens:27,546
Snippets:241
Trust Score:8.1
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Project setup and teardown hooks

Source: https://mutagen.io/documentation/orchestration/projects

Example of project-level hooks that run commands in the system shell before and after session creation and termination. The beforeCreate hook starts infrastructure with docker-compose, and afterTerminate tears it down.

```yaml
beforeCreate:
  - docker-compose up --build --detach

afterTerminate:
  - docker-compose down --rmi=all --volumes

```

--------------------------------

### Start a Mutagen project

Source: https://mutagen.io/documentation/orchestration/projects

Initializes and starts all sessions defined in the project file within the current directory.

```bash
# Start a Mutagen project.
mutagen project start
```

--------------------------------

### Example SSH synchronization URLs

Source: https://mutagen.io/documentation/transports/ssh

Example SSH synchronization URLs. They illustrate absolute paths, custom SSH ports, home-directory-relative paths, and user-specific home-directory paths.

```text
example.org:/var/www
```

```text
example.org:23:relative/path
```

```text
hostalias:~/path/in/home/directory
```

```text
george@example.org:~otheruser/path/in/their/home/directory
```

--------------------------------

### Install Mutagen beta channel with Homebrew

Source: https://mutagen.io/documentation/introduction/installation

Installs the beta release channel via Homebrew. Beta releases are fairly stable and can be thought of as release candidates, but they are not officially supported.

```bash
# Subscribe to the beta release channel
brew install mutagen-io/mutagen/mutagen-beta

```

--------------------------------

### Install Mutagen edge channel with Homebrew

Source: https://mutagen.io/documentation/introduction/installation

Installs the edge release channel via Homebrew. Edge releases are unstable nightly/alpha builds and are not recommended for any user. Features may appear and disappear.

```bash
# Subscribe to the edge release channel (NOT RECOMMENDED!)
brew install mutagen-io/mutagen/mutagen-edge

```

--------------------------------

### Install Mutagen with Homebrew (stable channel)

Source: https://mutagen.io/documentation/introduction/installation

Installs Mutagen via Homebrew on macOS and Linux. This is the stable release channel.

```bash
# Subscribe to the stable release channel
brew install mutagen-io/mutagen/mutagen

```

--------------------------------

### Show Mutagen CLI help with mutagen --help

Source: https://mutagen.io/documentation/introduction/getting-started

Use the mutagen command with the --help flag to display general help, or specify a command to get help for that specific command. This is the built-in help information for the Mutagen CLI.

```bash
# Show general help.
mutagen --help
# Show help for a specific command.
mutagen <command> --help

```

--------------------------------

### Restart the Mutagen daemon after upgrading

Source: https://mutagen.io/documentation/introduction/daemon

Stop and start the daemon to apply upgrades. If you forget, Mutagen prints a warning on the next session management command.

```bash
$ mutagen daemon stop
$ mutagen daemon start

```

--------------------------------

### Configure default permissions in ~/.mutagen.yml

Source: https://mutagen.io/documentation/synchronization/permissions

Use this YAML configuration in ~/.mutagen.yml to set default file and directory permission modes for sync sessions. The modes are specified in octal format with an optional 0 prefix, and the example uses 0XXX as a placeholder.

```yaml
sync:
  defaults:
    permissions:
      defaultFileMode: 0XXX
      defaultDirectoryMode: 0XXX

```

--------------------------------

### Define x-mutagen sessions in Compose YAML

Source: https://mutagen.io/documentation/orchestration/compose

Defines a Compose project with an x-mutagen field that creates a synchronization session (code) and two forwarding sessions (database and web). The sync session uses a volume URL for the beta endpoint, and forwarding sessions use network URLs to expose services. This example manually creates networks and uses a separate volume for code.

```yaml
# Define networks
networks:
  frontend:
  backend:

 # Define volumes
volumes:
  code:

# Define services
services:
  database:
    ...
    networks:
      - backend
  web:
    ...
    volumes:
      - code:/code
    networks:
      - frontend
      - backend
    ...

# Define synchronization and forwarding sessions
x-mutagen:
  sync:
    defaults:
      ignore:
        vcs: true
    code:
      alpha: "."
      beta: "volume://code"
  forward:
    database:
      source: "tcp:localhost:5432"
      destination: "network://backend:tcp:database:5432"
    web:
      source: "tcp::8080"
      destination: "network://frontend:tcp:web:8080"

```

--------------------------------

### Show help for a mutagen sync command

Source: https://mutagen.io/documentation/synchronization

Use this command to display help for any synchronization session management command, such as create, list, monitor, flush, pause, resume, or terminate. The help output explains the command's flags and behavior.

```bash
# Show help about a particular synchronization session management command.
mutagen sync <command> --help

```

--------------------------------

### Set MUTAGEN_DOCKER_PATH to Chocolatey Docker CLI tools directory

Source: https://mutagen.io/documentation/transports/docker

Use this environment variable setting to point Mutagen to the unshimmed Docker CLI executables installed via Chocolatey, avoiding the shim breakage of standard input/output streaming. Adjust the path if your Chocolatey installation differs.

```plaintext
MUTAGEN_DOCKER_PATH=C:\ProgramData\chocolatey\lib\docker-cli\tools

```

--------------------------------

### Global configuration file format (~/.mutagen.yml)

Source: https://mutagen.io/documentation/introduction/configuration

Shows the complete YAML format for Mutagen's global configuration file, which is stored at ~/.mutagen.yml. All parameters are optional and the '...' placeholders represent values documented in their respective sections.

```yaml
sync:
  defaults:
    mode: ...
    maxEntryCount: ...
    maxStagingFileSize: ...
    probeMode: ...
    scanMode: ...
    stageMode: ...
    symlink:
      mode: ...
    watch:
      mode: ...
      pollingInterval: ...
    ignore:
      paths:
        - ...
        - ...
      vcs: ...
    permissions:
      defaultFileMode: ...
      defaultDirectoryMode: ...
      defaultOwner: ...
      defaultGroup: ...

forward:
  defaults:
    socket:
      overwriteMode: ...
      owner: ...
      group: ...
      permissionMode: ...

```

--------------------------------

### Set MUTAGEN_DOCKER_PATH using %ChocolateyInstall% variable

Source: https://mutagen.io/documentation/transports/docker

Alternative setting for the MUTAGEN_DOCKER_PATH environment variable that uses the %ChocolateyInstall% variable to locate the Docker CLI tools directory, which may be more portable across Chocolatey installations.

```plaintext
MUTAGEN_DOCKER_PATH=%ChocolateyInstall%\lib\docker-cli\tools

```

--------------------------------

### List project sessions

Source: https://mutagen.io/documentation/orchestration/projects

Displays the status of all sessions associated with the project, including any conflicts.

```bash
# List the status of project sessions.
mutagen project list
```

--------------------------------

### Create a synchronization session with mutagen sync create

Source: https://mutagen.io/documentation/introduction/getting-started

Creates a synchronization session named 'web-app-code' between a local path and an SSH-accessible endpoint. The command uses OpenSSH settings, keys, and aliases automatically. Prompts for confirmation or authentication if required.

```bash
# Create a synchronization session named "web-app-code" between the local path
# ~/project and an SSH-accessible endpoint.
mutagen sync create --name=web-app-code ~/project user@example.org:~/project

```

--------------------------------

### Show help for a forwarding command

Source: https://mutagen.io/documentation/forwarding

Shows help for a particular forwarding session management command.

```bash
mutagen forward <command> --help
```

--------------------------------

### Configure default symbolic link mode in ~/.mutagen.yml

Source: https://mutagen.io/documentation/synchronization/symbolic-links

Sets the default symbolic link synchronization mode for all sessions via the sync.defaults.symlink.mode key in ~/.mutagen.yml. Replace <mode> with ignore, portable, or posix-raw.

```yaml
sync:
  defaults:
    symlink:
      mode: "<mode>"

```

--------------------------------

### SSH synchronization endpoint URL syntax

Source: https://mutagen.io/documentation/transports/ssh

SCP-like URL syntax for specifying SSH synchronization endpoints to the `mutagen sync create` command. The `<user>` and `<port>` components are optional and passed to OpenSSH to override defaults; `<host>` and `<path>` are required and must not be empty.

```text
[<user>@]<host>[:<port>]:<path>

```

--------------------------------

### Create a forwarding session with mutagen forward create

Source: https://mutagen.io/documentation/introduction/getting-started

Creates a forwarding session named 'web-app' between port 8080 on localhost and port 1313 inside a Docker container. The command shells out to the docker command, respecting DOCKER_HOST and other settings. Prompts for confirmation or authentication if required.

```bash
# Create a forwarding session named "web-app" between port 8080 on localhost and
# port 1313 inside a Docker container.
mutagen forward create --name=web-app tcp:localhost:8080 docker://devcontainer:tcp:localhost:1313

```

--------------------------------

### Run a custom project command

Source: https://mutagen.io/documentation/orchestration/projects

Executes a command defined in the commands section of the mutagen.yml file.

```bash
# Run a Mutagen project command.
mutagen project run <command-name>
```

--------------------------------

### Create forwarding session with non-matching ports

Source: https://mutagen.io/documentation/forwarding/tcp-sockets

Creates a forwarding session from a local TCP port to a container's port, demonstrating that source and target ports need not match. The source endpoint is subject to privileged port restrictions, while the target is not.

```bash
mutagen forward create tcp:localhost:8080 docker://web_container:tcp:localhost:80

```

--------------------------------

### Resume project sessions

Source: https://mutagen.io/documentation/orchestration/projects

Resumes or reconnects all synchronization and forwarding sessions associated with the project.

```bash
# Resume project synchronization and forwarding sessions.
mutagen project resume
```

--------------------------------

### Configure default sync mode in ~/.mutagen.yml

Source: https://mutagen.io/documentation/synchronization

Sets the default synchronization mode for all sessions created without an explicit mode. Place in ~/.mutagen.yml. Replace <mode> with one of two-way-safe, two-way-resolved, one-way-safe, or one-way-replica.

```yaml
sync:
  defaults:
    mode: "<mode>"

```

--------------------------------

### Default VCS ignore configuration in ~/.mutagen.yml

Source: https://mutagen.io/documentation/synchronization/ignores

Include this configuration in `~/.mutagen.yml` to ignore VCS directories by default. This setting can be overridden per-session with the `--no-ignore-vcs` flag.

```yaml
sync:
  defaults:
    ignore:
      vcs: true

```

--------------------------------

### List synchronization sessions with mutagen sync list

Source: https://mutagen.io/documentation/introduction/getting-started

Shows the current status of synchronization sessions. If no session or label selectors are specified, prints all sessions. Output includes conflicts or problems in propagation of changes.

```bash
$ mutagen sync list
Name: web-app-code
Identifier: sync_rJA9OdPDEtIVcqwhOMlBw2BvMgpctZXUsEr4Jl3kUd7
Labels: None
Alpha:
    URL: /home/user/project
    Connection state: Connected
Beta:
    URL: user@example.org:~/project
    Connection state: Connected
Status: Watching for changes

```

--------------------------------

### List forwarding sessions with mutagen forward list

Source: https://mutagen.io/documentation/introduction/getting-started

Shows the current status of forwarding sessions. If no session or label selectors are specified, prints all sessions.

```bash
$ mutagen forward list
Name: web-app
Identifier: fwrd_6mkwS3yuAZyD1VmDtUvCgn3pwqMQf28V4EbxLLvm8OI
Labels: None
Source:
    URL: tcp:localhost:8080
    Connection state: Connected
Destination:
    URL: docker://devcontainer:tcp:localhost:1313
    Connection state: Connected
Status: Forwarding connections

```

--------------------------------

### Configure default stageMode in ~/.mutagen.yml

Source: https://mutagen.io/documentation/synchronization/staging

Sets a default staging mode for all synchronization sessions via the stageMode key in the sync defaults section of ~/.mutagen.yml. Replace <mode> with one of mutagen, neighboring, or internal.

```yaml
sync:
  defaults:
    stageMode: "<mode>"

```

--------------------------------

### Configure default watch mode in ~/.mutagen.yml

Source: https://mutagen.io/documentation/synchronization/watching

Sets the default filesystem watching mode for all synchronization sessions in the Mutagen configuration file. The mode can be one of 'portable' (default), 'force-poll', or 'no-watch'.

```yaml
sync:
  defaults:
    watch:
      mode: "<mode>"

```

--------------------------------

### Resume synchronization session with mutagen sync resume

Source: https://mutagen.io/documentation/introduction/getting-started

Pauses the synchronization session named "web-app-code". Use this command to unpause a session and resume synchronization, or to provide user input (e.g., a password) when the daemon cannot automatically reconnect. It can also resume synchronization after a safety mechanism halts it.

```bash
# Pause the synchronization session named "web-app-code".
mutagen sync resume web-app-code

```

--------------------------------

### General x-mutagen configuration structure

Source: https://mutagen.io/documentation/orchestration/compose

Shows the most general structure of the x-mutagen field, including defaults, named sessions, and endpoint-specific configuration keys (configurationAlpha, configurationBeta, configurationSource, configurationDestination). Use this as a template for defining synchronization and forwarding sessions with per-endpoint options.

```yaml
x-mutagen:
  sync:
    defaults:
      ...default synchronization configuration...
    example-sync-session:
      alpha: ...
      beta: ...
      ...configuration...
      configurationAlpha:
        ...alpha-specific configuration...
      configurationBeta:
        ...beta-specific configuration...
    ...

  forward:
    defaults:
      ...default forwarding configuration...
    example-forwarding-session:
      source: ...
      destination: ...
      ...configuration...
      configurationSource:
        ...source-specific configuration...
      configurationDestination:
        ...destination-specific configuration...
    ...

```

--------------------------------

### Configure default max staging file size in ~/mutagen.yml

Source: https://mutagen.io/documentation/synchronization/size-limits

Sets a default maximum staging file size for all sessions in the Mutagen configuration file. The size can be a numeric byte count or a human-friendly string like "1000 MB". A value of 0 (the default) means no limit up to 2^64-1 bytes.

```yaml
sync:
  defaults:
    maxStagingFileSize: "<size>"

```

--------------------------------

### Mutagen project file general structure

Source: https://mutagen.io/documentation/orchestration/projects

General structure of a Mutagen project file, showing synchronization and forwarding session definitions with defaults, endpoint-specific configuration keys (configurationAlpha, configurationBeta, configurationSource, configurationDestination), and the flushOnCreate option.

```yaml
sync:
  defaults:
    ...default synchronization configuration...
    flushOnCreate: ...
  example-sync-session:
    alpha: ...
    beta: ...
    flushOnCreate: ...
    ...configuration...
    configurationAlpha:
      ...alpha-specific configuration...
    configurationBeta:
      ...beta-specific configuration...
  ...

forward:
  defaults:
    ...default forwarding configuration...
  example-forwarding-session:
    source: ...
    destination: ...
    ...configuration...
    configurationSource:
      ...source-specific configuration...
    configurationDestination:
      ...destination-specific configuration...
  ...

```

--------------------------------

### Set default probe mode in ~/.mutagen.yml

Source: https://mutagen.io/documentation/synchronization/probing-and-scanning

Configure the default probe mode for all synchronization sessions in the global Mutagen configuration file. Replace <mode> with either probe or assume.

```yaml
sync:
  defaults:
    probeMode: "<mode>"

```

--------------------------------

### Monitor a synchronization session with mutagen sync monitor

Source: https://mutagen.io/documentation/introduction/getting-started

Shows live monitoring information for a synchronization session. If no session is specified, shows information for the most recently created synchronization session.

```bash
$ mutagen sync monitor web-app-code
Name: web-app-code
Identifier: sync_rJA9OdPDEtIVcqwhOMlBw2BvMgpctZXUsEr4Jl3kUd7
Labels: None
Alpha: /home/user/project
Beta: user@example.org:~/project
Status: Staging files on beta: 75% (8942/11782)

```

--------------------------------

### Configure default max entry count in ~/.mutagen.yml

Source: https://mutagen.io/documentation/synchronization/size-limits

Sets a default maximum entry count for all sessions in the Mutagen configuration file. The count must be a positive integer. A value of 0 (the default) means no limit up to 2^64-1 entries.

```yaml
sync:
  defaults:
    maxEntryCount: <count>

```
Tokens:
Raw