update manual

2 files changed, 122 insertions, 36 deletions

diff --git a/Documentation/magit.org b/Documentation/magit.org
index 8140cdc..14a688b 100644
--- a/Documentation/magit.org
+++ b/Documentation/magit.org
@@ -113,13 +113,12 @@ that are useful for resolving conflicts and resuming the sequence
 after doing so.
 
 Magit wraps and in many cases improves upon at least the following Git
-porcelain commands: ~add~, ~am~, ~bisect~, ~blame~, ~branch~,
-~checkout~, ~cherry~, ~cherry-pick~, ~clean~, ~clone~, ~commit~,
-~config~, ~describe~, ~diff~, ~fetch~, ~format-patch~, ~init~, ~log~,
-~merge~, ~merge-tree~, ~mv~, ~notes~, ~pull~, ~rebase~, ~reflog~,
-~remote~, ~request-pull~, ~reset~, ~revert~, ~rm~, ~show~, ~stash~,
-~submodule~, and ~tag~.  Many more Magit porcelain commands are
-implemented on top of Git plumbing commands.
+porcelain commands: ~add~, ~am~, ~bisect~, ~blame~, ~branch~, ~checkout~, ~cherry~,
+~cherry-pick~, ~clean~, ~clone~, ~commit~, ~config~, ~describe~, ~diff~, ~fetch~,
+~format-patch~, ~init~, ~log~, ~merge~, ~merge-tree~, ~mv~, ~notes~, ~pull~, ~rebase~,
+~reflog~, ~remote~, ~request-pull~, ~reset~, ~revert~, ~rm~, ~show~, ~stash~,
+~submodule~, ~subtree~, ~tag~, and ~worktree.~  Many more Magit porcelain
+commands are implemented on top of Git plumbing commands.
 
 * Installation
 
@@ -384,9 +383,9 @@ Write a message and then type ~C-c C-c~ to actually create the commit.
 
 You probably don't want to push the commit you just created because
 you just committed some random changes, but if that is not the case
-you could push it by typing ~P~ to bring up the push popup and then ~P~
-again to push to the configured upstream.  (If the upstream is not
-configured, then you would be prompted for the push target instead.)
+you could push it by typing ~P~ to bring up the push popup and then ~u~ to
+push to the configured upstream.  (If the upstream is not configured,
+then you would be prompted for the push target instead.)
 
 Instead we are going to undo the changes made so far.  Bring up the
 log for the current branch by typing ~l l~, move to the last commit
@@ -478,9 +477,7 @@ buffers whose major-modes derive from ~magit-mode~.
   Magit provides several functions, listed below, that are suitable
   values for this option.  If you want to use different rules, then a
   good way of doing that is to start with a copy of one of these
-  functions and then adjust it to your needs.  More functions to
-  choose from will likely be added in the future, and eventually the
-  default will change.
+  functions and then adjust it to your needs.
 
   Instead of using a wrapper around ~display-buffer~, that function
   itself can be used here, in which case the display actions have to
@@ -1624,8 +1621,13 @@ The following functions can also be added to the above hook:
 
 - Function: magit-insert-submodules
 
-  Insert sections for all modules.  For each section insert the path
-  and the output of ~git describe --tags~.
+  Insert sections for all submodules.  For each section insert the
+  path, the branch, and the output of ~git describe --tags~.
+
+  Press ~RET~ on such a submodule section to show its own status buffer.
+  Press ~RET~ on the "Modules" section to display a list of submodules
+  in a separate buffer.  This shows additional information not
+  displayed in the super-repository's status buffer.
 
 - Function: magit-insert-unpulled-cherries
 
@@ -1740,7 +1742,7 @@ buffers.
 
 - Command: magit-list-repositories
 
-  This command displays a list of repositories.
+  This command displays a list of repositories in a separate buffer.
 
   The options ~magit-repository-directories~ and
   ~magit-repository-directories-depth~ control which repositories are
@@ -2580,7 +2582,6 @@ bisect session.
   This option controls whether a graph is displayed for the log of
   commits that still have to be bisected.
 
-
 ** Visiting blobs
 
 - Key: M-x magit-find-file, magit-find-file
