vcsh

Initialize an (empty) repository

$ vcsh init [repository_name]

$ vcsh clone [git_url] [repository_name]

$ vcsh list

$ vcsh [repository_name] [git_command]

$ vcsh [push|pull]

$ vcsh write-gitignore [repository_name]

vcsh [OPTIONS] COMMAND [ARGUMENTS...]

OPTIONS
    Global options that can be applied before any vcsh command to modify its behavior.

-d, --dry-run
    Perform a dry run; show what would be done without actually making changes to files or repositories.

-v, --verbose
    Increase the verbosity of vcsh's output, providing more detailed information about its operations.

--config <file>
    Specify an alternative configuration file to use instead of the default ~/.config/vcsh/config.

--repo <repo_name>
    Specify the dotfile repository (or repositories, if used multiple times) on which the subsequent command should operate. If omitted for some commands, it may operate on all repositories or require selection.

--list-repo
    List all vcsh repositories currently known and managed by vcsh on the system.

COMMAND
    The specific operation to perform. vcsh dispatches to various subcommands, many of which mirror standard Git commands.

add <file>...
    Add file contents from your home directory to the index of the selected vcsh repository, preparing them for commit.

clone <url> <repo_name>
    Clone an existing Git repository from a URL into vcsh, assigning it a local repo_name for management.

commit [OPTIONS]
    Record changes to the repository by creating a new commit containing the currently staged contents.

exec <repo_name> -- <git_command> [ARGUMENTS]
    Execute an arbitrary Git command directly within the specified vcsh repository. The -- acts as a separator between vcsh arguments and Git command arguments.

init <repo_name>
    Initialize a new, empty vcsh repository with the given name, ready for adding dotfiles.

link [repo_name...]
    Ensures that files from the specified (or all) vcsh repositories are correctly placed or linked into your home directory. Useful after cloning or pulling changes.

list
    Displays a list of all configured vcsh repositories, similar to --list-repo.

pull [OPTIONS]
    Fetch changes from the remote repository and integrate them into the local vcsh repository.

push [OPTIONS]
    Update remote references along with associated objects from the local vcsh repository.

status
    Show the working tree status for the selected (or all) vcsh repositories, indicating modified, added, or untracked files.

update [repo_name...]
    Update one or all vcsh repositories by pulling changes from their remotes and linking them into the home directory.

vcsh (version control shell) is a powerful command-line tool designed to manage your dotfiles (configuration files) using Git, but with a unique approach that fosters isolation and flexibility. Instead of maintaining a single, monolithic Git repository for all your dotfiles, vcsh allows you to create separate, independent Git repositories for different sets of configurations—for example, one for your Vim settings, another for Bash, and yet another for Git configurations.

It operates by creating bare Git repositories for each dotfile collection in a dedicated hidden directory (typically ~/.config/vcsh/repo.d/). These repositories then transparently project their contents into your home directory, making them appear as if they reside there directly. This method avoids the complexities of symlink farms, Git submodules, or large, unmanageable repositories.

vcsh acts as a user-friendly wrapper around standard Git commands. It enables you to perform common Git operations like add, commit, push, and pull on specific dotfile repositories, simplifying the management of configurations across different machines, sharing specific subsets of dotfiles, and preventing accidental exposure of sensitive information.

Effective use of vcsh benefits from a solid understanding of Git, especially the concept of bare repositories. Initial setup and advanced configurations can sometimes be complex, requiring manual intervention for conflicts or specific linking needs. As vcsh directly interacts with files in your home directory, careful management is advised to prevent conflicts if other dotfile management tools are also in use. It does not provide built-in secrets management; users should employ separate tools like git-crypt or age for sensitive information.

vcsh's core mechanism involves creating bare Git repositories for each dotfile group (e.g., 'bash', 'vim') within a hidden directory, commonly ~/.config/vcsh/repo.d/. When you run a vcsh command like vcsh commit bash, vcsh effectively executes the corresponding Git command from within the ~/.config/vcsh/repo.d/bash.git repository, using your home directory (~) as the working tree. The vcsh link command (or implicit linking during vcsh update) ensures that the files tracked by these bare repositories are correctly placed or synchronized in your home directory, providing a seamless user experience without requiring traditional working directories for each Git repo.

vcsh can be extensively configured via a main configuration file, usually located at ~/.config/vcsh/config. This file allows users to define custom aliases, global settings, and even repository-specific configurations. A powerful feature is the ability to define hooks (e.g., post-checkout, post-merge) that automatically execute scripts or commands after certain Git operations within a vcsh repository. This enables automation of tasks like compiling configuration files, running linters, or restarting services when dotfiles are updated.

vcsh was created by Richi Plana in 2011 to address the limitations of existing dotfile management approaches. Its primary goal was to provide a flexible and robust system that avoids monolithic Git repositories, complex symlink farms, and the accidental exposure of sensitive data. By leveraging Git's bare repository functionality, vcsh offered a novel solution for managing distinct sets of configuration files while making them appear to reside cohesively within the user's home directory.

git(1), stow(1), chezmoi(1), rcm(1), ansible(1)