magit.org: update for most changes since v2.1.0

2 files changed, 427 insertions, 28 deletions

diff --git a/Documentation/magit.org b/Documentation/magit.org
index a3d6401..b088785 100644
--- a/Documentation/magit.org
+++ b/Documentation/magit.org
@@ -463,6 +463,28 @@ other commits as usual.
 
   With a prefix argument, the user can pick an arbitrary name.
 
+- Key: M-w, magit-copy-buffer-thing-as-kill
+
+  This command saves a representation of the thing that is being
+  displayed in the current buffer to the kill ring.
+
+  In buffers in which it is undefined what this "buffer thing" is,
+  this command instead saves the value of the current section, as
+  ~magit-copy-as-kill~ would.
+
+  When the region is active, then this command behaves like
+  ~kill-ring-save~.
+
+- Key: C-w, magit-copy-as-kill
+
+  This commands saves the value of the current section to the kill
+  ring.  For commits it saves the full hash.  For branches it saves
+  the branch name, except when a prefix argument is used, then it
+  saves the full hash.
+
+  When the region is active, then this command behaves like
+  ~kill-ring-save~.
+
 ** Automatic save
 
 File-visiting buffers are by default saved at certain points in time.
@@ -1290,6 +1312,14 @@ The following functions can also be added to the above hook:
 
   Insert a header line about the remote of the current branch.
 
+  If no remote is configured for the current branch, then fall back
+  showing the "origin" remote, or if that does not exist the first
+  remote in alphabetic order.
+
+- Function: magit-insert-user-header
+
+  Insert a header line about the current user.
+
 *** Status options
 
 - User Option: magit-status-refresh-hook
@@ -1446,6 +1476,11 @@ The following related commands are not available from the popup.
 
   The maximum number of commits to show in log and reflog buffers.
 
+- User Option: magit-log-show-refname-after-summary
+
+  Whether to show the refnames after the commit summaries.  This is
+  useful if you use really long branch names.
+
 *** Select from log
 
 When the user has to select a recent commit that is reachable from
@@ -1706,6 +1741,18 @@ displayed but not how.
   would normally not look at the changes, e.g. because you are
   committing some binary files.
 
+- User Option: magit-diff-auto-show-delay
+
+  How long to delay showing or updating the revision buffer, when
+  that happens automatically (according to ~magit-diff-auto-show~).
+
+  When holding down a key to move by several lines, then that would
+  update that buffer for each line on the way.  To prevent that,
+  updating the revision buffer is delayed, and this option controls
+  for how long it is delayed.  For optimal experience you might have
+  to adjust this delay and/or the keyboard repeat rate and delay of
+  your graphical environment or operating system.
+
 - User Option: magit-diff-refine-hunk
 
   Whether to show word-granularity differences within diff hunks.
@@ -1830,6 +1877,16 @@ displayed but not how.
   ~magit-ediff-show-unstaged~ to show staged and unstaged changes,
   respectively.
 
+- User Option: magit-ediff-quit-hook
+
+  This hook is run after quitting an Ediff session that was created
+  using a Magit command.  The hook functions are run inside the Ediff
+  control buffer, and should not change the current buffer.
+
+  This is similar to ~ediff-quit-hook~ but takes the needs of Magit into
+  account.  The regular ~ediff-quit-hook~ is ignored by Ediff sessions
+  that were created using a Magit command.
+
 ** References buffer
 
 - Key: y, magit-show-refs-popup
@@ -1909,6 +1966,39 @@ should also change the others to keep things aligned.  The following
   Indentation of cherries in refs buffers.  This should be N-1 where N
   is taken from "%Nc" in the above format strings.
 
