diff --git a/README.md b/README.md index 811265d..11032ff 100644 --- a/README.md +++ b/README.md @@ -14,42 +14,50 @@ addfav foobar cdf foobar ``` +**Auto-complete works with `cdf`:** It is sufficient to type the first letters of the name of a shortcut plus the Tab key. + ## Installation (UNIX/OSX only) -### Simple -1. Create a directory in your home directory, e.g. `~/myshortcuts`, either in the OSX Finder or a terminal window with `mkdir ~/myshortcuts`. (On OSX, it is better to put this somewhere under the `~/Documents` folder due to Apple's default permissions scheme.) -2. Depending on your system, open either `~/.bashrc` or `~/.bash_profile` with a text editor. You may need to turn on the display of hidden files (starting with a dot) in the OSX Finder with Command + Shift + .. -3. At the end of the `~/.bashrc` or `~/.bash_profile` file, insert the following lines: - ```bash - 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. +**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. -### Via Git +### Simple -1. Follow the steps 1 - 3 from above. -2. Clone this Github repository to a directory of your choice: +1. Download the tool from Github to your computer + - **Option 1:** With `git clone`: ```bash + mkdir some_directory cd some_directory git clone https://github.com/mfhepp/cdf.git + # Git will create a folder named cdf/ + cd cdf ``` - On OSX, it is strongly recommended to put this somewhere under the `~/Documents` folder due to Apple's default permissions scheme or to change the permissions of the directory manually via `chmod`. Otherwise, other users on the system could modify the executed script. -3. Go to the newly created directory and check that that it contains `cdf.sh`: + - **Option 2:** Download and extract ZIP from +2. Open a terminal window in the respective directory. +3. Run the install script `install.sh` ```bash - cd cdf - ls $PWD/*.sh + # Make it executable + chmod +x install.sh + # Run script + ./install.sh ``` - This will also show the absolute path of the file, like so: `/Users/myname/Documents/cdf/cdf.sh`. **Remember this path.** -4. In the `~/.bashrc` or `~/.bash_profile` file, insert the following lines **after the `export` command above**, with the actual path for `cdf.sh` on your computer (see step 3): +4. Open a new terminal window for the changes to take effect. + +### Manual + +1. Create a directory in your home directory, e.g. `~/myshortcuts`, either in the OSX Finder or a terminal window with + ```bash + mkdir ~/myshortcuts + ``` + On OSX, it is better to put this somewhere under the `~/Documents` folder due to Apple's default permissions scheme. +2. Depending on your system, open either `~/.bashrc` or `~/.bash_profile` with a text editor. You may need to turn on the display of hidden files (starting with a dot) in the OSX Finder with Command+Shift+. (dot). +3. At the end of the `~/.bashrc` or `~/.bash_profile` file, insert the following lines: ```bash - source /Users/myname/Documents/cdf/cdf.sh + export CDFPATH=~/myshortcuts ``` - Instead of `/Users/myname/...`, you can also write `~/` (like so: `~/Documents/cdf/cdf.sh`). `Documents/` is the location to where you cloned this repository. + 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. - ## Usage ### Adding the current directory to the list of shortcuts with `addfav` @@ -117,13 +125,13 @@ Example: ## Technical Details -The tool creates *symbolic links* to the bookmarked paths in the chosen directory. When running `cdf`, we simply execute `cd` to that symbolic link, if it exists. However, as we want to end up in the real path, it runs `cd $(realpath .)` at the very end to make sure we see the physical location and not that of the symbolic link. +The tool creates *symbolic links* pointing to the bookmarked paths in the chosen directory. When running `cdf`, we simply execute `cd` to that symbolic link, if it exists. However, as **we want to end up in the *real* path,** it runs `cd $(realpath .)` at the very end to make sure we see the physical location and not that of the symbolic link. It is possible to use the `CDPATH` variable for similar purposes, but this has several downsides. One could also change the behavior of the original `cd` command, but I think it is bad practice to mess around with core OS components in an intransparent way; hence the usage of a new `cdf` command. -The script tries to prevent you from creating shortcuts to locations that are themselves symbolic links. +The script tries to prevent you from creating shortcuts to locations that are themselves symbolic links. -## Warning! Be careful when deleting symbolic links! +## Serious Warning: Be CAREFUL when 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.** @@ -143,6 +151,8 @@ 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 The following aspects are not specific to this tool, but likely useful background information. @@ -170,12 +180,14 @@ Pictures/ This is because OSX, by default, grants at least read-access to all users on the given machine, via the `staff` usergroup. -If you use the `source` command to include the `cdf.sh` script within your `.bashrc` or `.bashprofile` 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. +If you were to use the `source` command to include the `cdf.sh` script within your `.bashrc` or `.bashprofile` 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 -This tool was inspired by the following article: +This tool was initially inspired by the following article: - -The proposed approach has the problem that you end up in the symbolic link directory, not the realpath thereof, which can be confusing and intransparent. +While the proposed approach works, it has a few limitations, namely that you end up in the symbolic link directory, not the physical `realpath` thereof, which can be confusing and intransparent. + +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.