<commit_before><commit_msg>Add README<commit_after># `go`

`go` is a smarter way to move between directories. It makes navigating across
branches of the file tree painless, especially to your most popular folders.
Combining classic `cd` behavior with user-defined shortcuts and inferences based
on historic choices means you'll (almost) always end up exactly where you want.

The three different methods that `go` uses to determine a destination directory,
are, in order of preference:

1. `cd` - If you just want to `cd` somewhere, `go` will follow the path
   appropriately.
2. Shortcuts - Custom shortcuts (symbolic links) stored in the ~/.go_links
   allow you to navigate to tricky places with minimal keystrokes.
3. Most Recent [Coming Soon] - Navigate to the most recent directory with the
   given name. This allows you to navigate _across_ the file system tree as
   easily as you move up and down it.

## Installation

Since `go` changes the current directory, it must be run as a bash _function_,
not as a bash program<a href="foot-1"><sup>1</sup></a>. This means that rather
than adding the executable to your path, you must define the `go` function. This
needs to occur in your `.bashrc`,`.bash_profile`, `.profile`, or whatever other
login file you choose to use. For most people, the following command will make
sure the function is loaded when you log in to your terminal:

```bash
echo ". $(pwd)/go" >> ~/.bashrc
```

## Usage

```bash
go [dest]
```

The `dest` given to `go` can be one of the following:

1. Nothing
    If no destination is given, `go` changes the current directory to the home
    directory (same as `cd`).
2. Pathname
    Both relative and absolute pathnames are accepted by `go`, and will be
    navigated to the same way that `cd` navigates to them.
3. Shortcut
    If a name does not resolve to an absolute or relative path, `go` will check
    if the name matches a shortcut. If a matching shortcut is found, the current
    directory is set to the directory the shortcut points to<a
    href="foot-2"><sup>2</sup></a>.

    If a shortcut is found, but the link is broken, the shortcut will be deleted
    to avoid future false positives.
4. Indirect Folder Name
    _Coming Soon!_

    When a name that cannot be evaluated as a relative path, absolute path, or
    shortcut is given, `go` will attempt to find a recent directory that was
    navigated to. Example:

    ```bash
    $ go 15410
    go: 15410: Directory not found.
    $ go ~/Documents/Courses/15410
    $ go ~
    $ go 1540 # Goes to ~/Documents/Courses/15410
    ```

## Saving Shortcuts

Shortcuts are stored in the form of [symbolic links](https://en.wikipedia.org/wiki/Symbolic_link#POSIX_and_Unix-like_operating_systems).
For now, `go` only looks for shortcuts in one directory. By default this
directory is `~/.go_shortcuts`, but it can be set by exporting a new
global `GO_SHORTCUT_DIR` in your `.bashrc` (or similar login file).

```bash
# Adding a shortcut
$ ln -s /Users/Scott/Documents/Courses/15410 ~/.go_shortcuts/os
$ go os # Goes to /Users/Scott/Documents/Courses/15410

# Removing a shortcut
$ rm ~/.go_shortcuts/os
```


## Replacing `cd`

It may be tempting to entirely replace `cd` with `go`. For yourself, this is
totally reasonable, but before aliasing away your old `cd` command, remember
that other programs may rely on its exact behavior.

I recommend typing `go` whenever you are navigating anywhere in the terminal,
and leaving the `cd` command as-is to ensure you don't screw up other programs.

If you use the [Go Language](https://golang.org), renaming or aliasing `go` is
a good idea. But in this case, it's still probably better to rename or alias it
to `goto` (or similar) rather than `cd`.

---

<a href="foot-1"><sup>1</sup></a> Typical command line programs execute in their
own process (forked from the main shell process). Executing a `cd` command
inside of such a forked process will not have an effect on the parent shell
process. Functions, on the other hand, are run as part of the current process,
hence `go` is defined as a function rather than a program.

<a href="foot-1"><sup>2</sup></a> This means that if a symbolic link in the
shortcut folder named `mylink` points to `/Users/Scott/Documents/Courses/15410`,
`go mylink` changes the current directory to
`/Users/Scott/Documents/Courses/15410` not `~/.go_shortcuts/mylink`. Going to
the directory that the symbolic link points to, instead of setting the symbolic
link to the current directory, keeps file paths cleaner.

{'fraction_non_alphanumeric': 0.08311229000884174, 'fraction_numerical': 0.013041556145004421, 'mean_word_length': 3.9024918743228603, 'pattern_counts': {'":': 0, '<': 19, '<?xml version=': 0, '>': 21, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4833725', 'n_tokens_mistral': 1380, 'n_tokens_neox': 1272, 'n_words': 661}