Note: This repository contains the management code for installing packages, and not the actual "dotfiles" themselves. See Dotfiles.

dotfiles repositories are commonly used for synchronising files related to *nix shell environments. In addition to offering a synchronisation source, this piece of software also helps set up some more sought utilities and tools.

usage: dotfiles [-h] [-l | -i | -u] [package [package ...]]

The dotfiles.py main script handles installing the environment. Specify the packages to install.

If no packages are specified, the list and description of packages will be shown. If package names are specified, the default action is to install the packages.

Listing status for a particular package is possible if --list is explicitly specified: dotfiles --list foo bar.

⚠️ Note: This tool is intended to be used when a new user profile is created, such as when a new machine is installed.

Multiple packages belonging to a package "group" can be selected by saying group.* or group.__ALL__.

Multiple package sources can be given to Dotfiles. To edit the package configuration, use the built-in editor by calling

dotfiles --edit-sources

which will allow you to manually add, remove, move the sources.

The package sources are forming a priority list. When installing a package foo, it will be installed from the first source it is found.

By default, the manager framework will use the following 2 package sources, in order:

1. Your ~/Dotfiles/packages/ directory.
2. The author's own Dotfiles repository.

To uninstall packages, specify --uninstall before the package names:

dotfiles --uninstall foo

Packages are present across a number of source root directories, where an arbitrary hierarchy can be present.

A package is any directory which contains a (valid) package.json file. Subpackages are translated from filesystem hierarchy to logical hierarchy via ., i.e. tools/system/package.json denotes the tools.system package.

Package descriptor files are YAMLs which contain the directives describing installation and handling of the package. Any other file is disregarded by the tool unless explicitly used, e.g. being the source of a copy operation.

The user-specific package source root configuration is parsed and expanded at the start of the invocation into special directories under ~/.cache and ~/.local/share. When a package name foo is requested, every package source is queried in the order configured, until one source is found, or it is realised the package does not exist. This resolution order is true for every package name lookup, so it applies to dependency queries, too.

Contains a free form textual description for the package which is printed in the "help" when dotfiles.py is invoked without any arguments.

The logical names of packages which must be installed before the installation of the current package could begin.

Whether the package should implicitly depend on the parent (e.g. for tools.system, parent is tools), assuming the parent is a valid package.

Support packages are packages which have all the necessary directives to perform an installation, but are NOT meant to do persistent changes to the user's environment and files.

Support packages can be depended upon, but may not be directly installed by the user. A support package's "installed" status will not be saved. Support packages may not have uninstall actions.

Packages with internal in their name (such as internal.mypkg) will automatically be considered as support packages.

The package descriptor might take the if and if not keys, which specifies a list of strings, each associated with a condition. (See the table below for the options.)

Conditions for the entire package require satisfaction, without which the package will NOT be visible to the installer.

description: A package that can only be installed if 'sudo'.
if:
  - superuser
install:
  - action: shell
    command: "sudo echo 'Hey root!'"

Action directives may specify a list of conditions, with the $if and $if not meta-arguments. The conditions in the $if list (positive conditions) must all be satisfied, and none of the conditions in the $if not (negative conditions) list may be satisfied for the action to execute. If the conditions aren't as described for the action, the action will be skipped, but the rest of the actions will be executed. $if and $if not can both be specified on the same action. If neither is specified, the action is not conditional, and will always execute.

    - action: print
      $if:
        - superuser
      text: "I have sudo!"
    - action: print
      $if not:
        - superuser
      text: "I do not have sudo!"
    - action: print
      $if:
        - superuser
      $if not:
        - superuser
      text: "Impossible to execute... hopefully."

The contents of the package-level and the action-level condition lists are the same:

The installation of a package consists of two separate phases. Before the installation of the first package, a temporary $SESSION_DIR is created where temporary resources may be shared between packages. This directory is deleted at the end of execution of all installs. The usage of this feature is discouraged unless absolutely necessary.

Action directives are laid out in the package descriptor YAML file as shown below. Each phase has a list of key-value tuples, which will be executed in the order they are added. Each tuple must have an action argument which defines the type/kind of the action to run.

The rest of the arguments to specify are specific to the action type identifier. All the arguments that are not meta-arguments (starting with $) are specific to the action type identifier.

prepare:
    - action: shell
      command: echo "True"

First, the package's configuration and external dependencies are obtained. This is called the preparation phase.

At the beginning of this phase, the executing environment switches into a temporary directory. In most directives, $TEMPORARY_DIR can be used to refer to this directory when specifying a path.

The installation starts from the packages/foo/bar/ directory (for package foo.bar). This phase is the main phase where changes to the user's files should be done.

In most directives, $TEMPORARY_DIR can be used to refer to the prepare phase's directory when specifying a path. (This may only be done if there was a prepare phase for the package!)

$PACKAGE_DIR refers to the directory where the package's metadata file (package.yaml) and additional resources are.

Uninstall starts from the directory that corresponds to $PACKAGE_DIR, but contains the files that were present in this directory at installation, not what are currently present on the system. This means that the state of package.yaml and the resource files are kept intact even if the packages/ directory on the system is updated.

In uninstall mode, $PACKAGE_DIR refers to this archived directory.

⚠️ Note! The "original" $PACKAGE_DIR is not accessible during uninstall.

Certain install directives can automatically be mapped to uninstall actions. At the uninstall of a package, the corresponding actions are executed in reverse order (compared to the order of install directives).

If automatic uninstall actions were generated for a package's install, they are executed after the manually written uninstall directives are executed.

Automatic transformation of the executed actions might be beneficial in some circumstances. All transformers are enabled with the --X flag, followed by the transformer's name (with dashes).

To forbid a transformer from running for an action, add its name set to false under the $transform meta-argument.

install:
  - action: copy
    file: foo
    to: bar
    $transform:
      copies as symlinks: false

Instead of executing copy-like directives during install normally, use the symlink action to set up symbolic links. The links will target the original files in the package source. This allows easy versioning of configuration file changes if the source is a versioned repository, as the original package source tree will have the files modified.