From 83ab6d947310cd38ef7080823b4e5da2a09ae586 Mon Sep 17 00:00:00 2001 From: Fred Cooke Date: Fri, 23 Apr 2021 11:47:53 +1200 Subject: [PATCH 1/6] Clarify the init instructions a bit. --- README.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 1694acb..61f67a1 100644 --- a/README.md +++ b/README.md @@ -40,7 +40,7 @@ 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 @@ -51,16 +51,18 @@ 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 ``` They will show as not cloned until you ```branchout pull``` If you want to clone when you add + ```branchout clone ``` ### Need to trust a certificate or ca bundle From e62dd2952c949df989b1bd2ad8885be8bfe49e1b Mon Sep 17 00:00:00 2001 From: Fred Cooke Date: Fri, 23 Apr 2021 12:05:34 +1200 Subject: [PATCH 2/6] Add documentation for the optional setup parameters commonly found in the Branchoutfile. --- README.md | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 61f67a1..73ed06e 100644 --- a/README.md +++ b/README.md @@ -45,7 +45,7 @@ brew install branchout 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 @@ -71,6 +71,25 @@ If you have a corporate CA bundle that you need to trust just add it at ` Date: Fri, 23 Apr 2021 12:09:22 +1200 Subject: [PATCH 3/6] Correct use of single and triple back ticks for quoting short strings and multiline code blocks. Triple must start and end on its own lines before and after the block. Single is usually used inline in the middle of text. It is an error to use triple inline in text and the local syntax highlighting reflects that. --- README.md | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 73ed06e..04575a8 100644 --- a/README.md +++ b/README.md @@ -57,13 +57,17 @@ The default branchout name is the name of the root project, but can be overridde You can now add projects -```branchout add ``` +``` +branchout add +``` -They will show as not cloned until you ```branchout pull``` +They will show as not cloned until you `branchout pull` If you want to clone when you add -```branchout clone ``` +``` +branchout clone +``` ### Need to trust a certificate or ca bundle @@ -77,7 +81,9 @@ branchout-yarn will configure the environment so that yarn can trust certificate 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``` +``` +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. @@ -85,7 +91,9 @@ to the Branchoutfile and you'll get whatever the next hyphen-separated part is u 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``` +``` +BRANCHOUT_NAME=shorter-name +``` to the Branchoutfile and ideally use the same value as the optionalDirName during branchout init. @@ -105,7 +113,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 From 8699728beb5a9a66ce4a1d8ead8fc24231fe6516 Mon Sep 17 00:00:00 2001 From: Fred Cooke Date: Fri, 23 Apr 2021 12:31:41 +1200 Subject: [PATCH 4/6] WIP: Flesh out a section on modifying default branchout behaviour, which may or may not be possible at this time. Intent is for Mike to add commits on top of this one to fill gaps and correct things and for me to rebase -i clean it up once we're where we need to be. Please don't amend this and force push. --- README.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/README.md b/README.md index 04575a8..bf72103 100644 --- a/README.md +++ b/README.md @@ -97,6 +97,24 @@ 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_BASE}/.branchoutrc +``` +#### 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 From 8750fce065b212b28529dfe4dc4e26ef7c0c88ba Mon Sep 17 00:00:00 2001 From: Fred Cooke Date: Fri, 23 Apr 2021 16:03:39 +1200 Subject: [PATCH 5/6] WIP eventual squash add some likely false assertions about the config file layering and remove question mark from branchoutrc and replace capital B with b and correct var name for the other branchoutrc and comment on that. --- README.md | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index bf72103..936c0f1 100644 --- a/README.md +++ b/README.md @@ -105,9 +105,21 @@ Another might be that you already have a tree with your code and you want to kee In cases like these you can use the following two files to ???? ``` -~/.config/Branchoutrc? -${BRANCHOUT_BASE}/.branchoutrc +~/.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 From 9f1dd8d9fa3168c27ba5e3aafa2584f9414f99ab Mon Sep 17 00:00:00 2001 From: Fred Cooke Date: Fri, 23 Apr 2021 16:04:20 +1200 Subject: [PATCH 6/6] WIP Add draft glossary markdown document to be discussed/completed and modified as necessary to suit any changes made. --- GLOSSARY.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 GLOSSARY.md diff --git a/GLOSSARY.md b/GLOSSARY.md new file mode 100644 index 0000000..efcb0e8 --- /dev/null +++ b/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. ? + +