mirrors/dotdrop
1
0
Fork 0
mirror of https://github.com/deadc0de6/dotdrop.git synced 2026-02-12 12:26:17 +00:00
Code Activity

update readme

Browse Source
This commit is contained in:
deadc0de6
2017-12-23 20:48:33 +01:00
parent b18484ad85
commit 38111a034b
1 changed files with 107 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files

143
README.md
View File

@@ -3,6 +3,8 @@
[![Build Status](https://travis-ci.org/deadc0de6/dotdrop.svg?branch=master)](https://travis-ci.org/deadc0de6/dotdrop) [![Build Status](https://travis-ci.org/deadc0de6/dotdrop.svg?branch=master)](https://travis-ci.org/deadc0de6/dotdrop)
[![License: GPL v3](https://img.shields.io/badge/License-GPL%20v3-blue.svg)](http://www.gnu.org/licenses/gpl-3.0) [![License: GPL v3](https://img.shields.io/badge/License-GPL%20v3-blue.svg)](http://www.gnu.org/licenses/gpl-3.0)
[![Coverage Status](https://coveralls.io/repos/github/deadc0de6/dotdrop/badge.svg?branch=master)](https://coveralls.io/github/deadc0de6/dotdrop?branch=master) [![Coverage Status](https://coveralls.io/repos/github/deadc0de6/dotdrop/badge.svg?branch=master)](https://coveralls.io/github/deadc0de6/dotdrop?branch=master)
[![PyPI version](https://badge.fury.io/py/dotdrop.svg)](https://badge.fury.io/py/dotdrop)
[![Python](https://img.shields.io/pypi/pyversions/dotdrop.svg)](https://pypi.python.org/pypi/dotdrop)
*Save your dotfiles once, deploy them everywhere* *Save your dotfiles once, deploy them everywhere*
@@ -34,11 +36,11 @@ and the [example](#example) for more.
Quick start: Quick start:
```bash ```bash
sudo pip3 install dotdrop
mkdir dotfiles && cd dotfiles mkdir dotfiles && cd dotfiles
git init git init
git submodule add https://github.com/deadc0de6/dotdrop.git git submodule add https://github.com/deadc0de6/dotdrop.git
./dotdrop/bootstrap.sh dotdrop --help
./dotdrop.sh --help
``` ```
## Why dotdrop ? ## Why dotdrop ?
@@ -74,6 +76,35 @@ why dotdrop rocks.
# Installation # Installation
There's two ways of installing and using dotdrop, either [as a submodule](#as-a-submodule)
to your dotfiles git tree or system-wide [through pypi](#with-pypi).
For MacOS users, make sure to install `realpath` through homebrew
(part of *coreutils*).
## With pypi
Start by installing dotdrop
```bash
$ sudo pip3 install dotdrop
```
And then create a repository for your dotfiles
```bash
$ mkdir dotfiles; cd dotfiles
$ git init
```
To avoid the need to provide the config file path to dotdrop each time it
is call, you can create an alias:
```
alias dotdrop='cd <path-to-your-dotfiles-git-tree> && dotdrop'
```
Finally import your dotfiles as described [below](#usage).
## As a submodule
The following will create a repository for your dotfiles and The following will create a repository for your dotfiles and
keep dotdrop as a submodules: keep dotdrop as a submodules:
```bash ```bash
@@ -81,6 +112,7 @@ $ mkdir dotfiles; cd dotfiles
$ git init $ git init
$ git submodule add https://github.com/deadc0de6/dotdrop.git $ git submodule add https://github.com/deadc0de6/dotdrop.git
$ ./dotdrop/bootstrap.sh $ ./dotdrop/bootstrap.sh
$ ./dotdrop.sh --help
``` ```
Then install the requirements: Then install the requirements:
@@ -88,10 +120,42 @@ Then install the requirements:
$ sudo pip3 install -r dotdrop/requirements.txt $ sudo pip3 install -r dotdrop/requirements.txt
``` ```
Using this solution will need you to work with dotdrop by
using the generated script `dotdrop.sh` at the base
of your dotfiles repository. For any documentation below,
simply replace the call to `dotdrop` by the bash script
`dotdrop.sh`.
Finally import your dotfiles as described [below](#usage). Finally import your dotfiles as described [below](#usage).
For MacOS users, make sure to install `realpath` through homebrew ## Migrate from submodule
(part of *coreutils*).
Initially dotdrop was used as a submodule directly in the
dotfiles git tree. It has since been packaged in pypi and
can thus be used directly.
If you want to keep it as a submodule, simply do the following
```bash
$ cd <dotfiles-directory>
## get latest version
$ git submodule update --init --recursive
## update the bash script wrapper
$ ./dotdrop/bootstrap.sh
```
Otherwise, simply install it from pypi as explained [above](#with-pypi)
and get rid of the submodule:
* move to the dotfiles directory where dotdrop is used as a submodule
* remove the entire `submodule "dotdrop"` section in `.gitmodules`
* stage the change with `git add .gitmodules`
* remove the entire `submodule "dotdrop"` section in `.git/config`
* remove the submodule with `git rm --cached dotdrop`
* remove the submodule from .git with `rm -rf .git/modules/dotdrop`
* commit the changes
* delete any remaining files from the dotdrop submodule with `rm -rf dotdrop`
# Usage # Usage
@@ -99,14 +163,14 @@ If starting fresh, the `import` command of dotdrop
allows to easily and quickly get a running setup. 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 Install dotdrop on one of your host and then import any dotfiles you want dotdrop to
manage (be it a file or a folder): manage (be it a file or a directory):
```bash ```bash
$ ./dotdrop.sh import ~/.vimrc ~/.xinitrc $ dotdrop import ~/.vimrc ~/.xinitrc
``` ```
Dotdrop does two things: Dotdrop does two things:
* Copy the dotfiles in the *dotfiles* folder * Copy the dotfiles in the *dotfiles* directory
* Create the entries in the *config.yaml* file * Create the entries in the *config.yaml* file
Commit and push your changes. Commit and push your changes.
@@ -115,8 +179,8 @@ Then go to another host where your dotfiles need to be managed as well,
clone the previously setup git tree clone the previously setup git tree
and compare local dotfiles with the ones stored by dotdrop: and compare local dotfiles with the ones stored by dotdrop:
```bash ```bash
$ ./dotdrop.sh list $ dotdrop list
$ ./dotdrop.sh compare --profile=<other-host-profile> $ dotdrop compare --profile=<other-host-profile>
``` ```
Then adapt any dotfile using the [template](#template) feature Then adapt any dotfile using the [template](#template) feature
@@ -139,7 +203,7 @@ profiles:
When done, you can install your dotfiles using When done, you can install your dotfiles using
```bash ```bash
$ ./dotdrop.sh install $ dotdrop install
``` ```
That's it, a single repository with all your dotfiles for your different hosts. That's it, a single repository with all your dotfiles for your different hosts.
@@ -147,7 +211,7 @@ That's it, a single repository with all your dotfiles for your different hosts.
For additional usage see the help: For additional usage see the help:
``` ```
$ ./dotdrop.sh --help $ dotdrop --help
_ _ _ _ _ _
__| | ___ | |_ __| |_ __ ___ _ __ __| | ___ | |_ __| |_ __ ___ _ __
@@ -156,13 +220,13 @@ $ ./dotdrop.sh --help
|_| |_|
Usage: Usage:
dotdrop.py install [-fndVc <path>] [--profile=<profile>] dotdrop install [-fndVc <path>] [--profile=<profile>]
dotdrop.py compare [-Vc <path>] [--profile=<profile>] [--files=<files>] dotdrop compare [-Vc <path>] [--profile=<profile>] [--files=<files>]
dotdrop.py import [-ldVc <path>] [--profile=<profile>] <paths>... dotdrop import [-ldVc <path>] [--profile=<profile>] <paths>...
dotdrop.py listfiles [-Vc <path>] [--profile=<profile>] dotdrop listfiles [-Vc <path>] [--profile=<profile>]
dotdrop.py list [-Vc <path>] dotdrop list [-Vc <path>]
dotdrop.py --help dotdrop --help
dotdrop.py --version dotdrop --version
Options: Options:
--profile=<profile> Specify the profile to use [default: thor]. --profile=<profile> Specify the profile to use [default: thor].
@@ -189,9 +253,9 @@ the following entries:
* **config** entry: contains settings for the deployment * **config** entry: contains settings for the deployment
* `backup`: create a backup of the dotfile in case it differs from the * `backup`: create a backup of the dotfile in case it differs from the
one that will be installed by dotdrop one that will be installed by dotdrop
* `create`: create folder hierarchy when installing dotfiles if * `create`: create directory hierarchy when installing dotfiles if
it doesn't exist it doesn't exist
* `dotpath`: path to the folder containing the dotfiles to be managed * `dotpath`: path to the directory containing the dotfiles to be managed
by dotdrop (absolute path or relative to the config file location) by dotdrop (absolute path or relative to the config file location)
* **dotfiles** entry: a list of dotfiles * **dotfiles** entry: a list of dotfiles
@@ -233,7 +297,7 @@ the following entries:
Simply run Simply run
```bash ```bash
./dotdrop.sh install $ dotdrop install
``` ```
Use the `--profile` switch to specify a profile if not using Use the `--profile` switch to specify a profile if not using
@@ -243,7 +307,7 @@ the host's hostname.
Compare local dotfiles with dotdrop's defined ones: Compare local dotfiles with dotdrop's defined ones:
```bash ```bash
./dotdrop.sh compare $ dotdrop compare
``` ```
## Import new dotfiles ## Import new dotfiles
@@ -254,14 +318,14 @@ config file automatically.
For example to import `~/.xinitrc` For example to import `~/.xinitrc`
```bash ```bash
$ ./dotdrop.sh import ~/.xinitrc $ dotdrop import ~/.xinitrc
``` ```
## List the available profiles ## List the available profiles
```bash ```bash
$ ./dotdrop.sh list $ dotdrop list
``` ```
Dotdrop allows to choose which profile to use Dotdrop allows to choose which profile to use
@@ -274,7 +338,7 @@ The following command lists the different dotfiles
configured for a specific profile: configured for a specific profile:
```bash ```bash
$ ./dotdrop.sh listfiles --profile=<some-profile> $ dotdrop listfiles --profile=<some-profile>
``` ```
For example: For example:
@@ -321,11 +385,12 @@ be executed.
## Update dotdrop ## Update dotdrop
If installed through the `bootstrap.sh` script, dotdrop is Through pypi:
installed as a submodule within your git tree. ```bash
You can thus simply run the following command $ sudo pip3 install dotdrop --upgrade
to update the submodule: ```
If used as a submodule, update it with
```bash ```bash
$ git submodule update --recursive --remote $ git submodule update --recursive --remote
``` ```
@@ -407,11 +472,11 @@ This allows for storing host-specific properties and/or secrets in environment v
You can have an `.env` file in the directory where your `config.yaml` lies: You can have an `.env` file in the directory where your `config.yaml` lies:
``` ```
# My variables for this host ## My variables for this host
var1="some value" var1="some value"
var2="some other value" var2="some other value"
# Some secrets ## Some secrets
pass="verysecurepassword" pass="verysecurepassword"
``` ```
Of course, this file should not be tracked by git (put it in your `.gitignore`). Of course, this file should not be tracked by git (put it in your `.gitignore`).
@@ -419,9 +484,13 @@ Of course, this file should not be tracked by git (put it in your `.gitignore`).
Then you can invoke dotdrop with the help of an alias like that: Then you can invoke dotdrop with the help of an alias like that:
``` ```
## when using dotdrop as a submodule
alias dotdrop='eval $(grep -v "^#" ~/dotfiles/.env) ~/dotfiles/dotdrop.sh' alias dotdrop='eval $(grep -v "^#" ~/dotfiles/.env) ~/dotfiles/dotdrop.sh'
## when using dotdrop from pypi
alias dotdrop='eval $(grep -v "^#" ~/dotfiles/.env) dotdrop --cfg=~/dotfiles/config.yaml'
``` ```
This loads all the variables from `.env` (while omitting lines starting with `#`) before calling `~/dotfiles/dotdrop.sh`. This loads all the variables from `.env` (while omitting lines starting with `#`) before calling dotdrop.
# Example # Example
@@ -487,17 +556,19 @@ Installing the dotfiles (the `--profile` switch is not needed if
the hostname matches the entry in the config file): the hostname matches the entry in the config file):
```bash ```bash
# on home computer # on home computer
$ ./dotdrop.sh install --profile=home $ dotdrop install --profile=home
# on office computer # on office computer
$ ./dotdrop.sh install --profile=office $ dotdrop install --profile=office
``` ```
Comparing the dotfiles: Comparing the dotfiles:
```bash ```bash
# on home computer # on home computer
$ ./dotdrop.sh compare $ dotdrop compare
# on office computer # on office computer
$ ./dotdrop.sh compare $ dotdroph compare
``` ```
# People using dotdrop # People using dotdrop