mirror of
https://github.com/deadc0de6/dotdrop.git
synced 2026-02-04 15:39:43 +00:00
adding readme
This commit is contained in:
deadc0de6
339
README.md
Normal file
339
README.md
Normal file
@@ -0,0 +1,339 @@
|
||||
# DOTDROP
|
||||
|
||||
|
||||
*Save your dotfiles once, deploy them everywhere*
|
||||
|
||||
Dotdrop makes the management of dotfiles between different
|
||||
hosts easy.
|
||||
It allows to store your dotfiles on git and automagically deploy
|
||||
different versions on different setups.
|
||||
|
||||
For example you can have a set of dotfiles for your home laptop and
|
||||
a different set for your office desktop. Those sets may overlap and different
|
||||
versions of the same dotfile can be deploy on different predefined *profiles*.
|
||||
Another use case is when you have a main set of dotfiles for your
|
||||
everyday's host and a sub-set you only need to deploy to temporary
|
||||
hosts (cloud, etc) that may be using
|
||||
a slightly different version of some of the dotfiles.
|
||||
|
||||
Features:
|
||||
|
||||
* Sync once every dotfile on git for different usages
|
||||
* Allow dotfiles templating by leveraging [jinja2](http://jinja.pocoo.org/)
|
||||
* Comparison between local and stored dotfiles
|
||||
* Handling multiple profiles with different sets of dotfiles
|
||||
* Easy import dotfiles in dotdrop
|
||||
|
||||
Quick start:
|
||||
```
|
||||
mkdir dotfiles && cd dotfiles
|
||||
git init
|
||||
git submodule add https://github.com/deadc0de6/dotdrop.git
|
||||
./dotdrop/bootstrap.sh
|
||||
./dotdrop.sh --help
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Table of Contents**
|
||||
|
||||
* [Installation](#installation)
|
||||
* [Usage](#usage)
|
||||
* [Template](#template)
|
||||
* [Example](#example)
|
||||
|
||||
## Why dotdrop ?
|
||||
|
||||
There exist many tools to manage dotfiles however not
|
||||
many allow to deploy different versions of the same dotfile
|
||||
on different hosts. Moreover dotdrop allows to specify the
|
||||
set of dotfiles that need to be deployed on a specific profile.
|
||||
|
||||
See the [example](#example) for a concrete example on
|
||||
why dotdrop rocks.
|
||||
|
||||
These are some dotfiles related projects that
|
||||
have inspired me for dotdrop:
|
||||
|
||||
* [https://github.com/EvanPurkhiser/dots](https://github.com/EvanPurkhiser/dots)
|
||||
* [https://github.com/jaagr/dots](https://github.com/jaagr/dots)
|
||||
* [https://github.com/anishathalye/dotbot](https://github.com/anishathalye/dotbot)
|
||||
|
||||
# Installation
|
||||
|
||||
The following will create a repository for your dotfiles and
|
||||
keep dotdrop as a submodules
|
||||
```
|
||||
mkdir dotfiles; cd dotfiles
|
||||
git init
|
||||
git submodule add https://github.com/deadc0de6/dotdrop.git
|
||||
./dotdrop/bootstrap.sh
|
||||
```
|
||||
|
||||
Then install the requirements:
|
||||
```
|
||||
sudo pip install -r dotdrop/requirements.txt
|
||||
```
|
||||
|
||||
Finally import your dotfiles as described [below](#usage).
|
||||
|
||||
# Usage
|
||||
|
||||
If starting fresh, the import function of dotdrop
|
||||
allows to easily and quickly get a running setup.
|
||||
|
||||
Install dotdrop on one of your host and then import any dotfiles you want dotdrop to
|
||||
manage (be it a file or a folder)
|
||||
```
|
||||
$ ./dotdrop.sh import ~/.vimrc ~/.xinitrc
|
||||
```
|
||||
|
||||
Dotdrop does two things:
|
||||
|
||||
* Copy the dotfiles in the *dotfiles* folder
|
||||
* Create the entries in the *config.yaml* file
|
||||
|
||||
Commit and push your changes.
|
||||
|
||||
Then go to another host where your dotfiles need to be managed as well,
|
||||
clone the previously setup git tree
|
||||
and compare local dotfiles with the ones stored by dotdrop
|
||||
```
|
||||
$ ./dotdrop.sh list
|
||||
$ ./dotdrop.sh compare --profile=<other-host-profile>
|
||||
```
|
||||
|
||||
Then adapt any dotfile using the [template](#template) feature
|
||||
and set a new profile for the current host by simply adding lines in
|
||||
the config files, for example:
|
||||
|
||||
```
|
||||
...
|
||||
profiles:
|
||||
host1:
|
||||
- f_vimrc
|
||||
- f_xinitrc
|
||||
host2:
|
||||
- f_vimrc
|
||||
...
|
||||
```
|
||||
|
||||
When done, you can install your dotfiles using
|
||||
|
||||
```
|
||||
$ ./dotdrop.sh install
|
||||
```
|
||||
|
||||
That's it, a single repository with all your dotfiles for your different hosts.
|
||||
|
||||
For additional usage see the help:
|
||||
|
||||
```
|
||||
$ ./dotdrop.sh --help
|
||||
_ _ _
|
||||
__| | ___ | |_ __| |_ __ ___ _ __
|
||||
/ _` |/ _ \| __/ _` | '__/ _ \| '_ |
|
||||
\__,_|\___/ \__\__,_|_| \___/| .__/ v0.1
|
||||
|_|
|
||||
|
||||
Usage:
|
||||
dotdrop.py install [--profile=<profile>] [--cfg=<path>]
|
||||
[(-f | --force)] [--nodiff] [--dry]
|
||||
dotdrop.py compare [--profile=<profile>] [--cfg=<path>]
|
||||
dotdrop.py list [--cfg=<path>]
|
||||
dotdrop.py import [--cfg=<path>] [--profile=<profile>] [--dry] <paths>...
|
||||
dotdrop.py (-h | --help)
|
||||
dotdrop.py (-v | --version)
|
||||
|
||||
Options:
|
||||
--profile=<profiles> Specify the profile to use [default: hostname].
|
||||
--cfg=<path> Path to the config [default: config.yaml].
|
||||
--dry Dry run.
|
||||
--nodiff Do not diff when installing [default: False].
|
||||
-f --force Do not warn if exists [default: False].
|
||||
-v --version Show version.
|
||||
-h --help Show this screen.
|
||||
```
|
||||
|
||||
For easy deployment the default profile used by dotdrop reflects the
|
||||
hostname of the host on which it runs.
|
||||
|
||||
## Config file details
|
||||
|
||||
The config file (defaults to *config.yaml*) is a yaml file containing
|
||||
the following entries:
|
||||
|
||||
* **config** entry: contains settings for the deployment
|
||||
* `backup`: create a backup of the dotfile in case it differs from the
|
||||
one that will be installed by dotdrop
|
||||
* `create`: create folder hierarchy when installing dotfiles if
|
||||
it doesn't exist
|
||||
* `dotpath`: path to the folder containing the dotfiles to be managed
|
||||
by dotdrop (absolute path or relative to the config file location)
|
||||
* **dotfiles** entry: a list of dotfiles in the form
|
||||
|
||||
```
|
||||
<dotfile-key-name>:
|
||||
dst: <where-this-file-is-deployed>
|
||||
src: <filename-within-the-dotpath>
|
||||
```
|
||||
|
||||
* **profiles** entry: a list of profiles with a sublist
|
||||
of dotfiles that need to be deployed for this profile
|
||||
|
||||
```
|
||||
<some-name-usually-the-hostname>:
|
||||
- <some-dotfile-key-name-defined-above>
|
||||
- <some-other-dotfile-key-name>
|
||||
- ...
|
||||
```
|
||||
|
||||
## Installing dotfiles
|
||||
|
||||
Simply run
|
||||
```
|
||||
./dotdrop.sh install
|
||||
```
|
||||
|
||||
Use the *--profile* switch to specify a profile if not using
|
||||
the host's hostname.
|
||||
|
||||
## Diffing your local dotfiles with dotdrop
|
||||
|
||||
Compare local dotfiles with dotdrop's defined ones:
|
||||
```
|
||||
./dotdrop.sh compare
|
||||
```
|
||||
|
||||
## Import new dotfiles
|
||||
|
||||
Dotdrop allows to import dotfiles directly from the
|
||||
filesystem. It will copy the dotfile and update the
|
||||
config file automatically.
|
||||
|
||||
For example to import *$HOME/.xinitrc*
|
||||
```
|
||||
$ ./dotdrop.sh import $HOME/.xinitrc
|
||||
|
||||
```
|
||||
|
||||
## List the available profiles
|
||||
|
||||
```
|
||||
$ ./dotdrop.sh list
|
||||
```
|
||||
|
||||
Dotdrop allows to choose which profile to use
|
||||
with the *--profile* switch if you used something
|
||||
else than the default (the hostname).
|
||||
|
||||
|
||||
## Update dotbot
|
||||
|
||||
If installed through the `bootstrap.sh` script, dotdrop is
|
||||
installed as a submodule within your git tree.
|
||||
You can thus simply run the following command
|
||||
to update the submodule:
|
||||
|
||||
```
|
||||
git submodule update --recursive --remote
|
||||
```
|
||||
|
||||
# Template
|
||||
|
||||
Dotdrop leverage the power of [jinja2](http://jinja.pocoo.org/) to handle the
|
||||
templating of dotfiles. See [jinja2 template doc](http://jinja.pocoo.org/docs/2.9/templates/)
|
||||
or the [example secion](#example) for more information on how to template your dotfiles.
|
||||
|
||||
Note that dotdrop uses different delimiters than the
|
||||
[jinja2](http://jinja.pocoo.org/) defaults:
|
||||
|
||||
* block start = `{%@@`
|
||||
* block end = `@@%}`
|
||||
* variable start = `{{@@`
|
||||
* variable end = `@@}}`
|
||||
* comment start = `{#@@`
|
||||
* comment end = `@@#}`
|
||||
|
||||
# Example
|
||||
|
||||
Let's consider two hosts:
|
||||
|
||||
* **home**: home computer with hostname *home*
|
||||
* **office**: office computer with hostname *office*
|
||||
|
||||
The home computer is running [awesomeWM](https://awesomewm.org/)
|
||||
and the office computer [bspwm](https://github.com/baskerville/bspwm).
|
||||
The *.xinitrc* file will therefore be different while still sharing some lines.
|
||||
Dotdrop allows to store only one single *.xinitrc* but
|
||||
to deploy different versions depending on where it is run from.
|
||||
|
||||
The following file is the dotfile stored in dotdrop containing
|
||||
jinja2 directives for the deployment based on the profile used.
|
||||
|
||||
Dotfile `<dotpath>/xinitrc`:
|
||||
```
|
||||
#!/bin/bash
|
||||
|
||||
# load Xresources
|
||||
userresources=$HOME/.Xresources
|
||||
if [ -f "$userresources" ]; then
|
||||
xrdb -merge "$userresources" &
|
||||
fi
|
||||
|
||||
# launch the wm
|
||||
{%@@ if profile == "home" @@%}
|
||||
exec awesome
|
||||
{%@@ elif profile == "office" @@%}
|
||||
exec bspwm
|
||||
{%@@ endif @@%}
|
||||
```
|
||||
|
||||
And here's how the config file looks like with this setup.
|
||||
Of course any combination of the dotfiles (different sets)
|
||||
can be done once you have more dotfiles to deploy.
|
||||
|
||||
`config.yaml` file:
|
||||
```
|
||||
config:
|
||||
backup: true
|
||||
create: true
|
||||
dotpath: dotfiles
|
||||
dotfiles:
|
||||
f_xinitrc:
|
||||
dst: ~/.xinitrc
|
||||
src: xinitrc
|
||||
profiles:
|
||||
home:
|
||||
- f_xinitrc
|
||||
office:
|
||||
- f_xinitrc
|
||||
```
|
||||
|
||||
Installing the dotfiles (the `--profile` switch is not needed if
|
||||
the hostname matches the entry in the config file):
|
||||
```
|
||||
# on home computer
|
||||
./dotdrop.sh install --profile=home
|
||||
# on office computer
|
||||
./dotdrop.sh install --profile=office
|
||||
```
|
||||
|
||||
Comparing the dotfiles:
|
||||
```
|
||||
# on home computer
|
||||
./dotdrop.sh compare
|
||||
# on office computer
|
||||
./dotdrop.sh compare
|
||||
```
|
||||
|
||||
# Contribution
|
||||
|
||||
If you are having trouble installing or using dotdrop, open an issue.
|
||||
|
||||
If you want to contribute, feel free to do a PR (please follow PEP8).
|
||||
|
||||
# License
|
||||
|
||||
This project is licensed under the terms of the GPLv3 license.
|
||||
|
||||
Reference in New Issue
Block a user