Docs and customised paths

GLOSSARY.md

@@ -0,0 +1,23 @@
+# Terms and Variables Defined
+
+## Terms defined and orhan terms
+
+- `BRANCHOUT_NAME` - The common name for both the meta project directory and cache/settings directory for a given project.
+- `BRANCHOUT_FILE` - The file name in the meta repo with the basic setup of the project tree, such as the above. Can be called either `Branchoutfile` or `.branchout`.
+- `BRANCHOUT_PROJECTS` - The file name in the meta repo where the project names are listed in raw form with prefix (if any) and group. Can be called either `Branchoutprojects` or `.projects`.
+- `BRANCHOUT_STATE` ? - **TODO** This one is the settings/cache dir specific to current meta project? Is the name appropriate? To me state of a set of repos is git status run across all of them, not maven settings and repo cache.
+- `PROJECTION_DIRECTORY` ? - **TODO** This one stands out like a sore thumb - rename to `BRANCHOUT_PROJECTION_DIR`?
+- `BRANCHOUT_PROJECTS_DIRECTORY` ? - **TODO** sub directory under home under which branchout meta projects live - needs to be independent of ${HOME}
+- `BRANCHOUT_STATES_DIRECTORY` ? - **TODO** doesn't yet exist, equivalent to the above, but for the settings/caches directory structure for each meta project.
+- `BRANCHOUT_GIT_BASEURL` - The prefix for all git repos included in a particular branchout meta project. Derived, but can be overriden in case the base project differs from the rest (unlikely).
+- `BRANCHOUT_PATH` - The path under which the `branchout` script lives and under which it knows it can find its siblings in order to explicitly call them rather than relying on them being on the path (which breaks if the script is called with a direct call and isn't on the path).
+
+## Definitions needing a home above
+
+1. The root directory where branchout meta projects live side by side with each other. Where the branchout init process places new meta projects in folders called `BRANCHOUT_NAME`.
+2. The root directory where branchout places project-specific folders called `${BRANCHOUT_NAME}` side by side with settings and cache directories for different tooling nested beneath.
+3. ?
+4. ?
+5. ?
+
+

README.md

@@ -40,35 +40,94 @@ brew tap Branchout/homebrew-branchout
 brew install branchout
 ```
 
-### Initialise an existing organisation
+### Initialise an existing or new organisation
 
 To start with an existing project just init it from the git url
 
 ```
-branchout init https://github.com/Branchout/branchout-reactor.git
+branchout init https://github.com/Branchout/branchout-reactor.git [optionalDirName]
 cd ~/project/branchout-reactor
 branchout status
 branchout pull
 ```
 
-This will create the Branchoutfile and Branchoutprojects if needed
+This will create the Branchoutfile and Branchoutprojects if needed, for example if the repo is new/empty and you're setting it up for the first time.
 
-The default branchout name is the name of the root project
+The default branchout name is the name of the root project, but can be overridden.
 
 You can now add projects
-```branchout add <project-name>```
 
-They will show as not cloned until you ```branchout pull```
+```
+branchout add <project-name>
+```
+
+They will show as not cloned until you `branchout pull`
 
 If you want to clone when you add 
-```branchout clone <project-name>```
+
+```
+branchout clone <project-name>
+```
 
 ### Need to trust a certificate or ca bundle
 
 If you have a corporate CA bundle that you need to trust just add it at `<metarepo>/.branchout/cacerts`
 
 branchout-yarn will configure the environment so that yarn can trust certificates in or signed by certificates in cacarts
 
+### Common config in Branchoutfile
+
+#### Repo name prefixes
+
+If in your git structure your repos are all commonly prefixed with the same thing, and you'd like that to be ignored by Branchout as a prefix, then add:
+
+```
+BRANCHOUT_PREFIX=prefix-without-trailing-hyphen
+```
+
+to the Branchoutfile and you'll get whatever the next hyphen-separated part is used as the group for directory layout.
+
+#### Branchout name override
+
+In case of your branchout repository having a long name that you don't want as part of the two branchout paths, you can override by adding:
+
+```
+BRANCHOUT_NAME=shorter-name
+```
+
+to the Branchoutfile and ideally use the same value as the optionalDirName during branchout init.
+
+### Personal customisation
+
+Sometimes the branchout defaults don't work for a particular scenario even though they do work for most of your colleagues.
+One example is that the `${HOME}` places the two root directories on a very slow network drive.
+Another might be that you already have a tree with your code and you want to keep it all together.
+In cases like these you can use the following two files to ????
+
+```
+~/.config/branchoutrc
+${BRANCHOUT_STATE}/.branchoutrc - Can the decision to make this a dot file be reversed? What was behind that? Seems like the sort of thing you'd want to wave a flag at you, not hide ready to bite.
+```
+
+#### PROBABLY NOT TRUE:
+
+Branchout settings have an override hierarchy as follows:
+
+- Built in defaults and behaviours in scripts are the first layer intended to minimise config by convention
+- `Branchoutfile` is read next and all values used from here over the built-in ones
+- `~/.config/branchoutrc` is read next and any values here are used over either of the two sources above
+- `${BRANCHOUT_STATE}/.branchoutrc` is read next and is the final project-specific personal override possible
+
+Branchout then goes about performing its normal duties on the basis of this layered configuration approach.
+
+#### Moving the branchout projects base dir
+
+To set the root of where branchout initialises branchout repos do XXX
+
+#### Moving the branchout caching base dir
+
+To set the root of where branchout stores project specific caches and settings/credentials do YYY
+
 ## Grokking the code and contributing
 
 
@@ -84,7 +143,7 @@ brew install git bats-core shellcheck
 
 The tests are written in bats https://github.com/bats-core/bats-core
 
-Note, the ```sstephenson/bats``` repository is unmaintained, bats-core is what you want.
+Note, the `sstephenson/bats` repository is unmaintained, bats-core is what you want.
 
 ```
 make test