Add README.md.

1 files changed, 52 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f447c92
--- /dev/null
+++ b/README.md
@@ -0,0 +1,52 @@
+## What is this?
+
+`cdlog` is a small amount of GNU Bash code that provides a better
+interactive experience for directory changes than
+Bash's built-in directory stack mechanism (commands `pushd`, `popd`
+and `dirs`, plus `~-` expansion).
+
+## How to use
+
+Install the file `cdlog.sh` somewhere, and source it from your
+`.bashrc` script.
+
+The user interface consists of three commands:
+
+* `cd` is now an alias which calls the function `cdlog.chdir`.
+Every time you change directory, it pushes the previous directory
+into a FIFO log. The log maintains nine entries. The ninth entry
+is erased. The entries are stored in the variables `c1` through `c9`.
+The first four entries are also copied into the variables `x`, `y`,
+`z` and `w` for shorter access.
+
+* `cs` (cd swap) is an alias for a command which changes back to the most
+recent directory in the log as if by using `cd "$c1"` or `cd "$x"`.
+This triggers a special swapping behavior in `cdlog.chdir`; see below.
+
+* `pd` (pop dir) is an alias for a command which changes to the most recent
+directory in the log, and removes that entry from the log. The second
+most recent directory becomes most recent and so on.
+
+* `cdlog` shows a listing of the four most recent entries in the
+log.
+
+In addition, the `cdlog.sh` script sets the bash `direxpand` option.
+With the `direxpand` option, Tab completion on a directory coming
+from a variable name will expand that variable into the command line.
+
+The directory changing commands do nothing if you attempt to change into the
+same directory you are already in. There is no effect on the FIFO.
+
+The internal function `cdlog.chdir` has a special behavior.
+If you change to the directory that is currently in `c1`,
+a swap is performed. Rather than pushing a new entry into the `cdlog` FIFO,
+the most recent entry is replaced with the previous directory
+that you are coming from. For instance if the current directory
+is `/etc` and `c1` holds `/var`, then `cdlog.chdir /var` 
+will change to `/var` and just replace `c1` with `/etc`, without rotating
+through the FIFO entries `c2` through `c9`.
+
+## License
+
+This is under distributed under a modified two-clause BSD license.
+See the license block at the bottom of the `cdlog.sh` file.