Manual

First Start Wizard

Running hods with a user that doesn’t have a ~/.hods/ directory yet, will start the wizard. You can also start it from the menu at any time.

Pull existing configuration guides you through the setup of a new hods client:

1. Open the Settings window. (Configure your server and ssh-agent preferences.)

2. Start the SSH Agent (if enabled).

3. Pull the configuration file.

4. Open the Install Features window. (Select the features to install.)

5. Pull sources in installed features.

When done, you’ll see the Home screen. Press F5 to open the Update window and synchronize your home directory.

Start new configuration guides you through your first configuration from scratch:

1. Open the Settings window.

2. Start the SSH Agent (if enabled).

3. Open the Add Feature window.

When done, you’ll see the Home screen. Add a source to your feature and press a to add files and directories to it.

Abort exits the wizard. You will be asked to start the SSH Agent.

Home

This is the main screen of hods, the navigation and overview of your configuration. Use the arrow keys to navigate and enter to show/edit the selected item.

To switch to the menu press F2.

• The left column is the list of all your features (source groups).

• The middle column is a list of Sources in the selected feature. (git repositories and/or rsync directories)

• The right column is the file tree of the selected source.

  • Press a to add files from your home directory to the selected directory.

Features and Sources are synchronized and updated in the order they are displayed. Use F7 (move down) and F8 (move up) to rearrange them.

Settings

Configuration Options

Server

This is the remote ssh user that stores your configuration ([user@]server). hods will synchronize features in its configuration directory ([user@]server:.hods/) with the local one. Leave this empty on your server user.

Note

git source repositories are synchronized with their upstream!

Check Server is a proxy in Settings to synchronize them using rsync instead.

And/Or edit the git repository and check Pull Only to disable push.

This is a proxy

Make the current instance of hods a proxy server.

If checked, pull and push will ignore the Installed flag of your features and synchronize all sources. You can then use the current [user@]host as server for other hods instances. Make sure to check Server is a proxy on those clients that don’t have access to the internet.

This is unchecked by default.

Server is a proxy

This instance of hods sits behind a proxy and/or does not have access to all upstream git repositories.

If checked, git repositories will be synchronized with the configured server using rsync.

This is unchecked by default.

Cascade

Forward synchronization to the proxy server.

If checked, hods will:

• ssh to the server and run pull on it before running it locally and

• ssh to the server and run push on it after running it locally

This setting is ignored if Server is a proxy is not checked.

This is checked by default.

SSH Agent

The pull and push commands for your sources may require you to enter the password for your ssh key many times. To enter it only once you need a ssh-agent.

At every start hods looks for a running ssh-agent and a key to use. If not found, it starts an agent for the current session and/or adds your key.

There are 4 options to control this behaviour:

• Start if not running

• Ask to start if not running (This is the default)

  

• Warn if not running

• Do nothing disables the check. hods will not look for a running agent or start one in this mode.

Template Variables

This is a list of your own custom template context variables.

hods scans these every time you Pull the configuration. If new variables are found it will ask you for their values.

You can also list all available variables here.

Add Feature

Feature

The feature is a group of Sources to create different home directory configurations. Each user / home directory can select a different set of features to install.

It also provides shell-hooks to prepare or finalize the synchronization of its sources. They are only executed for installed features!

Configuration options

Installed

Enable this feature for the current user / home directory.

If checked, the sources in this feature will be:

• downloaded from the server on Pull

• used to synchronize the home directory of the current user and

• uploaded to the server on Push

Note

A proxy server (Server is a proxy) will always pull and push all features. You can still use this to keep the home directory of that user clean.

This is unchecked by default.

Install by default

Pre-check this feature in the Install Features window.

This is unchecked by default.

Install Features

When you pull features that are unknown to the local configuration you’ll see this window. Select the features you want to install.

If Install by default is checked, the feature is pre-checked here.

Sources

Sources are root source directories that can be synchronized using git or rsync.

