proj/README.md

# proj

## Usage

Invoke the script and pass the name of the project as its only non-flag argument:

```bash
proj learncpp
```

If the project exists in your project directory, it will spawn a subshell in that directory. Advanced usage and hooks are detailed below, but you can use it as a glorified `cd` if that's all you need.

## Behavior

When invoked as specified in usage (with any number of valid flags plus exactly one non-flag argument referred to here as `$arg1`), `proj` will do the following:

* Check for the existence of `project_dir`

  * If `project_dir` is a directory or symbolic link, proceed

  * If `project_dir` is any other type of file, panic

  * If `project_dir` does not exist, create it

* `cd` to `project_dir` (normally `~/Projects`)

* Check for the existence of `$arg1`

  * If `$arg1` is a directory or symbolic link, proceed

  * If `$arg1` is any other type of file, panic

  * If `$arg1` does not exist, then:

    * Execute the pre-create hook if configured to do so

    * Create `$arg1` as a directory

    * Initialize an empty git repository if configured to do so

    * Add and commit a `.gitignore` if configured to do so

* `cd` to `$arg1`

* Execute a subshell, and

  * Source `.projenv` if configured to do so

  * Execute `$SHELL`

## Flags

flag|description|args
---|---|---
-c|Path to a config file to load in place of the default (`~/.config/proj.conf`)|Path to config file
-h|Print basic help text|

## Configuration

value|description|default
---|---|---
git\_auto\_init|If not set to `0`, automatically initialize a git repository on project creation|`0`
git\_auto\_init\_gitignore|A colon-separated ($PATH-style) list of items to include in the initial `.gitignore`|`*.swp`
hook\_pre\_create|Path to a script invoked (not sourced) before a project is created. Script will be executed relative to `project_dir`|Empty string
hook\_pre\_spawn|Path to a script invoked (not sourced) before a shell is spawned in the project directory. Script will be executed relative to the project's root directory|Empty string
hook\_env|Path to a script to *source in* after entering a project directory but before a shell is spawned. Script will be sourced relative to the project's root directory|`.projenv`
project\_dir|Path to where projects should be stored.|`$HOME/Projects`

## Return Codes

code|description
---|---
0|Success
2|Invalid flag or missing flag argument
50|Non-flag arguments have errors or are nonsensical