@@ -3228,7 +3229,6 @@ To show no diff while committing remove ~magit-commit-diff~ from
 ~server-switch-hook~.
 
 ** Branching
-
 *** The two remotes
 
 The upstream branch of some local branch is the branch into which the
@@ -4648,12 +4648,47 @@ following suffix commands, instead of those listed above.
 
 Also see [[info:gitman#git-submodule]].
 
+*** Listing submodules
+
+The command ~magit-list-submodule~ displays a list of the current
+repository's submodules in a separate buffer.  It's also possible to
+display information about submodules directly in the status buffer of
+the super-repository by adding ~magit-insert-submodules~ to the hook
+~magit-status-sections-hook~.
+
 - Command: magit-list-submodules
 
-  This command displays of the current repository's submodules.
+  This command displays a list of the current repository's submodules
+  in a separate buffer.
 
   It can be invoked by pressing ~RET~ on the section titled "Modules".
 
+- User Option: magit-submodule-list-columns
+
+  This option controls what columns are displayed by the command
+  ~magit-list-submodules~ and how they are displayed.
+
+  Each element has the form ~(HEADER WIDTH FORMAT PROPS)~.
+
+  HEADER is the string displayed in the header.  WIDTH is the width of
+  the column.  FORMAT is a function that is called with one argument,
+  the repository identification (usually its basename), and with
+  ~default-directory~ bound to the toplevel of its working tree.  It
+  has to return a string to be inserted or nil.  PROPS is an alist
+  that supports the keys ~:right-align~ and ~:pad-right~.
+
+- Function: magit-insert-submodules
+
+  Insert sections for all submodules.  For each section insert the
+  path, the branch, and the output of ~git describe --tags~.
+
+  Press ~RET~ on such a submodule section to show its own status buffer.
+  Press ~RET~ on the "Modules" section to display a list of submodules
+  in a separate buffer.  This shows additional information not
+  displayed in the super-repository's status buffer.
+
+*** Submodule popup
+
 - Key: o, magit-submodule-popup
 
   This prefix command shows the following suffix commands along with
diff --git a/Documentation/magit.texi b/Documentation/magit.texi
index 3d02f2f..baa94e6 100644
--- a/Documentation/magit.texi
+++ b/Documentation/magit.texi
@@ -233,6 +233,11 @@ Miscellaneous
 
 
 
+Submodules
+
+* Listing submodules::
+* Submodule popup::
+
 Customizing
 
 * Per-repository configuration::
@@ -371,13 +376,12 @@ that are useful for resolving conflicts and resuming the sequence
 after doing so.
 
 Magit wraps and in many cases improves upon at least the following Git
-porcelain commands: @code{add}, @code{am}, @code{bisect}, @code{blame}, @code{branch},
-@code{checkout}, @code{cherry}, @code{cherry-pick}, @code{clean}, @code{clone}, @code{commit},
-@code{config}, @code{describe}, @code{diff}, @code{fetch}, @code{format-patch}, @code{init}, @code{log},
-@code{merge}, @code{merge-tree}, @code{mv}, @code{notes}, @code{pull}, @code{rebase}, @code{reflog},
-@code{remote}, @code{request-pull}, @code{reset}, @code{revert}, @code{rm}, @code{show}, @code{stash},
-@code{submodule}, and @code{tag}.  Many more Magit porcelain commands are
-implemented on top of Git plumbing commands.
+porcelain commands: @code{add}, @code{am}, @code{bisect}, @code{blame}, @code{branch}, @code{checkout}, @code{cherry},
+@code{cherry-pick}, @code{clean}, @code{clone}, @code{commit}, @code{config}, @code{describe}, @code{diff}, @code{fetch},
+@code{format-patch}, @code{init}, @code{log}, @code{merge}, @code{merge-tree}, @code{mv}, @code{notes}, @code{pull}, @code{rebase},
+@code{reflog}, @code{remote}, @code{request-pull}, @code{reset}, @code{revert}, @code{rm}, @code{show}, @code{stash},
+@code{submodule}, @code{subtree}, @code{tag}, and @code{worktree.}  Many more Magit porcelain
+commands are implemented on top of Git plumbing commands.
 
 @node Installation
 @chapter Installation
@@ -666,9 +670,9 @@ Write a message and then type @code{C-c C-c} to actually create the commit.
 
 You probably don't want to push the commit you just created because
 you just committed some random changes, but if that is not the case
-you could push it by typing @code{P} to bring up the push popup and then @code{P}
-again to push to the configured upstream.  (If the upstream is not
-configured, then you would be prompted for the push target instead.)
+you could push it by typing @code{P} to bring up the push popup and then @code{u} to
+push to the configured upstream.  (If the upstream is not configured,
+then you would be prompted for the push target instead.)
 
 Instead we are going to undo the changes made so far.  Bring up the
 log for the current branch by typing @code{l l}, move to the last commit
@@ -786,9 +790,7 @@ list of display actions as second argument.
 Magit provides several functions, listed below, that are suitable
 values for this option.  If you want to use different rules, then a
 good way of doing that is to start with a copy of one of these
-functions and then adjust it to your needs.  More functions to
-choose from will likely be added in the future, and eventually the
-default will change.
+functions and then adjust it to your needs.
 
 Instead of using a wrapper around @code{display-buffer}, that function
 itself can be used here, in which case the display actions have to
@@ -2200,8 +2202,13 @@ respective commits.
 
 @defun magit-insert-submodules
 
-Insert sections for all modules.  For each section insert the path
-and the output of @code{git describe --tags}.
+Insert sections for all submodules.  For each section insert the
+path, the branch, and the output of @code{git describe --tags}.
+
+Press @code{RET} on such a submodule section to show its own status buffer.
+Press @code{RET} on the "Modules" section to display a list of submodules
+in a separate buffer.  This shows additional information not
+displayed in the super-repository's status buffer.
 @end defun
 
 @defun magit-insert-unpulled-cherries
@@ -2336,7 +2343,7 @@ buffers.
 @cindex magit-list-repositories
 @deffn Command magit-list-repositories
 
-This command displays a list of repositories.
+This command displays a list of repositories in a separate buffer.
 
 The options @code{magit-repository-directories} and
 @code{magit-repository-directories-depth} control which repositories are
@@ -6476,14 +6483,58 @@ the git-submodule(1) manpage
 @end iftex
 .
 
+@menu
+* Listing submodules::
+* Submodule popup::
+@end menu
+
+@node Listing submodules
+@subsection Listing submodules
+
+The command @code{magit-list-submodule} displays a list of the current
+repository's submodules in a separate buffer.  It's also possible to
+display information about submodules directly in the status buffer of
+the super-repository by adding @code{magit-insert-submodules} to the hook
+@code{magit-status-sections-hook}.
+
 @cindex magit-list-submodules
 @deffn Command magit-list-submodules
 
-This command displays of the current repository's submodules.
+This command displays a list of the current repository's submodules
+in a separate buffer.
 
 It can be invoked by pressing @code{RET} on the section titled "Modules".
 @end deffn
 
+@defopt magit-submodule-list-columns
+
+This option controls what columns are displayed by the command
+@code{magit-list-submodules} and how they are displayed.
+
+Each element has the form @code{(HEADER WIDTH FORMAT PROPS)}.
+
+HEADER is the string displayed in the header.  WIDTH is the width of
+the column.  FORMAT is a function that is called with one argument,
+the repository identification (usually its basename), and with
+@code{default-directory} bound to the toplevel of its working tree.  It
+has to return a string to be inserted or nil.  PROPS is an alist
+that supports the keys @code{:right-align} and @code{:pad-right}.
+@end defopt
+
+@defun magit-insert-submodules
+
+Insert sections for all submodules.  For each section insert the
+path, the branch, and the output of @code{git describe --tags}.
+
+Press @code{RET} on such a submodule section to show its own status buffer.
+Press @code{RET} on the "Modules" section to display a list of submodules
+in a separate buffer.  This shows additional information not
+displayed in the super-repository's status buffer.
+@end defun
+
+@node Submodule popup
+@subsection Submodule popup
+
 @table @asis
 @kindex o
 @cindex magit-submodule-popup