By default, hods creates files in your home directory using its relative source path. In other words, the file tree of a source is considered the desired tree of your home directory. The default destination of the source itself is your home directory. Any file in it is created at the same relative location in your home directory. E.g.:

• <source>/.vimrc -> ~/.vimrc

• <source>/bin/decrypt-ssl -> ~/bin/decrypt-ssl

• <source>/.config/i3/config -> ~/.config/i3/config

You can change the destination at any level. Each file and directory uses the destination of its parent directory by default.

Configuration options

Pull Only

(read-only)

If checked this source will be skipped during Push.

Check this for sources where you don’t have permissions to add or change files.

This is unchecked by default

rsync source

The rsync source is a directory stored on your hods server. Its main purpose is to include private and/or binary files in your configuration.

It is skipped when synchronizing sources on the server since this would synchronize it with itself.

git source

The git source is a clone of a git repository.

Unlike rsync directories, git repositories are synchronized when running hods on the server.

Note

The Server is a proxy setting will turn all git sources into rsync-sources. E.g. they will be synchronized with the server using rsync.

Directory

The source directory is a simple file container with some control over the files and directories it contains.

Configuration options

Ignore

Ignore this directory and all of its contents.

If checked, the directory and all of its children will be skipped in the Update. E.g. no symlinks or templates are created in your home directory.

This is unchecked by default.

Add Files

Pressing a on a directory shows this window.

Select the directories and files you want to add. hods copies them into the directory you pressed a on. On next update, they will be replaced with symlinks and/or templates.

File

The source file configures each file in your sources.

Configuration options

Mode

The mode specifies how to apply the file to your home directory. There are 3 options:

• ignore: Do not apply this file to the home directory.

• link: Create a symlink in the home directory pointing to this file. (This is the default)

• template: This file is a template. Render it to the home directory.

  • This mode requires jinja2 or mako to be installed (whichever you prefer).

  • See Template Context for all available variables and/or add your own in Settings

Destination

The destination is the relative path to create the symlink or template in your home directory.

By default, it uses the destination of its parent directory as a base. Configure it on the parent directory instead to change the destination of all of its children recursively.

Template Engine

The template engine used to render this template.

This option is only used and visible if the selected Mode is template.

Template Context

The context variables consist of:

• All Environment variables

• Your own custom variables configured in Settings

• Some information about the current hods installation and configuration:

  • version (str): Current hods version

  • server (str): The value of Server

  • is_proxy (bool): The value of This is a proxy

  • is_server (bool): True if server is empty or is_proxy is True

  • server_is_proxy (bool): The value of Server is a proxy

  • cascade (bool): The value of Cascade

• A map (dict) of all features in your configuration called features

• The File object to be rendered called file

New Variables

When you pull variables that are unknown to the local configuration you’ll see this window. Enter the values for your user or leave them empty to use the default values.

Update

When everything is configured, its time to update your home directory.

hods shows a summary before adding or removing anything. Read it carefully!

Then, finally its time to update!

Server Synchronization

The pull and push actions synchronize the configuration and sources in your ~/.hods/ directory with the configured Server.

Pull

The pull action in detail:

1. If Server is a proxy and Cascade are checked, ssh to the server and run the pull action on it.

2. Download the configuration file from <server>:.hods/config.json using rsync.

3. If new features are found, show the Install Features window.

4. If new template variables are found, show the New Variables window.

5. For each installed feature:

   1. Run its pre-pull hook.

   2. Download/pull all of its sources.

   3. Run its post-pull hook.

Push

The push action in detail:

1. Upload the configuration file to <server>:.hods/config.json using rsync.

2. For each installed features:

   1. Run its pre-push hook.

   2. For each source:

      1. If it’s a git repository with changes, run git add --all and git commit. (Opens an editor to list the changes and to change the commit message.)

      2. Upload/push the source.

   3. Run its post-push hook.

3. If Server is a proxy and Cascade are checked, ssh to the server and run the push action on it.