diff options
| -rw-r--r-- | Documentation/magit.org | 196 | ||||
| -rw-r--r-- | Documentation/magit.texi | 259 |
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 |