ZsHero is a simple helper to manage dotfiles configuration.
This is a project under construction. Things are not well documented and pretty simple right now. Feel free to suggest features or report bugs using the issue tracker.
Who a hero would be without it's sidekicks, am I right? When it comes to
ZsHero, you're the Hero and
vim and many others are your sidekicks.
ZsHero is here to help you manage and version your configuration files.
There are two main ways to use ZsHero: as a submodule in your dotfiles repository or as a shell plugin. In the end, they both work the same way and I myself use a combination of both.
If you want to use ZsHero as a submodule you can manually add it or you can
zshero-installer in your dotfiles folder to configure the submodule for
Just run the following command on your repository:
curl -fsSL https://raw.githubusercontent.com/filipekiss/zshero/master/zshero-installer | zsh
If you don't have cURL, you can use wget:
wget -qO- https://raw.githubusercontent.com/filipekiss/zshero/master/zshero-installer | zsh
If you'd rather not run scripts directly you are free to download and inspect it, or even add the module manually to your repository:
Adding ZsHero as a submodule manually
In your repository, run the following command:
git submodule add https://github.com/filipekiss/zshero.git .zshero
Assuming you run this at the root of your repository, ZsHero will be on the
Using Zplug, Zplugin or other plugins manager
ZsHero can also be installed use any of these plugins managers:
zplugin light "filipekiss/zshero"
Using the plugin managers automatically makes the
zshero function available
in the interactive shell. If you added ZsHero as a submodule, you'll need to
init.zsh file to load the
Assuming you already sourced the
init.zsh file manually or the plugin
manager sourced it for you, the
zshero function should be available at your
Before starting, run
zshero info. You should see something like this:
ZsHero - Version 0.5.0 ZSHERO_ROOT = /Users/filipekiss/code/filipekiss/zshero ZSHERO_HOME = /Users/filipekiss/.dotfiles ZSHERO_DESTINATION_FOLDER = /Users/filipekiss ZSHERO_SIDEKICKS_FOLDER = sidekicks
This is where ZsHero was loaded from. This can be your dotfiles repository if you're using as a submodule or it can be somewhere else if you installed ZsHero using a plugin manager.
This is where ZsHero will look for configuration files when installing or where it will add new configuration files when you "adopt" them.
This is where ZsHero will put the links. Usually this is your
it's the default value assumed by ZsHero)
This is a folder where ZsHero will group your config files. We'll enter into
details later. This path is relative to
For the rest of this guide, assume the following tree for the repository where we'll configure ZsHero:
$HOME/.dotfiles ├── bin ├── homebrew └── scripts
These are just sample folders and they have nothing to do with ZsHero. I'll
also assume that you already initialized
zshero and the command is available
for you in the shell (you can check by running
Adding a new configuration to your repository
Now, we'll add our git configuration to the repository. (We'll use git in this
example but you can do this for zsh, vim and basically any configuration file
that lives under
$HOME. On macOS you can even use configuration files from
$HOME/Library/Application Support. ZsHero only cares about file structure,
not file contents).
Let's say we want to add our
$HOME/.gitconfig file to our repository. Simply
zshero add git ~/.gitconfig
You should see an output like this:
→ Created git ✔ /Users/filipekiss/.dotfiles/sidekicks/git created → Adopting git! ✔ git adopted!
If you check your
$HOME/.gitconfig file, you'll see that now it's just a
That's it. Now your
.gitconfig file is managed by ZsHero. You can
git add sidekicks/git/.gitconfig and start versioning your changes.
zshero add command
zshero add git ~/.gitconfig │ │ │ └─────── The file to be added to the repository └─────────────── The name of the 'sidekick'
The add command is really simple: You tell it which sidekick is responsible
for this configuration file and pass the path for the configuration file.
That's it. ZsHero will copy the file to a folder inside the
$ZSHEROSIDEKICKS_FOLDER named after the sidekick you chose. So, in the
command above, we're telling ZsHero that the _sidekick
git is responsible
Installing configurations from a sidekick
When setting up ZsHero in a new computer, all you need to do after installing ZsHero and cloning your dotfiles repository, is run the following
zshero install [sidekick]
The sidekick name is optional. If you don't provide a name, all sidekicks
will be installed. But if you run, let's say,
zshero install git, only the
files for the git sidekick will be added.
ZsHero © 2018+, Filipe Kiss Released under the MIT License.
Authored and maintained by Filipe Kiss