+Everywhere in Magit ~RET~ visits the thing represented by the section
+at point.  In almost all cases visiting is done by showing some
+information in another buffer and *not* doing anything else.  In refs
+buffers ~RET~ behaves differently, and because many users have grown
+accustomed to that inconsistency we are keeping it that way.
+
+- Key: RET, magit-visit-ref
+
+  Everywhere except in refs buffers this command behaves exactly like
+  ~magit-show-commit~; it shows the commit at point in another buffer.
+
+  In refs buffers, when there is a local branch at point, then this
+  command instead checks out that branch.  When there is a remote
+  branch or a tag at point then the respective commit is checked out
+  causing ~HEAD~ to be detached.
+
+  When a prefix argument it used, then this command only *focuses* on
+  the reference at point, i.e. the commit counts and cherries are
+  updated to be relative to that reference, but nothing is checked
+  out.
+
+- User Option: magit-visit-ref-create
+
+  When this is non-nil and ~magit-visit-ref~ is called inside a refs
+  buffer, then it "visits" the remote branch at point by creating a
+  new local branch which tracks that remote branch and then checking
+  out the newly created branch.
+
+  This is not enabled by default because one has to use an extremely
+  loose definition of the verb "to visit" to be able to argue that
+  creating and then checking out a new local branch is a form of
+  visiting a remote branch.
+
 *** References sections
 
 The contents of references buffers is controlled using the hook
