github.com/StackExchange/blackbox/v2@v2.0.1-0.20220331193400-d84e904973ab/docs/backwards-compatibility.md (about)

     1  Backwards Compatibility
     2  =======================
     3  
     4  # Where is the configuration stored? .blackbox vs. keyrings/live
     5  
     6  Blackbox stores its configuration data in the `.blackbox` subdirectory.  Older
     7  repos use `keyrings/live`.  For backwards compatibility either will work.
     8  
     9  All documentation refers to `.blackbox`.
    10  
    11  You can convert an old repo by simply renaming the directory:
    12  
    13  ```
    14  mv keyrings/live .blackbox
    15  rmdir keyrings
    16  ```
    17  
    18  There is no technical reason to convert old repos except that it is less
    19  confusing to users.
    20  
    21  This change was made in commit 60e782a0, release v1.20180615.
    22  
    23  
    24  # How blackbox fines the config directory:
    25  
    26  ## Creating the repo:
    27  
    28  `blackbox init` creates the config directory in the root
    29  of the repo.  Here's how it picks the name:
    30  
    31  - If `$BLACKBOX_TEAM` is set, `.blackbox-$BLACKBOX_TEAM` is used.
    32  - If the flag `--team <teamname>` is set, it uses `.blackbox-<teamname>`
    33  - Otherwise, it uses `.blackbox`
    34  
    35  When searching for the configuration directory, the following
    36  locations are checked. First match wins.
    37  
    38  - `.blackbox-$BLACKBOX_TEAM` (only if `$BLACKBOX_TEAM` is set)
    39  - The value of `--config value` (if the flag is set)
    40  - `$BLACKBOX_CONFIGDIR` (the preferred env. variable to use)
    41  - `$BLACKBOXDATA` (for backwards compatibility with v1)
    42  - `.blackbox`
    43  - `keyrings/live` (for backwards compatibility)
    44  
    45  NOTE: The env variables and `--config` should be set to the full path
    46  to the config directory (i.e.: `/Users/tom/gitstuff/myrepo/.blackbox`).
    47  If it is set to a relative directory (i.e. `.blackbox` or
    48  `../myrepo/.blackbox`) most commands will break.
    49  
    50  NOTE: Why the change from `$BLACKBOXDATA` to `$BLACKBOX_CONFIGDIR`?  We want
    51  all the env. variables to begin with the prefix `BLACKBOX_`.  If v1
    52  supported another name, that is still supported. If you are starting
    53  with v2 and have no other users using v1, please use the `BLACKBOX_`
    54  prefix.
    55