quickstart

This guide will get you up and running with trovl in minutes.

Prerequisites

  • trovl installed on your system (see Installation)
  • Basic familiarity with symbolic links
  • Editor for manifest files

Step 1: Create a target file

First, create a file that you want to symlink:

1

echo "Hello trovl" > ~/myfile.txt

Use trovl to create a symlink to this file:

1

trovl add ~/myfile.txt ~/Desktop/mylink.txt

This creates a symlink at ~/Desktop/mylink.txt that points to ~/myfile.txt.

When creating the symlink, all parent directories above it will be too, in this case Desktop.

Check that the symlink works:

1
2

cat ~/Desktop/mylink.txt
# Output: Hello trovl

Using Manifests

For managing multiple symlinks, manifests are more powerful than individual add commands since these can be run altogether.

Step 1: Create a manifest file

Create a file named manifest.json (note: the name does not matter):

1
2
3
4
5
6
7
8
9
10
11
12
13

{
  "$schema": "https://github.com/sneha-afk/trovl/raw/main/docs/trovl_schema.json",
  "links": [
    {
      "target": "~/Documents/notes.txt",
      "link": "~/Desktop/notes.txt"
    },
    {
      "target": "~/.config/myapp",
      "link": "~/myapp-config"
    }
  ]
}

Note: trovl never creates dangling links, so if these two targets do not exist, you will probably get an error.

Step 2: Preview the changes

Before applying, check what will happen:

1

trovl plan manifest.json

This shows you what symlinks will be created without modifying anything.

Step 3: Apply the manifest

Create the symlinks:

1

trovl apply manifest.json

If files already exist at the link locations, trovl will prompt you to choose whether to backup or skip them.

If a file already exists at the link location, two things happen depending on what type of file it is:

  • A directory: nope, trovl will exit with an error.
  • An ordinary file: trovl will ask if you would like to backup the file (see more details in add)
  • A symlink: trovl will ask if you would like to overwrite the symlink with a new one

Platform-Specific Configuration

One of trovl’s most powerful features is platform-specific configuration.

Create a manifest that works across different operating systems:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

{
  "links": [
    {
      "target": "~/dotfiles/bashrc",
      "link": "~/.bashrc",
      "platforms": ["linux", "darwin"]
    },
    {
      "target": "~/dotfiles/config",
      "link": "~/.config/myapp",
      "platforms": ["all"],
      "platform_overrides": {
        "windows": {
          "link": "~/AppData/Local/myapp/config"
        }
      }
    }
  ]
}

Common Options

Dry run

Test operations without making changes:

1

trovl apply manifest.json --dry-run

Verbose output

See detailed information about what trovl is doing:

1

trovl apply manifest.json --verbose

Next Steps

  • Learn more about configuring trovl’s behavior and more about manifests
  • Explore the commands supported by trovl along with their options