From c4dab40c360caaf0ee7c0948e2e40420643919e4 Mon Sep 17 00:00:00 2001 From: deadc0de6 Date: Fri, 27 May 2022 11:51:39 +0200 Subject: [PATCH] refactor installation doc --- README.md | 49 +++---------------------------- docs/howto/symlink-dotfiles.md | 4 +-- docs/howto/system-config-files.md | 8 ++--- docs/installation.md | 26 +++++++++------- 4 files changed, 26 insertions(+), 61 deletions(-) diff --git a/README.md b/README.md index 379cfff..6fbf621 100644 --- a/README.md +++ b/README.md @@ -55,6 +55,7 @@ for more. Quick start: ```bash +## using dotdrop as a submodule mkdir dotfiles && cd dotfiles git init git submodule add https://github.com/deadc0de6/dotdrop.git @@ -86,16 +87,9 @@ why [dotdrop](https://github.com/deadc0de6/dotdrop) rocks. # Installation -There are multiple ways to install and use dotdrop. -It is recommended to install dotdrop [as a submodule](#as-a-submodule) -to your dotfiles Git tree. Having dotdrop as a submodule guarantees that anywhere -you are cloning your dotfiles Git tree from you'll have dotdrop shipped with it. +See the [installation instructions](https://dotdrop.readthedocs.io/en/latest/installation/). -The below instructions show how to install dotdrop as a submodule. For alternative -installation instructions, see the -[installation documentation](https://dotdrop.readthedocs.io/en/latest/installation/). - -Dotdrop is also available on: +Dotdrop is available on: * PyPI: https://pypi.org/project/dotdrop/ * Homebrew: https://formulae.brew.sh/formula/dotdrop @@ -104,46 +98,11 @@ Dotdrop is also available on: * Snapcraft: https://snapcraft.io/dotdrop * pacstall: https://github.com/pacstall/pacstall-programs/blob/master/packages/dotdrop/dotdrop.pacscript -## As a submodule - -The following will create a git repository for your dotfiles and -keep dotdrop as a submodule: -```bash -## create the repository -$ mkdir dotfiles; cd dotfiles -$ git init - -## install dotdrop as a submodule -$ git submodule add https://github.com/deadc0de6/dotdrop.git -$ pip3 install -r dotdrop/requirements.txt --user -$ ./dotdrop/bootstrap.sh - -## use dotdrop -$ ./dotdrop.sh --help -``` - -For macOS users, make sure to install `realpath` through Homebrew -(part of *coreutils*). - -Using dotdrop as a submodule will require you to work with dotdrop by -using the generated script `dotdrop.sh` at the root -of your dotfiles repository. Note that this script updates the submodule -automatically unless called with the environment variable `DOTDROP_AUTOUPDATE` -set to `no`. - -To ease the use of dotdrop, it is recommended to add an alias to it in your -shell (*~/.bashrc*, *~/.zshrc*, etc.) with the config file path, for example: -``` -alias dotdrop=' --cfg=' -``` - -Completion scripts exist for `bash`, `zsh` and `fish`; see [the related doc](completion/README.md). - # Getting started [Create a new repository](https://dotdrop.readthedocs.io/en/latest/repository-setup/) to store your dotfiles with dotdrop. *Init* or *clone* that new repository and -[install dotdrop](https://dotdrop.readthedocs.io/en/latest/installation/#as-a-submodule). +[install dotdrop](https://dotdrop.readthedocs.io/en/latest/installation). Then import any dotfiles (files or directories) you want to manage with dotdrop. You can either use the default profile (which resolves to the *hostname* of the host diff --git a/docs/howto/symlink-dotfiles.md b/docs/howto/symlink-dotfiles.md index f155c8b..0e17beb 100644 --- a/docs/howto/symlink-dotfiles.md +++ b/docs/howto/symlink-dotfiles.md @@ -24,7 +24,7 @@ and [link_on_import](https://dotdrop.readthedocs.io/en/latest/config-format/#con Import the file: ```bash -$ ./dotdrop.sh import ~/.bashrc +$ dotdrop import ~/.bashrc -> "/home/user/.bashrc" imported ``` @@ -39,7 +39,7 @@ dotfiles: Install the dotfile, which will remove your `~/.bashrc` and replace it with a link to the file stored in dotdrop: ```bash -$ ./dotdrop.sh install +$ dotdrop install Remove "/home/user/.bashrc" for link creation? [y/N] ? y -> linked /home/user/.bashrc to /home/user/dotdrop/dotfiles/bashrc diff --git a/docs/howto/system-config-files.md b/docs/howto/system-config-files.md index b9e8e20..0290af1 100644 --- a/docs/howto/system-config-files.md +++ b/docs/howto/system-config-files.md @@ -15,15 +15,15 @@ For example: `config-user.yaml` is used when managing the user's dotfiles: ```bash ## user config file is config-user.yaml -$ ./dotdrop.sh import --cfg config-user.yaml -$ ./dotdrop.sh install --cfg config-user.yaml +$ dotdrop import --cfg config-user.yaml +$ dotdrop install --cfg config-user.yaml ... ``` `config-root.yaml` is used when managing the system's dotfiles and is to be used with `sudo` or directly by the root user: ```bash ## root config file is config-root.yaml -$ sudo ./dotdrop.sh import --cfg=config-root.yaml -$ sudo ./dotdrop.sh install --cfg=config-root.yaml +$ sudo dotdrop import --cfg=config-root.yaml +$ sudo dotdrop install --cfg=config-root.yaml ... ``` diff --git a/docs/installation.md b/docs/installation.md index 40d2915..342af13 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -1,16 +1,20 @@ # Installation -Installing dotdrop [as a submodule](#as-a-submodule) is the recommended way. - -If you want to keep your Python environment clean, use the virtualenv installation instructions -(see [As a submodule in a virtualenv](#as-a-submodule-in-a-virtualenv) and -[PyPI package in a virtualenv](#pypi-package-in-a-virtualenv)). -In that case, the virtualenv environment might need to be loaded before any attempt to use dotdrop. +* PyPI: https://pypi.org/project/dotdrop/ +* Homebrew: https://formulae.brew.sh/formula/dotdrop +* AUR (stable): https://aur.archlinux.org/packages/dotdrop/ +* AUR (git version): https://aur.archlinux.org/packages/dotdrop-git/ +* Snapcraft: https://snapcraft.io/dotdrop +* pacstall: https://github.com/pacstall/pacstall-programs/blob/master/packages/dotdrop/dotdrop.pacscript ## As a submodule +Having dotdrop as a submodule guarantees that anywhere +you are cloning your dotfiles Git tree from you will have dotdrop shipped with it. +Note that when using dotdrop as a submodule you will be tracking the master branch (and not a specific version) + The following will create a Git repository for your dotfiles and -keep dotdrop as a submodule: +keep dotdrop as a submodule. ```bash ## create the repository $ mkdir dotfiles; cd dotfiles @@ -28,9 +32,11 @@ $ ./dotdrop.sh --help For macOS users, make sure to install `realpath` through Homebrew (part of *coreutils*). -Using this solution will require you to work with dotdrop by +Using dotdrop as a submodule will require you to work with dotdrop by using the generated script `dotdrop.sh` at the root -of your dotfiles repository. +of your dotfiles repository. Note that this script updates the submodule +automatically unless called with the environment variable `DOTDROP_AUTOUPDATE` +set to `no`. To ease the use of dotdrop, it is recommended to add an alias to it in your shell with the config file path; for example: @@ -170,7 +176,7 @@ $ git clone https://github.com/deadc0de6/dotdrop.git ``` Start using it directly through the `dotdrop.sh` script and -use the `--cfg` to make it point to your config file. +use the `--cfg` switch to make it point to your config file. ```bash $ cd dotdrop/