@@ -2066,6 +2156,10 @@ Also see [[info:gitman#git-blame]].
   Turn off Magit-Blame mode.  If the buffer was created during a
   recursive blame, then also kill the buffer.
 
+- Key: M-w, magit-blame-copy-hash
+
+  Save the hash of the current chunk's commit to the kill ring.
+
 - Key: t, magit-blame-toggle-headings
 
   Show or hide blame chunk headings.
@@ -2092,7 +2186,8 @@ Also see [[info:gitman#git-blame]].
 
 - Key: M-x magit-init, magit-init
 
-  Initialize a Git repository, then show its status.
+  This command initializes a repository and then shows the status
+  buffer for the new repository.
 
   If the directory is below an existing repository, then the user has
   to confirm that a new one should be created inside.  If the
@@ -2101,8 +2196,10 @@ Also see [[info:gitman#git-blame]].
 
 - Key: M-x magit-clone, magit-clone
 
-  Clone a repository.  The user is queried for a remote url and a
-  local directory.
+  This command clones a repository and then shows the status buffer
+  for the new repository.
+
+  The user is queried for a remote url and a local directory.
 
 ** Staging and unstaging
 
@@ -2208,8 +2305,7 @@ variants.
 
 - Key: a, magit-apply
 
-  Apply the change at point to the working tree.  With a prefix argument
-  and if necessary, attempt a 3-way merge.
+  Apply the change at point to the working tree.
 
 - Key: k, magit-discard
 
@@ -2219,6 +2315,9 @@ variants.
 
   Reverse the change at point in the working tree.
 
+With a prefix argument all apply variants attempt a 3-way merge when
+appropriate (i.e. when ~git apply~ is used internally).
+
 ** Committing
 
 When the user initiates a commit, Magit calls ~git commit~ without any
@@ -2266,10 +2365,11 @@ Also see [[info:gitman#git-commit]].
 
 - Key: c f, magit-commit-fixup
 
-  Create a fixup commit.  With a prefix argument the target commit has
-  to be confirmed.  Otherwise the commit at point may be used without
-  confirmation depending on the value of option
-  ~magit-commit-squash-confirm~.
+  Create a fixup commit.
+
+  With a prefix argument the target commit has to be confirmed.
+  Otherwise the commit at point may be used without confirmation
+  depending on the value of option ~magit-commit-squash-confirm~.
 
 - Key: c F, magit-commit-instant-fixup
 
@@ -2277,15 +2377,24 @@ Also see [[info:gitman#git-commit]].
 
 - Key: c s, magit-commit-squash
 
-  Create a squash commit.  With a prefix argument the target commit
-  has to be confirmed.  Otherwise the commit at point may be used
-  without confirmation depending on the value of option
-  ~magit-commit-squash-confirm~.
+  Create a squash commit, without editing the squash message.
+
+  With a prefix argument the target commit has to be confirmed.
+  Otherwise the commit at point may be used without confirmation
+  depending on the value of option ~magit-commit-squash-confirm~.
 
 - Key: c S, magit-commit-instant-squash
 
   Create a squash commit and instantly rebase.
 
+- Key: c A, magit-commit-augment
+
+  Create a squash commit, editing the squash message.
+
+  With a prefix argument the target commit has to be confirmed.
+  Otherwise the commit at point may be used without confirmation
+  depending on the value of option ~magit-commit-squash-confirm~.
+
 - User Option: magit-commit-ask-to-stage
 
   Whether to ask to stage everything when committing and nothing is
@@ -2561,6 +2670,11 @@ Also see [[info:gitman#git-branch]] and [[info:gitman#git-checkout]].
   The description is edited in a regular buffer similar to how commit
   messages are edited.
 
+- User Option: magit-branch-read-upstream-first
+
+  When creating a branch, whether to read the upstream branch before
+  the name of the branch that is to be created.
+
 ** Merging
 
 Also see [[info:gitman#git-merge]].
@@ -2689,7 +2803,22 @@ commands instead.
 
 - Key: RET, git-rebase-show-commit
 
-  Show the commit on the current line if any.
+  Show the commit on the current line in another buffer and select
+  that buffer.
+
+- Key: SPC, magit-diff-show-or-scroll-up
+
+  Show the commit on the current line in another buffer without
+  selecting that buffer.  If the revision buffer is already visible in
+  another window of the current frame, then instead scroll that window
+  up.
+
+- Key: DEL, magit-diff-show-or-scroll-down
+
+  Show the commit on the current line in another buffer without
+  selecting that buffer.  If the revision buffer is already visible in
+  another window of the current frame, then instead scroll that window
+  down.
 
 - Key: p, git-rebase-backward-line
 
@@ -3064,6 +3193,21 @@ Also see [[info:gitman#git-push]].
   Push a branch or commit to some remote branch.  Read the local and
   remote branch.
 
+- Key: P Q, magit-push-quickly
+
+  Push the current branch to some remote.  When the Git variable
+  ~magit.pushRemote~ is set, then push to that remote.  If that variable
+  is undefined or the remote does not exist, then push to "origin".
+  If that also doesn't exist then raise an error.  The local branch is
+  pushed to the remote branch with the same name.
+
+- Key: P i, magit-push-implicitly
+
+  Push without explicitly specifing what to push.  This runs ~git push
+  -v~.  What is being pushed depends on various Git variables as
+  described in the info:gitman#git-push and info:gitman#git-config
+  manpages.
+
 - Key: P m, magit-push-matching
 
   Push all matching branches to another repository.  If multiple
@@ -3080,6 +3224,26 @@ Also see [[info:gitman#git-push]].
 
   Push a tag to another repository.
 
+- User Option: magit-push-always-verify
+
+  Whether certain commands require verification before pushing.
+
+  Starting with ~v2.1.0~ some of the push commands are supposed to
+  push to the configured upstream branch without requiring user
+  confirmation or offering to push somewhere else.
+
+  This has taken a few users by surprise, and they suggested that we
+  force users to opt-in to this behavior.  Unfortunately adding this
+  option means that now other users will complain about us needlessly
+  forcing them to set an option.  This is an attempt to make everyone
+  happy and like all such attempts it is prone to fail.  Before
+  complaining about having to set this option, please consider that
+  other users are less experienced than you and have different needs.
+
+  You should set the value of this option to nil, causing all push
+  commands to behave as intended.  But first read the description of
+  each command above.
+
 ** Creating and sending patches
 
 - Key: W, magit-patch-popup
@@ -3261,6 +3425,10 @@ Also see [[info:gitman#git-submodule]].
 
   Fetch submodule.  With a prefix argument fetch all remotes.
 
+- Key: o i, magit-submodule-init
+
+  Unregister the submodule at PATH.
+
 ** Wip modes
 
 Git keeps *committed* changes around long enough for users to recover
diff --git a/Documentation/magit.texi b/Documentation/magit.texi
index 155eab5..688d633 100644
--- a/Documentation/magit.texi
+++ b/Documentation/magit.texi
@@ -712,6 +712,32 @@ appending @code{<N>} and thereby keeping Magit from re-using it to display
 other information of the same kind.
 
 With a prefix argument, the user can pick an arbitrary name.
+
+@kindex M-w
+@cindex magit-copy-buffer-thing-as-kill
+@item @kbd{M-w} @tie{}@tie{}@tie{}@tie{}(@code{magit-copy-buffer-thing-as-kill})
+
+This command saves a representation of the thing that is being
+displayed in the current buffer to the kill ring.
+
+In buffers in which it is undefined what this "buffer thing" is,
+this command instead saves the value of the current section, as
+@code{magit-copy-as-kill} would.
+
+When the region is active, then this command behaves like
+@code{kill-ring-save}.
+
+@kindex C-w
+@cindex magit-copy-as-kill
+@item @kbd{C-w} @tie{}@tie{}@tie{}@tie{}(@code{magit-copy-as-kill})
+
+This commands saves the value of the current section to the kill
+ring.  For commits it saves the full hash.  For branches it saves
+the branch name, except when a prefix argument is used, then it
+saves the full hash.
+
+When the region is active, then this command behaves like
+@code{kill-ring-save}.
 @end table
 
 @node Automatic save
@@ -1761,6 +1787,15 @@ Insert a header line showing the path to the repository top-level.
 @defun magit-insert-remote-header
 
 Insert a header line about the remote of the current branch.
+
+If no remote is configured for the current branch, then fall back
+showing the "origin" remote, or if that does not exist the first
+remote in alphabetic order.
+@end defun
+
+@defun magit-insert-user-header
+
+Insert a header line about the current user.
 @end defun
 
 @node Status options
@@ -1992,6 +2027,12 @@ Show or hide the Magit margin.
 The maximum number of commits to show in log and reflog buffers.
 @end defopt
 
+@defopt magit-log-show-refname-after-summary
+
+Whether to show the refnames after the commit summaries.  This is
+useful if you use really long branch names.
+@end defopt
+
 @node Select from log
 @subsection Select from log
 
@@ -2386,6 +2427,19 @@ would normally not look at the changes, e.g. because you are
 committing some binary files.
 @end defopt
 
+@defopt magit-diff-auto-show-delay
+
+How long to delay showing or updating the revision buffer, when
+that happens automatically (according to @code{magit-diff-auto-show}).
+
+When holding down a key to move by several lines, then that would
+update that buffer for each line on the way.  To prevent that,
+updating the revision buffer is delayed, and this option controls
+for how long it is delayed.  For optimal experience you might have
+to adjust this delay and/or the keyboard repeat rate and delay of
+your graphical environment or operating system.
+@end defopt
+
 @defopt magit-diff-refine-hunk
 
 Whether to show word-granularity differences within diff hunks.
@@ -2499,6 +2553,10 @@ common ancestor of both revisions (i.e., use a "@dots{}"  range).
 Resolve outstanding conflicts in a file using Ediff, defaulting to
 the file at point.
 
+Provided that the value of @code{merge.conflictstyle} is @code{diff3}, you can
+view the file's merge-base revision using @code{/} in the Ediff control
+buffer.
+
 In the rare event that you want to manually resolve all conflicts,
 including those already resolved by Git, use
 @code{ediff-merge-revisions-with-ancestor}.
@@ -2545,6 +2603,17 @@ point is on uncommitted hunks.  When nil, always run
 respectively.
 @end defopt
 
+@defopt magit-ediff-quit-hook
+
+This hook is run after quitting an Ediff session that was created
+using a Magit command.  The hook functions are run inside the Ediff
+control buffer, and should not change the current buffer.
+
+This is similar to @code{ediff-quit-hook} but takes the needs of Magit into
+account.  The regular @code{ediff-quit-hook} is ignored by Ediff sessions
+that were created using a Magit command.
+@end defopt
+
 @node References buffer
 @section References buffer
 
@@ -2668,6 +2737,45 @@ Indentation of cherries in refs buffers.  This should be N-1 where N
 is taken from "%Nc" in the above format strings.
 @end defvar
 
+Everywhere in Magit @code{RET} visits the thing represented by the section
+at point.  In almost all cases visiting is done by showing some
+information in another buffer and @strong{not} doing anything else.  In refs
+buffers @code{RET} behaves differently, and because many users have grown
+accustomed to that inconsistency we are keeping it that way.
+
+@table @asis
+@kindex RET
+@cindex magit-visit-ref
+@item @kbd{RET} @tie{}@tie{}@tie{}@tie{}(@code{magit-visit-ref})
+
+Everywhere except in refs buffers this command behaves exactly like
+@code{magit-show-commit}; it shows the commit at point in another buffer.
+
+In refs buffers, when there is a local branch at point, then this
+command instead checks out that branch.  When there is a remote
+branch or a tag at point then the respective commit is checked out
+causing @code{HEAD} to be detached.
+
+When a prefix argument it used, then this command only @strong{focuses} on
+the reference at point, i.e. the commit counts and cherries are
+updated to be relative to that reference, but nothing is checked
+out.
+
+@end table
+
+@defopt magit-visit-ref-create
+
+When this is non-nil and @code{magit-visit-ref} is called inside a refs
+buffer, then it "visits" the remote branch at point by creating a
+new local branch which tracks that remote branch and then checking
+out the newly created branch.
+
+This is not enabled by default because one has to use an extremely
+loose definition of the verb "to visit" to be able to argue that
+creating and then checking out a new local branch is a form of
+visiting a remote branch.
+@end defopt
+
 @menu
 * References sections::
 @end menu
@@ -2908,6 +3016,12 @@ Move to the previous chunk from the same commit.
 Turn off Magit-Blame mode.  If the buffer was created during a
 recursive blame, then also kill the buffer.
 
+@kindex M-w
+@cindex magit-blame-copy-hash
+@item @kbd{M-w} @tie{}@tie{}@tie{}@tie{}(@code{magit-blame-copy-hash})
+
+Save the hash of the current chunk's commit to the kill ring.
+
 @kindex t
 @cindex magit-blame-toggle-headings
 @item @kbd{t} @tie{}@tie{}@tie{}@tie{}(@code{magit-blame-toggle-headings})
@@ -2962,7 +3076,8 @@ Hook run by @code{magit-blame-next-chunk} and @code{magit-blame-previous-chunk}.
 @cindex magit-init
 @item @kbd{M-x magit-init} @tie{}@tie{}@tie{}@tie{}(@code{magit-init})
 
-Initialize a Git repository, then show its status.
+This command initializes a repository and then shows the status
+buffer for the new repository.
 
 If the directory is below an existing repository, then the user has
 to confirm that a new one should be created inside.  If the
@@ -2973,8 +3088,10 @@ to confirm that it should be reinitialized.
 @cindex magit-clone
 @item @kbd{M-x magit-clone} @tie{}@tie{}@tie{}@tie{}(@code{magit-clone})
 
-Clone a repository.  The user is queried for a remote url and a
-local directory.
+This command clones a repository and then shows the status buffer
+for the new repository.
+
+The user is queried for a remote url and a local directory.
 @end table
 
 @node Staging and unstaging
@@ -3120,8 +3237,7 @@ variants.
 @cindex magit-apply
 @item @kbd{a} @tie{}@tie{}@tie{}@tie{}(@code{magit-apply})
 
-Apply the change at point to the working tree.  With a prefix argument
-and if necessary, attempt a 3-way merge.
+Apply the change at point to the working tree.
 
 @kindex k
 @cindex magit-discard
@@ -3136,6 +3252,9 @@ Remove the change at point from the working tree.
 Reverse the change at point in the working tree.
 @end table
 
+With a prefix argument all apply variants attempt a 3-way merge when
+appropriate (i.e. when @code{git apply} is used internally).
+
 @node Committing
 @section Committing
 
@@ -3215,10 +3334,11 @@ ignore the option.
 @cindex magit-commit-fixup
 @item @kbd{c f} @tie{}@tie{}@tie{}@tie{}(@code{magit-commit-fixup})
 
-Create a fixup commit.  With a prefix argument the target commit has
-to be confirmed.  Otherwise the commit at point may be used without
-confirmation depending on the value of option
-@code{magit-commit-squash-confirm}.
+Create a fixup commit.
+
+With a prefix argument the target commit has to be confirmed.
+Otherwise the commit at point may be used without confirmation
+depending on the value of option @code{magit-commit-squash-confirm}.
 
 @kindex c F
 @cindex magit-commit-instant-fixup
@@ -3230,10 +3350,11 @@ Create a fixup commit and instantly rebase.
 @cindex magit-commit-squash
 @item @kbd{c s} @tie{}@tie{}@tie{}@tie{}(@code{magit-commit-squash})
 
-Create a squash commit.  With a prefix argument the target commit
-has to be confirmed.  Otherwise the commit at point may be used
-without confirmation depending on the value of option
-@code{magit-commit-squash-confirm}.
+Create a squash commit, without editing the squash message.
+
+With a prefix argument the target commit has to be confirmed.
+Otherwise the commit at point may be used without confirmation
+depending on the value of option @code{magit-commit-squash-confirm}.
 
 @kindex c S
 @cindex magit-commit-instant-squash
@@ -3241,6 +3362,16 @@ without confirmation depending on the value of option
 
 Create a squash commit and instantly rebase.
 
+@kindex c A
+@cindex magit-commit-augment
+@item @kbd{c A} @tie{}@tie{}@tie{}@tie{}(@code{magit-commit-augment})
+
+Create a squash commit, editing the squash message.
+
+With a prefix argument the target commit has to be confirmed.
+Otherwise the commit at point may be used without confirmation
+depending on the value of option @code{magit-commit-squash-confirm}.
+
 @end table
 
 @defopt magit-commit-ask-to-stage
@@ -3614,8 +3745,15 @@ Edit the description of a branch.  The branch is read in the
 minibuffer defaulting to the branch at point or the current branch.
 The description is edited in a regular buffer similar to how commit
 messages are edited.
+
 @end table
 
+@defopt magit-branch-read-upstream-first
+
+When creating a branch, whether to read the upstream branch before
+the name of the branch that is to be created.
+@end defopt
+
 @node Merging
 @section Merging
 
@@ -3830,7 +3968,26 @@ Git then cancels the commit, but leaves the file untouched.
 @cindex git-rebase-show-commit
 @item @kbd{RET} @tie{}@tie{}@tie{}@tie{}(@code{git-rebase-show-commit})
 
-Show the commit on the current line if any.
+Show the commit on the current line in another buffer and select
+that buffer.
+
+@kindex SPC
+@cindex magit-diff-show-or-scroll-up
+@item @kbd{SPC} @tie{}@tie{}@tie{}@tie{}(@code{magit-diff-show-or-scroll-up})
+
+Show the commit on the current line in another buffer without
+selecting that buffer.  If the revision buffer is already visible in
+another window of the current frame, then instead scroll that window
+up.
+
+@kindex DEL
+@cindex magit-diff-show-or-scroll-down
+@item @kbd{DEL} @tie{}@tie{}@tie{}@tie{}(@code{magit-diff-show-or-scroll-down})
+
+Show the commit on the current line in another buffer without
+selecting that buffer.  If the revision buffer is already visible in
+another window of the current frame, then instead scroll that window
+down.
 
 @kindex p
 @cindex git-rebase-backward-line
@@ -4465,6 +4622,49 @@ then read the remote branch.
 Push a branch or commit to some remote branch.  Read the local and
 remote branch.
 
+@kindex P Q
+@cindex magit-push-quickly
+@item @kbd{P Q} @tie{}@tie{}@tie{}@tie{}(@code{magit-push-quickly})
+
+Push the current branch to some remote.  When the Git variable
+@code{magit.pushRemote} is set, then push to that remote.  If that variable
+is undefined or the remote does not exist, then push to "origin".
+If that also doesn't exist then raise an error.  The local branch is
+pushed to the remote branch with the same name.
+
+@kindex P i
+@cindex magit-push-implicitly
+@item @kbd{P i} @tie{}@tie{}@tie{}@tie{}(@code{magit-push-implicitly})
+
+Push without explicitly specifing what to push.  This runs @code{git push
+  -v}.  What is being pushed depends on various Git variables as
+described in the 
+@ifinfo
+@ref{git-push,,,gitman,}
+@end ifinfo
+@ifhtml
+@html
+the <a href="http://git-scm.com/docs/git-push">git-push(1)</a> manpage
+@end html
+@end ifhtml
+@iftex
+the git-push(1) manpage
+@end iftex
+ and 
+@ifinfo
+@ref{git-config,,,gitman,}
+@end ifinfo
+@ifhtml
+@html
+the <a href="http://git-scm.com/docs/git-config">git-config(1)</a> manpage
+@end html
+@end ifhtml
+@iftex
+the git-config(1) manpage
+@end iftex
+
+manpages.
+
 @kindex P m
 @cindex magit-push-matching
 @item @kbd{P m} @tie{}@tie{}@tie{}@tie{}(@code{magit-push-matching})
@@ -4486,8 +4686,30 @@ remote configured for the current branch as default.
 @item @kbd{P T} @tie{}@tie{}@tie{}@tie{}(@code{magit-push-tag})
 
 Push a tag to another repository.
+
 @end table
 
+@defopt magit-push-always-verify
+
+Whether certain commands require verification before pushing.
+
+Starting with @code{v2.1.0} some of the push commands are supposed to
+push to the configured upstream branch without requiring user
+confirmation or offering to push somewhere else.
+
+This has taken a few users by surprise, and they suggested that we
+force users to opt-in to this behavior.  Unfortunately adding this
+option means that now other users will complain about us needlessly
+forcing them to set an option.  This is an attempt to make everyone
+happy and like all such attempts it is prone to fail.  Before
+complaining about having to set this option, please consider that
+other users are less experienced than you and have different needs.
+
+You should set the value of this option to nil, causing all push
+commands to behave as intended.  But first read the description of
+each command above.
+@end defopt
+
 @node Creating and sending patches
 @section Creating and sending patches
 
@@ -4803,6 +5025,12 @@ Update each submodule's remote URL according to ".gitmodules".
 @item @kbd{o f} @tie{}@tie{}@tie{}@tie{}(@code{magit-submodule-fetch})
 
 Fetch submodule.  With a prefix argument fetch all remotes.
+
+@kindex o i
+@cindex magit-submodule-init
+@item @kbd{o i} @tie{}@tie{}@tie{}@tie{}(@code{magit-submodule-init})
+
+Unregister the submodule at PATH.
 @end table
 
 @node Wip modes
@@ -4879,6 +5107,9 @@ which might seem excessive, but allows fine tuning of when exactly
 changes are being committed to the wip refs.  Enabling all modes makes
 it less likely that a change slips through the cracks.
 
+Setting the below variable directly does not take effect; either
+customize them or call the respective mode function.
+
 @defopt magit-wip-after-save-mode
 
 When this mode is enabled, then saving a buffer that visits a file