Replace occurrences of definition file with branch layout file ac…

…ross the docs and code

.circleci/config.yml

@@ -357,8 +357,4 @@ workflows:
             - build and upload deb package to ppa
             - publish snap to the stable channel
 
-      # Note: there are also releases happening outside of our CI:
-      # 1) every time a commit is pushed to `develop` or `master`, a build for docs (`latest` or `stable` version, respectively)
-      #    is triggered automatically via GitHub webhook on https://readthedocs.org/projects/git-machete/builds/,
-      # 2) every time a https://github.com/r-ryantm bot runs on NixOS/nixpkgs repository,
-      #    Nix git-machete package is updated with the fresh version/package hash according to the data from PyPI.
+      # Note: there are also releases happening outside of our CI, see PACKAGES.md

RELEASE_NOTES.md

@@ -2,7 +2,8 @@
 
 ## New in git-machete 3.17.9
 
-- improved: documentation at ReadTheDocs
+- improved: layout of documentation at ReadTheDocs
+- improved: replaced `definition file` with `branch layout file` across the docs
 
 ## New in git-machete 3.17.8
 

blogs/git-machete-1/blog.md

@@ -50,7 +50,7 @@ Okey, let's get our hands dirty... first install `git-machete` with the sequence
 
 Once you have `git-machete` in your executable `PATH` (and thus git already recognizes the `machete` subcommand), let's specify how you would like to organize your branches — basically, what depends on what.
 Run `git machete edit` or simply open the `.git/machete` file with your favorite editor.
-Paste the following "branch tree" definition:
+Paste the following branch layout:
 ```
 develop
     adjust-reads-prec
@@ -147,7 +147,7 @@ Of course you'll still need to sync `edit-margin-not-allowed`, `full-load-gatlin
 As the cherry on top, let's now assume that you need to merge the `change-table` branch to `develop` as soon as possible
 and you can't wait for `adjust-reads-prec` and `block-cancel-order` to get merged first.
 Unfortunately, the two mentioned upstream branches introduced some nice helpers that you later used in `change-table`.
-To make the process as painless as possible, let's modify the definition file with `git machete edit`:
+To make the process as painless as possible, let's modify the branch layout file with `git machete edit`:
 
 ```
 develop
@@ -164,7 +164,7 @@ master
 
 ![git machete status](status-l-3.png)
 
-When you modified the definition file, `git machete status` marked the edge between `develop` and `change-table` as yellow.
+When you modified the branch layout file, `git machete status` marked the edge between `develop` and `change-table` as yellow.
 This means that the downstream branch (`change-table`) is still in sync with the upstream (`develop`), but the upstream branch tip isn't the fork point of the downstream branch.
 Translating from _git-ese_ to English, there are probably commits from some other branches on the way between `develop` and `change-table`;
 this is exactly the case now (there are indeed commits originating on `adjust-reads-prec` and `block-cancel-order`).
@@ -190,8 +190,8 @@ This will compare the current working directory to the fork point commit of the
 You can also provide a branch parameter (`git machete diff <branch>`) to see the diff of the given branch against its fork point.
 
 `git machete add [--onto=<target-upstream>] [<branch>]` adds the specified branch (or the current one, if skipped) onto the given target upstream branch.
-The same effect can also be achieved by editing the definition file `.git/machete` manually e.g. with `git machete edit`.
-For example, if you run `git branch ignore-whitespace` and then `git machete add --onto=block-cancel-order ignore-whitespace`, you'll end up with the following definition file:
+The same effect can also be achieved by editing the branch layout file `.git/machete` manually e.g. with `git machete edit`.
+For example, if you run `git branch ignore-whitespace` and then `git machete add --onto=block-cancel-order ignore-whitespace`, you'll end up with the following branch layout file:
 
 ```
 develop
