From 7445b0116f83bdcf841672d7aa40b8c5b0b7602e Mon Sep 17 00:00:00 2001 From: mfhepp Date: Sun, 28 Jan 2024 16:12:04 +0100 Subject: [PATCH] improved README --- README.md | 53 ++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 36 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index a76c301..a1d38c8 100644 --- a/README.md +++ b/README.md @@ -24,11 +24,16 @@ cdf papers # Your are now here: ~/the/windy/road/to/my/many/papers ``` -**Auto-complete works with `cdf`:** It is sufficient to type the first letters of the name of a shortcut plus the Tab key. +## Features -## Installation (UNIX/OSX only) +- **Simple and lightweight:** `cdf` adds just two new commands: + - `addfav` ("add to favorites") + - `cdf` ("`cd` to favorite") +- You can use any **short and memorable name** for your shortcuts, like `pet` or `thesis` (or even `p73`). +- Supports **auto-complete:** Just type the first few letters and hit the Tab key. +- All **shortcuts can also be used in** a GUI tool like **Apple Finder,** because they are simple symbolic links. -**Note:** Always backup your `~/.bashrc` or `~/.bash_profile` files prior to installing this tool. If not, please do not blame me if things go wrong. +## Installation (UNIX/OSX only) ### Simple @@ -38,21 +43,22 @@ cdf papers mkdir some_directory cd some_directory git clone https://github.com/mfhepp/cdf.git - # Git will create a folder named cdf/ cd cdf ``` - **Option 2:** Download and extract ZIP from 2. Open a terminal window in the respective directory. 3. Run the install script `install.sh` ```bash - # Make it executable - chmod +x install.sh # Run script ./install.sh ``` + Normally, the install script should be executable as it stands. If not, run + ```bash + chmod +x install.sh + ``` 4. Open a new terminal window for the changes to take effect. -### Manual +### Manual installation 1. Create a directory in your home directory, e.g. `~/myshortcuts`, either in the OSX Finder or a terminal window with ```bash @@ -65,8 +71,10 @@ cdf papers export CDFPATH=~/myshortcuts ``` Replace `~/myshortcuts` with the absolute path of your chosen directory for the shortcuts (e.g. `~/Documents/myshortcuts`; note that `~/` is a shortcut for your user directory on Unix systems; you can also use the full path.). **Save the file, but keep it open.** -4. After these lines, insert the entire contents from the `cdf.sh` file from this repository. **Save and close the `~/.bashrc` or `~/.bash_profile` file.** -5. Open a new terminal window or run `source ~/.bashrc` or `source ~/.bash_profile` in open terminal window to activate the changes. +4. After these lines, insert the entire contents [from the `cdf.sh` file from this repository](https://raw.githubusercontent.com/mfhepp/cdf/main/cdf.sh). You can directly copy-and-paste it from the link. **Save and close the `~/.bashrc` or `~/.bash_profile` file.** +5. Open a new terminal window for the changes to take effect. + +**Note:** Always backup your `~/.bashrc` or `~/.bash_profile` files prior to installing this tool. If not, please do not blame me if things go wrong. The install script tries to create backups automatically. ## Usage @@ -109,7 +117,7 @@ Existing directory shortcuts are: You can also use `addfav --list` for the same purpose. -## Command-Line Arguments +## Command-line arguments ```bash CDF: Change to a directory via a shortcut from CDFPATH @@ -133,7 +141,7 @@ Example: addfav --list: List all available shortcuts ``` -## Technical Details +## Technical details The tool creates *symbolic links* pointing to the bookmarked paths in the chosen directory. When running `cdf`, we simply obtain the **physical path** with `realpath` (available on most modern systems) and the `cd` to that path, if it exists. Hence, **we end up in the *real physical location and not that of the symbolic link*.** @@ -141,7 +149,9 @@ It is possible to use the `CDPATH` variable for similar purposes, but this has s The script tries to prevent you from creating shortcuts to locations that are themselves symbolic links. -## Serious Warning: Be CAREFUL when DELETING symbolic links! +## Warning: Be CAREFUL when DELETING symbolic links! + +**IMPORTANT:** Read this if you want to delete shortcuts from the shortcuts folder! When unsure, **use** a GUI tool like the **OSX Finder for deleting symbolic links.** This tool uses [symbolic links](https://en.wikipedia.org/wiki/Symbolic_link). While this an established part of any Unix-like environment, things can go terribly wrong **when deleting symbolic links**. In the **worst case, you can delete ALL CONTENTS of the target of a symbolic link** when you are **trying to delete the symbolic link.** @@ -161,11 +171,9 @@ rm -r bar/ rm -r bar ``` -**Recommendation:** When unsure, **use** a GUI tool like the **OSX Finder for deleting symbolic links.** - This warning is mostly relevant when you are trying to remove previously created symbolic links in the respective folder. -## Security +## Security considerations The following aspects are not specific to this tool, but likely useful background information. @@ -194,7 +202,7 @@ This is because OSX, by default, grants at least read-access to all users on the If you were to use the `source` command to include the `cdf.sh` script within your `.bashrc` or `.bash_profile` file, you must make sure that the respective directory cannot be written to by other users. Otherwise, someone could inject arbitrary Bash commands into your environment. **This is why the install script instead *copies the contents of that script* to your Bash profile.** -## Credits and Acknowledgments +## Credits and acknowledgments This tool was initially inspired by the following article: @@ -205,7 +213,7 @@ While the proposed approach works, it has a few limitations, namely that you end ChatGPT 4 was a great buddy and time-saver, helping me through the many pitfalls of Bash as the grand, old lady of scripting languages. -## Similar Projects +## Similar projects There are several other very popular tools for similar purposes, e.g. @@ -228,6 +236,17 @@ Main differences between `cdf` and most of these are as follows: - `cdf` **uses a simple folder with symbolic links** for managing the names and target locations of shortcuts. - `cdf` **supports arbitrary names for any target path** that are **easy to remember.** You can use **very short names for your most popular directories;** like a simple form of [entropy coding](https://en.wikipedia.org/wiki/Entropy_coding). +## Disclaimer + +This project and all Web resources are a non-commercial community contribution. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. ## Contact