diff --git a/docs/generate-sphinx-man.sh b/docs/generate-sphinx-man.sh index 9c7e5bcf0..1b9949cf6 100755 --- a/docs/generate-sphinx-man.sh +++ b/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 diff --git a/docs/man/git-machete.1 b/docs/man/git-machete.1 index bcf66a60c..73805f956 100644 --- a/docs/man/git-machete.1 +++ b/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=] [\-R|\-\-as\-root] [\- Adds the provided (or the current branch, if none specified) to the branch layout file. If 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,8 +825,6 @@ Fork point of the given \fB\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\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 @@ -840,8 +832,6 @@ passed to \fBgit rebase\fP by \fBgit machete\fP \fBreapply\fP/\fBslide\-out\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\fP is the most recent commit in the log of \fB\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 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 )\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 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,15 +1422,11 @@ At least two parameters (branch names) are passed to the hook: are all the following (possibly zero) parameters, which correspond to all original downstreams of , now reattached as the downstreams of . .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 @@ -1454,8 +1434,6 @@ exactly once during a \fBslide\-out\fP execution (even if multiple branches are .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,8 +1495,6 @@ 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 is provided but isn\(aqt managed (or doesn\(aqt exist), or .IP \(bu 2 @@ -1526,8 +1502,6 @@ the isn\(aqt provided and the current branch isn\(aqt managed, or .IP \(bu 2 the isn\(aqt provided and there\(aqs no current branch (detached HEAD). .UNINDENT -.UNINDENT -.UNINDENT .SH LIST .sp \fBUsage:\fP @@ -1546,8 +1520,6 @@ where 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 , or the current checked out branch if (or the current branch, if none specified) to the branch layout file. If 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``. diff --git a/docs/source/cli/advance.rst b/docs/source/cli/advance.rst index 7e4a99ec8..c41796752 100644 --- a/docs/source/cli/advance.rst +++ b/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: diff --git a/docs/source/cli/edit.rst b/docs/source/cli/edit.rst index a2623a18e..d0e21b964 100644 --- a/docs/source/cli/edit.rst +++ b/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``. diff --git a/docs/source/cli/file.rst b/docs/source/cli/file.rst index 6589c726f..537d19549 100644 --- a/docs/source/cli/file.rst +++ b/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``. diff --git a/docs/source/cli/fork-point.rst b/docs/source/cli/fork-point.rst index 14073595f..19b0fa491 100644 --- a/docs/source/cli/fork-point.rst +++ b/docs/source/cli/fork-point.rst @@ -29,9 +29,9 @@ Fork point of the given ```` 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 ```` 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 ```` is the most recent commit in the log of ```` that has NOT been introduced on that very branch, but instead occurs on a reflog (see help for ``git reflog``) of some other branch. diff --git a/docs/source/cli/go.rst b/docs/source/cli/go.rst index 8d6101670..d55c7b1b4 100644 --- a/docs/source/cli/go.rst +++ b/docs/source/cli/go.rst @@ -12,16 +12,16 @@ where is one of: ``d[own]``, ``f[irst]``, ``l[ast]``, ``n[ext]``, `` Checks out the branch specified by the given direction relative to the current branch: - * ``down``: the direct children/downstream branch of the current branch. - * ``first``: the first downstream of the root branch of the current branch (like ``root`` followed by ``next``), - or the root branch itself if the root has no downstream branches. - * ``last``: the last branch in the branch layout file that has the same root as the current branch; - can be the root branch itself if the root has no downstream branches. - * ``next``: the direct successor of the current branch in the branch layout file. - * ``prev``: the direct predecessor of the current branch in the branch layout file. - * ``root``: the root of the tree where the current branch is located. - Note: this will typically be something like ``develop`` or ``master``, - since all branches are usually meant to be ultimately merged to one of those. - * ``up``: the direct parent/upstream branch of the current branch. +* ``down``: the direct children/downstream branch of the current branch. +* ``first``: the first downstream of the root branch of the current branch (like ``root`` followed by ``next``), + or the root branch itself if the root has no downstream branches. +* ``last``: the last branch in the branch layout file that has the same root as the current branch; + can be the root branch itself if the root has no downstream branches. +* ``next``: the direct successor of the current branch in the branch layout file. +* ``prev``: the direct predecessor of the current branch in the branch layout file. +* ``root``: the root of the tree where the current branch is located. + Note: this will typically be something like ``develop`` or ``master``, + since all branches are usually meant to be ultimately merged to one of those. +* ``up``: the direct parent/upstream branch of the current branch. Roughly equivalent to ``git checkout $(git machete show )``. diff --git a/docs/source/cli/hooks.rst b/docs/source/cli/hooks.rst index 018dc154b..20ea9b1a1 100644 --- a/docs/source/cli/hooks.rst +++ b/docs/source/cli/hooks.rst @@ -15,19 +15,19 @@ Note: ``hooks`` is not a command as such, just a help topic (there is no ``git m At least two parameters (branch names) are passed to the hook: - * 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; - * is the branch that has been slid out, or in case of multiple branches being slid out --- the lowest slid out branch; - * are all the following (possibly zero) parameters, which correspond to all original downstreams - of , now reattached as the downstreams of . + * 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; + * is the branch that has been slid out, or in case of multiple branches being slid out --- the lowest slid out branch; + * are all the following (possibly zero) parameters, which correspond to all original downstreams + of , now reattached as the downstreams of . Note that this may be zero, one, or multiple branches. Note: the hook, if present, is executed: - * zero or once during a ``advance`` execution (depending on whether the slide-out has been confirmed or not), - * exactly once during a ``slide-out`` execution (even if multiple branches are slid out), - * zero or more times during ``traverse`` (every time a slide-out operation is confirmed). + * zero or once during a ``advance`` execution (depending on whether the slide-out has been confirmed or not), + * exactly once during a ``slide-out`` execution (even if multiple branches are slid out), + * zero or more times during ``traverse`` (every time a slide-out operation is confirmed). If the hook returns a non-zero exit code, then an error is raised and the execution of the command is aborted --- ``slide-out`` won't attempt rebase of the new downstream branches and ``traverse`` won't continue the traversal. diff --git a/docs/source/cli/is-managed.rst b/docs/source/cli/is-managed.rst index a682a479e..355b202e2 100644 --- a/docs/source/cli/is-managed.rst +++ b/docs/source/cli/is-managed.rst @@ -12,6 +12,6 @@ Returns with zero exit code if the given branch (or current branch, if none spec Returns with a non-zero exit code in case: - * the is provided but isn't managed (or doesn't exist), or - * the isn't provided and the current branch isn't managed, or - * the isn't provided and there's no current branch (detached HEAD). +* the is provided but isn't managed (or doesn't exist), or +* the isn't provided and the current branch isn't managed, or +* the isn't provided and there's no current branch (detached HEAD). diff --git a/docs/source/cli/list.rst b/docs/source/cli/list.rst index 3c2753ca8..030d874b2 100644 --- a/docs/source/cli/list.rst +++ b/docs/source/cli/list.rst @@ -12,14 +12,14 @@ where is one of: ``addable``, ``childless``, ``managed``, ``slidable` Lists all branches that fall into one of the specified categories: - * ``addable``: all branches (local or remote) than can be added to the branch layout file, - * ``childless``: all managed branches that do not possess child branches, - * ``managed``: all branches that appear in the branch layout file, - * ``slidable``: all managed branches that have an upstream and can be slid out with :ref:`slide-out` command - * ``slidable-after ``: the downstream branch of the , if it exists and is the only downstream of - (and thus can be slid out immediately following ), - * ``unmanaged``: all local branches that don't appear in the branch layout file, - * ``with-overridden-fork-point``: all local branches that have a :ref:`fork point` override set up - (even if this override does not affect the location of their fork point anymore). +* ``addable``: all branches (local or remote) than can be added to the branch layout file, +* ``childless``: all managed branches that do not possess child branches, +* ``managed``: all branches that appear in the branch layout file, +* ``slidable``: all managed branches that have an upstream and can be slid out with :ref:`slide-out` command +* ``slidable-after ``: the downstream branch of the , if it exists and is the only downstream of + (and thus can be slid out immediately following ), +* ``unmanaged``: all local branches that don't appear in the branch layout file, +* ``with-overridden-fork-point``: all local branches that have a :ref:`fork point` override set up + (even if this override does not affect the location of their fork point anymore). This command is generally not meant for a day-to-day use, it's mostly needed for the sake of branch name completion in shell. diff --git a/docs/source/cli/show.rst b/docs/source/cli/show.rst index 766bf68c9..da49b59cd 100644 --- a/docs/source/cli/show.rst +++ b/docs/source/cli/show.rst @@ -13,15 +13,15 @@ displayed relative to given , or the current checked out branch if ` of the downstream branch is NOT equal to the upstream branch. + - :yellow:`yellow edge` means *in sync but fork point off*. The downstream branch is a direct descendant of the upstream branch, + but the :ref:`fork point` of the downstream branch is NOT equal to the upstream branch. - - :green:`green edge` means *in sync*. The downstream branch is a direct descendant of the upstream branch - and the fork point of the downstream branch is equal to the upstream branch. + - :green:`green edge` means *in sync*. The downstream branch is a direct descendant of the upstream branch + and the fork point of the downstream branch is equal to the upstream branch. - - :grey:`grey/dimmed edge` means *merged*. The downstream branch has been merged to the upstream branch, - detected by commit equivalency (default), or by strict detection of merge commits (if ``--no-detect-squash-merges`` passed). + - :grey:`grey/dimmed edge` means *merged*. The downstream branch has been merged to the upstream branch, + detected by commit equivalency (default), or by strict detection of merge commits (if ``--no-detect-squash-merges`` passed). - * prints (``untracked``/``ahead of ``/``behind ``/``diverged from [& older than] ``) message if the branch - is not in sync with its remote counterpart; +* prints (``untracked``/``ahead of ``/``behind ``/``diverged from [& older than] ``) message if the branch + is not in sync with its remote counterpart; - * displays the custom annotations (see help for :ref:`format` and :ref:`anno`) next to each branch, if present. Annotations might contain underlined branch - qualifiers (``push=no``, ``rebase=no``, ``slide-out=no``) that control rebase and push behavior of ``traverse`` (see help for :ref:`traverse`); +* displays the custom annotations (see help for :ref:`format` and :ref:`anno`) next to each branch, if present. Annotations might contain underlined branch + qualifiers (``push=no``, ``rebase=no``, ``slide-out=no``) that control rebase and push behavior of ``traverse`` (see help for :ref:`traverse`); - * displays the output of ``machete-status-branch hook`` (see help for :ref:`hooks`), if present; +* displays the output of ``machete-status-branch hook`` (see help for :ref:`hooks`), if present; - * optionally lists commits introduced on each branch if ``-l/--list-commits`` or ``-L/--list-commits-with-hashes`` is supplied. +* optionally lists commits introduced on each branch if ``-l/--list-commits`` or ``-L/--list-commits-with-hashes`` is supplied. Name of the currently checked-out branch is underlined (or shown in blue on terminals that don't support underline). diff --git a/docs/source/cli/traverse.rst b/docs/source/cli/traverse.rst index 3a66a967e..331f6bda8 100644 --- a/docs/source/cli/traverse.rst +++ b/docs/source/cli/traverse.rst @@ -29,32 +29,32 @@ This behavior can, however, be customized using options: ``--start-from=``, ``-- For each branch, the command: - * detects if the branch is merged (:grey:`grey` edge) to its parent (aka upstream): +* detects if the branch is merged (:grey:`grey` edge) to its parent (aka upstream): - - by commit equivalency (default), or by strict detection of merge commits (if ``--no-detect-squash-merges`` passed), - - if so, asks the user whether to **slide out** the branch from the dependency tree (typically branches are no longer needed after they're merged); + - by commit equivalency (default), or by strict detection of merge commits (if ``--no-detect-squash-merges`` passed), + - if so, asks the user whether to **slide out** the branch from the dependency tree (typically branches are no longer needed after they're merged); - * otherwise, if the branch has a :red:`red` or :yellow:`yellow` edge to its parent/upstream (see help for :ref:`status`): +* otherwise, if the branch has a :red:`red` or :yellow:`yellow` edge to its parent/upstream (see help for :ref:`status`): - - asks the user whether to **rebase** (default) or merge (if ``--merge`` passed) the branch onto into its upstream branch - --- equivalent to ``git machete update``; + - asks the user whether to **rebase** (default) or merge (if ``--merge`` passed) the branch onto into its upstream branch + --- equivalent to ``git machete update``; - * if the branch is not tracked on a remote, is ahead of its remote counterpart, or diverged from the counterpart & - has newer head commit than the counterpart: +* if the branch is not tracked on a remote, is ahead of its remote counterpart, or diverged from the counterpart & + has newer head commit than the counterpart: - - asks the user whether to **push** the branch (possibly with ``--force-with-lease`` if the branches diverged); + - asks the user whether to **push** the branch (possibly with ``--force-with-lease`` if the branches diverged); - * otherwise, if the branch diverged from the remote counterpart & has older head commit than the counterpart: +* otherwise, if the branch diverged from the remote counterpart & has older head commit than the counterpart: - - asks the user whether to **reset** (``git reset --keep``) the branch to its remote counterpart + - asks the user whether to **reset** (``git reset --keep``) the branch to its remote counterpart - * otherwise, if the branch is behind its remote counterpart: +* otherwise, if the branch is behind its remote counterpart: - - asks the user whether to **pull** the branch; + - asks the user whether to **pull** the branch; - * and finally, if any of the above operations has been successfully completed: +* and finally, if any of the above operations has been successfully completed: - - prints the updated ``status``. + - prints the updated ``status``. By default ``traverse`` asks if the branch should be pushed. This behavior can, however, be changed with the ``machete.traverse.push`` configuration key. It can also be customized using options: ``--[no-]push`` or ``--[no-]push-untracked`` --- the order of the flags defines their precedence over each other diff --git a/docs/source/index.rst b/docs/source/index.rst index a6ebd07ce..fd63ab6b5 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -14,8 +14,8 @@ Using this tool, you can maintain **small, focused, easy-to-review pull requests A look at a ``git machete status`` gives an instant answer to the questions: - * What branches are in this repository? - * What is going to be merged (rebased/pushed/pulled) and to what? +* What branches are in this repository? +* What is going to be merged (rebased/pushed/pulled) and to what? ``git machete traverse`` semi-automatically traverses the branches, helping you effortlessly rebase, merge, push and pull. @@ -28,6 +28,14 @@ git machete commands and help topics: .. include:: learning_materials.rst +General options +--------------- + +--debug Log detailed diagnostic info, including outputs of the executed git commands. +-h, --help Print help and exit. +-v, --verbose Log the executed git commands. +--version Print version and exit. + Commands & help topics ---------------------- diff --git a/docs/source/learning_materials.rst b/docs/source/learning_materials.rst index 6753365a1..4c9e26691 100644 --- a/docs/source/learning_materials.rst +++ b/docs/source/learning_materials.rst @@ -13,7 +13,7 @@ Check the following blog posts for more information on how to use git machete or how to manage CI in your own project using Docker: - * `Make your way through the git (rebase) jungle with Git Machete `_ - * `git machete strikes again! Traverse the git (rebase) jungle even faster `_ - * `Nifty Docker tricks for your CI (vol. 1) `_ - * `Nifty Docker tricks for your CI (vol. 2) `_ + * `Make your way through the git (rebase) jungle with Git Machete `_ + * `git machete strikes again! Traverse the git (rebase) jungle even faster `_ + * `Nifty Docker tricks for your CI (vol. 1) `_ + * `Nifty Docker tricks for your CI (vol. 2) `_ diff --git a/git_machete/cli.py b/git_machete/cli.py index e652be76c..142e056f0 100644 --- a/git_machete/cli.py +++ b/git_machete/cli.py @@ -61,7 +61,7 @@ def get_help_description(display_help_topics: bool, command: Optional[str] = Non usage_str += fmt(textwrap.dedent(long_docs[command_by_alias[command]])) else: usage_str += get_short_general_usage() + '\n' + fmt( - "\nTL;DR tip\n\n" + "\nQuick start tip\n\n" " Get familiar with the help for format, edit," " status and update, in this order.\n\n") for hdr, cmds in command_groups: diff --git a/tox.ini b/tox.ini index ec5f98338..2aac28494 100644 --- a/tox.ini +++ b/tox.ini @@ -137,44 +137,52 @@ commands = [testenv:sphinx-html] basepython=3.11 description = "Build Sphinx documentation in HTML" -allowlist_externals = bash deps = -r{[requirements]dir}/sphinx-docs.txt +allowlist_externals = bash commands = bash docs/generate-sphinx-html.sh docs/html [testenv:sphinx-man] basepython=3.11 description = "Build Sphinx documentation in groff format (Unix man page)" -allowlist_externals = bash deps = -r{[requirements]dir}/sphinx-docs.txt +allowlist_externals = bash commands = bash docs/generate-sphinx-man.sh docs/man +[testenv:sphinx-man-display] +basepython=3.11 +description = "Build and display Sphinx documentation in groff format (Unix man page)" +depends = sphinx-man +allowlist_externals = sh +commands = + sh -c 'groff -man -Tascii < docs/man/git-machete.1 2>/dev/null' + [testenv:sphinx-man-check] basepython=3.11 description = "Check if Unix man page is up to date with reStructuredText sources" -allowlist_externals = bash deps = -r{[requirements]dir}/sphinx-docs.txt +allowlist_externals = bash commands = bash docs/enforce-sphinx-man-up-to-date.sh [testenv:py-docs] description = "Build Python documentation" # The generation of the python docs uses git_machete package -allowlist_externals = bash deps = -r{[requirements]dir}/py-docs.txt +allowlist_externals = sh commands = - bash -c "python docs/generate_py_docs.py > git_machete/generated_docs.py" + sh -c "python docs/generate_py_docs.py > git_machete/generated_docs.py" [testenv:py-docs-check] description = "Check if Python documentation is up to date with with reStructuredText sources" -allowlist_externals = bash deps = -r{[requirements]dir}/py-docs.txt +allowlist_externals = bash commands = bash docs/enforce-py-docs-up-to-date.sh