@@ -247,5 +247,5 @@ Anyway, the potentially undesired effects of `git machete` failing to find a cor
 
 More git-savvy users may argue that it should be enough to simply use the `--fork-point` option of `git rebase`, but the reality turns out to be harder than that.
 `git merge-base --fork-point` (and thus `git rebase` with the said option) only takes the reflog of the one provided upstream branch into account.
-This works fine as long as nobody disturbs the structure of the tree in the definition file (i.e. the upstream branch of any branch doesn't change).
+This works fine as long as nobody disturbs the structure of the tree in the branch layout file (i.e. the upstream branch of any branch doesn't change).
 Unfortunately, as mentioned before in this post, such tree structure modifications happen pretty often in real-life development, therefore a custom, more powerful way to find the fork point was necessary.

blogs/git-machete-2/blog.md

@@ -24,7 +24,7 @@ This will serve as a dummy remote for the repo under `~/machete-sandbox`.
 More specifically, the script runs `git remote add origin ~/machete-sandbox-remote` from `~/machete-sandbox` directory
 so as to establish an actual local/remote relation between the repos, with similar push/pull capabilities that are available over HTTPS or SSH.
 
-The initial structure of branches in the demo (i.e., the contents of the `.git/machete` definition file, excluding custom annotations that will be covered soon) is as follows:
+The initial structure of branches in the demo (i.e., the contents of the `.git/machete` branch layout file, excluding custom annotations that will be covered soon) is as follows:
 
 ```
 develop
@@ -86,7 +86,7 @@ actually repeats pretty often in a daily work with `git machete`, especially whe
 To free yourself from thinking about what to check out/rebase/push next, you can turn to `git machete traverse` —
 a wizard that walks (or rather, traverses) the branch dependency tree and suggests what needs to be done to restore sync of branches with their parent branches and remotes.
 
-Let's check out the `develop` branch (which is listed first in the definition file) and then iterate through the branches.
+Let's check out the `develop` branch (which is listed first in the branch layout file) and then iterate through the branches.
 
 ![git machete traverse](traverse.png)
 
@@ -131,7 +131,7 @@ The stderr output warns that `drop-constraint` isn't present in `.git/machete` a
 If you take a look at the `sandbox-setup-2.sh`, `drop-constraint` was indeed originally checked out from `call-ws`, even though the branches are no longer in commit-wise sync.
 Analogically, the `go up` subcommand checked out the inferred upstream.
 
-Note that if `drop-constraint` was tracked in `.git/machete`, then the whole inference wouldn't happen since git machete would instead simply go for the upstream explicitly provided by the user in the definition file.
+Note that if `drop-constraint` was tracked in `.git/machete`, then the whole inference wouldn't happen since git machete would instead simply go for the upstream explicitly provided by the user in the branch layout file.
 Also, the inference doesn't happen for any other `show`/`go` direction (like `down` or `next`) since that behavior could be pretty confusing and generally of little practical use.
 
 ### `update`
@@ -140,7 +140,7 @@ Let's check out `drop-constraint` back again and, without changing anything in `
 
 ![git machete update](update-3.png)
 
-`update` couldn't find an entry for `drop-constraint` in the definition file, so it fell back to automatic inference.
+`update` couldn't find an entry for `drop-constraint` in the branch layout file, so it fell back to automatic inference.
 
 ### `add`
 
@@ -160,7 +160,7 @@ For demonstration purposes, let's now remove the `.git/machete` file (so as to m
 ![git machete discover](discover.png)
 
 `discover` gives the choice to either accept the discovered tree right away with `y[es]`, `e[dit]` it first, or reject it with `n[o]`.
-In the case of `yes`/`edit`, the old definition file (if it already exists) will be saved under `.git/machete~` (note the added tilde).
+In the case of `yes`/`edit`, the old branch layout file (if it already exists) will be saved under `.git/machete~` (note the added tilde).
 
 Under the hood, `discover` simply performed upstream inference (just as for `show up` etc.) for every single local branch independently,
 while applying some tricks (inspired by the [disjoint-set data structure](https://en.wikipedia.org/wiki/Disjoint-set_data_structure)) to make sure no cycles appear in the created graph.
@@ -169,7 +169,7 @@ The only thing that obviously could not be inferred were custom annotations.
 Also, if the tree structure has been changed in the meantime (so that e.g. `develop` became a child of `call-ws` instead of the inverse), `discover` can't be expected to exactly guess the changed structure.
 The inference is based on git reflogs and doesn't know anything about the current or previous state of the `.git/machete` file.
 
-At this point one can ask a question: why then is the definition file even needed since the upstreams could be always inferred on the fly?
+At this point one can ask a question: why then is the branch layout file even needed since the upstreams could be always inferred on the fly?
 The argument against such an approach is that it wouldn't be desirable if everything in the tool happened automagically/behind the scenes.
 The developer should keep a sensible amount of control while still being provided with some hints when they're in doubt.
 It seems much more reasonable than the inverse — inferring everything that's possible and only asking the human when the tool is in doubt.

blogs/git-machete-2/sandbox-setup-2.sh

@@ -51,7 +51,7 @@ newb call-ws
   cmt Call web service
   cmt 1st round of fixes
   push
-newb drop-constraint # not added to definition file
+newb drop-constraint # not added to branch layout file
   cmt Drop unneeded SQL constraints
 git checkout call-ws
   cmt 2nd round of fixes

completion/git-machete.completion.zsh

@@ -160,14 +160,14 @@ __git_machete_cmds=(
   'advance:Fast-forward the current branch to match one of its downstreams and subsequently slide out this downstream'
   'anno:Manage custom annotations'
   'clean:Delete untracked and unmanaged branches and optionally check out open GitHub PRs'
-  'delete-unmanaged:Delete local branches that are not present in the definition file'
+  'delete-unmanaged:Delete local branches that are not present in the branch layout file'
   {diff,d}':Diff current working directory or a given branch against its fork point'
   'discover:Automatically discover tree of branch dependencies'
-  {edit,e}':Edit the definition file'
-  'file:Display the location of the definition file'
+  {edit,e}':Edit the branch layout file'
+  'file:Display the location of the branch layout file'
   'fork-point:Display hash of the fork point commit of a branch'
   {go,g}':Check out the branch relative to the position of the current branch'
-  'github:Creates, checks out and manages GitHub PRs while keeping them reflected in branch definition file'
+  'github:Creates, checks out and manages GitHub PRs while keeping them reflected in branch layout file'
   'help:Display this overview, or detailed help for a specified command'
   'is-managed:Check if the current branch is managed by git-machete (mostly for scripts)'
   'list:List all branches that fall into one of pre-defined categories (mostly for internal use)'
@@ -191,7 +191,7 @@ __git_machete_help_topics() {
   set -A topics ${__git_machete_cmds}
   topics+=(
     'config:Docs for the configuration keys and environment variables'
-    'format:Format of the .git/machete definition file'
+    'format:Format of the .git/machete branch layout file'
     'hooks:Display docs for the extra hooks added by git machete'
   )
   _describe -t topics 'git machete help topic' topics "$@"
@@ -278,12 +278,12 @@ __git_machete_categories() {
   local categories
   # TODO (#115): complete slidable-after's argument
   categories=(
-    'addable:all branches (local or remote) than can be added to the definition file'
+    'addable:all branches (local or remote) than can be added to the branch layout file'
     'childless:all branches that do not possess child branches'
-    'managed:all branches that appear in the definition file'
+    'managed:all branches that appear in the branch layout file'
     'slidable:all managed branches that have exactly one upstream and one downstream (i.e. the ones that can be slid out with slide-out command)'
     'slidable-after:the downstream branch of the given branch, if it exists and is its only downstream (i.e. the one that can be slid out immediately following <branch>)'
-    'unmanaged:all local branches that do not appear in the definition file'
+    'unmanaged:all local branches that do not appear in the branch layout file'
     'with-overridden-fork-point:all local branches that have a fork point override config'
   )
   _describe -t categories 'category' categories "$@"