Improve doc formatting

docs/generate-sphinx-man.sh

@@ -6,6 +6,3 @@ target_dir=$1
 
 # `-t man` is needed for the conditionally rendered sections
 sphinx-build -W --keep-going -b man -t man docs/source "$target_dir"
-
-# To view the generated file, use
-#   groff -man -Tascii < docs/man/git-machete.1 | less -r

docs/man/git-machete.1

@@ -41,15 +41,11 @@ Using this tool, you can maintain \fBsmall, focused, easy\-to\-review pull reque
 .sp
 A look at a \fBgit machete status\fP gives an instant answer to the questions:
 .INDENT 0.0
-.INDENT 3.5
-.INDENT 0.0
 .IP \(bu 2
 What branches are in this repository?
 .IP \(bu 2
 What is going to be merged (rebased/pushed/pulled) and to what?
 .UNINDENT
-.UNINDENT
-.UNINDENT
 .sp
 \fBgit machete traverse\fP semi\-automatically traverses the branches, helping you effortlessly rebase, merge, push and pull.
 .sp
@@ -117,6 +113,20 @@ git machete commands and help topics:
 .IP \(bu 2
 \fI\%version\fP          \-\- Display the version and exit
 .UNINDENT
+.INDENT 0.0
+.TP
+.B  \-\-debug
+Log detailed diagnostic info, including outputs of the executed git commands.
+.TP
+.B  \-h\fP,\fB  \-\-help
+Print help and exit.
+.TP
+.B  \-v\fP,\fB  \-\-verbose
+Log the executed git commands.
+.TP
+.B  \-\-version
+Print version and exit.
+.UNINDENT
 .SH ADD
 .sp
 \fBUsage:\fP
@@ -134,16 +144,12 @@ git machete add [\-o|\-\-onto=<target\-upstream\-branch>] [\-R|\-\-as\-root] [\-
 Adds the provided <branch> (or the current branch, if none specified) to the branch layout file.
 If <branch> is provided but no local branch with the given name exists:
 .INDENT 0.0
-.INDENT 3.5
-.INDENT 0.0
 .IP \(bu 2
 if a remote branch of the same name exists in exactly one remote,
 then user is asked whether to check out this branch locally (as in \fBgit checkout\fP),
 .IP \(bu 2
 otherwise, user is asked whether it should be created as a new local branch.
 .UNINDENT
-.UNINDENT
-.UNINDENT
 .sp
 If the branch layout file is empty or \fB\-R/\-\-as\-root\fP is provided, the branch will be added as a root of the tree of branch dependencies.
 Otherwise, the desired upstream (parent) branch can be specified with \fB\-o/\-\-onto\fP\&.
@@ -189,8 +195,6 @@ and subsequently slides out \fBD\fP\&. All three steps require manual confirmati
 .sp
 The downstream \fBD\fP is selected according to the following criteria:
 .INDENT 0.0
-.INDENT 3.5
-.INDENT 0.0
 .IP \(bu 2
 if \fBC\fP has exactly one downstream (child) branch \fBd\fP connected with a green edge (see help for \fI\%status\fP) to \fBC\fP
 or is overridden, then \fBd\fP is selected as \fBD\fP,
@@ -201,8 +205,6 @@ if \fBC\fP has more than one downstream branch connected with a green edge to \f
 then user is asked to pick the branch to fast\-forward merge into (similarly to what happens in \fBgit machete go down\fP).
 If \fB\-\-yes\fP is specified, then \fBadvance\fP fails.
 .UNINDENT
-.UNINDENT
-.UNINDENT
 .sp
 As an example, if \fBgit machete status \-\-color=never \-\-list\-commits\fP is as follows:
 .INDENT 0.0
@@ -732,8 +734,6 @@ Opens an editor and lets you edit the branch layout file manually.
 .sp
 The editor is determined by checking up the following locations:
 .INDENT 0.0
-.INDENT 3.5
-.INDENT 0.0
 .IP \(bu 2
 \fB$GIT_MACHETE_EDITOR\fP
 .IP \(bu 2
@@ -751,8 +751,6 @@ The editor is determined by checking up the following locations:
 .IP \(bu 2
 \fBvi\fP
 .UNINDENT
-.UNINDENT
-.UNINDENT
 .sp
 and selecting the first one that is defined and points to an executable file accessible on \fBPATH\fP\&.
 .sp
@@ -787,8 +785,6 @@ The file is always called \fBmachete\fP and is located in the git directory of t
 .sp
 Three cases are possible:
 .INDENT 0.0
-.INDENT 3.5
-.INDENT 0.0
 .IP \(bu 2
 if \fBgit machete\fP is executed from a regular working directory (not a worktree or submodule),
 the file is located under \fB\&.git/machete\fP,
@@ -804,8 +800,6 @@ if \fBmachete.worktree.useTopLevelMacheteFile\fP is false, the file is located u
 .IP \(bu 2
 if \fBgit machete\fP is executed from a \fBsubmodule\fP, this file is located in the git folder of the submodule itself under \fB\&.git/modules/.../machete\fP\&.
 .UNINDENT
-.UNINDENT
-.UNINDENT
 .SH FORK-POINT
 .sp
 \fBUsage:\fP
@@ -831,17 +825,13 @@ Fork point of the given \fB<branch>\fP is the commit at which the history of the
 Fork point is assumed by many \fBgit machete\fP commands as the place where the unique history of the \fB<branch>\fP starts.
 The range of commits between the fork point and the tip of the given branch is, for instance:
 .INDENT 0.0
-.INDENT 3.5
-.INDENT 0.0
 .IP \(bu 2
 listed for each branch by \fBgit machete status \-\-list\-commits\fP
 .IP \(bu 2
 passed to \fBgit rebase\fP by \fBgit machete\fP \fBreapply\fP/\fBslide\-out\fP/\fBtraverse\fP/\fBupdate\fP
 .IP \(bu 2
 provided to \fBgit diff\fP/\fBlog\fP by \fBgit machete\fP \fBdiff\fP/\fBlog\fP\&.
 .UNINDENT
-.UNINDENT
-.UNINDENT
 .sp
 \fBgit machete\fP assumes fork point of \fB<branch>\fP is the most recent commit in the log of \fB<branch>\fP that has NOT been introduced on that very branch,
 but instead occurs on a reflog (see help for \fBgit reflog\fP) of some other branch.
@@ -1371,8 +1361,6 @@ where <direction> is one of: \fBd[own]\fP, \fBf[irst]\fP, \fBl[ast]\fP, \fBn[ext
 .sp
 Checks out the branch specified by the given direction relative to the current branch:
 .INDENT 0.0
-.INDENT 3.5
-.INDENT 0.0
 .IP \(bu 2
 \fBdown\fP:    the direct children/downstream branch of the current branch.
 .IP \(bu 2
@@ -1392,8 +1380,6 @@ since all branches are usually meant to be ultimately merged to one of those.
 .IP \(bu 2
 \fBup\fP:      the direct parent/upstream branch of the current branch.
 .UNINDENT
-.UNINDENT
-.UNINDENT
 .sp
 Roughly equivalent to \fBgit checkout $(git machete show <direction>)\fP\&.
 .SH HELP
@@ -1427,8 +1413,6 @@ is slid out by \fBadvance\fP, \fBslide\-out\fP or \fBtraverse\fP\&.
 .sp
 At least two parameters (branch names) are passed to the hook:
 .INDENT 7.0
-.INDENT 3.5
-.INDENT 0.0
 .IP \(bu 2
 <new\-upstream> is the upstream of the branch that has been slid out, or in case of multiple branches being slid out
 \-\-\- the upstream of the highest slid out branch;
@@ -1438,24 +1422,18 @@ At least two parameters (branch names) are passed to the hook:
 <new\-downstreams> are all the following (possibly zero) parameters, which correspond to all original downstreams
 of <lowest\-slid\-out\-branch>, now reattached as the downstreams of <new\-upstream>.
 .UNINDENT
-.UNINDENT
-.UNINDENT
 .sp
 Note that this may be zero, one, or multiple branches.
 .sp
 Note: the hook, if present, is executed:
 .INDENT 7.0
-.INDENT 3.5
-.INDENT 0.0
 .IP \(bu 2
 zero or once during a \fBadvance\fP execution (depending on whether the slide\-out has been confirmed or not),
 .IP \(bu 2
 exactly once during a \fBslide\-out\fP execution (even if multiple branches are slid out),
 .IP \(bu 2
 zero or more times during \fBtraverse\fP (every time a slide\-out operation is confirmed).
 .UNINDENT
-.UNINDENT
-.UNINDENT
 .sp
 If the hook returns a non\-zero exit code, then an error is raised and the execution of the command is aborted \-\-\-
 \fBslide\-out\fP won\(aqt attempt rebase of the new downstream branches and \fBtraverse\fP won\(aqt continue the traversal.
@@ -1517,17 +1495,13 @@ Returns with zero exit code if the given branch (or current branch, if none spec
 .sp
 Returns with a non\-zero exit code in case:
 .INDENT 0.0
-.INDENT 3.5
-.INDENT 0.0
 .IP \(bu 2
 the <branch> is provided but isn\(aqt managed (or doesn\(aqt exist), or
 .IP \(bu 2
 the <branch> isn\(aqt provided and the current branch isn\(aqt managed, or
 .IP \(bu 2
 the <branch> isn\(aqt provided and there\(aqs no current branch (detached HEAD).
 .UNINDENT
-.UNINDENT
-.UNINDENT
 .SH LIST
 .sp
 \fBUsage:\fP
@@ -1546,8 +1520,6 @@ where <category> is one of: \fBaddable\fP, \fBchildless\fP, \fBmanaged\fP, \fBsl
 .sp
 Lists all branches that fall into one of the specified categories:
 .INDENT 0.0
-.INDENT 3.5
-.INDENT 0.0
 .IP \(bu 2
 \fBaddable\fP: all branches (local or remote) than can be added to the branch layout file,
 .IP \(bu 2
@@ -1565,8 +1537,6 @@ Lists all branches that fall into one of the specified categories:
 \fBwith\-overridden\-fork\-point\fP: all local branches that have a \fI\%fork point\fP override set up
 (even if this override does not affect the location of their fork point anymore).
 .UNINDENT
-.UNINDENT
-.UNINDENT
 .sp
 This command is generally not meant for a day\-to\-day use, it\(aqs mostly needed for the sake of branch name completion in shell.
 .SH LOG
@@ -1644,8 +1614,6 @@ displayed relative to given <branch>, or the current checked out branch if <bran
 .sp
 Outputs name of the branch (or possibly multiple branches, in case of \fBdown\fP) that is:
 .INDENT 0.0
-.INDENT 3.5
-.INDENT 0.0
 .IP \(bu 2
 \fBcurrent\fP: the current branch; exits with a non\-zero status if none (detached HEAD)
 .IP \(bu 2
@@ -1667,8 +1635,6 @@ since all branches are usually meant to be ultimately merged to one of those.
 .IP \(bu 2
 \fBup\fP:      the direct parent/upstream branch of the given branch.
 .UNINDENT
-.UNINDENT
-.UNINDENT
 .SH SLIDE-OUT
 .sp
 \fBUsage:\fP
@@ -1779,8 +1745,6 @@ Not allowed if updating by merge.
 Slide out managed branches whose remote tracking branches have been deleted and that have no downstreams.
 In other words, this deletes all branches except:
 .INDENT 7.0
-.INDENT 3.5
-.INDENT 0.0
 .IP \(bu 2
 those that are unmanaged,
 .IP \(bu 2
@@ -1791,8 +1755,6 @@ those whose remote tracking branches still exist (not deleted remotely),
 those that have at least one downstream (child) branch.
 .UNINDENT
 .UNINDENT
-.UNINDENT
-.UNINDENT
 .sp
 \fBEnvironment variables:\fP
 .INDENT 0.0
@@ -1853,8 +1815,6 @@ Displays a tree\-shaped status of the branches listed in the branch layout file.
 .sp
 Apart from simply ASCII\-formatting the branch layout file, this also:
 .INDENT 0.0
-.INDENT 3.5
-.INDENT 0.0
 .IP \(bu 2
 colors the edges between upstream (parent) and downstream (children) branches:
 .INDENT 2.0
@@ -1881,8 +1841,6 @@ displays the output of \fBmachete\-status\-branch hook\fP (see help for \fI\%hoo
 .IP \(bu 2
 optionally lists commits introduced on each branch if \fB\-l/\-\-list\-commits\fP or \fB\-L/\-\-list\-commits\-with\-hashes\fP is supplied.
 .UNINDENT
-.UNINDENT
-.UNINDENT
 .sp
 Name of the currently checked\-out branch is underlined (or shown in blue on terminals that don\(aqt support underline).
 .sp
@@ -2027,8 +1985,6 @@ This behavior can, however, be customized using options: \fB\-\-start\-from=\fP,
 .sp
 For each branch, the command:
 .INDENT 0.0
-.INDENT 3.5
-.INDENT 0.0
 .IP \(bu 2
 detects if the branch is merged (grey edge) to its parent (aka upstream):
 .INDENT 2.0
@@ -2070,8 +2026,6 @@ and finally, if any of the above operations has been successfully completed:
 prints the updated \fBstatus\fP\&.
 .UNINDENT
 .UNINDENT
-.UNINDENT
-.UNINDENT
 .sp
 By default \fBtraverse\fP asks if the branch should be pushed. This behavior can, however, be changed with the \fBmachete.traverse.push\fP configuration key.
 It can also be customized using options: \fB\-\-[no\-]push\fP or \fB\-\-[no\-]push\-untracked\fP \-\-\- the order of the flags defines their precedence over each other

docs/source/cli/add.rst

@@ -11,9 +11,9 @@ add
 Adds the provided <branch> (or the current branch, if none specified) to the branch layout file.
 If <branch> is provided but no local branch with the given name exists:
 
-    * if a remote branch of the same name exists in exactly one remote,
-      then user is asked whether to check out this branch locally (as in ``git checkout``),
-    * otherwise, user is asked whether it should be created as a new local branch.
+* if a remote branch of the same name exists in exactly one remote,
+  then user is asked whether to check out this branch locally (as in ``git checkout``),
+* otherwise, user is asked whether it should be created as a new local branch.
 
 If the branch layout file is empty or ``-R/--as-root`` is provided, the branch will be added as a root of the tree of branch dependencies.
 Otherwise, the desired upstream (parent) branch can be specified with ``-o/--onto``.

docs/source/cli/advance.rst

@@ -19,12 +19,12 @@ and subsequently slides out ``D``. All three steps require manual confirmation u
 
 The downstream ``D`` is selected according to the following criteria:
 
-    * if ``C`` has exactly one downstream (child) branch ``d`` connected with a :green:`green edge` (see help for :ref:`status`) to ``C``
-      or is overridden, then ``d`` is selected as ``D``,
-    * if ``C`` has no downstream branches connected with a :green:`green edge` to ``C``, then ``advance`` fails,
-    * if ``C`` has more than one downstream branch connected with a :green:`green edge` to ``C``,
-      then user is asked to pick the branch to fast-forward merge into (similarly to what happens in ``git machete go down``).
-      If ``--yes`` is specified, then ``advance`` fails.
+* if ``C`` has exactly one downstream (child) branch ``d`` connected with a :green:`green edge` (see help for :ref:`status`) to ``C``
+  or is overridden, then ``d`` is selected as ``D``,
+* if ``C`` has no downstream branches connected with a :green:`green edge` to ``C``, then ``advance`` fails,
+* if ``C`` has more than one downstream branch connected with a :green:`green edge` to ``C``,
+  then user is asked to pick the branch to fast-forward merge into (similarly to what happens in ``git machete go down``).
+  If ``--yes`` is specified, then ``advance`` fails.
 
 As an example, if ``git machete status --color=never --list-commits`` is as follows:
 

docs/source/cli/edit.rst

@@ -12,14 +12,14 @@ Opens an editor and lets you edit the branch layout file manually.
 
 The editor is determined by checking up the following locations:
 
-    * ``$GIT_MACHETE_EDITOR``
-    * ``$GIT_EDITOR``
-    * ``$(git config core.editor)``
-    * ``$VISUAL``
-    * ``$EDITOR``
-    * ``editor``
-    * ``nano``
-    * ``vi``
+* ``$GIT_MACHETE_EDITOR``
+* ``$GIT_EDITOR``
+* ``$(git config core.editor)``
+* ``$VISUAL``
+* ``$EDITOR``
+* ``editor``
+* ``nano``
+* ``vi``
 
 and selecting the first one that is defined and points to an executable file accessible on ``PATH``.
 

docs/source/cli/file.rst

@@ -13,12 +13,12 @@ The file is always called ``machete`` and is located in the git directory of the
 
 Three cases are possible:
 
-    * if ``git machete`` is executed from a regular working directory (not a worktree or submodule),
-      the file is located under ``.git/machete``,
-    * if ``git machete`` is executed from a **worktree**,
-      the file path depends on the ``machete.worktree.useTopLevelMacheteFile`` config key value:
+* if ``git machete`` is executed from a regular working directory (not a worktree or submodule),
+  the file is located under ``.git/machete``,
+* if ``git machete`` is executed from a **worktree**,
+  the file path depends on the ``machete.worktree.useTopLevelMacheteFile`` config key value:
 
-      - if ``machete.worktree.useTopLevelMacheteFile`` is true (default), the file is located under ``.git/machete``
-      - if ``machete.worktree.useTopLevelMacheteFile`` is false, the file is located under ``.git/worktrees/.../machete``,
+  - if ``machete.worktree.useTopLevelMacheteFile`` is true (default), the file is located under ``.git/machete``
+  - if ``machete.worktree.useTopLevelMacheteFile`` is false, the file is located under ``.git/worktrees/.../machete``,
 
-    * if ``git machete`` is executed from a **submodule**, this file is located in the git folder of the submodule itself under ``.git/modules/.../machete``.
+* if ``git machete`` is executed from a **submodule**, this file is located in the git folder of the submodule itself under ``.git/modules/.../machete``.

docs/source/cli/fork-point.rst

@@ -29,9 +29,9 @@ Fork point of the given ``<branch>`` is the commit at which the history of the `
 Fork point is assumed by many ``git machete`` commands as the place where the unique history of the ``<branch>`` starts.
 The range of commits between the fork point and the tip of the given branch is, for instance:
 
-    * listed for each branch by ``git machete status --list-commits``
-    * passed to ``git rebase`` by ``git machete`` ``reapply``/``slide-out``/``traverse``/``update``
-    * provided to ``git diff``/``log`` by ``git machete`` ``diff``/``log``.
+* listed for each branch by ``git machete status --list-commits``
+* passed to ``git rebase`` by ``git machete`` ``reapply``/``slide-out``/``traverse``/``update``
+* provided to ``git diff``/``log`` by ``git machete`` ``diff``/``log``.
 
 ``git machete`` assumes fork point of ``<branch>`` is the most recent commit in the log of ``<branch>`` that has NOT been introduced on that very branch,
 but instead occurs on a reflog (see help for ``git reflog``) of some other branch.