commit 91794386a544d493db59cc4af53baa89eae10189
parent 5e91c9b86a973b285e2f4e1834e8952f4b1acab1
Author: GeaRSiX <gearsix@tuta.io>
Date: Mon, 20 Apr 2020 17:17:17 +0100
updated readme
Diffstat:
| M | README.md | | | 103 | ++++++++++++++++++++++++++++++++++++++++++++++--------------------------------- |
1 file changed, 60 insertions(+), 43 deletions(-)
diff --git a/README.md b/README.md
@@ -13,86 +13,90 @@ a **really** simple dot file manager.
## overview
This is a really simple python script I wrote to manage dotfiles. I had a brief look at a few and decided I'd just make my own.
-It doesn't do anything complicated, but there's an array near the top of the file (_DOTFILE_LOCATIONS_) that informs _dotfm_ where to install recognised files to. The downside to this tool is that dot files I don't use will need to be manually added to this array by yourself. I'll be adding to it overtime, but feel free to modify it yourself.
-
---
## usage
-Make sure to check DOTFILE_LOCATIONS first.
+There's an array near the top of the file (`DOTFILE_LOCATIONS`) that informs _dotfm_ of alias names for calling a dotfile and where to install that dotfile. Feel free to modify this array to your liking.
### cheatsheet
-**Note:** For the following example, DOTFILE_LOCATIONS has the following element:<br/>
-`['bashrc', '/home/{}/.bashrc'.format(USER)]`
+**Note:** For the following examples, _$DOTFILES_ will be used to address the src folder dotfiles are stored in.
-- **Install** a dot file: `dotfm install $DOTFILES/bashrc` (will **ln -s** _$DOTFILES/bashrc_ -> _~/.bashrc_)
-- **Uninstall** a dot file: `dotfm remove bashrc` (will **rm** _~/.bashrc_)
-- **Edit** a dot file: `dotfm edit bashrc` (will open _.bashrc_ in _$EDITOR_ or _nano_)
+- **Install** a dotfile: `dotfm install $DOTFILES/bashrc` (will **ln -s** _$DOTFILES/bashrc_ -> _~/.bashrc_)
+- **Uninstall** a dotfile: `dotfm remove bashrc` (will **rm** _~/.bashrc_)
+- **Edit** a dotfile: `dotfm edit bashrc` (will open _.bashrc_ in _$EDITOR_ or _nano_)
- **Install all** your dotfiles: `dotfm install-all $DOTFILES` (runs **dotfm install** on all files in _$DOTFILES_)
+- **List** your dotfm dotfile aliases and their location: `dotfm list $DOTFILE`
### details
-#### DOTFILE_LOCATIONS
-_DOTFILE_LOCATIONS_ is a multi-dimensional array near the top of _src/dotfm.py_ (under _GLOBALS_). Think of this array as your _config file_.
+#### DOTFILE\_LOCATIONS
+
+_DOTFILE\_LOCATIONS_ is a multi-dimensional array near the top of _src/dotfm.py_ (under _GLOBALS_). Think of this array as your _config file_ for now.
**It's important this array has the correct values for dotfm to work.**
-Each element of it is an array with _two values_: `['dotfile_name', 'dotfile_install_path']`
+Each element of it is an array with _two values_: `[['dotfile_alias', ...], 'dotfile_install_path']`
-- **dotfile_name** = Filename of the dotfile to install (should match the dotfile's name in your dotfile repo)
-- **dotfile_install_path** = Filepath of where the dotfile should install to (include filename, e.g. _`/home/{}/.bashrc'.format(USER)_)
+- **[dotfile\_alias, ...]** = An array of names you'd like to use to call this dotfile (at least one value should match the dotfile's name in your $DOTFILE repo)
+- **dotfile\_install\_path** = Filepath of where the dotfile should install to (include filename, e.g. `'/home/{}/.bashrc'.format(USER)`)
-#### _dotfm install DOTFILE\_NAME_
-_DOTFILE_ should be a **path** to the **dotfile to install**.
-
-If the file name of _DOTFILE_ is recognised, it will make sure the directory to install the dotfile to exists and then create a symbolic link at that location to _DOTFILE_.
+#### dotfm install DOTFILE\_PATH
+_DOTFILE_ should be **path** of the **dotfile to install**.
+**If the base name of _DOTFILE_ is recognised**, _dotfm_ will make sure the directory to install the dotfile to exists and then create a symbolic link at that location to _DOTFILE_.
If a file already exists at the install location, you'll get a prompt asking whether you want to:
-- _\[o\]verwrite_ = move the existing file to __(existing file location).bak_ and continue with creating the symbolic link
-- _\[c\]ompare_ = print out a _diff_ of the two files
+
+- _\[o\]verwrite_ = move the existing file to _(existing file location).bak_ and force create the symbolic link
+- _\[c\]ompare_ = print out a _diff_ of the two files and return to these options
- _\[a\]bort_ = abort the installation
-If _DOTFILE_ isn't found in _DOTFILE\_LOCATIONS_, then you'll have to manually add it. This is simple though, just go modify _src/dotfm.py_ and add an element to the array. Make sure to re-install too.
+**If the base name of _DOTFILE_ isn't found** in the alias lists in _DOTFILE\_LOCATIONS_, then the install will abort. You'll have to manually add your dotfile to _DOTFILE_LOCATIONS_ or modify it's aliases to include yours. Make sure to re-install afterwards.
-#### _dotfm remove DOTFILE\_NAME_
+#### dotfm remove DOTFILE\_NAME
_DOTFILE_ should be the **name** of the **dotfile to remove**.
**WARNING!** This will _rm_ the file named _DOTFILE_ from it's install location (found in _DOTFILE\_LOCATIONS_).
-#### _dotfm edit DOTFILE\_NAME_
+_This is a destructive function and you will **permenantly lose the file**._ This should be fine in most cases if you installed the file with _dotfm_ as it will only rm the symlink to your source dotfile, It's always best to make sure you check though.
+
+#### dotfm edit DOTFILE\_NAME
_DOTFILE_ should be the **name** of the **dotfile to edit**.
-This will open the _DOTFILE_ in the editor named in your environment variables as _EDITOR_. If _EDITOR_ is not available as an environment varialbe, then it will open it in _nano_.
+This will open the _DOTFILE_ in the editor set in your environment variables as _EDITOR_. If _EDITOR_ is not set, then it will open it in _nano_.
The file opened is located at the matching install location found in _DOTFILE\_LOCATIONS_.
-#### _dotfm install-all DOTFILE\_DIR_
-_DOTFILE_DIR_ should be a **directory path** containing all the **dotfiles to install**
+#### dotfm install-all DOTFILE\_DIR
+_DOTFILE_DIR_ should be a **directory path** containing the source files of all the **dotfiles to install**
This will recursively run _dotfm install DOTFILE_ on each file found in the specified directory.
-### help
-
-```
-usage: dotfm [-h] [-d] [-v] COMMAND DOTFILE
+#### _dotfm list DOTFILE\_NAME_
+Useful if you've forgotten the alias names of your dotfiles or if you've forgotten where they're kept.
-a simple tool to help you manage your dot files, see "man dotfm" for more
+_DOTFILE\_NAME_ can be **all** to **list all known** dotfiles, otherwise it should be the **name** of the **dotfile to list**.
-positional arguments:
- COMMAND the dotfm COMMAND to execute: ['install', 'remove', 'edit',
- 'install-all']
- DOTFILE name of the dotfile dotfm will execute COMMAND on, for
- "install" this must be a path to the dotfile to install
+### help
-optional arguments:
- -h, --help show this help message and exit
- -d, --debug display debug logs
- -v, --version show program's version number and exit
-```
+ usage: dotfm [-h] [-d] [-v] COMMAND DOTFILE
+
+ a simple tool to help you manage your dot files, see "man dotfm" for more
+
+ positional arguments:
+ COMMAND the dotfm COMMAND to execute: ['install', 'remove', 'edit',
+ 'install-all', 'list']
+ DOTFILE name of the dotfile dotfm will execute COMMAND on, for
+ "install" this must be a path to the dotfile to install
+
+ optional arguments:
+ -h, --help show this help message and exit
+ -d, --debug display debug logs
+ -v, --version show program's version number and exit
---
## installing dotfm
-- If you **do** plan on modifying _DOTFILE\_LOCATIONS_ after install _dotfm_ (recommended): `sudo make link`
-- If you **don't** plan on modifying _DOTFILE\_LOCATIONS_ after installing _dotfm_: `sudo make install`
+- If you **do** plan on modifying _DOTFILE\_LOCATIONS_ after install _dotfm_ (recommended): `sudo make link`. This will install the script as a symlink.
+- If you **don't** plan on modifying _DOTFILE\_LOCATIONS_ after installing _dotfm_: `sudo make install`. This will copy the script.
### install location
By default this will install the python script to _/usr/bin/local/dotfm_.
@@ -102,7 +106,20 @@ To change this, just modify _Makefile_ and change the value of _DESTDIR_ to your
---
## uninstall dotfm
-Just run `sudo make uninstall`
+Just run `sudo make uninstall` while in the same directory as the _Makefile_.
+
+---
+
+## TODO
+Development on this project isn't a massive priority for me. Currently things are getting added as I need them.
+
+- Change `DOTFILE_LOCATIONS` to use an external config
+- Allow a remote git repo to be used for calling dotfile source
+- Add a double-check to _dotfm remove_
+- Follow symlinks to list source file locations too
+- Commands:
+ - <s>List dotfile locations</s>
+ - Create a dotfile
---
