Debian Codegraph @

docs/installation.md

raw
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).