mirror of
https://github.com/deadc0de6/dotdrop.git
synced 2026-02-04 19:44:45 +00:00
update doc
This commit is contained in:
deadc0de6
18
docs/README.md
Normal file
18
docs/README.md
Normal file
@@ -0,0 +1,18 @@
|
||||
# Dotdrop documentation
|
||||
|
||||
[Dotdrop](https://deadc0de.re/dotdrop/) is a dotfiles manager that provides efficient ways of managing your dotfiles.
|
||||
It is especially powerful when it comes to managing those across different hosts..
|
||||
|
||||
The idea of dotdrop is to have the ability to store each dotfile only once and deploy them with a different content on different hosts/setups.
|
||||
To achieve this, it uses [jinja2](http://jinja.pocoo.org/) which is a templating engine that allows to specify
|
||||
during the dotfile installation how (with what content) each dotfile will be installed based on a selected profile.
|
||||
|
||||
Most information on using dotdrop are described in this wiki and in the [readme](https://github.com/deadc0de6/dotdrop/blob/master/README.md).
|
||||
For more check
|
||||
|
||||
* [a quick overview of dotdrop features](https://deadc0de.re/dotdrop/)
|
||||
* [the blogpost on dotdrop](https://deadc0de.re/articles/dotfiles.html)
|
||||
* [an example](https://github.com/deadc0de6/dotdrop#getting-started)
|
||||
* [how people are using dotdrop](meta/people-using-dotdrop.md)
|
||||
|
||||
For more examples of config file, [search github](https://github.com/search?q=filename%3Aconfig.yaml+dotdrop&type=Code).
|
||||
@@ -3,28 +3,7 @@
|
||||
The config file used by dotdrop is
|
||||
[config.yaml](https://github.com/deadc0de6/dotdrop/blob/master/config.yaml).
|
||||
|
||||
* [Location](#location)
|
||||
* [Format](#format)
|
||||
* [Actions](#actions)
|
||||
* [Transformations](#transformations)
|
||||
* [Variables](#variables)
|
||||
* [Interpreted variables](#interpreted-variables)
|
||||
* Config details on
|
||||
* [Symlinking dotfiles](#symlinking-dotfiles)
|
||||
* [All dotfiles for a profile](#all-dotfiles-for-a-profile)
|
||||
* [Include dotfiles from another profile](#include-dotfiles-from-another-profile)
|
||||
* [Import profile dotfiles from file](#import-profile-dotfiles-from-file)
|
||||
* [Import variables from file](#import-variables-from-file)
|
||||
* [Import actions from file](#import-actions-from-file)
|
||||
* [Import config files](#import-config-files)
|
||||
* Dynamic elements
|
||||
* [Dynamic dotfile paths](#dynamic-dotfile-paths)
|
||||
* [Dynamic actions](#dynamic-actions)
|
||||
* [Dynamic transformations](#dynamic-transformations)
|
||||
|
||||
---
|
||||
|
||||
# Location
|
||||
## Location
|
||||
|
||||
Unless specified dotdrop will look in following places for the config file (`config.yaml`)
|
||||
and use the first one found
|
||||
@@ -38,7 +17,7 @@ and use the first one found
|
||||
You can force dotdrop to use a different file either by using the `-c --cfg` cli switch
|
||||
or by defining the `DOTDROP_CONFIG` environment variable.
|
||||
|
||||
# Format
|
||||
## Format
|
||||
|
||||
Dotdrop config file uses [yaml](https://yaml.org/) syntax.
|
||||
|
||||
@@ -209,23 +188,23 @@ dynvariables:
|
||||
<variable-name>: <shell-oneliner>
|
||||
```
|
||||
|
||||
# Actions
|
||||
## Actions
|
||||
|
||||
see [Actions](usage-actions.md)
|
||||
|
||||
# Transformations
|
||||
## Transformations
|
||||
|
||||
see [Transformations](usage-transformations.md)
|
||||
|
||||
# Variables
|
||||
## Variables
|
||||
|
||||
see [Variables](config-variables.md)
|
||||
|
||||
# Interpreted variables
|
||||
## Interpreted variables
|
||||
|
||||
see [Interpreted variables](config-variables.md)
|
||||
|
||||
# Symlinking dotfiles
|
||||
## Symlinking dotfiles
|
||||
|
||||
Dotdrop is able to install dotfiles in three different ways
|
||||
which are controlled by the `link` attribute of each dotfile:
|
||||
@@ -236,7 +215,7 @@ which are controlled by the `link` attribute of each dotfile:
|
||||
|
||||
For more see [this how-to](../howto/symlinked-dotfiles.md)
|
||||
|
||||
# All dotfiles for a profile
|
||||
## All dotfiles for a profile
|
||||
|
||||
To use all defined dotfiles for a profile, simply use
|
||||
the keyword `ALL`.
|
||||
@@ -259,7 +238,7 @@ profiles:
|
||||
- f_vimrc
|
||||
```
|
||||
|
||||
# Include dotfiles from another profile
|
||||
## Include dotfiles from another profile
|
||||
|
||||
If one profile is using the entire set of another profile, one can use
|
||||
the `include` entry to avoid redundancy.
|
||||
@@ -306,7 +285,7 @@ profiles:
|
||||
- "profile_{{@@ var1 @@}}"
|
||||
```
|
||||
|
||||
# Import profile dotfiles from file
|
||||
## Import profile dotfiles from file
|
||||
|
||||
Profile's dotfiles list can be loaded from external files
|
||||
by specifying their paths in the config entry `import` under the specific profile.
|
||||
@@ -346,7 +325,7 @@ import:
|
||||
- profiles.d/{{@@ profile @@}}.yaml
|
||||
```
|
||||
|
||||
# Import variables from file
|
||||
## Import variables from file
|
||||
|
||||
It is possible to load variables/dynvariables from external files by providing their
|
||||
paths in the config entry `import_variables`.
|
||||
@@ -378,7 +357,7 @@ import_variables:
|
||||
- variables.d/myvars.yaml:optional
|
||||
```
|
||||
|
||||
# Import actions from file
|
||||
## Import actions from file
|
||||
|
||||
It is possible to load actions from external files by providing their
|
||||
paths in the config entry `import_actions`.
|
||||
@@ -417,7 +396,7 @@ import_actions:
|
||||
- actions.d/myactions.yaml:optional
|
||||
```
|
||||
|
||||
# Import config files
|
||||
## Import config files
|
||||
|
||||
Entire config files can be imported. This means making the following available
|
||||
from the imported config file in the original config file:
|
||||
@@ -495,7 +474,7 @@ import_configs:
|
||||
- other-config.yaml:optional
|
||||
```
|
||||
|
||||
# Dynamic dotfile paths
|
||||
## Dynamic dotfile paths
|
||||
|
||||
Dotfile source (`src`) and destination (`dst`) can be dynamically constructed using
|
||||
defined variables ([variables and dynvariables](config-variables.md)).
|
||||
@@ -517,7 +496,7 @@ profiles:
|
||||
|
||||
Make sure to quote the path in the config file.
|
||||
|
||||
# Dynamic actions
|
||||
## Dynamic actions
|
||||
|
||||
Variables ([config variables and dynvariables](config-variables.md)
|
||||
and [template variables](../template/templating.md#template-variables)) can be used
|
||||
@@ -550,7 +529,7 @@ config:
|
||||
|
||||
Make sure to quote the actions using variables.
|
||||
|
||||
# Dynamic transformations
|
||||
## Dynamic transformations
|
||||
|
||||
As for [dynamic actions](#dynamic-actions), transformations support
|
||||
the use of variables ([variables and dynvariables](config-variables.md)
|
||||
|
||||
@@ -1,9 +1,4 @@
|
||||
* [ignore patterns](#ignore-patterns)
|
||||
* [examples](#examples)
|
||||
|
||||
---
|
||||
|
||||
# ignore patterns
|
||||
# Ignore patterns
|
||||
|
||||
It is possible to ignore specific patterns when using dotdrop. For example for `compare` when temporary
|
||||
files don't need to appear in the output.
|
||||
@@ -41,7 +36,7 @@ dotfiles:
|
||||
...
|
||||
```
|
||||
|
||||
# examples
|
||||
## examples
|
||||
|
||||
To completely ignore comparison of a specific dotfile:
|
||||
```yaml
|
||||
|
||||
37
docs/howto/README.md
Normal file
37
docs/howto/README.md
Normal file
@@ -0,0 +1,37 @@
|
||||
# HowTo
|
||||
|
||||
## Append to a dotfile
|
||||
|
||||
[Append to a dotfile](howto/append.md)
|
||||
|
||||
## Create special files
|
||||
|
||||
[Create special files](howto/create-special-files.md)
|
||||
|
||||
## Handle special chars
|
||||
|
||||
[Handle special chars](howto/special-chars.md)
|
||||
|
||||
## Improve git integration
|
||||
|
||||
[Improve git integration](improve-git-integration.md)
|
||||
|
||||
## Merge files on install
|
||||
|
||||
[Merge files on install](howto/merge-files-when-installing.md)
|
||||
|
||||
## Share content across dotfiles
|
||||
|
||||
[Share content across dotfiles](howto/sharing-content.md)
|
||||
|
||||
## Store compressed directories
|
||||
|
||||
[Store compressed directories](howto/store-compressed-directories.md)
|
||||
|
||||
## Store secrets
|
||||
|
||||
[Store secrets](howto/sensitive-dotfiles.md)
|
||||
|
||||
## Symlink dotfiles
|
||||
|
||||
[Symlink dotfiles](howto/symlinked-dotfiles.md)
|
||||
14
docs/howto/improve-git-integration.md
Normal file
14
docs/howto/improve-git-integration.md
Normal file
@@ -0,0 +1,14 @@
|
||||
# Improve git integration
|
||||
|
||||
The below aliases can help with the process of updating your dotfiles between multiple hosts. Add those to your `~/.zshrc` or `~/.bashrc`. You can then simply run `dotsync` to push or pull from your dotfile repository.
|
||||
|
||||
```
|
||||
# Your dotdrop git repository location
|
||||
export DOTREPO="/path/to/your/dotdrop/repo"
|
||||
|
||||
alias dotdrop="$DOTREPO/dotdrop.sh"
|
||||
alias dotgit="git -C $DOTREPO"
|
||||
alias dotsync="dotgit pull && dotgit add -A && dotgit commit && dotgit push; dotdrop install"
|
||||
```
|
||||
|
||||
Provided by [ReekyMarko](https://github.com/ReekyMarko)
|
||||
@@ -1 +0,0 @@
|
||||
**TODO**
|
||||
@@ -1,32 +0,0 @@
|
||||
# Welcome to the dotdrop wiki!
|
||||
|
||||
The idea of dotdrop is to have the ability to store each dotfile only once and deploy them with a different content on different hosts/setups. To achieve this, it uses [jinja2](http://jinja.pocoo.org/) which is a templating engine that allows to specify, during the dotfile installation with dotdrop, based on a selected profile, how (with what content) each dotfile will be installed.
|
||||
|
||||
Most information on using dotdrop are described in this wiki and in the [readme](https://github.com/deadc0de6/dotdrop/blob/master/README.md). For more check
|
||||
|
||||
* [a quick overview of dotdrop features](https://deadc0de.re/dotdrop/)
|
||||
* [the blogpost on dotdrop](https://deadc0de.re/articles/dotfiles.html)
|
||||
* [an example](https://github.com/deadc0de6/dotdrop#getting-started)
|
||||
* [how people are using dotdrop](meta/people-using-dotdrop.md)
|
||||
|
||||
For more examples of config file, [search github](https://github.com/search?q=filename%3Aconfig.yaml+dotdrop&type=Code).
|
||||
|
||||
# Wiki pages
|
||||
|
||||
* [Installation](installation.md)
|
||||
* [Usage](usage.md)
|
||||
* [Config file format](config/config.md)
|
||||
* [Use actions](config/usage-actions.md)
|
||||
* [Use transformations](config/usage-transformations.md)
|
||||
* [Manage system/global config files](howto/global-config-files.md)
|
||||
* [Ignore patterns](config/ignore-pattern.md)
|
||||
* [Templating](template/templating.md)
|
||||
* HowTo
|
||||
* [Store secrets](howto/sensitive-dotfiles.md)
|
||||
* [Symlink dotfiles](howto/symlinked-dotfiles.md)
|
||||
* [Store compressed directories](howto/store-compressed-directories.md)
|
||||
* [Merge files when installing](howto/merge-files-when-installing.md)
|
||||
* [Append to a dotfile](howto/append.md)
|
||||
* [Handle special chars](howto/special-chars.md)
|
||||
* [Share content across dotfiles](howto/sharing-content.md)
|
||||
* [Create special files](howto/create-special-files.md)
|
||||
@@ -7,20 +7,7 @@ If you want to keep your python environment clean, use the virtualenv installati
|
||||
[With pypi in a virtualenv](#with-pypi-in-a-virtualenv)).
|
||||
In that case, the virtualenv environment might need to be loaded before any attempt to use dotdrop.
|
||||
|
||||
Installation instructions
|
||||
|
||||
* Installation
|
||||
* [Install as a submodule](#as-a-submodule)
|
||||
* [Install as a submodule in a virtualenv](#as-a-submodule-in-a-virtualenv)
|
||||
* [Install with pypi](#with-pypi)
|
||||
* [Install with pypi in a virtualenv](#with-pypi-in-a-virtualenv)
|
||||
* [Aur packages](#aur-packages)
|
||||
* [Snap package](#snap-package)
|
||||
* [Setup your repository](#setup-your-repository)
|
||||
* [Shell completion](#shell-completion)
|
||||
* [Dependencies](meta/dependencies.md)
|
||||
|
||||
# As a submodule
|
||||
## As a submodule
|
||||
|
||||
The following will create a git repository for your dotfiles and
|
||||
keep dotdrop as a submodule:
|
||||
@@ -51,7 +38,7 @@ shell with the config file path, for example
|
||||
alias dotdrop=<absolute-path-to-dotdrop.sh> --cfg=<path-to-your-config.yaml>'
|
||||
```
|
||||
|
||||
# As a submodule in a virtualenv
|
||||
## As a submodule in a virtualenv
|
||||
|
||||
To install in a [virtualenv](https://virtualenv.pypa.io):
|
||||
```bash
|
||||
@@ -79,7 +66,7 @@ $ ./dotdrop.sh --help
|
||||
|
||||
Then follow the instructions under [As a submodule](#as-a-submodule).
|
||||
|
||||
# With pypi
|
||||
## With pypi
|
||||
|
||||
Install dotdrop
|
||||
```bash
|
||||
@@ -88,7 +75,7 @@ $ pip3 install --user dotdrop
|
||||
|
||||
and then [setup your repository](#setup-your-repository).
|
||||
|
||||
# With pypi in a virtualenv
|
||||
## With pypi in a virtualenv
|
||||
|
||||
Install dotdrop in a virtualenv from pypi
|
||||
```bash
|
||||
@@ -106,7 +93,7 @@ $ dotdrop --help
|
||||
|
||||
Then follow the instructions under [With pypi](#with-pypi).
|
||||
|
||||
# Aur packages
|
||||
## Aur packages
|
||||
|
||||
Dotdrop is available on aur:
|
||||
* stable: https://aur.archlinux.org/packages/dotdrop/
|
||||
@@ -114,7 +101,7 @@ Dotdrop is available on aur:
|
||||
|
||||
Then follow the [doc to setup your repository](#setup-your-repository).
|
||||
|
||||
# Snap package
|
||||
## Snap package
|
||||
|
||||
Dotdrop is available as a snap package: <https://snapcraft.io/dotdrop>
|
||||
|
||||
@@ -125,7 +112,45 @@ snap install dotdrop
|
||||
|
||||
Then follow the [doc to setup your repository](#setup-your-repository).
|
||||
|
||||
# Setup your repository
|
||||
## Dependencies
|
||||
|
||||
Beside the python dependencies defined in [requirements.txt](https://github.com/deadc0de6/dotdrop/blob/master/requirements.txt),
|
||||
dotdrop depends on following tools:
|
||||
|
||||
* `file`
|
||||
* `diff`
|
||||
* `mkdir`
|
||||
* `git` (for the entry point script [dotdrop.sh](https://github.com/deadc0de6/dotdrop/blob/master/dotdrop.sh))
|
||||
* `readlink` or `realpath` (for the entry point script [dotdrop.sh](https://github.com/deadc0de6/dotdrop/blob/master/dotdrop.sh))
|
||||
|
||||
For MacOS users, make sure to install `realpath` (part of `coreutils`) through [homebrew](https://brew.sh/).
|
||||
|
||||
## Update dotdrop
|
||||
|
||||
If using dotdrop as a submodule, one can control if dotdrop
|
||||
is auto-updated through the [dotdrop.sh](https://github.com/deadc0de6/dotdrop/blob/master/dotdrop.sh)
|
||||
script by defining the environment variable `DOTDROP_AUTOUPDATE=yes`.
|
||||
If undefined, `DOTDROP_AUTOUPDATE` will take the value `yes`.
|
||||
|
||||
If used as a submodule, update it with
|
||||
```bash
|
||||
$ git submodule update --init --recursive
|
||||
$ git submodule update --remote dotdrop
|
||||
```
|
||||
|
||||
You will then need to commit the changes with
|
||||
```bash
|
||||
$ git add dotdrop
|
||||
$ git commit -m 'update dotdrop'
|
||||
$ git push
|
||||
```
|
||||
|
||||
Or if installed through pypi:
|
||||
```bash
|
||||
$ pip3 install --user dotdrop --upgrade
|
||||
```
|
||||
|
||||
## Setup your repository
|
||||
|
||||
Either create a repository on your prefered platform and clone it or create one locally.
|
||||
This repository will contain two main elements, dotdrop's config file (`config.yaml`)
|
||||
@@ -167,7 +192,8 @@ For more info on the config file format, see [the config doc](https://github.com
|
||||
|
||||
Finally start using dotdrop with `dotdrop --help`. See the [usage doc](https://github.com/deadc0de6/dotdrop/wiki/usage) and [the example](https://github.com/deadc0de6/dotdrop/blob/master/README.md#getting-started).
|
||||
|
||||
# Shell completion
|
||||
## Shell completion
|
||||
|
||||
Completion scripts exist for `bash`, `zsh` and `fish`,
|
||||
see [the related doc](https://github.com/deadc0de6/dotdrop/blob/master/completion/README.md).
|
||||
|
||||
|
||||
@@ -1,8 +0,0 @@
|
||||
Beside the python dependencies defined in [requirements.txt](https://github.com/deadc0de6/dotdrop/blob/master/requirements.txt), dotdrop depends on following tools:
|
||||
* `file`
|
||||
* `diff`
|
||||
* `mkdir`
|
||||
* `git` (for the entry point script [dotdrop.sh](https://github.com/deadc0de6/dotdrop/blob/master/dotdrop.sh))
|
||||
* `readlink` or `realpath` (for the entry point script [dotdrop.sh](https://github.com/deadc0de6/dotdrop/blob/master/dotdrop.sh))
|
||||
|
||||
For MacOS users, make sure to install `realpath` (part of `coreutils`) through [homebrew](https://brew.sh/).
|
||||
36
docs/template/templating.md
vendored
36
docs/template/templating.md
vendored
@@ -4,21 +4,7 @@ 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 below sections for more information on how to template your dotfiles.
|
||||
|
||||
* [Delimiters](#delimiters)
|
||||
* [Template variables](#template-variables)
|
||||
* [Dotfile variables](#dotfile-variables)
|
||||
* [Environment variables](#environment-variables)
|
||||
* [Dotdrop header](#dotdrop-header)
|
||||
* [Available methods](#available-methods)
|
||||
* [Available filters](#available-filters)
|
||||
* [Import macros](#import-macros)
|
||||
* [Ignore empty template](#ignore-empty-template)
|
||||
* [Include file or template in template](#include-file-or-template-in-template)
|
||||
* [Debug templates](#debug-templates)
|
||||
|
||||
---
|
||||
|
||||
# Delimiters
|
||||
## Delimiters
|
||||
|
||||
Dotdrop uses different delimiters than
|
||||
[jinja2](http://jinja.pocoo.org/)'s defaults:
|
||||
@@ -32,7 +18,7 @@ Dotdrop uses different delimiters than
|
||||
|
||||
More info in [jinja2 templating doc](https://jinja.palletsprojects.com/en/2.11.x/templates/?highlight=delimiter)
|
||||
|
||||
# Template variables
|
||||
## Template variables
|
||||
|
||||
Following variables are available in templates:
|
||||
|
||||
@@ -46,7 +32,7 @@ Following variables are available in templates:
|
||||
* config variables (see [Variables](../config/config-variables.md)).
|
||||
* config interpreted variables (see [Interpreted variables](../config/config-variables.md)).
|
||||
|
||||
# Dotfile variables
|
||||
## Dotfile variables
|
||||
|
||||
When a dotfile is handled by dotdrop, the following variables are added:
|
||||
|
||||
@@ -65,7 +51,7 @@ For example a directory dotfile (like `~/.ssh`) would process several files
|
||||
* `_dotfile_abs_dst` would be `/home/user/.ssh`
|
||||
* `_dotfile_sub_abs_dst` would be `/home/user/.ssh/config`
|
||||
|
||||
# Environment variables
|
||||
## Environment variables
|
||||
|
||||
It's possible to access environment variables inside the templates.
|
||||
```
|
||||
@@ -97,7 +83,7 @@ alias dotdrop='eval $(grep -v "^#" ~/dotfiles/.env) /usr/bin/dotdrop --cfg=~/dot
|
||||
The above aliases load all the variables from `~/dotfiles/.env`
|
||||
(while omitting lines starting with `#`) before calling dotdrop.
|
||||
|
||||
# Dotdrop header
|
||||
## Dotdrop header
|
||||
|
||||
Dotdrop is able to insert a header in the generated dotfiles. This allows
|
||||
to remind anyone opening the file for editing that this file is managed by dotdrop.
|
||||
@@ -118,7 +104,7 @@ Either prepend the directive with the commenting char(s) used in the dotfile
|
||||
(for example `# {{@@ header() @@}}`) or provide it as an argument `{{@@ header('# ') @@}}`.
|
||||
The result is equivalent.
|
||||
|
||||
# Available methods
|
||||
## Available methods
|
||||
|
||||
Beside [jinja2 global functions](http://jinja.pocoo.org/docs/2.10/templates/#list-of-global-functions)
|
||||
the following methods can be used within the templates:
|
||||
@@ -173,7 +159,7 @@ this should exist
|
||||
{%@@ endif @@%}
|
||||
```
|
||||
|
||||
# Available filters
|
||||
## Available filters
|
||||
|
||||
Beside [jinja2 builtin filters](https://jinja.palletsprojects.com/en/2.10.x/templates/#builtin-filters)
|
||||
custom user-defined filter functions can be loaded using the config entry `filter_file`:
|
||||
@@ -200,7 +186,7 @@ dotfile content
|
||||
For more information on how to create filters,
|
||||
see [jinja2 official doc](https://jinja.palletsprojects.com/en/2.10.x/api/#writing-filters).
|
||||
|
||||
# Import macros
|
||||
## Import macros
|
||||
|
||||
Macros must be imported `with context` in order to have access to the variables:
|
||||
```
|
||||
@@ -209,7 +195,7 @@ Macros must be imported `with context` in order to have access to the variables:
|
||||
|
||||
For more see the [dedicated jinja2 doc](https://jinja.palletsprojects.com/en/2.11.x/templates/#macros).
|
||||
|
||||
# Ignore empty template
|
||||
## Ignore empty template
|
||||
|
||||
It is possible to avoid having an empty rendered template being
|
||||
deployed by setting the `ignoreempty` entry to *true*. This can be set
|
||||
@@ -217,7 +203,7 @@ globally for all dotfiles or only for specific dotfiles.
|
||||
|
||||
For more see the [Config](../config/config.md).
|
||||
|
||||
# Include file or template in template
|
||||
## Include file or template in template
|
||||
|
||||
[Jinja2](http://jinja.pocoo.org/docs/2.10/templates/) provides the ability to include an external file/template from within a template with the directive `include`. See the [related doc](http://jinja.pocoo.org/docs/2.10/templates/#include) for more. The path must be relative to the `dotpath`.
|
||||
|
||||
@@ -232,7 +218,7 @@ For example:
|
||||
{%@@ include colors_path + '/black.colors' @@%}
|
||||
```
|
||||
|
||||
# Debug templates
|
||||
## Debug templates
|
||||
|
||||
To debug the result of a template, one can install the dotfiles to a temporary
|
||||
directory with the `install` command and the `-t` switch:
|
||||
|
||||
@@ -2,38 +2,22 @@
|
||||
|
||||
Run `dotdrop --help` to see all available options.
|
||||
|
||||
* [Basic use](#basic-use)
|
||||
* Commands:
|
||||
* [Install dotfiles](#install-dotfiles)
|
||||
* [Compare dotfiles](#compare-dotfiles)
|
||||
* [Import dotfiles](#import-dotfiles)
|
||||
* [List profiles](#list-profiles)
|
||||
* [List dotfiles](#list-dotfiles)
|
||||
* [Update dotfiles](#update-dotfiles)
|
||||
* [Remove dotfiles](#remove-dotfiles)
|
||||
* Uses
|
||||
* [Use actions](config/usage-actions.md)
|
||||
* [Use transformations](config/usage-transformations.md)
|
||||
* [Update dotdrop](#update-dotdrop)
|
||||
* [Environment variables](#environment-variables)
|
||||
* [User tricks](#user-tricks)
|
||||
|
||||
---
|
||||
|
||||
# Basic use
|
||||
## Basic usage
|
||||
|
||||
The basic use of dotdrop is
|
||||
|
||||
* import a file/directory to manage (this will copy the files from the filesystem to your `dotpath`): `dotdrop import <somefile>`
|
||||
* install the dotfiles (will *copy/link* those from your `dotpath` to the filesystem): `dotdrop install`
|
||||
|
||||
Then if you happen to update the file/directory directly on the filesystem (add new file/dir, edit content, etc) you can use `update` to mirror back those changes in the `dotpath` of dotdrop.
|
||||
|
||||
For more advanced uses:
|
||||
|
||||
* See [this wiki](https://github.com/deadc0de6/dotdrop/wiki)
|
||||
* `dotdrop --help` for more options.
|
||||
* [the example](https://github.com/deadc0de6/dotdrop#getting-started)
|
||||
|
||||
# Install dotfiles
|
||||
## Install dotfiles
|
||||
|
||||
Simply run
|
||||
```bash
|
||||
@@ -49,7 +33,7 @@ For more detail, see the usage with `dotdrop --help`
|
||||
|
||||
To ignore specific pattern during installation see [the dedicated wiki page](config/ignore-pattern.md)
|
||||
|
||||
# Compare dotfiles
|
||||
## Compare dotfiles
|
||||
|
||||
Compare local dotfiles with the ones stored in dotdrop:
|
||||
```bash
|
||||
@@ -66,7 +50,7 @@ It is also possible to install all dotfiles for a specific profile
|
||||
in a temporary directory in order to manually compare them with
|
||||
the local version by using `install` and the `-t` switch.
|
||||
|
||||
# Import dotfiles
|
||||
## Import dotfiles
|
||||
|
||||
Dotdrop allows to import dotfiles directly from the
|
||||
filesystem. It will copy the dotfile and update the
|
||||
@@ -106,7 +90,7 @@ dotfiles management.
|
||||
$ dotdrop import ~/.zshrc --as=~/.zshrc.test
|
||||
```
|
||||
|
||||
# List profiles
|
||||
## List profiles
|
||||
|
||||
```bash
|
||||
$ dotdrop profiles
|
||||
@@ -119,7 +103,7 @@ else than the default (the hostname).
|
||||
The default profile can also be changed by defining the
|
||||
`DOTDROP_PROFILE` environment variable.
|
||||
|
||||
# List dotfiles
|
||||
## List dotfiles
|
||||
|
||||
The following command lists the different dotfiles
|
||||
configured for a specific profile:
|
||||
@@ -155,7 +139,7 @@ This is especially useful when the dotfile entry is a directory
|
||||
and one wants to have information on the different files (is it
|
||||
a templated file, etc).
|
||||
|
||||
# Update dotfiles
|
||||
## Update dotfiles
|
||||
|
||||
Dotfiles managed by dotdrop can be updated using the `update` command. When updating, only
|
||||
dotfiles that have differences with the stored version are updated.
|
||||
@@ -180,7 +164,7 @@ see [the dedicated wiki page](config/ignore-pattern.md)
|
||||
|
||||
There are two cases when updating a dotfile:
|
||||
|
||||
## The dotfile doesn't use [templating](template/templating.md)
|
||||
### The dotfile doesn't use [templating](template/templating.md)
|
||||
|
||||
The new version of the dotfile is copied to the *dotpath* directory and overwrites
|
||||
the old version. If git is used to version the dotfiles stored by dotdrop, the git command
|
||||
@@ -191,7 +175,7 @@ $ dotdrop update ~/.vimrc
|
||||
$ git diff
|
||||
```
|
||||
|
||||
## The dotfile uses [templating](template/templating.md)
|
||||
### The dotfile uses [templating](template/templating.md)
|
||||
|
||||
The dotfile must be manually updated, three solutions can be used to identify the
|
||||
changes to apply to the template:
|
||||
@@ -227,7 +211,7 @@ in the command line. For example for a dotfile having a key `f_zshrc` in the con
|
||||
$ dotdrop install -t f_zshrc
|
||||
```
|
||||
|
||||
# Remove dotfiles
|
||||
## Remove dotfiles
|
||||
|
||||
The command `remove` allows to stop managing a specific dotfile with
|
||||
dotdrop. It will:
|
||||
@@ -235,32 +219,7 @@ dotdrop. It will:
|
||||
* remove the entry in the config file (under `dotfiles` and `profile`)
|
||||
* remove the file from the `dotpath`
|
||||
|
||||
# Update dotdrop
|
||||
|
||||
If using dotdrop as a submodule, one can control if dotdrop
|
||||
is auto-updated through the [dotdrop.sh](https://github.com/deadc0de6/dotdrop/blob/master/dotdrop.sh)
|
||||
script by defining the environment variable `DOTDROP_AUTOUPDATE=yes`.
|
||||
If undefined, `DOTDROP_AUTOUPDATE` will take the value `yes`.
|
||||
|
||||
If used as a submodule, update it with
|
||||
```bash
|
||||
$ git submodule update --init --recursive
|
||||
$ git submodule update --remote dotdrop
|
||||
```
|
||||
|
||||
You will then need to commit the changes with
|
||||
```bash
|
||||
$ git add dotdrop
|
||||
$ git commit -m 'update dotdrop'
|
||||
$ git push
|
||||
```
|
||||
|
||||
Or if installed through pypi:
|
||||
```bash
|
||||
$ pip3 install --user dotdrop --upgrade
|
||||
```
|
||||
|
||||
# Environment variables
|
||||
## Environment variables
|
||||
|
||||
Following environment variables can be used to specify different CLI options.
|
||||
Note that CLI switches take precedence over environment variables (except for `DOTDROP_FORCE_NODEBUG`)
|
||||
@@ -285,20 +244,3 @@ export DOTDROP_DEBUG=
|
||||
```bash
|
||||
export DOTDROP_FORCE_NODEBUG=
|
||||
```
|
||||
|
||||
# User tricks
|
||||
|
||||
## Improve git integration
|
||||
|
||||
The below aliases can help with the process of updating your dotfiles between multiple hosts. Add those to your `~/.zshrc` or `~/.bashrc`. You can then simply run `dotsync` to push or pull from your dotfile repository.
|
||||
|
||||
```
|
||||
# Your dotdrop git repository location
|
||||
export DOTREPO="/path/to/your/dotdrop/repo"
|
||||
|
||||
alias dotdrop="$DOTREPO/dotdrop.sh"
|
||||
alias dotgit="git -C $DOTREPO"
|
||||
alias dotsync="dotgit pull && dotgit add -A && dotgit commit && dotgit push; dotdrop install"
|
||||
```
|
||||
|
||||
Provided by [ReekyMarko](https://github.com/ReekyMarko)
|
||||
|
||||
Reference in New Issue
Block a user