| 1 |
# Installation |
| 2 |
|
| 3 |
* [As a submodule](#as-a-submodule) |
| 4 |
* [As a submodule in a virtualenv](#as-a-submodule-in-a-virtualenv) |
| 5 |
* [Submodule upgrade/downgrade](#submodule-upgradedowngrade) |
| 6 |
* [PyPI package](#pypi-package) |
| 7 |
- [pipx install](#pipx-install) |
| 8 |
* [Homebrew package](#homebrew-package) |
| 9 |
* [Debian unstable (sid)](#debian) |
| 10 |
* [Ubuntu](#ubuntu) |
| 11 |
* [AUR packages](#aur-packages) |
| 12 |
* [Snap package](#snap-package) |
| 13 |
* [From source](#from-source) |
| 14 |
* [Pacstall package](https://github.com/pacstall/pacstall-programs/blob/master/packages/dotdrop/dotdrop.pacscript) |
| 15 |
|
| 16 |
## As a submodule |
| 17 |
|
| 18 |
Having dotdrop as a submodule guarantees that anywhere |
| 19 |
you are cloning your dotfiles Git tree from you will have dotdrop shipped with it. |
| 20 |
Note that when using dotdrop as a submodule you will be tracking the master branch (and not a specific version) |
| 21 |
|
| 22 |
The following will create a Git repository for your dotfiles and |
| 23 |
keep dotdrop as a submodule. |
| 24 |
```bash |
| 25 |
## create the repository |
| 26 |
$ mkdir dotfiles; cd dotfiles |
| 27 |
$ git init |
| 28 |
|
| 29 |
## install dotdrop as a submodule |
| 30 |
$ git submodule add https://github.com/deadc0de6/dotdrop.git |
| 31 |
$ pip3 install --user -r dotdrop/requirements.txt |
| 32 |
$ ./dotdrop/bootstrap.sh |
| 33 |
|
| 34 |
## use dotdrop |
| 35 |
$ ./dotdrop.sh --help |
| 36 |
``` |
| 37 |
|
| 38 |
For macOS users, make sure to install `realpath` through Homebrew |
| 39 |
(part of *coreutils*) and `libmagic`. |
| 40 |
|
| 41 |
Using dotdrop as a submodule will require you to work with dotdrop by |
| 42 |
using the generated script `dotdrop.sh` at the root |
| 43 |
of your dotfiles repository. Note that this script updates the submodule |
| 44 |
automatically unless called with the environment variable `DOTDROP_AUTOUPDATE` |
| 45 |
set to `no`. |
| 46 |
|
| 47 |
If you happened to encounter `ModuleNotFoundError` error after an |
| 48 |
update, it means the dependencies have changed and you should re-install |
| 49 |
dependencies with |
| 50 |
```bash |
| 51 |
pip3 install --user -r dotdrop/requirements.txt |
| 52 |
``` |
| 53 |
|
| 54 |
To ease the use of dotdrop, it is recommended to add an alias to it in your |
| 55 |
shell with the config file path; for example: |
| 56 |
``` |
| 57 |
alias dotdrop=<absolute-path-to-dotdrop.sh> --cfg=<path-to-your-config.yaml>' |
| 58 |
``` |
| 59 |
|
| 60 |
## As a submodule in a virtualenv |
| 61 |
|
| 62 |
To install it in a [virtualenv](https://virtualenv.pypa.io): |
| 63 |
```bash |
| 64 |
## create the repository |
| 65 |
$ mkdir dotfiles; cd dotfiles |
| 66 |
$ git init |
| 67 |
|
| 68 |
## install dotdrop as a submodule |
| 69 |
$ git submodule add https://github.com/deadc0de6/dotdrop.git |
| 70 |
$ virtualenv -p python3 env |
| 71 |
$ echo 'env' >> .gitignore |
| 72 |
$ env/bin/pip install -r dotdrop/requirements.txt |
| 73 |
$ ./dotdrop/bootstrap.sh |
| 74 |
|
| 75 |
# add the following in your .bashrc/.zshrc/etc |
| 76 |
# or hardcode it in the dotdrop.sh script |
| 77 |
$ export DOTDROP_VIRTUALENV=env |
| 78 |
|
| 79 |
## use dotdrop |
| 80 |
$ ./dotdrop.sh --help |
| 81 |
``` |
| 82 |
|
| 83 |
When using a virtualenv, make sure to export the `DOTDROP_VIRTUALENV` |
| 84 |
variable with the directory name of your virtualenv: |
| 85 |
```bash |
| 86 |
$ export DOTDROP_VIRTUALENV=env |
| 87 |
$ ./dotdrop.sh --help |
| 88 |
``` |
| 89 |
|
| 90 |
Then follow the instructions under [As a submodule](#as-a-submodule). |
| 91 |
|
| 92 |
## Submodule upgrade/downgrade |
| 93 |
|
| 94 |
### Upgrade dotdrop submodule |
| 95 |
|
| 96 |
If using dotdrop as a submodule, one can control if dotdrop |
| 97 |
is auto-updated through the [dotdrop.sh](https://github.com/deadc0de6/dotdrop/blob/master/dotdrop.sh) |
| 98 |
script by defining the environment variable `DOTDROP_AUTOUPDATE=yes`. |
| 99 |
If undefined, `DOTDROP_AUTOUPDATE` will take the value `yes`. |
| 100 |
|
| 101 |
If used as a submodule, update it with: |
| 102 |
```bash |
| 103 |
$ git submodule update --init --recursive |
| 104 |
$ git submodule update --remote dotdrop |
| 105 |
|
| 106 |
## install dependencies |
| 107 |
$ pip3 install --user -r dotdrop/requirements.txt |
| 108 |
``` |
| 109 |
|
| 110 |
You will then need to commit the changes with: |
| 111 |
```bash |
| 112 |
$ git add dotdrop |
| 113 |
$ git commit -m 'update dotdrop' |
| 114 |
$ git push |
| 115 |
``` |
| 116 |
|
| 117 |
### Downgrade dotdrop submodule |
| 118 |
|
| 119 |
If you wish to get a specific version of dotdrop when using |
| 120 |
it as a submodule, the following operations can be done. |
| 121 |
|
| 122 |
Here dotdrop is downgraded to the latest stable version: |
| 123 |
```bash |
| 124 |
## enter the repository containing the dotdrop submodule |
| 125 |
$ cd my-dotfiles |
| 126 |
## enter the dotdrop submodule |
| 127 |
$ cd dotdrop |
| 128 |
## update the list of tags |
| 129 |
$ git fetch --tags |
| 130 |
## checkout the latest stable version |
| 131 |
$ git checkout `git tag -l | tail -1` |
| 132 |
``` |
| 133 |
|
| 134 |
If using the `dotdrop.sh` script, make sure it doesn't |
| 135 |
automatically update dotdrop back to the latest commit. |
| 136 |
|
| 137 |
## PyPI package |
| 138 |
|
| 139 |
[PyPI package](https://pypi.org/project/dotdrop/) |
| 140 |
|
| 141 |
Install dotdrop: |
| 142 |
```bash |
| 143 |
$ pip3 install dotdrop --user |
| 144 |
``` |
| 145 |
|
| 146 |
### PyPI package in a virtualenv |
| 147 |
|
| 148 |
Install dotdrop from PyPI in a virtualenv: |
| 149 |
```bash |
| 150 |
$ virtualenv -p python3 env |
| 151 |
$ source env/bin/activate |
| 152 |
$ pip install dotdrop |
| 153 |
``` |
| 154 |
|
| 155 |
When using a virtualenv, make sure to source the environment |
| 156 |
before using dotdrop: |
| 157 |
```bash |
| 158 |
$ source env/bin/activate |
| 159 |
$ dotdrop --help |
| 160 |
``` |
| 161 |
|
| 162 |
Then follow the instructions under [PyPI package](#pypi-package). |
| 163 |
|
| 164 |
## pipx install |
| 165 |
|
| 166 |
[pipx](https://pipx.pypa.io/) allows to install a package in an isolated |
| 167 |
environment. |
| 168 |
|
| 169 |
It is packaged in all main Linux distributions, and macOS. |
| 170 |
|
| 171 |
### PyPI package with pipx |
| 172 |
|
| 173 |
To install the last PyPI package: |
| 174 |
```bash |
| 175 |
$ pipx install dotdrop |
| 176 |
``` |
| 177 |
|
| 178 |
To upgrade an installed package to the last version. |
| 179 |
```bash |
| 180 |
$ pipx upgrade dotdrop |
| 181 |
``` |
| 182 |
|
| 183 |
### From GitHub with pipx |
| 184 |
|
| 185 |
To install the from the master branch on GitHub |
| 186 |
|
| 187 |
```bash |
| 188 |
$ pipx install git+https://github.com/deadc0de6/dotdrop.git |
| 189 |
``` |
| 190 |
|
| 191 |
You can choose a branch or commit |
| 192 |
```bash |
| 193 |
$ pipx install git+https://github.com/deadc0de6/dotdrop.git@2c462c3 |
| 194 |
``` |
| 195 |
|
| 196 |
## Homebrew package |
| 197 |
|
| 198 |
[Homebrew package](https://formulae.brew.sh/formula/dotdrop) |
| 199 |
|
| 200 |
Install dotdrop from Homebrew with: |
| 201 |
```bash |
| 202 |
$ brew install dotdrop |
| 203 |
``` |
| 204 |
|
| 205 |
## Debian |
| 206 |
|
| 207 |
dotdrop is a |
| 208 |
[Debian package](https://packages.debian.org/dotdrop) since bookworm (Debian 12), be |
| 209 |
warned that the Debian version is usually behind the last stable release. |
| 210 |
|
| 211 |
Install dotdrop |
| 212 |
```bash |
| 213 |
$ sudo apt install dotdrop |
| 214 |
``` |
| 215 |
|
| 216 |
## Ubuntu |
| 217 |
|
| 218 |
[Ubuntu package](https://packages.ubuntu.com/search?keywords=dotdrop) |
| 219 |
|
| 220 |
Install dotdrop |
| 221 |
```bash |
| 222 |
$ sudo apt install dotdrop |
| 223 |
``` |
| 224 |
|
| 225 |
## Aur packages |
| 226 |
|
| 227 |
Dotdrop is available on aur: |
| 228 |
|
| 229 |
* Stable: <https://aur.archlinux.org/packages/dotdrop/> |
| 230 |
* Git version: <https://aur.archlinux.org/packages/dotdrop-git/> |
| 231 |
|
| 232 |
## Snap package |
| 233 |
|
| 234 |
Dotdrop is available as a snap package: <https://snapcraft.io/dotdrop>. |
| 235 |
|
| 236 |
Install it with: |
| 237 |
```bash |
| 238 |
$ snap install dotdrop |
| 239 |
``` |
| 240 |
|
| 241 |
If you encounter warnings like `Warning: using regular magic file`, |
| 242 |
try defining the following environment variable: |
| 243 |
```bash |
| 244 |
export MAGIC=$SNAP/usr/share/file/magic.mgc |
| 245 |
``` |
| 246 |
|
| 247 |
## From source |
| 248 |
|
| 249 |
Clone the repository: |
| 250 |
```bash |
| 251 |
$ git clone https://github.com/deadc0de6/dotdrop.git |
| 252 |
``` |
| 253 |
|
| 254 |
Start using it directly through the `dotdrop.sh` script and |
| 255 |
use the `--cfg` switch to make it point to your config file. |
| 256 |
|
| 257 |
```bash |
| 258 |
$ cd dotdrop/ |
| 259 |
$ ./dotdrop.sh --cfg <my-config-file> files |
| 260 |
``` |
| 261 |
|
| 262 |
## Dependencies |
| 263 |
|
| 264 |
Beside the Python dependencies defined in [requirements.txt](https://github.com/deadc0de6/dotdrop/blob/master/requirements.txt), |
| 265 |
dotdrop depends on the following tools: |
| 266 |
|
| 267 |
* `diff` (unless a different tool is used, see [diff_command](config/config-config.md#config-block)) |
| 268 |
* `git` (only if using the entry point script [dotdrop.sh](https://github.com/deadc0de6/dotdrop/blob/master/dotdrop.sh)) |
| 269 |
|
| 270 |
For macOS users, make sure to install the below packages through [Homebrew](https://brew.sh/): |
| 271 |
|
| 272 |
* [libmagic](https://formulae.brew.sh/formula/libmagic) (for python-magic) |
| 273 |
|
| 274 |
For WSL (Windows Subsystem for Linux), make sure to install `python-magic-bin`: |
| 275 |
```bash |
| 276 |
pip install python-magic-bin |
| 277 |
``` |
| 278 |
|
| 279 |
## Shell completion |
| 280 |
|
| 281 |
Completion scripts exist for `bash`, `zsh` and `fish`; |
| 282 |
see [the related doc](https://github.com/deadc0de6/dotdrop/blob/master/completion/README.md). |
| 283 |
|
| 284 |
## Highlighters |
| 285 |
|
| 286 |
Highlighters for dotdrop templates are available [here](https://github.com/deadc0de6/dotdrop/tree/master/highlighters). |