| 1 | This is magit.info, produced by makeinfo version 7.1.1 from magit.texi. |
| 2 | |
| 3 | Copyright (C) 2015-2026 Jonas Bernoulli |
| 4 | <emacs.magit@jonas.bernoulli.dev> |
| 5 | |
| 6 | You can redistribute this document and/or modify it under the terms |
| 7 | of the GNU General Public License as published by the Free Software |
| 8 | Foundation, either version 3 of the License, or (at your option) |
| 9 | any later version. |
| 10 | |
| 11 | This document is distributed in the hope that it will be useful, |
| 12 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 13 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
| 14 | General Public License for more details. |
| 15 | |
| 16 | INFO-DIR-SECTION Emacs |
| 17 | START-INFO-DIR-ENTRY |
| 18 | * Magit: (magit). Using Git from Emacs with Magit. |
| 19 | END-INFO-DIR-ENTRY |
| 20 | |
| 21 | |
| 22 | File: magit.info, Node: Top, Next: Introduction, Up: (dir) |
| 23 | |
| 24 | Magit User Manual |
| 25 | ***************** |
| 26 | |
| 27 | Magit is an interface to the version control system Git, implemented as |
| 28 | an Emacs package. Magit aspires to be a complete Git porcelain. While |
| 29 | we cannot (yet) claim that Magit wraps and improves upon each and every |
| 30 | Git command, it is complete enough to allow even experienced Git users |
| 31 | to perform almost all of their daily version control tasks directly from |
| 32 | within Emacs. While many fine Git clients exist, only Magit and Git |
| 33 | itself deserve to be called porcelains. |
| 34 | |
| 35 | This manual is for Magit version 4.7.1. |
| 36 | |
| 37 | Copyright (C) 2015-2026 Jonas Bernoulli |
| 38 | <emacs.magit@jonas.bernoulli.dev> |
| 39 | |
| 40 | You can redistribute this document and/or modify it under the terms |
| 41 | of the GNU General Public License as published by the Free Software |
| 42 | Foundation, either version 3 of the License, or (at your option) |
| 43 | any later version. |
| 44 | |
| 45 | This document is distributed in the hope that it will be useful, |
| 46 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 47 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
| 48 | General Public License for more details. |
| 49 | |
| 50 | * Menu: |
| 51 | |
| 52 | * Introduction:: |
| 53 | * Installation:: |
| 54 | * Getting Started:: |
| 55 | * Interface Concepts:: |
| 56 | * Inspecting:: |
| 57 | * Manipulating:: |
| 58 | * Transferring:: |
| 59 | * Miscellaneous:: |
| 60 | * Customizing:: |
| 61 | * Plumbing:: |
| 62 | * FAQ:: |
| 63 | * Debugging Tools:: |
| 64 | * Keystroke Index:: |
| 65 | * Function and Command Index:: |
| 66 | * Variable Index:: |
| 67 | |
| 68 | -- The Detailed Node Listing -- |
| 69 | |
| 70 | Installation |
| 71 | |
| 72 | * Installing from Melpa:: |
| 73 | * Installing from the Git Repository:: |
| 74 | * Post-Installation Tasks:: |
| 75 | |
| 76 | Interface Concepts |
| 77 | |
| 78 | * Modes and Buffers:: |
| 79 | * Sections:: |
| 80 | * Transient Commands:: |
| 81 | * Transient Arguments and Buffer Variables:: |
| 82 | * Completion, Confirmation and the Selection: Completion Confirmation and the Selection. |
| 83 | * Mouse Support:: |
| 84 | * Running Git:: |
| 85 | |
| 86 | Inspecting |
| 87 | |
| 88 | * Status Buffer:: |
| 89 | * Repository List:: |
| 90 | * Logging:: |
| 91 | * Diffing:: |
| 92 | * Ediffing:: |
| 93 | * References Buffer:: |
| 94 | * Bisecting:: |
| 95 | * Visiting Files and Blobs:: |
| 96 | * Blaming:: |
| 97 | |
| 98 | Manipulating |
| 99 | |
| 100 | * Creating Repository:: |
| 101 | * Cloning Repository:: |
| 102 | * Staging and Unstaging:: |
| 103 | * Applying:: |
| 104 | * Committing:: |
| 105 | * Branching:: |
| 106 | * Merging:: |
| 107 | * Resolving Conflicts:: |
| 108 | * Rebasing:: |
| 109 | * Cherry Picking:: |
| 110 | * Resetting:: |
| 111 | * Stashing:: |
| 112 | |
| 113 | Transferring |
| 114 | |
| 115 | * Remotes:: |
| 116 | * Fetching:: |
| 117 | * Pulling:: |
| 118 | * Pushing:: |
| 119 | * Plain Patches:: |
| 120 | * Maildir Patches:: |
| 121 | |
| 122 | Miscellaneous |
| 123 | |
| 124 | * Tagging:: |
| 125 | * Notes:: |
| 126 | * Submodules:: |
| 127 | * Subtree:: |
| 128 | * Worktree:: |
| 129 | * Sparse checkouts:: |
| 130 | * Bundle:: |
| 131 | * Common Commands:: |
| 132 | * Wip Modes:: |
| 133 | * Commands for Buffers Visiting Files:: |
| 134 | * Minor Mode for Buffers Visiting Blobs:: |
| 135 | |
| 136 | Customizing |
| 137 | |
| 138 | * Per-Repository Configuration:: |
| 139 | * Essential Settings:: |
| 140 | |
| 141 | Plumbing |
| 142 | |
| 143 | * Calling Git:: |
| 144 | * Section Plumbing:: |
| 145 | * Refreshing Buffers:: |
| 146 | * Conventions:: |
| 147 | |
| 148 | FAQ |
| 149 | |
| 150 | * FAQ - How to ...?:: |
| 151 | * FAQ - Issues and Errors:: |
| 152 | |
| 153 | |
| 154 | |
| 155 | File: magit.info, Node: Introduction, Next: Installation, Prev: Top, Up: Top |
| 156 | |
| 157 | 1 Introduction |
| 158 | ************** |
| 159 | |
| 160 | Magit is an interface to the version control system Git, implemented as |
| 161 | an Emacs package. Magit aspires to be a complete Git porcelain. While |
| 162 | we cannot (yet) claim that Magit wraps and improves upon each and every |
| 163 | Git command, it is complete enough to allow even experienced Git users |
| 164 | to perform almost all of their daily version control tasks directly from |
| 165 | within Emacs. While many fine Git clients exist, only Magit and Git |
| 166 | itself deserve to be called porcelains. |
| 167 | |
| 168 | Staging and otherwise applying changes is one of the most important |
| 169 | features in a Git porcelain and here Magit outshines anything else, |
| 170 | including Git itself. Git's own staging interface (‘git add --patch’) |
| 171 | is so cumbersome that many users only use it in exceptional cases. In |
| 172 | Magit staging a hunk or even just part of a hunk is as trivial as |
| 173 | staging all changes made to a file. |
| 174 | |
| 175 | The most visible part of Magit's interface is the status buffer, |
| 176 | which displays information about the current repository. Its content is |
| 177 | created by running several Git commands and making their output |
| 178 | actionable. Among other things, it displays information about the |
| 179 | current branch, lists unpulled and unpushed changes and contains |
| 180 | sections displaying the staged and unstaged changes. That might sound |
| 181 | noisy, but, since sections are collapsible, it's not. |
| 182 | |
| 183 | To stage or unstage a change one places the cursor on the change and |
| 184 | then types ‘s’ or ‘u’. The change can be a file or a hunk, or when the |
| 185 | region is active (i.e., when there is a selection) several files or |
| 186 | hunks, or even just part of a hunk. The change or changes that these |
| 187 | commands - and many others - would act on are highlighted. |
| 188 | |
| 189 | Magit also implements several other "apply variants" in addition to |
| 190 | staging and unstaging. One can discard or reverse a change, or apply it |
| 191 | to the working tree. Git's own porcelain only supports this for staging |
| 192 | and unstaging and you would have to do something like ‘git diff ... | |
| 193 | ??? | git apply ...’ to discard, revert, or apply a single hunk on the |
| 194 | command line. In fact that's exactly what Magit does internally (which |
| 195 | is what lead to the term "apply variants"). |
| 196 | |
| 197 | Magit isn't just for Git experts, but it does assume some prior |
| 198 | experience with Git as well as Emacs. That being said, many users have |
| 199 | reported that using Magit was what finally taught them what Git is |
| 200 | capable of and how to use it to its fullest. Other users wished they |
| 201 | had switched to Emacs sooner so that they would have gotten their hands |
| 202 | on Magit earlier. |
| 203 | |
| 204 | While one has to know the basic features of Emacs to be able to make |
| 205 | full use of Magit, acquiring just enough Emacs skills doesn't take long |
| 206 | and is worth it, even for users who prefer other editors. Vim users are |
| 207 | advised to give Evil (https://github.com/emacs-evil/evil), the |
| 208 | "Extensible VI Layer for Emacs", and Spacemacs |
| 209 | (https://github.com/syl20bnr/spacemacs), an "Emacs starter-kit focused |
| 210 | on Evil" a try. |
| 211 | |
| 212 | Magit provides a consistent and efficient Git porcelain. After a |
| 213 | short learning period, you will be able to perform most of your daily |
| 214 | version control tasks faster than you would on the command line. You |
| 215 | will likely also start using features that seemed too daunting in the |
| 216 | past. |
| 217 | |
| 218 | Magit fully embraces Git. It exposes many advanced features using a |
| 219 | simple but flexible interface instead of only wrapping the trivial ones |
| 220 | like many GUI clients do. Of course Magit supports logging, cloning, |
| 221 | pushing, and other commands that usually don't fail in spectacular ways; |
| 222 | but it also supports tasks that often cannot be completed in a single |
| 223 | step. Magit fully supports tasks such as merging, rebasing, |
| 224 | cherry-picking, reverting, and blaming by not only providing a command |
| 225 | to initiate these tasks but also by displaying context sensitive |
| 226 | information along the way and providing commands that are useful for |
| 227 | resolving conflicts and resuming the sequence after doing so. |
| 228 | |
| 229 | Magit wraps and in many cases improves upon at least the following |
| 230 | Git porcelain commands: ‘add’, ‘am’, ‘bisect’, ‘blame’, ‘branch’, |
| 231 | ‘checkout’, ‘cherry’, ‘cherry-pick’, ‘clean’, ‘clone’, ‘commit’, |
| 232 | ‘config’, ‘describe’, ‘diff’, ‘fetch’, ‘format-patch’, ‘init’, ‘log’, |
| 233 | ‘merge’, ‘merge-tree’, ‘mv’, ‘notes’, ‘pull’, ‘rebase’, ‘reflog’, |
| 234 | ‘remote’, ‘request-pull’, ‘reset’, ‘revert’, ‘rm’, ‘show’, ‘stash’, |
| 235 | ‘submodule’, ‘subtree’, ‘tag’, and ‘worktree.’ Many more Magit porcelain |
| 236 | commands are implemented on top of Git plumbing commands. |
| 237 | |
| 238 | |
| 239 | File: magit.info, Node: Installation, Next: Getting Started, Prev: Introduction, Up: Top |
| 240 | |
| 241 | 2 Installation |
| 242 | ************** |
| 243 | |
| 244 | Magit can be installed using Emacs' package manager or manually from its |
| 245 | development repository. |
| 246 | |
| 247 | * Menu: |
| 248 | |
| 249 | * Installing from Melpa:: |
| 250 | * Installing from the Git Repository:: |
| 251 | * Post-Installation Tasks:: |
| 252 | |
| 253 | |
| 254 | File: magit.info, Node: Installing from Melpa, Next: Installing from the Git Repository, Up: Installation |
| 255 | |
| 256 | 2.1 Installing from Melpa |
| 257 | ========================= |
| 258 | |
| 259 | Magit is available from Melpa and Melpa-Stable. If you haven't used |
| 260 | Emacs' package manager before, then it is high time you familiarize |
| 261 | yourself with it by reading the documentation in the Emacs manual, see |
| 262 | *note (emacs)Packages::. Then add one of the archives to |
| 263 | ‘package-archives’: |
| 264 | |
| 265 | • To use Melpa: |
| 266 | |
| 267 | (require 'package) |
| 268 | (add-to-list 'package-archives |
| 269 | '("melpa" . "https://melpa.org/packages/") t) |
| 270 | |
| 271 | • To use Melpa-Stable: |
| 272 | |
| 273 | (require 'package) |
| 274 | (add-to-list 'package-archives |
| 275 | '("melpa-stable" . "https://stable.melpa.org/packages/") t) |
| 276 | |
| 277 | Once you have added your preferred archive, you need to update the |
| 278 | local package list using: |
| 279 | |
| 280 | M-x package-refresh-contents RET |
| 281 | |
| 282 | Once you have done that, you can install Magit and its dependencies |
| 283 | using: |
| 284 | |
| 285 | M-x package-install RET magit RET |
| 286 | |
| 287 | Now see *note Post-Installation Tasks::. |
| 288 | |
| 289 | |
| 290 | File: magit.info, Node: Installing from the Git Repository, Next: Post-Installation Tasks, Prev: Installing from Melpa, Up: Installation |
| 291 | |
| 292 | 2.2 Installing from the Git Repository |
| 293 | ====================================== |
| 294 | |
| 295 | Magit depends on the ‘compat’, ‘cond-let’, ‘llama’, ‘seq’ (the built-in |
| 296 | version is enough when using Emacs >= 29.1), ‘transient’ and |
| 297 | ‘with-editor’ libraries which are available from Melpa and Melpa-Stable. |
| 298 | Install them using ‘M-x package-install RET <package> RET’. Of course |
| 299 | you may also install them manually from their repository. |
| 300 | |
| 301 | Then clone the Magit repository: |
| 302 | |
| 303 | $ git clone https://github.com/magit/magit.git ~/.emacs.d/site-lisp/magit |
| 304 | $ cd ~/.emacs.d/site-lisp/magit |
| 305 | |
| 306 | Then compile the libraries and generate the info manuals: |
| 307 | |
| 308 | $ make |
| 309 | |
| 310 | If you haven't installed ‘compat’, ‘cond-let’, ‘llama’, ‘seq’ (only |
| 311 | for Emacs 28), ‘transient’ and ‘with-editor’ from Melpa, or at |
| 312 | ‘/path/to/magit/../<package>’, then you have to tell ‘make’ where to |
| 313 | find them. To do so create the file ‘/path/to/magit/config.mk’ with the |
| 314 | following content before running ‘make’: |
| 315 | |
| 316 | LOAD_PATH = -L ~/.emacs.d/site-lisp/magit/lisp |
| 317 | LOAD_PATH += -L ~/.emacs.d/site-lisp/compat |
| 318 | LOAD_PATH += -L ~/.emacs.d/site-lisp/cond-let |
| 319 | LOAD_PATH += -L ~/.emacs.d/site-lisp/llama |
| 320 | LOAD_PATH += -L ~/.emacs.d/site-lisp/seq |
| 321 | LOAD_PATH += -L ~/.emacs.d/site-lisp/transient/lisp |
| 322 | LOAD_PATH += -L ~/.emacs.d/site-lisp/with-editor/lisp |
| 323 | |
| 324 | Finally add this to your init file: |
| 325 | |
| 326 | (add-to-list 'load-path "~/.emacs.d/site-lisp/magit/lisp") |
| 327 | (require 'magit) |
| 328 | |
| 329 | (with-eval-after-load 'info |
| 330 | (info-initialize) |
| 331 | (add-to-list 'Info-directory-list "~/.emacs.d/site-lisp/magit/docs/")) |
| 332 | |
| 333 | Of course if you installed the dependencies manually as well, then |
| 334 | you have to tell Emacs about them too, by prefixing the above with: |
| 335 | |
| 336 | (add-to-list 'load-path "~/.emacs.d/site-lisp/compat") |
| 337 | (add-to-list 'load-path "~/.emacs.d/site-lisp/cond-let") |
| 338 | (add-to-list 'load-path "~/.emacs.d/site-lisp/llama") |
| 339 | (add-to-list 'load-path "~/.emacs.d/site-lisp/seq") |
| 340 | (add-to-list 'load-path "~/.emacs.d/site-lisp/transient/lisp") |
| 341 | (add-to-list 'load-path "~/.emacs.d/site-lisp/with-editor") |
| 342 | |
| 343 | Note that you have to add the ‘lisp’ subdirectory to the ‘load-path’, |
| 344 | not the top-level of the repository, and that elements of ‘load-path’ |
| 345 | should not end with a slash, while those of ‘Info-directory-list’ |
| 346 | should. |
| 347 | |
| 348 | Instead of requiring the feature ‘magit’, you could load just the |
| 349 | autoload definitions, by loading the file ‘magit-autoloads.el’. |
| 350 | |
| 351 | (load "/path/to/magit/lisp/magit-autoloads") |
| 352 | |
| 353 | Instead of running Magit directly from the repository by adding that |
| 354 | to the ‘load-path’, you might want to instead install it in some other |
| 355 | directory using ‘sudo make install’ and setting ‘load-path’ accordingly. |
| 356 | |
| 357 | To update Magit use: |
| 358 | |
| 359 | $ git pull |
| 360 | $ make |
| 361 | |
| 362 | At times it might be necessary to run ‘make clean all’ instead. |
| 363 | |
| 364 | To view all available targets use ‘make help’. |
| 365 | |
| 366 | Now see *note Post-Installation Tasks::. |
| 367 | |
| 368 | |
| 369 | File: magit.info, Node: Post-Installation Tasks, Prev: Installing from the Git Repository, Up: Installation |
| 370 | |
| 371 | 2.3 Post-Installation Tasks |
| 372 | =========================== |
| 373 | |
| 374 | After installing Magit you should verify that you are indeed using the |
| 375 | Magit, Git, and Emacs releases you think you are using. It's best to |
| 376 | restart Emacs before doing so, to make sure you are not using an |
| 377 | outdated value for ‘load-path’. |
| 378 | |
| 379 | M-x magit-version RET |
| 380 | |
| 381 | should display something like |
| 382 | |
| 383 | Magit 2.8.0, Git 2.10.2, Emacs 25.1.1, gnu/linux |
| 384 | |
| 385 | Then you might also want to read about options that many users likely |
| 386 | want to customize. See *note Essential Settings::. |
| 387 | |
| 388 | To be able to follow cross references to Git manpages found in this |
| 389 | manual, you might also have to manually install the ‘gitman’ info |
| 390 | manual, or advice ‘Info-follow-nearest-node’ to instead open the actual |
| 391 | manpage. See *note How to install the gitman info manual?::. |
| 392 | |
| 393 | If you are completely new to Magit then see *note Getting Started::. |
| 394 | |
| 395 | If you run into problems, then please see the *note FAQ::. Also see |
| 396 | the *note Debugging Tools::. |
| 397 | |
| 398 | And last but not least please consider making a donation, to ensure |
| 399 | that I can keep working on Magit. See <https://magit.vc/donate>. for |
| 400 | various donation options. |
| 401 | |
| 402 | |
| 403 | File: magit.info, Node: Getting Started, Next: Interface Concepts, Prev: Installation, Up: Top |
| 404 | |
| 405 | 3 Getting Started |
| 406 | ***************** |
| 407 | |
| 408 | This short tutorial describes the most essential features that many |
| 409 | Magitians use on a daily basis. It only scratches the surface but |
| 410 | should be enough to get you started. |
| 411 | |
| 412 | IMPORTANT: It is safest if you clone some repository just for this |
| 413 | tutorial. Alternatively you can use an existing local repository, but |
| 414 | if you do that, then you should commit all uncommitted changes before |
| 415 | proceeding. |
| 416 | |
| 417 | Type ‘C-x g’ to display information about the current Git repository |
| 418 | in a dedicated buffer, called the status buffer. |
| 419 | |
| 420 | Most Magit commands are commonly invoked from the status buffer. It |
| 421 | can be considered the primary interface for interacting with Git using |
| 422 | Magit. Many other Magit buffers may exist at a given time, but they are |
| 423 | often created from this buffer. |
| 424 | |
| 425 | Depending on what state your repository is in, this buffer may |
| 426 | contain sections titled "Staged changes", "Unstaged changes", "Unmerged |
| 427 | into origin/master", "Unpushed to origin/master", and many others. |
| 428 | |
| 429 | Since we are starting from a safe state, which you can easily return |
| 430 | to (by doing a ‘git reset --hard PRE-MAGIT-STATE’), there currently are |
| 431 | no staged or unstaged changes. Edit some files and save the changes. |
| 432 | Then go back to the status buffer, while at the same time refreshing it, |
| 433 | by typing ‘C-x g’. (When the status buffer, or any Magit buffer for |
| 434 | that matter, is the current buffer, then you can also use just ‘g’ to |
| 435 | refresh it). |
| 436 | |
| 437 | Move between sections using ‘p’ and ‘n’. Note that the bodies of |
| 438 | some sections are hidden. Type ‘TAB’ to expand or collapse the section |
| 439 | at point. You can also use ‘C-tab’ to cycle the visibility of the |
| 440 | current section and its children. Move to a file section inside the |
| 441 | section named "Unstaged changes" and type ‘s’ to stage the changes you |
| 442 | have made to that file. That file now appears under "Staged changes". |
| 443 | |
| 444 | Magit can stage and unstage individual hunks, not just complete |
| 445 | files. Move to the file you have just staged, expand it using ‘TAB’, |
| 446 | move to one of the hunks using ‘n’, and unstage just that by typing ‘u’. |
| 447 | Note how the staging (‘s’) and unstaging (‘u’) commands operate on the |
| 448 | change at point. Many other commands behave the same way. |
| 449 | |
| 450 | You can also un-/stage just part of a hunk. Inside the body of a |
| 451 | hunk section (move there using ‘C-n’), set the mark using ‘C-SPC’ and |
| 452 | move down until some added and/or removed lines fall inside the region |
| 453 | but not all of them. Again type ‘s’ to stage. |
| 454 | |
| 455 | It is also possible to un-/stage multiple files at once. Move to a |
| 456 | file section, type ‘C-SPC’, move to the next file using ‘n’, and then |
| 457 | ‘s’ to stage both files. Note that both the mark and point have to be |
| 458 | on the headings of sibling sections for this to work. If the region |
| 459 | looks like it does in other buffers, then it doesn't select Magit |
| 460 | sections that can be acted on as a unit. |
| 461 | |
| 462 | And then of course you want to commit your changes. Type ‘c’. This |
| 463 | shows the available commit commands and arguments in a buffer at the |
| 464 | bottom of the frame. Each command and argument is prefixed with the key |
| 465 | that invokes/sets it. Do not worry about this for now. We want to |
| 466 | create a "normal" commit, which is done by typing ‘c’ again. |
| 467 | |
| 468 | Now two new buffers appear. One is for writing the commit message, |
| 469 | the other shows a diff with the changes that you are about to commit. |
| 470 | Write a message and then type ‘C-c C-c’ to actually create the commit. |
| 471 | |
| 472 | You probably don't want to push the commit you just created because |
| 473 | you just committed some random changes, but if that is not the case you |
| 474 | could push it by typing ‘P’ to show all the available push commands and |
| 475 | arguments and then ‘p’ to push to a branch with the same name as the |
| 476 | local branch onto the remote configured as the push-remote. (If the |
| 477 | push-remote is not configured yet, then you would first be prompted for |
| 478 | the remote to push to.) |
| 479 | |
| 480 | So far we have mentioned the commit and push menu commands. These |
| 481 | are probably among the menus you will be using the most, but many others |
| 482 | exist. To show a menu that lists all other menus (as well as the |
| 483 | various apply commands and some other essential commands), type ‘h’. |
| 484 | Try a few. (Such menus are also called "transient prefix commands" or |
| 485 | just "transients".) |
| 486 | |
| 487 | The key bindings in that menu correspond to the bindings in Magit |
| 488 | buffers, including but not limited to the status buffer. So you could |
| 489 | type ‘h d’ to bring up the diff menu, but once you remember that "d" |
| 490 | stands for "diff", you would usually do so by just typing ‘d’. |
| 491 | |
| 492 | This "prefix of prefixes" is useful even once you have memorized all |
| 493 | the bindings, as it can provide easy access to Magit commands from |
| 494 | non-Magit buffers. So, by default, it is globally bound to ‘C-x M-g’. |
| 495 | |
| 496 | A similar menu featuring (for the most part) commands that act on |
| 497 | just the file being visited in the current buffer, is globally bound to |
| 498 | ‘C-c M-g’. That binding can also be used in buffers, which do not visit |
| 499 | a file, but then only a subset of the commands is available. |
| 500 | |
| 501 | The global key bindings mentioned in the previous two paragraphs are |
| 502 | quite inconvenient. We recommend using ‘C-c g’ and ‘C-c f’ instead, but |
| 503 | cannot use those key sequences by default because they are strictly |
| 504 | reserved for bindings added by the user. See *note Global Bindings::, |
| 505 | if you want to explicitly opt-in to the recommended key bindings. |
| 506 | |
| 507 | Magit also provides context menus and other mouse commands, see *note |
| 508 | Mouse Support::. |
| 509 | |
| 510 | It is not necessary that you do so now, but if you stick with Magit, |
| 511 | then it is highly recommended that you read the next section too. |
| 512 | |
| 513 | |
| 514 | File: magit.info, Node: Interface Concepts, Next: Inspecting, Prev: Getting Started, Up: Top |
| 515 | |
| 516 | 4 Interface Concepts |
| 517 | ******************** |
| 518 | |
| 519 | * Menu: |
| 520 | |
| 521 | * Modes and Buffers:: |
| 522 | * Sections:: |
| 523 | * Transient Commands:: |
| 524 | * Transient Arguments and Buffer Variables:: |
| 525 | * Completion, Confirmation and the Selection: Completion Confirmation and the Selection. |
| 526 | * Mouse Support:: |
| 527 | * Running Git:: |
| 528 | |
| 529 | |
| 530 | File: magit.info, Node: Modes and Buffers, Next: Sections, Up: Interface Concepts |
| 531 | |
| 532 | 4.1 Modes and Buffers |
| 533 | ===================== |
| 534 | |
| 535 | Magit provides several major-modes. For each of these modes there |
| 536 | usually exists only one buffer per repository. Separate modes and thus |
| 537 | buffers exist for commits, diffs, logs, and some other things. |
| 538 | |
| 539 | Besides these special purpose buffers, there also exists an overview |
| 540 | buffer, called the *status buffer*. It's usually from this buffer that |
| 541 | the user invokes Git commands, or creates or visits other buffers. |
| 542 | |
| 543 | In this manual we often speak about "Magit buffers". By that we mean |
| 544 | buffers whose major-modes derive from ‘magit-mode’. |
| 545 | |
| 546 | ‘M-x magit-toggle-buffer-lock’ |
| 547 | This command locks the current buffer to its value or if the buffer |
| 548 | is already locked, then it unlocks it. |
| 549 | |
| 550 | Locking a buffer to its value prevents it from being reused to |
| 551 | display another value. The name of a locked buffer contains its |
| 552 | value, which allows telling it apart from other locked buffers and |
| 553 | the unlocked buffer. |
| 554 | |
| 555 | Not all Magit buffers can be locked to their values; for example, |
| 556 | it wouldn't make sense to lock a status buffer. |
| 557 | |
| 558 | There can only be a single unlocked buffer using a certain |
| 559 | major-mode per repository. So when a buffer is being unlocked and |
| 560 | another unlocked buffer already exists for that mode and |
| 561 | repository, then the former buffer is instead deleted and the |
| 562 | latter is displayed in its place. |
| 563 | |
| 564 | 4.1.1 Switching Buffers |
| 565 | ----------------------- |
| 566 | |
| 567 | -- Function: magit-display-buffer buffer &optional display-function |
| 568 | This function is a wrapper around ‘display-buffer’ and is used to |
| 569 | display any Magit buffer. It displays BUFFER in some window and, |
| 570 | unlike ‘display-buffer’, also selects that window, provided |
| 571 | ‘magit-display-buffer-noselect’ is ‘nil’. It also runs the hooks |
| 572 | mentioned below. |
| 573 | |
| 574 | If optional DISPLAY-FUNCTION is non-‘nil’, then that is used to |
| 575 | display the buffer. Usually that is ‘nil’ and the function |
| 576 | specified by ‘magit-display-buffer-function’ is used. |
| 577 | |
| 578 | -- Variable: magit-display-buffer-noselect |
| 579 | When this is non-‘nil’, then ‘magit-display-buffer’ only displays |
| 580 | the buffer but forgoes also selecting the window. This variable |
| 581 | should not be set globally, it is only intended to be let-bound, by |
| 582 | code that automatically updates "the other window". This is used |
| 583 | for example when the revision buffer is updated when you move |
| 584 | inside the log buffer. |
| 585 | |
| 586 | -- User Option: magit-display-buffer-function |
| 587 | The function specified here is called by ‘magit-display-buffer’ |
| 588 | with one argument, a buffer, to actually display that buffer. This |
| 589 | function should call ‘display-buffer’ with that buffer as first and |
| 590 | a list of display actions as second argument. |
| 591 | |
| 592 | Magit provides several functions, listed below, that are suitable |
| 593 | values for this option. If you want to use different rules, then a |
| 594 | good way of doing that is to start with a copy of one of these |
| 595 | functions and then adjust it to your needs. |
| 596 | |
| 597 | Instead of using a wrapper around ‘display-buffer’, that function |
| 598 | itself can be used here, in which case the display actions have to |
| 599 | be specified by adding them to ‘display-buffer-alist’ instead. |
| 600 | |
| 601 | To learn about display actions, see *note (elisp)Choosing Window::. |
| 602 | |
| 603 | -- Function: magit-display-buffer-traditional buffer |
| 604 | This function is the current default value of the option |
| 605 | ‘magit-display-buffer-function’. Before that option and this |
| 606 | function were added, the behavior was hard-coded in many places all |
| 607 | over the code base but now all the rules are contained in this one |
| 608 | function (except for the "noselect" special case mentioned above). |
| 609 | |
| 610 | -- Function: magit-display-buffer-same-window-except-diff-v1 |
| 611 | This function displays most buffers in the currently selected |
| 612 | window. If a buffer's mode derives from ‘magit-diff-mode’ or |
| 613 | ‘magit-process-mode’, it is displayed in another window. |
| 614 | |
| 615 | -- Function: magit-display-buffer-fullframe-status-v1 |
| 616 | This function fills the entire frame when displaying a status |
| 617 | buffer. Otherwise, it behaves like |
| 618 | ‘magit-display-buffer-traditional’. |
| 619 | |
| 620 | -- Function: magit-display-buffer-fullframe-status-topleft-v1 |
| 621 | This function fills the entire frame when displaying a status |
| 622 | buffer. It behaves like ‘magit-display-buffer-fullframe-status-v1’ |
| 623 | except that it displays buffers that derive from ‘magit-diff-mode’ |
| 624 | or ‘magit-process-mode’ to the top or left of the current buffer |
| 625 | rather than to the bottom or right. As a result, Magit buffers |
| 626 | tend to pop up on the same side as they would if |
| 627 | ‘magit-display-buffer-traditional’ were in use. |
| 628 | |
| 629 | -- Function: magit-display-buffer-fullcolumn-most-v1 |
| 630 | This function displays most buffers so that they fill the entire |
| 631 | height of the frame. However, the buffer is displayed in another |
| 632 | window if (1) the buffer's mode derives from ‘magit-process-mode’, |
| 633 | or (2) the buffer's mode derives from ‘magit-diff-mode’, provided |
| 634 | that the mode of the current buffer derives from ‘magit-log-mode’ |
| 635 | or ‘magit-cherry-mode’. |
| 636 | |
| 637 | -- User Option: magit-pre-display-buffer-hook |
| 638 | This hook is run by ‘magit-display-buffer’ before displaying the |
| 639 | buffer. |
| 640 | |
| 641 | -- Function: magit-save-window-configuration |
| 642 | This function saves the current window configuration. Later when |
| 643 | the buffer is buried, it may be restored by |
| 644 | ‘magit-restore-window-configuration’. |
| 645 | |
| 646 | -- User Option: magit-post-display-buffer-hook |
| 647 | This hook is run by ‘magit-display-buffer’ after displaying the |
| 648 | buffer. |
| 649 | |
| 650 | -- Function: magit-maybe-set-dedicated |
| 651 | This function remembers if a new window had to be created to |
| 652 | display the buffer, or whether an existing window was reused. This |
| 653 | information is later used by ‘magit-mode-quit-window’, to determine |
| 654 | whether the window should be deleted when its last Magit buffer is |
| 655 | buried. |
| 656 | |
| 657 | 4.1.2 Naming Buffers |
| 658 | -------------------- |
| 659 | |
| 660 | -- User Option: magit-generate-buffer-name-function |
| 661 | The function used to generate the names of Magit buffers. |
| 662 | |
| 663 | Such a function should take the options |
| 664 | ‘magit-uniquify-buffer-names’ as well as ‘magit-buffer-name-format’ |
| 665 | into account. If it doesn't, then should be clearly stated in the |
| 666 | doc-string. And if it supports %-sequences beyond those mentioned |
| 667 | in the doc-string of the option ‘magit-buffer-name-format’, then |
| 668 | its own doc-string should describe the additions. |
| 669 | |
| 670 | -- Function: magit-generate-buffer-name-default-function mode |
| 671 | This function returns a buffer name suitable for a buffer whose |
| 672 | major-mode is MODE and which shows information about the repository |
| 673 | in which ‘default-directory’ is located. |
| 674 | |
| 675 | This function uses ‘magit-buffer-name-format’ and supporting all of |
| 676 | the %-sequences mentioned the documentation of that option. It |
| 677 | also respects the option ‘magit-uniquify-buffer-names’. |
| 678 | |
| 679 | -- User Option: magit-buffer-name-format |
| 680 | The format string used to name Magit buffers. |
| 681 | |
| 682 | At least the following %-sequences are supported: |
| 683 | |
| 684 | • ‘%m’ |
| 685 | |
| 686 | The name of the major-mode, but with the ‘-mode’ suffix |
| 687 | removed. |
| 688 | |
| 689 | • ‘%M’ |
| 690 | |
| 691 | Like ‘%m’ but abbreviate ‘magit-status-mode’ as ‘magit’. |
| 692 | |
| 693 | • ‘%v’ |
| 694 | |
| 695 | The value the buffer is locked to, in parentheses, or an empty |
| 696 | string if the buffer is not locked to a value. |
| 697 | |
| 698 | • ‘%V’ |
| 699 | |
| 700 | Like ‘%v’, but the string is prefixed with a space, unless it |
| 701 | is an empty string. |
| 702 | |
| 703 | • ‘%t’ |
| 704 | |
| 705 | The top-level directory of the working tree of the repository, |
| 706 | or if ‘magit-uniquify-buffer-names’ is non-‘nil’ an |
| 707 | abbreviation of that. |
| 708 | |
| 709 | • ‘%x’ |
| 710 | |
| 711 | If ‘magit-uniquify-buffer-names’ is ‘nil’ "*", otherwise the |
| 712 | empty string. Due to limitations of the ‘uniquify’ package, |
| 713 | buffer names must end with the path. |
| 714 | |
| 715 | The value should always contain ‘%m’ or ‘%M’, ‘%v’ or ‘%V’, and |
| 716 | ‘%t’. If ‘magit-uniquify-buffer-names’ is non-‘nil’, then the |
| 717 | value must end with ‘%t’ or ‘%t%x’. See issue #2841. |
| 718 | |
| 719 | -- User Option: magit-uniquify-buffer-names |
| 720 | This option controls whether the names of Magit buffers are |
| 721 | uniquified. If the names are not being uniquified, then they |
| 722 | contain the full path of the top-level of the working tree of the |
| 723 | corresponding repository. If they are being uniquified, then they |
| 724 | end with the basename of the top-level, or if that would conflict |
| 725 | with the name used for other buffers, then the names of all these |
| 726 | buffers are adjusted until they no longer conflict. |
| 727 | |
| 728 | This is done using the ‘uniquify’ package; customize its options to |
| 729 | control how buffer names are uniquified. |
| 730 | |
| 731 | 4.1.3 Quitting Windows |
| 732 | ---------------------- |
| 733 | |
| 734 | ‘q’ (‘magit-mode-bury-buffer’) |
| 735 | This command buries or kills the current Magit buffer. The |
| 736 | function specified by option ‘magit-bury-buffer-function’ is used |
| 737 | to bury the buffer when called without a prefix argument or to kill |
| 738 | it when called with a single prefix argument. |
| 739 | |
| 740 | When called with two or more prefix arguments then it always kills |
| 741 | all Magit buffers, associated with the current project, including |
| 742 | the current buffer. |
| 743 | |
| 744 | -- User Option: magit-bury-buffer-function |
| 745 | The function used to actually bury or kill the current buffer. |
| 746 | |
| 747 | ‘magit-mode-bury-buffer’ calls this function with one argument. If |
| 748 | the argument is non-‘nil’, then the function has to kill the |
| 749 | current buffer. Otherwise it has to bury it alive. The default |
| 750 | value currently is ‘magit-mode-quit-window’. |
| 751 | |
| 752 | -- Function: magit-restore-window-configuration kill-buffer |
| 753 | Bury or kill the current buffer using ‘quit-window’, which is |
| 754 | called with KILL-BUFFER as first and the selected window as second |
| 755 | argument. |
| 756 | |
| 757 | Then restore the window configuration that existed right before the |
| 758 | current buffer was displayed in the selected frame. Unfortunately |
| 759 | that also means that point gets adjusted in all the buffers, which |
| 760 | are being displayed in the selected frame. |
| 761 | |
| 762 | -- Function: magit-mode-quit-window kill-buffer |
| 763 | Bury or kill the current buffer using ‘quit-window’, which is |
| 764 | called with KILL-BUFFER as first and the selected window as second |
| 765 | argument. |
| 766 | |
| 767 | Then, if the window was originally created to display a Magit |
| 768 | buffer and the buried buffer was the last remaining Magit buffer |
| 769 | that was ever displayed in the window, then that is deleted. |
| 770 | |
| 771 | 4.1.4 Automatic Refreshing of Magit Buffers |
| 772 | ------------------------------------------- |
| 773 | |
| 774 | After running a command which may change the state of the current |
| 775 | repository, the current Magit buffer and the corresponding status buffer |
| 776 | are refreshed. The status buffer can be automatically refreshed |
| 777 | whenever a buffer is saved to a file inside the respective repository by |
| 778 | adding a hook, like so: |
| 779 | |
| 780 | (with-eval-after-load 'magit-mode |
| 781 | (add-hook 'after-save-hook 'magit-after-save-refresh-status t)) |
| 782 | |
| 783 | Automatically refreshing Magit buffers ensures that the displayed |
| 784 | information is up-to-date most of the time but can lead to a noticeable |
| 785 | delay in big repositories. Other Magit buffers are not refreshed to |
| 786 | keep the delay to a minimum and also because doing so can sometimes be |
| 787 | undesirable. |
| 788 | |
| 789 | Buffers can also be refreshed explicitly, which is useful in buffers |
| 790 | that weren't current during the last refresh and after changes were made |
| 791 | to the repository outside of Magit. |
| 792 | |
| 793 | ‘g’ (‘magit-refresh’) |
| 794 | This command refreshes the current buffer if its major mode derives |
| 795 | from ‘magit-mode’ as well as the corresponding status buffer. |
| 796 | |
| 797 | If the option ‘magit-revert-buffers’ calls for it, then it also |
| 798 | reverts all unmodified buffers that visit files being tracked in |
| 799 | the current repository. |
| 800 | |
| 801 | ‘G’ (‘magit-refresh-all’) |
| 802 | This command refreshes all Magit buffers belonging to the current |
| 803 | repository and also reverts all unmodified buffers that visit files |
| 804 | being tracked in the current repository. |
| 805 | |
| 806 | The file-visiting buffers are always reverted, even if |
| 807 | ‘magit-revert-buffers’ is ‘nil’. |
| 808 | |
| 809 | -- User Option: magit-refresh-buffer-hook |
| 810 | This hook is run in each Magit buffer that was refreshed during the |
| 811 | current refresh - normally the current buffer and the status |
| 812 | buffer. |
| 813 | |
| 814 | -- User Option: magit-refresh-status-buffer |
| 815 | When this option is non-‘nil’, then the status buffer is |
| 816 | automatically refreshed after running git for side-effects, in |
| 817 | addition to the current Magit buffer, which is always refreshed |
| 818 | automatically. |
| 819 | |
| 820 | Only set this to ‘nil’ after exhausting all other options to |
| 821 | improve performance. |
| 822 | |
| 823 | -- Function: magit-after-save-refresh-status |
| 824 | This function is intended to be added to ‘after-save-hook’. After |
| 825 | doing that the corresponding status buffer is refreshed whenever a |
| 826 | buffer is saved to a file inside a repository. |
| 827 | |
| 828 | Note that refreshing a Magit buffer is done by re-creating its |
| 829 | contents from scratch, which can be slow in large repositories. If |
| 830 | you are not satisfied with Magit's performance, then you should |
| 831 | obviously not add this function to that hook. |
| 832 | |
| 833 | 4.1.5 Automatic Saving of File-Visiting Buffers |
| 834 | ----------------------------------------------- |
| 835 | |
| 836 | File-visiting buffers are by default saved at certain points in time. |
| 837 | This doesn't guarantee that Magit buffers are always up-to-date, but, |
| 838 | provided one only edits files by editing them in Emacs and uses only |
| 839 | Magit to interact with Git, one can be fairly confident. When in doubt |
| 840 | or after outside changes, type ‘g’ (‘magit-refresh’) to save and refresh |
| 841 | explicitly. |
| 842 | |
| 843 | -- User Option: magit-save-repository-buffers |
| 844 | This option controls whether file-visiting buffers are saved before |
| 845 | certain events. |
| 846 | |
| 847 | If this is non-‘nil’ then all modified file-visiting buffers |
| 848 | belonging to the current repository may be saved before running |
| 849 | commands, before creating new Magit buffers, and before explicitly |
| 850 | refreshing such buffers. If this is ‘dontask’ then this is done |
| 851 | without user intervention. If it is ‘t’ then the user has to |
| 852 | confirm each save. |
| 853 | |
| 854 | 4.1.6 Automatic Reverting of File-Visiting Buffers |
| 855 | -------------------------------------------------- |
| 856 | |
| 857 | By default Magit automatically reverts buffers that are visiting files |
| 858 | that are being tracked in a Git repository, after they have changed on |
| 859 | disk. When using Magit one often changes files on disk by running Git, |
| 860 | i.e., "outside Emacs", making this a rather important feature. |
| 861 | |
| 862 | For example, if you discard a change in the status buffer, then that |
| 863 | is done by running ‘git apply --reverse ...’, and Emacs considers the |
| 864 | file to have "changed on disk". If Magit did not automatically revert |
| 865 | the buffer, then you would have to type ‘M-x revert-buffer RET RET’ in |
| 866 | the visiting buffer before you could continue making changes. |
| 867 | |
| 868 | -- User Option: magit-auto-revert-mode |
| 869 | When this mode is enabled, then buffers that visit tracked files |
| 870 | are automatically reverted after the visited files change on disk. |
| 871 | |
| 872 | -- User Option: global-auto-revert-mode |
| 873 | When this mode is enabled, then any file-visiting buffer is |
| 874 | automatically reverted after the visited file changes on disk. |
| 875 | |
| 876 | If you like buffers that visit tracked files to be automatically |
| 877 | reverted, then you might also like any buffer to be reverted, not |
| 878 | just those visiting tracked files. If that is the case, then |
| 879 | enable this mode _instead of_ ‘magit-auto-revert-mode’. |
| 880 | |
| 881 | -- User Option: magit-auto-revert-immediately |
| 882 | This option controls whether Magit reverts buffers immediately. |
| 883 | |
| 884 | If this is non-‘nil’ and either ‘global-auto-revert-mode’ or |
| 885 | ‘magit-auto-revert-mode’ is enabled, then Magit immediately reverts |
| 886 | buffers by explicitly calling ‘auto-revert-buffers’ after running |
| 887 | Git for side-effects. |
| 888 | |
| 889 | If ‘auto-revert-use-notify’ is non-‘nil’ (and file notifications |
| 890 | are actually supported), then ‘magit-auto-revert-immediately’ does |
| 891 | not have to be non-‘nil’, because the reverts happen immediately |
| 892 | anyway. |
| 893 | |
| 894 | If ‘magit-auto-revert-immediately’ and ‘auto-revert-use-notify’ are |
| 895 | both ‘nil’, then reverts happen after ‘auto-revert-interval’ |
| 896 | seconds of user inactivity. That is not desirable. |
| 897 | |
| 898 | -- User Option: auto-revert-use-notify |
| 899 | This option controls whether file notification functions should be |
| 900 | used. Note that this variable unfortunately defaults to ‘t’ even |
| 901 | on systems on which file notifications cannot be used. |
| 902 | |
| 903 | -- User Option: magit-auto-revert-tracked-only |
| 904 | This option controls whether ‘magit-auto-revert-mode’ only reverts |
| 905 | tracked files or all files that are located inside Git |
| 906 | repositories, including untracked files and files located inside |
| 907 | Git's control directory. |
| 908 | |
| 909 | -- User Option: auto-revert-mode |
| 910 | The global mode ‘magit-auto-revert-mode’ works by turning on this |
| 911 | local mode in the appropriate buffers (but |
| 912 | ‘global-auto-revert-mode’ is implemented differently). You can |
| 913 | also turn it on or off manually, which might be necessary if Magit |
| 914 | does not notice that a previously untracked file now is being |
| 915 | tracked or vice-versa. |
| 916 | |
| 917 | -- User Option: auto-revert-stop-on-user-input |
| 918 | This option controls whether the arrival of user input suspends the |
| 919 | automatic reverts for ‘auto-revert-interval’ seconds. |
| 920 | |
| 921 | -- User Option: auto-revert-interval |
| 922 | This option controls how many seconds Emacs waits for before |
| 923 | resuming suspended reverts. |
| 924 | |
| 925 | -- User Option: auto-revert-buffer-list-filter |
| 926 | This option specifies an additional filter used by |
| 927 | ‘auto-revert-buffers’ to determine whether a buffer should be |
| 928 | reverted or not. |
| 929 | |
| 930 | This option is provided by Magit, which also advises |
| 931 | ‘auto-revert-buffers’ to respect it. Magit users who do not turn |
| 932 | on the local mode ‘auto-revert-mode’ themselves, are best served by |
| 933 | setting the value to ‘magit-auto-revert-repository-buffer-p’. |
| 934 | |
| 935 | However the default is ‘nil’, so as not to disturb users who do use |
| 936 | the local mode directly. If you experience delays when running |
| 937 | Magit commands, then you should consider using one of the |
| 938 | predicates provided by Magit - especially if you also use Tramp. |
| 939 | |
| 940 | Users who do turn on ‘auto-revert-mode’ in buffers in which Magit |
| 941 | doesn't do that for them, should likely not use any filter. Users |
| 942 | who turn on ‘global-auto-revert-mode’, do not have to worry about |
| 943 | this option, because it is disregarded if the global mode is |
| 944 | enabled. |
| 945 | |
| 946 | -- User Option: auto-revert-verbose |
| 947 | This option controls whether Emacs reports when a buffer has been |
| 948 | reverted. |
| 949 | |
| 950 | The options with the ‘auto-revert-’ prefix are located in the Custom |
| 951 | group named ‘auto-revert’. The other, Magit-specific, options are |
| 952 | located in the ‘magit’ group. |
| 953 | |
| 954 | Risk of Reverting Automatically |
| 955 | ............................... |
| 956 | |
| 957 | For the vast majority of users, automatically reverting file-visiting |
| 958 | buffers after they have changed on disk is harmless. |
| 959 | |
| 960 | If a buffer is modified (i.e., it contains changes that haven't been |
| 961 | saved yet), then Emacs will refuse to automatically revert it. If you |
| 962 | save a previously modified buffer, then that results in what is seen by |
| 963 | Git as an uncommitted change. Git will then refuse to carry out any |
| 964 | commands that would cause these changes to be lost. In other words, if |
| 965 | there is anything that could be lost, then either Git or Emacs will |
| 966 | refuse to discard the changes. |
| 967 | |
| 968 | However, if you use file-visiting buffers as a sort of ad hoc |
| 969 | "staging area", then the automatic reverts could potentially cause data |
| 970 | loss. So far I have heard from only one user who uses such a workflow. |
| 971 | |
| 972 | An example: You visit some file in a buffer, edit it, and save the |
| 973 | changes. Then, outside of Emacs (or at least not using Magit or by |
| 974 | saving the buffer) you change the file on disk again. At this point the |
| 975 | buffer is the only place where the intermediate version still exists. |
| 976 | You have saved the changes to disk, but that has since been overwritten. |
| 977 | Meanwhile Emacs considers the buffer to be unmodified (because you have |
| 978 | not made any changes to it since you last saved it to the visited file) |
| 979 | and therefore would not object to it being automatically reverted. At |
| 980 | this point an Auto-Revert mode would kick in. It would check whether |
| 981 | the buffer is modified and since that is not the case it would revert |
| 982 | it. The intermediate version would be lost. (Actually you could still |
| 983 | get it back using the ‘undo’ command.) |
| 984 | |
| 985 | If your workflow depends on Emacs preserving the intermediate version |
| 986 | in the buffer, then you have to disable all Auto-Revert modes. But |
| 987 | please consider that such a workflow would be dangerous even without |
| 988 | using an Auto-Revert mode, and should therefore be avoided. If Emacs |
| 989 | crashes or if you quit Emacs by mistake, then you would also lose the |
| 990 | buffer content. There would be no autosave file still containing the |
| 991 | intermediate version (because that was deleted when you saved the |
| 992 | buffer) and you would not be asked whether you want to save the buffer |
| 993 | (because it isn't modified). |
| 994 | |
| 995 | |
| 996 | File: magit.info, Node: Sections, Next: Transient Commands, Prev: Modes and Buffers, Up: Interface Concepts |
| 997 | |
| 998 | 4.2 Sections |
| 999 | ============ |
| 1000 | |
| 1001 | Magit buffers are organized into nested sections, which can be collapsed |
| 1002 | and expanded, similar to how sections are handled in Org mode. Each |
| 1003 | section also has a type, and some sections also have a value. For each |
| 1004 | section type there can also be a local keymap, shared by all sections of |
| 1005 | that type. |
| 1006 | |
| 1007 | Taking advantage of the section value and type, many commands operate |
| 1008 | on the current section, or when the region is active and selects |
| 1009 | sections of the same type, all of the selected sections. Commands that |
| 1010 | only make sense for a particular section type (as opposed to just |
| 1011 | behaving differently depending on the type) are usually bound in section |
| 1012 | type keymaps. |
| 1013 | |
| 1014 | 4.2.1 Section Movement |
| 1015 | ---------------------- |
| 1016 | |
| 1017 | To move within a section use the usual keys (‘C-p’, ‘C-n’, ‘C-b’, ‘C-f’ |
| 1018 | etc), whose global bindings are not shadowed. To move to another |
| 1019 | section use the following commands. |
| 1020 | |
| 1021 | The section movement commands described here run the hook |
| 1022 | ‘magit-section-movement-hook’. Note that they explicitly run that hook |
| 1023 | and that arbitrary other movement, defined in Emacs and other packages, |
| 1024 | do not run that hook. That hook, and hook functions that can be added |
| 1025 | to it, or are part of its default value, are described below. |
| 1026 | |
| 1027 | ‘p’ (‘magit-section-backward’) |
| 1028 | When not at the beginning of a section, then move to the beginning |
| 1029 | of the current section. At the beginning of a section, instead |
| 1030 | move to the beginning of the previous visible section. |
| 1031 | |
| 1032 | ‘n’ (‘magit-section-forward’) |
| 1033 | Move to the beginning of the next visible section. |
| 1034 | |
| 1035 | ‘M-p’ (‘magit-section-backward-siblings’) |
| 1036 | Move to the beginning of the previous sibling section. If there is |
| 1037 | no previous sibling section, then move to the parent section |
| 1038 | instead. |
| 1039 | |
| 1040 | ‘M-n’ (‘magit-section-forward-siblings’) |
| 1041 | Move to the beginning of the next sibling section. If there is no |
| 1042 | next sibling section, then move to the parent section instead. |
| 1043 | |
| 1044 | ‘^’ (‘magit-section-up’) |
| 1045 | Move to the beginning of the parent of the current section. |
| 1046 | |
| 1047 | The above commands all call the hook ‘magit-section-movement-hook’. |
| 1048 | Any of the functions listed below can be used as members of this hook. |
| 1049 | |
| 1050 | You might want to remove some of the functions that Magit adds using |
| 1051 | ‘add-hook’. In doing so you have to make sure you do not attempt to |
| 1052 | remove function that haven't even been added yet, for example: |
| 1053 | |
| 1054 | (with-eval-after-load 'magit-diff |
| 1055 | (remove-hook 'magit-section-movement-hook |
| 1056 | 'magit-hunk-set-window-start)) |
| 1057 | |
| 1058 | -- Variable: magit-section-movement-hook |
| 1059 | This hook is run by all of the above section movement commands, |
| 1060 | after arriving at the destination. It is *not* run by arbitrary |
| 1061 | other movement commands (such as ‘next-line’), which are provided |
| 1062 | by Emacs or third-party packages. |
| 1063 | |
| 1064 | -- Function: magit-hunk-set-window-start |
| 1065 | This hook function ensures that the beginning of the current |
| 1066 | section is visible, provided it is a ‘hunk’ section. Otherwise, it |
| 1067 | does nothing. |
| 1068 | |
| 1069 | Loading ‘magit-diff’ adds this function to the hook. |
| 1070 | |
| 1071 | -- Function: magit-section-set-window-start |
| 1072 | This hook function ensures that the beginning of the current |
| 1073 | section is visible, regardless of the section's type. If you add |
| 1074 | this to ‘magit-section-movement-hook’, then you must remove the |
| 1075 | hunk-only variant in turn. |
| 1076 | |
| 1077 | -- Function: magit-log-maybe-show-more-commits |
| 1078 | This hook function only has an effect in log buffers, and ‘point’ |
| 1079 | is on the "show more" section. If that is the case, then it |
| 1080 | doubles the number of commits that are being shown. |
| 1081 | |
| 1082 | Loading ‘magit-log’ adds this function to the hook. |
| 1083 | |
| 1084 | -- Function: magit-log-maybe-update-revision-buffer |
| 1085 | When moving inside a log buffer, then this function updates the |
| 1086 | revision buffer, provided it is already being displayed in another |
| 1087 | window of the same frame. |
| 1088 | |
| 1089 | Loading ‘magit-log’ adds this function to the hook. |
| 1090 | |
| 1091 | -- Function: magit-log-maybe-update-blob-buffer |
| 1092 | When moving inside a log buffer and another window of the same |
| 1093 | frame displays a blob buffer, then this function instead displays |
| 1094 | the blob buffer for the commit at point in that window. |
| 1095 | |
| 1096 | -- Function: magit-status-maybe-update-revision-buffer |
| 1097 | When moving inside a status buffer, then this function updates the |
| 1098 | revision buffer, provided it is already being displayed in another |
| 1099 | window of the same frame. |
| 1100 | |
| 1101 | -- Function: magit-status-maybe-update-stash-buffer |
| 1102 | When moving inside a status buffer, then this function updates the |
| 1103 | stash buffer, provided it is already being displayed in another |
| 1104 | window of the same frame. |
| 1105 | |
| 1106 | -- Function: magit-status-maybe-update-blob-buffer |
| 1107 | When moving inside a status buffer and another window of the same |
| 1108 | frame displays a blob buffer, then this function instead displays |
| 1109 | the blob buffer for the commit at point in that window. |
| 1110 | |
| 1111 | -- Function: magit-stashes-maybe-update-stash-buffer |
| 1112 | When moving inside a buffer listing stashes, then this function |
| 1113 | updates the stash buffer, provided it is already being displayed in |
| 1114 | another window of the same frame. |
| 1115 | |
| 1116 | -- User Option: magit-update-other-window-delay |
| 1117 | Delay before automatically updating the other window. |
| 1118 | |
| 1119 | When moving around in certain buffers using Magit's own section |
| 1120 | movement commands (but not other movement commands), then certain |
| 1121 | other buffers, which are being displayed in another window, may |
| 1122 | optionally be updated to display information about the section at |
| 1123 | point. |
| 1124 | |
| 1125 | When holding down a key to move by more than just one section, then |
| 1126 | that would update that buffer for each section on the way. To |
| 1127 | prevent that, updating the revision buffer is delayed, and this |
| 1128 | option controls for how long. For optimal experience you might |
| 1129 | have to adjust this delay and/or the keyboard repeat rate and delay |
| 1130 | of your graphical environment or operating system. |
| 1131 | |
| 1132 | 4.2.2 Section Visibility |
| 1133 | ------------------------ |
| 1134 | |
| 1135 | Magit provides many commands for changing the visibility of sections, |
| 1136 | but all you need to get started are the next two. |
| 1137 | |
| 1138 | ‘<TAB>’ (‘magit-section-toggle’) |
| 1139 | Toggle the visibility of the body of the current section. |
| 1140 | |
| 1141 | ‘C-c <TAB>’ (‘magit-section-cycle’) |
| 1142 | ‘C-<tab>’ (‘magit-section-cycle’) |
| 1143 | Cycle the visibility of current section and its children. |
| 1144 | |
| 1145 | If this command is invoked using ‘C-<tab>’ and that is globally |
| 1146 | bound to ‘tab-next’, then this command pivots to behave like that |
| 1147 | command, and you must instead use ‘C-c TAB’ to cycle section |
| 1148 | visibility. |
| 1149 | |
| 1150 | If you would like to keep using ‘C-<tab>’ to cycle section |
| 1151 | visibility but also want to use ‘tab-bar-mode’, then you have to |
| 1152 | prevent that mode from using this key and instead bind another key |
| 1153 | to ‘tab-next’. Because ‘tab-bar-mode’ does not use a mode map but |
| 1154 | instead manipulates the global map, this involves advising |
| 1155 | ‘tab-bar--define-keys’. |
| 1156 | |
| 1157 | ‘M-<tab>’ (‘magit-section-cycle-diffs’) |
| 1158 | Cycle the visibility of diff-related sections in the current |
| 1159 | buffer. |
| 1160 | |
| 1161 | ‘S-<tab>’ (‘magit-section-cycle-global’) |
| 1162 | Cycle the visibility of all sections in the current buffer. |
| 1163 | |
| 1164 | ‘1’ (‘magit-section-show-level-1’) |
| 1165 | ‘2’ (‘magit-section-show-level-2’) |
| 1166 | ‘3’ (‘magit-section-show-level-3’) |
| 1167 | ‘4’ (‘magit-section-show-level-4’) |
| 1168 | Show sections surrounding the current section up to level N. |
| 1169 | |
| 1170 | ‘M-1’ (‘magit-section-show-level-1-all’) |
| 1171 | ‘M-2’ (‘magit-section-show-level-2-all’) |
| 1172 | ‘M-3’ (‘magit-section-show-level-3-all’) |
| 1173 | ‘M-4’ (‘magit-section-show-level-4-all’) |
| 1174 | Show all sections up to level N. |
| 1175 | |
| 1176 | Some functions, which are used to implement the above commands, are |
| 1177 | also exposed as commands themselves. By default no keys are bound to |
| 1178 | these commands, as they are generally perceived to be much less useful. |
| 1179 | But your mileage may vary. |
| 1180 | |
| 1181 | -- Command: magit-section-show |
| 1182 | Show the body of the current section. |
| 1183 | |
| 1184 | -- Command: magit-section-hide |
| 1185 | Hide the body of the current section. |
| 1186 | |
| 1187 | -- Command: magit-section-show-headings |
| 1188 | Recursively show headings of children of the current section. Only |
| 1189 | show the headings. Previously shown text-only bodies are hidden. |
| 1190 | |
| 1191 | -- Command: magit-section-show-children |
| 1192 | Recursively show the bodies of children of the current section. |
| 1193 | With a prefix argument show children down to the level of the |
| 1194 | current section, and hide deeper children. |
| 1195 | |
| 1196 | -- Command: magit-section-hide-children |
| 1197 | Recursively hide the bodies of children of the current section. |
| 1198 | |
| 1199 | -- Command: magit-section-toggle-children |
| 1200 | Toggle visibility of bodies of children of the current section. |
| 1201 | |
| 1202 | When a buffer is first created then some sections are shown expanded |
| 1203 | while others are not. This is hard coded. When a buffer is refreshed |
| 1204 | then the previous visibility is preserved. The initial visibility of |
| 1205 | certain sections can also be overwritten using the hook |
| 1206 | ‘magit-section-set-visibility-hook’. |
| 1207 | |
| 1208 | -- User Option: magit-section-initial-visibility-alist |
| 1209 | This options can be used to override the initial visibility of |
| 1210 | sections. In the future it will also be used to define the |
| 1211 | defaults, but currently a section's default is still hardcoded. |
| 1212 | |
| 1213 | The value is an alist. Each element maps a section type or lineage |
| 1214 | to the initial visibility state for such sections. The state has |
| 1215 | to be one of ‘show’ or ‘hide’, or a function that returns one of |
| 1216 | these symbols. A function is called with the section as the only |
| 1217 | argument. |
| 1218 | |
| 1219 | Use the command ‘magit-describe-section-briefly’ to determine a |
| 1220 | section's lineage or type. The vector in the output is the section |
| 1221 | lineage and the type is the first element of that vector. |
| 1222 | Wildcards can be used, see ‘magit-section-match’. |
| 1223 | |
| 1224 | -- User Option: magit-section-cache-visibility |
| 1225 | This option controls for which sections the previous visibility |
| 1226 | state should be restored if a section disappears and later appears |
| 1227 | again. The value is a boolean or a list of section types. If ‘t’, |
| 1228 | then the visibility of all sections is cached. Otherwise this is |
| 1229 | only done for sections whose type matches one of the listed types. |
| 1230 | |
| 1231 | This requires that the function ‘magit-section-cached-visibility’ |
| 1232 | is a member of ‘magit-section-set-visibility-hook’. |
| 1233 | |
| 1234 | -- Variable: magit-section-set-visibility-hook |
| 1235 | This hook is run when first creating a buffer and also when |
| 1236 | refreshing an existing buffer, and is used to determine the |
| 1237 | visibility of the section currently being inserted. |
| 1238 | |
| 1239 | Each function is called with one argument, the section being |
| 1240 | inserted. It should return ‘hide’ or ‘show’, or to leave the |
| 1241 | visibility undefined ‘nil’. If no function decides on the |
| 1242 | visibility and the buffer is being refreshed, then the visibility |
| 1243 | is preserved; or if the buffer is being created, then the hard |
| 1244 | coded default is used. |
| 1245 | |
| 1246 | Usually this should only be used to set the initial visibility but |
| 1247 | not during refreshes. If ‘magit-insert-section--oldroot’ is |
| 1248 | non-‘nil’, then the buffer is being refreshed and these functions |
| 1249 | should immediately return ‘nil’. |
| 1250 | |
| 1251 | -- User Option: magit-section-visibility-indicators |
| 1252 | This option controls whether and how to indicate that a section can |
| 1253 | be expanded/collapsed. |
| 1254 | |
| 1255 | If ‘nil’, then don't show any indicators. Otherwise the value has |
| 1256 | to be a list with two elements. The first controls the indicators |
| 1257 | used in graphical frames, the second the indicators in terminal |
| 1258 | frames. For graphical frames all of the following forms are valid, |
| 1259 | while terminal frames do not have fringes and thus do not support |
| 1260 | the first form. |
| 1261 | |
| 1262 | • ‘(EXPANDABLE-BITMAP . COLLAPSIBLE-BITMAP)’ |
| 1263 | |
| 1264 | Both values have to be variables whose values are fringe |
| 1265 | bitmaps. In this case every section that can be expanded or |
| 1266 | collapsed gets an indicator in the left fringe. |
| 1267 | |
| 1268 | To provide extra padding around the indicator, set |
| 1269 | ‘left-fringe-width’ in ‘magit-mode-hook’, e.g.: |
| 1270 | |
| 1271 | (add-hook 'magit-mode-hook |
| 1272 | (lambda () (setq left-fringe-width 20))) |
| 1273 | |
| 1274 | • ‘(EXPANDABLE-CHAR . COLLAPSIBLE-CHAR)’ |
| 1275 | |
| 1276 | In this case every section that can be expanded or collapsed |
| 1277 | gets an indicator in the left margin. |
| 1278 | |
| 1279 | • ‘(STRING . BOOLEAN)’ |
| 1280 | |
| 1281 | In this case STRING (usually an ellipsis) is shown at the end |
| 1282 | of the heading of every collapsed section. Expanded sections |
| 1283 | get no indicator. The cdr controls whether the appearance of |
| 1284 | these ellipsis take section highlighting into account. Doing |
| 1285 | so might potentially have an impact on performance, while not |
| 1286 | doing so is kinda ugly. |
| 1287 | |
| 1288 | 4.2.3 Section Hooks |
| 1289 | ------------------- |
| 1290 | |
| 1291 | Which sections are inserted into certain buffers is controlled with |
| 1292 | hooks. This includes the status and the refs buffers. For other |
| 1293 | buffers, e.g., log and diff buffers, this is not possible. The command |
| 1294 | ‘magit-describe-section’ can be used to see which hook (if any) was |
| 1295 | responsible for inserting the section at point. |
| 1296 | |
| 1297 | For buffers whose sections can be customized by the user, a hook |
| 1298 | variable called ‘magit-TYPE-sections-hook’ exists. This hook should be |
| 1299 | changed using ‘magit-add-section-hook’. Avoid using ‘add-hooks’ or the |
| 1300 | Custom interface. |
| 1301 | |
| 1302 | The various available section hook variables are described later in |
| 1303 | this manual along with the appropriate "section inserter functions". |
| 1304 | |
| 1305 | -- Function: magit-add-section-hook hook function &optional at append |
| 1306 | local |
| 1307 | Add the function FUNCTION to the value of section hook HOOK. |
| 1308 | |
| 1309 | Add FUNCTION at the beginning of the hook list unless optional |
| 1310 | APPEND is non-‘nil’, in which case FUNCTION is added at the end. |
| 1311 | If FUNCTION already is a member then move it to the new location. |
| 1312 | |
| 1313 | If optional AT is non-‘nil’ and a member of the hook list, then add |
| 1314 | FUNCTION next to that instead. Add before or after AT, or replace |
| 1315 | AT with FUNCTION depending on APPEND. If APPEND is the symbol |
| 1316 | ‘replace’, then replace AT with FUNCTION. For any other non-‘nil’ |
| 1317 | value place FUNCTION right after AT. If ‘nil’, then place FUNCTION |
| 1318 | right before AT. If FUNCTION already is a member of the list but |
| 1319 | AT is not, then leave FUNCTION where ever it already is. |
| 1320 | |
| 1321 | If optional LOCAL is non-‘nil’, then modify the hook's buffer-local |
| 1322 | value rather than its global value. This makes the hook local by |
| 1323 | copying the default value. That copy is then modified. |
| 1324 | |
| 1325 | HOOK should be a symbol. If HOOK is void, it is first set to |
| 1326 | ‘nil’. HOOK's value must not be a single hook function. FUNCTION |
| 1327 | should be a function that takes no arguments and inserts one or |
| 1328 | multiple sections at point, moving point forward. FUNCTION may |
| 1329 | choose not to insert its section(s), when doing so would not make |
| 1330 | sense. It should not be abused for other side-effects. |
| 1331 | |
| 1332 | To remove a function from a section hook, use ‘remove-hook’. |
| 1333 | |
| 1334 | 4.2.4 Section Types and Values |
| 1335 | ------------------------------ |
| 1336 | |
| 1337 | Each section has a type, for example ‘hunk’, ‘file’, and ‘commit’. |
| 1338 | Instances of certain section types also have a value. The value of a |
| 1339 | section of type ‘file’, for example, is a file name. |
| 1340 | |
| 1341 | Users usually do not have to worry about a section's type and value, |
| 1342 | but knowing them can be handy at times. |
| 1343 | |
| 1344 | ‘H’ (‘magit-describe-section’) |
| 1345 | This command shows information about the section at point in a |
| 1346 | separate buffer. |
| 1347 | |
| 1348 | The main purpose of this command is to direct the user to the |
| 1349 | function used to insert the section at point, and to the hook, from |
| 1350 | which that function is called. This information is useful, for |
| 1351 | example, if one wants to stop displaying a certain section. Or if |
| 1352 | one wants to learn about related options. |
| 1353 | |
| 1354 | That function may also be responsible for inserting the parent and |
| 1355 | siblings of the section at point. If that is the case, this |
| 1356 | command identifies that ancestor section, not the actual section at |
| 1357 | point. |
| 1358 | |
| 1359 | Use ‘magit-describe-section-briefly’ to always identify precisely |
| 1360 | the innermost section at point. |
| 1361 | |
| 1362 | -- Command: magit-describe-section-briefly |
| 1363 | This command shows information about the section at point in the |
| 1364 | echo area, as ‘#<magit-section VALUE [TYPE PARENT-TYPE...] |
| 1365 | BEGINNING-END>’. |
| 1366 | |
| 1367 | Many commands behave differently depending on the type of the section |
| 1368 | at point and/or somehow consume the value of that section. But that is |
| 1369 | only one of the reasons why the same key may do something different, |
| 1370 | depending on what section is current. |
| 1371 | |
| 1372 | Additionally for each section type a keymap *might* be defined, named |
| 1373 | ‘magit-TYPE-section-map’. That keymap is used as text property keymap |
| 1374 | of all text belonging to any section of the respective type. If such a |
| 1375 | map does not exist for a certain type, then you can define it yourself, |
| 1376 | and it will automatically be used. |
| 1377 | |
| 1378 | 4.2.5 Section Options |
| 1379 | --------------------- |
| 1380 | |
| 1381 | This section describes options that have an effect on more than just a |
| 1382 | certain type of sections. As you can see there are not many of those. |
| 1383 | |
| 1384 | -- User Option: magit-section-show-child-count |
| 1385 | Whether to append the number of children to section headings. This |
| 1386 | only affects sections that could benefit from this information. |
| 1387 | |
| 1388 | |
| 1389 | File: magit.info, Node: Transient Commands, Next: Transient Arguments and Buffer Variables, Prev: Sections, Up: Interface Concepts |
| 1390 | |
| 1391 | 4.3 Transient Commands |
| 1392 | ====================== |
| 1393 | |
| 1394 | Many Magit commands are implemented as *transient* commands. First the |
| 1395 | user invokes a *prefix* command, which causes its *infix* arguments and |
| 1396 | *suffix* commands to be displayed in the echo area. The user then |
| 1397 | optionally sets some infix arguments and finally invokes one of the |
| 1398 | suffix commands. |
| 1399 | |
| 1400 | This is implemented in the library ‘transient’. Earlier Magit |
| 1401 | releases used the package ‘magit-popup’ and even earlier versions |
| 1402 | library ‘magit-key-mode’. |
| 1403 | |
| 1404 | Transient is documented in *note (transient)Top::. |
| 1405 | |
| 1406 | ‘C-x M-g’ (‘magit-dispatch’) |
| 1407 | ‘C-c g’ (‘magit-dispatch’) |
| 1408 | This transient prefix command binds most of Magit's other prefix |
| 1409 | commands as suffix commands and displays them in a temporary buffer |
| 1410 | until one of them is invoked. Invoking such a sub-prefix causes |
| 1411 | the suffixes of that command to be bound and displayed instead of |
| 1412 | those of ‘magit-dispatch’. |
| 1413 | |
| 1414 | This command is also, or especially, useful outside Magit buffers, |
| 1415 | so Magit by default binds it to ‘C-c M-g’ in the global keymap. |
| 1416 | ‘C-c g’ would be a better binding, but we cannot use that by |
| 1417 | default, because that key sequence is reserved for the user. See |
| 1418 | *note Global Bindings:: to learn more default and recommended key |
| 1419 | bindings. |
| 1420 | |
| 1421 | |
| 1422 | File: magit.info, Node: Transient Arguments and Buffer Variables, Next: Completion Confirmation and the Selection, Prev: Transient Commands, Up: Interface Concepts |
| 1423 | |
| 1424 | 4.4 Transient Arguments and Buffer Variables |
| 1425 | ============================================ |
| 1426 | |
| 1427 | The infix arguments of many of Magit's transient prefix commands cease |
| 1428 | to have an effect once the ‘git’ command that is called with those |
| 1429 | arguments has returned. Commands that create a commit are a good |
| 1430 | example for this. If the user changes the arguments, then that only |
| 1431 | affects the next invocation of a suffix command. If the same transient |
| 1432 | prefix command is later invoked again, then the arguments are initially |
| 1433 | reset to the default value. This default value can be set for the |
| 1434 | current Emacs session or saved permanently, see *note (transient)Saving |
| 1435 | Values::. It is also possible to cycle through previously used sets of |
| 1436 | arguments using ‘C-M-p’ and ‘C-M-n’, see *note (transient)Using |
| 1437 | History::. |
| 1438 | |
| 1439 | However the infix arguments of many other transient commands continue |
| 1440 | to have an effect even after the ‘git’ command that was called with |
| 1441 | those arguments has returned. The most important commands like this are |
| 1442 | those that display a diff or log in a dedicated buffer. Their arguments |
| 1443 | obviously continue to have an effect for as long as the respective diff |
| 1444 | or log is being displayed. Furthermore the used arguments are stored in |
| 1445 | buffer-local variables for future reference. |
| 1446 | |
| 1447 | For commands in the second group it isn't always desirable to reset |
| 1448 | their arguments to the global value when the transient prefix command is |
| 1449 | invoked again. |
| 1450 | |
| 1451 | As mentioned above, it is possible to cycle through previously used |
| 1452 | sets of arguments while a transient popup is visible. That means that |
| 1453 | we could always reset the infix arguments to the default because the set |
| 1454 | of arguments that is active in the existing buffer is only a few ‘C-M-p’ |
| 1455 | away. Magit can be configured to behave like that, but because I expect |
| 1456 | that most users would not find that very convenient, it is not the |
| 1457 | default. |
| 1458 | |
| 1459 | Also note that it is possible to change the diff and log arguments |
| 1460 | used in the current buffer (including the status buffer, which contains |
| 1461 | both diff and log sections) using the respective "refresh" transient |
| 1462 | prefix commands on ‘D’ and ‘L’. (‘d’ and ‘l’ on the other hand are |
| 1463 | intended to change *what* diff or log is being displayed. It is |
| 1464 | possible to also change *how* the diff or log is being displayed at the |
| 1465 | same time, but if you only want to do the latter, then you should use |
| 1466 | the refresh variants.) Because these secondary diff and log transient |
| 1467 | prefixes are about *changing* the arguments used in the current buffer, |
| 1468 | they *always* start out with the set of arguments that are currently in |
| 1469 | effect in that buffer. |
| 1470 | |
| 1471 | Some commands are usually invoked directly even though they can also |
| 1472 | be invoked as the suffix of a transient prefix command. Most |
| 1473 | prominently ‘magit-show-commit’ is usually invoked by typing ‘RET’ while |
| 1474 | point is on a commit in a log, but it can also be invoked from the |
| 1475 | ‘magit-diff’ transient prefix. |
| 1476 | |
| 1477 | When such a command is invoked directly, then it is important to |
| 1478 | reuse the arguments as specified by the respective buffer-local values, |
| 1479 | instead of using the default arguments. Imagine you press ‘RET’ in a |
| 1480 | log to display the commit at point in a different buffer and then use |
| 1481 | ‘D’ to change how the diff is displayed in that buffer. And then you |
| 1482 | press ‘RET’ on another commit to show that instead and the diff |
| 1483 | arguments are reset to the default. Not cool; so Magit does not do that |
| 1484 | by default. |
| 1485 | |
| 1486 | -- User Option: magit-prefix-use-buffer-arguments |
| 1487 | This option controls whether the infix arguments initially shown in |
| 1488 | certain transient prefix commands are based on the arguments that |
| 1489 | are currently in effect in the buffer that their suffixes update. |
| 1490 | |
| 1491 | The ‘magit-diff’ and ‘magit-log’ transient prefix commands are |
| 1492 | affected by this option. |
| 1493 | |
| 1494 | -- User Option: magit-direct-use-buffer-arguments |
| 1495 | This option controls whether certain commands, when invoked |
| 1496 | directly (i.e., not as the suffix of a transient prefix command), |
| 1497 | use the arguments that are currently active in the buffer that they |
| 1498 | are about to update. The alternative is to use the default value |
| 1499 | for these arguments, which might change the arguments that are used |
| 1500 | in the buffer. |
| 1501 | |
| 1502 | Valid values for both of the above options are: |
| 1503 | |
| 1504 | • ‘always’: Always use the set of arguments that is currently active |
| 1505 | in the respective buffer, provided that buffer exists of course. |
| 1506 | • ‘selected’ or ‘t’: Use the set of arguments from the respective |
| 1507 | buffer, but only if it is displayed in a window of the current |
| 1508 | frame. This is the default for both variables. |
| 1509 | • ‘current’: Use the set of arguments from the respective buffer, but |
| 1510 | only if it is the current buffer. |
| 1511 | • ‘never’: Never use the set of arguments from the respective buffer. |
| 1512 | |
| 1513 | I am afraid it gets more complicated still: |
| 1514 | |
| 1515 | • The global diff and log arguments are set for each supported mode |
| 1516 | individually. The diff arguments for example have different values |
| 1517 | in ‘magit-diff-mode’, ‘magit-revision-mode’, |
| 1518 | ‘magit-merge-preview-mode’ and ‘magit-status-mode’ buffers. |
| 1519 | Setting or saving the value for one mode does not change the value |
| 1520 | for other modes. The history however is shared. |
| 1521 | |
| 1522 | • When ‘magit-show-commit’ is invoked directly from a log buffer, |
| 1523 | then the file filter is picked up from that buffer, not from the |
| 1524 | revision buffer or the mode's global diff arguments. |
| 1525 | |
| 1526 | • Even though they are suffixes of the diff prefix |
| 1527 | ‘magit-show-commit’ and ‘magit-stash-show’ do not use the diff |
| 1528 | buffer used by the diff commands, instead they use the dedicated |
| 1529 | revision and stash buffers. |
| 1530 | |
| 1531 | At the time you invoke the diff prefix it is unknown to Magit which |
| 1532 | of the suffix commands you are going to invoke. While not certain, |
| 1533 | more often than not users invoke one of the commands that use the |
| 1534 | diff buffer, so the initial infix arguments are those used in that |
| 1535 | buffer. However if you invoke one of these commands directly, then |
| 1536 | Magit knows that it should use the arguments from the revision |
| 1537 | resp. stash buffer. |
| 1538 | |
| 1539 | • The log prefix also features reflog commands, but these commands do |
| 1540 | not use the log arguments. |
| 1541 | |
| 1542 | • If ‘magit-show-refs’ is invoked from a ‘magit-refs-mode’ buffer, |
| 1543 | then it acts as a refresh prefix and therefore unconditionally uses |
| 1544 | the buffer's arguments as initial arguments. If it is invoked |
| 1545 | elsewhere with a prefix argument, then it acts as regular prefix |
| 1546 | and therefore respects ‘magit-prefix-use-buffer-arguments’. If it |
| 1547 | is invoked elsewhere without a prefix argument, then it acts as a |
| 1548 | direct command and therefore respects |
| 1549 | ‘magit-direct-use-buffer-arguments’. |
| 1550 | |
| 1551 | |
| 1552 | File: magit.info, Node: Completion Confirmation and the Selection, Next: Mouse Support, Prev: Transient Arguments and Buffer Variables, Up: Interface Concepts |
| 1553 | |
| 1554 | 4.5 Completion, Confirmation and the Selection |
| 1555 | ============================================== |
| 1556 | |
| 1557 | 4.5.1 Action Confirmation |
| 1558 | ------------------------- |
| 1559 | |
| 1560 | By default many actions that could potentially lead to data loss have to |
| 1561 | be confirmed. This includes many very common actions, so this can |
| 1562 | quickly become annoying. Many of these actions can be undone and if you |
| 1563 | have thought about how to undo certain mistakes, then it should be safe |
| 1564 | to disable confirmation for the respective actions. |
| 1565 | |
| 1566 | The option ‘magit-no-confirm’ can be used to tell Magit to perform |
| 1567 | certain actions without the user having to confirm them. Note that |
| 1568 | while this option can only be used to disable confirmation for a |
| 1569 | specific set of actions, the next section explains another way of |
| 1570 | telling Magit to ask fewer questions. |
| 1571 | |
| 1572 | -- User Option: magit-no-confirm |
| 1573 | The value of this option is a list of symbols, representing actions |
| 1574 | that do not have to be confirmed by the user before being carried |
| 1575 | out. |
| 1576 | |
| 1577 | By default many potentially dangerous commands ask the user for |
| 1578 | confirmation. Each of the below symbols stands for an action |
| 1579 | which, when invoked unintentionally or without being fully aware of |
| 1580 | the consequences, could lead to tears. In many cases there are |
| 1581 | several commands that perform variations of a certain action, so we |
| 1582 | don't use the command names but more generic symbols. |
| 1583 | |
| 1584 | • Applying changes: |
| 1585 | |
| 1586 | • ‘discard’ Discarding one or more changes (i.e., hunks or |
| 1587 | the complete diff for a file) loses that change, |
| 1588 | obviously. |
| 1589 | |
| 1590 | • ‘reverse’ Reverting one or more changes can usually be |
| 1591 | undone by reverting the reversion. |
| 1592 | |
| 1593 | • ‘stage-all-changes’, ‘unstage-all-changes’ When there are |
| 1594 | both staged and unstaged changes, then un-/staging |
| 1595 | everything would destroy that distinction. Of course |
| 1596 | that also applies when un-/staging a single change, but |
| 1597 | then less is lost and one does that so often that having |
| 1598 | to confirm every time would be unacceptable. |
| 1599 | |
| 1600 | • Files: |
| 1601 | |
| 1602 | • ‘delete’ When a file that isn't yet tracked by Git is |
| 1603 | deleted, then it is completely lost, not just the last |
| 1604 | changes. Very dangerous. |
| 1605 | |
| 1606 | • ‘trash’ Instead of deleting a file it can also be move to |
| 1607 | the system trash. Obviously much less dangerous than |
| 1608 | deleting it. |
| 1609 | |
| 1610 | Also see option ‘magit-delete-by-moving-to-trash’. |
| 1611 | |
| 1612 | • ‘resurrect’ A deleted file can easily be resurrected by |
| 1613 | "deleting" the deletion, which is done using the same |
| 1614 | command that was used to delete the same file in the |
| 1615 | first place. |
| 1616 | |
| 1617 | • ‘untrack’ Untracking a file can be undone by tracking it |
| 1618 | again. |
| 1619 | |
| 1620 | • ‘rename’ Renaming a file can easily be undone. |
| 1621 | |
| 1622 | • Sequences: |
| 1623 | |
| 1624 | • ‘reset-bisect’ Aborting (known to Git as "resetting") a |
| 1625 | bisect operation loses all information collected so far. |
| 1626 | |
| 1627 | • ‘abort-cherry-pick’ Aborting a cherry-pick throws away |
| 1628 | all conflict resolutions which have already been carried |
| 1629 | out by the user. |
| 1630 | |
| 1631 | • ‘abort-revert’ Aborting a revert throws away all conflict |
| 1632 | resolutions which have already been carried out by the |
| 1633 | user. |
| 1634 | |
| 1635 | • ‘abort-rebase’ Aborting a rebase throws away all already |
| 1636 | modified commits, but it's possible to restore those from |
| 1637 | the reflog. |
| 1638 | |
| 1639 | • ‘abort-merge’ Aborting a merge throws away all conflict |
| 1640 | resolutions which have already been carried out by the |
| 1641 | user. |
| 1642 | |
| 1643 | • ‘merge-dirty’ Merging with a dirty worktree can make it |
| 1644 | hard to go back to the state before the merge was |
| 1645 | initiated. |
| 1646 | |
| 1647 | • References: |
| 1648 | |
| 1649 | • ‘delete-unmerged-branch’ Once a branch has been deleted, |
| 1650 | it can only be restored using low-level recovery tools |
| 1651 | provided by Git. And even then the reflog is gone. The |
| 1652 | user always has to confirm the deletion of a branch by |
| 1653 | accepting the default choice (or selecting another |
| 1654 | branch), but when a branch has not been merged yet, also |
| 1655 | make sure the user is aware of that. |
| 1656 | |
| 1657 | • ‘delete-pr-remote’ When deleting a branch that was |
| 1658 | created from a pull-request and if no other branches |
| 1659 | still exist on that remote, then ‘magit-branch-delete’ |
| 1660 | offers to delete the remote as well. This should be safe |
| 1661 | because it only happens if no other refs exist in the |
| 1662 | remotes namespace, and you can recreate the remote if |
| 1663 | necessary. |
| 1664 | |
| 1665 | • ‘drop-stashes’ Dropping a stash is dangerous because Git |
| 1666 | stores stashes in the reflog. Once a stash is removed, |
| 1667 | there is no going back without using low-level recovery |
| 1668 | tools provided by Git. When a single stash is dropped, |
| 1669 | then the user always has to confirm by accepting the |
| 1670 | default (or selecting another). This action only |
| 1671 | concerns the deletion of multiple stashes at once. |
| 1672 | |
| 1673 | • Publishing: |
| 1674 | |
| 1675 | • ‘set-and-push’ When pushing to the upstream or the |
| 1676 | push-remote and that isn't actually configured yet, then |
| 1677 | the user can first set the target. If s/he confirms the |
| 1678 | default too quickly, then s/he might end up pushing to |
| 1679 | the wrong branch and if the remote repository is |
| 1680 | configured to disallow fixing such mistakes, then that |
| 1681 | can be quite embarrassing and annoying. |
| 1682 | |
| 1683 | • Edit published history: |
| 1684 | |
| 1685 | Without adding these symbols here, you will be warned before |
| 1686 | editing commits that have already been pushed to one of the |
| 1687 | branches listed in ‘magit-published-branches’. |
| 1688 | |
| 1689 | • ‘amend-published’ Affects most commands that amend to |
| 1690 | "HEAD". |
| 1691 | |
| 1692 | • ‘rebase-published’ Affects commands that perform |
| 1693 | interactive rebases. This includes commands from the |
| 1694 | commit transient that modify a commit other than "HEAD", |
| 1695 | namely the various fixup and squash variants. |
| 1696 | |
| 1697 | • ‘edit-published’ Affects the commands |
| 1698 | ‘magit-edit-line-commit’ and |
| 1699 | ‘magit-diff-edit-hunk-commit’. These two commands make |
| 1700 | it quite easy to accidentally edit a published commit, so |
| 1701 | you should think twice before configuring them not to ask |
| 1702 | for confirmation. |
| 1703 | |
| 1704 | To disable confirmation completely, add all three symbols here |
| 1705 | or set ‘magit-published-branches’ to ‘nil’. |
| 1706 | |
| 1707 | • Various: |
| 1708 | |
| 1709 | • ‘stash-apply-3way’ When a stash cannot be applied using |
| 1710 | ‘git stash apply’, then Magit uses ‘git apply’ instead, |
| 1711 | possibly using the ‘--3way’ argument, which isn't always |
| 1712 | perfectly safe. See also ‘magit-stash-apply’. |
| 1713 | |
| 1714 | • ‘kill-process’ There seldom is a reason to kill a |
| 1715 | process. |
| 1716 | |
| 1717 | • Global settings: |
| 1718 | |
| 1719 | Instead of adding all of the above symbols to the value of |
| 1720 | this option, you can also set it to the atom 't', which has |
| 1721 | the same effect as adding all of the above symbols. Doing |
| 1722 | that most certainly is a bad idea, especially because other |
| 1723 | symbols might be added in the future. So even if you don't |
| 1724 | want to be asked for confirmation for any of these actions, |
| 1725 | you are still better of adding all of the respective symbols |
| 1726 | individually. |
| 1727 | |
| 1728 | When ‘magit-wip-before-change-mode’ is enabled, then the |
| 1729 | following actions can be undone fairly easily: ‘discard’, |
| 1730 | ‘reverse’, ‘stage-all-changes’, and ‘unstage-all-changes’. If |
| 1731 | and only if this mode is enabled, then ‘safe-with-wip’ has the |
| 1732 | same effect as adding all of these symbols individually. |
| 1733 | |
| 1734 | 4.5.2 Completion and Confirmation |
| 1735 | --------------------------------- |
| 1736 | |
| 1737 | Many Magit commands ask the user to select from a list of possible |
| 1738 | things to act on, while offering the most likely choice as the default. |
| 1739 | For many of these commands the default is the thing at point, provided |
| 1740 | that it actually is a valid thing to act on. For many commands that act |
| 1741 | on a branch, the current branch serves as the default if there is no |
| 1742 | branch at point. |
| 1743 | |
| 1744 | These commands combine asking for confirmation and asking for a |
| 1745 | target to act on into a single action. The user can confirm the default |
| 1746 | target using ‘RET’ or abort using ‘C-g’. This is similar to a |
| 1747 | ‘y-or-n-p’ prompt, but the keys to confirm or abort differ. |
| 1748 | |
| 1749 | At the same time the user is also given the opportunity to select |
| 1750 | another target, which is useful because for some commands and/or in some |
| 1751 | situations you might want to select the action before selecting the |
| 1752 | target by moving to it. |
| 1753 | |
| 1754 | However you might find that for some commands you always want to use |
| 1755 | the default target, if any, or even that you want the command to act on |
| 1756 | the default without requiring any confirmation at all. The option |
| 1757 | ‘magit-dwim-selection’ can be used to configure certain commands to that |
| 1758 | effect. |
| 1759 | |
| 1760 | Note that when the region is active then many commands act on the |
| 1761 | things that are selected using a mechanism based on the region, in many |
| 1762 | cases after asking for confirmation. This region-based mechanism is |
| 1763 | called the "selection" and is described in detail in the next section. |
| 1764 | When a selection exists that is valid for the invoked command, then that |
| 1765 | command never offers to act on something else, and whether it asks for |
| 1766 | confirmation is not controlled by this option. |
| 1767 | |
| 1768 | Also note that Magit asks for confirmation of certain actions that |
| 1769 | are not coupled with completion (or the selection). Such dialogs are |
| 1770 | also not affected by this option and are described in the previous |
| 1771 | section. |
| 1772 | |
| 1773 | -- User Option: magit-dwim-selection |
| 1774 | This option can be used to tell certain commands to use the thing at |
| 1775 | point instead of asking the user to select a candidate to act on, with |
| 1776 | or without confirmation. |
| 1777 | |
| 1778 | The value has the form ‘((COMMAND nil|PROMPT DEFAULT)...)’. |
| 1779 | |
| 1780 | • COMMAND is the command that should not prompt for a choice. To |
| 1781 | have an effect, the command has to use the function |
| 1782 | ‘magit-completing-read’ or a utility function which in turn uses |
| 1783 | that function. |
| 1784 | |
| 1785 | • If the command uses ‘magit-completing-read’ multiple times, then |
| 1786 | PROMPT can be used to only affect one of these uses. PROMPT, if |
| 1787 | non-‘nil’, is a regular expression that is used to match against |
| 1788 | the PROMPT argument passed to ‘magit-completing-read’. |
| 1789 | |
| 1790 | • DEFAULT specifies how to use the default. If it is ‘t’, then the |
| 1791 | DEFAULT argument passed to ‘magit-completing-read’ is used without |
| 1792 | confirmation. If it is ‘ask’, then the user is given a chance to |
| 1793 | abort. DEFAULT can also be ‘nil’, in which case the entry has no |
| 1794 | effect. |
| 1795 | |
| 1796 | 4.5.3 The Selection |
| 1797 | ------------------- |
| 1798 | |
| 1799 | If the region is active, then many Magit commands act on the things that |
| 1800 | are selected using a mechanism based on the region instead of one single |
| 1801 | thing. When the region is not active, then these commands act on the |
| 1802 | thing at point or read a single thing to act on. This is described in |
| 1803 | the previous section — this section only covers how multiple things are |
| 1804 | selected, how that is visualized, and how certain commands behave when |
| 1805 | that is the case. |
| 1806 | |
| 1807 | Magit's mechanism for selecting multiple things, or rather sections |
| 1808 | that represent these things, is based on the Emacs region, but the area |
| 1809 | that Magit considers to be selected is typically larger than the region |
| 1810 | and additional restrictions apply. |
| 1811 | |
| 1812 | Magit makes a distinction between a region that qualifies as forming |
| 1813 | a valid Magit selection and a region that does not. If the region does |
| 1814 | not qualify, then it is displayed as it is in other Emacs buffers. If |
| 1815 | the region does qualify as a Magit selection, then the selection is |
| 1816 | always visualized, while the region itself is only visualized if it |
| 1817 | begins and ends on the same line. |
| 1818 | |
| 1819 | For a region to qualify as a Magit selection, it must begin in the |
| 1820 | heading of one section and end in the heading of a sibling section. |
| 1821 | Note that if the end of the region is at the very beginning of section |
| 1822 | heading (i.e., at the very beginning of a line) then that section is |
| 1823 | considered to be *inside* the selection. |
| 1824 | |
| 1825 | This is not consistent with how the region is normally treated in |
| 1826 | Emacs — if the region ends at the beginning of a line, then that line is |
| 1827 | outside the region. Due to how Magit visualizes the selection, it |
| 1828 | should be obvious that this difference exists. |
| 1829 | |
| 1830 | Not every command acts on every valid selection. Some commands do |
| 1831 | not even consider the location of point, others may act on the section |
| 1832 | at point but not support acting on the selection, and even commands that |
| 1833 | do support the selection of course only do so if it selects things that |
| 1834 | they can act on. |
| 1835 | |
| 1836 | This is the main reason why the selection must include the section at |
| 1837 | point. Even if a selection exists, the invoked command may disregard |
| 1838 | it, in which case it may act on the current section only. It is much |
| 1839 | safer to only act on the current section but not the other selected |
| 1840 | sections than it is to act on the current section *instead* of the |
| 1841 | selected sections. The latter would be much more surprising and if the |
| 1842 | current section always is part of the selection, then that cannot |
| 1843 | happen. |
| 1844 | |
| 1845 | -- Variable: magit-keep-region-overlay |
| 1846 | This variable controls whether the region is visualized as usual |
| 1847 | even when a valid Magit selection or a hunk-internal region exists. |
| 1848 | See the doc-string for more information. |
| 1849 | |
| 1850 | 4.5.4 The hunk-internal region |
| 1851 | ------------------------------ |
| 1852 | |
| 1853 | Somewhat related to the Magit selection described in the previous |
| 1854 | section is the hunk-internal region. |
| 1855 | |
| 1856 | Like the selection, the hunk-internal region is based on the Emacs |
| 1857 | region but causes that region to not be visualized as it would in other |
| 1858 | Emacs buffers, and includes the line on which the region ends even if it |
| 1859 | ends at the very beginning of that line. |
| 1860 | |
| 1861 | Unlike the selection, which is based on a region that must begin in |
| 1862 | the heading of one section and ends in the section of a sibling section, |
| 1863 | the hunk-internal region must begin inside the *body* of a hunk section |
| 1864 | and end in the body of the *same* section. |
| 1865 | |
| 1866 | The hunk-internal region is honored by "apply" commands, which can, |
| 1867 | among other targets, act on a hunk. If the hunk-internal region is |
| 1868 | active, then such commands act only on the marked part of the hunk |
| 1869 | instead of on the complete hunk. |
| 1870 | |
| 1871 | 4.5.5 Support for Completion Frameworks |
| 1872 | --------------------------------------- |
| 1873 | |
| 1874 | The built-in option ‘completing-read-function’ specifies the low-level |
| 1875 | function used by ‘completing-read’ to ask a user to select from a list |
| 1876 | of choices. Its default value is ‘completing-read-default’. |
| 1877 | Alternative completion frameworks typically activate themselves by |
| 1878 | substituting their own implementation. |
| 1879 | |
| 1880 | Mostly for historic reasons Magit provides a similar option named |
| 1881 | ‘magit-completing-read-function’, which only controls the low-level |
| 1882 | function used by ‘magit-completing-read’. This option also makes it |
| 1883 | possible to use a different completing mechanism for Magit than for the |
| 1884 | rest of Emacs, but doing that is not recommend. |
| 1885 | |
| 1886 | You most likely don't have to customize the magit-specific option to |
| 1887 | use an alternative completion framework. For example, if you enable |
| 1888 | ‘ivy-mode’, then Magit will respect that, and if you enable ‘helm-mode’, |
| 1889 | then you are done too. |
| 1890 | |
| 1891 | -- User Option: magit-completing-read-function |
| 1892 | The value of this variable is the low-level function used to |
| 1893 | perform completion by code that uses ‘magit-completing-read’ (as |
| 1894 | opposed to the built-in ‘completing-read’). |
| 1895 | |
| 1896 | The default value, ‘magit-builtin-completing-read’, is suitable for |
| 1897 | the standard completion mechanism, ‘ivy-mode’, and ‘helm-mode’ at |
| 1898 | least. |
| 1899 | |
| 1900 | The built-in ‘completing-read’ and ‘completing-read-default’ are |
| 1901 | *not* suitable to be used here. ‘magit-builtin-completing-read’ |
| 1902 | performs some additional work, and any function used in its place |
| 1903 | has to do the same. |
| 1904 | |
| 1905 | -- Function: magit-builtin-completing-read prompt choices &optional |
| 1906 | predicate require-match initial-input hist def |
| 1907 | This function performs completion using the built-in |
| 1908 | ‘completing-read’ and does some additional magit-specific work. |
| 1909 | |
| 1910 | -- Function: magit-completing-read prompt choices &optional predicate |
| 1911 | require-match initial-input hist def fallback |
| 1912 | This is the function that Magit commands use when they need the |
| 1913 | user to select a single thing to act on. The arguments have the |
| 1914 | same meaning as for ‘completing-read’, except for FALLBACK, which |
| 1915 | is unique to this function and is described below. |
| 1916 | |
| 1917 | Instead of asking the user to choose from a list of possible |
| 1918 | candidates, this function may just return the default specified by |
| 1919 | DEF, with or without requiring user confirmation. Whether that is |
| 1920 | the case depends on PROMPT, ‘this-command’ and |
| 1921 | ‘magit-dwim-selection’. See the documentation of the latter for |
| 1922 | more information. |
| 1923 | |
| 1924 | If it does read a value in the minibuffer, then this function acts |
| 1925 | similar to ‘completing-read’, except for the following: |
| 1926 | |
| 1927 | • COLLECTION must be a list of choices. A function is not |
| 1928 | supported. |
| 1929 | |
| 1930 | • If REQUIRE-MATCH is ‘nil’ and the user exits without a choice, |
| 1931 | then ‘nil’ is returned instead of an empty string. |
| 1932 | |
| 1933 | • If REQUIRE-MATCH is ‘any’, then do not require a match but do |
| 1934 | require non-empty input (or non-‘nil’ DEFAULT, since that is |
| 1935 | substituted for empty input). |
| 1936 | |
| 1937 | • If REQUIRE-MATCH is non-‘nil’ and the users exits without a |
| 1938 | choice, an user-error is raised. |
| 1939 | |
| 1940 | • FALLBACK specifies a secondary default that is only used if |
| 1941 | the primary default DEF is ‘nil’. The secondary default is |
| 1942 | not subject to ‘magit-dwim-selection’ — if DEF is ‘nil’ but |
| 1943 | FALLBACK is not, then this function always asks the user to |
| 1944 | choose a candidate, just as if both defaults were ‘nil’. |
| 1945 | |
| 1946 | • ‘format-prompt’ is called on PROMPT and DEF (or FALLBACK if |
| 1947 | DEF is ‘nil’). This appends ": " to the prompt and may also |
| 1948 | add the default to the prompt, using the format specified by |
| 1949 | ‘minibuffer-default-prompt-format’ and depending on |
| 1950 | ‘magit-completing-read-default-prompt-predicate’. |
| 1951 | |
| 1952 | 4.5.6 Additional Completion Options |
| 1953 | ----------------------------------- |
| 1954 | |
| 1955 | -- User Option: magit-list-refs-sortby |
| 1956 | For many commands that read a ref or refs from the user, the value |
| 1957 | of this option can be used to control the order of the refs. Valid |
| 1958 | values include any key accepted by the ‘--sort’ flag of ‘git |
| 1959 | for-each-ref’. By default, refs are sorted alphabetically by their |
| 1960 | full name (e.g., "refs/heads/master"). |
| 1961 | |
| 1962 | |
| 1963 | File: magit.info, Node: Mouse Support, Next: Running Git, Prev: Completion Confirmation and the Selection, Up: Interface Concepts |
| 1964 | |
| 1965 | 4.6 Mouse Support |
| 1966 | ================= |
| 1967 | |
| 1968 | Double clicking on a section heading toggles the visibility of its body, |
| 1969 | if any. Likewise clicking in the left fringe toggles the visibility of |
| 1970 | the appropriate section. |
| 1971 | |
| 1972 | A context menu is provided but has to be enabled explicitly. In |
| 1973 | Emacs 28 and greater, enable the global mode ‘context-menu-mode’. If |
| 1974 | you use an older Emacs release, set |
| 1975 | ‘magit-section-show-context-menu-for-emacs<28’. |
| 1976 | |
| 1977 | |
| 1978 | File: magit.info, Node: Running Git, Prev: Mouse Support, Up: Interface Concepts |
| 1979 | |
| 1980 | 4.7 Running Git |
| 1981 | =============== |
| 1982 | |
| 1983 | 4.7.1 Viewing Git Output |
| 1984 | ------------------------ |
| 1985 | |
| 1986 | Magit runs Git either for side-effects (e.g., when pushing) or to get |
| 1987 | some value (e.g., the name of the current branch). |
| 1988 | |
| 1989 | When Git is run for side-effects, the process output is logged in a |
| 1990 | per-repository log buffer, which can be consulted using the |
| 1991 | ‘magit-process-buffer’ command, when things don't go as expected. |
| 1992 | |
| 1993 | The output/errors for up to ‘magit-process-log-max’ Git commands are |
| 1994 | retained. |
| 1995 | |
| 1996 | ‘$’ (‘magit-process-buffer’) |
| 1997 | This commands displays the process buffer for the current |
| 1998 | repository. |
| 1999 | |
| 2000 | Inside that buffer, the usual key bindings for navigating and showing |
| 2001 | sections are available. There is one additional command. |
| 2002 | |
| 2003 | ‘k’ (‘magit-process-kill’) |
| 2004 | This command first tries to interrupt the process represented by |
| 2005 | the section at point. If that fails a second invocation instead |
| 2006 | kills the process. |
| 2007 | |
| 2008 | ‘M-x magit-toggle-git-debug’ |
| 2009 | This command toggles whether additional git errors are reported. |
| 2010 | |
| 2011 | Magit basically calls git for one of these two reasons: for |
| 2012 | side-effects or to do something with its standard output. |
| 2013 | |
| 2014 | When git is run for side-effects then its output, including error |
| 2015 | messages, go into the process buffer which is shown when using ‘$’. |
| 2016 | |
| 2017 | When git's output is consumed in some way, then it would be too |
| 2018 | expensive to also insert it into this buffer, but with this command |
| 2019 | that can be enabled temporarily. In that case, if git returns with |
| 2020 | a non-zero exit status, then at least its standard error is |
| 2021 | inserted into this buffer. |
| 2022 | |
| 2023 | Also note that just because git exits with a non-zero status and |
| 2024 | prints an error message, that usually doesn't mean that it is an |
| 2025 | error as far as Magit is concerned, which is another reason we |
| 2026 | usually hide these error messages. Whether some error message is |
| 2027 | relevant in the context of some unexpected behavior has to be |
| 2028 | judged on a case by case basis. |
| 2029 | |
| 2030 | 4.7.2 Git Process Status |
| 2031 | ------------------------ |
| 2032 | |
| 2033 | When a Git process is running for side-effects, Magit displays an |
| 2034 | indicator in the mode line, using the ‘magit-mode-line-process’ face. |
| 2035 | |
| 2036 | If the Git process exits successfully, the process indicator is |
| 2037 | removed from the mode line immediately. |
| 2038 | |
| 2039 | In the case of a Git error, the process indicator is not removed, but |
| 2040 | is instead highlighted with the ‘magit-mode-line-process-error’ face, |
| 2041 | and the error details from the process buffer are provided as a tooltip |
| 2042 | for mouse users. This error indicator persists in the mode line until |
| 2043 | the next magit buffer refresh. |
| 2044 | |
| 2045 | If you do not wish process errors to be indicated in the mode line, |
| 2046 | set ‘magit-process-display-mode-line-error’ to ‘nil’. |
| 2047 | |
| 2048 | Process errors are displayed at the top of the status buffer and in |
| 2049 | the echo area. In both places a hint is appended, which informs users |
| 2050 | that they can see the full output in the process buffer and how to |
| 2051 | display that buffer. However, once you are aware of that, you might |
| 2052 | want to set ‘magit-show-process-buffer-hint’ to ‘nil’. |
| 2053 | |
| 2054 | 4.7.3 Running Git Manually |
| 2055 | -------------------------- |
| 2056 | |
| 2057 | While Magit provides many Emacs commands to interact with Git, it does |
| 2058 | not cover everything. In those cases your existing Git knowledge will |
| 2059 | come in handy. Magit provides some commands for running arbitrary Git |
| 2060 | commands by typing them into the minibuffer, instead of having to switch |
| 2061 | to a shell. |
| 2062 | |
| 2063 | ‘!’ (‘magit-run’) |
| 2064 | This transient prefix command binds the following suffix commands |
| 2065 | and displays them in a temporary buffer until a suffix is invoked. |
| 2066 | |
| 2067 | ‘! !’ (‘magit-git-command-topdir’) |
| 2068 | This command reads a command from the user and executes it in the |
| 2069 | top-level directory of the current working tree. |
| 2070 | |
| 2071 | The string "git " is used as initial input when prompting the user |
| 2072 | for the command. It can be removed to run another command. |
| 2073 | |
| 2074 | ‘:’ (‘magit-git-command’) |
| 2075 | ‘! p’ |
| 2076 | This command reads a command from the user and executes it in |
| 2077 | ‘default-directory’. With a prefix argument the command is |
| 2078 | executed in the top-level directory of the current working tree |
| 2079 | instead. |
| 2080 | |
| 2081 | The string "git " is used as initial input when prompting the user |
| 2082 | for the command. It can be removed to run another command. |
| 2083 | |
| 2084 | ‘! s’ (‘magit-shell-command-topdir’) |
| 2085 | This command reads a command from the user and executes it in the |
| 2086 | top-level directory of the current working tree. |
| 2087 | |
| 2088 | ‘! S’ (‘magit-shell-command’) |
| 2089 | This command reads a command from the user and executes it in |
| 2090 | ‘default-directory’. With a prefix argument the command is |
| 2091 | executed in the top-level directory of the current working tree |
| 2092 | instead. |
| 2093 | |
| 2094 | -- User Option: magit-shell-command-verbose-prompt |
| 2095 | Whether the prompt, used by the above commands when reading a shell |
| 2096 | command, shows the directory in which it will be run. |
| 2097 | |
| 2098 | These suffix commands start external gui tools. |
| 2099 | |
| 2100 | ‘! k’ (‘magit-run-gitk’) |
| 2101 | This command runs ‘gitk’ in the current repository. |
| 2102 | |
| 2103 | ‘! a’ (‘magit-run-gitk-all’) |
| 2104 | This command runs ‘gitk --all’ in the current repository. |
| 2105 | |
| 2106 | ‘! b’ (‘magit-run-gitk-branches’) |
| 2107 | This command runs ‘gitk --branches’ in the current repository. |
| 2108 | |
| 2109 | ‘! g’ (‘magit-run-git-gui’) |
| 2110 | This command runs ‘git gui’ in the current repository. |
| 2111 | |
| 2112 | ‘! m’ (‘magit-git-mergetool’) |
| 2113 | This command runs ‘git mergetool --gui’ in the current repository. |
| 2114 | |
| 2115 | With a prefix argument this acts as a transient prefix command, |
| 2116 | allowing the user to select the mergetool and change some settings. |
| 2117 | |
| 2118 | 4.7.4 Git Executable |
| 2119 | -------------------- |
| 2120 | |
| 2121 | When Magit calls Git, then it may do so using the absolute path to the |
| 2122 | ‘git’ executable, or using just its name. |
| 2123 | |
| 2124 | When running ‘git’ locally and the ‘system-type’ is ‘windows-nt’ (any |
| 2125 | Windows version) or ‘darwin’ (macOS) then ‘magit-git-executable’ is set |
| 2126 | to an absolute path when Magit is loaded. |
| 2127 | |
| 2128 | On Windows it is necessary to use an absolute path because Git comes |
| 2129 | with several wrapper scripts for the actual ‘git’ binary, which are also |
| 2130 | placed on ‘$PATH’, and using one of these wrappers instead of the binary |
| 2131 | would degrade performance horribly. For some macOS users using just the |
| 2132 | name of the executable also performs horribly, so we avoid doing that on |
| 2133 | that platform as well. On other platforms, using just the name seems to |
| 2134 | work just fine. |
| 2135 | |
| 2136 | Using an absolute path when running ‘git’ on a remote machine over |
| 2137 | Tramp, would be problematic to use an absolute path that is suitable on |
| 2138 | the local machine, so a separate option is used to control the name or |
| 2139 | path that is used on remote machines. |
| 2140 | |
| 2141 | -- User Option: magit-git-executable |
| 2142 | The ‘git’ executable used by Magit on the local host. This should |
| 2143 | be either the absolute path to the executable, or the string "git" |
| 2144 | to let Emacs find the executable itself, using the standard |
| 2145 | mechanism for doing such things. |
| 2146 | |
| 2147 | -- User Option: magit-remote-git-executable |
| 2148 | The ‘git’ executable used by Magit on remote machines over Tramp. |
| 2149 | Normally this should be just the string "git". Consider |
| 2150 | customizing ‘tramp-remote-path’ instead of this option. |
| 2151 | |
| 2152 | If Emacs is unable to find the correct executable, then you can work |
| 2153 | around that by explicitly setting the value of one of these two options. |
| 2154 | Doing that should be considered a kludge; it is better to make sure that |
| 2155 | the order in ‘exec-path’ or ‘tramp-remote-path’ is correct. |
| 2156 | |
| 2157 | Note that ‘exec-path’ is set based on the value of the ‘PATH’ |
| 2158 | environment variable that is in effect when Emacs is started. If you |
| 2159 | set ‘PATH’ in your shell's init files, then that only has an effect on |
| 2160 | Emacs if you start it from that shell (because the environment of a |
| 2161 | process is only passed to its child processes, not to arbitrary other |
| 2162 | processes). If that is not how you start Emacs, then the |
| 2163 | ‘exec-path-from-shell’ package can help; though honestly I consider that |
| 2164 | a kludge too. |
| 2165 | |
| 2166 | The command ‘magit-debug-git-executable’ can be useful to find out |
| 2167 | where Emacs is searching for ‘git’. |
| 2168 | |
| 2169 | ‘M-x magit-debug-git-executable’ |
| 2170 | This command displays a buffer with information about |
| 2171 | ‘magit-git-executable’ and ‘magit-remote-git-executable’. |
| 2172 | |
| 2173 | ‘M-x magit-version’ |
| 2174 | This command shows the currently used versions of Magit, Git, and |
| 2175 | Emacs in the echo area. Non-interactively this just returns the |
| 2176 | Magit version. |
| 2177 | |
| 2178 | 4.7.5 Global Git Arguments |
| 2179 | -------------------------- |
| 2180 | |
| 2181 | -- User Option: magit-git-global-arguments |
| 2182 | The arguments set here are used every time the git executable is |
| 2183 | run as a subprocess. They are placed right after the executable |
| 2184 | itself and before the git command - as in ‘git HERE... COMMAND |
| 2185 | REST’. For valid arguments see *note (gitman)git::. |
| 2186 | |
| 2187 | Be careful what you add here, especially if you are using Tramp to |
| 2188 | connect to servers with ancient Git versions. Never remove |
| 2189 | anything that is part of the default value, unless you really know |
| 2190 | what you are doing. And think very hard before adding something; |
| 2191 | it will be used every time Magit runs Git for any purpose. |
| 2192 | |
| 2193 | 4.7.6 Mapping Git Hooks to Lisp Hooks |
| 2194 | ------------------------------------- |
| 2195 | |
| 2196 | Git hooks can be configured to call Lisp hooks, starting with Git |
| 2197 | v2.54.0. The mechanism described here is only used when ‘git’ is |
| 2198 | invoked by Magit, and ‘git’ is run asynchronously and on the local |
| 2199 | machine. |
| 2200 | |
| 2201 | ‘magit-run-hooks-from-githooks’ |
| 2202 | This option controls whether Git hooks may run Lisp hooks. |
| 2203 | |
| 2204 | By default the Lisp hook ‘magit-common-git-post-commit-functions’ |
| 2205 | is run by the Git hooks ‘post-commit’, ‘post-merge’ and |
| 2206 | ‘post-rewrite’. Use ‘magit-user-githook-file’ to define additional |
| 2207 | hooks. |
| 2208 | |
| 2209 | Git hooks can only run Lisp hooks, if Magit invokes Git |
| 2210 | asynchronously and on the local machine, |
| 2211 | ‘with-editor-emacsclient-executable’ is set, and at least Git |
| 2212 | v2.54.0 is used. |
| 2213 | |
| 2214 | ‘magit-user-githook-file’ |
| 2215 | This option controls the location of a user-editable file |
| 2216 | containing additional hook mappings. |
| 2217 | |
| 2218 | -- Variable: magit-githook-directory |
| 2219 | The value of this variable is the directory containing files Magit |
| 2220 | needs to map Git hooks to Lisp hooks. |
| 2221 | |
| 2222 | This directory must contains two files; ‘config’, which maps Git |
| 2223 | hooks to the Lisp hook ‘magit-common-git-post-commit-functions’, |
| 2224 | and an executable ‘magit-run-git-hook’, which is used in that, and |
| 2225 | potentially other, hook mappings. |
| 2226 | |
| 2227 | The value of this variable is set by ‘magit-process-git-arguments’, |
| 2228 | when it is first needed. Users can set it to another directory, |
| 2229 | but that should rarely be necessary. Additional hook mappings |
| 2230 | should instead be defined in ‘magit-user-githook-file’. |
| 2231 | |
| 2232 | -- Function: magit-run-git-hook (hook &rest args) |
| 2233 | This function runs the Lisp hook HOOK with the specified arguments |
| 2234 | ARGS. ARGS are the arguments (a possibly empty list of strings), |
| 2235 | which the Git hook was called with. HOOK is a string naming a |
| 2236 | hook. |
| 2237 | |
| 2238 | This function is only intended to be called via ‘emacsclient’, by |
| 2239 | an executable by the same name, which in turn is only intended to |
| 2240 | be called by Git hooks. |
| 2241 | |
| 2242 | -- Variable: magit-common-git-post-commit-functions |
| 2243 | This Lisp hook is run by the Git hooks ‘post-commit’, ‘post-merge’ |
| 2244 | and ‘post-rewrite’. There is not a single Git hook, which is |
| 2245 | called after a commit is created; to achieve that, all of these |
| 2246 | hooks have to be used. |
| 2247 | |
| 2248 | Git hooks are documented in *note (gitman)githooks::. Also see *note |
| 2249 | (gitman)git-hook::. Using ‘magit-common-git-post-commit-functions’ as |
| 2250 | an example, the following is how Magit gets Git to map Git hooks to Lisp |
| 2251 | hooks. |
| 2252 | |
| 2253 | Iff Magit calls Git asynchronously and on the local machine, it |
| 2254 | injects the global arguments ‘-c include.path=/path/to/githooks/config’. |
| 2255 | That file contains: |
| 2256 | |
| 2257 | [hook "magit-common-post-commit"] |
| 2258 | event = post-commit |
| 2259 | event = post-merge |
| 2260 | event = post-rewrite |
| 2261 | command = magit-run-git-hook magit-common-git-post-commit-functions |
| 2262 | |
| 2263 | Consequently when one of the Git hooks ‘post-commit’, ‘post-merge’ or |
| 2264 | ‘post-rewrite’ is triggered, that causes the ‘magit-run-git-hook’ |
| 2265 | executable to be called with ‘magit-common-git-post-commit-functions’ as |
| 2266 | the first argument. |
| 2267 | |
| 2268 | That executable used the ‘emacsclient’ to call a Lisp function by the |
| 2269 | same name, which takes the name of a Lisp hook as the first argument. |
| 2270 | The executable may receive additional arguments from the Git hook, which |
| 2271 | it passes on to the function. All arguments are strings. |
| 2272 | |
| 2273 | The function ‘magit-run-git-hook’ runs the Lisp hook using |
| 2274 | ‘run-hook-with-args’, passing along all arguments, starting with the |
| 2275 | second. It also arranges for ‘message’ to output to standard output, so |
| 2276 | that messages appear in Magit's process buffer. |
| 2277 | |
| 2278 | |
| 2279 | File: magit.info, Node: Inspecting, Next: Manipulating, Prev: Interface Concepts, Up: Top |
| 2280 | |
| 2281 | 5 Inspecting |
| 2282 | ************ |
| 2283 | |
| 2284 | The functionality provided by Magit can be roughly divided into three |
| 2285 | groups: inspecting existing data, manipulating existing data or adding |
| 2286 | new data, and transferring data. Of course that is a rather crude |
| 2287 | distinction that often falls short, but it's more useful than no |
| 2288 | distinction at all. This section is concerned with inspecting data, the |
| 2289 | next two with manipulating and transferring it. Then follows a section |
| 2290 | about miscellaneous functionality, which cannot easily be fit into this |
| 2291 | distinction. |
| 2292 | |
| 2293 | Of course other distinctions make sense too, e.g., Git's distinction |
| 2294 | between porcelain and plumbing commands, which for the most part is |
| 2295 | equivalent to Emacs' distinction between interactive commands and |
| 2296 | non-interactive functions. All of the sections mentioned before are |
| 2297 | mainly concerned with the porcelain - Magit's plumbing layer is |
| 2298 | described later. |
| 2299 | |
| 2300 | * Menu: |
| 2301 | |
| 2302 | * Status Buffer:: |
| 2303 | * Repository List:: |
| 2304 | * Logging:: |
| 2305 | * Diffing:: |
| 2306 | * Ediffing:: |
| 2307 | * References Buffer:: |
| 2308 | * Bisecting:: |
| 2309 | * Visiting Files and Blobs:: |
| 2310 | * Blaming:: |
| 2311 | |
| 2312 | |
| 2313 | File: magit.info, Node: Status Buffer, Next: Repository List, Up: Inspecting |
| 2314 | |
| 2315 | 5.1 Status Buffer |
| 2316 | ================= |
| 2317 | |
| 2318 | While other Magit buffers contain, e.g., one particular diff or one |
| 2319 | particular log, the status buffer contains the diffs for staged and |
| 2320 | unstaged changes, logs for unpushed and unpulled commits, lists of |
| 2321 | stashes and untracked files, and information related to the current |
| 2322 | branch. |
| 2323 | |
| 2324 | During certain incomplete operations - for example when a merge |
| 2325 | resulted in a conflict - additional information is displayed that helps |
| 2326 | proceeding with or aborting the operation. |
| 2327 | |
| 2328 | The command ‘magit-status’ displays the status buffer belonging to |
| 2329 | the current repository in another window. This command is used so often |
| 2330 | that it should be bound globally. We recommend using ‘C-x g’: |
| 2331 | |
| 2332 | (global-set-key (kbd "C-x g") 'magit-status) |
| 2333 | |
| 2334 | ‘C-x g’ (‘magit-status’) |
| 2335 | When invoked from within an existing Git repository, then this |
| 2336 | command shows the status of that repository in a buffer. |
| 2337 | |
| 2338 | If the current directory isn't located within a Git repository, |
| 2339 | then this command prompts for an existing repository or an |
| 2340 | arbitrary directory, depending on the option |
| 2341 | ‘magit-repository-directories’, and the status for the selected |
| 2342 | repository is shown instead. |
| 2343 | |
| 2344 | • If that option specifies any existing repositories, then the |
| 2345 | user is asked to select one of them. |
| 2346 | |
| 2347 | • Otherwise the user is asked to select an arbitrary directory |
| 2348 | using regular file-name completion. If the selected directory |
| 2349 | is the top-level directory of an existing working tree, then |
| 2350 | the status buffer for that is shown. |
| 2351 | |
| 2352 | • Otherwise the user is offered to initialize the selected |
| 2353 | directory as a new repository. After creating the repository |
| 2354 | its status buffer is shown. |
| 2355 | |
| 2356 | These fallback behaviors can also be forced using one or more |
| 2357 | prefix arguments: |
| 2358 | |
| 2359 | • With two prefix arguments (or more precisely a numeric prefix |
| 2360 | value of 16 or greater) an arbitrary directory is read, which |
| 2361 | is then acted on as described above. The same could be |
| 2362 | accomplished using the command ‘magit-init’. |
| 2363 | |
| 2364 | • With a single prefix argument an existing repository is read |
| 2365 | from the user, or if no repository can be found based on the |
| 2366 | value of ‘magit-repository-directories’, then the behavior is |
| 2367 | the same as with two prefix arguments. |
| 2368 | |
| 2369 | -- User Option: magit-repository-directories |
| 2370 | List of directories that are Git repositories or contain Git |
| 2371 | repositories. |
| 2372 | |
| 2373 | Each element has the form ‘(DIRECTORY . DEPTH)’. DIRECTORY has to |
| 2374 | be a directory or a directory file-name, a string. specifies the |
| 2375 | maximum depth to look for Git repositories. If it is 0, then only |
| 2376 | add DIRECTORY itself. DEPTH, is an integer, its absolute value |
| 2377 | specifies the maximum depth to look for Git repositories. If it is |
| 2378 | 0, only add DIRECTORY itself. If it is positive, do not list |
| 2379 | nested repositories. If it is negative, descend into repositories |
| 2380 | as for any other directory. |
| 2381 | |
| 2382 | This option controls which repositories are being listed by |
| 2383 | ‘magit-list-repositories’. It also affects ‘magit-status’ (which |
| 2384 | see) in potentially surprising ways (see above). |
| 2385 | |
| 2386 | -- Command: magit-status-quick |
| 2387 | This command is an alternative to ‘magit-status’ that usually |
| 2388 | avoids refreshing the status buffer. |
| 2389 | |
| 2390 | If the status buffer of the current Git repository exists but isn't |
| 2391 | being displayed in the selected frame, then it is displayed without |
| 2392 | being refreshed. |
| 2393 | |
| 2394 | If the status buffer is being displayed in the selected frame, then |
| 2395 | this command refreshes it. |
| 2396 | |
| 2397 | Prefix arguments have the same meaning as for ‘magit-status’, and |
| 2398 | additionally cause the buffer to be refresh. |
| 2399 | |
| 2400 | To use this command add this to your init file: |
| 2401 | |
| 2402 | (global-set-key (kbd "C-x g") 'magit-status-quick). |
| 2403 | |
| 2404 | If you do that and then for once want to redisplay the buffer and |
| 2405 | also immediately refresh it, then type ‘C-x g’ followed by ‘g’. |
| 2406 | |
| 2407 | A possible alternative command is |
| 2408 | ‘magit-display-repository-buffer’. It supports displaying any |
| 2409 | existing Magit buffer that belongs to the current repository; not |
| 2410 | just the status buffer. |
| 2411 | |
| 2412 | -- Command: magit-parent-status |
| 2413 | This command shows the status of the parent repository of the |
| 2414 | current Git repository. If the current repository is a submodule, |
| 2415 | it shows the status buffer of its super-repository. Otherwise it |
| 2416 | steps outside the worktree of the current repository, and if that |
| 2417 | takes us to another repository, that is considered that the parent |
| 2418 | repository. |
| 2419 | |
| 2420 | 5.1.1 Status Sections |
| 2421 | --------------------- |
| 2422 | |
| 2423 | The contents of status buffers is controlled using the hook |
| 2424 | ‘magit-status-sections-hook’. See *note Section Hooks:: to learn about |
| 2425 | such hooks and how to customize them. |
| 2426 | |
| 2427 | -- User Option: magit-status-sections-hook |
| 2428 | This hook is run to insert sections into a status buffer. |
| 2429 | |
| 2430 | The functions described in this section, and the functions |
| 2431 | ‘magit-insert-status-headers’ and ‘magit-insert-untracked-files’, |
| 2432 | which are described in subsequent sections, are members of this |
| 2433 | hook. |
| 2434 | |
| 2435 | Some additional functions that can be added to this hook, but are |
| 2436 | by default added to another hooks, are listed in *note References |
| 2437 | Buffer::. |
| 2438 | |
| 2439 | -- Function: magit-insert-status-headers |
| 2440 | Insert header sections appropriate for ‘magit-status-mode’ buffers. |
| 2441 | The sections are inserted by running the functions on the hook |
| 2442 | ‘magit-status-headers-hook’. See *note Status Header Sections::. |
| 2443 | |
| 2444 | -- Function: magit-insert-merge-log |
| 2445 | Insert section for the on-going merge. Display the heads that are |
| 2446 | being merged. If no merge is in progress, do nothing. |
| 2447 | |
| 2448 | -- Function: magit-insert-rebase-sequence |
| 2449 | Insert section for the on-going rebase sequence. If no such |
| 2450 | sequence is in progress, do nothing. |
| 2451 | |
| 2452 | -- Function: magit-insert-am-sequence |
| 2453 | Insert section for the on-going patch applying sequence. If no |
| 2454 | such sequence is in progress, do nothing. |
| 2455 | |
| 2456 | -- Function: magit-insert-sequencer-sequence |
| 2457 | Insert section for the on-going cherry-pick or revert sequence. If |
| 2458 | no such sequence is in progress, do nothing. |
| 2459 | |
| 2460 | -- Function: magit-insert-bisect-output |
| 2461 | While bisecting, insert section with output from ‘git bisect’. |
| 2462 | |
| 2463 | -- Function: magit-insert-bisect-rest |
| 2464 | While bisecting, insert section visualizing the bisect state. |
| 2465 | |
| 2466 | -- Function: magit-insert-bisect-log |
| 2467 | While bisecting, insert section logging bisect progress. |
| 2468 | |
| 2469 | -- Function: magit-insert-unstaged-changes |
| 2470 | Insert section showing unstaged changes. |
| 2471 | |
| 2472 | -- Function: magit-insert-staged-changes |
| 2473 | Insert section showing staged changes. |
| 2474 | |
| 2475 | -- Function: magit-insert-stashes &optional ref heading |
| 2476 | Insert the ‘stashes’ section showing reflog for "refs/stash". If |
| 2477 | optional REF is non-‘nil’ show reflog for that instead. If |
| 2478 | optional HEADING is non-‘nil’ use that as section heading instead |
| 2479 | of "Stashes:". |
| 2480 | |
| 2481 | -- Function: magit-insert-unpulled-from-upstream |
| 2482 | Insert section showing commits that haven't been pulled from the |
| 2483 | upstream branch yet. |
| 2484 | |
| 2485 | -- Function: magit-insert-unpulled-from-pushremote |
| 2486 | Insert section showing commits that haven't been pulled from the |
| 2487 | push-remote branch yet. |
| 2488 | |
| 2489 | -- Function: magit-insert-unpushed-to-upstream-or-recent |
| 2490 | Insert section showing unpushed or other recent commits. If an |
| 2491 | upstream is configured for the current branch and it is behind of |
| 2492 | the current branch, then show the commits that have not yet been |
| 2493 | pushed into the upstream branch. If no upstream is configured or |
| 2494 | if the upstream is not behind of the current branch, then show the |
| 2495 | last ‘magit-log-section-commit-count’ commits. |
| 2496 | |
| 2497 | -- Function: magit-insert-unpushed-to-upstream |
| 2498 | Insert section showing commits that haven't been pushed to the |
| 2499 | upstream yet. |
| 2500 | |
| 2501 | -- Function: magit-insert-unpushed-to-pushremote |
| 2502 | Insert section showing commits that haven't been pushed to the |
| 2503 | push-remote yet. |
| 2504 | |
| 2505 | 5.1.2 Status File List Sections |
| 2506 | ------------------------------- |
| 2507 | |
| 2508 | These functions honor the buffer's file filter, which can be set using |
| 2509 | ‘D - -’. |
| 2510 | |
| 2511 | -- Function: magit-insert-untracked-files |
| 2512 | This function may insert a list of untracked files. Whether it |
| 2513 | actually does so, depends on the option described next. |
| 2514 | |
| 2515 | -- User Option: magit-status-show-untracked-files |
| 2516 | This option controls whether the above function inserts a list of |
| 2517 | untracked files in the status buffer. |
| 2518 | |
| 2519 | • If ‘nil’, do not list any untracked files. |
| 2520 | • If ‘t’, list untracked files, but if a directory does not |
| 2521 | contain any tracked files, then only list that directory, not |
| 2522 | the contained untracked files. |
| 2523 | • If ‘all’, then list each individual untracked files. This is |
| 2524 | can be very slow and is discouraged. |
| 2525 | |
| 2526 | The corresponding values for the Git variable are "no", "normal" |
| 2527 | and "all". |
| 2528 | |
| 2529 | To disable listing untracked files in a specific repository only, |
| 2530 | add the following to ‘.dir-locals.el’: |
| 2531 | |
| 2532 | ((magit-status-mode |
| 2533 | (magit-status-show-untracked-files . "no"))) |
| 2534 | |
| 2535 | Alternatively (and mostly for historic reasons), it is possible to |
| 2536 | use ‘git config’ to set the repository-local value: |
| 2537 | |
| 2538 | git config set --local status.showUntrackedFiles no |
| 2539 | |
| 2540 | This does *not* override the (if any) local value of this Lisp |
| 2541 | variable, but it does override its global value. |
| 2542 | |
| 2543 | See the last section in the git-status(1) manpage, to speed up the |
| 2544 | part of the work Git is responsible for. Turning that list into |
| 2545 | sections is also not free, so Magit only lists |
| 2546 | ‘magit-status-file-list-limit’ files. |
| 2547 | |
| 2548 | -- User Option: magit-status-file-list-limit |
| 2549 | This option controls many files are listed at most in each section |
| 2550 | that lists files in the status buffer. For performance reasons, it |
| 2551 | is recommended that you do not increase this limit. |
| 2552 | |
| 2553 | While the above function is a member of ‘magit-status-section-hook’ |
| 2554 | by default, the following functions have to be explicitly added by the |
| 2555 | user. Because that negatively affects performance, it is recommended |
| 2556 | that you don't do that. |
| 2557 | |
| 2558 | -- Function: magit-insert-tracked-files |
| 2559 | Insert a list of tracked files. |
| 2560 | |
| 2561 | -- Function: magit-insert-ignored-files |
| 2562 | Insert a list of ignored files. |
| 2563 | |
| 2564 | -- Function: magit-insert-skip-worktree-files |
| 2565 | Insert a list of skip-worktree files. |
| 2566 | |
| 2567 | -- Function: magit-insert-assume-unchanged-files |
| 2568 | Insert a list of files that are assumed to be unchanged. |
| 2569 | |
| 2570 | 5.1.3 Status Log Sections |
| 2571 | ------------------------- |
| 2572 | |
| 2573 | -- Function: magit-insert-recent-commits |
| 2574 | Insert section showing the last ‘magit-log-section-commit-count’ |
| 2575 | commits. |
| 2576 | |
| 2577 | -- User Option: magit-log-section-commit-count |
| 2578 | How many recent commits ‘magit-insert-recent-commits’ and |
| 2579 | ‘magit-insert-unpulled-or-recent-commits’ (provided there are no |
| 2580 | unpulled commits) show. |
| 2581 | |
| 2582 | -- Function: magit-insert-unpulled-cherries |
| 2583 | Insert section showing unpulled commits. Like |
| 2584 | ‘magit-insert-unpulled-commits’ but prefix each commit that has not |
| 2585 | been applied yet (i.e., a commit with a patch-id not shared with |
| 2586 | any local commit) with "+", and all others with "-". |
| 2587 | |
| 2588 | -- Function: magit-insert-unpushed-cherries |
| 2589 | Insert section showing unpushed commits. Like |
| 2590 | ‘magit-insert-unpushed-commits’ but prefix each commit which has |
| 2591 | not been applied to upstream yet (i.e., a commit with a patch-id |
| 2592 | not shared with any upstream commit) with "+" and all others with |
| 2593 | "-". |
| 2594 | |
| 2595 | 5.1.4 Status Header Sections |
| 2596 | ---------------------------- |
| 2597 | |
| 2598 | The contents of status buffers is controlled using the hook |
| 2599 | ‘magit-status-sections-hook’ (see *note Status Sections::). |
| 2600 | |
| 2601 | By default ‘magit-insert-status-headers’ is the first member of that |
| 2602 | hook variable. |
| 2603 | |
| 2604 | -- Function: magit-insert-status-headers |
| 2605 | Insert headers sections appropriate for ‘magit-status-mode’ |
| 2606 | buffers. The sections are inserted by running the functions on the |
| 2607 | hook ‘magit-status-headers-hook’. |
| 2608 | |
| 2609 | -- User Option: magit-status-headers-hook |
| 2610 | Hook run to insert headers sections into the status buffer. |
| 2611 | |
| 2612 | This hook is run by ‘magit-insert-status-headers’, which in turn |
| 2613 | has to be a member of ‘magit-status-sections-hook’ to be used at |
| 2614 | all. |
| 2615 | |
| 2616 | By default the following functions are members of the above hook: |
| 2617 | |
| 2618 | -- Function: magit-insert-error-header |
| 2619 | Insert a header line showing the message about the Git error that |
| 2620 | just occurred. |
| 2621 | |
| 2622 | This function is only aware of the last error that occur when Git |
| 2623 | was run for side-effects. If, for example, an error occurs while |
| 2624 | generating a diff, then that error won't be inserted. Refreshing |
| 2625 | the status buffer causes this section to disappear again. |
| 2626 | |
| 2627 | -- Function: magit-insert-diff-filter-header |
| 2628 | Insert a header line showing the effective diff filters. |
| 2629 | |
| 2630 | -- Function: magit-insert-head-branch-header |
| 2631 | Insert a header line about the current branch or detached ‘HEAD’. |
| 2632 | |
| 2633 | -- Function: magit-insert-upstream-branch-header |
| 2634 | Insert a header line about the branch that is usually pulled into |
| 2635 | the current branch. |
| 2636 | |
| 2637 | -- Function: magit-insert-push-branch-header |
| 2638 | Insert a header line about the branch that the current branch is |
| 2639 | usually pushed to. |
| 2640 | |
| 2641 | -- Function: magit-insert-tags-header |
| 2642 | Insert a header line about the current and/or next tag, along with |
| 2643 | the number of commits between the tag and ‘HEAD’. |
| 2644 | |
| 2645 | The following functions can also be added to the above hook: |
| 2646 | |
| 2647 | -- Function: magit-insert-repo-header |
| 2648 | Insert a header line showing the path to the repository top-level. |
| 2649 | |
| 2650 | -- Function: magit-insert-remote-header |
| 2651 | Insert a header line about the remote of the current branch. |
| 2652 | |
| 2653 | If no remote is configured for the current branch, then fall back |
| 2654 | showing the "origin" remote, or if that does not exist the first |
| 2655 | remote in alphabetic order. |
| 2656 | |
| 2657 | -- Function: magit-insert-user-header |
| 2658 | Insert a header line about the current user. |
| 2659 | |
| 2660 | 5.1.5 Status Module Sections |
| 2661 | ---------------------------- |
| 2662 | |
| 2663 | The contents of status buffers is controlled using the hook |
| 2664 | ‘magit-status-sections-hook’ (see *note Status Sections::). |
| 2665 | |
| 2666 | By default ‘magit-insert-modules’ is _not_ a member of that hook |
| 2667 | variable. |
| 2668 | |
| 2669 | -- Function: magit-insert-modules |
| 2670 | Insert submodule sections. |
| 2671 | |
| 2672 | Hook ‘magit-module-sections-hook’ controls which module sections |
| 2673 | are inserted, and option ‘magit-module-sections-nested’ controls |
| 2674 | whether they are wrapped in an additional section. |
| 2675 | |
| 2676 | -- User Option: magit-module-sections-hook |
| 2677 | Hook run by ‘magit-insert-modules’. |
| 2678 | |
| 2679 | -- User Option: magit-module-sections-nested |
| 2680 | This option controls whether ‘magit-insert-modules’ wraps inserted |
| 2681 | sections in an additional section. |
| 2682 | |
| 2683 | If this is non-‘nil’, then only a single top-level section is |
| 2684 | inserted. If it is ‘nil’, then all sections listed in |
| 2685 | ‘magit-module-sections-hook’ become top-level sections. |
| 2686 | |
| 2687 | -- Function: magit-insert-modules-overview |
| 2688 | Insert sections for all submodules. For each section insert the |
| 2689 | path, the branch, and the output of ‘git describe --tags’, or, |
| 2690 | failing that, the abbreviated HEAD commit hash. |
| 2691 | |
| 2692 | Press ‘RET’ on such a submodule section to show its own status |
| 2693 | buffer. Press ‘RET’ on the "Modules" section to display a list of |
| 2694 | submodules in a separate buffer. This shows additional information |
| 2695 | not displayed in the super-repository's status buffer. |
| 2696 | |
| 2697 | -- Function: magit-insert-modules-unpulled-from-upstream |
| 2698 | Insert sections for modules that haven't been pulled from the |
| 2699 | upstream yet. These sections can be expanded to show the |
| 2700 | respective commits. |
| 2701 | |
| 2702 | -- Function: magit-insert-modules-unpulled-from-pushremote |
| 2703 | Insert sections for modules that haven't been pulled from the |
| 2704 | push-remote yet. These sections can be expanded to show the |
| 2705 | respective commits. |
| 2706 | |
| 2707 | -- Function: magit-insert-modules-unpushed-to-upstream |
| 2708 | Insert sections for modules that haven't been pushed to the |
| 2709 | upstream yet. These sections can be expanded to show the |
| 2710 | respective commits. |
| 2711 | |
| 2712 | -- Function: magit-insert-modules-unpushed-to-pushremote |
| 2713 | Insert sections for modules that haven't been pushed to the |
| 2714 | push-remote yet. These sections can be expanded to show the |
| 2715 | respective commits. |
| 2716 | |
| 2717 | 5.1.6 Status Options |
| 2718 | -------------------- |
| 2719 | |
| 2720 | -- User Option: magit-status-margin |
| 2721 | This option specifies whether the margin is initially shown in |
| 2722 | Magit-Status mode buffers and how it is formatted. |
| 2723 | |
| 2724 | The value has the form ‘(INIT STYLE WIDTH AUTHOR AUTHOR-WIDTH)’. |
| 2725 | |
| 2726 | • If INIT is non-‘nil’, then the margin is shown initially. |
| 2727 | • STYLE controls how to format the author or committer date. It |
| 2728 | can be one of ‘age’ (to show the age of the commit), |
| 2729 | ‘age-abbreviated’ (to abbreviate the time unit to a |
| 2730 | character), or a string (suitable for ‘format-time-string’) to |
| 2731 | show the actual date. Option |
| 2732 | ‘magit-log-margin-show-committer-date’ controls which date is |
| 2733 | being displayed. |
| 2734 | • WIDTH controls the width of the margin. This exists for |
| 2735 | forward compatibility and currently the value should not be |
| 2736 | changed. |
| 2737 | • AUTHOR controls whether the name of the author is also shown |
| 2738 | by default. |
| 2739 | • AUTHOR-WIDTH has to be an integer. When the name of the |
| 2740 | author is shown, then this specifies how much space is used to |
| 2741 | do so. |
| 2742 | |
| 2743 | Also see the proceeding section for more options concerning status |
| 2744 | buffers. |
| 2745 | |
| 2746 | |
| 2747 | File: magit.info, Node: Repository List, Next: Logging, Prev: Status Buffer, Up: Inspecting |
| 2748 | |
| 2749 | 5.2 Repository List |
| 2750 | =================== |
| 2751 | |
| 2752 | -- Command: magit-list-repositories |
| 2753 | This command displays a list of repositories in a separate buffer. |
| 2754 | |
| 2755 | Use option ‘magit-repository-directories’ to control which |
| 2756 | repositories are displayed. Use ".dir-locals.el" to specify a |
| 2757 | different set of repositories to be listed, when invoked from below |
| 2758 | a certain directory. With a prefix argument, always display the |
| 2759 | global list. |
| 2760 | |
| 2761 | -- User Option: magit-repolist-columns |
| 2762 | This option controls what columns are displayed by the command |
| 2763 | ‘magit-list-repositories’ and how they are displayed. |
| 2764 | |
| 2765 | Each element has the form ‘(HEADER WIDTH FORMAT PROPS)’. |
| 2766 | |
| 2767 | HEADER is the string displayed in the header. WIDTH is the width |
| 2768 | of the column. FORMAT is a function that is called with one |
| 2769 | argument, the repository identification (usually its basename), and |
| 2770 | with ‘default-directory’ bound to the toplevel of its working tree. |
| 2771 | It has to return a string to be inserted or ‘nil’. PROPS is an |
| 2772 | alist that supports the keys ‘:right-align’, ‘:pad-right’ and |
| 2773 | ‘:sort’. |
| 2774 | |
| 2775 | The ‘:sort’ function has a weird interface described in the |
| 2776 | docstring of ‘tabulated-list--get-sort’. Alternatively ‘<’ and |
| 2777 | ‘magit-repolist-version<’ can be used as those functions are |
| 2778 | automatically replaced with functions that satisfy the interface. |
| 2779 | Set ‘:sort’ to ‘nil’ to inhibit sorting; if unspecified, then the |
| 2780 | column is sortable using the default sorter. |
| 2781 | |
| 2782 | You may wish to display a range of numeric columns using just one |
| 2783 | character per column and without any padding between columns, in |
| 2784 | which case you should use an appropriate HEADER, set WIDTH to 1, |
| 2785 | and set ‘:pad-right’ to 9. ‘+’ is substituted for numbers higher |
| 2786 | than 9. |
| 2787 | |
| 2788 | The following functions can be added to the above option: |
| 2789 | |
| 2790 | -- Function: magit-repolist-column-ident |
| 2791 | This function inserts the identification of the repository. |
| 2792 | Usually this is just its basename. |
| 2793 | |
| 2794 | -- Function: magit-repolist-column-path |
| 2795 | This function inserts the absolute path of the repository. |
| 2796 | |
| 2797 | -- Function: magit-repolist-column-version |
| 2798 | This function inserts a description of the repository's ‘HEAD’ |
| 2799 | revision. |
| 2800 | |
| 2801 | -- Function: magit-repolist-column-branch |
| 2802 | This function inserts the name of the current branch. |
| 2803 | |
| 2804 | -- Function: magit-repolist-column-upstream |
| 2805 | This function inserts the name of the upstream branch of the |
| 2806 | current branch. |
| 2807 | |
| 2808 | -- Function: magit-repolist-column-branches |
| 2809 | This function inserts the number of branches. |
| 2810 | |
| 2811 | -- Function: magit-repolist-column-stashes |
| 2812 | This function inserts the number of stashes. |
| 2813 | |
| 2814 | -- Function: magit-repolist-column-flag |
| 2815 | This function inserts a flag as specified by |
| 2816 | ‘magit-repolist-column-flag-alist’. |
| 2817 | |
| 2818 | By default this indicates whether there are uncommitted changes. |
| 2819 | |
| 2820 | • ‘N’ if there is at least one untracked file. |
| 2821 | • ‘U’ if there is at least one unstaged file. |
| 2822 | • ‘S’ if there is at least one staged file. |
| 2823 | |
| 2824 | Only the first one of these that applies is shown. |
| 2825 | |
| 2826 | -- Function: magit-repolist-column-flags |
| 2827 | This functions insert all flags as specified by |
| 2828 | ‘magit-repolist-column-flag-alist’. |
| 2829 | |
| 2830 | This is an alternative to function ‘magit-repolist-column-flag’, |
| 2831 | which only lists the first one found. |
| 2832 | |
| 2833 | -- Function: magit-repolist-column-unpulled-from-upstream |
| 2834 | This function inserts the number of upstream commits not in the |
| 2835 | current branch. |
| 2836 | |
| 2837 | -- Function: magit-repolist-column-unpulled-from-pushremote |
| 2838 | This function inserts the number of commits in the push branch but |
| 2839 | not the current branch. |
| 2840 | |
| 2841 | -- Function: magit-repolist-column-unpushed-to-upstream |
| 2842 | This function inserts the number of commits in the current branch |
| 2843 | but not its upstream. |
| 2844 | |
| 2845 | -- Function: magit-repolist-column-unpushed-to-pushremote |
| 2846 | This function inserts the number of commits in the current branch |
| 2847 | but not its push branch. |
| 2848 | |
| 2849 | The following commands are available in repolist buffers: |
| 2850 | |
| 2851 | ‘<RET>’ (‘magit-repolist-status’) |
| 2852 | This command shows the status for the repository at point. |
| 2853 | |
| 2854 | ‘m’ (‘magit-repolist-mark’) |
| 2855 | This command marks the repository at point. |
| 2856 | |
| 2857 | ‘u’ (‘magit-repolist-unmark’) |
| 2858 | This command unmarks the repository at point. |
| 2859 | |
| 2860 | ‘f’ (‘magit-repolist-fetch’) |
| 2861 | This command fetches all marked repositories. If no repositories |
| 2862 | are marked, then it offers to fetch all displayed repositories. |
| 2863 | |
| 2864 | ‘5’ (‘magit-repolist-find-file-other-frame’) |
| 2865 | This command reads a relative file-name (without completion) and |
| 2866 | opens the respective file in each marked repository in a new frame. |
| 2867 | If no repositories are marked, then it offers to do this for all |
| 2868 | displayed repositories. |
| 2869 | |
| 2870 | |
| 2871 | File: magit.info, Node: Logging, Next: Diffing, Prev: Repository List, Up: Inspecting |
| 2872 | |
| 2873 | 5.3 Logging |
| 2874 | =========== |
| 2875 | |
| 2876 | The status buffer contains logs for the unpushed and unpulled commits, |
| 2877 | but that obviously isn't enough. The transient prefix command |
| 2878 | ‘magit-log’, on ‘l’, features several suffix commands, which show a |
| 2879 | specific log in a separate log buffer. |
| 2880 | |
| 2881 | Like other transient prefix commands, ‘magit-log’ also features |
| 2882 | several infix arguments that can be changed before invoking one of the |
| 2883 | suffix commands. However, in the case of the log transient, these |
| 2884 | arguments may be taken from those currently in use in the current |
| 2885 | repository's log buffer, depending on the value of |
| 2886 | ‘magit-prefix-use-buffer-arguments’ (see *note Transient Arguments and |
| 2887 | Buffer Variables::). |
| 2888 | |
| 2889 | For information about the various arguments, see *note |
| 2890 | (gitman)git-log::. The switch ‘++order=VALUE’ is converted to one of |
| 2891 | ‘--author-date-order’, ‘--date-order’, or ‘--topo-order’ before being |
| 2892 | passed to ‘git log’. |
| 2893 | |
| 2894 | The log transient also features several reflog commands. See *note |
| 2895 | Reflog::. |
| 2896 | |
| 2897 | ‘l’ (‘magit-log’) |
| 2898 | This transient prefix command binds the following suffix commands |
| 2899 | along with the appropriate infix arguments and displays them in a |
| 2900 | temporary buffer until a suffix is invoked. |
| 2901 | |
| 2902 | ‘l l’ (‘magit-log-current’) |
| 2903 | Show log for the current branch. When ‘HEAD’ is detached or with a |
| 2904 | prefix argument, show log for one or more revs read from the |
| 2905 | minibuffer. |
| 2906 | |
| 2907 | ‘l h’ (‘magit-log-head’) |
| 2908 | Show log for ‘HEAD’. |
| 2909 | |
| 2910 | ‘l u’ (‘magit-log-related’) |
| 2911 | Show log for the current branch, its upstream and its push target. |
| 2912 | When the upstream is a local branch, then also show its own |
| 2913 | upstream. When ‘HEAD’ is detached, then show log for that, the |
| 2914 | previously checked out branch and its upstream and push-target. |
| 2915 | |
| 2916 | ‘l o’ (‘magit-log-other’) |
| 2917 | Show log for one or more revs read from the minibuffer. The user |
| 2918 | can input any revision or revisions separated by a space, or even |
| 2919 | ranges, but only branches, tags, and a representation of the commit |
| 2920 | at point are available as completion candidates. |
| 2921 | |
| 2922 | ‘l L’ (‘magit-log-branches’) |
| 2923 | Show log for all local branches and ‘HEAD’. |
| 2924 | |
| 2925 | ‘l b’ (‘magit-log-all-branches’) |
| 2926 | Show log for all local and remote branches and ‘HEAD’. |
| 2927 | |
| 2928 | ‘l a’ (‘magit-log-all’) |
| 2929 | Show log for all references and ‘HEAD’. |
| 2930 | |
| 2931 | Two additional commands that show the log for the file or blob that |
| 2932 | is being visited in the current buffer exists, see *note Commands for |
| 2933 | Buffers Visiting Files::. The command ‘magit-cherry’ also shows a log, |
| 2934 | see *note Cherries::. |
| 2935 | |
| 2936 | 5.3.1 Refreshing Logs |
| 2937 | --------------------- |
| 2938 | |
| 2939 | The transient prefix command ‘magit-log-refresh’, on ‘L’, can be used to |
| 2940 | change the log arguments used in the current buffer, without changing |
| 2941 | which log is shown. This works in dedicated log buffers, but also in |
| 2942 | the status buffer. |
| 2943 | |
| 2944 | ‘L’ (‘magit-log-refresh’) |
| 2945 | This transient prefix command binds the following suffix commands |
| 2946 | along with the appropriate infix arguments and displays them in a |
| 2947 | temporary buffer until a suffix is invoked. |
| 2948 | |
| 2949 | ‘L g’ (‘magit-log-refresh’) |
| 2950 | This suffix command sets the local log arguments for the current |
| 2951 | buffer. |
| 2952 | |
| 2953 | ‘L s’ (‘magit-log-set-default-arguments’) |
| 2954 | This suffix command sets the default log arguments for buffers of |
| 2955 | the same type as that of the current buffer. Other existing |
| 2956 | buffers of the same type are not affected because their local |
| 2957 | values have already been initialized. |
| 2958 | |
| 2959 | ‘L w’ (‘magit-log-save-default-arguments’) |
| 2960 | This suffix command sets the default log arguments for buffers of |
| 2961 | the same type as that of the current buffer, and saves the value |
| 2962 | for future sessions. Other existing buffers of the same type are |
| 2963 | not affected because their local values have already been |
| 2964 | initialized. |
| 2965 | |
| 2966 | ‘L L’ (‘magit-toggle-margin’) |
| 2967 | Show or hide the margin. |
| 2968 | |
| 2969 | 5.3.2 Log Buffer |
| 2970 | ---------------- |
| 2971 | |
| 2972 | ‘L’ (‘magit-log-refresh’) |
| 2973 | This transient prefix command binds the following suffix commands |
| 2974 | along with the appropriate infix arguments and displays them in a |
| 2975 | temporary buffer until a suffix is invoked. |
| 2976 | |
| 2977 | See *note Refreshing Logs::. |
| 2978 | |
| 2979 | ‘q’ (‘magit-log-bury-buffer’) |
| 2980 | Bury the current buffer or the revision buffer in the same frame. |
| 2981 | Like ‘magit-mode-bury-buffer’ (which see) but with a negative |
| 2982 | prefix argument instead bury the revision buffer, provided it is |
| 2983 | displayed in the current frame. |
| 2984 | |
| 2985 | ‘C-c C-b’ (‘magit-go-backward’) |
| 2986 | Move backward in current buffer's history. |
| 2987 | |
| 2988 | ‘C-c C-f’ (‘magit-go-forward’) |
| 2989 | Move forward in current buffer's history. |
| 2990 | |
| 2991 | ‘C-c C-n’ (‘magit-log-move-to-parent’) |
| 2992 | Move to a parent of the current commit. By default, this is the |
| 2993 | first parent, but a numeric prefix can be used to specify another |
| 2994 | parent. |
| 2995 | |
| 2996 | ‘j’ (‘magit-log-move-to-revision’) |
| 2997 | Read a revision and move to it in current log buffer. |
| 2998 | |
| 2999 | If the chosen reference or revision isn't being displayed in the |
| 3000 | current log buffer, then inform the user about that and do nothing |
| 3001 | else. |
| 3002 | |
| 3003 | If invoked outside any log buffer, then display the log buffer of |
| 3004 | the current repository first; creating it if necessary. |
| 3005 | |
| 3006 | ‘<SPC>’ (‘magit-diff-show-or-scroll-up’) |
| 3007 | Update the commit or diff buffer for the thing at point. |
| 3008 | |
| 3009 | Either show the commit or stash at point in the appropriate buffer, |
| 3010 | or if that buffer is already being displayed in the current frame |
| 3011 | and contains information about that commit or stash, then instead |
| 3012 | scroll the buffer up. If there is no commit or stash at point, |
| 3013 | then prompt for a commit. |
| 3014 | |
| 3015 | ‘<DEL>’ (‘magit-diff-show-or-scroll-down’) |
| 3016 | Update the commit or diff buffer for the thing at point. |
| 3017 | |
| 3018 | Either show the commit or stash at point in the appropriate buffer, |
| 3019 | or if that buffer is already being displayed in the current frame |
| 3020 | and contains information about that commit or stash, then instead |
| 3021 | scroll the buffer down. If there is no commit or stash at point, |
| 3022 | then prompt for a commit. |
| 3023 | |
| 3024 | ‘=’ (‘magit-log-toggle-commit-limit’) |
| 3025 | Toggle the number of commits the current log buffer is limited to. |
| 3026 | If the number of commits is currently limited, then remove that |
| 3027 | limit. Otherwise set it to 256. |
| 3028 | |
| 3029 | ‘+’ (‘magit-log-double-commit-limit’) |
| 3030 | Double the number of commits the current log buffer is limited to. |
| 3031 | |
| 3032 | ‘-’ (‘magit-log-half-commit-limit’) |
| 3033 | Half the number of commits the current log buffer is limited to. |
| 3034 | |
| 3035 | -- User Option: magit-log-auto-more |
| 3036 | Insert more log entries automatically when moving past the last |
| 3037 | entry. Only considered when moving past the last entry with |
| 3038 | ‘magit-goto-*-section’ commands. |
| 3039 | |
| 3040 | -- User Option: magit-log-show-refname-after-summary |
| 3041 | Whether to show the refnames after the commit summaries. This is |
| 3042 | useful if you use really long branch names. |
| 3043 | |
| 3044 | -- User Option: magit-log-show-color-graph-limit |
| 3045 | When showing more commits than specified by this option, then the |
| 3046 | ‘--color’ argument, if specified, is silently dropped. This is |
| 3047 | necessary because the ‘ansi-color’ library, which is used to turn |
| 3048 | control sequences into faces, is just too slow. |
| 3049 | |
| 3050 | -- User Option: magit-log-show-signatures-limit |
| 3051 | When showing more commits than specified by this option, then the |
| 3052 | ‘--show-signature’ argument, if specified, is silently dropped. |
| 3053 | This is necessary because checking the signature of a large number |
| 3054 | of commits is just too slow. |
| 3055 | |
| 3056 | Magit displays references in logs a bit differently from how Git does |
| 3057 | it. |
| 3058 | |
| 3059 | Local branches are blue and remote branches are green. Of course |
| 3060 | that depends on the used theme, as do the colors used for other types of |
| 3061 | references. The current branch has a box around it, as do remote |
| 3062 | branches that are their respective remote's ‘HEAD’ branch. |
| 3063 | |
| 3064 | If a local branch and its push-target point at the same commit, then |
| 3065 | their names are combined to preserve space and to make that relationship |
| 3066 | visible. For example: |
| 3067 | |
| 3068 | origin/feature |
| 3069 | [green][blue-] |
| 3070 | |
| 3071 | instead of |
| 3072 | |
| 3073 | feature origin/feature |
| 3074 | [blue-] [green-------] |
| 3075 | |
| 3076 | Also note that while the transient features the ‘--show-signature’ |
| 3077 | argument, that won't actually be used when enabled, because Magit |
| 3078 | defaults to use just one line per commit. Instead the commit colorized |
| 3079 | to indicate the validity of the signed commit object, using the faces |
| 3080 | named ‘magit-signature-*’ (which see). |
| 3081 | |
| 3082 | For a description of ‘magit-log-margin’ see *note Log Margin::. |
| 3083 | |
| 3084 | 5.3.3 Log Margin |
| 3085 | ---------------- |
| 3086 | |
| 3087 | In buffers which show one or more logs, it is possible to show |
| 3088 | additional information about each commit in the margin. The options |
| 3089 | used to configure the margin are named ‘magit-INFIX-margin’, where INFIX |
| 3090 | is the same as in the respective major-mode ‘magit-INFIX-mode’. In |
| 3091 | regular log buffers that would be ‘magit-log-margin’. |
| 3092 | |
| 3093 | -- User Option: magit-log-margin |
| 3094 | This option specifies whether the margin is initially shown in |
| 3095 | Magit-Log mode buffers and how it is formatted. |
| 3096 | |
| 3097 | The value has the form ‘(INIT STYLE WIDTH AUTHOR AUTHOR-WIDTH)’. |
| 3098 | |
| 3099 | • If INIT is non-‘nil’, then the margin is shown initially. |
| 3100 | • STYLE controls how to format the author or committer date. It |
| 3101 | can be one of ‘age’ (to show the age of the commit), |
| 3102 | ‘age-abbreviated’ (to abbreviate the time unit to a |
| 3103 | character), or a string (suitable for ‘format-time-string’) to |
| 3104 | show the actual date. Option |
| 3105 | ‘magit-log-margin-show-committer-date’ controls which date is |
| 3106 | being displayed. |
| 3107 | • WIDTH controls the width of the margin. This exists for |
| 3108 | forward compatibility and currently the value should not be |
| 3109 | changed. |
| 3110 | • AUTHOR controls whether the name of the author is also shown |
| 3111 | by default. |
| 3112 | • AUTHOR-WIDTH has to be an integer. When the name of the |
| 3113 | author is shown, then this specifies how much space is used to |
| 3114 | do so. |
| 3115 | |
| 3116 | You can change the STYLE and AUTHOR-WIDTH of all ‘magit-INFIX-margin’ |
| 3117 | options to the same values by customizing ‘magit-log-margin’ *before* |
| 3118 | ‘magit’ is loaded. If you do that, then the respective values for the |
| 3119 | other options will default to what you have set for that variable. |
| 3120 | Likewise if you set INIT in ‘magit-log-margin’ to ‘nil’, then that is |
| 3121 | used in the default of all other options. But setting it to ‘t’, i.e. |
| 3122 | re-enforcing the default for that option, does not carry to other |
| 3123 | options. |
| 3124 | |
| 3125 | -- User Option: magit-log-margin-show-committer-date |
| 3126 | This option specifies whether to show the committer date in the |
| 3127 | margin. This option only controls whether the committer date is |
| 3128 | displayed instead of the author date. Whether some date is |
| 3129 | displayed in the margin and whether the margin is displayed at all |
| 3130 | is controlled by other options. |
| 3131 | |
| 3132 | ‘L’ (‘magit-margin-settings’) |
| 3133 | This transient prefix command binds the following suffix commands, |
| 3134 | each of which changes the appearance of the margin in some way. |
| 3135 | |
| 3136 | In some buffers that support the margin, ‘L’ is instead bound to |
| 3137 | ‘magit-log-refresh’, but that transient features the same commands, and |
| 3138 | then some other unrelated commands. |
| 3139 | |
| 3140 | ‘L L’ (‘magit-toggle-margin’) |
| 3141 | This command shows or hides the margin. |
| 3142 | |
| 3143 | ‘L l’ (‘magit-cycle-margin-style’) |
| 3144 | This command cycles the style used for the margin. |
| 3145 | |
| 3146 | ‘L d’ (‘magit-toggle-margin-details’) |
| 3147 | This command shows or hides details in the margin. |
| 3148 | |
| 3149 | 5.3.4 Select from Log |
| 3150 | --------------------- |
| 3151 | |
| 3152 | When the user has to select a recent commit that is reachable from |
| 3153 | ‘HEAD’, using regular completion would be inconvenient (because most |
| 3154 | humans cannot remember hashes or "HEAD~5", at least not without double |
| 3155 | checking). Instead a log buffer is used to select the commit, which has |
| 3156 | the advantage that commits are presented in order and with the commit |
| 3157 | message. |
| 3158 | |
| 3159 | Such selection logs are used when selecting the beginning of a rebase |
| 3160 | and when selecting the commit to be squashed into. |
| 3161 | |
| 3162 | In addition to the key bindings available in all log buffers, the |
| 3163 | following additional key bindings are available in selection log |
| 3164 | buffers: |
| 3165 | |
| 3166 | ‘C-c C-c’ (‘magit-log-select-pick’) |
| 3167 | Select the commit at point and act on it. Call |
| 3168 | ‘magit-log-select-pick-function’ with the selected commit as |
| 3169 | argument. |
| 3170 | |
| 3171 | ‘C-c C-k’ (‘magit-log-select-quit’) |
| 3172 | Abort selecting a commit, don't act on any commit. |
| 3173 | |
| 3174 | -- User Option: magit-log-select-margin |
| 3175 | This option specifies whether the margin is initially shown in |
| 3176 | Magit-Log-Select mode buffers and how it is formatted. |
| 3177 | |
| 3178 | The value has the form ‘(INIT STYLE WIDTH AUTHOR AUTHOR-WIDTH)’. |
| 3179 | |
| 3180 | • If INIT is non-‘nil’, then the margin is shown initially. |
| 3181 | • STYLE controls how to format the author or committer date. It |
| 3182 | can be one of ‘age’ (to show the age of the commit), |
| 3183 | ‘age-abbreviated’ (to abbreviate the time unit to a |
| 3184 | character), or a string (suitable for ‘format-time-string’) to |
| 3185 | show the actual date. Option |
| 3186 | ‘magit-log-margin-show-committer-date’ controls which date is |
| 3187 | being displayed. |
| 3188 | • WIDTH controls the width of the margin. This exists for |
| 3189 | forward compatibility and currently the value should not be |
| 3190 | changed. |
| 3191 | • AUTHOR controls whether the name of the author is also shown |
| 3192 | by default. |
| 3193 | • AUTHOR-WIDTH has to be an integer. When the name of the |
| 3194 | author is shown, then this specifies how much space is used to |
| 3195 | do so. |
| 3196 | |
| 3197 | 5.3.5 Reflog |
| 3198 | ------------ |
| 3199 | |
| 3200 | Also see *note (gitman)git-reflog::. |
| 3201 | |
| 3202 | These reflog commands are available from the log transient. See |
| 3203 | *note Logging::. |
| 3204 | |
| 3205 | ‘l r’ (‘magit-reflog-current’) |
| 3206 | Display the reflog of the current branch. |
| 3207 | |
| 3208 | ‘l O’ (‘magit-reflog-other’) |
| 3209 | Display the reflog of a branch or another ref. |
| 3210 | |
| 3211 | ‘l H’ (‘magit-reflog-head’) |
| 3212 | Display the ‘HEAD’ reflog. |
| 3213 | |
| 3214 | -- User Option: magit-reflog-margin |
| 3215 | This option specifies whether the margin is initially shown in |
| 3216 | Magit-Reflog mode buffers and how it is formatted. |
| 3217 | |
| 3218 | The value has the form ‘(INIT STYLE WIDTH AUTHOR AUTHOR-WIDTH)’. |
| 3219 | |
| 3220 | • If INIT is non-‘nil’, then the margin is shown initially. |
| 3221 | • STYLE controls how to format the author or committer date. It |
| 3222 | can be one of ‘age’ (to show the age of the commit), |
| 3223 | ‘age-abbreviated’ (to abbreviate the time unit to a |
| 3224 | character), or a string (suitable for ‘format-time-string’) to |
| 3225 | show the actual date. Option |
| 3226 | ‘magit-log-margin-show-committer-date’ controls which date is |
| 3227 | being displayed. |
| 3228 | • WIDTH controls the width of the margin. This exists for |
| 3229 | forward compatibility and currently the value should not be |
| 3230 | changed. |
| 3231 | • AUTHOR controls whether the name of the author is also shown |
| 3232 | by default. |
| 3233 | • AUTHOR-WIDTH has to be an integer. When the name of the |
| 3234 | author is shown, then this specifies how much space is used to |
| 3235 | do so. |
| 3236 | |
| 3237 | 5.3.6 Cherries |
| 3238 | -------------- |
| 3239 | |
| 3240 | Cherries are commits that haven't been applied upstream (yet), and are |
| 3241 | usually visualized using a log. Each commit is prefixed with ‘-’ if it |
| 3242 | has an equivalent in the upstream and ‘+’ if it does not, i.e., if it is |
| 3243 | a cherry. |
| 3244 | |
| 3245 | The command ‘magit-cherry’ shows cherries for a single branch, but |
| 3246 | the references buffer (see *note References Buffer::) can show cherries |
| 3247 | for multiple "upstreams" at once. |
| 3248 | |
| 3249 | Also see *note (gitman)git-reflog::. |
| 3250 | |
| 3251 | ‘Y’ (‘magit-cherry’) |
| 3252 | Show commits that are in a certain branch but that have not been |
| 3253 | merged in the upstream branch. |
| 3254 | |
| 3255 | -- User Option: magit-cherry-margin |
| 3256 | This option specifies whether the margin is initially shown in |
| 3257 | Magit-Cherry mode buffers and how it is formatted. |
| 3258 | |
| 3259 | The value has the form ‘(INIT STYLE WIDTH AUTHOR AUTHOR-WIDTH)’. |
| 3260 | |
| 3261 | • If INIT is non-‘nil’, then the margin is shown initially. |
| 3262 | • STYLE controls how to format the author or committer date. It |
| 3263 | can be one of ‘age’ (to show the age of the commit), |
| 3264 | ‘age-abbreviated’ (to abbreviate the time unit to a |
| 3265 | character), or a string (suitable for ‘format-time-string’) to |
| 3266 | show the actual date. Option |
| 3267 | ‘magit-log-margin-show-committer-date’ controls which date is |
| 3268 | being displayed. |
| 3269 | • WIDTH controls the width of the margin. This exists for |
| 3270 | forward compatibility and currently the value should not be |
| 3271 | changed. |
| 3272 | • AUTHOR controls whether the name of the author is also shown |
| 3273 | by default. |
| 3274 | • AUTHOR-WIDTH has to be an integer. When the name of the |
| 3275 | author is shown, then this specifies how much space is used to |
| 3276 | do so. |
| 3277 | |
| 3278 | |
| 3279 | File: magit.info, Node: Diffing, Next: Ediffing, Prev: Logging, Up: Inspecting |
| 3280 | |
| 3281 | 5.4 Diffing |
| 3282 | =========== |
| 3283 | |
| 3284 | The status buffer contains diffs for the staged and unstaged commits, |
| 3285 | but that obviously isn't enough. The transient prefix command |
| 3286 | ‘magit-diff’, on ‘d’, features several suffix commands, which show a |
| 3287 | specific diff in a separate diff buffer. |
| 3288 | |
| 3289 | Like other transient prefix commands, ‘magit-diff’ also features |
| 3290 | several infix arguments that can be changed before invoking one of the |
| 3291 | suffix commands. However, in the case of the diff transient, these |
| 3292 | arguments may be taken from those currently in use in the current |
| 3293 | repository's diff buffer, depending on the value of |
| 3294 | ‘magit-prefix-use-buffer-arguments’ (see *note Transient Arguments and |
| 3295 | Buffer Variables::). |
| 3296 | |
| 3297 | Also see *note (gitman)git-diff::. |
| 3298 | |
| 3299 | ‘d’ (‘magit-diff’) |
| 3300 | This transient prefix command binds the following suffix commands |
| 3301 | along with the appropriate infix arguments and displays them in a |
| 3302 | temporary buffer until a suffix is invoked. |
| 3303 | |
| 3304 | ‘d d’ (‘magit-diff-dwim’) |
| 3305 | Show changes for the thing at point. |
| 3306 | |
| 3307 | For example, if point is on a commit, show the changes introduced |
| 3308 | by that commit. Likewise if point is on the section titled |
| 3309 | "Unstaged changes", then show those changes in a separate buffer. |
| 3310 | Generally speaking, compare the thing at point with the most |
| 3311 | logical, trivial and (in *any* situation) at least potentially |
| 3312 | useful other thing it could be compared to. |
| 3313 | |
| 3314 | When the region selects commits, then compare the two commits at |
| 3315 | either end. There are different ways two commits can be compared. |
| 3316 | In the buffer showing the diff, you can control how the comparison, |
| 3317 | is done, using "D r" and "D f". |
| 3318 | |
| 3319 | This function does not always show the changes that you might want |
| 3320 | to view in any given situation. You can think of the changes being |
| 3321 | shown as the smallest common denominator. There is no AI involved. |
| 3322 | If this command never does what you want, then ignore it, and |
| 3323 | instead use the commands that allow you to explicitly specify what |
| 3324 | you need. |
| 3325 | |
| 3326 | ‘d r’ (‘magit-diff-range’) |
| 3327 | Show differences between two commits. |
| 3328 | |
| 3329 | RANGE should be a range (A..B or A...B) but can also be a single |
| 3330 | commit. If one side of the range is omitted, then it defaults to |
| 3331 | ‘HEAD’. If just a commit is given, then changes in the working |
| 3332 | tree relative to that commit are shown. |
| 3333 | |
| 3334 | If the region is active, use the revisions on the first and last |
| 3335 | line of the region. With a prefix argument, instead of diffing the |
| 3336 | revisions, choose a revision to view changes along, starting at the |
| 3337 | common ancestor of both revisions (i.e., use a "..." range). |
| 3338 | |
| 3339 | ‘d w’ (‘magit-diff-working-tree’) |
| 3340 | Show changes between the current working tree and the ‘HEAD’ |
| 3341 | commit. With a prefix argument show changes between the working |
| 3342 | tree and a commit read from the minibuffer. |
| 3343 | |
| 3344 | ‘d s’ (‘magit-diff-staged’) |
| 3345 | Show changes between the index and the ‘HEAD’ commit. With a |
| 3346 | prefix argument show changes between the index and a commit read |
| 3347 | from the minibuffer. |
| 3348 | |
| 3349 | ‘d u’ (‘magit-diff-unstaged’) |
| 3350 | Show changes between the working tree and the index. |
| 3351 | |
| 3352 | ‘d p’ (‘magit-diff-paths’) |
| 3353 | Show changes between any two files on disk. |
| 3354 | |
| 3355 | All of the above suffix commands update the repository's diff buffer. |
| 3356 | The diff transient also features two commands which show differences in |
| 3357 | another buffer: |
| 3358 | |
| 3359 | ‘d c’ (‘magit-show-commit’) |
| 3360 | Show the commit at point. If there is no commit at point or with a |
| 3361 | prefix argument, prompt for a commit. |
| 3362 | |
| 3363 | ‘d t’ (‘magit-stash-show’) |
| 3364 | Show all diffs of a stash in a buffer. |
| 3365 | |
| 3366 | Two additional commands that show the diff for the file or blob that |
| 3367 | is being visited in the current buffer exists, see *note Commands for |
| 3368 | Buffers Visiting Files::. |
| 3369 | |
| 3370 | 5.4.1 Refreshing Diffs |
| 3371 | ---------------------- |
| 3372 | |
| 3373 | The transient prefix command ‘magit-diff-refresh’, on ‘D’, can be used |
| 3374 | to change the diff arguments used in the current buffer, without |
| 3375 | changing which diff is shown. This works in dedicated diff buffers, but |
| 3376 | also in the status buffer. |
| 3377 | |
| 3378 | (There is one exception; diff arguments cannot be changed in buffers |
| 3379 | created by ‘magit-merge-preview’ because the underlying Git command does |
| 3380 | not support these arguments.) |
| 3381 | |
| 3382 | ‘D’ (‘magit-diff-refresh’) |
| 3383 | This transient prefix command binds the following suffix commands |
| 3384 | along with the appropriate infix arguments and displays them in a |
| 3385 | temporary buffer until a suffix is invoked. |
| 3386 | |
| 3387 | ‘D g’ (‘magit-diff-refresh’) |
| 3388 | This suffix command sets the local diff arguments for the current |
| 3389 | buffer. |
| 3390 | |
| 3391 | ‘D s’ (‘magit-diff-set-default-arguments’) |
| 3392 | This suffix command sets the default diff arguments for buffers of |
| 3393 | the same type as that of the current buffer. Other existing |
| 3394 | buffers of the same type are not affected because their local |
| 3395 | values have already been initialized. |
| 3396 | |
| 3397 | ‘D w’ (‘magit-diff-save-default-arguments’) |
| 3398 | This suffix command sets the default diff arguments for buffers of |
| 3399 | the same type as that of the current buffer, and saves the value |
| 3400 | for future sessions. Other existing buffers of the same type are |
| 3401 | not affected because their local values have already been |
| 3402 | initialized. |
| 3403 | |
| 3404 | ‘D t’ (‘magit-diff-toggle-refine-hunk’) |
| 3405 | This command toggles hunk refinement on or off, or switches the |
| 3406 | refinement method. |
| 3407 | |
| 3408 | If hunk refinement is currently on, then turn off hunk refinement. |
| 3409 | If hunk refinement is off, then turn on immediate hunk refinement. |
| 3410 | |
| 3411 | With a prefix argument, an alternative refinement method comes into |
| 3412 | play. When using that method, mode hunks are not refined |
| 3413 | immediately, instead each hunk is refined once it is selected, and |
| 3414 | then stays refined until the next refresh of the buffer. If hunk |
| 3415 | refinement is currently on, then toggle between refining all hunks |
| 3416 | up front or only once they are selected. If hunk refinement is |
| 3417 | off, then turn on hunk refinement, using the eventual refinement |
| 3418 | method. |
| 3419 | |
| 3420 | Customize option ‘magit-diff-refine-hunk’ to change the default |
| 3421 | method. |
| 3422 | |
| 3423 | ‘D T’ (‘magit-diff-toggle-fontify-hunk’) |
| 3424 | This command toggles hunk fontification on or off, or switches the |
| 3425 | fontification method. |
| 3426 | |
| 3427 | If hunk fontification is currently on, then turn off hunk |
| 3428 | fontification. If hunk fontification is off, then turn on |
| 3429 | immediate hunk fontification. |
| 3430 | |
| 3431 | With a prefix argument, an alternative fontification method comes |
| 3432 | into play. When using that method, mode hunks are not refined |
| 3433 | immediately, instead each hunk is refined once it is selected, and |
| 3434 | then stays refined until the next refresh of the buffer. If hunk |
| 3435 | fontification is currently on, then toggle between refining all |
| 3436 | hunks up front or only once they are selected. If hunk |
| 3437 | fontification is off, then turn on fontification, using the |
| 3438 | eventual fontification method. |
| 3439 | |
| 3440 | Customize option ‘magit-diff-fontify-hunk’ to change the default |
| 3441 | method. |
| 3442 | |
| 3443 | ‘D r’ (‘magit-diff-switch-range-type’) |
| 3444 | This command converts the diff range type from "revA..revB" to |
| 3445 | "revB...revA", or vice versa. |
| 3446 | |
| 3447 | ‘D f’ (‘magit-diff-flip-revs’) |
| 3448 | This command swaps revisions in the diff range from "revA..revB" to |
| 3449 | "revB..revA", or vice versa. |
| 3450 | |
| 3451 | ‘D F’ (‘magit-diff-toggle-file-filter’) |
| 3452 | This command toggles the file restriction of the diffs in the |
| 3453 | current buffer, allowing you to quickly switch between viewing all |
| 3454 | the changes in the commit and the restricted subset. As a special |
| 3455 | case, when this command is called from a log buffer, it toggles the |
| 3456 | file restriction in the repository's revision buffer, which is |
| 3457 | useful when you display a revision from a log buffer that is |
| 3458 | restricted to a file or files. |
| 3459 | |
| 3460 | In addition to the above transient, which allows changing any of the |
| 3461 | supported arguments, there also exist some commands that change only a |
| 3462 | particular argument. |
| 3463 | |
| 3464 | ‘-’ (‘magit-diff-less-context’) |
| 3465 | This command decreases the context for diff hunks by COUNT lines. |
| 3466 | |
| 3467 | ‘+’ (‘magit-diff-more-context’) |
| 3468 | This command increases the context for diff hunks by COUNT lines. |
| 3469 | |
| 3470 | ‘0’ (‘magit-diff-default-context’) |
| 3471 | This command resets the context for diff hunks to the default |
| 3472 | height. |
| 3473 | |
| 3474 | The following commands quickly change what diff is being displayed |
| 3475 | without having to using one of the diff transient. |
| 3476 | |
| 3477 | ‘C-c C-d’ (‘magit-diff-while-committing’) |
| 3478 | While committing, this command shows the changes that are about to |
| 3479 | be committed. While amending, invoking the command again toggles |
| 3480 | between showing just the new changes or all the changes that will |
| 3481 | be committed. |
| 3482 | |
| 3483 | This binding is available in the diff buffer as well as the commit |
| 3484 | message buffer. |
| 3485 | |
| 3486 | ‘C-c C-b’ (‘magit-go-backward’) |
| 3487 | This command moves backward in current buffer's history. |
| 3488 | |
| 3489 | ‘C-c C-f’ (‘magit-go-forward’) |
| 3490 | This command moves forward in current buffer's history. |
| 3491 | |
| 3492 | 5.4.2 Commands Available in Diffs |
| 3493 | --------------------------------- |
| 3494 | |
| 3495 | Some commands are only available if point is inside a diff. |
| 3496 | |
| 3497 | ‘magit-diff-visit-file’ and related commands visit the appropriate |
| 3498 | version of the file that the diff at point is about. Likewise |
| 3499 | ‘magit-diff-visit-worktree-file’ and related commands visit the worktree |
| 3500 | version of the file that the diff at point is about. See *note Visiting |
| 3501 | Files and Blobs from a Diff:: for more information and the key bindings. |
| 3502 | |
| 3503 | ‘C-c C-t’ (‘magit-diff-trace-definition’) |
| 3504 | This command shows a log for the definition at point. |
| 3505 | |
| 3506 | -- User Option: magit-log-trace-definition-function |
| 3507 | The function specified by this option is used by |
| 3508 | ‘magit-log-trace-definition’ to determine the function at point. |
| 3509 | For major-modes that have special needs, you could set the local |
| 3510 | value using the mode's hook. |
| 3511 | |
| 3512 | ‘C-c C-e’ (‘magit-diff-edit-hunk-commit’) |
| 3513 | From a hunk, this command edits the respective commit and visits |
| 3514 | the file. |
| 3515 | |
| 3516 | First it visits the file being modified by the hunk at the correct |
| 3517 | location using ‘magit-diff-visit-file’. This actually visits a |
| 3518 | blob. When point is on a diff header, not within an individual |
| 3519 | hunk, then this visits the blob the first hunk is about. |
| 3520 | |
| 3521 | Then it invokes ‘magit-edit-line-commit’, which uses an interactive |
| 3522 | rebase to make the commit editable, or if that is not possible |
| 3523 | because the commit is not reachable from ‘HEAD’ by checking out |
| 3524 | that commit directly. This also causes the actual worktree file to |
| 3525 | be visited. |
| 3526 | |
| 3527 | Neither the blob nor the file buffer are killed when finishing the |
| 3528 | rebase. If that is undesirable, then it might be better to use |
| 3529 | ‘magit-rebase-edit-commit’ instead of this command. |
| 3530 | |
| 3531 | ‘j’ (‘magit-jump-to-diffstat-or-diff’) |
| 3532 | This command jumps to the diffstat or diff. When point is on a |
| 3533 | file inside the diffstat section, then jump to the respective diff |
| 3534 | section. Otherwise, jump to the diffstat section or a child |
| 3535 | thereof. |
| 3536 | |
| 3537 | The next two commands are not specific to Magit-Diff mode (or and |
| 3538 | Magit buffer for that matter), but it might be worth pointing out that |
| 3539 | they are available here too. |
| 3540 | |
| 3541 | ‘<SPC>’ (‘scroll-up’) |
| 3542 | This command scrolls text upward. |
| 3543 | |
| 3544 | ‘<DEL>’ (‘scroll-down’) |
| 3545 | This command scrolls text downward. |
| 3546 | |
| 3547 | 5.4.3 Diff Options |
| 3548 | ------------------ |
| 3549 | |
| 3550 | -- User Option: magit-diff-refine-hunk |
| 3551 | Whether to show word-granularity differences within diff hunks. |
| 3552 | |
| 3553 | • ‘nil’ Never show fine differences. |
| 3554 | • ‘all’ Show fine differences for all displayed diff hunks. |
| 3555 | • ‘t’ Refine each hunk once it becomes the current section. |
| 3556 | Keep the refinement when another section is selected. |
| 3557 | Refreshing the buffer removes all refinement. This variant is |
| 3558 | only provided for performance reasons. |
| 3559 | |
| 3560 | -- User Option: magit-diff-refine-ignore-whitespace |
| 3561 | Whether to ignore whitespace changes in word-granularity |
| 3562 | differences. |
| 3563 | |
| 3564 | -- User Option: magit-diff-fontify-hunk |
| 3565 | Whether to apply syntax highlighting to diff hunks. |
| 3566 | |
| 3567 | • ‘nil’ Never fontify diff hunks. |
| 3568 | • ‘all’ Fontify all diff hunks. |
| 3569 | • ‘t’ Fontify each hunk once it becomes the current section. |
| 3570 | Keep the fontification when another section is selected. |
| 3571 | Refreshing the buffer removes all fontification. This variant |
| 3572 | is only provided for performance reasons. |
| 3573 | |
| 3574 | If this is enabled, then ‘magit-diff-specify-hunk-foreground’ |
| 3575 | should be disabled. Also consider enabling |
| 3576 | ‘magit-diff-use-indicator-faces’. Emacs has to be restarted, after |
| 3577 | changing the value of the former. |
| 3578 | |
| 3579 | This is considered experimental and is disabled by default, because |
| 3580 | the fontification is done synchronously, and that can lead to a |
| 3581 | noticeable delay. The plan is to make it asynchronous, probably |
| 3582 | with the help of the new ‘futur’ package, which itself still under |
| 3583 | heavy development. |
| 3584 | |
| 3585 | -- User Option: magit-diff-specify-hunk-foreground |
| 3586 | Whether to specify foreground colors for hunk faces. |
| 3587 | |
| 3588 | Setting this only has an effect if done before Magit is loaded. |
| 3589 | |
| 3590 | -- User Option: magit-diff-use-indicator-faces |
| 3591 | Whether to use separate faces for diff side indicators. |
| 3592 | |
| 3593 | If non-‘nil’, use, for example, ‘magit-diff-removed-indicator’ for |
| 3594 | the plus sign at the beginning of a removed line. If ‘nil’, use |
| 3595 | the same face as for the rest of the line. |
| 3596 | |
| 3597 | -- User Option: magit-diff-adjust-tab-width |
| 3598 | Whether to adjust the width of tabs in diffs. |
| 3599 | |
| 3600 | Determining the correct width can be expensive if it requires |
| 3601 | opening large and/or many files, so the widths are cached in the |
| 3602 | variable ‘magit-diff--tab-width-cache’. Set that to ‘nil’ to |
| 3603 | invalidate the cache. |
| 3604 | |
| 3605 | • ‘nil’ Never adjust tab width. Use 'tab-width's value from the |
| 3606 | Magit buffer itself instead. |
| 3607 | |
| 3608 | • ‘t’ If the corresponding file-visiting buffer exits, then use |
| 3609 | ‘tab-width’'s value from that buffer. Doing this is cheap, so |
| 3610 | this value is used even if a corresponding cache entry exists. |
| 3611 | |
| 3612 | • ‘always’ If there is no such buffer, then temporarily visit |
| 3613 | the file to determine the value. |
| 3614 | |
| 3615 | • NUMBER Like ‘always’, but don't visit files larger than NUMBER |
| 3616 | bytes. |
| 3617 | |
| 3618 | -- User Option: magit-diff-paint-whitespace |
| 3619 | Specify where to highlight whitespace errors. |
| 3620 | |
| 3621 | See ‘magit-diff-highlight-trailing’, |
| 3622 | ‘magit-diff-highlight-indentation’. The symbol ‘t’ means in all |
| 3623 | diffs, ‘status’ means only in the status buffer, and ‘nil’ means |
| 3624 | nowhere. |
| 3625 | |
| 3626 | • ‘nil’ Never highlight whitespace errors. |
| 3627 | • ‘t’ Highlight whitespace errors everywhere. |
| 3628 | • ‘uncommitted’ Only highlight whitespace errors in diffs |
| 3629 | showing uncommitted changes. For backward compatibility |
| 3630 | ‘status’ is treated as a synonym. |
| 3631 | |
| 3632 | -- User Option: magit-diff-paint-whitespace-lines |
| 3633 | Specify in what kind of lines to highlight whitespace errors. |
| 3634 | |
| 3635 | • ‘t’ Highlight only in added lines. |
| 3636 | • ‘both’ Highlight in added and removed lines. |
| 3637 | • ‘all’ Highlight in added, removed and context lines. |
| 3638 | |
| 3639 | -- User Option: magit-diff-highlight-trailing |
| 3640 | Whether to highlight whitespace at the end of a line in diffs. |
| 3641 | Used only when ‘magit-diff-paint-whitespace’ is non-‘nil’. |
| 3642 | |
| 3643 | -- User Option: magit-diff-highlight-indentation |
| 3644 | This option controls whether to highlight the indentation in case |
| 3645 | it used the "wrong" indentation style. Indentation is only |
| 3646 | highlighted if ‘magit-diff-paint-whitespace’ is also non-‘nil’. |
| 3647 | |
| 3648 | The value is an alist of the form ‘((REGEXP . INDENT)...)’. The |
| 3649 | path to the current repository is matched against each element in |
| 3650 | reverse order. Therefore if a REGEXP matches, then earlier |
| 3651 | elements are not tried. |
| 3652 | |
| 3653 | If the used INDENT is ‘tabs’, highlight indentation with tabs. If |
| 3654 | INDENT is an integer, highlight indentation with at least that many |
| 3655 | spaces. Otherwise, highlight neither. |
| 3656 | |
| 3657 | -- User Option: magit-diff-hide-trailing-cr-characters |
| 3658 | Whether to hide ^M characters at the end of a line in diffs. |
| 3659 | |
| 3660 | -- User Option: magit-diff-highlight-hunk-region-functions |
| 3661 | This option specifies the functions used to highlight the |
| 3662 | hunk-internal region. |
| 3663 | |
| 3664 | ‘magit-diff-highlight-hunk-region-dim-outside’ overlays the outside |
| 3665 | of the hunk internal selection with a face that causes the added |
| 3666 | and removed lines to have the same background color as context |
| 3667 | lines. This function should not be removed from the value of this |
| 3668 | option. |
| 3669 | |
| 3670 | ‘magit-diff-highlight-hunk-region-using-overlays’ and |
| 3671 | ‘magit-diff-highlight-hunk-region-using-underline’ emphasize the |
| 3672 | region by placing delimiting horizontal lines before and after it. |
| 3673 | Both of these functions have glitches which cannot be fixed due to |
| 3674 | limitations of Emacs' display engine. For more information see |
| 3675 | <https://github.com/magit/magit/issues/2758> ff. |
| 3676 | |
| 3677 | Instead of, or in addition to, using delimiting horizontal lines, |
| 3678 | to emphasize the boundaries, you may wish to emphasize the text |
| 3679 | itself, using ‘magit-diff-highlight-hunk-region-using-face’. |
| 3680 | |
| 3681 | In terminal frames it's not possible to draw lines as the overlay |
| 3682 | and underline variants normally do, so there they fall back to |
| 3683 | calling the face function instead. |
| 3684 | |
| 3685 | -- User Option: magit-diff-unmarked-lines-keep-foreground |
| 3686 | This option controls whether added and removed lines outside the |
| 3687 | hunk-internal region only lose their distinct background color or |
| 3688 | also the foreground color. Whether the outside of the region is |
| 3689 | dimmed at all depends on |
| 3690 | ‘magit-diff-highlight-hunk-region-functions’. |
| 3691 | |
| 3692 | -- User Option: magit-diff-extra-stat-arguments |
| 3693 | This option specifies additional arguments to be used alongside |
| 3694 | ‘--stat’. |
| 3695 | |
| 3696 | The value is a list of zero or more arguments or a function that |
| 3697 | takes no argument and returns such a list. These arguments are |
| 3698 | allowed here: ‘--stat-width’, ‘--stat-name-width’, |
| 3699 | ‘--stat-graph-width’ and ‘--compact-summary’. Also see *note |
| 3700 | (gitman)git-diff::. |
| 3701 | |
| 3702 | -- User Option: magit-format-file-function |
| 3703 | This function is used to format lines representing a file. It is |
| 3704 | used for file headings in diffs, in diffstats and for lists of |
| 3705 | files (such as the untracked files). Depending on the caller, it |
| 3706 | receives either three or five arguments; the signature has to be |
| 3707 | ‘(kind file face &optional status orig)’. KIND is one of ‘diff’, |
| 3708 | ‘module’, ‘stat’ and ‘list’. |
| 3709 | |
| 3710 | 5.4.4 Revision Buffer |
| 3711 | --------------------- |
| 3712 | |
| 3713 | -- User Option: magit-revision-insert-related-refs |
| 3714 | Whether to show related branches in revision buffers. |
| 3715 | |
| 3716 | • ‘nil’ Don't show any related branches. |
| 3717 | • ‘t’ Show related local branches. |
| 3718 | • ‘all’ Show related local and remote branches. |
| 3719 | • ‘mixed’ Show all containing branches and local merged |
| 3720 | branches. |
| 3721 | |
| 3722 | -- User Option: magit-revision-show-gravatars |
| 3723 | Whether to show gravatar images in revision buffers. |
| 3724 | |
| 3725 | If ‘nil’, then don't insert any gravatar images. If ‘t’, then |
| 3726 | insert both images. If ‘author’ or ‘committer’, then insert only |
| 3727 | the respective image. |
| 3728 | |
| 3729 | If you have customized the option ‘magit-revision-headers-format’ |
| 3730 | and want to insert the images then you might also have to specify |
| 3731 | where to do so. In that case the value has to be a cons-cell of |
| 3732 | two regular expressions. The car specifies where to insert the |
| 3733 | author's image. The top half of the image is inserted right after |
| 3734 | the matched text, the bottom half on the next line in the same |
| 3735 | column. The cdr specifies where to insert the committer's image, |
| 3736 | accordingly. Either the car or the cdr may be ‘nil’." |
| 3737 | |
| 3738 | -- User Option: magit-revision-use-hash-sections |
| 3739 | Whether to turn hashes inside the commit message into sections. |
| 3740 | |
| 3741 | If non-‘nil’, then hashes inside the commit message are turned into |
| 3742 | ‘commit’ sections. There is a trade off to be made between |
| 3743 | performance and reliability: |
| 3744 | |
| 3745 | • ‘slow’ calls git for every word to be absolutely sure. |
| 3746 | • ‘quick’ skips words less than seven characters long. |
| 3747 | • ‘quicker’ additionally skips words that don't contain a |
| 3748 | number. |
| 3749 | • ‘quickest’ uses all words that are at least seven characters |
| 3750 | long and which contain at least one number as well as at least |
| 3751 | one letter. |
| 3752 | |
| 3753 | If ‘nil’, then no hashes are turned into sections, but you can |
| 3754 | still visit the commit at point using "RET". |
| 3755 | |
| 3756 | The diffs shown in the revision buffer may be automatically |
| 3757 | restricted to a subset of the changed files. If the revision buffer is |
| 3758 | displayed from a log buffer, the revision buffer will share the same |
| 3759 | file restriction as that log buffer (also see the command |
| 3760 | ‘magit-diff-toggle-file-filter’). |
| 3761 | |
| 3762 | -- User Option: magit-revision-filter-files-on-follow |
| 3763 | Whether showing a commit from a log buffer honors the log's file |
| 3764 | filter when the log arguments include ‘--follow’. |
| 3765 | |
| 3766 | When this option is ‘nil’, displaying a commit from a log ignores |
| 3767 | the log's file filter if the log arguments include ‘--follow’. |
| 3768 | Doing so avoids showing an empty diff in revision buffers for |
| 3769 | commits before a rename event. In such cases, the ‘--patch’ |
| 3770 | argument of the log transient can be used to show the |
| 3771 | file-restricted diffs inline. |
| 3772 | |
| 3773 | Set this option to non-‘nil’ to keep the log's file restriction |
| 3774 | even if ‘--follow’ is present in the log arguments. |
| 3775 | |
| 3776 | If the revision buffer is not displayed from a log buffer, the file |
| 3777 | restriction is determined as usual (see *note Transient Arguments and |
| 3778 | Buffer Variables::). |
| 3779 | |
| 3780 | -- User Option: magit-revision-use-dedicated-buffers |
| 3781 | Whether ‘magit-show-commit’ uses a dedicated buffer for each |
| 3782 | revision. |
| 3783 | |
| 3784 | If this is ‘nil’, then each revision is initially displayed in the |
| 3785 | same per-repository buffer. You can then lock that buffer to the |
| 3786 | revision; if you later display another revision, the locked buffer |
| 3787 | continues to display the same revision as before and the new |
| 3788 | revision is displayed in another buffer. |
| 3789 | |
| 3790 | If this is ‘t’, then each revision is displayed in a dedicated |
| 3791 | buffer. A revision buffer is only reused (i.e., raised), if it |
| 3792 | already displays the requested revision. If you enable this, you |
| 3793 | will quickly accumulate revision buffers and will have to find a |
| 3794 | way to keep that under control. |
| 3795 | ‘magit-{blame,log,status}-maybe-update-revision-buffer’ also will |
| 3796 | stop working, if this is enabled. For these reasons it is |
| 3797 | recommended, that you do not enable this." |
| 3798 | |
| 3799 | |
| 3800 | File: magit.info, Node: Ediffing, Next: References Buffer, Prev: Diffing, Up: Inspecting |
| 3801 | |
| 3802 | 5.5 Ediffing |
| 3803 | ============ |
| 3804 | |
| 3805 | This section describes how to enter Ediff from Magit buffers. For |
| 3806 | information on how to use Ediff itself, see *note (ediff)Top::. |
| 3807 | |
| 3808 | ‘e’ (‘magit-ediff-dwim’) |
| 3809 | Compare, stage, or resolve using Ediff. |
| 3810 | |
| 3811 | This command tries to guess what file, and what commit or range the |
| 3812 | user wants to compare, stage, or resolve using Ediff. It might |
| 3813 | only be able to guess either the file, or range/commit, in which |
| 3814 | case the user is asked about the other. It might not always guess |
| 3815 | right, in which case the appropriate ‘magit-ediff-*’ command has to |
| 3816 | be used explicitly. If it cannot read the user's mind at all, then |
| 3817 | it asks the user for a command to run. |
| 3818 | |
| 3819 | ‘E’ (‘magit-ediff’) |
| 3820 | This transient prefix command binds the following suffix commands |
| 3821 | and displays them in a temporary buffer until a suffix is invoked. |
| 3822 | |
| 3823 | ‘E r’ (‘magit-ediff-compare’) |
| 3824 | Compare two revisions of a file using Ediff. |
| 3825 | |
| 3826 | If the region is active, use the revisions on the first and last |
| 3827 | line of the region. With a prefix argument, instead of diffing the |
| 3828 | revisions, choose a revision to view changes along, starting at the |
| 3829 | common ancestor of both revisions (i.e., use a "..." range). |
| 3830 | |
| 3831 | ‘E m’ (‘magit-ediff-resolve-rest’) |
| 3832 | This command allows you to resolve outstanding conflicts in the |
| 3833 | file at point using Ediff. If there is no file at point or if it |
| 3834 | doesn't have any unmerged changes, then this command prompts for a |
| 3835 | file. |
| 3836 | |
| 3837 | Provided that the value of ‘merge.conflictstyle’ is ‘diff3’, you |
| 3838 | can view the file's merge-base revision using ‘/’ in the Ediff |
| 3839 | control buffer. |
| 3840 | |
| 3841 | The A, B and Ancestor buffers are constructed from the conflict |
| 3842 | markers in the worktree file. Because you and/or Git may have |
| 3843 | already resolved some conflicts, that means that these buffers may |
| 3844 | not contain the actual versions from the respective blobs. |
| 3845 | |
| 3846 | ‘E M’ (‘magit-ediff-resolve-all’) |
| 3847 | This command allows you to resolve all conflicts in the file at |
| 3848 | point using Ediff. If there is no file at point or if it doesn't |
| 3849 | have any unmerged changes, then this command prompts for a file. |
| 3850 | |
| 3851 | Provided that the value of ‘merge.conflictstyle’ is ‘diff3’, you |
| 3852 | can view the file's merge-base revision using ‘/’ in the Ediff |
| 3853 | control buffer. |
| 3854 | |
| 3855 | First the file in the worktree is moved aside, appending the suffix |
| 3856 | ‘.ORIG’, so that you could later go back to that version. Then it |
| 3857 | is reconstructed from the two sides of the conflict and the |
| 3858 | merge-base, if available. |
| 3859 | |
| 3860 | It would be nice if the worktree file were just used as-is, but |
| 3861 | Ediff does not support that. This means that all conflicts, that |
| 3862 | Git has already resolved, are restored. On the other hand Ediff |
| 3863 | also tries to resolve conflicts, and in many cases Ediff and Git |
| 3864 | should produce similar results. |
| 3865 | |
| 3866 | However if you have already resolved some conflicts manually, then |
| 3867 | those changes are discarded (though you can recover them from the |
| 3868 | backup file). In such cases ‘magit-ediff-resolve-rest’ might be |
| 3869 | more suitable. |
| 3870 | |
| 3871 | The advantage that this command has over ‘magit-ediff-resolve-rest’ |
| 3872 | is that the A, B and Ancestor buffers correspond to blobs from the |
| 3873 | respective commits, allowing you to inspect a side in context and |
| 3874 | to use Magit commands in these buffers to do so. Blame and log |
| 3875 | commands are particularly useful here. |
| 3876 | |
| 3877 | ‘E t’ (‘magit-git-mergetool’) |
| 3878 | This command does not actually use Ediff. While it serves the same |
| 3879 | purpose as ‘magit-ediff-resolve-rest’, it uses ‘git mergetool |
| 3880 | --gui’ to resolve conflicts. |
| 3881 | |
| 3882 | With a prefix argument this acts as a transient prefix command, |
| 3883 | allowing the user to select the mergetool and change some settings. |
| 3884 | |
| 3885 | ‘E s’ (‘magit-ediff-stage’) |
| 3886 | Stage and unstage changes to a file using Ediff, defaulting to the |
| 3887 | file at point. |
| 3888 | |
| 3889 | ‘E u’ (‘magit-ediff-show-unstaged’) |
| 3890 | Show unstaged changes to a file using Ediff. |
| 3891 | |
| 3892 | ‘E i’ (‘magit-ediff-show-staged’) |
| 3893 | Show staged changes to a file using Ediff. |
| 3894 | |
| 3895 | ‘E w’ (‘magit-ediff-show-working-tree’) |
| 3896 | Show changes in a file between ‘HEAD’ and working tree using Ediff. |
| 3897 | |
| 3898 | ‘E c’ (‘magit-ediff-show-commit’) |
| 3899 | Show changes to a file introduced by a commit using Ediff. |
| 3900 | |
| 3901 | ‘E z’ (‘magit-ediff-show-stash’) |
| 3902 | Show changes to a file introduced by a stash using Ediff. |
| 3903 | |
| 3904 | -- User Option: magit-ediff-dwim-resolve-function |
| 3905 | This option controls which function ‘magit-ediff-dwim’ uses to |
| 3906 | resolve conflicts. One of ‘magit-ediff-resolve-rest’, |
| 3907 | ‘magit-ediff-resolve-all’ or ‘magit-git-mergetool’; which are all |
| 3908 | discussed above. |
| 3909 | |
| 3910 | -- User Option: magit-ediff-dwim-show-on-hunks |
| 3911 | This option controls what command ‘magit-ediff-dwim’ calls when |
| 3912 | point is on uncommitted hunks. When ‘nil’, always run |
| 3913 | ‘magit-ediff-stage’. Otherwise, use ‘magit-ediff-show-staged’ and |
| 3914 | ‘magit-ediff-show-unstaged’ to show staged and unstaged changes, |
| 3915 | respectively. |
| 3916 | |
| 3917 | -- User Option: magit-ediff-show-stash-with-index |
| 3918 | This option controls whether ‘magit-ediff-show-stash’ includes a |
| 3919 | buffer containing the file's state in the index at the time the |
| 3920 | stash was created. This makes it possible to tell which changes in |
| 3921 | the stash were staged. |
| 3922 | |
| 3923 | -- User Option: magit-ediff-quit-hook |
| 3924 | This hook is run after quitting an Ediff session that was created |
| 3925 | using a Magit command. The hook functions are run inside the Ediff |
| 3926 | control buffer, and should not change the current buffer. |
| 3927 | |
| 3928 | This is similar to ‘ediff-quit-hook’ but takes the needs of Magit |
| 3929 | into account. The regular ‘ediff-quit-hook’ is ignored by Ediff |
| 3930 | sessions that were created using a Magit command. |
| 3931 | |
| 3932 | |
| 3933 | File: magit.info, Node: References Buffer, Next: Bisecting, Prev: Ediffing, Up: Inspecting |
| 3934 | |
| 3935 | 5.6 References Buffer |
| 3936 | ===================== |
| 3937 | |
| 3938 | ‘y’ (‘magit-show-refs’) |
| 3939 | This command lists branches and tags in a dedicated buffer. |
| 3940 | |
| 3941 | However if this command is invoked again from this buffer or if it |
| 3942 | is invoked with a prefix argument, then it acts as a transient |
| 3943 | prefix command, which binds the following suffix commands and some |
| 3944 | infix arguments. |
| 3945 | |
| 3946 | All of the following suffix commands list exactly the same branches |
| 3947 | and tags. The only difference the optional feature that can be enabled |
| 3948 | by changing the value of ‘magit-refs-show-commit-count’ (see below). |
| 3949 | These commands specify a different branch or commit against which all |
| 3950 | the other references are compared. |
| 3951 | |
| 3952 | ‘y y’ (‘magit-show-refs-head’) |
| 3953 | This command lists branches and tags in a dedicated buffer. Each |
| 3954 | reference is being compared with ‘HEAD’. |
| 3955 | |
| 3956 | ‘y c’ (‘magit-show-refs-current’) |
| 3957 | This command lists branches and tags in a dedicated buffer. Each |
| 3958 | reference is being compared with the current branch or ‘HEAD’ if it |
| 3959 | is detached. |
| 3960 | |
| 3961 | ‘y o’ (‘magit-show-refs-other’) |
| 3962 | This command lists branches and tags in a dedicated buffer. Each |
| 3963 | reference is being compared with a branch read from the user. |
| 3964 | |
| 3965 | ‘y r’ (‘magit-refs-set-show-commit-count’) |
| 3966 | This command changes for which refs the commit count is shown. |
| 3967 | |
| 3968 | -- User Option: magit-refs-show-commit-count |
| 3969 | Whether to show commit counts in Magit-Refs mode buffers. |
| 3970 | |
| 3971 | • ‘all’ Show counts for branches and tags. |
| 3972 | • ‘branch’ Show counts for branches only. |
| 3973 | • ‘nil’ Never show counts. |
| 3974 | |
| 3975 | The default is ‘nil’ because anything else can be very expensive. |
| 3976 | |
| 3977 | -- User Option: magit-refs-pad-commit-counts |
| 3978 | Whether to pad all commit counts on all sides in Magit-Refs mode |
| 3979 | buffers. |
| 3980 | |
| 3981 | If this is ‘nil’, then some commit counts are displayed right next |
| 3982 | to one of the branches that appear next to the count, without any |
| 3983 | space in between. This might look bad if the branch name faces |
| 3984 | look too similar to ‘magit-dimmed’. |
| 3985 | |
| 3986 | If this is non-‘nil’, then spaces are placed on both sides of all |
| 3987 | commit counts. |
| 3988 | |
| 3989 | -- User Option: magit-refs-show-remote-prefix |
| 3990 | Whether to show the remote prefix in lists of remote branches. |
| 3991 | |
| 3992 | Showing the prefix is redundant because the name of the remote is |
| 3993 | already shown in the heading preceding the list of its branches. |
| 3994 | |
| 3995 | -- User Option: magit-refs-primary-column-width |
| 3996 | Width of the primary column in 'magit-refs-mode' buffers. The |
| 3997 | primary column is the column that contains the name of the branch |
| 3998 | that the current row is about. |
| 3999 | |
| 4000 | If this is an integer, then the column is that many columns wide. |
| 4001 | Otherwise it has to be a cons-cell of two integers. The first |
| 4002 | specifies the minimal width, the second the maximal width. In that |
| 4003 | case the actual width is determined using the length of the names |
| 4004 | of the shown local branches. (Remote branches and tags are not |
| 4005 | taken into account when calculating to optimal width.) |
| 4006 | |
| 4007 | -- User Option: magit-refs-focus-column-width |
| 4008 | Width of the focus column in 'magit-refs-mode' buffers. |
| 4009 | |
| 4010 | The focus column is the first column, which marks one branch |
| 4011 | (usually the current branch) as the focused branch using ‘*’ or |
| 4012 | ‘@’. For each other reference, this column optionally shows how |
| 4013 | many commits it is ahead of the focused branch and ‘<’, or if it |
| 4014 | isn't ahead then the commits it is behind and ‘>’, or if it isn't |
| 4015 | behind either, then a ‘=’. |
| 4016 | |
| 4017 | This column may also display only ‘*’ or ‘@’ for the focused |
| 4018 | branch, in which case this option is ignored. Use ‘L v’ to change |
| 4019 | the verbosity of this column. |
| 4020 | |
| 4021 | -- User Option: magit-refs-margin |
| 4022 | This option specifies whether the margin is initially shown in |
| 4023 | Magit-Refs mode buffers and how it is formatted. |
| 4024 | |
| 4025 | The value has the form ‘(INIT STYLE WIDTH AUTHOR AUTHOR-WIDTH)’. |
| 4026 | |
| 4027 | • If INIT is non-‘nil’, then the margin is shown initially. |
| 4028 | • STYLE controls how to format the author or committer date. It |
| 4029 | can be one of ‘age’ (to show the age of the commit), |
| 4030 | ‘age-abbreviated’ (to abbreviate the time unit to a |
| 4031 | character), or a string (suitable for ‘format-time-string’) to |
| 4032 | show the actual date. Option |
| 4033 | ‘magit-log-margin-show-committer-date’ controls which date is |
| 4034 | being displayed. |
| 4035 | • WIDTH controls the width of the margin. This exists for |
| 4036 | forward compatibility and currently the value should not be |
| 4037 | changed. |
| 4038 | • AUTHOR controls whether the name of the author is also shown |
| 4039 | by default. |
| 4040 | • AUTHOR-WIDTH has to be an integer. When the name of the |
| 4041 | author is shown, then this specifies how much space is used to |
| 4042 | do so. |
| 4043 | |
| 4044 | -- User Option: magit-refs-margin-for-tags |
| 4045 | This option specifies whether to show information about tags in the |
| 4046 | margin. This is disabled by default because it is slow if there |
| 4047 | are many tags. |
| 4048 | |
| 4049 | The following variables control how individual refs are displayed. |
| 4050 | If you change one of these variables (especially the "%c" part), then |
| 4051 | you should also change the others to keep things aligned. The following |
| 4052 | %-sequences are supported: |
| 4053 | |
| 4054 | • ‘%a’ Number of commits this ref has over the one we compare to. |
| 4055 | • ‘%b’ Number of commits the ref we compare to has over this one. |
| 4056 | • ‘%c’ Number of commits this ref has over the one we compare to. |
| 4057 | For the ref which all other refs are compared this is instead "@", |
| 4058 | if it is the current branch, or "#" otherwise. |
| 4059 | • ‘%C’ For the ref which all other refs are compared this is "@", if |
| 4060 | it is the current branch, or "#" otherwise. For all other refs " |
| 4061 | ". |
| 4062 | • ‘%h’ Hash of this ref's tip. |
| 4063 | • ‘%m’ Commit summary of the tip of this ref. |
| 4064 | • ‘%n’ Name of this ref. |
| 4065 | • ‘%u’ Upstream of this local branch. |
| 4066 | • ‘%U’ Upstream of this local branch and additional local vs. |
| 4067 | upstream information. |
| 4068 | |
| 4069 | -- User Option: magit-refs-filter-alist |
| 4070 | The purpose of this option is to forgo displaying certain refs |
| 4071 | based on their name. If you want to not display any refs of a |
| 4072 | certain type, then you should remove the appropriate function from |
| 4073 | ‘magit-refs-sections-hook’ instead. |
| 4074 | |
| 4075 | This alist controls which tags and branches are omitted from being |
| 4076 | displayed in ‘magit-refs-mode’ buffers. If it is ‘nil’, then all |
| 4077 | refs are displayed (subject to ‘magit-refs-sections-hook’). |
| 4078 | |
| 4079 | All keys are tried in order until one matches. Then its value is |
| 4080 | used and subsequent elements are ignored. If the value is |
| 4081 | non-‘nil’, then the reference is displayed, otherwise it is not. |
| 4082 | If no element matches, then the reference is displayed. |
| 4083 | |
| 4084 | A key can either be a regular expression that the refname has to |
| 4085 | match, or a function that takes the refname as only argument and |
| 4086 | returns a boolean. A remote branch such as "origin/master" is |
| 4087 | displayed as just "master", however for this comparison the former |
| 4088 | is used. |
| 4089 | |
| 4090 | ‘<RET>’ (‘magit-visit-ref’) |
| 4091 | This command visits the reference or revision at point in another |
| 4092 | buffer. If there is no revision at point or with a prefix argument |
| 4093 | then it prompts for a revision. |
| 4094 | |
| 4095 | This command behaves just like ‘magit-show-commit’ as described |
| 4096 | above, except if point is on a reference in a ‘magit-refs-mode’ |
| 4097 | buffer, in which case the behavior may be different, but only if |
| 4098 | you have customized the option ‘magit-visit-ref-behavior’. |
| 4099 | |
| 4100 | -- User Option: magit-visit-ref-behavior |
| 4101 | This option controls how ‘magit-visit-ref’ behaves in |
| 4102 | ‘magit-refs-mode’ buffers. |
| 4103 | |
| 4104 | By default ‘magit-visit-ref’ behaves like ‘magit-show-commit’, in |
| 4105 | all buffers, including ‘magit-refs-mode’ buffers. When the type of |
| 4106 | the section at point is ‘commit’ then "RET" is bound to |
| 4107 | ‘magit-show-commit’, and when the type is either ‘branch’ or ‘tag’ |
| 4108 | then it is bound to ‘magit-visit-ref’. |
| 4109 | |
| 4110 | "RET" is one of Magit's most essential keys and at least by default |
| 4111 | it should behave consistently across all of Magit, especially |
| 4112 | because users quickly learn that it does something very harmless; |
| 4113 | it shows more information about the thing at point in another |
| 4114 | buffer. |
| 4115 | |
| 4116 | However "RET" used to behave differently in ‘magit-refs-mode’ |
| 4117 | buffers, doing surprising things, some of which cannot really be |
| 4118 | described as "visit this thing". If you've grown accustomed this |
| 4119 | behavior, you can restore it by adding one or more of the below |
| 4120 | symbols to the value of this option. But keep in mind that by |
| 4121 | doing so you don't only introduce inconsistencies, you also lose |
| 4122 | some functionality and might have to resort to ‘M-x |
| 4123 | magit-show-commit’ to get it back. |
| 4124 | |
| 4125 | ‘magit-visit-ref’ looks for these symbols in the order in which |
| 4126 | they are described here. If the presence of a symbol applies to |
| 4127 | the current situation, then the symbols that follow do not affect |
| 4128 | the outcome. |
| 4129 | |
| 4130 | • ‘focus-on-ref’ |
| 4131 | |
| 4132 | With a prefix argument update the buffer to show commit counts |
| 4133 | and lists of cherry commits relative to the reference at point |
| 4134 | instead of relative to the current buffer or ‘HEAD’. |
| 4135 | |
| 4136 | Instead of adding this symbol, consider pressing "C-u y o |
| 4137 | RET". |
| 4138 | |
| 4139 | • ‘create-branch’ |
| 4140 | |
| 4141 | If point is on a remote branch, then create a new local branch |
| 4142 | with the same name, use the remote branch as its upstream, and |
| 4143 | then check out the local branch. |
| 4144 | |
| 4145 | Instead of adding this symbol, consider pressing "b c RET |
| 4146 | RET", like you would do in other buffers. |
| 4147 | |
| 4148 | • ‘checkout-any’ |
| 4149 | |
| 4150 | Check out the reference at point. If that reference is a tag |
| 4151 | or a remote branch, then this results in a detached ‘HEAD’. |
| 4152 | |
| 4153 | Instead of adding this symbol, consider pressing "b b RET", |
| 4154 | like you would do in other buffers. |
| 4155 | |
| 4156 | • ‘checkout-branch’ |
| 4157 | |
| 4158 | Check out the local branch at point. |
| 4159 | |
| 4160 | Instead of adding this symbol, consider pressing "b b RET", |
| 4161 | like you would do in other buffers. |
| 4162 | |
| 4163 | 5.6.1 References Sections |
| 4164 | ------------------------- |
| 4165 | |
| 4166 | The contents of references buffers is controlled using the hook |
| 4167 | ‘magit-refs-sections-hook’. See *note Section Hooks:: to learn about |
| 4168 | such hooks and how to customize them. All of the below functions are |
| 4169 | members of the default value. Note that it makes much less sense to |
| 4170 | customize this hook than it does for the respective hook used for the |
| 4171 | status buffer. |
| 4172 | |
| 4173 | -- User Option: magit-refs-sections-hook |
| 4174 | Hook run to insert sections into a references buffer. |
| 4175 | |
| 4176 | -- Function: magit-insert-local-branches |
| 4177 | Insert sections showing all local branches. |
| 4178 | |
| 4179 | -- Function: magit-insert-remote-branches |
| 4180 | Insert sections showing all remote-tracking branches. |
| 4181 | |
| 4182 | -- Function: magit-insert-tags |
| 4183 | Insert sections showing all tags. |
| 4184 | |
| 4185 | |
| 4186 | File: magit.info, Node: Bisecting, Next: Visiting Files and Blobs, Prev: References Buffer, Up: Inspecting |
| 4187 | |
| 4188 | 5.7 Bisecting |
| 4189 | ============= |
| 4190 | |
| 4191 | Also see *note (gitman)git-bisect::. |
| 4192 | |
| 4193 | ‘B’ (‘magit-bisect’) |
| 4194 | This transient prefix command binds the following suffix commands |
| 4195 | and displays them in a temporary buffer until a suffix is invoked. |
| 4196 | |
| 4197 | When bisecting is not in progress, then the transient features the |
| 4198 | following suffix commands. |
| 4199 | |
| 4200 | ‘B B’ (‘magit-bisect-start’) |
| 4201 | Start a bisect session. |
| 4202 | |
| 4203 | Bisecting a bug means to find the commit that introduced it. |
| 4204 | |
| 4205 | This command starts such a bisect session by asking for a known |
| 4206 | good commit and a known bad commit. If the region marks a range of |
| 4207 | commit, where one is an ancestor of the other, then these commits |
| 4208 | are used as the good and bad commits. Otherwise these starting |
| 4209 | points are read in the minibuffer. |
| 4210 | |
| 4211 | If you're bisecting a change that isn't a regression, you can |
| 4212 | select alternate terms that are conceptually more fitting than |
| 4213 | "bad" and "good", but the infix arguments to do so are disabled by |
| 4214 | default. |
| 4215 | |
| 4216 | ‘B s’ (‘magit-bisect-run’) |
| 4217 | Bisect automatically by running commands after each step. |
| 4218 | |
| 4219 | When bisecting in progress, then the transient instead features the |
| 4220 | following suffix commands. |
| 4221 | |
| 4222 | ‘B b’ (‘magit-bisect-bad’) |
| 4223 | Mark the current commit as bad. Use this after you have asserted |
| 4224 | that the commit does contain the bug in question. |
| 4225 | |
| 4226 | ‘B g’ (‘magit-bisect-good’) |
| 4227 | Mark the current commit as good. Use this after you have asserted |
| 4228 | that the commit does not contain the bug in question. |
| 4229 | |
| 4230 | ‘B m’ (‘magit-bisect-mark’) |
| 4231 | Mark the current commit with one of the bisect terms. This command |
| 4232 | provides an alternative to ‘magit-bisect-bad’ and |
| 4233 | ‘magit-bisect-good’ and is useful when using terms other than "bad" |
| 4234 | and "good". This suffix is disabled by default. |
| 4235 | |
| 4236 | ‘B k’ (‘magit-bisect-skip’) |
| 4237 | Skip the current commit. Use this if for some reason the current |
| 4238 | commit is not a good one to test. This command lets Git choose a |
| 4239 | different one. |
| 4240 | |
| 4241 | ‘B r’ (‘magit-bisect-reset’) |
| 4242 | After bisecting, cleanup bisection state and return to original |
| 4243 | ‘HEAD’. |
| 4244 | |
| 4245 | By default the status buffer shows information about the ongoing |
| 4246 | bisect session. |
| 4247 | |
| 4248 | -- User Option: magit-bisect-show-graph |
| 4249 | This option controls whether a graph is displayed for the log of |
| 4250 | commits that still have to be bisected. |
| 4251 | |
| 4252 | |
| 4253 | File: magit.info, Node: Visiting Files and Blobs, Next: Blaming, Prev: Bisecting, Up: Inspecting |
| 4254 | |
| 4255 | 5.8 Visiting Files and Blobs |
| 4256 | ============================ |
| 4257 | |
| 4258 | Magit provides several commands that visit a file or blob (the version |
| 4259 | of a file that is stored in a certain commit). Actually it provides |
| 4260 | several *groups* of such commands and the several *variants* within each |
| 4261 | group. |
| 4262 | |
| 4263 | Also see *note Commands for Buffers Visiting Files::. |
| 4264 | |
| 4265 | 5.8.1 General-Purpose Visit Commands |
| 4266 | ------------------------------------ |
| 4267 | |
| 4268 | These commands can be used anywhere to open any blob. Currently no keys |
| 4269 | are bound to these commands by default, but that is likely to change. |
| 4270 | |
| 4271 | -- Command: magit-find-file |
| 4272 | This command reads a filename and revision from the user and visits |
| 4273 | the respective blob in a buffer. The buffer is displayed in the |
| 4274 | selected window. |
| 4275 | |
| 4276 | -- Command: magit-find-file-other-window |
| 4277 | This command reads a filename and revision from the user and visits |
| 4278 | the respective blob in a buffer. The buffer is displayed in |
| 4279 | another window. |
| 4280 | |
| 4281 | -- Command: magit-find-file-other-frame |
| 4282 | This command reads a filename and revision from the user and visits |
| 4283 | the respective blob in a buffer. The buffer is displayed in |
| 4284 | another frame. |
| 4285 | |
| 4286 | 5.8.2 Visiting Files and Blobs from a Diff |
| 4287 | ------------------------------------------ |
| 4288 | |
| 4289 | These commands can only be used when point is inside a diff. Elsewhere |
| 4290 | use ‘magit-find-file’. |
| 4291 | |
| 4292 | ‘<RET>’ (‘magit-diff-visit-file’) |
| 4293 | This command visits the appropriate version of the file at point. |
| 4294 | |
| 4295 | Display the buffer in the selected window. With a prefix argument, |
| 4296 | OTHER-WINDOW, instead display the buffer in another window. |
| 4297 | |
| 4298 | In the visited file or blob, go to the location corresponding to |
| 4299 | the location in the diff. |
| 4300 | |
| 4301 | If point is on an added or context line, visit the blob |
| 4302 | corresponding to our side (i.e., the new/right side). If point is |
| 4303 | on a removed line, visit the blob corresponding to their side |
| 4304 | (i.e., the old/left side). |
| 4305 | |
| 4306 | This applies to diffs of staged and unstaged changes as well. For |
| 4307 | staged changes the two sides are blobs from the index and the |
| 4308 | 'HEAD' commit. For unstaged changes the two sides are the actual |
| 4309 | file in the worktree and the blob from the index. |
| 4310 | |
| 4311 | To visit the file in the worktree, regardless of what the current |
| 4312 | diff is about, use ‘magit-diff-visit-worktree-file’, described |
| 4313 | next. |
| 4314 | |
| 4315 | ‘C-<return>’ (‘magit-diff-visit-worktree-file’) |
| 4316 | This command visits the worktree version of the appropriate file. |
| 4317 | The location of point inside the diff determines which file is |
| 4318 | being visited. Unlike ‘magit-diff-visit-file’ it always visits the |
| 4319 | "real" file in the working tree, i.e., the "current version" of the |
| 4320 | file. |
| 4321 | |
| 4322 | In the file-visiting buffer this command goes to the line that |
| 4323 | corresponds to the line that point is on in the diff. Lines that |
| 4324 | were added or removed in the working tree, the index and other |
| 4325 | commits in between are automatically accounted for. |
| 4326 | |
| 4327 | The buffer is displayed in the selected window. With a prefix |
| 4328 | argument the buffer is displayed in another window instead. |
| 4329 | |
| 4330 | Variants of the above two commands exist that instead visit the file |
| 4331 | in another window or in another frame. If you prefer such behavior, |
| 4332 | then you may want to change the above key bindings, but note that the |
| 4333 | above commands also use another window when invoked with a prefix |
| 4334 | argument. |
| 4335 | |
| 4336 | -- Command: magit-diff-visit-file-other-window |
| 4337 | -- Command: magit-diff-visit-file-other-frame |
| 4338 | -- Command: magit-diff-visit-worktree-file-other-window |
| 4339 | -- Command: magit-diff-visit-worktree-file-other-frame |
| 4340 | These commands behave like the respective commands described above, |
| 4341 | except that they display the blob or file in another window or |
| 4342 | frame. |
| 4343 | |
| 4344 | -- User Option: magit-diff-visit-prefer-worktree |
| 4345 | This option controls whether ‘magit-diff-visit-file’ always visits |
| 4346 | the respective file in the worktree, when invoked anywhere from |
| 4347 | within a hunk of staged or unstaged changes. |
| 4348 | |
| 4349 | By default ‘magit-diff-visit-file’ does not do that. Instead it |
| 4350 | behaves for staged and unstaged changes as it does for committed |
| 4351 | changes, by visiting a blob from the old/left or new/right side, |
| 4352 | depending on whether point is on a removed line or not. |
| 4353 | |
| 4354 | For staged changes the old side is the blob from HEAD and the right |
| 4355 | side is the blog from the index. For unstaged changes the left |
| 4356 | side is the blob from the index (if there are any changes in the |
| 4357 | index for that file, else the blob from HEAD), and the right side |
| 4358 | is the file in the worktree. |
| 4359 | |
| 4360 | Being able to jump to HEAD or the index from a removed line is very |
| 4361 | useful, because it allows you to, e.g., use blame to investigate |
| 4362 | why some line, which you have already removed, was added in the |
| 4363 | first place. |
| 4364 | |
| 4365 | But if you want to make further changes to already staged changes, |
| 4366 | you of course instead need to go to the respective file in the |
| 4367 | worktree. The command ‘magit-diff-visit-worktree-file’ was created |
| 4368 | for that purpose, and it is strongly recommend that you make use of |
| 4369 | that command, even if you initially find it inconvenient having to |
| 4370 | remember to use ‘C-<return>’ instead of ‘RET’ in this case. |
| 4371 | |
| 4372 | While discouraged, you can alternatively set this option to ‘t’, |
| 4373 | which causes ‘magit-diff-visit-file’ itself to go to the file in |
| 4374 | the worktree, even when invoked from within a hunk of staged |
| 4375 | changes. If you do that, you lose the ability to instantly go to |
| 4376 | lines you have already removed. |
| 4377 | |
| 4378 | -- User Option: magit-diff-visit-previous-blob |
| 4379 | This option controls whether ‘magit-diff-visit-file’ visits the |
| 4380 | previous blob when invoked with point on a removed line. |
| 4381 | |
| 4382 | When this is ‘t’ (the default) and point is on a removed line, then |
| 4383 | ‘magit-diff-visit-file’ visits the blob from the old/left commit, |
| 4384 | which still has that line, instead of going to the new/right blob, |
| 4385 | which removes that line. |
| 4386 | |
| 4387 | Setting this to ‘nil’, causes ‘magit-diff-visit-file’ to always go |
| 4388 | to the new/right blob, even when point is on a removed line. This |
| 4389 | is very strongly discouraged. Instead place the cursor anywhere |
| 4390 | else within the hunk but on a removed line, if you want to visit |
| 4391 | the new side. That way you don't lose the ability to visit the old |
| 4392 | side. |
| 4393 | |
| 4394 | |
| 4395 | File: magit.info, Node: Blaming, Prev: Visiting Files and Blobs, Up: Inspecting |
| 4396 | |
| 4397 | 5.9 Blaming |
| 4398 | =========== |
| 4399 | |
| 4400 | Also see *note (gitman)git-blame::. |
| 4401 | |
| 4402 | To start blaming, invoke the ‘magit-file-dispatch’ transient prefix |
| 4403 | command. When using the default key bindings, that can be done by |
| 4404 | pressing ‘C-c M-g’. When using the recommended bindings, this command |
| 4405 | is instead bound to ‘C-c f’. Also see *note Global Bindings::. |
| 4406 | |
| 4407 | The blaming suffix commands can be invoked directly from the file |
| 4408 | dispatch transient. However if you want to set an infix argument, then |
| 4409 | you have to enter the blaming sub-prefix first. |
| 4410 | |
| 4411 | ‘C-c f B’ (‘magit-blame’) |
| 4412 | ‘C-c f b’ (‘magit-blame-addition’) |
| 4413 | ‘C-c f B b’ |
| 4414 | ‘C-c f r’ (‘magit-blame-removal’) |
| 4415 | ‘C-c f B r’ |
| 4416 | ‘C-c f f’ (‘magit-blame-reverse’) |
| 4417 | ‘C-c f B f’ |
| 4418 | ‘C-c f e’ (‘magit-blame-echo’) |
| 4419 | ‘C-c f B e’ |
| 4420 | ‘C-c f q’ (‘magit-blame-quit’) |
| 4421 | ‘C-c f B q’ |
| 4422 | Each of these commands is documented individually right below, |
| 4423 | alongside their default key bindings. The bindings shown above are |
| 4424 | the recommended bindings, which you can enable by following the |
| 4425 | instructions in *note Global Bindings::. |
| 4426 | |
| 4427 | ‘C-c M-g B’ (‘magit-blame’) |
| 4428 | This transient prefix command binds the following suffix commands |
| 4429 | along with the appropriate infix arguments and displays them in a |
| 4430 | temporary buffer until a suffix is invoked. |
| 4431 | |
| 4432 | Note that not all of the following suffixes are available at all |
| 4433 | times. For example if ‘magit-blame-mode’ is not enabled, then the |
| 4434 | command whose purpose is to turn off that mode would not be of any use |
| 4435 | and therefore isn't available. |
| 4436 | |
| 4437 | ‘C-c M-g b’ (‘magit-blame-addition’) |
| 4438 | ‘C-c M-g B b’ |
| 4439 | This command augments each line or chunk of lines in the current |
| 4440 | file-visiting or blob-visiting buffer with information about what |
| 4441 | commits last touched these lines. |
| 4442 | |
| 4443 | If the buffer visits a revision of that file, then history up to |
| 4444 | that revision is considered. Otherwise, the file's full history is |
| 4445 | considered, including uncommitted changes. |
| 4446 | |
| 4447 | If Magit-Blame mode is already turned on in the current buffer then |
| 4448 | blaming is done recursively, by visiting REVISION:FILE (using |
| 4449 | ‘magit-find-file’), where REVISION is a parent of the revision that |
| 4450 | added the current line or chunk of lines. |
| 4451 | |
| 4452 | ‘C-c M-g r’ (‘magit-blame-removal’) |
| 4453 | ‘C-c M-g B r’ |
| 4454 | This command augments each line or chunk of lines in the current |
| 4455 | blob-visiting buffer with information about the revision that |
| 4456 | removes it. It cannot be used in file-visiting buffers. |
| 4457 | |
| 4458 | Like ‘magit-blame-addition’, this command can be used recursively. |
| 4459 | |
| 4460 | ‘C-c M-g f’ (‘magit-blame-reverse’) |
| 4461 | ‘C-c M-g B f’ |
| 4462 | This command augments each line or chunk of lines in the current |
| 4463 | file-visiting or blob-visiting buffer with information about the |
| 4464 | last revision in which a line still existed. |
| 4465 | |
| 4466 | Like ‘magit-blame-addition’, this command can be used recursively. |
| 4467 | |
| 4468 | ‘C-c M-g e’ (‘magit-blame-echo’) |
| 4469 | ‘C-c M-g B e’ |
| 4470 | This command is like ‘magit-blame-addition’ except that it doesn't |
| 4471 | turn on ‘read-only-mode’ and that it initially uses the |
| 4472 | visualization style specified by option ‘magit-blame-echo-style’. |
| 4473 | |
| 4474 | The following key bindings are available when Magit-Blame mode is |
| 4475 | enabled and Read-Only mode is not enabled. These commands are also |
| 4476 | available in other buffers; here only the behavior is described that is |
| 4477 | relevant in file-visiting buffers that are being blamed. |
| 4478 | |
| 4479 | ‘C-c M-g q’ (‘magit-blame-quit’) |
| 4480 | ‘C-c M-g B q’ |
| 4481 | This command turns off Magit-Blame mode. If the buffer was created |
| 4482 | during a recursive blame, then it also kills the buffer. |
| 4483 | |
| 4484 | ‘<RET>’ (‘magit-show-commit’) |
| 4485 | This command shows the commit that last touched the line at point. |
| 4486 | |
| 4487 | ‘<SPC>’ (‘magit-diff-show-or-scroll-up’) |
| 4488 | This command updates the commit buffer. |
| 4489 | |
| 4490 | This either shows the commit that last touched the line at point in |
| 4491 | the appropriate buffer, or if that buffer is already being |
| 4492 | displayed in the current frame and if that buffer contains |
| 4493 | information about that commit, then the buffer is scrolled up |
| 4494 | instead. |
| 4495 | |
| 4496 | ‘<DEL>’ (‘magit-diff-show-or-scroll-down’) |
| 4497 | This command updates the commit buffer. |
| 4498 | |
| 4499 | This either shows the commit that last touched the line at point in |
| 4500 | the appropriate buffer, or if that buffer is already being |
| 4501 | displayed in the current frame and if that buffer contains |
| 4502 | information about that commit, then the buffer is scrolled down |
| 4503 | instead. |
| 4504 | |
| 4505 | The following key bindings are available when both Magit-Blame mode |
| 4506 | and Read-Only mode are enabled. |
| 4507 | |
| 4508 | ‘b’ (‘magit-blame’) |
| 4509 | See above. |
| 4510 | |
| 4511 | ‘n’ (‘magit-blame-next-chunk’) |
| 4512 | This command moves to the next chunk. |
| 4513 | |
| 4514 | ‘N’ (‘magit-blame-next-chunk-same-commit’) |
| 4515 | This command moves to the next chunk from the same commit. |
| 4516 | |
| 4517 | ‘p’ (‘magit-blame-previous-chunk’) |
| 4518 | This command moves to the previous chunk. |
| 4519 | |
| 4520 | ‘P’ (‘magit-blame-previous-chunk-same-commit’) |
| 4521 | This command moves to the previous chunk from the same commit. |
| 4522 | |
| 4523 | ‘q’ (‘magit-blame-quit’) |
| 4524 | This command turns off Magit-Blame mode. If the buffer was created |
| 4525 | during a recursive blame, then it also kills the buffer. |
| 4526 | |
| 4527 | ‘M-w’ (‘magit-blame-copy-hash’) |
| 4528 | This command saves the hash of the current chunk's commit to the |
| 4529 | kill ring. |
| 4530 | |
| 4531 | When the region is active, the command saves the region's content |
| 4532 | instead of the hash, like ‘kill-ring-save’ would. |
| 4533 | |
| 4534 | ‘c’ (‘magit-blame-cycle-style’) |
| 4535 | This command changes how blame information is visualized in the |
| 4536 | current buffer by cycling through the styles specified using the |
| 4537 | option ‘magit-blame-styles’. |
| 4538 | |
| 4539 | Blaming is also controlled using the following options. |
| 4540 | |
| 4541 | -- User Option: magit-blame-styles |
| 4542 | This option defines a list of styles used to visualize blame |
| 4543 | information. For now see its doc-string to learn more. |
| 4544 | |
| 4545 | -- User Option: magit-blame-echo-style |
| 4546 | This option specifies the blame visualization style used by the |
| 4547 | command ‘magit-blame-echo’. This must be a symbol that is used as |
| 4548 | the identifier for one of the styles defined in |
| 4549 | ‘magit-blame-styles’. |
| 4550 | |
| 4551 | -- User Option: magit-blame-time-format |
| 4552 | This option specifies the format string used to display times when |
| 4553 | showing blame information. |
| 4554 | |
| 4555 | -- User Option: magit-blame-read-only |
| 4556 | This option controls whether blaming a buffer also makes |
| 4557 | temporarily read-only. |
| 4558 | |
| 4559 | -- User Option: magit-blame-disable-modes |
| 4560 | This option lists incompatible minor-modes that should be disabled |
| 4561 | temporarily when a buffer contains blame information. They are |
| 4562 | enabled again when the buffer no longer shows blame information. |
| 4563 | |
| 4564 | -- User Option: magit-blame-goto-chunk-hook |
| 4565 | This hook is run when moving between chunks. |
| 4566 | |
| 4567 | |
| 4568 | File: magit.info, Node: Manipulating, Next: Transferring, Prev: Inspecting, Up: Top |
| 4569 | |
| 4570 | 6 Manipulating |
| 4571 | ************** |
| 4572 | |
| 4573 | * Menu: |
| 4574 | |
| 4575 | * Creating Repository:: |
| 4576 | * Cloning Repository:: |
| 4577 | * Staging and Unstaging:: |
| 4578 | * Applying:: |
| 4579 | * Committing:: |
| 4580 | * Branching:: |
| 4581 | * Merging:: |
| 4582 | * Resolving Conflicts:: |
| 4583 | * Rebasing:: |
| 4584 | * Cherry Picking:: |
| 4585 | * Resetting:: |
| 4586 | * Stashing:: |
| 4587 | |
| 4588 | |
| 4589 | File: magit.info, Node: Creating Repository, Next: Cloning Repository, Up: Manipulating |
| 4590 | |
| 4591 | 6.1 Creating Repository |
| 4592 | ======================= |
| 4593 | |
| 4594 | ‘I’ (‘magit-init’) |
| 4595 | This command initializes a repository and then shows the status |
| 4596 | buffer for the new repository. |
| 4597 | |
| 4598 | If the directory is below an existing repository, then the user has |
| 4599 | to confirm that a new one should be created inside. If the |
| 4600 | directory is the root of the existing repository, then the user has |
| 4601 | to confirm that it should be reinitialized. |
| 4602 | |
| 4603 | |
| 4604 | File: magit.info, Node: Cloning Repository, Next: Staging and Unstaging, Prev: Creating Repository, Up: Manipulating |
| 4605 | |
| 4606 | 6.2 Cloning Repository |
| 4607 | ====================== |
| 4608 | |
| 4609 | To clone a remote or local repository use ‘C’, which is bound to the |
| 4610 | command ‘magit-clone’. This command either act as a transient prefix |
| 4611 | command, which binds several infix arguments and suffix commands, or it |
| 4612 | can invoke ‘git clone’ directly, depending on whether a prefix argument |
| 4613 | is used and on the value of ‘magit-clone-always-transient’. |
| 4614 | |
| 4615 | -- User Option: magit-clone-always-transient |
| 4616 | This option controls whether the command ‘magit-clone’ always acts |
| 4617 | as a transient prefix command, regardless of whether a prefix |
| 4618 | argument is used or not. If ‘t’, then that command always acts as |
| 4619 | a transient prefix. If ‘nil’, then a prefix argument has to be |
| 4620 | used for it to act as a transient. |
| 4621 | |
| 4622 | ‘C’ (‘magit-clone’) |
| 4623 | This command either acts as a transient prefix command as described |
| 4624 | above or does the same thing as ‘transient-clone-regular’ as |
| 4625 | described below. |
| 4626 | |
| 4627 | If it acts as a transient prefix, then it binds the following |
| 4628 | suffix commands and several infix arguments. |
| 4629 | |
| 4630 | ‘C C’ (‘magit-clone-regular’) |
| 4631 | This command creates a regular clone of an existing repository. |
| 4632 | The repository and the target directory are read from the user. |
| 4633 | |
| 4634 | ‘C s’ (‘magit-clone-shallow’) |
| 4635 | This command creates a shallow clone of an existing repository. |
| 4636 | The repository and the target directory are read from the user. By |
| 4637 | default the depth of the cloned history is a single commit, but |
| 4638 | with a prefix argument the depth is read from the user. |
| 4639 | |
| 4640 | ‘C >’ (‘magit-clone-sparse’) |
| 4641 | This command creates a clone of an existing repository and |
| 4642 | initializes a sparse checkout, avoiding a checkout of the full |
| 4643 | working tree. To add more directories, use the |
| 4644 | ‘magit-sparse-checkout’ transient (see *note Sparse checkouts::). |
| 4645 | |
| 4646 | ‘C b’ (‘magit-clone-bare’) |
| 4647 | This command creates a bare clone of an existing repository. The |
| 4648 | repository and the target directory are read from the user. |
| 4649 | |
| 4650 | ‘C m’ (‘magit-clone-mirror’) |
| 4651 | This command creates a mirror of an existing repository. The |
| 4652 | repository and the target directory are read from the user. |
| 4653 | |
| 4654 | The following suffixes are disabled by default. See *note |
| 4655 | (transient)Enabling and Disabling Suffixes:: for how to enable them. |
| 4656 | |
| 4657 | ‘C d’ (‘magit-clone-shallow-since’) |
| 4658 | This command creates a shallow clone of an existing repository. |
| 4659 | Only commits that were committed after a date are cloned, which is |
| 4660 | read from the user. The repository and the target directory are |
| 4661 | also read from the user. |
| 4662 | |
| 4663 | ‘C e’ (‘magit-clone-shallow-exclude’) |
| 4664 | This command creates a shallow clone of an existing repository. |
| 4665 | This reads a branch or tag from the user. Commits that are |
| 4666 | reachable from that are not cloned. The repository and the target |
| 4667 | directory are also read from the user. |
| 4668 | |
| 4669 | -- User Option: magit-clone-set-remote-head |
| 4670 | This option controls whether cloning causes the reference |
| 4671 | ‘refs/remotes/<remote>/HEAD’ to be created in the clone. The |
| 4672 | default is to delete the reference after running ‘git clone’, which |
| 4673 | insists on creating it. This is because the reference has not been |
| 4674 | found to be particularly useful as it is not automatically updated |
| 4675 | when the ‘HEAD’ of the remote changes. Setting this option to ‘t’ |
| 4676 | preserves Git's default behavior of creating the reference. |
| 4677 | |
| 4678 | -- User Option: magit-clone-set-remote.pushDefault |
| 4679 | This option controls whether the value of the Git variable |
| 4680 | ‘remote.pushDefault’ is set after cloning. |
| 4681 | |
| 4682 | • If ‘t’, then it is always set without asking. |
| 4683 | • If ‘ask’, then the users are asked every time they clone a |
| 4684 | repository. |
| 4685 | • If ‘nil’, then it is never set. |
| 4686 | |
| 4687 | -- User Option: magit-clone-default-directory |
| 4688 | This option control the default directory name used when reading |
| 4689 | the destination for a cloning operation. |
| 4690 | |
| 4691 | • If ‘nil’ (the default), then the value of ‘default-directory’ |
| 4692 | is used. |
| 4693 | • If a directory, then that is used. |
| 4694 | • If a function, then that is called with the remote url as the |
| 4695 | only argument and the returned value is used. |
| 4696 | |
| 4697 | -- User Option: magit-clone-name-alist |
| 4698 | This option maps regular expressions, which match repository names, |
| 4699 | to repository urls, making it possible for users to enter short |
| 4700 | names instead of urls when cloning repositories. |
| 4701 | |
| 4702 | Each element has the form ‘(REGEXP HOSTNAME USER)’. When the user |
| 4703 | enters a name when a cloning command asks for a name or url, then |
| 4704 | that is looked up in this list. The first element whose REGEXP |
| 4705 | matches is used. |
| 4706 | |
| 4707 | The format specified by option ‘magit-clone-url-format’ is used to |
| 4708 | turn the name into an url, using HOSTNAME and the repository name. |
| 4709 | If the provided name contains a slash, then that is used. |
| 4710 | Otherwise if the name omits the owner of the repository, then the |
| 4711 | default user specified in the matched entry is used. |
| 4712 | |
| 4713 | If USER contains a dot, then it is treated as a Git variable and |
| 4714 | the value of that is used as the username. Otherwise it is used as |
| 4715 | the username itself. |
| 4716 | |
| 4717 | -- User Option: magit-clone-url-format |
| 4718 | The format specified by this option is used when turning repository |
| 4719 | names into urls. ‘%h’ is the hostname and ‘%n’ is the repository |
| 4720 | name, including the name of the owner. The value can be a string |
| 4721 | (representing a single static format) or an alist with elements |
| 4722 | ‘(HOSTNAME . FORMAT)’ mapping hostnames to formats. When an alist |
| 4723 | is used, the ‘t’ key represents the default format. |
| 4724 | |
| 4725 | Example of a single format string: |
| 4726 | |
| 4727 | (setq magit-clone-url-format |
| 4728 | "git@%h:%n.git") |
| 4729 | |
| 4730 | Example of by-hostname format strings: |
| 4731 | |
| 4732 | (setq magit-clone-url-format |
| 4733 | '(("git.example.com" . "git@%h:~%n") |
| 4734 | (nil . "git@%h:%n.git"))) |
| 4735 | |
| 4736 | -- User Option: magit-post-clone-hook |
| 4737 | Hook run after the Git process has successfully finished cloning |
| 4738 | the repository. When the hook is called, ‘default-directory’ is |
| 4739 | let-bound to the directory where the repository has been cloned. |
| 4740 | |
| 4741 | |
| 4742 | File: magit.info, Node: Staging and Unstaging, Next: Applying, Prev: Cloning Repository, Up: Manipulating |
| 4743 | |
| 4744 | 6.3 Staging and Unstaging |
| 4745 | ========================= |
| 4746 | |
| 4747 | Like Git, Magit can of course stage and unstage complete files. Unlike |
| 4748 | Git, it also allows users to gracefully un-/stage individual hunks and |
| 4749 | even just part of a hunk. To stage individual hunks and parts of hunks |
| 4750 | using Git directly, one has to use the very modal and rather clumsy |
| 4751 | interface of a ‘git add --interactive’ session. |
| 4752 | |
| 4753 | With Magit, on the other hand, one can un-/stage individual hunks by |
| 4754 | just moving point into the respective section inside a diff displayed in |
| 4755 | the status buffer or a separate diff buffer and typing ‘s’ or ‘u’. To |
| 4756 | operate on just parts of a hunk, mark the changes that should be |
| 4757 | un-/staged using the region and then press the same key that would be |
| 4758 | used to un-/stage. To stage multiple files or hunks at once use a |
| 4759 | region that starts inside the heading of such a section and ends inside |
| 4760 | the heading of a sibling section of the same type. |
| 4761 | |
| 4762 | Besides staging and unstaging, Magit also provides several other |
| 4763 | "apply variants" that can also operate on a file, multiple files at |
| 4764 | once, a hunk, multiple hunks at once, and on parts of a hunk. These |
| 4765 | apply variants are described in the next section. |
| 4766 | |
| 4767 | You can also use Ediff to stage and unstage. See *note Ediffing::. |
| 4768 | |
| 4769 | ‘s’ (‘magit-stage’) |
| 4770 | Add the change at point to the staging area. |
| 4771 | |
| 4772 | With a prefix argument and an untracked file (or files) at point, |
| 4773 | stage the file but not its content. This makes it possible to |
| 4774 | stage only a subset of the new file's changes. |
| 4775 | |
| 4776 | ‘S’ (‘magit-stage-modified’) |
| 4777 | Stage all changes to files modified in the worktree. Stage all new |
| 4778 | content of tracked files and remove tracked files that no longer |
| 4779 | exist in the working tree from the index also. With a prefix |
| 4780 | argument also stage previously untracked (but not ignored) files. |
| 4781 | |
| 4782 | ‘u’ (‘magit-unstage’) |
| 4783 | Remove the change at point from the staging area. |
| 4784 | |
| 4785 | Only staged changes can be unstaged. But by default this command |
| 4786 | performs an action that is somewhat similar to unstaging, when it |
| 4787 | is called on a committed change: it reverses the change in the |
| 4788 | index but not in the working tree. |
| 4789 | |
| 4790 | ‘U’ (‘magit-unstage-all’) |
| 4791 | Remove all changes from the staging area. |
| 4792 | |
| 4793 | -- User Option: magit-unstage-committed |
| 4794 | This option controls whether ‘magit-unstage’ "unstages" committed |
| 4795 | changes by reversing them in the index but not the working tree. |
| 4796 | The alternative is to raise an error. |
| 4797 | |
| 4798 | ‘M-x magit-reverse-in-index’ |
| 4799 | This command reverses the committed change at point in the index |
| 4800 | but not the working tree. By default no key is bound directly to |
| 4801 | this command, but it is indirectly called when ‘u’ |
| 4802 | (‘magit-unstage’) is pressed on a committed change. |
| 4803 | |
| 4804 | This allows extracting a change from ‘HEAD’, while leaving it in |
| 4805 | the working tree, so that it can later be committed using a |
| 4806 | separate commit. A typical workflow would be: |
| 4807 | |
| 4808 | 1. Optionally make sure that there are no uncommitted changes. |
| 4809 | 2. Visit the ‘HEAD’ commit and navigate to the change that should |
| 4810 | not have been included in that commit. |
| 4811 | 3. Type ‘u’ (‘magit-unstage’) to reverse it in the index. This |
| 4812 | assumes that ‘magit-unstage-committed’ is non-‘nil’. |
| 4813 | 4. Type ‘c e’ to extend ‘HEAD’ with the staged changes, including |
| 4814 | those that were already staged before. |
| 4815 | 5. Optionally stage the remaining changes using ‘s’ or ‘S’ and |
| 4816 | then type ‘c c’ to create a new commit. |
| 4817 | |
| 4818 | ‘M-x magit-reset-index’ |
| 4819 | Reset the index to some commit. The commit is read from the user |
| 4820 | and defaults to the commit at point. If there is no commit at |
| 4821 | point, then it defaults to ‘HEAD’. |
| 4822 | |
| 4823 | 6.3.1 Staging from File-Visiting Buffers |
| 4824 | ---------------------------------------- |
| 4825 | |
| 4826 | Fine-grained un-/staging has to be done from the status or a diff |
| 4827 | buffer, but it's also possible to un-/stage all changes made to the file |
| 4828 | visited in the current buffer right from inside that buffer. |
| 4829 | |
| 4830 | ‘M-x magit-stage-files’ |
| 4831 | When invoked inside a file-visiting buffer, then stage all changes |
| 4832 | to that file. In a Magit buffer, stage the file at point if any. |
| 4833 | Otherwise prompt for a file to be staged. With a prefix argument |
| 4834 | always prompt the user for a file, even in a file-visiting buffer |
| 4835 | or when there is a file section at point. |
| 4836 | |
| 4837 | ‘M-x magit-unstage-files’ |
| 4838 | When invoked inside a file-visiting buffer, then unstage all |
| 4839 | changes to that file. In a Magit buffer, unstage the file at point |
| 4840 | if any. Otherwise prompt for a file to be unstaged. With a prefix |
| 4841 | argument always prompt the user for a file, even in a file-visiting |
| 4842 | buffer or when there is a file section at point. |
| 4843 | |
| 4844 | |
| 4845 | File: magit.info, Node: Applying, Next: Committing, Prev: Staging and Unstaging, Up: Manipulating |
| 4846 | |
| 4847 | 6.4 Applying |
| 4848 | ============ |
| 4849 | |
| 4850 | Magit provides several "apply variants": stage, unstage, discard, |
| 4851 | reverse, and "regular apply". At least when operating on a hunk they |
| 4852 | are all implemented using ‘git apply’, which is why they are called |
| 4853 | "apply variants". |
| 4854 | |
| 4855 | • Stage. Apply a change from the working tree to the index. The |
| 4856 | change also remains in the working tree. |
| 4857 | |
| 4858 | • Unstage. Remove a change from the index. The change remains in |
| 4859 | the working tree. |
| 4860 | |
| 4861 | • Discard. On a staged change, remove it from the working tree and |
| 4862 | the index. On an unstaged change, remove it from the working tree |
| 4863 | only. |
| 4864 | |
| 4865 | • Reverse. Reverse a change in the working tree. Both committed and |
| 4866 | staged changes can be reversed. Unstaged changes cannot be |
| 4867 | reversed. Discard them instead. |
| 4868 | |
| 4869 | • Apply. Apply a change to the working tree. Both committed and |
| 4870 | staged changes can be applied. Unstaged changes cannot be applied |
| 4871 | - as they already have been applied. |
| 4872 | |
| 4873 | The previous section described the staging and unstaging commands. |
| 4874 | What follows are the commands which implement the remaining apply |
| 4875 | variants. |
| 4876 | |
| 4877 | ‘a’ (‘magit-apply’) |
| 4878 | Apply the change at point to the working tree. |
| 4879 | |
| 4880 | With a prefix argument fallback to a 3-way merge. Doing so causes |
| 4881 | the change to be applied to the index as well. |
| 4882 | |
| 4883 | ‘k’ (‘magit-discard’) |
| 4884 | Remove the change at point from the working tree. |
| 4885 | |
| 4886 | On a hunk or file with unresolved conflicts prompt which side to |
| 4887 | keep (while discarding the other). If point is within the text of |
| 4888 | a side, then keep that side without prompting. |
| 4889 | |
| 4890 | ‘v’ (‘magit-reverse’) |
| 4891 | Reverse the change at point in the working tree. |
| 4892 | |
| 4893 | With a prefix argument fallback to a 3-way merge. Doing so causes |
| 4894 | the change to be applied to the index as well. |
| 4895 | |
| 4896 | With a prefix argument all apply variants attempt a 3-way merge when |
| 4897 | appropriate (i.e., when ‘git apply’ is used internally). |
| 4898 | |
| 4899 | -- Command: magit-copy-diff-as-kill |
| 4900 | This command saves the diff at point to the kill ring. |
| 4901 | |
| 4902 | It can be used on staged and unstaged changes, and anywhere |
| 4903 | ‘magit-apply’ can be used. Additionally, if there is no diff at |
| 4904 | point but ‘magit-buffer-revision’ is non-nil, or there is a commit |
| 4905 | at point, the diff for that commit is saved. |
| 4906 | |
| 4907 | This is useful if you need to copy some diff elsewhere, e.g., to a |
| 4908 | mail client or browser text area. |
| 4909 | |
| 4910 | |
| 4911 | File: magit.info, Node: Committing, Next: Branching, Prev: Applying, Up: Manipulating |
| 4912 | |
| 4913 | 6.5 Committing |
| 4914 | ============== |
| 4915 | |
| 4916 | When the user initiates a commit, Magit calls ‘git commit’ without the |
| 4917 | ‘--message’ argument, so Git has to get the message from the user. To |
| 4918 | do so, it creates a file such as ‘.git/COMMIT_EDITMSG’ and then opens |
| 4919 | that file in the editor specified by ‘$EDITOR’ (or ‘$GIT_EDITOR’). |
| 4920 | |
| 4921 | Magit arranges for that editor to be the Emacsclient. Once the user |
| 4922 | finishes the editing session, the Emacsclient exits and Git creates the |
| 4923 | commit, using the file's content as the commit message. |
| 4924 | |
| 4925 | 6.5.1 Initiating a Commit |
| 4926 | ------------------------- |
| 4927 | |
| 4928 | Also see *note (gitman)git-commit::. |
| 4929 | |
| 4930 | ‘c’ (‘magit-commit’) |
| 4931 | This transient prefix command binds the following suffix commands |
| 4932 | along with the appropriate infix arguments and displays them in a |
| 4933 | temporary buffer until a suffix is invoked. |
| 4934 | |
| 4935 | Creating a new commit |
| 4936 | ..................... |
| 4937 | |
| 4938 | ‘c c’ (‘magit-commit-create’) |
| 4939 | Create a new commit. |
| 4940 | |
| 4941 | Editing the last commit |
| 4942 | ....................... |
| 4943 | |
| 4944 | These commands modify the last (a.k.a., "HEAD") commit. The commit is |
| 4945 | modified (a.k.a., replaced) immediately. Similar commands exist for |
| 4946 | modifying other (non-HEAD) commits. Those commands are described in the |
| 4947 | following two sections. For each command in this section, we mention |
| 4948 | the respective non-HEAD commands, to make the relation explicit. |
| 4949 | |
| 4950 | The command descriptions below mention the specific arguments they |
| 4951 | use when calling ‘git commit’. The arguments specified in the menu are |
| 4952 | appended to those arguments. |
| 4953 | |
| 4954 | ‘c e’ (‘magit-commit-extend’) |
| 4955 | This command amends the staged changes to the last commit, without |
| 4956 | editing its commit message. |
| 4957 | |
| 4958 | This command calls ‘git commit --amend --no-edit’. |
| 4959 | |
| 4960 | With a prefix argument the committer date is not updated; without |
| 4961 | an argument it is updated. |
| 4962 | |
| 4963 | The option ‘magit-commit-extend-override-date’ can be used to |
| 4964 | inverse the meaning of the prefix argument. Non-interactively, the |
| 4965 | optional OVERRIDE-DATE argument controls this behavior, and the |
| 4966 | option is of no relevance. |
| 4967 | |
| 4968 | ‘c a’ (‘magit-commit-amend’) |
| 4969 | This command amends the staged changes to the last commit, and pops |
| 4970 | up a buffer to let the user edit its commit message. |
| 4971 | |
| 4972 | This command calls ‘git commit --amend --edit’. |
| 4973 | |
| 4974 | ‘c w’ (‘magit-commit-reword’) |
| 4975 | This command pops up a buffer to let the user edit the message of |
| 4976 | the latest commit. The commit tree remains unchanged and staged |
| 4977 | changes remain staged. |
| 4978 | |
| 4979 | This command calls ‘git commit --amend --only --edit’. |
| 4980 | |
| 4981 | With a prefix argument the committer date is not updated; without |
| 4982 | an argument it is updated. |
| 4983 | |
| 4984 | The option ‘magit-commit-reword-override-date’ can be used to |
| 4985 | inverse the meaning of the prefix argument. Non-interactively, the |
| 4986 | optional OVERRIDE-DATE argument controls this behavior, and the |
| 4987 | option is of no relevance. |
| 4988 | |
| 4989 | Editing any reachable commit |
| 4990 | ............................ |
| 4991 | |
| 4992 | These commands create a new commit, which targets an existing commit, |
| 4993 | from the staged changes and/or using a new commit message. Any commit |
| 4994 | that is reachable from HEAD, including HEAD itself, can be the target. |
| 4995 | |
| 4996 | The new commit is intended to be eventually squashed into the |
| 4997 | targeted commit, but this is *not* done immediately. The squashing is |
| 4998 | done at a later time, when you explicitly call |
| 4999 | ‘magit-rebase-autosquash’, or use ‘--autosquash’ with another rebase |
| 5000 | command. |
| 5001 | |
| 5002 | Some of these commands require that you immediately write a new |
| 5003 | commit message, or that you immediately edit an existing message. |
| 5004 | |
| 5005 | The new commits are called "squash" and "fixup" commits. The |
| 5006 | difference is that when a "squash" commit is squashed into its targeted |
| 5007 | commit, the user gets a chance to modify the message to be used for the |
| 5008 | final commit; while for "fixup" commits the existing message of the |
| 5009 | targeted commit is used as-is and the message of the "fixup" commit is |
| 5010 | discarded. |
| 5011 | |
| 5012 | If point is on a reachable commit, then all of these commands target |
| 5013 | that commit, without requiring confirmation. If point is on some |
| 5014 | reachable commit, but you want to target another commit, use a prefix |
| 5015 | argument, to select a commit in a log buffer dedicated to that task. |
| 5016 | The meaning of the prefix argument can be inverted by customizing |
| 5017 | ‘magit-commit-squash-confirm’. |
| 5018 | |
| 5019 | The command descriptions below mention the specific arguments they |
| 5020 | use when calling ‘git commit’. The arguments specified in the menu are |
| 5021 | appended to those arguments. |
| 5022 | |
| 5023 | The next two commands also exist in "instant" variants, which are |
| 5024 | described in the next section. Those variants behave the same as the |
| 5025 | variants described here, except that they immediately initiate an |
| 5026 | ‘--autosquash’ rebase. |
| 5027 | |
| 5028 | ‘c f’ (‘magit-commit-fixup’) |
| 5029 | This command creates a new fixup commit from the staged changes, |
| 5030 | targeting the reachable commit at point, if any. Otherwise the |
| 5031 | user is prompted for a commit. |
| 5032 | |
| 5033 | Use this variant if you want to correct some minor defect in the |
| 5034 | targeted commit, which does not require changes to the existing |
| 5035 | message of the targeted commit. |
| 5036 | |
| 5037 | This command calls ‘git commit --fixup=COMMIT --no-edit’. |
| 5038 | |
| 5039 | ‘c s’ (‘magit-commit-squash’) |
| 5040 | This command creates a new squash commit from the staged changes, |
| 5041 | targeting the reachable commit at point, if any. Otherwise the |
| 5042 | user is prompted for a commit. |
| 5043 | |
| 5044 | Use this variant if you want a chance to make changes to the final |
| 5045 | commit message, but not until the two commits are being squashed |
| 5046 | into the final combined commit. |
| 5047 | |
| 5048 | This command calls ‘git commit --squash=COMMIT --no-edit’. |
| 5049 | |
| 5050 | ‘c A’ (‘magit-commit-alter’) |
| 5051 | This command creates a new fixup commit from the staged changes, |
| 5052 | targeting the reachable commit at point, if any. Otherwise the |
| 5053 | user is prompted for a commit. |
| 5054 | |
| 5055 | Use this variant if you want to write the final commit message now, |
| 5056 | but (as for all variants in this section) do not want to |
| 5057 | immediately squash the fixup and targeted commits into a final |
| 5058 | combined commit. |
| 5059 | |
| 5060 | This command calls ‘git commit --fixup=amend:COMMIT --edit’. |
| 5061 | |
| 5062 | ‘c n’ (‘magit-commit-augment’) |
| 5063 | This command creates a new squash commit from the staged changes, |
| 5064 | targeting the reachable commit at point, if any. Otherwise the |
| 5065 | user is prompted for a commit. |
| 5066 | |
| 5067 | Use this variant if you want to describe the new changes now, but |
| 5068 | want to delay writing the final message, which describes the |
| 5069 | changes in the combined commit, until you actually combine the |
| 5070 | squash and target commits into the final commit. You can think of |
| 5071 | the new message, which you write here, as a "note", to be |
| 5072 | integrated once once you write the final commit message. |
| 5073 | |
| 5074 | This command calls ‘git commit --squash=COMMIT --edit’. |
| 5075 | |
| 5076 | ‘c W’ (‘magit-commit-revise’) |
| 5077 | This command pops up a buffer containing the commit message of the |
| 5078 | reachable commit at point, if any. Otherwise the user is prompted |
| 5079 | for a commit to target. |
| 5080 | |
| 5081 | Use this variant if you want to correct the message of the targeted |
| 5082 | commit, but want to delay performing the ‘--autosquash’ rebase, |
| 5083 | which actually changes that commit. |
| 5084 | |
| 5085 | This command calls ‘git commit --fixup=reword:COMMIT --edit’. |
| 5086 | |
| 5087 | Editing any reachable commit and rebasing immediately |
| 5088 | ..................................................... |
| 5089 | |
| 5090 | These commands create a new commit, which targets an existing commit, |
| 5091 | from the staged changes. Any commit that is reachable from HEAD, |
| 5092 | including HEAD itself, can be the target. |
| 5093 | |
| 5094 | The new commit is immediately squashed into its target commit, using |
| 5095 | an ‘--autosquash’ rebase. |
| 5096 | |
| 5097 | The command descriptions below mention the specific arguments they |
| 5098 | use when calling ‘git commit’. The arguments specified in the menu are |
| 5099 | appended to those arguments when calling ‘git commit’. |
| 5100 | |
| 5101 | ‘c F’ (‘magit-commit-instant-fixup’) |
| 5102 | This command creates a fixup commit, targeting the reachable commit |
| 5103 | at point, if any. Otherwise the user is prompted for a commit. |
| 5104 | Then it instantly performs a rebase, to squash the new commit into |
| 5105 | the targeted commit. |
| 5106 | |
| 5107 | The original commit message of the targeted commit is left |
| 5108 | untouched. |
| 5109 | |
| 5110 | This command calls ‘git commit --fixup=COMMIT --no-edit’ and then |
| 5111 | ‘git rebase --autosquash MERGE-BASE’. |
| 5112 | |
| 5113 | ‘c S’ (‘magit-commit-instant-squash’) |
| 5114 | This command creates a squash commit, targeting the reachable |
| 5115 | commit at point, if any. Otherwise the user is prompted for a |
| 5116 | commit. Then it instantly performs a rebase, to squash the new |
| 5117 | commit into the targeted commit. |
| 5118 | |
| 5119 | During the rebase phase the user is asked to author the final |
| 5120 | commit message, based on the original message of the targeted |
| 5121 | commit. |
| 5122 | |
| 5123 | This command calls ‘git commit --squash=COMMIT --no-edit’ and then |
| 5124 | ‘git rebase --autosquash MERGE-BASE’. |
| 5125 | |
| 5126 | Options used by commit commands |
| 5127 | ............................... |
| 5128 | |
| 5129 | • Used by all or most commit commands |
| 5130 | |
| 5131 | -- User Option: magit-commit-show-diff |
| 5132 | Whether the relevant diff is automatically shown when |
| 5133 | committing. |
| 5134 | |
| 5135 | -- User Option: magit-commit-ask-to-stage |
| 5136 | Whether to ask to stage all unstaged changes when committing |
| 5137 | and nothing is staged. |
| 5138 | |
| 5139 | -- User Option: magit-post-commit-hook |
| 5140 | Hook run after creating a commit without the user editing a |
| 5141 | message. |
| 5142 | |
| 5143 | This hook is run by ‘magit-refresh’ if ‘this-command’ is a |
| 5144 | member of ‘magit-post-commit-hook-commands’. This only |
| 5145 | includes commands named ‘magit-commit-*’ that do *not* require |
| 5146 | that the user edits the commit message in a buffer. |
| 5147 | |
| 5148 | Also see ‘git-commit-post-finish-hook’. |
| 5149 | |
| 5150 | -- User Option: magit-commit-diff-inhibit-same-window |
| 5151 | Whether to inhibit use of same window when showing diff while |
| 5152 | committing. |
| 5153 | |
| 5154 | When writing a commit, then a diff of the changes to be |
| 5155 | committed is automatically shown. The idea is that the diff |
| 5156 | is shown in a different window of the same frame and for most |
| 5157 | users that just works. In other words most users can |
| 5158 | completely ignore this option because its value doesn't make a |
| 5159 | difference for them. |
| 5160 | |
| 5161 | However for users who configured Emacs to never create a new |
| 5162 | window even when the package explicitly tries to do so, then |
| 5163 | displaying two new buffers necessarily means that the first is |
| 5164 | immediately replaced by the second. In our case the message |
| 5165 | buffer is immediately replaced by the diff buffer, which is of |
| 5166 | course highly undesirable. |
| 5167 | |
| 5168 | A workaround is to suppress this user configuration in this |
| 5169 | particular case. Users have to explicitly opt-in by toggling |
| 5170 | this option. We cannot enable the workaround unconditionally |
| 5171 | because that again causes issues for other users: if the frame |
| 5172 | is too tiny or the relevant settings too aggressive, then the |
| 5173 | diff buffer would end up being displayed in a new frame. |
| 5174 | |
| 5175 | Also see <https://github.com/magit/magit/issues/4132>. |
| 5176 | |
| 5177 | • Used by all squash and fixup commands |
| 5178 | |
| 5179 | -- User Option: magit-commit-squash-confirm |
| 5180 | Whether the commit targeted by squash and fixup has to be |
| 5181 | confirmed. When non-‘nil’ then the commit at point (if any) |
| 5182 | is used as default choice. Otherwise it has to be confirmed. |
| 5183 | This option only affects ‘magit-commit-squash’ and |
| 5184 | ‘magit-commit-fixup’. The "instant" variants always require |
| 5185 | confirmation because making an error while using those is |
| 5186 | harder to recover from. |
| 5187 | |
| 5188 | • Used by specific commit commands |
| 5189 | |
| 5190 | -- User Option: magit-commit-extend-override-date |
| 5191 | Whether using ‘magit-commit-extend’ changes the committer |
| 5192 | date. |
| 5193 | |
| 5194 | -- User Option: magit-commit-reword-override-date |
| 5195 | Whether using ‘magit-commit-reword’ changes the committer |
| 5196 | date. |
| 5197 | |
| 5198 | 6.5.2 Editing Commit Messages |
| 5199 | ----------------------------- |
| 5200 | |
| 5201 | After initiating a commit as described in the previous section, two new |
| 5202 | buffers appear. One shows the changes that are about to be committed, |
| 5203 | while the other is used to write the message. |
| 5204 | |
| 5205 | Commit messages are edited in an edit session - in the background |
| 5206 | ‘git’ is waiting for the editor, in our case ‘emacsclient’, to save the |
| 5207 | commit message in a file (in most cases ‘.git/COMMIT_EDITMSG’) and then |
| 5208 | return. If the editor returns with a non-zero exit status then ‘git’ |
| 5209 | does not create the commit. So the most important commands are those |
| 5210 | for finishing and aborting the commit. |
| 5211 | |
| 5212 | ‘C-c C-c’ (‘with-editor-finish’) |
| 5213 | Finish the current editing session by returning with exit code 0. |
| 5214 | Git then creates the commit using the message it finds in the file. |
| 5215 | |
| 5216 | ‘C-c C-k’ (‘with-editor-cancel’) |
| 5217 | Cancel the current editing session by returning with exit code 1. |
| 5218 | Git then cancels the commit, but leaves the file untouched. |
| 5219 | |
| 5220 | In addition to being used by ‘git commit’, messages may also be |
| 5221 | stored in a ring that persists until Emacs is closed. By default the |
| 5222 | message is stored at the beginning and the end of an edit session |
| 5223 | (regardless of whether the session is finished successfully or was |
| 5224 | canceled). It is sometimes useful to bring back messages from that |
| 5225 | ring. |
| 5226 | |
| 5227 | ‘C-c M-s’ (‘git-commit-save-message’) |
| 5228 | Save the current buffer content to the commit message ring. |
| 5229 | |
| 5230 | ‘M-p’ (‘git-commit-prev-message’) |
| 5231 | Cycle backward through the commit message ring, after saving the |
| 5232 | current message to the ring. With a numeric prefix ARG, go back |
| 5233 | ARG comments. |
| 5234 | |
| 5235 | ‘M-n’ (‘git-commit-next-message’) |
| 5236 | Cycle forward through the commit message ring, after saving the |
| 5237 | current message to the ring. With a numeric prefix ARG, go back |
| 5238 | ARG comments. |
| 5239 | |
| 5240 | By default the diff for the changes that are about to be committed |
| 5241 | are automatically shown when invoking the commit. To prevent that, |
| 5242 | remove ‘magit-commit-diff’ from ‘server-switch-hook’. |
| 5243 | |
| 5244 | When amending to an existing commit it may be useful to show either |
| 5245 | the changes that are about to be added to that commit or to show those |
| 5246 | changes alongside those that have already been committed. |
| 5247 | |
| 5248 | ‘C-c C-d’ (‘magit-diff-while-committing’) |
| 5249 | While committing, show the changes that are about to be committed. |
| 5250 | While amending, invoking the command again toggles between showing |
| 5251 | just the new changes or all the changes that will be committed. |
| 5252 | |
| 5253 | Using the Revision Stack |
| 5254 | ........................ |
| 5255 | |
| 5256 | ‘C-c C-w’ (‘magit-pop-revision-stack’) |
| 5257 | This command inserts a representation of a revision into the |
| 5258 | current buffer. It can be used inside buffers used to write commit |
| 5259 | messages but also in other buffers such as buffers used to edit |
| 5260 | emails or ChangeLog files. |
| 5261 | |
| 5262 | By default this command pops the revision which was last added to |
| 5263 | the ‘magit-revision-stack’ and inserts it into the current buffer |
| 5264 | according to ‘magit-pop-revision-stack-format’. Revisions can be |
| 5265 | put on the stack using ‘magit-copy-section-value’ and |
| 5266 | ‘magit-copy-buffer-revision’. |
| 5267 | |
| 5268 | If the stack is empty or with a prefix argument it instead reads a |
| 5269 | revision in the minibuffer. By using the minibuffer history this |
| 5270 | allows selecting an item which was popped earlier or to insert an |
| 5271 | arbitrary reference or revision without first pushing it onto the |
| 5272 | stack. |
| 5273 | |
| 5274 | When reading the revision from the minibuffer, then it might not be |
| 5275 | possible to guess the correct repository. When this command is |
| 5276 | called inside a repository (e.g., while composing a commit |
| 5277 | message), then that repository is used. Otherwise (e.g., while |
| 5278 | composing an email) then the repository recorded for the top |
| 5279 | element of the stack is used (even though we insert another |
| 5280 | revision). If not called inside a repository and with an empty |
| 5281 | stack, or with two prefix arguments, then read the repository in |
| 5282 | the minibuffer too. |
| 5283 | |
| 5284 | -- User Option: magit-pop-revision-stack-format |
| 5285 | This option controls how the command ‘magit-pop-revision-stack’ |
| 5286 | inserts a revision into the current buffer. |
| 5287 | |
| 5288 | The entries on the stack have the format ‘(HASH TOPLEVEL)’ and this |
| 5289 | option has the format ‘(POINT-FORMAT EOB-FORMAT INDEX-REGEXP)’, all |
| 5290 | of which may be ‘nil’ or a string (though either one of EOB-FORMAT |
| 5291 | or POINT-FORMAT should be a string, and if INDEX-REGEXP is |
| 5292 | non-‘nil’, then the two formats should be too). |
| 5293 | |
| 5294 | First INDEX-REGEXP is used to find the previously inserted entry, |
| 5295 | by searching backward from point. The first submatch must match |
| 5296 | the index number. That number is incremented by one, and becomes |
| 5297 | the index number of the entry to be inserted. If you don't want to |
| 5298 | number the inserted revisions, then use ‘nil’ for INDEX-REGEXP. |
| 5299 | |
| 5300 | If INDEX-REGEXP is non-‘nil’ then both POINT-FORMAT and EOB-FORMAT |
| 5301 | should contain \"%N\", which is replaced with the number that was |
| 5302 | determined in the previous step. |
| 5303 | |
| 5304 | Both formats, if non-‘nil’ and after removing %N, are then expanded |
| 5305 | using ‘git show --format=FORMAT ...’ inside TOPLEVEL. |
| 5306 | |
| 5307 | The expansion of POINT-FORMAT is inserted at point, and the |
| 5308 | expansion of EOB-FORMAT is inserted at the end of the buffer (if |
| 5309 | the buffer ends with a comment, then it is inserted right before |
| 5310 | that). |
| 5311 | |
| 5312 | Commit Pseudo Headers |
| 5313 | ..................... |
| 5314 | |
| 5315 | Some projects use pseudo headers in commit messages. Magit colorizes |
| 5316 | such headers and provides some commands to insert such headers. |
| 5317 | |
| 5318 | -- User Option: git-commit-known-pseudo-headers |
| 5319 | A list of Git pseudo headers to be highlighted. |
| 5320 | |
| 5321 | ‘C-c C-i’ (‘git-commit-insert-pseudo-header’) |
| 5322 | Insert a commit message pseudo header. |
| 5323 | |
| 5324 | ‘C-c C-a’ (‘git-commit-ack’) |
| 5325 | Insert a header acknowledging that you have looked at the commit. |
| 5326 | |
| 5327 | ‘C-c C-r’ (‘git-commit-review’) |
| 5328 | Insert a header acknowledging that you have reviewed the commit. |
| 5329 | |
| 5330 | ‘C-c C-s’ (‘git-commit-signoff’) |
| 5331 | Insert a header to sign off the commit. |
| 5332 | |
| 5333 | ‘C-c C-t’ (‘git-commit-test’) |
| 5334 | Insert a header acknowledging that you have tested the commit. |
| 5335 | |
| 5336 | ‘C-c C-o’ (‘git-commit-cc’) |
| 5337 | Insert a header mentioning someone who might be interested. |
| 5338 | |
| 5339 | ‘C-c C-p’ (‘git-commit-reported’) |
| 5340 | Insert a header mentioning the person who reported the issue being |
| 5341 | fixed by the commit. |
| 5342 | |
| 5343 | ‘C-c M-i’ (‘git-commit-suggested’) |
| 5344 | Insert a header mentioning the person who suggested the change. |
| 5345 | |
| 5346 | Commit Mode and Hooks |
| 5347 | ..................... |
| 5348 | |
| 5349 | ‘git-commit-mode’ is a minor mode that is only used to establish certain |
| 5350 | key bindings. This makes it possible to use an arbitrary major mode in |
| 5351 | buffers used to edit commit messages. It is even possible to use |
| 5352 | different major modes in different repositories, which is useful when |
| 5353 | different projects impose different commit message conventions. |
| 5354 | |
| 5355 | -- User Option: git-commit-major-mode |
| 5356 | The value of this option is the major mode used to edit Git commit |
| 5357 | messages. |
| 5358 | |
| 5359 | Because ‘git-commit-mode’ is a minor mode, we don't use its mode hook |
| 5360 | to setup the buffer, except for the key bindings. All other setup |
| 5361 | happens in the function ‘git-commit-setup’, which among other things |
| 5362 | runs the hook ‘git-commit-setup-hook’. |
| 5363 | |
| 5364 | -- User Option: git-commit-setup-hook |
| 5365 | Hook run at the end of ‘git-commit-setup’. |
| 5366 | |
| 5367 | The following functions are suitable for this hook: |
| 5368 | |
| 5369 | -- Function: git-commit-save-message |
| 5370 | Save the current buffer content to the commit message ring. |
| 5371 | |
| 5372 | -- Function: git-commit-setup-changelog-support |
| 5373 | After this function is called, ChangeLog entries are treated as |
| 5374 | paragraphs. |
| 5375 | |
| 5376 | -- Function: git-commit-turn-on-auto-fill |
| 5377 | Turn on ‘auto-fill-mode’. |
| 5378 | |
| 5379 | -- Function: git-commit-turn-on-flyspell |
| 5380 | Turn on Flyspell mode. Also prevent comments from being checked |
| 5381 | and finally check current non-comment text. |
| 5382 | |
| 5383 | -- Function: git-commit-propertize-diff |
| 5384 | Propertize the diff shown inside the commit message buffer. Git |
| 5385 | inserts such diffs into the commit message template when the |
| 5386 | ‘--verbose’ argument is used. ‘magit-commit’ by default does not |
| 5387 | offer that argument because the diff that is shown in a separate |
| 5388 | buffer is more useful. But some users disagree, which is why this |
| 5389 | function exists. |
| 5390 | |
| 5391 | -- Function: bug-reference-mode |
| 5392 | Hyperlink bug references in the buffer. |
| 5393 | |
| 5394 | -- Function: with-editor-usage-message |
| 5395 | Show usage information in the echo area. |
| 5396 | |
| 5397 | -- User Option: git-commit-post-finish-hook |
| 5398 | Hook run after the user finished writing a commit message. |
| 5399 | |
| 5400 | This hook is only run after pressing ‘C-c C-c’ in a buffer used to |
| 5401 | edit a commit message. If a commit is created without the user |
| 5402 | typing a message into a buffer, then this hook is not run. |
| 5403 | |
| 5404 | This hook is not run until the new commit has been created. If |
| 5405 | doing so takes Git longer than one second, then this hook isn't run |
| 5406 | at all. For certain commands such as ‘magit-rebase-continue’ this |
| 5407 | hook is never run because doing so would lead to a race condition. |
| 5408 | |
| 5409 | This hook is only run if ‘magit’ is available. |
| 5410 | |
| 5411 | Also see ‘magit-post-commit-hook’. |
| 5412 | |
| 5413 | Commit Message Conventions |
| 5414 | .......................... |
| 5415 | |
| 5416 | Git-Commit highlights certain violations of commonly accepted commit |
| 5417 | message conventions. Certain violations even cause Git-Commit to ask |
| 5418 | you to confirm that you really want to do that. This nagging can of |
| 5419 | course be turned off, but the result of doing that usually is that |
| 5420 | instead of some code it's now the human who is reviewing your commits |
| 5421 | who has to waste some time telling you to fix your commits. |
| 5422 | |
| 5423 | -- User Option: git-commit-summary-max-length |
| 5424 | The intended maximal length of the summary line of commit messages. |
| 5425 | Characters beyond this column are colorized to indicate that this |
| 5426 | preference has been violated. |
| 5427 | |
| 5428 | -- User Option: git-commit-finish-query-functions |
| 5429 | List of functions called to query before performing commit. |
| 5430 | |
| 5431 | The commit message buffer is current while the functions are |
| 5432 | called. If any of them returns ‘nil’, then the commit is not |
| 5433 | performed and the buffer is not killed. The user should then fix |
| 5434 | the issue and try again. |
| 5435 | |
| 5436 | The functions are called with one argument. If it is non-‘nil’ |
| 5437 | then that indicates that the user used a prefix argument to force |
| 5438 | finishing the session despite issues. Functions should usually |
| 5439 | honor this wish and return non-‘nil’. |
| 5440 | |
| 5441 | By default the only member is ‘git-commit-check-style-conventions’. |
| 5442 | |
| 5443 | -- Function: git-commit-check-style-conventions |
| 5444 | This function checks for violations of certain basic style |
| 5445 | conventions. For each violation it asks users if they want to |
| 5446 | proceed anyway. |
| 5447 | |
| 5448 | -- User Option: git-commit-style-convention-checks |
| 5449 | This option controls what conventions the function by the same name |
| 5450 | tries to enforce. The value is a list of self-explanatory symbols |
| 5451 | identifying certain conventions; ‘non-empty-second-line’ and |
| 5452 | ‘overlong-summary-line’. |
| 5453 | |
| 5454 | |
| 5455 | File: magit.info, Node: Branching, Next: Merging, Prev: Committing, Up: Manipulating |
| 5456 | |
| 5457 | 6.6 Branching |
| 5458 | ============= |
| 5459 | |
| 5460 | 6.6.1 The Two Remotes |
| 5461 | --------------------- |
| 5462 | |
| 5463 | The upstream branch of some local branch is the branch into which the |
| 5464 | commits on that local branch should eventually be merged, usually |
| 5465 | something like ‘origin/master’. For the ‘master’ branch itself the |
| 5466 | upstream branch and the branch it is being pushed to, are usually the |
| 5467 | same remote branch. But for a feature branch the upstream branch and |
| 5468 | the branch it is being pushed to should differ. |
| 5469 | |
| 5470 | The commits on feature branches too should _eventually_ end up in a |
| 5471 | remote branch such as ‘origin/master’ or ‘origin/maint’. Such a branch |
| 5472 | should therefore be used as the upstream. But feature branches |
| 5473 | shouldn't be pushed directly to such branches. Instead a feature branch |
| 5474 | ‘my-feature’ is usually pushed to ‘my-fork/my-feature’ or if you are a |
| 5475 | contributor ‘origin/my-feature’. After the new feature has been |
| 5476 | reviewed, the maintainer merges the feature into ‘master’. And finally |
| 5477 | ‘master’ (not ‘my-feature’ itself) is pushed to ‘origin/master’. |
| 5478 | |
| 5479 | But new features seldom are perfect on the first try, and so feature |
| 5480 | branches usually have to be reviewed, improved, and re-pushed several |
| 5481 | times. Pushing should therefore be easy to do, and for that reason many |
| 5482 | Git users have concluded that it is best to use the remote branch to |
| 5483 | which the local feature branch is being pushed as its upstream. |
| 5484 | |
| 5485 | But luckily Git has long ago gained support for a push-remote which |
| 5486 | can be configured separately from the upstream branch, using the |
| 5487 | variables ‘branch.<name>.pushRemote’ and ‘remote.pushDefault’. So we no |
| 5488 | longer have to choose which of the two remotes should be used as "the |
| 5489 | remote". |
| 5490 | |
| 5491 | Each of the fetching, pulling, and pushing transient commands |
| 5492 | features three suffix commands that act on the current branch and some |
| 5493 | other branch. Of these, ‘p’ is bound to a command which acts on the |
| 5494 | push-remote, ‘u’ is bound to a command which acts on the upstream, and |
| 5495 | ‘e’ is bound to a command which acts on any other branch. The status |
| 5496 | buffer shows unpushed and unpulled commits for both the push-remote and |
| 5497 | the upstream. |
| 5498 | |
| 5499 | It's fairly simple to configure these two remotes. The values of all |
| 5500 | the variables that are related to fetching, pulling, and pushing (as |
| 5501 | well as some other branch-related variables) can be inspected and |
| 5502 | changed using the command ‘magit-branch-configure’, which is available |
| 5503 | from many transient prefix commands that deal with branches. It is also |
| 5504 | possible to set the push-remote or upstream while pushing (see *note |
| 5505 | Pushing::). |
| 5506 | |
| 5507 | 6.6.2 Branch Commands |
| 5508 | --------------------- |
| 5509 | |
| 5510 | The transient prefix command ‘magit-branch’ is used to create and |
| 5511 | checkout branches, and to make changes to existing branches. It is not |
| 5512 | used to fetch, pull, merge, rebase, or push branches, i.e., this command |
| 5513 | deals with branches themselves, not with the commits reachable from |
| 5514 | them. Those features are available from separate transient commands. |
| 5515 | |
| 5516 | ‘b’ (‘magit-branch’) |
| 5517 | This transient prefix command binds the following suffix commands |
| 5518 | and displays them in a temporary buffer until a suffix is invoked. |
| 5519 | |
| 5520 | By default it also binds and displays the values of some |
| 5521 | branch-related Git variables and allows changing their values. |
| 5522 | |
| 5523 | -- User Option: magit-branch-direct-configure |
| 5524 | This option controls whether the transient command ‘magit-branch’ |
| 5525 | can be used to directly change the values of Git variables. This |
| 5526 | defaults to ‘t’ (to avoid changing key bindings). When set to |
| 5527 | ‘nil’, then no variables are displayed by that transient command, |
| 5528 | and its suffix command ‘magit-branch-configure’ has to be used |
| 5529 | instead to view and change branch related variables. |
| 5530 | |
| 5531 | ‘b C’ (‘magit-branch-configure’) |
| 5532 | ‘f C’ |
| 5533 | ‘F C’ |
| 5534 | ‘P C’ |
| 5535 | This transient prefix command binds commands that set the value of |
| 5536 | branch-related variables and displays them in a temporary buffer |
| 5537 | until the transient is exited. |
| 5538 | |
| 5539 | With a prefix argument, this command always prompts for a branch. |
| 5540 | |
| 5541 | Without a prefix argument this depends on whether it was invoked as |
| 5542 | a suffix of ‘magit-branch’ and on the |
| 5543 | ‘magit-branch-direct-configure’ option. If ‘magit-branch’ already |
| 5544 | displays the variables for the current branch, then it isn't useful |
| 5545 | to invoke another transient that displays them for the same branch. |
| 5546 | In that case this command prompts for a branch. |
| 5547 | |
| 5548 | The variables are described in *note Branch Git Variables::. |
| 5549 | |
| 5550 | ‘b b’ (‘magit-checkout’) |
| 5551 | Checkout a revision read in the minibuffer and defaulting to the |
| 5552 | branch or arbitrary revision at point. If the revision is a local |
| 5553 | branch then that becomes the current branch. If it is something |
| 5554 | else then ‘HEAD’ becomes detached. Checkout fails if the working |
| 5555 | tree or the staging area contain changes. |
| 5556 | |
| 5557 | ‘b n’ (‘magit-branch-create’) |
| 5558 | Create a new branch. The user is asked for a branch or arbitrary |
| 5559 | revision to use as the starting point of the new branch. When a |
| 5560 | branch name is provided, then that becomes the upstream branch of |
| 5561 | the new branch. The name of the new branch is also read in the |
| 5562 | minibuffer. |
| 5563 | |
| 5564 | Also see option ‘magit-branch-prefer-remote-upstream’. |
| 5565 | |
| 5566 | ‘b c’ (‘magit-branch-and-checkout’) |
| 5567 | This command creates a new branch like ‘magit-branch-create’, but |
| 5568 | then also checks it out. |
| 5569 | |
| 5570 | Also see option ‘magit-branch-prefer-remote-upstream’. |
| 5571 | |
| 5572 | ‘b l’ (‘magit-branch-checkout’) |
| 5573 | This command checks out an existing or new local branch. It reads |
| 5574 | a branch name from the user offering all local branches and a |
| 5575 | subset of remote branches as candidates. Remote branches for which |
| 5576 | a local branch by the same name exists are omitted from the list of |
| 5577 | candidates. The user can also enter a completely new branch name. |
| 5578 | |
| 5579 | • If the user selects an existing local branch, then that is |
| 5580 | checked out. |
| 5581 | |
| 5582 | • If the user selects a remote branch, then it creates and |
| 5583 | checks out a new local branch with the same name, and |
| 5584 | configures the selected remote branch as the push target. |
| 5585 | |
| 5586 | • If the user enters a new branch name, then it creates and |
| 5587 | checks that out, after also reading the starting-point from |
| 5588 | the user. |
| 5589 | |
| 5590 | In the latter two cases the upstream is also set. Whether it is |
| 5591 | set to the chosen starting point or something else depends on the |
| 5592 | value of ‘magit-branch-adjust-remote-upstream-alist’. |
| 5593 | |
| 5594 | ‘b s’ (‘magit-branch-spinoff’) |
| 5595 | This command creates and checks out a new branch starting at and |
| 5596 | tracking the current branch. That branch in turn is reset to the |
| 5597 | last commit it shares with its upstream. If the current branch has |
| 5598 | no upstream or no unpushed commits, then the new branch is created |
| 5599 | anyway and the previously current branch is not touched. |
| 5600 | |
| 5601 | This is useful to create a feature branch after work has already |
| 5602 | begun on the old branch (likely but not necessarily "master"). |
| 5603 | |
| 5604 | If the current branch is a member of the value of option |
| 5605 | ‘magit-branch-prefer-remote-upstream’ (which see), then the current |
| 5606 | branch will be used as the starting point as usual, but the |
| 5607 | upstream of the starting-point may be used as the upstream of the |
| 5608 | new branch, instead of the starting-point itself. |
| 5609 | |
| 5610 | If optional FROM is non-‘nil’, then the source branch is reset to |
| 5611 | ‘FROM~’, instead of to the last commit it shares with its upstream. |
| 5612 | Interactively, FROM is only ever non-‘nil’, if the region selects |
| 5613 | some commits, and among those commits, FROM is the commit that is |
| 5614 | the fewest commits ahead of the source branch. |
| 5615 | |
| 5616 | The commit at the other end of the selection actually does not |
| 5617 | matter, all commits between FROM and ‘HEAD’ are moved to the new |
| 5618 | branch. If FROM is not reachable from ‘HEAD’ or is reachable from |
| 5619 | the source branch's upstream, then an error is raised. |
| 5620 | |
| 5621 | ‘b S’ (‘magit-branch-spinout’) |
| 5622 | This command behaves like ‘magit-branch-spinoff’, except that it |
| 5623 | does not change the current branch. If there are any uncommitted |
| 5624 | changes, then it behaves exactly like ‘magit-branch-spinoff’. |
| 5625 | |
| 5626 | ‘b x’ (‘magit-branch-reset’) |
| 5627 | This command resets a branch, defaulting to the branch at point, to |
| 5628 | the tip of another branch or any other commit. |
| 5629 | |
| 5630 | When the branch being reset is the current branch, then a hard |
| 5631 | reset is performed. If there are any uncommitted changes, then the |
| 5632 | user has to confirm the reset because those changes would be lost. |
| 5633 | |
| 5634 | This is useful when you have started work on a feature branch but |
| 5635 | realize it's all crap and want to start over. |
| 5636 | |
| 5637 | When resetting to another branch and a prefix argument is used, |
| 5638 | then the target branch is set as the upstream of the branch that is |
| 5639 | being reset. |
| 5640 | |
| 5641 | ‘b k’ (‘magit-branch-delete’) |
| 5642 | Delete one or multiple branches. If the region marks multiple |
| 5643 | branches, then offer to delete those. Otherwise, prompt for a |
| 5644 | single branch to be deleted, defaulting to the branch at point. |
| 5645 | |
| 5646 | Require confirmation when deleting branches is dangerous in some |
| 5647 | way. Option ‘magit-no-confirm’ can be customized to not require |
| 5648 | confirmation in certain cases. See its docstring to learn why |
| 5649 | confirmation is required by default in certain cases or if a prompt |
| 5650 | is confusing. |
| 5651 | |
| 5652 | ‘b m’ (‘magit-branch-rename’) |
| 5653 | Rename a branch. The branch and the new name are read in the |
| 5654 | minibuffer. With prefix argument the branch is renamed even if |
| 5655 | that name conflicts with an existing branch. |
| 5656 | |
| 5657 | ‘b r’ (‘magit-checkout-remote-ref’) |
| 5658 | This commands first reads a remote from the user. Then it queries |
| 5659 | that remote for a list of its references and presents that to the |
| 5660 | user. After the user has selected one of them, it fetches just |
| 5661 | that ref, and finally it checks out "FETCH_HEAD", which now refers |
| 5662 | to the same commit as REF does on REMOTE. |
| 5663 | |
| 5664 | This is only useful if you usually only fetch a subset of the refs |
| 5665 | from REMOTE. Otherwise it is better to use ‘magit-checkout’, as |
| 5666 | that avoids a round-trip. |
| 5667 | |
| 5668 | This command is not shown in the menu by default, see *note |
| 5669 | transient#Enabling and Disabling Suffixes: (transient)Enabling and |
| 5670 | Disabling Suffixes. |
| 5671 | |
| 5672 | -- User Option: magit-branch-read-upstream-first |
| 5673 | When creating a branch, whether to read the upstream branch before |
| 5674 | the name of the branch that is to be created. The default is ‘t’, |
| 5675 | and I recommend you leave it at that. |
| 5676 | |
| 5677 | -- User Option: magit-branch-name-suggestions |
| 5678 | List of names and/or prefixes suggested when naming a new branch. |
| 5679 | |
| 5680 | -- User Option: magit-branch-prefer-remote-upstream |
| 5681 | This option specifies whether remote upstreams are favored over |
| 5682 | local upstreams when creating new branches. |
| 5683 | |
| 5684 | When a new branch is created, then the branch, commit, or stash at |
| 5685 | point is suggested as the starting point of the new branch, or if |
| 5686 | there is no such revision at point the current branch. In either |
| 5687 | case the user may choose another starting point. |
| 5688 | |
| 5689 | If the chosen starting point is a branch, then it may also be set |
| 5690 | as the upstream of the new branch, depending on the value of the |
| 5691 | Git variable 'branch.autoSetupMerge'. By default this is done for |
| 5692 | remote branches, but not for local branches. |
| 5693 | |
| 5694 | You might prefer to always use some remote branch as upstream. If |
| 5695 | the chosen starting point is (1) a local branch, (2) whose name |
| 5696 | matches a member of the value of this option, (3) the upstream of |
| 5697 | that local branch is a remote branch with the same name, and (4) |
| 5698 | that remote branch can be fast-forwarded to the local branch, then |
| 5699 | the chosen branch is used as starting point, but its own upstream |
| 5700 | is used as the upstream of the new branch. |
| 5701 | |
| 5702 | Members of this option's value are treated as branch names that |
| 5703 | have to match exactly unless they contain a character that makes |
| 5704 | them invalid as a branch name. Recommended characters to use to |
| 5705 | trigger interpretation as a regexp are "*" and "^". Some other |
| 5706 | characters which you might expect to be invalid, actually are not, |
| 5707 | e.g., ".+$" are all perfectly valid. More precisely, if ‘git |
| 5708 | check-ref-format --branch STRING’ exits with a non-zero status, |
| 5709 | then treat STRING as a regexp. |
| 5710 | |
| 5711 | Assuming the chosen branch matches these conditions you would end |
| 5712 | up with with e.g.: |
| 5713 | |
| 5714 | feature --upstream--> origin/master |
| 5715 | |
| 5716 | instead of |
| 5717 | |
| 5718 | feature --upstream--> master --upstream--> origin/master |
| 5719 | |
| 5720 | Which you prefer is a matter of personal preference. If you do |
| 5721 | prefer the former, then you should add branches such as ‘master’, |
| 5722 | ‘next’, and ‘maint’ to the value of this options. |
| 5723 | |
| 5724 | -- User Option: magit-branch-adjust-remote-upstream-alist |
| 5725 | The value of this option is an alist of branches to be used as the |
| 5726 | upstream when branching a remote branch. |
| 5727 | |
| 5728 | When creating a local branch from an ephemeral branch located on a |
| 5729 | remote, e.g., a feature or hotfix branch, then that remote branch |
| 5730 | should usually not be used as the upstream branch, since the |
| 5731 | push-remote already allows accessing it and having both the |
| 5732 | upstream and the push-remote reference the same related branch |
| 5733 | would be wasteful. Instead a branch like "maint" or "master" |
| 5734 | should be used as the upstream. |
| 5735 | |
| 5736 | This option allows specifying the branch that should be used as the |
| 5737 | upstream when branching certain remote branches. The value is an |
| 5738 | alist of the form ‘((UPSTREAM . RULE)...)’. The first matching |
| 5739 | element is used, the following elements are ignored. |
| 5740 | |
| 5741 | UPSTREAM is the branch to be used as the upstream for branches |
| 5742 | specified by RULE. It can be a local or a remote branch. |
| 5743 | |
| 5744 | RULE can either be a regular expression, matching branches whose |
| 5745 | upstream should be the one specified by UPSTREAM. Or it can be a |
| 5746 | list of the only branches that should *not* use UPSTREAM; all other |
| 5747 | branches will. Matching is done after stripping the remote part of |
| 5748 | the name of the branch that is being branched from. |
| 5749 | |
| 5750 | If you use a finite set of non-ephemeral branches across all your |
| 5751 | repositories, then you might use something like: |
| 5752 | |
| 5753 | (("origin/master" . ("master" "next" "maint"))) |
| 5754 | |
| 5755 | Or if the names of all your ephemeral branches contain a slash, at |
| 5756 | least in some repositories, then a good value could be: |
| 5757 | |
| 5758 | (("origin/master" . "/")) |
| 5759 | |
| 5760 | Of course you can also fine-tune: |
| 5761 | |
| 5762 | (("origin/maint" . "\\`hotfix/") |
| 5763 | ("origin/master" . "\\`feature/")) |
| 5764 | |
| 5765 | UPSTREAM can be a local branch: |
| 5766 | |
| 5767 | (("master" . ("master" "next" "maint"))) |
| 5768 | |
| 5769 | Because the main branch is no longer almost always named "master" you |
| 5770 | should also account for other common names: |
| 5771 | |
| 5772 | (("main" . ("main" "master" "next" "maint")) |
| 5773 | ("master" . ("main" "master" "next" "maint"))) |
| 5774 | |
| 5775 | -- Command: magit-branch-orphan |
| 5776 | This command creates and checks out a new orphan branch with |
| 5777 | contents from a given revision. |
| 5778 | |
| 5779 | -- Command: magit-branch-or-checkout |
| 5780 | This command is a hybrid between ‘magit-checkout’ and |
| 5781 | ‘magit-branch-and-checkout’ and is intended as a replacement for |
| 5782 | the former in ‘magit-branch’. |
| 5783 | |
| 5784 | It first asks the user for an existing branch or revision. If the |
| 5785 | user input actually can be resolved as a branch or revision, then |
| 5786 | it checks that out, just like ‘magit-checkout’ would. |
| 5787 | |
| 5788 | Otherwise it creates and checks out a new branch using the input as |
| 5789 | its name. Before doing so it reads the starting-point for the new |
| 5790 | branch. This is similar to what ‘magit-branch-and-checkout’ does. |
| 5791 | |
| 5792 | To use this command instead of ‘magit-checkout’ add this to your |
| 5793 | init file: |
| 5794 | |
| 5795 | (transient-replace-suffix 'magit-branch 'magit-checkout |
| 5796 | '("b" "dwim" magit-branch-or-checkout)) |
| 5797 | |
| 5798 | 6.6.3 Branch Git Variables |
| 5799 | -------------------------- |
| 5800 | |
| 5801 | These variables can be set from the transient prefix command |
| 5802 | ‘magit-branch-configure’. By default they can also be set from |
| 5803 | ‘magit-branch’. See *note Branch Commands::. |
| 5804 | |
| 5805 | -- Variable: branch.NAME.merge |
| 5806 | Together with ‘branch.NAME.remote’ this variable defines the |
| 5807 | upstream branch of the local branch named NAME. The value of this |
| 5808 | variable is the full reference of the upstream _branch_. |
| 5809 | |
| 5810 | -- Variable: branch.NAME.remote |
| 5811 | Together with ‘branch.NAME.merge’ this variable defines the |
| 5812 | upstream branch of the local branch named NAME. The value of this |
| 5813 | variable is the name of the upstream _remote_. |
| 5814 | |
| 5815 | -- Variable: branch.NAME.rebase |
| 5816 | This variable controls whether pulling into the branch named NAME |
| 5817 | is done by rebasing or by merging the fetched branch. |
| 5818 | |
| 5819 | • When ‘true’ then pulling is done by rebasing. |
| 5820 | • When ‘false’ then pulling is done by merging. |
| 5821 | • When undefined then the value of ‘pull.rebase’ is used. The |
| 5822 | default of that variable is ‘false’. |
| 5823 | |
| 5824 | -- Variable: branch.NAME.pushRemote |
| 5825 | This variable specifies the remote that the branch named NAME is |
| 5826 | usually pushed to. The value has to be the name of an existing |
| 5827 | remote. |
| 5828 | |
| 5829 | It is not possible to specify the name of _branch_ to push the |
| 5830 | local branch to. The name of the remote branch is always the same |
| 5831 | as the name of the local branch. |
| 5832 | |
| 5833 | If this variable is undefined but ‘remote.pushDefault’ is defined, |
| 5834 | then the value of the latter is used. By default |
| 5835 | ‘remote.pushDefault’ is undefined. |
| 5836 | |
| 5837 | -- Variable: branch.NAME.description |
| 5838 | This variable can be used to describe the branch named NAME. That |
| 5839 | description is used, e.g., when turning the branch into a series of |
| 5840 | patches. |
| 5841 | |
| 5842 | The following variables specify defaults which are used if the above |
| 5843 | branch-specific variables are not set. |
| 5844 | |
| 5845 | -- Variable: pull.rebase |
| 5846 | This variable specifies whether pulling is done by rebasing or by |
| 5847 | merging. It can be overwritten using ‘branch.NAME.rebase’. |
| 5848 | |
| 5849 | • When ‘true’ then pulling is done by rebasing. |
| 5850 | • When ‘false’ (the default) then pulling is done by merging. |
| 5851 | |
| 5852 | Since it is never a good idea to merge the upstream branch into a |
| 5853 | feature or hotfix branch and most branches are such branches, you |
| 5854 | should consider setting this to ‘true’, and ‘branch.master.rebase’ |
| 5855 | to ‘false’. |
| 5856 | |
| 5857 | -- Variable: remote.pushDefault |
| 5858 | This variable specifies what remote the local branches are usually |
| 5859 | pushed to. This can be overwritten per branch using |
| 5860 | ‘branch.NAME.pushRemote’. |
| 5861 | |
| 5862 | The following variables are used during the creation of a branch and |
| 5863 | control whether the various branch-specific variables are automatically |
| 5864 | set at this time. |
| 5865 | |
| 5866 | -- Variable: branch.autoSetupMerge |
| 5867 | This variable specifies under what circumstances creating a branch |
| 5868 | NAME should result in the variables ‘branch.NAME.merge’ and |
| 5869 | ‘branch.NAME.remote’ being set according to the starting point used |
| 5870 | to create the branch. If the starting point isn't a branch, then |
| 5871 | these variables are never set. |
| 5872 | |
| 5873 | • When ‘always’ then the variables are set regardless of whether |
| 5874 | the starting point is a local or a remote branch. |
| 5875 | • When ‘true’ (the default) then the variables are set when the |
| 5876 | starting point is a remote branch, but not when it is a local |
| 5877 | branch. |
| 5878 | • When ‘false’ then the variables are never set. |
| 5879 | |
| 5880 | -- Variable: branch.autoSetupRebase |
| 5881 | This variable specifies whether creating a branch NAME should |
| 5882 | result in the variable ‘branch.NAME.rebase’ being set to ‘true’. |
| 5883 | |
| 5884 | • When ‘always’ then the variable is set regardless of whether |
| 5885 | the starting point is a local or a remote branch. |
| 5886 | • When ‘local’ then the variable are set when the starting point |
| 5887 | is a local branch, but not when it is a remote branch. |
| 5888 | • When ‘remote’ then the variable are set when the starting |
| 5889 | point is a remote branch, but not when it is a local branch. |
| 5890 | • When ‘never’ (the default) then the variable is never set. |
| 5891 | |
| 5892 | Note that the respective commands always change the repository-local |
| 5893 | values. If you want to change the global value, which is used when the |
| 5894 | local value is undefined, then you have to do so on the command line, |
| 5895 | e.g.: |
| 5896 | |
| 5897 | git config --global remote.autoSetupMerge always |
| 5898 | |
| 5899 | For more information about these variables you should also see *note |
| 5900 | (gitman)git-config::. Also see *note (gitman)git-branch::. , *note |
| 5901 | (gitman)git-checkout::. and *note Pushing::. |
| 5902 | |
| 5903 | -- User Option: magit-prefer-remote-upstream |
| 5904 | This option controls whether commands that read a branch from the |
| 5905 | user and then set it as the upstream branch, offer a local or a |
| 5906 | remote branch as default completion candidate, when they have the |
| 5907 | choice. |
| 5908 | |
| 5909 | This affects all commands that use ‘magit-read-upstream-branch’ or |
| 5910 | ‘magit-read-starting-point’, which includes all commands that |
| 5911 | change the upstream and many which create new branches. |
| 5912 | |
| 5913 | 6.6.4 Auxiliary Branch Commands |
| 5914 | ------------------------------- |
| 5915 | |
| 5916 | These commands are not available from the transient ‘magit-branch’ by |
| 5917 | default. |
| 5918 | |
| 5919 | -- Command: magit-branch-shelve |
| 5920 | This command shelves a branch. This is done by deleting the |
| 5921 | branch, and creating a new reference "refs/shelved/BRANCH-NAME" |
| 5922 | pointing at the same commit as the branch pointed at. If the |
| 5923 | deleted branch had a reflog, then that is preserved as the reflog |
| 5924 | of the new reference. |
| 5925 | |
| 5926 | This is useful if you want to move a branch out of sight, but are |
| 5927 | not ready to completely discard it yet. |
| 5928 | |
| 5929 | -- Command: magit-branch-unshelve |
| 5930 | This command unshelves a branch that was previously shelved using |
| 5931 | ‘magit-branch-shelve’. This is done by deleting the reference |
| 5932 | "refs/shelved/BRANCH-NAME" and creating a branch "BRANCH-NAME" |
| 5933 | pointing at the same commit as the deleted reference pointed at. |
| 5934 | If the deleted reference had a reflog, then that is restored as the |
| 5935 | reflog of the branch. |
| 5936 | |
| 5937 | |
| 5938 | File: magit.info, Node: Merging, Next: Resolving Conflicts, Prev: Branching, Up: Manipulating |
| 5939 | |
| 5940 | 6.7 Merging |
| 5941 | =========== |
| 5942 | |
| 5943 | Also see *note (gitman)git-merge::. For information on how to resolve |
| 5944 | merge conflicts see the next section. |
| 5945 | |
| 5946 | ‘m’ (‘magit-merge’) |
| 5947 | This transient prefix command binds the following suffix commands |
| 5948 | along with the appropriate infix arguments and displays them in a |
| 5949 | temporary buffer until a suffix is invoked. |
| 5950 | |
| 5951 | When no merge is in progress, then the transient features the |
| 5952 | following suffix commands. |
| 5953 | |
| 5954 | ‘m m’ (‘magit-merge-plain’) |
| 5955 | This command merges another branch or an arbitrary revision into |
| 5956 | the current branch. The branch or revision to be merged is read in |
| 5957 | the minibuffer and defaults to the branch at point. |
| 5958 | |
| 5959 | Unless there are conflicts or a prefix argument is used, then the |
| 5960 | resulting merge commit uses a generic commit message, and the user |
| 5961 | does not get a chance to inspect or change it before the commit is |
| 5962 | created. With a prefix argument this does not actually create the |
| 5963 | merge commit, which makes it possible to inspect how conflicts were |
| 5964 | resolved and to adjust the commit message. |
| 5965 | |
| 5966 | To create an octopus-merge, separate branches with commas. |
| 5967 | |
| 5968 | ‘m e’ (‘magit-merge-editmsg’) |
| 5969 | This command merges another branch or an arbitrary revision into |
| 5970 | the current branch and opens a commit message buffer, so that the |
| 5971 | user can make adjustments. The commit is not actually created |
| 5972 | until the user finishes with ‘C-c C-c’. |
| 5973 | |
| 5974 | To create an octopus-merge, separate branches with commas. |
| 5975 | |
| 5976 | ‘m n’ (‘magit-merge-nocommit’) |
| 5977 | This command merges another branch or an arbitrary revision into |
| 5978 | the current branch, but does not actually create the merge commit. |
| 5979 | The user can then further adjust the merge, even when automatic |
| 5980 | conflict resolution succeeded and/or adjust the commit message. |
| 5981 | |
| 5982 | ‘m a’ (‘magit-merge-absorb’) |
| 5983 | This command merges another local branch into the current branch |
| 5984 | and then removes the former. |
| 5985 | |
| 5986 | Before the source branch is merged, it is first force pushed to its |
| 5987 | push-remote, provided the respective remote branch already exists. |
| 5988 | This ensures that the respective pull-request (if any) won't get |
| 5989 | stuck on some obsolete version of the commits that are being |
| 5990 | merged. Finally, if ‘magit-branch-pull-request’ was used to create |
| 5991 | the merged branch, then the respective remote branch is also |
| 5992 | removed. |
| 5993 | |
| 5994 | To create an octopus-merge, separate branches with commas. |
| 5995 | |
| 5996 | ‘m d’ (‘magit-merge-dissolve’) |
| 5997 | This command merges the current branch into another local branch |
| 5998 | and then removes the former. The latter becomes the new current |
| 5999 | branch. |
| 6000 | |
| 6001 | Before the source branch is merged, it is first force pushed to its |
| 6002 | push-remote, provided the respective remote branch already exists. |
| 6003 | This ensures that the respective pull-request (if any) won't get |
| 6004 | stuck on some obsolete version of the commits that are being |
| 6005 | merged. Finally, if ‘magit-branch-pull-request’ was used to create |
| 6006 | the merged branch, then the respective remote branch is also |
| 6007 | removed. |
| 6008 | |
| 6009 | ‘m s’ (‘magit-merge-squash’) |
| 6010 | This command squashes the changes introduced by another branch or |
| 6011 | an arbitrary revision into the current branch. This only applies |
| 6012 | the changes made by the squashed commits. No information is |
| 6013 | preserved that would allow creating an actual merge commit. |
| 6014 | Instead of this command you should probably use a command from the |
| 6015 | apply transient. |
| 6016 | |
| 6017 | ‘m p’ (‘magit-merge-preview’) |
| 6018 | This command shows a preview of merging another branch or an |
| 6019 | arbitrary revision into the current branch. |
| 6020 | |
| 6021 | Note that commands, that normally change how a diff is displayed, |
| 6022 | do not work in buffers created by this command, because the |
| 6023 | underlying Git command does not support diff arguments. |
| 6024 | |
| 6025 | When a merge is in progress, then the transient instead features the |
| 6026 | following suffix commands. |
| 6027 | |
| 6028 | ‘m m’ (‘magit-merge’) |
| 6029 | After the user resolved conflicts, this command proceeds with the |
| 6030 | merge. If some conflicts weren't resolved, then this command |
| 6031 | fails. |
| 6032 | |
| 6033 | ‘m a’ (‘magit-merge-abort’) |
| 6034 | This command aborts the current merge operation. |
| 6035 | |
| 6036 | |
| 6037 | File: magit.info, Node: Resolving Conflicts, Next: Rebasing, Prev: Merging, Up: Manipulating |
| 6038 | |
| 6039 | 6.8 Resolving Conflicts |
| 6040 | ======================= |
| 6041 | |
| 6042 | When merging branches (or otherwise combining or changing history) |
| 6043 | conflicts can occur. If you edited two completely different parts of |
| 6044 | the same file in two branches and then merge one of these branches into |
| 6045 | the other, then Git can resolve that on its own, but if you edit the |
| 6046 | same area of a file, then a human is required to decide how the two |
| 6047 | versions, or "sides of the conflict", are to be combined into one. |
| 6048 | |
| 6049 | Here we can only provide a brief introduction to the subject and |
| 6050 | point you toward some tools that can help. If you are new to this, then |
| 6051 | please also consult Git's own documentation as well as other resources. |
| 6052 | |
| 6053 | If a file has conflicts and Git cannot resolve them by itself, then |
| 6054 | it puts both versions into the affected file along with special markers |
| 6055 | whose purpose is to denote the boundaries of the unresolved part of the |
| 6056 | file and between the different versions. These boundary lines begin |
| 6057 | with the strings consisting of seven times the same character, one of |
| 6058 | ‘<’, ‘|’, ‘=’ and ‘>’, and are followed by information about the source |
| 6059 | of the respective versions, e.g.: |
| 6060 | |
| 6061 | <<<<<<< HEAD |
| 6062 | Take the blue pill. |
| 6063 | ======= |
| 6064 | Take the red pill. |
| 6065 | >>>>>>> feature |
| 6066 | |
| 6067 | In this case you have chosen to take the red pill on one branch and |
| 6068 | on another you picked the blue pill. Now that you are merging these two |
| 6069 | diverging branches, Git cannot possibly know which pill you want to |
| 6070 | take. |
| 6071 | |
| 6072 | To resolve that conflict you have to create a version of the affected |
| 6073 | area of the file by keeping only one of the sides, possibly by editing |
| 6074 | it in order to bring in the changes from the other side, remove the |
| 6075 | other versions as well as the markers, and then stage the result. A |
| 6076 | possible resolution might be: |
| 6077 | |
| 6078 | Take both pills. |
| 6079 | |
| 6080 | Often it is useful to see not only the two sides of the conflict but |
| 6081 | also the "original" version from before the same area of the file was |
| 6082 | modified twice on different branches. Instruct Git to insert that |
| 6083 | version as well by running this command once: |
| 6084 | |
| 6085 | git config --global merge.conflictStyle diff3 |
| 6086 | |
| 6087 | The above conflict might then have looked like this: |
| 6088 | |
| 6089 | <<<<<<< HEAD |
| 6090 | Take the blue pill. |
| 6091 | ||||||| merged common ancestors |
| 6092 | Take either the blue or the red pill, but not both. |
| 6093 | ======= |
| 6094 | Take the red pill. |
| 6095 | >>>>>>> feature |
| 6096 | |
| 6097 | If that were the case, then the above conflict resolution would not |
| 6098 | have been correct, which demonstrates why seeing the original version |
| 6099 | alongside the conflicting versions can be useful. |
| 6100 | |
| 6101 | You can perform the conflict resolution completely by hand, but Emacs |
| 6102 | also provides some packages that help in the process: Smerge, Ediff |
| 6103 | (*note (ediff)Top::), and Emerge (*note (emacs)Emerge::). Magit does |
| 6104 | not provide its own tools for conflict resolution, but it does make |
| 6105 | using Smerge and Ediff more convenient. (Ediff supersedes Emerge, so |
| 6106 | you probably don't want to use the latter anyway.) |
| 6107 | |
| 6108 | In the Magit status buffer, files with unresolved conflicts are |
| 6109 | listed in the "Unstaged changes" and/or "Staged changes" sections. They |
| 6110 | are prefixed with the word "unmerged", which in this context essentially |
| 6111 | is a synonym for "unresolved". |
| 6112 | |
| 6113 | Pressing ‘RET’ while point is on such a file section shows a buffer |
| 6114 | visiting that file, turns on ‘smerge-mode’ in that buffer, and places |
| 6115 | point inside the first area with conflicts. You should then resolve |
| 6116 | that conflict using regular edit commands and/or Smerge commands. |
| 6117 | |
| 6118 | Unfortunately Smerge does not have a manual, but you can get a list |
| 6119 | of commands and binding ‘C-c ^ C-h’ and press ‘RET’ while point is on a |
| 6120 | command name to read its documentation. |
| 6121 | |
| 6122 | Normally you would edit one version and then tell Smerge to keep only |
| 6123 | that version. Use ‘C-c ^ m’ (‘smerge-keep-mine’) to keep the ‘HEAD’ |
| 6124 | version or ‘C-c ^ o’ (‘smerge-keep-other’) to keep the version that |
| 6125 | follows "|||||||". Then use ‘C-c ^ n’ to move to the next conflicting |
| 6126 | area in the same file. Once you are done resolving conflicts, return to |
| 6127 | the Magit status buffer. The file should now be shown as "modified", no |
| 6128 | longer as "unmerged", because Smerge automatically stages the file when |
| 6129 | you save the buffer after resolving the last conflict. |
| 6130 | |
| 6131 | Magit now wraps the mentioned Smerge commands, allowing you to use |
| 6132 | these key bindings without having to go to the file-visiting buffer. |
| 6133 | Additionally ‘k’ (‘magit-discard’) on a hunk with unresolved conflicts |
| 6134 | asks which side to keep or, if point is on a side, then it keeps it |
| 6135 | without prompting. Similarly ‘k’ on a unresolved file ask which side to |
| 6136 | keep. |
| 6137 | |
| 6138 | Alternatively you could use Ediff, which uses separate buffers for |
| 6139 | the different versions of the file. To resolve conflicts in a file |
| 6140 | using Ediff press ‘e’ while point is on such a file in the status |
| 6141 | buffer. |
| 6142 | |
| 6143 | Ediff can be used for other purposes as well. For more information |
| 6144 | on how to enter Ediff from Magit, see *note Ediffing::. Explaining how |
| 6145 | to use Ediff is beyond the scope of this manual, instead see *note |
| 6146 | (ediff)Top::. |
| 6147 | |
| 6148 | If you are unsure whether you should Smerge or Ediff, then use the |
| 6149 | former. It is much easier to understand and use, and except for truly |
| 6150 | complex conflicts, the latter is usually overkill. |
| 6151 | |
| 6152 | |
| 6153 | File: magit.info, Node: Rebasing, Next: Cherry Picking, Prev: Resolving Conflicts, Up: Manipulating |
| 6154 | |
| 6155 | 6.9 Rebasing |
| 6156 | ============ |
| 6157 | |
| 6158 | Also see *note (gitman)git-rebase::. For information on how to resolve |
| 6159 | conflicts that occur during rebases see the preceding section. |
| 6160 | |
| 6161 | ‘r’ (‘magit-rebase’) |
| 6162 | This transient prefix command binds the following suffix commands |
| 6163 | along with the appropriate infix arguments and displays them in a |
| 6164 | temporary buffer until a suffix is invoked. |
| 6165 | |
| 6166 | When no rebase is in progress, then the transient features the |
| 6167 | following suffix commands. |
| 6168 | |
| 6169 | Using one of these commands _starts_ a rebase sequence. Git might |
| 6170 | then stop somewhere along the way, either because you told it to do so, |
| 6171 | or because applying a commit failed due to a conflict. When that |
| 6172 | happens, then the status buffer shows information about the rebase |
| 6173 | sequence which is in progress in a section similar to a log section. |
| 6174 | See *note Information About In-Progress Rebase::. |
| 6175 | |
| 6176 | For information about the upstream and the push-remote, see *note The |
| 6177 | Two Remotes::. |
| 6178 | |
| 6179 | ‘r p’ (‘magit-rebase-onto-pushremote’) |
| 6180 | This command rebases the current branch onto its push-remote. |
| 6181 | |
| 6182 | With a prefix argument or when the push-remote is either not |
| 6183 | configured or unusable, then let the user first configure the |
| 6184 | push-remote. |
| 6185 | |
| 6186 | ‘r u’ (‘magit-rebase-onto-upstream’) |
| 6187 | This command rebases the current branch onto its upstream branch. |
| 6188 | |
| 6189 | With a prefix argument or when the upstream is either not |
| 6190 | configured or unusable, then let the user first configure the |
| 6191 | upstream. |
| 6192 | |
| 6193 | ‘r e’ (‘magit-rebase-branch’) |
| 6194 | This command rebases the current branch onto a branch read in the |
| 6195 | minibuffer. All commits that are reachable from head but not from |
| 6196 | the selected branch TARGET are being rebased. |
| 6197 | |
| 6198 | ‘r s’ (‘magit-rebase-subset’) |
| 6199 | This command starts a non-interactive rebase sequence to transfer |
| 6200 | commits from START to ‘HEAD’ onto NEWBASE. START has to be |
| 6201 | selected from a list of recent commits. |
| 6202 | |
| 6203 | This command calls ‘git rebase --onto NEWBASE START HEAD’. Because |
| 6204 | the range always ends at ‘HEAD’, you must first check out the |
| 6205 | branch or commit you want as the upper bound (a detached ‘HEAD’ |
| 6206 | works too). |
| 6207 | |
| 6208 | By default Magit uses the ‘--autostash’ argument, which causes |
| 6209 | uncommitted changes to be stored in a stash before the rebase begins. |
| 6210 | These changes are restored after the rebase completes and if possible |
| 6211 | the stash is removed. If the stash does not apply cleanly, then the |
| 6212 | stash is not removed. In case something goes wrong when resolving the |
| 6213 | conflicts, this allows you to start over. |
| 6214 | |
| 6215 | Even though one of the actions is dedicated to interactive rebases, |
| 6216 | the transient also features the infix argument ‘--interactive’. This |
| 6217 | can be used to turn one of the other, non-interactive rebase variants |
| 6218 | into an interactive rebase. |
| 6219 | |
| 6220 | For example if you want to clean up a feature branch and at the same |
| 6221 | time rebase it onto ‘master’, then you could use ‘r-iu’. But we |
| 6222 | recommend that you instead do that in two steps. First use ‘ri’ to |
| 6223 | cleanup the feature branch, and then in a second step ‘ru’ to rebase it |
| 6224 | onto ‘master’. That way if things turn out to be more complicated than |
| 6225 | you thought and/or you make a mistake and have to start over, then you |
| 6226 | only have to redo half the work. |
| 6227 | |
| 6228 | Explicitly enabling ‘--interactive’ won't have an effect on the |
| 6229 | following commands as they always use that argument anyway, even if it |
| 6230 | is not enabled in the transient. |
| 6231 | |
| 6232 | ‘r i’ (‘magit-rebase-interactive’) |
| 6233 | This command starts an interactive rebase sequence. |
| 6234 | |
| 6235 | ‘r f’ (‘magit-rebase-autosquash’) |
| 6236 | This command combines squash and fixup commits with their intended |
| 6237 | targets. |
| 6238 | |
| 6239 | By default only commits that are not reachable from the upstream |
| 6240 | branch are potentially squashed into. If no upstream is configured |
| 6241 | or with a prefix argument, the user is prompted for the first |
| 6242 | commit to potentially squash into. |
| 6243 | |
| 6244 | ‘r m’ (‘magit-rebase-edit-commit’) |
| 6245 | This command starts an interactive rebase sequence that lets the |
| 6246 | user edit a single older commit. |
| 6247 | |
| 6248 | ‘r w’ (‘magit-rebase-reword-commit’) |
| 6249 | This command starts an interactive rebase sequence that lets the |
| 6250 | user reword a single older commit. |
| 6251 | |
| 6252 | ‘r k’ (‘magit-rebase-remove-commit’) |
| 6253 | This command removes a single older commit using rebase. |
| 6254 | |
| 6255 | When a rebase is in progress, then the transient instead features the |
| 6256 | following suffix commands. |
| 6257 | |
| 6258 | ‘r r’ (‘magit-rebase-continue’) |
| 6259 | This command restart the current rebasing operation. |
| 6260 | |
| 6261 | In some cases this pops up a commit message buffer for you do edit. |
| 6262 | With a prefix argument the old message is reused as-is. |
| 6263 | |
| 6264 | ‘r s’ (‘magit-rebase-skip’) |
| 6265 | This command skips the current commit and restarts the current |
| 6266 | rebase operation. |
| 6267 | |
| 6268 | ‘r e’ (‘magit-rebase-edit’) |
| 6269 | This command lets the user edit the todo list of the current rebase |
| 6270 | operation. |
| 6271 | |
| 6272 | ‘r a’ (‘magit-rebase-abort’) |
| 6273 | This command aborts the current rebase operation, restoring the |
| 6274 | original branch. |
| 6275 | |
| 6276 | 6.9.1 Editing Rebase Sequences |
| 6277 | ------------------------------ |
| 6278 | |
| 6279 | ‘C-c C-c’ (‘with-editor-finish’) |
| 6280 | Finish the current editing session by returning with exit code 0. |
| 6281 | Git then uses the rebase instructions it finds in the file. |
| 6282 | |
| 6283 | ‘C-c C-k’ (‘with-editor-cancel’) |
| 6284 | Cancel the current editing session by returning with exit code 1. |
| 6285 | Git then forgoes starting the rebase sequence. |
| 6286 | |
| 6287 | ‘<RET>’ (‘git-rebase-show-commit’) |
| 6288 | Show the commit on the current line in another buffer and select |
| 6289 | that buffer. |
| 6290 | |
| 6291 | ‘<SPC>’ (‘git-rebase-show-or-scroll-up’) |
| 6292 | Show the commit on the current line in another buffer without |
| 6293 | selecting that buffer. If the revision buffer is already visible |
| 6294 | in another window of the current frame, then instead scroll that |
| 6295 | window up. |
| 6296 | |
| 6297 | ‘<DEL>’ (‘git-rebase-show-or-scroll-down’) |
| 6298 | Show the commit on the current line in another buffer without |
| 6299 | selecting that buffer. If the revision buffer is already visible |
| 6300 | in another window of the current frame, then instead scroll that |
| 6301 | window down. |
| 6302 | |
| 6303 | ‘p’ (‘git-rebase-backward-line’) |
| 6304 | Move to previous line. |
| 6305 | |
| 6306 | ‘n’ (‘forward-line’) |
| 6307 | Move to next line. |
| 6308 | |
| 6309 | ‘M-p’ (‘git-rebase-move-line-up’) |
| 6310 | Move the current commit (or command) up. |
| 6311 | |
| 6312 | ‘M-n’ (‘git-rebase-move-line-down’) |
| 6313 | Move the current commit (or command) down. |
| 6314 | |
| 6315 | ‘r’ (‘git-rebase-reword’) |
| 6316 | Edit message of commit on current line. |
| 6317 | |
| 6318 | ‘e’ (‘git-rebase-edit’) |
| 6319 | Stop at the commit on the current line. |
| 6320 | |
| 6321 | ‘s’ (‘git-rebase-squash’) |
| 6322 | This command folds the commit on the current line into the previous |
| 6323 | commit, giving the user a change to manually merge the two |
| 6324 | messages. |
| 6325 | |
| 6326 | ‘S’ (‘git-rebase-squish’) |
| 6327 | This command folds the commit on the current line into the previous |
| 6328 | commit, discarding the message of the previous commit but giving |
| 6329 | the user a change to edit the final message, based on the message |
| 6330 | of the current commit. |
| 6331 | |
| 6332 | This action's indicator, shown in the list of commits, is ‘fixup |
| 6333 | -c’ (with a lower-case c). |
| 6334 | |
| 6335 | ‘f’ (‘git-rebase-fixup’) |
| 6336 | This command folds the commit on the current line into the previous |
| 6337 | commit, using only the message of the previous commit as-is and |
| 6338 | discarding the message of the current commit. |
| 6339 | |
| 6340 | ‘F’ (‘git-rebase-alter’) |
| 6341 | This command folds the commit on the current into the previous |
| 6342 | commit, discarding the message of the previous commit and instead |
| 6343 | using the message of the current commit as-is. |
| 6344 | |
| 6345 | This is like ‘git-rebase-alter’, except that it uses the other |
| 6346 | message. This is also like ‘git-rebase-squish’, except that it |
| 6347 | lets the user edit the message. |
| 6348 | |
| 6349 | This action's indicator, shown in the list of commits, is ‘fixup |
| 6350 | -C’ (with a upper-case C). |
| 6351 | |
| 6352 | ‘k’ (‘git-rebase-kill-line’) |
| 6353 | Comment the current action line, or if it is already commented, |
| 6354 | then uncomment it. |
| 6355 | |
| 6356 | ‘c’ (‘git-rebase-pick’) |
| 6357 | Use commit on current line. |
| 6358 | |
| 6359 | ‘x’ (‘git-rebase-exec’) |
| 6360 | Insert a shell command to be run after the proceeding commit. |
| 6361 | |
| 6362 | If there already is such a command on the current line, then edit |
| 6363 | that instead. With a prefix argument insert a new command even |
| 6364 | when there already is one on the current line. With empty input |
| 6365 | remove the command on the current line, if any. |
| 6366 | |
| 6367 | ‘b’ (‘git-rebase-break’) |
| 6368 | Insert a break action before the current line, instructing Git to |
| 6369 | return control to the user. |
| 6370 | |
| 6371 | ‘y’ (‘git-rebase-insert’) |
| 6372 | Read an arbitrary commit and insert it below current line. |
| 6373 | |
| 6374 | ‘C-x u’ (‘git-rebase-undo’) |
| 6375 | Undo some previous changes. Like ‘undo’ but works in read-only |
| 6376 | buffers. |
| 6377 | |
| 6378 | -- User Option: git-rebase-auto-advance |
| 6379 | Whether to move to next line after changing a line. |
| 6380 | |
| 6381 | -- User Option: git-rebase-show-instructions |
| 6382 | Whether to show usage instructions inside the rebase buffer. |
| 6383 | |
| 6384 | -- User Option: git-rebase-confirm-cancel |
| 6385 | Whether confirmation is required to cancel. |
| 6386 | |
| 6387 | When a rebase is performed with the ‘--rebase-merges’ option, the |
| 6388 | sequence will include a few other types of actions and the following |
| 6389 | commands become relevant. |
| 6390 | |
| 6391 | ‘l’ (‘git-rebase-label’) |
| 6392 | This commands inserts a label action or edits the one at point. |
| 6393 | |
| 6394 | ‘t’ (‘git-rebase-reset’) |
| 6395 | This command inserts a reset action or edits the one at point. The |
| 6396 | prompt will offer the labels that are currently present in the |
| 6397 | buffer. |
| 6398 | |
| 6399 | ‘MM’ (‘git-rebase-merge’) |
| 6400 | The command inserts a merge action or edits the one at point. The |
| 6401 | prompt will offer the labels that are currently present in the |
| 6402 | buffer. Specifying a message to reuse via ‘-c’ or ‘-C’ is not |
| 6403 | supported; an editor will always be invoked for the merge. |
| 6404 | |
| 6405 | ‘Mt’ (‘git-rebase-merge-toggle-editmsg’) |
| 6406 | This command toggles between the ‘-C’ and ‘-c’ options of the merge |
| 6407 | action at point. These options both specify a commit whose message |
| 6408 | should be reused. The lower-case variant instructs Git to invoke |
| 6409 | the editor when creating the merge, allowing the user to edit the |
| 6410 | message. |
| 6411 | |
| 6412 | 6.9.2 Information About In-Progress Rebase |
| 6413 | ------------------------------------------ |
| 6414 | |
| 6415 | While a rebase sequence is in progress, the status buffer features a |
| 6416 | section that lists the commits that have already been applied as well as |
| 6417 | the commits that still have to be applied. |
| 6418 | |
| 6419 | The commits are split in two halves. When rebase stops at a commit, |
| 6420 | either because the user has to deal with a conflict or because s/he |
| 6421 | explicitly requested that rebase stops at that commit, then point is |
| 6422 | placed on the commit that separates the two groups, i.e., on ‘HEAD’. |
| 6423 | The commits above it have not been applied yet, while the ‘HEAD’ and the |
| 6424 | commits below it have already been applied. In between these two groups |
| 6425 | of applied and yet-to-be applied commits, there sometimes is a commit |
| 6426 | which has been dropped. |
| 6427 | |
| 6428 | Each commit is prefixed with a word and these words are additionally |
| 6429 | shown in different colors to indicate the status of the commits. |
| 6430 | |
| 6431 | The following colors are used: |
| 6432 | |
| 6433 | • Commits that use the same foreground color as the ‘default’ face |
| 6434 | have not been applied yet. |
| 6435 | |
| 6436 | • Yellow commits have some special relationship to the commit rebase |
| 6437 | stopped at. This is used for the words "join", "goal", "same" and |
| 6438 | "work" (see below). |
| 6439 | |
| 6440 | • Gray commits have already been applied. |
| 6441 | |
| 6442 | • The blue commit is the ‘HEAD’ commit. |
| 6443 | |
| 6444 | • The green commit is the commit the rebase sequence stopped at. If |
| 6445 | this is the same commit as ‘HEAD’ (e.g., because you haven't done |
| 6446 | anything yet after rebase stopped at the commit, then this commit |
| 6447 | is shown in blue, not green). There can only be a green *and* a |
| 6448 | blue commit at the same time, if you create one or more new commits |
| 6449 | after rebase stops at a commit. |
| 6450 | |
| 6451 | • Red commits have been dropped. They are shown for reference only, |
| 6452 | e.g., to make it easier to diff. |
| 6453 | |
| 6454 | Of course these colors are subject to the color-theme in use. |
| 6455 | |
| 6456 | The following words are used: |
| 6457 | |
| 6458 | • Commits prefixed with ‘pick’, ‘reword’, ‘edit’, ‘squash’, and |
| 6459 | ‘fixup’ have not been applied yet. These words have the same |
| 6460 | meaning here as they do in the buffer used to edit the rebase |
| 6461 | sequence. See *note Editing Rebase Sequences::. When the |
| 6462 | ‘--rebase-merges’ option was specified, ‘reset’, ‘label’, and |
| 6463 | ‘merge’ lines may also be present. |
| 6464 | |
| 6465 | • Commits prefixed with ‘done’ and ‘onto’ have already been applied. |
| 6466 | It is possible for such a commit to be the ‘HEAD’, in which case it |
| 6467 | is blue. Otherwise it is grey. |
| 6468 | |
| 6469 | • The commit prefixed with ‘onto’ is the commit on top of which |
| 6470 | all the other commits are being re-applied. This commit |
| 6471 | itself did not have to be re-applied, it is the commit rebase |
| 6472 | did rewind to before starting to re-apply other commits. |
| 6473 | |
| 6474 | • Commits prefixed with ‘done’ have already been re-applied. |
| 6475 | This includes commits that have been re-applied but also new |
| 6476 | commits that you have created during the rebase. |
| 6477 | |
| 6478 | • All other commits, those not prefixed with any of the above words, |
| 6479 | are in some way related to the commit at which rebase stopped. |
| 6480 | |
| 6481 | To determine whether a commit is related to the stopped-at commit |
| 6482 | their hashes, trees and patch-ids (1) are being compared. The |
| 6483 | commit message is not used for this purpose. |
| 6484 | |
| 6485 | Generally speaking commits that are related to the stopped-at |
| 6486 | commit can have any of the used colors, though not all color/word |
| 6487 | combinations are possible. |
| 6488 | |
| 6489 | Words used for stopped-at commits are: |
| 6490 | |
| 6491 | • When a commit is prefixed with ‘void’, then that indicates |
| 6492 | that Magit knows for sure that all the changes in that commit |
| 6493 | have been applied using several new commits. This commit is |
| 6494 | no longer reachable from ‘HEAD’, and it also isn't one of the |
| 6495 | commits that will be applied when resuming the session. |
| 6496 | |
| 6497 | • When a commit is prefixed with ‘join’, then that indicates |
| 6498 | that the rebase sequence stopped at that commit due to a |
| 6499 | conflict - you now have to join (merge) the changes with what |
| 6500 | has already been applied. In a sense this is the commit |
| 6501 | rebase stopped at, but while its effect is already in the |
| 6502 | index and in the worktree (with conflict markers), the commit |
| 6503 | itself has not actually been applied yet (it isn't the |
| 6504 | ‘HEAD’). So it is shown in yellow, like the other commits |
| 6505 | that still have to be applied. |
| 6506 | |
| 6507 | • When a commit is prefixed with ‘stop’ or a _blue_ or _green_ |
| 6508 | ‘same’, then that indicates that rebase stopped at this |
| 6509 | commit, that it is still applied or has been applied again, |
| 6510 | and that at least its patch-id is unchanged. |
| 6511 | |
| 6512 | • When a commit is prefixed with ‘stop’, then that |
| 6513 | indicates that rebase stopped at that commit because you |
| 6514 | requested that earlier, and its patch-id is unchanged. |
| 6515 | It might even still be the exact same commit. |
| 6516 | |
| 6517 | • When a commit is prefixed with a _blue_ or _green_ |
| 6518 | ‘same’, then that indicates that while its tree or hash |
| 6519 | changed, its patch-id did not. If it is blue, then it is |
| 6520 | the ‘HEAD’ commit (as always for blue). When it is |
| 6521 | green, then it no longer is ‘HEAD’ because other commit |
| 6522 | have been created since (but before continuing the |
| 6523 | rebase). |
| 6524 | |
| 6525 | • When a commit is prefixed with ‘goal’, a _yellow_ ‘same,’ or |
| 6526 | ‘work’, then that indicates that rebase applied that commit |
| 6527 | but that you then reset ‘HEAD’ to an earlier commit (likely to |
| 6528 | split it up into multiple commits), and that there are some |
| 6529 | uncommitted changes remaining which likely (but not |
| 6530 | necessarily) originate from that commit. |
| 6531 | |
| 6532 | • When a commit is prefixed with ‘goal’, then that |
| 6533 | indicates that it is still possible to create a new |
| 6534 | commit with the exact same tree (the "goal") without |
| 6535 | manually editing any files, by committing the index, or |
| 6536 | by staging all changes and then committing that. This is |
| 6537 | the case when the original tree still exists in the index |
| 6538 | or worktree in untainted form. |
| 6539 | |
| 6540 | • When a commit is prefixed with a yellow ‘same’, then that |
| 6541 | indicates that it is no longer possible to create a |
| 6542 | commit with the exact same tree, but that it is still |
| 6543 | possible to create a commit with the same patch-id. This |
| 6544 | would be the case if you created a new commit with other |
| 6545 | changes, but the changes from the original commit still |
| 6546 | exist in the index or working tree in untainted form. |
| 6547 | |
| 6548 | • When a commit is prefixed with ‘work’, then that |
| 6549 | indicates that you reset ‘HEAD’ to an earlier commit, and |
| 6550 | that there are some staged and/or unstaged changes |
| 6551 | (likely, but not necessarily) originating from that |
| 6552 | commit. However it is no longer possible to create a new |
| 6553 | commit with the same tree or at least the same patch-id |
| 6554 | because you have already made other changes. |
| 6555 | |
| 6556 | • When a commit is prefixed with ‘poof’ or ‘gone’, then that |
| 6557 | indicates that rebase applied that commit but that you then |
| 6558 | reset ‘HEAD’ to an earlier commit (likely to split it up into |
| 6559 | multiple commits), and that there are no uncommitted changes. |
| 6560 | |
| 6561 | • When a commit is prefixed with ‘poof’, then that |
| 6562 | indicates that it is no longer reachable from ‘HEAD’, but |
| 6563 | that it has been replaced with one or more commits, which |
| 6564 | together have the exact same effect. |
| 6565 | |
| 6566 | • When a commit is prefixed with ‘gone’, then that |
| 6567 | indicates that it is no longer reachable from ‘HEAD’ and |
| 6568 | that we also cannot determine whether its changes are |
| 6569 | still in effect in one or more new commits. They might |
| 6570 | be, but if so, then there must also be other changes |
| 6571 | which makes it impossible to know for sure. |
| 6572 | |
| 6573 | Do not worry if you do not fully understand the above. That's okay, |
| 6574 | you will acquire a good enough understanding through practice. |
| 6575 | |
| 6576 | For other sequence operations such as cherry-picking, a similar |
| 6577 | section is displayed, but they lack some of the features described |
| 6578 | above, due to limitations in the git commands used to implement them. |
| 6579 | Most importantly these sequences only support "picking" a commit but not |
| 6580 | other actions such as "rewording", and they do not keep track of the |
| 6581 | commits which have already been applied. |
| 6582 | |
| 6583 | ---------- Footnotes ---------- |
| 6584 | |
| 6585 | (1) The patch-id is a hash of the _changes_ introduced by a commit. |
| 6586 | It differs from the hash of the commit itself, which is a hash of the |
| 6587 | result of applying that change (i.e., the resulting trees and blobs) as |
| 6588 | well as author and committer information, the commit message, and the |
| 6589 | hashes of the parents of the commit. The patch-id hash on the other |
| 6590 | hand is created only from the added and removed lines, even line numbers |
| 6591 | and whitespace changes are ignored when calculating this hash. The |
| 6592 | patch-ids of two commits can be used to answer the question "Do these |
| 6593 | commits make the same change?". |
| 6594 | |
| 6595 | |
| 6596 | File: magit.info, Node: Cherry Picking, Next: Resetting, Prev: Rebasing, Up: Manipulating |
| 6597 | |
| 6598 | 6.10 Cherry Picking |
| 6599 | =================== |
| 6600 | |
| 6601 | Also see *note (gitman)git-cherry-pick::. |
| 6602 | |
| 6603 | ‘A’ (‘magit-cherry-pick’) |
| 6604 | This transient prefix command binds the following suffix commands |
| 6605 | along with the appropriate infix arguments and displays them in a |
| 6606 | temporary buffer until a suffix is invoked. |
| 6607 | |
| 6608 | When no cherry-pick or revert is in progress, then the transient |
| 6609 | features the following suffix commands. |
| 6610 | |
| 6611 | ‘A A’ (‘magit-cherry-copy’) |
| 6612 | This command copies COMMITS from another branch onto the current |
| 6613 | branch. If the region selects multiple commits, then those are |
| 6614 | copied, without prompting. Otherwise the user is prompted for a |
| 6615 | commit or range, defaulting to the commit at point. |
| 6616 | |
| 6617 | ‘A a’ (‘magit-cherry-apply’) |
| 6618 | This command applies the changes in COMMITS from another branch |
| 6619 | onto the current branch. If the region selects multiple commits, |
| 6620 | then those are used, without prompting. Otherwise the user is |
| 6621 | prompted for a commit or range, defaulting to the commit at point. |
| 6622 | |
| 6623 | This command also has a top-level binding, which can be invoked |
| 6624 | without using the transient by typing ‘a’ at the top-level. |
| 6625 | |
| 6626 | The following commands not only apply some commits to some branch, |
| 6627 | but also remove them from some other branch. The removal is performed |
| 6628 | using either ‘git-update-ref’ or if necessary ‘git-rebase’. Both |
| 6629 | applying commits as well as removing them using ‘git-rebase’ can lead to |
| 6630 | conflicts. If that happens, then these commands abort and you not only |
| 6631 | have to resolve the conflicts but also finish the process the same way |
| 6632 | you would have to if these commands didn't exist at all. |
| 6633 | |
| 6634 | ‘A h’ (‘magit-cherry-harvest’) |
| 6635 | This command moves the selected COMMITS that must be located on |
| 6636 | another BRANCH onto the current branch instead, removing them from |
| 6637 | the former. When this command succeeds, then the same branch is |
| 6638 | current as before. |
| 6639 | |
| 6640 | Applying the commits on the current branch or removing them from |
| 6641 | the other branch can lead to conflicts. When that happens, then |
| 6642 | this command stops and you have to resolve the conflicts and then |
| 6643 | finish the process manually. |
| 6644 | |
| 6645 | ‘A d’ (‘magit-cherry-donate’) |
| 6646 | This command moves the selected COMMITS from the current branch |
| 6647 | onto another existing BRANCH, removing them from the former. When |
| 6648 | this command succeeds, then the same branch is current as before. |
| 6649 | ‘HEAD’ is allowed to be detached initially. |
| 6650 | |
| 6651 | Applying the commits on the other branch or removing them from the |
| 6652 | current branch can lead to conflicts. When that happens, then this |
| 6653 | command stops and you have to resolve the conflicts and then finish |
| 6654 | the process manually. |
| 6655 | |
| 6656 | ‘A n’ (‘magit-cherry-spinout’) |
| 6657 | This command moves the selected COMMITS from the current branch |
| 6658 | onto a new branch BRANCH, removing them from the former. When this |
| 6659 | command succeeds, then the same branch is current as before. |
| 6660 | |
| 6661 | Applying the commits on the other branch or removing them from the |
| 6662 | current branch can lead to conflicts. When that happens, then this |
| 6663 | command stops and you have to resolve the conflicts and then finish |
| 6664 | the process manually. |
| 6665 | |
| 6666 | ‘A s’ (‘magit-cherry-spinoff’) |
| 6667 | This command moves the selected COMMITS from the current branch |
| 6668 | onto a new branch BRANCH, removing them from the former. When this |
| 6669 | command succeeds, then the new branch is checked out. |
| 6670 | |
| 6671 | Applying the commits on the other branch or removing them from the |
| 6672 | current branch can lead to conflicts. When that happens, then this |
| 6673 | command stops and you have to resolve the conflicts and then finish |
| 6674 | the process manually. |
| 6675 | |
| 6676 | When a cherry-pick or revert is in progress, then the transient |
| 6677 | instead features the following suffix commands. |
| 6678 | |
| 6679 | ‘A A’ (‘magit-sequence-continue’) |
| 6680 | Resume the current cherry-pick or revert sequence. |
| 6681 | |
| 6682 | ‘A s’ (‘magit-sequence-skip’) |
| 6683 | Skip the stopped at commit during a cherry-pick or revert sequence. |
| 6684 | |
| 6685 | ‘A a’ (‘magit-sequence-abort’) |
| 6686 | Abort the current cherry-pick or revert sequence. This discards |
| 6687 | all changes made since the sequence started. |
| 6688 | |
| 6689 | 6.10.1 Reverting |
| 6690 | ---------------- |
| 6691 | |
| 6692 | ‘V’ (‘magit-revert’) |
| 6693 | This transient prefix command binds the following suffix commands |
| 6694 | along with the appropriate infix arguments and displays them in a |
| 6695 | temporary buffer until a suffix is invoked. |
| 6696 | |
| 6697 | When no cherry-pick or revert is in progress, then the transient |
| 6698 | features the following suffix commands. |
| 6699 | |
| 6700 | ‘V V’ (‘magit-revert-and-commit’) |
| 6701 | Revert a commit by creating a new commit. Prompt for a commit, |
| 6702 | defaulting to the commit at point. If the region selects multiple |
| 6703 | commits, then revert all of them, without prompting. |
| 6704 | |
| 6705 | ‘V v’ (‘magit-revert-no-commit’) |
| 6706 | Revert a commit by applying it in reverse to the working tree. |
| 6707 | Prompt for a commit, defaulting to the commit at point. If the |
| 6708 | region selects multiple commits, then revert all of them, without |
| 6709 | prompting. |
| 6710 | |
| 6711 | When a cherry-pick or revert is in progress, then the transient |
| 6712 | instead features the following suffix commands. |
| 6713 | |
| 6714 | ‘V V’ (‘magit-sequence-continue’) |
| 6715 | Resume the current cherry-pick or revert sequence. |
| 6716 | |
| 6717 | ‘V s’ (‘magit-sequence-skip’) |
| 6718 | Skip the stopped at commit during a cherry-pick or revert sequence. |
| 6719 | |
| 6720 | ‘V a’ (‘magit-sequence-abort’) |
| 6721 | Abort the current cherry-pick or revert sequence. This discards |
| 6722 | all changes made since the sequence started. |
| 6723 | |
| 6724 | |
| 6725 | File: magit.info, Node: Resetting, Next: Stashing, Prev: Cherry Picking, Up: Manipulating |
| 6726 | |
| 6727 | 6.11 Resetting |
| 6728 | ============== |
| 6729 | |
| 6730 | Also see *note (gitman)git-reset::. |
| 6731 | |
| 6732 | ‘x’ (‘magit-reset-quickly’) |
| 6733 | Reset the ‘HEAD’ and index to some commit read from the user and |
| 6734 | defaulting to the commit at point, and possibly also reset the |
| 6735 | working tree. With a prefix argument reset the working tree |
| 6736 | otherwise don't. |
| 6737 | |
| 6738 | ‘X m’ (‘magit-reset-mixed’) |
| 6739 | Reset the ‘HEAD’ and index to some commit read from the user and |
| 6740 | defaulting to the commit at point. The working tree is kept as-is. |
| 6741 | |
| 6742 | ‘X s’ (‘magit-reset-soft’) |
| 6743 | Reset the ‘HEAD’ to some commit read from the user and defaulting |
| 6744 | to the commit at point. The index and the working tree are kept |
| 6745 | as-is. |
| 6746 | |
| 6747 | ‘X h’ (‘magit-reset-hard’) |
| 6748 | Reset the ‘HEAD’, index, and working tree to some commit read from |
| 6749 | the user and defaulting to the commit at point. |
| 6750 | |
| 6751 | ‘X k’ (‘magit-reset-keep’) |
| 6752 | Reset the ‘HEAD’, index, and working tree to some commit read from |
| 6753 | the user and defaulting to the commit at point. Uncommitted |
| 6754 | changes are kept as-is. |
| 6755 | |
| 6756 | ‘X i’ (‘magit-reset-index’) |
| 6757 | Reset the index to some commit read from the user and defaulting to |
| 6758 | the commit at point. Keep the ‘HEAD’ and working tree as-is, so if |
| 6759 | the commit refers to the ‘HEAD’, then this effectively unstages all |
| 6760 | changes. |
| 6761 | |
| 6762 | ‘X w’ (‘magit-reset-worktree’) |
| 6763 | Reset the working tree to some commit read from the user and |
| 6764 | defaulting to the commit at point. Keep the ‘HEAD’ and index |
| 6765 | as-is. |
| 6766 | |
| 6767 | ‘X f’ (‘magit-file-checkout’) |
| 6768 | Update file in the working tree and index to the contents from a |
| 6769 | revision. Both the revision and file are read from the user. |
| 6770 | |
| 6771 | |
| 6772 | File: magit.info, Node: Stashing, Prev: Resetting, Up: Manipulating |
| 6773 | |
| 6774 | 6.12 Stashing |
| 6775 | ============= |
| 6776 | |
| 6777 | Also see *note (gitman)git-stash::. |
| 6778 | |
| 6779 | ‘z’ (‘magit-stash’) |
| 6780 | This transient prefix command binds the following suffix commands |
| 6781 | along with the appropriate infix arguments and displays them in a |
| 6782 | temporary buffer until a suffix is invoked. |
| 6783 | |
| 6784 | ‘z z’ (‘magit-stash-both’) |
| 6785 | Create a stash of the index and working tree. Untracked files are |
| 6786 | included according to infix arguments. One prefix argument is |
| 6787 | equivalent to ‘--include-untracked’ while two prefix arguments are |
| 6788 | equivalent to ‘--all’. |
| 6789 | |
| 6790 | ‘z i’ (‘magit-stash-index’) |
| 6791 | Create a stash of the index only. Unstaged and untracked changes |
| 6792 | are not stashed. |
| 6793 | |
| 6794 | ‘z w’ (‘magit-stash-worktree’) |
| 6795 | Create a stash of unstaged changes in the working tree. Untracked |
| 6796 | files are included according to infix arguments. One prefix |
| 6797 | argument is equivalent to ‘--include-untracked’ while two prefix |
| 6798 | arguments are equivalent to ‘--all’. |
| 6799 | |
| 6800 | ‘z x’ (‘magit-stash-keep-index’) |
| 6801 | Create a stash of the index and working tree, keeping index intact. |
| 6802 | Untracked files are included according to infix arguments. One |
| 6803 | prefix argument is equivalent to ‘--include-untracked’ while two |
| 6804 | prefix arguments are equivalent to ‘--all’. |
| 6805 | |
| 6806 | ‘z Z’ (‘magit-snapshot-both’) |
| 6807 | Create a snapshot of the index and working tree. Untracked files |
| 6808 | are included according to infix arguments. One prefix argument is |
| 6809 | equivalent to ‘--include-untracked’ while two prefix arguments are |
| 6810 | equivalent to ‘--all’. |
| 6811 | |
| 6812 | ‘z I’ (‘magit-snapshot-index’) |
| 6813 | Create a snapshot of the index only. Unstaged and untracked |
| 6814 | changes are not stashed. |
| 6815 | |
| 6816 | ‘z W’ (‘magit-snapshot-worktree’) |
| 6817 | Create a snapshot of unstaged changes in the working tree. |
| 6818 | Untracked files are included according to infix arguments. One |
| 6819 | prefix argument is equivalent to ‘--include-untracked’ while two |
| 6820 | prefix arguments are equivalent to ‘--all’-. |
| 6821 | |
| 6822 | ‘z a’ (‘magit-stash-apply’) |
| 6823 | Apply a stash to the working tree. |
| 6824 | |
| 6825 | When using a Git release before v2.38.0, simply run ‘git stash |
| 6826 | apply’ or with a prefix argument ‘git stash apply --index’. |
| 6827 | |
| 6828 | When using Git v2.38.0 or later, behave more intelligently: |
| 6829 | |
| 6830 | First try ‘git stash apply --index’, which tries to preserve the |
| 6831 | index stored in the stash, if any. This may fail because applying |
| 6832 | the stash could result in conflicts and those have to be stored in |
| 6833 | the index, making it impossible to also store the stash's index |
| 6834 | there. |
| 6835 | |
| 6836 | If ‘git stash’ fails, then potentially fall back to using ‘git |
| 6837 | apply’. If the stash does not touch any unstaged files, then pass |
| 6838 | ‘--3way’ to that command. Otherwise ask the user whether to use |
| 6839 | that argument or ‘--reject’. Customize ‘magit-no-confirm’ if you |
| 6840 | want to fall back to using ‘--3way’, without being prompted. |
| 6841 | |
| 6842 | ‘z p’ (‘magit-stash-pop’) |
| 6843 | Apply a stash to the working tree. On complete success (if the |
| 6844 | stash can be applied without any conflicts, and while preserving |
| 6845 | the stash's index) then remove the stash from stash list. |
| 6846 | |
| 6847 | When using a Git release before v2.38.0, simply run ‘git stash pop’ |
| 6848 | or with a prefix argument ‘git stash pop --index’. |
| 6849 | |
| 6850 | When using Git v2.38.0 or later, behave more intelligently: |
| 6851 | |
| 6852 | First try ‘git stash pop --index’, which tries to preserve the |
| 6853 | index stored in the stash, if any. This may fail because applying |
| 6854 | the stash could result in conflicts and those have to be stored in |
| 6855 | the index, making it impossible to also store the stash's index |
| 6856 | there. |
| 6857 | |
| 6858 | If ‘git stash’ fails, then potentially fall back to using ‘git |
| 6859 | apply’. If the stash does not touch any unstaged files, then pass |
| 6860 | ‘--3way’ to that command. Otherwise ask the user whether to use |
| 6861 | that argument or ‘--reject’. Customize ‘magit-no-confirm’ if you |
| 6862 | want to fall back to using ‘--3way’, without being prompted. |
| 6863 | |
| 6864 | ‘z k’ (‘magit-stash-drop’) |
| 6865 | Remove a stash from the stash list. When the region is active, |
| 6866 | offer to drop all contained stashes. |
| 6867 | |
| 6868 | ‘z v’ (‘magit-stash-show’) |
| 6869 | Show all diffs of a stash in a buffer. |
| 6870 | |
| 6871 | ‘z b’ (‘magit-stash-branch’) |
| 6872 | Create and checkout a new branch from an existing stash. The new |
| 6873 | branch starts at the commit that was current when the stash was |
| 6874 | created. |
| 6875 | |
| 6876 | ‘z B’ (‘magit-stash-branch-here’) |
| 6877 | Create and checkout a new branch from an existing stash. Use the |
| 6878 | current branch or ‘HEAD’ as the starting-point of the new branch. |
| 6879 | Then apply the stash, dropping it if it applies cleanly. |
| 6880 | |
| 6881 | ‘z f’ (‘magit-stash-format-patch’) |
| 6882 | Create a patch from STASH. |
| 6883 | |
| 6884 | ‘k’ (‘magit-stash-clear’) |
| 6885 | Remove all stashes saved in REF's reflog by deleting REF. |
| 6886 | |
| 6887 | ‘z l’ (‘magit-stash-list’) |
| 6888 | List all stashes in a buffer. |
| 6889 | |
| 6890 | -- User Option: magit-stashes-margin |
| 6891 | This option specifies whether the margin is initially shown in |
| 6892 | stashes buffers and how it is formatted. |
| 6893 | |
| 6894 | The value has the form ‘(INIT STYLE WIDTH AUTHOR AUTHOR-WIDTH)’. |
| 6895 | |
| 6896 | • If INIT is non-‘nil’, then the margin is shown initially. |
| 6897 | • STYLE controls how to format the author or committer date. It |
| 6898 | can be one of ‘age’ (to show the age of the commit), |
| 6899 | ‘age-abbreviated’ (to abbreviate the time unit to a |
| 6900 | character), or a string (suitable for ‘format-time-string’) to |
| 6901 | show the actual date. Option |
| 6902 | ‘magit-log-margin-show-committer-date’ controls which date is |
| 6903 | being displayed. |
| 6904 | • WIDTH controls the width of the margin. This exists for |
| 6905 | forward compatibility and currently the value should not be |
| 6906 | changed. |
| 6907 | • AUTHOR controls whether the name of the author is also shown |
| 6908 | by default. |
| 6909 | • AUTHOR-WIDTH has to be an integer. When the name of the |
| 6910 | author is shown, then this specifies how much space is used to |
| 6911 | do so. |
| 6912 | |
| 6913 | |
| 6914 | File: magit.info, Node: Transferring, Next: Miscellaneous, Prev: Manipulating, Up: Top |
| 6915 | |
| 6916 | 7 Transferring |
| 6917 | ************** |
| 6918 | |
| 6919 | * Menu: |
| 6920 | |
| 6921 | * Remotes:: |
| 6922 | * Fetching:: |
| 6923 | * Pulling:: |
| 6924 | * Pushing:: |
| 6925 | * Plain Patches:: |
| 6926 | * Maildir Patches:: |
| 6927 | |
| 6928 | |
| 6929 | File: magit.info, Node: Remotes, Next: Fetching, Up: Transferring |
| 6930 | |
| 6931 | 7.1 Remotes |
| 6932 | =========== |
| 6933 | |
| 6934 | 7.1.1 Remote Commands |
| 6935 | --------------------- |
| 6936 | |
| 6937 | The transient prefix command ‘magit-remote’ is used to add remotes and |
| 6938 | to make changes to existing remotes. This command only deals with |
| 6939 | remotes themselves, not with branches or the transfer of commits. Those |
| 6940 | features are available from separate transient commands. |
| 6941 | |
| 6942 | Also see *note (gitman)git-remote::. |
| 6943 | |
| 6944 | ‘M’ (‘magit-remote’) |
| 6945 | This transient prefix command binds the following suffix commands |
| 6946 | and displays them in a temporary buffer until a suffix is invoked. |
| 6947 | |
| 6948 | By default it also binds and displays the values of some |
| 6949 | remote-related Git variables and allows changing their values. |
| 6950 | |
| 6951 | -- User Option: magit-remote-direct-configure |
| 6952 | This option controls whether remote-related Git variables are |
| 6953 | accessible directly from the transient ‘magit-remote’. |
| 6954 | |
| 6955 | If ‘t’ (the default) and a local branch is checked out, then |
| 6956 | ‘magit-remote’ features the variables for the upstream remote of |
| 6957 | that branch, or if ‘HEAD’ is detached, for ‘origin’, provided that |
| 6958 | exists. |
| 6959 | |
| 6960 | If ‘nil’, then ‘magit-remote-configure’ has to be used to do so. |
| 6961 | |
| 6962 | ‘M C’ (‘magit-remote-configure’) |
| 6963 | This transient prefix command binds commands that set the value of |
| 6964 | remote-related variables and displays them in a temporary buffer |
| 6965 | until the transient is exited. |
| 6966 | |
| 6967 | With a prefix argument, this command always prompts for a remote. |
| 6968 | |
| 6969 | Without a prefix argument this depends on whether it was invoked as |
| 6970 | a suffix of ‘magit-remote’ and on the |
| 6971 | ‘magit-remote-direct-configure’ option. If ‘magit-remote’ already |
| 6972 | displays the variables for the upstream, then it does not make |
| 6973 | sense to invoke another transient that displays them for the same |
| 6974 | remote. In that case this command prompts for a remote. |
| 6975 | |
| 6976 | The variables are described in *note Remote Git Variables::. |
| 6977 | |
| 6978 | ‘M a’ (‘magit-remote-add’) |
| 6979 | This command add a remote and fetches it. The remote name and url |
| 6980 | are read in the minibuffer. |
| 6981 | |
| 6982 | ‘M r’ (‘magit-remote-rename’) |
| 6983 | This command renames a remote. Both the old and the new names are |
| 6984 | read in the minibuffer. |
| 6985 | |
| 6986 | ‘M u’ (‘magit-remote-set-url’) |
| 6987 | This command changes the url of a remote. Both the remote and the |
| 6988 | new url are read in the minibuffer. |
| 6989 | |
| 6990 | ‘M k’ (‘magit-remote-remove’) |
| 6991 | This command deletes a remote, read in the minibuffer. |
| 6992 | |
| 6993 | ‘M p’ (‘magit-remote-prune’) |
| 6994 | This command removes stale remote-tracking branches for a remote |
| 6995 | read in the minibuffer. |
| 6996 | |
| 6997 | ‘M P’ (‘magit-remote-prune-refspecs’) |
| 6998 | This command removes stale refspecs for a remote read in the |
| 6999 | minibuffer. |
| 7000 | |
| 7001 | A refspec is stale if there no longer exists at least one branch on |
| 7002 | the remote that would be fetched due to that refspec. A stale |
| 7003 | refspec is problematic because its existence causes Git to refuse |
| 7004 | to fetch according to the remaining non-stale refspecs. |
| 7005 | |
| 7006 | If only stale refspecs remain, then this command offers to either |
| 7007 | delete the remote or to replace the stale refspecs with the default |
| 7008 | refspec ("+refs/heads/*:refs/remotes/REMOTE/*"). |
| 7009 | |
| 7010 | This command also removes the remote-tracking branches that were |
| 7011 | created due to the now stale refspecs. Other stale branches are |
| 7012 | not removed. |
| 7013 | |
| 7014 | -- User Option: magit-remote-add-set-remote.pushDefault |
| 7015 | This option controls whether the user is asked whether they want to |
| 7016 | set ‘remote.pushDefault’ after adding a remote. |
| 7017 | |
| 7018 | If ‘ask’, then users is always ask. If ‘ask-if-unset’, then the |
| 7019 | user is only if the variable isn't set already. If ‘nil’, then the |
| 7020 | user isn't asked and the variable isn't set. If the value is a |
| 7021 | string, then the variable is set without the user being asked, |
| 7022 | provided that the name of the added remote is equal to that string |
| 7023 | and the variable isn't already set. |
| 7024 | |
| 7025 | 7.1.2 Remote Git Variables |
| 7026 | -------------------------- |
| 7027 | |
| 7028 | These variables can be set from the transient prefix command |
| 7029 | ‘magit-remote-configure’. By default they can also be set from |
| 7030 | ‘magit-remote’. See *note Remote Commands::. |
| 7031 | |
| 7032 | -- Variable: remote.NAME.url |
| 7033 | This variable specifies the url of the remote named NAME. It can |
| 7034 | have multiple values. |
| 7035 | |
| 7036 | -- Variable: remote.NAME.fetch |
| 7037 | The refspec used when fetching from the remote named NAME. It can |
| 7038 | have multiple values. |
| 7039 | |
| 7040 | -- Variable: remote.NAME.pushurl |
| 7041 | This variable specifies the url used for pushing to the remote |
| 7042 | named NAME. If it is not specified, then ‘remote.NAME.url’ is used |
| 7043 | instead. It can have multiple values. |
| 7044 | |
| 7045 | -- Variable: remote.NAME.push |
| 7046 | The refspec used when pushing to the remote named NAME. It can |
| 7047 | have multiple values. |
| 7048 | |
| 7049 | -- Variable: remote.NAME.tagOpts |
| 7050 | This variable specifies what tags are fetched by default. If the |
| 7051 | value is ‘--no-tags’ then no tags are fetched. If the value is |
| 7052 | ‘--tags’, then all tags are fetched. If this variable has no |
| 7053 | value, then only tags are fetched that are reachable from fetched |
| 7054 | branches. |
| 7055 | |
| 7056 | -- Variable: remote.NAME.followRemoteHEAD |
| 7057 | How "git fetch" handles updates to "remotes/<remote>/HEAD". |
| 7058 | |
| 7059 | This command sets the local value of the Git variable |
| 7060 | ‘remote.<remote>.followRemoteHEAD’, where <remote> is a stand-in |
| 7061 | for the actual remote, as displayed in the menu, from which this |
| 7062 | command is invoked. This variable is documented in *note |
| 7063 | (gitman)git-config::. |
| 7064 | |
| 7065 | Unfortunately Git does not provide a variable to set a default for |
| 7066 | all remotes of all repositories, but you can set the global value |
| 7067 | for a remote name used in multiple repository, which will then be |
| 7068 | used as the default for that remote in all repositories. You |
| 7069 | should consider using "always" for remotes named "origin". |
| 7070 | |
| 7071 | |
| 7072 | File: magit.info, Node: Fetching, Next: Pulling, Prev: Remotes, Up: Transferring |
| 7073 | |
| 7074 | 7.2 Fetching |
| 7075 | ============ |
| 7076 | |
| 7077 | Also see *note (gitman)git-fetch::. For information about the upstream |
| 7078 | and the push-remote, see *note The Two Remotes::. |
| 7079 | |
| 7080 | ‘f’ (‘magit-fetch’) |
| 7081 | This transient prefix command binds the following suffix commands |
| 7082 | along with the appropriate infix arguments and displays them in a |
| 7083 | temporary buffer until a suffix is invoked. |
| 7084 | |
| 7085 | ‘f p’ (‘magit-fetch-from-pushremote’) |
| 7086 | This command fetches from the current push-remote. |
| 7087 | |
| 7088 | With a prefix argument or when the push-remote is either not |
| 7089 | configured or unusable, then let the user first configure the |
| 7090 | push-remote. |
| 7091 | |
| 7092 | ‘f u’ (‘magit-fetch-from-upstream’) |
| 7093 | This command fetch from the upstream of the current branch. |
| 7094 | |
| 7095 | If the upstream is configured for the current branch and names an |
| 7096 | existing remote, then use that. Otherwise try to use another |
| 7097 | remote: If only a single remote is configured, then use that. |
| 7098 | Otherwise if a remote named "origin" exists, then use that. |
| 7099 | |
| 7100 | If no remote can be determined, then this command is not available |
| 7101 | from the ‘magit-fetch’ transient prefix and invoking it directly |
| 7102 | results in an error. |
| 7103 | |
| 7104 | ‘f e’ (‘magit-fetch-other’) |
| 7105 | This command fetch from a repository read from the minibuffer. |
| 7106 | |
| 7107 | ‘f o’ (‘magit-fetch-branch’) |
| 7108 | This command fetches a branch from a remote, both of which are read |
| 7109 | from the minibuffer. |
| 7110 | |
| 7111 | ‘f r’ (‘magit-fetch-refspec’) |
| 7112 | This command fetches from a remote using an explicit refspec, both |
| 7113 | of which are read from the minibuffer. |
| 7114 | |
| 7115 | ‘f a’ (‘magit-fetch-all’) |
| 7116 | This command fetches from all remotes. |
| 7117 | |
| 7118 | ‘f m’ (‘magit-fetch-modules’) |
| 7119 | This command fetches all submodules. With a prefix argument, it |
| 7120 | acts as a transient prefix command, allowing the caller to set |
| 7121 | options. |
| 7122 | |
| 7123 | -- User Option: magit-pull-or-fetch |
| 7124 | By default fetch and pull commands are available from separate |
| 7125 | transient prefix command. Setting this to ‘t’ adds some (but not |
| 7126 | all) of the above suffix commands to the ‘magit-pull’ transient. |
| 7127 | |
| 7128 | If you do that, then you might also want to change the key binding |
| 7129 | for these prefix commands, e.g.: |
| 7130 | |
| 7131 | (setq magit-pull-or-fetch t) |
| 7132 | (define-key magit-mode-map "f" 'magit-pull) ; was magit-fetch |
| 7133 | (define-key magit-mode-map "F" nil) ; was magit-pull |
| 7134 | |
| 7135 | |
| 7136 | File: magit.info, Node: Pulling, Next: Pushing, Prev: Fetching, Up: Transferring |
| 7137 | |
| 7138 | 7.3 Pulling |
| 7139 | =========== |
| 7140 | |
| 7141 | Also see *note (gitman)git-pull::. For information about the upstream |
| 7142 | and the push-remote, see *note The Two Remotes::. |
| 7143 | |
| 7144 | ‘F’ (‘magit-pull’) |
| 7145 | This transient prefix command binds the following suffix commands |
| 7146 | and displays them in a temporary buffer until a suffix is invoked. |
| 7147 | |
| 7148 | ‘F p’ (‘magit-pull-from-pushremote’) |
| 7149 | This command pulls from the push-remote of the current branch. |
| 7150 | |
| 7151 | With a prefix argument or when the push-remote is either not |
| 7152 | configured or unusable, then let the user first configure the |
| 7153 | push-remote. |
| 7154 | |
| 7155 | ‘F u’ (‘magit-pull-from-upstream’) |
| 7156 | This command pulls from the upstream of the current branch. |
| 7157 | |
| 7158 | With a prefix argument or when the upstream is either not |
| 7159 | configured or unusable, then let the user first configure the |
| 7160 | upstream. |
| 7161 | |
| 7162 | ‘F e’ (‘magit-pull-branch’) |
| 7163 | This command pulls from a branch read in the minibuffer. |
| 7164 | |
| 7165 | The following suffix is disabled by default. See *note |
| 7166 | (transient)Enabling and Disabling Suffixes:: for how to enable it. |
| 7167 | |
| 7168 | ‘F U’ (‘magit-pull-into-upstream’) |
| 7169 | This command updates the upstream of the current branch from its |
| 7170 | own upstream. |
| 7171 | |
| 7172 | If the upstream of the current branch is a local branch, and the |
| 7173 | upstream of that is a remote branch, then the local upstream is |
| 7174 | updated. This makes it possible to update the upstream branch, |
| 7175 | without having to first check it out. |
| 7176 | |
| 7177 | |
| 7178 | File: magit.info, Node: Pushing, Next: Plain Patches, Prev: Pulling, Up: Transferring |
| 7179 | |
| 7180 | 7.4 Pushing |
| 7181 | =========== |
| 7182 | |
| 7183 | Also see *note (gitman)git-push::. For information about the upstream |
| 7184 | and the push-remote, see *note The Two Remotes::. |
| 7185 | |
| 7186 | ‘P’ (‘magit-push’) |
| 7187 | This transient prefix command binds the following suffix commands |
| 7188 | along with the appropriate infix arguments and displays them in a |
| 7189 | temporary buffer until a suffix is invoked. |
| 7190 | |
| 7191 | ‘P p’ (‘magit-push-current-to-pushremote’) |
| 7192 | This command pushes the current branch to its push-remote. |
| 7193 | |
| 7194 | With a prefix argument or when the push-remote is either not |
| 7195 | configured or unusable, then let the user first configure the |
| 7196 | push-remote. |
| 7197 | |
| 7198 | ‘P u’ (‘magit-push-current-to-upstream’) |
| 7199 | This command pushes the current branch to its upstream branch. |
| 7200 | |
| 7201 | With a prefix argument or when the upstream is either not |
| 7202 | configured or unusable, then let the user first configure the |
| 7203 | upstream. |
| 7204 | |
| 7205 | ‘P e’ (‘magit-push-current’) |
| 7206 | This command pushes the current branch to a branch read in the |
| 7207 | minibuffer. |
| 7208 | |
| 7209 | ‘P o’ (‘magit-push-other’) |
| 7210 | This command pushes an arbitrary branch or commit somewhere. Both |
| 7211 | the source and the target are read in the minibuffer. |
| 7212 | |
| 7213 | ‘P r’ (‘magit-push-refspecs’) |
| 7214 | This command pushes one or multiple refspecs to a remote, both of |
| 7215 | which are read in the minibuffer. |
| 7216 | |
| 7217 | To use multiple refspecs, separate them with commas. Completion is |
| 7218 | only available for the part before the colon, or when no colon is |
| 7219 | used. |
| 7220 | |
| 7221 | ‘P m’ (‘magit-push-matching’) |
| 7222 | This command pushes all matching branches to another repository. |
| 7223 | |
| 7224 | If only one remote exists, then push to that. Otherwise prompt for |
| 7225 | a remote, offering the remote configured for the current branch as |
| 7226 | default. |
| 7227 | |
| 7228 | ‘P t’ (‘magit-push-tags’) |
| 7229 | This command pushes all tags to another repository. |
| 7230 | |
| 7231 | If only one remote exists, then push to that. Otherwise prompt for |
| 7232 | a remote, offering the remote configured for the current branch as |
| 7233 | default. |
| 7234 | |
| 7235 | ‘P T’ (‘magit-push-tag’) |
| 7236 | This command pushes a tag to another repository. |
| 7237 | |
| 7238 | One of the infix arguments, ‘--force-with-lease’, deserves a word of |
| 7239 | caution. It is passed without a value, which means "permit a force push |
| 7240 | as long as the remote-tracking branches match their counterparts on the |
| 7241 | remote end". If you've set up a tool to do automatic fetches (Magit |
| 7242 | itself does not provide such functionality), using ‘--force-with-lease’ |
| 7243 | can be dangerous because you don't actually control or know the state of |
| 7244 | the remote-tracking refs. In that case, you should consider setting |
| 7245 | ‘push.useForceIfIncludes’ to ‘true’ (available since Git 2.30). |
| 7246 | |
| 7247 | Two more push commands exist, which by default are not available from |
| 7248 | the push transient. See their doc-strings for instructions on how to |
| 7249 | add them to the transient. |
| 7250 | |
| 7251 | -- Command: magit-push-implicitly args |
| 7252 | This command pushes somewhere without using an explicit refspec. |
| 7253 | |
| 7254 | This command simply runs ‘git push -v [ARGS]’. ARGS are the infix |
| 7255 | arguments. No explicit refspec arguments are used. Instead the |
| 7256 | behavior depends on at least these Git variables: ‘push.default’, |
| 7257 | ‘remote.pushDefault’, ‘branch.<branch>.pushRemote’, |
| 7258 | ‘branch.<branch>.remote’, ‘branch.<branch>.merge’, and |
| 7259 | ‘remote.<remote>.push’. |
| 7260 | |
| 7261 | If you add this suffix to a transient prefix without explicitly |
| 7262 | specifying the description, then an attempt is made to predict what |
| 7263 | this command will do. For example: |
| 7264 | |
| 7265 | (transient-insert-suffix 'magit-push \"p\" |
| 7266 | '(\"i\" magit-push-implicitly)) |
| 7267 | |
| 7268 | -- Command: magit-push-to-remote remote args |
| 7269 | This command pushes to the remote REMOTE without using an explicit |
| 7270 | refspec. The remote is read in the minibuffer. |
| 7271 | |
| 7272 | This command simply runs ‘git push -v [ARGS] REMOTE’. ARGS are the |
| 7273 | infix arguments. No refspec arguments are used. Instead the |
| 7274 | behavior depends on at least these Git variables: ‘push.default’, |
| 7275 | ‘remote.pushDefault’, ‘branch.<branch>.pushRemote’, |
| 7276 | ‘branch.<branch>.remote’, ‘branch.<branch>.merge’, and |
| 7277 | ‘remote.<remote>.push’. |
| 7278 | |
| 7279 | -- User Option: magit-push-options |
| 7280 | This option lists completion choices that are offered when setting |
| 7281 | ‘--push-option’ in the ‘magit-push’ menu. |
| 7282 | |
| 7283 | Note that ‘--push-option’ is disabled by default. See *note |
| 7284 | (transient)Enabling and Disabling Suffixes:: for how to enable it. |
| 7285 | |
| 7286 | Different forges support different push options. Links to upstream |
| 7287 | documentation: |
| 7288 | |
| 7289 | • <https://docs.gitlab.com/topics/git/commit/#push-options> |
| 7290 | |
| 7291 | There should be similar documentation for other forges, but I could |
| 7292 | not find the respective summary pages. If you find them, please |
| 7293 | let me know. |
| 7294 | |
| 7295 | |
| 7296 | File: magit.info, Node: Plain Patches, Next: Maildir Patches, Prev: Pushing, Up: Transferring |
| 7297 | |
| 7298 | 7.5 Plain Patches |
| 7299 | ================= |
| 7300 | |
| 7301 | ‘W’ (‘magit-patch’) |
| 7302 | This transient prefix command binds the following suffix commands |
| 7303 | along with the appropriate infix arguments and displays them in a |
| 7304 | temporary buffer until a suffix is invoked. |
| 7305 | |
| 7306 | ‘W c’ (‘magit-patch-create’) |
| 7307 | This command creates patches for a set commits. If the region |
| 7308 | marks several commits, then it creates patches for all of them. |
| 7309 | Otherwise it functions as a transient prefix command, which |
| 7310 | features several infix arguments and binds itself as a suffix |
| 7311 | command. When this command is invoked as a suffix of itself, then |
| 7312 | it creates a patch using the specified infix arguments. |
| 7313 | |
| 7314 | ‘w a’ (‘magit-patch-apply’) |
| 7315 | This command applies a patch. This is a transient prefix command, |
| 7316 | which features several infix arguments and binds itself as a suffix |
| 7317 | command. When this command is invoked as a suffix of itself, then |
| 7318 | it applies a patch using the specified infix arguments. |
| 7319 | |
| 7320 | ‘W s’ (‘magit-patch-save’) |
| 7321 | This command creates a patch from the current diff. |
| 7322 | |
| 7323 | Inside ‘magit-diff-mode’ or ‘magit-revision-mode’ buffers, ‘C-x |
| 7324 | C-w’ is also bound to this command. |
| 7325 | |
| 7326 | It is also possible to save a plain patch file by using ‘C-x C-w’ |
| 7327 | inside a ‘magit-diff-mode’ or ‘magit-revision-mode’ buffer. |
| 7328 | |
| 7329 | |
| 7330 | File: magit.info, Node: Maildir Patches, Prev: Plain Patches, Up: Transferring |
| 7331 | |
| 7332 | 7.6 Maildir Patches |
| 7333 | =================== |
| 7334 | |
| 7335 | Also see *note (gitman)git-am::. and *note (gitman)git-apply::. |
| 7336 | |
| 7337 | ‘w’ (‘magit-am’) |
| 7338 | This transient prefix command binds the following suffix commands |
| 7339 | along with the appropriate infix arguments and displays them in a |
| 7340 | temporary buffer until a suffix is invoked. |
| 7341 | |
| 7342 | ‘w w’ (‘magit-am-apply-patches’) |
| 7343 | This command applies one or more patches. If the region marks |
| 7344 | files, then those are applied as patches. Otherwise this command |
| 7345 | reads a file-name in the minibuffer, defaulting to the file at |
| 7346 | point. |
| 7347 | |
| 7348 | ‘w m’ (‘magit-am-apply-maildir’) |
| 7349 | This command applies patches from a maildir. |
| 7350 | |
| 7351 | ‘w a’ (‘magit-patch-apply’) |
| 7352 | This command applies a plain patch. For a longer description see |
| 7353 | *note Plain Patches::. This command is only available from the |
| 7354 | ‘magit-am’ transient for historic reasons. |
| 7355 | |
| 7356 | When an "am" operation is in progress, then the transient instead |
| 7357 | features the following suffix commands. |
| 7358 | |
| 7359 | ‘w w’ (‘magit-am-continue’) |
| 7360 | This command resumes the current patch applying sequence. |
| 7361 | |
| 7362 | ‘w s’ (‘magit-am-skip’) |
| 7363 | This command skips the stopped at patch during a patch applying |
| 7364 | sequence. |
| 7365 | |
| 7366 | ‘w a’ (‘magit-am-abort’) |
| 7367 | This command aborts the current patch applying sequence. This |
| 7368 | discards all changes made since the sequence started. |
| 7369 | |
| 7370 | |
| 7371 | File: magit.info, Node: Miscellaneous, Next: Customizing, Prev: Transferring, Up: Top |
| 7372 | |
| 7373 | 8 Miscellaneous |
| 7374 | *************** |
| 7375 | |
| 7376 | * Menu: |
| 7377 | |
| 7378 | * Tagging:: |
| 7379 | * Notes:: |
| 7380 | * Submodules:: |
| 7381 | * Subtree:: |
| 7382 | * Worktree:: |
| 7383 | * Sparse checkouts:: |
| 7384 | * Bundle:: |
| 7385 | * Common Commands:: |
| 7386 | * Wip Modes:: |
| 7387 | * Commands for Buffers Visiting Files:: |
| 7388 | * Minor Mode for Buffers Visiting Blobs:: |
| 7389 | |
| 7390 | |
| 7391 | File: magit.info, Node: Tagging, Next: Notes, Up: Miscellaneous |
| 7392 | |
| 7393 | 8.1 Tagging |
| 7394 | =========== |
| 7395 | |
| 7396 | Also see *note (gitman)git-tag::. |
| 7397 | |
| 7398 | ‘t’ (‘magit-tag’) |
| 7399 | This transient prefix command binds the following suffix commands |
| 7400 | along with the appropriate infix arguments and displays them in a |
| 7401 | temporary buffer until a suffix is invoked. |
| 7402 | |
| 7403 | ‘t t’ (‘magit-tag-create’) |
| 7404 | This command creates a new tag with the given NAME at REV. With a |
| 7405 | prefix argument it creates an annotated tag. |
| 7406 | |
| 7407 | ‘t r’ (‘magit-tag-release’) |
| 7408 | This commands creates a release tag. It assumes that release tags |
| 7409 | match ‘magit-release-tag-regexp’. |
| 7410 | |
| 7411 | First it prompts for the name of the new tag using the highest |
| 7412 | existing tag as initial input and leaving it to the user to |
| 7413 | increment the desired part of the version string. If you use |
| 7414 | unconventional release tags or version numbers (e.g., |
| 7415 | ‘v1.2.3-custom.1’), you can set the ‘magit-release-tag-regexp’ and |
| 7416 | ‘magit-tag-version-regexp-alist’ variables. |
| 7417 | |
| 7418 | If ‘--annotate’ is enabled then it prompts for the message of the |
| 7419 | new tag. The proposed tag message is based on the message of the |
| 7420 | highest tag, provided that that contains the corresponding version |
| 7421 | string and substituting the new version string for that. Otherwise |
| 7422 | it proposes something like "Foo-Bar 1.2.3", given, for example, a |
| 7423 | TAG "v1.2.3" and a repository located at something like |
| 7424 | "/path/to/foo-bar". |
| 7425 | |
| 7426 | ‘t k’ (‘magit-tag-delete’) |
| 7427 | This command deletes one or more tags. If the region marks |
| 7428 | multiple tags (and nothing else), then it offers to delete those. |
| 7429 | Otherwise, it prompts for a single tag to be deleted, defaulting to |
| 7430 | the tag at point. |
| 7431 | |
| 7432 | ‘t p’ (‘magit-tag-prune’) |
| 7433 | This command offers to delete tags missing locally from REMOTE, and |
| 7434 | vice versa. |
| 7435 | |
| 7436 | |
| 7437 | File: magit.info, Node: Notes, Next: Submodules, Prev: Tagging, Up: Miscellaneous |
| 7438 | |
| 7439 | 8.2 Notes |
| 7440 | ========= |
| 7441 | |
| 7442 | Also see *note (gitman)git-notes::. |
| 7443 | |
| 7444 | ‘T’ (‘magit-notes’) |
| 7445 | This transient prefix command binds the following suffix commands |
| 7446 | along with the appropriate infix arguments and displays them in a |
| 7447 | temporary buffer until a suffix is invoked. |
| 7448 | |
| 7449 | ‘T T’ (‘magit-notes-edit’) |
| 7450 | Edit the note attached to a commit, defaulting to the commit at |
| 7451 | point. |
| 7452 | |
| 7453 | By default use the value of Git variable ‘core.notesRef’ or |
| 7454 | "refs/notes/commits" if that is undefined. |
| 7455 | |
| 7456 | ‘T r’ (‘magit-notes-remove’) |
| 7457 | Remove the note attached to a commit, defaulting to the commit at |
| 7458 | point. |
| 7459 | |
| 7460 | By default use the value of Git variable ‘core.notesRef’ or |
| 7461 | "refs/notes/commits" if that is undefined. |
| 7462 | |
| 7463 | ‘T p’ (‘magit-notes-prune’) |
| 7464 | Remove notes about unreachable commits. |
| 7465 | |
| 7466 | It is possible to merge one note ref into another. That may result |
| 7467 | in conflicts which have to resolved in the temporary worktree |
| 7468 | ".git/NOTES_MERGE_WORKTREE". |
| 7469 | |
| 7470 | ‘T m’ (‘magit-notes-merge’) |
| 7471 | Merge the notes of a ref read from the user into the current notes |
| 7472 | ref. The current notes ref is the value of Git variable |
| 7473 | ‘core.notesRef’ or "refs/notes/commits" if that is undefined. |
| 7474 | |
| 7475 | When a notes merge is in progress then the transient features the |
| 7476 | following suffix commands, instead of those listed above. |
| 7477 | |
| 7478 | ‘T c’ (‘magit-notes-merge-commit’) |
| 7479 | Commit the current notes ref merge, after manually resolving |
| 7480 | conflicts. |
| 7481 | |
| 7482 | ‘T a’ (‘magit-notes-merge-abort’) |
| 7483 | Abort the current notes ref merge. |
| 7484 | |
| 7485 | The following variables control what notes reference ‘magit-notes-*’, |
| 7486 | ‘git notes’ and ‘git show’ act on and display. Both the local and |
| 7487 | global values are displayed and can be modified. |
| 7488 | |
| 7489 | -- Variable: core.notesRef |
| 7490 | This variable specifies the notes ref that is displayed by default |
| 7491 | and which commands act on by default. |
| 7492 | |
| 7493 | -- Variable: notes.displayRef |
| 7494 | This variable specifies additional notes ref to be displayed in |
| 7495 | addition to the ref specified by ‘core.notesRef’. It can have |
| 7496 | multiple values and may end with ‘*’ to display all refs in the |
| 7497 | ‘refs/notes/’ namespace (or ‘**’ if some names contain slashes). |
| 7498 | |
| 7499 | |
| 7500 | File: magit.info, Node: Submodules, Next: Subtree, Prev: Notes, Up: Miscellaneous |
| 7501 | |
| 7502 | 8.3 Submodules |
| 7503 | ============== |
| 7504 | |
| 7505 | Also see *note (gitman)git-submodule::. |
| 7506 | |
| 7507 | 8.3.1 Listing Submodules |
| 7508 | ------------------------ |
| 7509 | |
| 7510 | The command ‘magit-list-submodules’ displays a list of the current |
| 7511 | repository's submodules in a separate buffer. It's also possible to |
| 7512 | display information about submodules directly in the status buffer of |
| 7513 | the super-repository by adding ‘magit-insert-modules’ to the hook |
| 7514 | ‘magit-status-sections-hook’ as described in *note Status Module |
| 7515 | Sections::. |
| 7516 | |
| 7517 | -- Command: magit-list-submodules |
| 7518 | This command displays a list of the current repository's populated |
| 7519 | submodules in a separate buffer. |
| 7520 | |
| 7521 | It can be invoked by pressing ‘RET’ on the section titled |
| 7522 | "Modules". |
| 7523 | |
| 7524 | -- User Option: magit-submodule-list-columns |
| 7525 | This option controls what columns are displayed by the command |
| 7526 | ‘magit-list-submodules’ and how they are displayed. |
| 7527 | |
| 7528 | Each element has the form ‘(HEADER WIDTH FORMAT PROPS)’. |
| 7529 | |
| 7530 | HEADER is the string displayed in the header. WIDTH is the width |
| 7531 | of the column. FORMAT is a function that is called with one |
| 7532 | argument, the repository identification (usually its basename), and |
| 7533 | with ‘default-directory’ bound to the toplevel of its working tree. |
| 7534 | It has to return a string to be inserted or ‘nil’. PROPS is an |
| 7535 | alist that supports the keys ‘:right-align’, ‘:pad-right’ and |
| 7536 | ‘:sort’. |
| 7537 | |
| 7538 | The ‘:sort’ function has a weird interface described in the |
| 7539 | docstring of ‘tabulated-list--get-sort’. Alternatively ‘<’ and |
| 7540 | ‘magit-repolist-version<’ can be used as those functions are |
| 7541 | automatically replaced with functions that satisfy the interface. |
| 7542 | Set ‘:sort’ to ‘nil’ to inhibit sorting; if unspecified, then the |
| 7543 | column is sortable using the default sorter. |
| 7544 | |
| 7545 | You may wish to display a range of numeric columns using just one |
| 7546 | character per column and without any padding between columns, in |
| 7547 | which case you should use an appropriate HEADER, set WIDTH to 1, |
| 7548 | and set ‘:pad-right’ to 9. ‘+’ is substituted for numbers higher |
| 7549 | than 9. |
| 7550 | |
| 7551 | 8.3.2 Submodule Transient |
| 7552 | ------------------------- |
| 7553 | |
| 7554 | ‘o’ (‘magit-submodule’) |
| 7555 | This transient prefix command binds the following suffix commands |
| 7556 | along with the appropriate infix arguments and displays them in a |
| 7557 | temporary buffer until a suffix is invoked. |
| 7558 | |
| 7559 | Some of the below commands default to act on the modules that are |
| 7560 | selected using the region. For brevity their description talk about |
| 7561 | "the selected modules", but if no modules are selected, then they act on |
| 7562 | the current module instead, or if point isn't on a module, then the read |
| 7563 | a single module to act on. With a prefix argument these commands ignore |
| 7564 | the selection and the current module and instead act on all suitable |
| 7565 | modules. |
| 7566 | |
| 7567 | ‘o a’ (‘magit-submodule-add’) |
| 7568 | This commands adds the repository at URL as a module. Optional |
| 7569 | PATH is the path to the module relative to the root of the |
| 7570 | super-project. If it is ‘nil’ then the path is determined based on |
| 7571 | URL. |
| 7572 | |
| 7573 | ‘o r’ (‘magit-submodule-register’) |
| 7574 | This command registers the selected modules by copying their urls |
| 7575 | from ".gitmodules" to "$GIT_DIR/config". These values can then be |
| 7576 | edited before running ‘magit-submodule-populate’. If you don't |
| 7577 | need to edit any urls, then use the latter directly. |
| 7578 | |
| 7579 | ‘o p’ (‘magit-submodule-populate’) |
| 7580 | This command creates the working directory or directories of the |
| 7581 | selected modules, checking out the recorded commits. |
| 7582 | |
| 7583 | ‘o u’ (‘magit-submodule-update’) |
| 7584 | This command updates the selected modules checking out the recorded |
| 7585 | commits. |
| 7586 | |
| 7587 | ‘o s’ (‘magit-submodule-synchronize’) |
| 7588 | This command synchronizes the urls of the selected modules, copying |
| 7589 | the values from ".gitmodules" to the ".git/config" of the |
| 7590 | super-project as well those of the modules. |
| 7591 | |
| 7592 | ‘o d’ (‘magit-submodule-unpopulate’) |
| 7593 | This command removes the working directory of the selected modules. |
| 7594 | |
| 7595 | ‘o l’ (‘magit-list-submodules’) |
| 7596 | This command displays a list of the current repository's modules. |
| 7597 | |
| 7598 | ‘o f’ (‘magit-fetch-modules’) |
| 7599 | This command fetches all populated modules. With a prefix |
| 7600 | argument, it acts as a transient prefix command, allowing the |
| 7601 | caller to set options. |
| 7602 | |
| 7603 | Also fetch the super-repository, because ‘git fetch’ does not |
| 7604 | support not doing that. |
| 7605 | |
| 7606 | |
| 7607 | File: magit.info, Node: Subtree, Next: Worktree, Prev: Submodules, Up: Miscellaneous |
| 7608 | |
| 7609 | 8.4 Subtree |
| 7610 | =========== |
| 7611 | |
| 7612 | Also see *note (gitman)git-subtree::. |
| 7613 | |
| 7614 | ‘O’ (‘magit-subtree’) |
| 7615 | This transient prefix command binds the two sub-transients; one for |
| 7616 | importing a subtree and one for exporting a subtree. |
| 7617 | |
| 7618 | ‘O i’ (‘magit-subtree-import’) |
| 7619 | This transient prefix command binds the following suffix commands |
| 7620 | along with the appropriate infix arguments and displays them in a |
| 7621 | temporary buffer until a suffix is invoked. |
| 7622 | |
| 7623 | The suffixes of this command import subtrees. |
| 7624 | |
| 7625 | If the ‘--prefix’ argument is set, then the suffix commands use |
| 7626 | that prefix without prompting the user. If it is unset, then they |
| 7627 | read the prefix in the minibuffer. |
| 7628 | |
| 7629 | ‘O i a’ (‘magit-subtree-add’) |
| 7630 | This command adds COMMIT from REPOSITORY as a new subtree at |
| 7631 | PREFIX. |
| 7632 | |
| 7633 | ‘O i c’ (‘magit-subtree-add-commit’) |
| 7634 | This command add COMMIT as a new subtree at PREFIX. |
| 7635 | |
| 7636 | ‘O i m’ (‘magit-subtree-merge’) |
| 7637 | This command merges COMMIT into the PREFIX subtree. |
| 7638 | |
| 7639 | ‘O i f’ (‘magit-subtree-pull’) |
| 7640 | This command pulls COMMIT from REPOSITORY into the PREFIX subtree. |
| 7641 | |
| 7642 | ‘O e’ (‘magit-subtree-export’) |
| 7643 | This transient prefix command binds the following suffix commands |
| 7644 | along with the appropriate infix arguments and displays them in a |
| 7645 | temporary buffer until a suffix is invoked. |
| 7646 | |
| 7647 | The suffixes of this command export subtrees. |
| 7648 | |
| 7649 | If the ‘--prefix’ argument is set, then the suffix commands use |
| 7650 | that prefix without prompting the user. If it is unset, then they |
| 7651 | read the prefix in the minibuffer. |
| 7652 | |
| 7653 | ‘O e p’ (‘magit-subtree-push’) |
| 7654 | This command extract the history of the subtree PREFIX and pushes |
| 7655 | it to REF on REPOSITORY. |
| 7656 | |
| 7657 | ‘O e s’ (‘magit-subtree-split’) |
| 7658 | This command extracts the history of the subtree PREFIX. |
| 7659 | |
| 7660 | |
| 7661 | File: magit.info, Node: Worktree, Next: Sparse checkouts, Prev: Subtree, Up: Miscellaneous |
| 7662 | |
| 7663 | 8.5 Worktree |
| 7664 | ============ |
| 7665 | |
| 7666 | Also see *note (gitman)git-worktree::. |
| 7667 | |
| 7668 | ‘Z’ (‘magit-worktree’) |
| 7669 | This transient prefix command binds the following suffix commands |
| 7670 | and displays them in a temporary buffer until a suffix is invoked. |
| 7671 | |
| 7672 | ‘Z b’ (‘magit-worktree-checkout’) |
| 7673 | Checkout BRANCH in a new worktree at PATH. |
| 7674 | |
| 7675 | ‘Z c’ (‘magit-worktree-branch’) |
| 7676 | Create a new BRANCH and check it out in a new worktree at PATH. |
| 7677 | |
| 7678 | ‘Z m’ (‘magit-worktree-move’) |
| 7679 | Move an existing worktree to a new PATH. |
| 7680 | |
| 7681 | ‘Z k’ (‘magit-worktree-delete’) |
| 7682 | Delete a worktree, defaulting to the worktree at point. The |
| 7683 | primary worktree cannot be deleted. |
| 7684 | |
| 7685 | ‘Z g’ (‘magit-worktree-status’) |
| 7686 | Show the status for the worktree at point. |
| 7687 | |
| 7688 | If there is no worktree at point, then read one in the minibuffer. |
| 7689 | If the worktree at point is the one whose status is already being |
| 7690 | displayed in the current buffer, then show it in Dired instead. |
| 7691 | |
| 7692 | If you want the status buffer to list worktrees, add the function |
| 7693 | ‘magit-insert-worktrees’ to ‘magit-status-sections-hook’ as described in |
| 7694 | *note Status Sections::. If there is only one worktree, this function |
| 7695 | inserts nothing. |
| 7696 | |
| 7697 | |
| 7698 | File: magit.info, Node: Sparse checkouts, Next: Bundle, Prev: Worktree, Up: Miscellaneous |
| 7699 | |
| 7700 | 8.6 Sparse checkouts |
| 7701 | ==================== |
| 7702 | |
| 7703 | Sparse checkouts provide a way to restrict the working tree to a subset |
| 7704 | of directories. See *note (gitman)git-sparse-checkout::. |
| 7705 | |
| 7706 | *Warning*: Git introduced the ‘git sparse-checkout’ command in |
| 7707 | version 2.25 and still advertises it as experimental and subject to |
| 7708 | change. Magit's interface should be considered the same. In |
| 7709 | particular, if Git introduces a backward incompatible change, Magit's |
| 7710 | sparse checkout functionality may be updated in a way that requires a |
| 7711 | more recent Git version. |
| 7712 | |
| 7713 | ‘>’ (‘magit-sparse-checkout’) |
| 7714 | This transient prefix command binds the following suffix commands |
| 7715 | and displays them in a temporary buffer until a suffix is invoked. |
| 7716 | |
| 7717 | ‘> e’ (‘magit-sparse-checkout-enable’) |
| 7718 | This command initializes a sparse checkout that includes only the |
| 7719 | files in the top-level directory. |
| 7720 | |
| 7721 | Note that ‘magit-sparse-checkout-set’ and |
| 7722 | ‘magit-sparse-checkout-add’ automatically initialize a sparse |
| 7723 | checkout if necessary. However, you may want to call |
| 7724 | ‘magit-sparse-checkout-enable’ explicitly to re-initialize a sparse |
| 7725 | checkout after calling ‘magit-sparse-checkout-disable’, to pass |
| 7726 | additional arguments to ‘git sparse-checkout init’, or to execute |
| 7727 | the initialization asynchronously. |
| 7728 | |
| 7729 | ‘> s’ (‘magit-sparse-checkout-set’) |
| 7730 | This command takes a list of directories and configures the sparse |
| 7731 | checkout to include only files in those subdirectories. Any |
| 7732 | previously included directories are excluded unless they are in the |
| 7733 | provided list of directories. |
| 7734 | |
| 7735 | ‘> a’ (‘magit-sparse-checkout-add’) |
| 7736 | This command is like ‘magit-sparse-checkout-set’, but instead adds |
| 7737 | the specified list of directories to the set of directories that is |
| 7738 | already included in the sparse checkout. |
| 7739 | |
| 7740 | ‘> r’ (‘magit-sparse-checkout-reapply’) |
| 7741 | This command applies the currently configured sparse checkout |
| 7742 | patterns to the working tree. This is useful to call if excluded |
| 7743 | files have been checked out after operations such as merging or |
| 7744 | rebasing. |
| 7745 | |
| 7746 | ‘> d’ (‘magit-sparse-checkout-disable’) |
| 7747 | This command restores the full checkout. To return to the previous |
| 7748 | sparse checkout, call ‘magit-sparse-checkout-enable’. |
| 7749 | |
| 7750 | A sparse checkout can also be initiated when cloning a repository by |
| 7751 | using the ‘magit-clone-sparse’ command in the ‘magit-clone’ transient |
| 7752 | (see *note Cloning Repository::). |
| 7753 | |
| 7754 | If you want the status buffer to indicate when a sparse checkout is |
| 7755 | enabled, add the function ‘magit-sparse-checkout-insert-header’ to |
| 7756 | ‘magit-status-headers-hook’. |
| 7757 | |
| 7758 | |
| 7759 | File: magit.info, Node: Bundle, Next: Common Commands, Prev: Sparse checkouts, Up: Miscellaneous |
| 7760 | |
| 7761 | 8.7 Bundle |
| 7762 | ========== |
| 7763 | |
| 7764 | Also see *note (gitman)git-bundle::. |
| 7765 | |
| 7766 | -- Command: magit-bundle |
| 7767 | This transient prefix command binds several suffix commands for |
| 7768 | running ‘git bundle’ subcommands and displays them in a temporary |
| 7769 | buffer until a suffix is invoked. |
| 7770 | |
| 7771 | |
| 7772 | File: magit.info, Node: Common Commands, Next: Wip Modes, Prev: Bundle, Up: Miscellaneous |
| 7773 | |
| 7774 | 8.8 Common Commands |
| 7775 | =================== |
| 7776 | |
| 7777 | -- Command: magit-switch-to-repository-buffer |
| 7778 | -- Command: magit-switch-to-repository-buffer-other-window |
| 7779 | -- Command: magit-switch-to-repository-buffer-other-frame |
| 7780 | -- Command: magit-display-repository-buffer |
| 7781 | These commands read any existing Magit buffer that belongs to the |
| 7782 | current repository from the user and then switch to the selected |
| 7783 | buffer (without refreshing it). |
| 7784 | |
| 7785 | The last variant uses ‘magit-display-buffer’ to do so and thus |
| 7786 | respects ‘magit-display-buffer-function’. |
| 7787 | |
| 7788 | These are some of the commands that can be used in all buffers whose |
| 7789 | major-modes derive from ‘magit-mode’. There are other common commands |
| 7790 | beside the ones below, but these didn't fit well anywhere else. |
| 7791 | |
| 7792 | ‘C-w’ (‘magit-copy-section-value’) |
| 7793 | This command saves the value of the current section to the |
| 7794 | ‘kill-ring’, and, provided that the current section is a commit, |
| 7795 | branch, or tag section, it also pushes the (referenced) revision to |
| 7796 | the ‘magit-revision-stack’. |
| 7797 | |
| 7798 | When the current section is a branch or a tag, and a prefix |
| 7799 | argument is used, then it saves the revision at its tip to the |
| 7800 | ‘kill-ring’ instead of the reference name. |
| 7801 | |
| 7802 | When the region is active, this command saves that to the |
| 7803 | ‘kill-ring’, like ‘kill-ring-save’ would, instead of behaving as |
| 7804 | described above. If a prefix argument is used and the region is |
| 7805 | within a hunk, then it strips the diff marker column and keeps only |
| 7806 | either the added or removed lines, depending on the sign of the |
| 7807 | prefix argument. |
| 7808 | |
| 7809 | ‘M-w’ (‘magit-copy-buffer-revision’) |
| 7810 | This command saves the revision being displayed in the current |
| 7811 | buffer to the ‘kill-ring’ and also pushes it to the |
| 7812 | ‘magit-revision-stack’. It is mainly intended for use in |
| 7813 | ‘magit-revision-mode’ buffers, the only buffers where it is always |
| 7814 | unambiguous exactly which revision should be saved. |
| 7815 | |
| 7816 | Most other Magit buffers usually show more than one revision, in |
| 7817 | some way or another, so this command has to select one of them, and |
| 7818 | that choice might not always be the one you think would have been |
| 7819 | the best pick. |
| 7820 | |
| 7821 | Outside of Magit ‘M-w’ and ‘C-w’ are usually bound to |
| 7822 | ‘kill-ring-save’ and ‘kill-region’, and these commands would also be |
| 7823 | useful in Magit buffers. Therefore when the region is active, then both |
| 7824 | of these commands behave like ‘kill-ring-save’ instead of as described |
| 7825 | above. |
| 7826 | |
| 7827 | |
| 7828 | File: magit.info, Node: Wip Modes, Next: Commands for Buffers Visiting Files, Prev: Common Commands, Up: Miscellaneous |
| 7829 | |
| 7830 | 8.9 Wip Modes |
| 7831 | ============= |
| 7832 | |
| 7833 | Git keeps *committed* changes around long enough for users to recover |
| 7834 | changes they have accidentally deleted. It does so by not garbage |
| 7835 | collecting any committed but no longer referenced objects for a certain |
| 7836 | period of time, by default 30 days. |
| 7837 | |
| 7838 | But Git does *not* keep track of *uncommitted* changes in the working |
| 7839 | tree and not even the index (the staging area). Because Magit makes it |
| 7840 | so convenient to modify uncommitted changes, it also makes it easy to |
| 7841 | shoot yourself in the foot in the process. |
| 7842 | |
| 7843 | For that reason Magit provides a global mode that saves *tracked* |
| 7844 | files to work-in-progress references after or before certain actions. |
| 7845 | (At present untracked files are never saved and for technical reasons |
| 7846 | nothing is saved before the first commit has been created). |
| 7847 | |
| 7848 | Two separate work-in-progress references are used to track the state |
| 7849 | of the index and of the working tree: ‘refs/wip/index/<branchref>’ and |
| 7850 | ‘refs/wip/wtree/<branchref>’, where ‘<branchref>’ is the full ref of the |
| 7851 | current branch, e.g., ‘refs/heads/master’. When the ‘HEAD’ is detached |
| 7852 | then ‘HEAD’ is used in place of ‘<branchref>’. |
| 7853 | |
| 7854 | Checking out another branch (or detaching ‘HEAD’) causes the use of |
| 7855 | different wip refs for subsequent changes. |
| 7856 | |
| 7857 | -- User Option: magit-wip-mode |
| 7858 | When this mode is enabled, then uncommitted changes are committed |
| 7859 | to dedicated work-in-progress refs whenever appropriate (i.e., when |
| 7860 | dataloss would be a possibility otherwise). |
| 7861 | |
| 7862 | Setting this variable directly does not take effect; either use the |
| 7863 | Custom interface to do so or call the respective mode function. |
| 7864 | |
| 7865 | To view the log for a branch and its wip refs use the commands |
| 7866 | ‘magit-wip-log’ and ‘magit-wip-log-current’. You should use ‘--graph’ |
| 7867 | when using these commands. |
| 7868 | |
| 7869 | -- Command: magit-wip-log |
| 7870 | This command shows the log for a branch and its wip refs. With a |
| 7871 | negative prefix argument only the worktree wip ref is shown. |
| 7872 | |
| 7873 | The absolute numeric value of the prefix argument controls how many |
| 7874 | "branches" of each wip ref are shown. This is only relevant if the |
| 7875 | value of ‘magit-wip-merge-branch’ is ‘nil’. |
| 7876 | |
| 7877 | -- Command: magit-wip-log-current |
| 7878 | This command shows the log for the current branch and its wip refs. |
| 7879 | With a negative prefix argument only the worktree wip ref is shown. |
| 7880 | |
| 7881 | The absolute numeric value of the prefix argument controls how many |
| 7882 | "branches" of each wip ref are shown. This is only relevant if the |
| 7883 | value of ‘magit-wip-merge-branch’ is ‘nil’. |
| 7884 | |
| 7885 | ‘X w’ (‘magit-reset-worktree’) |
| 7886 | This command resets the working tree to some commit read from the |
| 7887 | user and defaulting to the commit at point, while keeping the |
| 7888 | ‘HEAD’ and index as-is. |
| 7889 | |
| 7890 | This can be used to restore files to the state committed to a wip |
| 7891 | ref. Note that this will discard any unstaged changes that might |
| 7892 | have existed before invoking this command (but of course only after |
| 7893 | committing that to the working tree wip ref). |
| 7894 | |
| 7895 | Note that even if you enable ‘magit-wip-mode’ this won't give you |
| 7896 | perfect protection. The most likely scenario for losing changes despite |
| 7897 | the use of ‘magit-wip-mode’ is making a change outside Emacs and then |
| 7898 | destroying it also outside Emacs. In some such a scenario, Magit, being |
| 7899 | an Emacs package, didn't get the opportunity to keep you from shooting |
| 7900 | yourself in the foot. |
| 7901 | |
| 7902 | When you are unsure whether Magit did commit a change to the wip |
| 7903 | refs, then you can explicitly request that all changes to all tracked |
| 7904 | files are being committed. |
| 7905 | |
| 7906 | ‘M-x magit-wip-commit’ |
| 7907 | This command commits all changes to all tracked files to the index |
| 7908 | and working tree work-in-progress refs. Like the modes described |
| 7909 | above, it does not commit untracked files, but it does check all |
| 7910 | tracked files for changes. Use this command when you suspect that |
| 7911 | the modes might have overlooked a change made outside Emacs/Magit. |
| 7912 | |
| 7913 | -- User Option: magit-wip-namespace |
| 7914 | The namespace used for work-in-progress refs. It has to end with a |
| 7915 | slash. The wip refs are named ‘<namespace>index/<branchref>’ and |
| 7916 | ‘<namespace>wtree/<branchref>’. When snapshots are created while |
| 7917 | the ‘HEAD’ is detached then ‘HEAD’ is used in place of |
| 7918 | ‘<branchref>’. |
| 7919 | |
| 7920 | -- User Option: magit-wip-mode-lighter |
| 7921 | Mode-line lighter for ‘magit-wip--mode’. |
| 7922 | |
| 7923 | 8.9.1 Wip Graph |
| 7924 | --------------- |
| 7925 | |
| 7926 | -- User Option: magit-wip-merge-branch |
| 7927 | This option controls whether the current branch is merged into the |
| 7928 | wip refs after a new commit was created on the branch. |
| 7929 | |
| 7930 | If ‘nil’ and the current branch has new commits, then the wip ref |
| 7931 | is reset to the tip of the branch before creating a new wip commit. |
| 7932 | With this setting wip commits are eventually garbage collected. |
| 7933 | |
| 7934 | If non-‘nil’ and the current branch has new commits, then it is |
| 7935 | merged into the wip ref before creating a new wip commit. This |
| 7936 | makes it easier to inspect wip history and the wip commits are |
| 7937 | never garbage collected. |
| 7938 | |
| 7939 | When ‘magit-wip-merge-branch’ is ‘t’, then the history looks like |
| 7940 | this: |
| 7941 | |
| 7942 | *--*--*--*--*--* refs/wip/index/refs/heads/master |
| 7943 | / / / |
| 7944 | A-----B-----C refs/heads/master |
| 7945 | |
| 7946 | When ‘magit-wip-merge-branch’ is ‘nil’, then creating a commit on the |
| 7947 | real branch and then making a change causes the wip refs to be recreated |
| 7948 | to fork from the new commit. But the old commits on the wip refs are |
| 7949 | not lost. They are still available from the reflog. To make it easier |
| 7950 | to see when the fork point of a wip ref was changed, an additional |
| 7951 | commit with the message "restart autosaving" is created on it (‘xxO’ |
| 7952 | commits below are such boundary commits). |
| 7953 | |
| 7954 | Starting with |
| 7955 | |
| 7956 | BI0---BI1 refs/wip/index/refs/heads/master |
| 7957 | / |
| 7958 | A---B refs/heads/master |
| 7959 | \ |
| 7960 | BW0---BW1 refs/wip/wtree/refs/heads/master |
| 7961 | |
| 7962 | and committing the staged changes and editing and saving a file would |
| 7963 | result in |
| 7964 | |
| 7965 | BI0---BI1 refs/wip/index/refs/heads/master |
| 7966 | / |
| 7967 | A---B---C refs/heads/master |
| 7968 | \ \ |
| 7969 | \ CW0---CW1 refs/wip/wtree/refs/heads/master |
| 7970 | \ |
| 7971 | BW0---BW1 refs/wip/wtree/refs/heads/master@{2} |
| 7972 | |
| 7973 | The fork-point of the index wip ref is not changed until some change |
| 7974 | is being staged. Likewise just checking out a branch or creating a |
| 7975 | commit does not change the fork-point of the working tree wip ref. The |
| 7976 | fork-points are not adjusted until there actually is a change that |
| 7977 | should be committed to the respective wip ref. |
| 7978 | |
| 7979 | |
| 7980 | File: magit.info, Node: Commands for Buffers Visiting Files, Next: Minor Mode for Buffers Visiting Blobs, Prev: Wip Modes, Up: Miscellaneous |
| 7981 | |
| 7982 | 8.10 Commands for Buffers Visiting Files |
| 7983 | ======================================== |
| 7984 | |
| 7985 | By default Magit defines a few global key bindings. These bindings are |
| 7986 | a compromise between providing no bindings at all and providing the |
| 7987 | better bindings I would have liked to use instead. Magit cannot provide |
| 7988 | the set of recommended bindings by default because those key sequences |
| 7989 | are strictly reserved for bindings added by the user. Also see *note |
| 7990 | Global Bindings:: and *note (elisp)Key Binding Conventions::. |
| 7991 | |
| 7992 | To use the recommended bindings, add this to your init file and |
| 7993 | restart Emacs. |
| 7994 | |
| 7995 | (setq magit-define-global-key-bindings 'recommended) |
| 7996 | |
| 7997 | If you don't want Magit to add any bindings to the global keymap at |
| 7998 | all, add this to your init file and restart Emacs. |
| 7999 | |
| 8000 | (setq magit-define-global-key-bindings nil) |
| 8001 | |
| 8002 | ‘C-c f’ (‘magit-file-dispatch’) |
| 8003 | ‘C-c f s’ (‘magit-stage-files’) |
| 8004 | ‘C-c f s’ (‘magit-file-stage’) |
| 8005 | ‘C-c f u’ (‘magit-unstage-files’) |
| 8006 | ‘C-c f u’ (‘magit-file-unstage’) |
| 8007 | ‘C-c f , x’ (‘magit-file-untrack’) |
| 8008 | ‘C-c f , r’ (‘magit-file-rename’) |
| 8009 | ‘C-c f , k’ (‘magit-file-delete’) |
| 8010 | ‘C-c f , c’ (‘magit-file-checkout’) |
| 8011 | ‘C-c f D’ (‘magit-diff’) |
| 8012 | ‘C-c f d’ (‘magit-diff-buffer-file’) |
| 8013 | ‘C-c f L’ (‘magit-log’) |
| 8014 | ‘C-c f l’ (‘magit-log-buffer-file’) |
| 8015 | ‘C-c f t’ (‘magit-log-trace-definition’) |
| 8016 | ‘C-c f M’ (‘magit-log-merged’) |
| 8017 | ‘C-c f B’ (‘magit-blame’) |
| 8018 | ‘C-c f b’ (‘magit-blame-additions’) |
| 8019 | ‘C-c f r’ (‘magit-blame-removal’) |
| 8020 | ‘C-c f f’ (‘magit-blame-reverse’) |
| 8021 | ‘C-c f m’ (‘magit-blame-echo’) |
| 8022 | ‘C-c f q’ (‘magit-blame-quit’) |
| 8023 | ‘C-c f p’ (‘magit-blob-previous’) |
| 8024 | ‘C-c f n’ (‘magit-blob-next’) |
| 8025 | ‘C-c f v’ (‘magit-find-file’) |
| 8026 | ‘C-c f V’ (‘magit-blob-visit-file’) |
| 8027 | ‘C-c f g’ (‘magit-status-here’) |
| 8028 | ‘C-c f G’ (‘magit-display-repository-buffer’) |
| 8029 | ‘C-c f c’ (‘magit-commit’) |
| 8030 | ‘C-c f e’ (‘magit-edit-line-commit’) |
| 8031 | Each of these commands is documented individually right below, |
| 8032 | alongside their default key bindings. The bindings shown above are |
| 8033 | the recommended bindings, which you can enable by following the |
| 8034 | instructions further up. |
| 8035 | |
| 8036 | ‘C-c M-g’ (‘magit-file-dispatch’) |
| 8037 | This transient prefix command binds the following suffix commands |
| 8038 | and displays them in a temporary buffer until a suffix is invoked. |
| 8039 | |
| 8040 | ‘C-c M-g s’ (‘magit-stage-files’) |
| 8041 | ‘C-c M-g s’ (‘magit-file-stage’) |
| 8042 | Stage all changes to the file being visited in the current buffer. |
| 8043 | When not visiting a file, then the first command is used, which |
| 8044 | prompts for a file. |
| 8045 | |
| 8046 | ‘C-c M-g u’ (‘magit-unstage-files’) |
| 8047 | ‘C-c M-g u’ (‘magit-file-unstage’) |
| 8048 | Unstage all changes to the file being visited in the current |
| 8049 | buffer. When not visiting a file, then the first command is used, |
| 8050 | which prompts for a file. |
| 8051 | |
| 8052 | ‘C-c M-g , x’ (‘magit-file-untrack’) |
| 8053 | This command untracks a file read from the user, defaulting to the |
| 8054 | visited file. |
| 8055 | |
| 8056 | ‘C-c M-g , r’ (‘magit-file-rename’) |
| 8057 | This command renames a file read from the user, defaulting to the |
| 8058 | visited file. |
| 8059 | |
| 8060 | ‘C-c M-g , k’ (‘magit-file-delete’) |
| 8061 | This command deletes a file read from the user, defaulting to the |
| 8062 | visited file. |
| 8063 | |
| 8064 | ‘C-c M-g , c’ (‘magit-file-checkout’) |
| 8065 | This command updates a file in the working tree and index to the |
| 8066 | contents from a revision. Both the revision and file are read from |
| 8067 | the user. |
| 8068 | |
| 8069 | ‘C-c M-g D’ (‘magit-diff’) |
| 8070 | This transient prefix command binds several diff suffix commands |
| 8071 | and infix arguments and displays them in a temporary buffer until a |
| 8072 | suffix is invoked. See *note Diffing::. |
| 8073 | |
| 8074 | This is the same command that ‘d’ is bound to in Magit buffers. If |
| 8075 | this command is invoked from a file-visiting buffer, then the |
| 8076 | initial value of the option (‘--’) that limits the diff to certain |
| 8077 | file(s) is set to the visited file. |
| 8078 | |
| 8079 | ‘C-c M-g d’ (‘magit-diff-buffer-file’) |
| 8080 | This command shows the diff for the file of blob that the current |
| 8081 | buffer visits. The diff is limited to the file or blob. |
| 8082 | |
| 8083 | When the buffer visits a blob, then show the respective commit. |
| 8084 | When the buffer visits a file, then show the differences between |
| 8085 | ‘HEAD’ and the working tree, or the index with a prefix argument. |
| 8086 | |
| 8087 | -- Command: magit-show-commit-removing-file |
| 8088 | This command shows the commit that removed FILE. |
| 8089 | |
| 8090 | -- User Option: magit-diff-buffer-file-locked |
| 8091 | This option controls whether ‘magit-diff-buffer-file’ uses a |
| 8092 | dedicated buffer. See *note Modes and Buffers::. |
| 8093 | |
| 8094 | ‘C-c M-g L’ (‘magit-log’) |
| 8095 | This transient prefix command binds several log suffix commands and |
| 8096 | infix arguments and displays them in a temporary buffer until a |
| 8097 | suffix is invoked. See *note Logging::. |
| 8098 | |
| 8099 | This is the same command that ‘l’ is bound to in Magit buffers. If |
| 8100 | this command is invoked from a file-visiting buffer, then the |
| 8101 | initial value of the option (‘--’) that limits the log to certain |
| 8102 | file(s) is set to the visited file. |
| 8103 | |
| 8104 | ‘C-c M-g l’ (‘magit-log-buffer-file’) |
| 8105 | This command shows the log for the file of blob that the current |
| 8106 | buffer visits. Renames are followed when a prefix argument is used |
| 8107 | or when ‘--follow’ is an active log argument. When the region is |
| 8108 | active, the log is restricted to the selected line range. |
| 8109 | |
| 8110 | -- User Option: magit-log-buffer-file-locked |
| 8111 | This option controls whether ‘magit-log-buffer-file’ uses a |
| 8112 | dedicated buffer. See *note Modes and Buffers::. |
| 8113 | |
| 8114 | ‘C-c M-g t’ (‘magit-log-trace-definition’) |
| 8115 | This command shows the log for the definition at point. |
| 8116 | |
| 8117 | ‘C-c M-g M’ (‘magit-log-merged’) |
| 8118 | This command reads a commit and a branch in shows a log concerning |
| 8119 | the merge of the former into the latter. This shows multiple |
| 8120 | commits even in case of a fast-forward merge. |
| 8121 | |
| 8122 | ‘C-c M-g B’ (‘magit-blame’) |
| 8123 | This transient prefix command binds all blaming suffix commands |
| 8124 | along with the appropriate infix arguments and displays them in a |
| 8125 | temporary buffer until a suffix is invoked. |
| 8126 | |
| 8127 | For more information about this and the following commands also see |
| 8128 | *note Blaming::. |
| 8129 | |
| 8130 | In addition to the ‘magit-blame’ sub-transient, the dispatch |
| 8131 | transient also binds several blaming suffix commands directly. See |
| 8132 | *note Blaming:: for information about those commands and bindings. |
| 8133 | |
| 8134 | ‘C-c M-g p’ (‘magit-blob-previous’) |
| 8135 | This command visits the previous blob which modified the current |
| 8136 | file. |
| 8137 | |
| 8138 | ‘C-c M-g n’ (‘magit-blob-next’) |
| 8139 | This command visits the next blob which modified the current file. |
| 8140 | |
| 8141 | ‘C-c M-g v’ (‘magit-find-file’) |
| 8142 | This command reads a revision and file and visits the respective |
| 8143 | blob. |
| 8144 | |
| 8145 | ‘C-c M-g V’ (‘magit-blob-visit-file’) |
| 8146 | This command visits the file from the working tree, corresponding |
| 8147 | to the current blob. When visiting a blob or the version from the |
| 8148 | index, then it goes to the same location in the respective file in |
| 8149 | the working tree. |
| 8150 | |
| 8151 | ‘C-c M-g g’ (‘magit-status-here’) |
| 8152 | This command displays the status of the current repository in a |
| 8153 | buffer, like ‘magit-status’ does. Additionally it tries to go to |
| 8154 | the position in that buffer, which corresponds to the position in |
| 8155 | the current file-visiting buffer (if any). |
| 8156 | |
| 8157 | Before doing so, save all file-visiting buffers belonging to the |
| 8158 | current repository without prompting. |
| 8159 | |
| 8160 | ‘C-c M-g G’ (‘magit-display-repository-buffer’) |
| 8161 | This command reads and displays a Magit buffer belonging to the |
| 8162 | current repository, without refreshing it. |
| 8163 | |
| 8164 | ‘C-c M-g c’ (‘magit-commit’) |
| 8165 | This transient prefix command binds the following suffix commands |
| 8166 | along with the appropriate infix arguments and displays them in a |
| 8167 | temporary buffer until a suffix is invoked. See *note Initiating a |
| 8168 | Commit::. |
| 8169 | |
| 8170 | ‘C-c M-g e’ (‘magit-edit-line-commit’) |
| 8171 | This command makes the commit editable that added the current line. |
| 8172 | |
| 8173 | With a prefix argument it makes the commit editable that removes |
| 8174 | the line, if any. The commit is determined using ‘git blame’ and |
| 8175 | made editable using ‘git rebase --interactive’ if it is reachable |
| 8176 | from ‘HEAD’, or by checking out the commit (or a branch that points |
| 8177 | at it) otherwise. |
| 8178 | |
| 8179 | |
| 8180 | File: magit.info, Node: Minor Mode for Buffers Visiting Blobs, Prev: Commands for Buffers Visiting Files, Up: Miscellaneous |
| 8181 | |
| 8182 | 8.11 Minor Mode for Buffers Visiting Blobs |
| 8183 | ========================================== |
| 8184 | |
| 8185 | The ‘magit-blob-mode’ enables certain Magit features in blob-visiting |
| 8186 | buffers. Such buffers can be created using ‘magit-find-file’ and some |
| 8187 | of the commands mentioned below, which also take care of turning on this |
| 8188 | minor mode. Currently this mode only establishes a few key bindings, |
| 8189 | but this might be extended. |
| 8190 | |
| 8191 | ‘p’ (‘magit-blob-previous’) |
| 8192 | This command visits the previous blob that modified the current |
| 8193 | file. |
| 8194 | |
| 8195 | ‘n’ (‘magit-blob-next’) |
| 8196 | This command visit the next blob that modified the current file. |
| 8197 | |
| 8198 | ‘q’ (‘magit-bury-or-kill-buffer’) |
| 8199 | This command buries the current buffer, if that is being displayed |
| 8200 | in multiple windows and/or when a prefix argument is used. If |
| 8201 | neither is the case, it instead kills the current buffer. |
| 8202 | |
| 8203 | You might want to bind ‘u’ to another command. Suitable commands |
| 8204 | include ‘bury-buffer’, ‘magit-bury-buffer’ and ‘magit-kill-this-buffer’. |
| 8205 | |
| 8206 | |
| 8207 | File: magit.info, Node: Customizing, Next: Plumbing, Prev: Miscellaneous, Up: Top |
| 8208 | |
| 8209 | 9 Customizing |
| 8210 | ************* |
| 8211 | |
| 8212 | Both Git and Emacs are highly customizable. Magit is both a Git |
| 8213 | porcelain as well as an Emacs package, so it makes sense to customize it |
| 8214 | using both Git variables as well as Emacs options. However this |
| 8215 | flexibility doesn't come without problems, including but not limited to |
| 8216 | the following. |
| 8217 | |
| 8218 | • Some Git variables automatically have an effect in Magit without |
| 8219 | requiring any explicit support. Sometimes that is desirable - in |
| 8220 | other cases, it breaks Magit. |
| 8221 | |
| 8222 | When a certain Git setting breaks Magit but you want to keep using |
| 8223 | that setting on the command line, then that can be accomplished by |
| 8224 | overriding the value for Magit only by appending something like |
| 8225 | ‘("-c" "some.variable=compatible-value")’ to |
| 8226 | ‘magit-git-global-arguments’. |
| 8227 | |
| 8228 | • Certain settings like ‘fetch.prune=true’ are respected by Magit |
| 8229 | commands (because they simply call the respective Git command) but |
| 8230 | their value is not reflected in the respective transient buffers. |
| 8231 | In this case the ‘--prune’ argument in ‘magit-fetch’ might be |
| 8232 | active or inactive, but that doesn't keep the Git variable from |
| 8233 | being honored by the suffix commands anyway. So pruning might |
| 8234 | happen despite the ‘--prune’ arguments being displayed in a way |
| 8235 | that seems to indicate that no pruning will happen. |
| 8236 | |
| 8237 | I intend to address these and similar issues in a future release. |
| 8238 | |
| 8239 | * Menu: |
| 8240 | |
| 8241 | * Per-Repository Configuration:: |
| 8242 | * Essential Settings:: |
| 8243 | |
| 8244 | |
| 8245 | File: magit.info, Node: Per-Repository Configuration, Next: Essential Settings, Up: Customizing |
| 8246 | |
| 8247 | 9.1 Per-Repository Configuration |
| 8248 | ================================ |
| 8249 | |
| 8250 | Magit can be configured on a per-repository level using both Git |
| 8251 | variables as well as Emacs options. |
| 8252 | |
| 8253 | To set a Git variable for one repository only, simply set it in |
| 8254 | ‘/path/to/repo/.git/config’ instead of ‘$HOME/.gitconfig’ or |
| 8255 | ‘/etc/gitconfig’. See *note (gitman)git-config::. |
| 8256 | |
| 8257 | Similarly, Emacs options can be set for one repository only by |
| 8258 | editing ‘/path/to/repo/.dir-locals.el’. See *note (emacs)Directory |
| 8259 | Variables::. For example to disable automatic refreshes of |
| 8260 | file-visiting buffers in just one huge repository use this: |
| 8261 | |
| 8262 | • ‘/path/to/huge/repo/.dir-locals.el’ |
| 8263 | |
| 8264 | ((nil . ((magit-refresh-buffers . nil)))) |
| 8265 | |
| 8266 | It might only be costly to insert certain information into Magit |
| 8267 | buffers for repositories that are exceptionally large, in which case you |
| 8268 | can disable the respective section inserters just for that repository: |
| 8269 | |
| 8270 | • ‘/path/to/tag/invested/repo/.dir-locals.el’ |
| 8271 | |
| 8272 | ((magit-status-mode |
| 8273 | . ((eval . (magit-disable-section-inserter 'magit-insert-tags-header))))) |
| 8274 | |
| 8275 | -- Function: magit-disable-section-inserter fn |
| 8276 | This function disables the section inserter FN in the current |
| 8277 | repository. It is only intended for use in ‘.dir-locals.el’ and |
| 8278 | ‘.dir-locals-2.el’. |
| 8279 | |
| 8280 | If you want to apply the same settings to several, but not all, |
| 8281 | repositories then keeping the repository-local config files in sync |
| 8282 | would quickly become annoying. To avoid that you can create config |
| 8283 | files for certain classes of repositories (e.g., "huge repositories") |
| 8284 | and then include those files in the per-repository config files. For |
| 8285 | example: |
| 8286 | |
| 8287 | • ‘/path/to/huge/repo/.git/config’ |
| 8288 | |
| 8289 | [include] |
| 8290 | path = /path/to/huge-gitconfig |
| 8291 | |
| 8292 | • ‘/path/to/huge-gitconfig’ |
| 8293 | |
| 8294 | [status] |
| 8295 | showUntrackedFiles = no |
| 8296 | |
| 8297 | • ‘$HOME/.emacs.d/init.el’ |
| 8298 | |
| 8299 | (dir-locals-set-class-variables 'huge-git-repository |
| 8300 | '((nil . ((magit-refresh-buffers . nil))))) |
| 8301 | |
| 8302 | (dir-locals-set-directory-class |
| 8303 | "/path/to/huge/repo/" 'huge-git-repository) |
| 8304 | |
| 8305 | |
| 8306 | File: magit.info, Node: Essential Settings, Prev: Per-Repository Configuration, Up: Customizing |
| 8307 | |
| 8308 | 9.2 Essential Settings |
| 8309 | ====================== |
| 8310 | |
| 8311 | The next three sections list and discuss several variables that many |
| 8312 | users might want to customize, for safety and/or performance reasons. |
| 8313 | |
| 8314 | 9.2.1 Safety |
| 8315 | ------------ |
| 8316 | |
| 8317 | This section discusses various variables that you might want to change |
| 8318 | (or *not* change) for safety reasons. |
| 8319 | |
| 8320 | Git keeps *committed* changes around long enough for users to recover |
| 8321 | changes they have accidentally been deleted. It does not do the same |
| 8322 | for *uncommitted* changes in the working tree and not even the index |
| 8323 | (the staging area). Because Magit makes it so easy to modify |
| 8324 | uncommitted changes, it also makes it easy to shoot yourself in the foot |
| 8325 | in the process. For that reason Magit provides three global modes that |
| 8326 | save *tracked* files to work-in-progress references after or before |
| 8327 | certain actions. See *note Wip Modes::. |
| 8328 | |
| 8329 | These modes are not enabled by default because of performance |
| 8330 | concerns. Instead a lot of potentially destructive commands require |
| 8331 | confirmation every time they are used. In many cases this can be |
| 8332 | disabled by adding a symbol to ‘magit-no-confirm’ (see *note Completion |
| 8333 | and Confirmation::). If you enable the various wip modes then you |
| 8334 | should add ‘safe-with-wip’ to this list. |
| 8335 | |
| 8336 | Similarly it isn't necessary to require confirmation before moving a |
| 8337 | file to the system trash - if you trashed a file by mistake then you can |
| 8338 | recover it from there. Option ‘magit-delete-by-moving-to-trash’ |
| 8339 | controls whether the system trash is used, which is the case by default. |
| 8340 | Nevertheless, ‘trash’ isn't a member of ‘magit-no-confirm’ - you might |
| 8341 | want to change that. |
| 8342 | |
| 8343 | By default buffers visiting files are automatically reverted when the |
| 8344 | visited file changes on disk. This isn't as risky as it might seem, but |
| 8345 | to make an informed decision you should see *note Risk of Reverting |
| 8346 | Automatically::. |
| 8347 | |
| 8348 | 9.2.2 Performance |
| 8349 | ----------------- |
| 8350 | |
| 8351 | After Magit has run ‘git’ for side-effects, it also refreshes the |
| 8352 | current Magit buffer and the respective status buffer. This is |
| 8353 | necessary because otherwise outdated information might be displayed |
| 8354 | without the user noticing. Magit buffers are updated by recreating |
| 8355 | their content from scratch, which makes updating simpler and less |
| 8356 | error-prone, but also more costly. Keeping it simple and just |
| 8357 | re-creating everything from scratch is an old design decision and |
| 8358 | departing from that will require major refactoring. |
| 8359 | |
| 8360 | Meanwhile you can tell Magit to only automatically refresh the |
| 8361 | current Magit buffer, but not the status buffer. If you do that, then |
| 8362 | the status buffer is only refreshed automatically if it is the current |
| 8363 | buffer. |
| 8364 | |
| 8365 | (setq magit-refresh-status-buffer nil) |
| 8366 | |
| 8367 | You should also check whether any third-party packages have added |
| 8368 | anything to ‘magit-refresh-buffer-hook’, ‘magit-pre-refresh-hook’, and |
| 8369 | ‘magit-post-refresh-hook’. If so, then check whether those additions |
| 8370 | impact performance significantly. |
| 8371 | |
| 8372 | Magit can be told to refresh buffers verbosely using ‘M-x |
| 8373 | magit-toggle-verbose-refresh’. Enabling this helps figuring out which |
| 8374 | sections are bottlenecks. Each line printed to the ‘*Messages*’ buffer |
| 8375 | contains a section name, the number of seconds it took to show this |
| 8376 | section, and from 0 to 2 exclamation marks: the more exclamation marks |
| 8377 | the slower the section is. |
| 8378 | |
| 8379 | Magit also reverts buffers for visited files located inside the |
| 8380 | current repository when the visited file changes on disk. That is |
| 8381 | implemented on top of ‘auto-revert-mode’ from the built-in library |
| 8382 | ‘autorevert’. To figure out whether that impacts performance, check |
| 8383 | whether performance is significantly worse, when many buffers exist |
| 8384 | and/or when some buffers visit files using TRAMP. If so, then this |
| 8385 | should help. |
| 8386 | |
| 8387 | (setq auto-revert-buffer-list-filter |
| 8388 | 'magit-auto-revert-repository-buffer-p) |
| 8389 | |
| 8390 | For alternative approaches see *note Automatic Reverting of |
| 8391 | File-Visiting Buffers::. |
| 8392 | |
| 8393 | If you have enabled any features that are disabled by default, then |
| 8394 | you should check whether they impact performance significantly. It's |
| 8395 | likely that they were not enabled by default because it is known that |
| 8396 | they reduce performance at least in large repositories. |
| 8397 | |
| 8398 | If performance is only slow inside certain unusually large |
| 8399 | repositories, then you might want to disable certain features on a |
| 8400 | per-repository or per-repository-class basis only. See *note |
| 8401 | Per-Repository Configuration::. For example it takes a long time to |
| 8402 | determine the next and current tag in repository with exceptional |
| 8403 | numbers of tags. It would therefore be a good idea to disable |
| 8404 | ‘magit-insert-tags-headers’, as explained at the mentioned node. |
| 8405 | |
| 8406 | Log Performance |
| 8407 | ............... |
| 8408 | |
| 8409 | When showing logs, Magit limits the number of commits initially shown in |
| 8410 | the hope that this avoids unnecessary work. When ‘--graph’ is used, |
| 8411 | then this unfortunately does not have the desired effect for large |
| 8412 | histories. Junio, Git's maintainer, said on the Git mailing list |
| 8413 | (<https://www.spinics.net/lists/git/msg232230.html>): "‘--graph’ wants |
| 8414 | to compute the whole history and the max-count only affects the output |
| 8415 | phase after ‘--graph’ does its computation". |
| 8416 | |
| 8417 | In other words, it's not that Git is slow at outputting the |
| 8418 | differences, or that Magit is slow at parsing the output - the problem |
| 8419 | is that Git first goes outside and has a smoke. |
| 8420 | |
| 8421 | We actually work around this issue by limiting the number of commits |
| 8422 | not only by using ‘-<N>’ but by also using a range. But unfortunately |
| 8423 | that's not always possible. |
| 8424 | |
| 8425 | When more than a few thousand commits are shown, then the use of |
| 8426 | ‘--graph’ can slow things down. |
| 8427 | |
| 8428 | Using ‘--color --graph’ is even slower. Magit uses code that is part |
| 8429 | of Emacs to turn control characters into faces. That code is pretty |
| 8430 | slow and this is quite noticeable when showing a log with many branches |
| 8431 | and merges. For that reason ‘--color’ is not enabled by default |
| 8432 | anymore. Consider leaving it at that. |
| 8433 | |
| 8434 | Diff Performance |
| 8435 | ................ |
| 8436 | |
| 8437 | If diffs are slow, then consider turning off some optional diff features |
| 8438 | by setting all or some of the following variables to ‘nil’: |
| 8439 | ‘magit-diff-highlight-indentation’, ‘magit-diff-highlight-trailing’, |
| 8440 | ‘magit-diff-paint-whitespace’, ‘magit-diff-highlight-hunk-body’, and |
| 8441 | ‘magit-diff-refine-hunk’. |
| 8442 | |
| 8443 | When showing a commit instead of some arbitrary diff, then some |
| 8444 | additional information is displayed. Calculating this information can |
| 8445 | be quite expensive given certain circumstances. If looking at a commit |
| 8446 | using ‘magit-revision-mode’ takes considerably more time than looking at |
| 8447 | the same commit in ‘magit-diff-mode’, then consider setting |
| 8448 | ‘magit-revision-insert-related-refs’ to ‘nil’. |
| 8449 | |
| 8450 | When you are often confronted with diffs that contain deleted files, |
| 8451 | then you might want to enable the ‘--irreversible-delete’ argument. If |
| 8452 | you do that then diffs still show that a file was deleted but without |
| 8453 | also showing the complete deleted content of the file. This argument is |
| 8454 | not available by default, see *note (transient)Enabling and Disabling |
| 8455 | Suffixes::. Once you have done that you should enable it and save that |
| 8456 | setting, see *note (transient)Saving Values::. You should do this in |
| 8457 | both the diff (‘d’) and the diff refresh (‘D’) transient popups. |
| 8458 | |
| 8459 | Refs Buffer Performance |
| 8460 | ....................... |
| 8461 | |
| 8462 | When refreshing the "references buffer" is slow, then that's usually |
| 8463 | because several hundred refs are being displayed. The best way to |
| 8464 | address that is to display fewer refs, obviously. |
| 8465 | |
| 8466 | If you are not, or only mildly, interested in seeing the list of |
| 8467 | tags, then start by not displaying them: |
| 8468 | |
| 8469 | (remove-hook 'magit-refs-sections-hook 'magit-insert-tags) |
| 8470 | |
| 8471 | Then you should also make sure that the listed remote branches |
| 8472 | actually all exist. You can do so by pruning branches which no longer |
| 8473 | exist using ‘f-pa’. |
| 8474 | |
| 8475 | Committing Performance |
| 8476 | ...................... |
| 8477 | |
| 8478 | When you initiate a commit, then Magit by default automatically shows a |
| 8479 | diff of the changes you are about to commit. For large commits this can |
| 8480 | take a long time, which is especially distracting when you are |
| 8481 | committing large amounts of generated data which you don't actually |
| 8482 | intend to inspect before committing. This behavior can be turned off |
| 8483 | using: |
| 8484 | |
| 8485 | (remove-hook 'server-switch-hook 'magit-commit-diff) |
| 8486 | (remove-hook 'with-editor-filter-visit-hook 'magit-commit-diff) |
| 8487 | |
| 8488 | Then you can type ‘C-c C-d’ to show the diff when you actually want |
| 8489 | to see it, but only then. Alternatively you can leave the hook alone |
| 8490 | and just type ‘C-g’ in those cases when it takes too long to generate |
| 8491 | the diff. If you do that, then you will end up with a broken diff |
| 8492 | buffer, but doing it this way has the advantage that you usually get to |
| 8493 | see the diff, which is useful because it increases the odds that you |
| 8494 | spot potential issues. |
| 8495 | |
| 8496 | Microsoft Windows Performance |
| 8497 | ............................. |
| 8498 | |
| 8499 | In order to update the status buffer, ‘git’ has to be run a few dozen |
| 8500 | times. That is problematic on Microsoft Windows, because that operating |
| 8501 | system is exceptionally slow at starting processes. Sadly this is an |
| 8502 | issue that can only be fixed by Microsoft itself, and they don't appear |
| 8503 | to be particularly interested in doing so. |
| 8504 | |
| 8505 | Beside the subprocess issue, there are also other Windows-specific |
| 8506 | performance issues. Some of these have workarounds. The maintainers of |
| 8507 | "Git for Windows" try to improve performance on Windows. Always use the |
| 8508 | latest release in order to benefit from the latest performance tweaks. |
| 8509 | Magit too tries to work around some Windows-specific issues. |
| 8510 | |
| 8511 | According to some sources, setting the following Git variables can |
| 8512 | also help. |
| 8513 | |
| 8514 | git config --global core.preloadindex true # default since v2.1 |
| 8515 | git config --global core.fscache true # default since v2.8 |
| 8516 | git config --global gc.auto 256 |
| 8517 | |
| 8518 | You should also check whether an anti-virus program is affecting |
| 8519 | performance. |
| 8520 | |
| 8521 | MacOS Performance |
| 8522 | ................. |
| 8523 | |
| 8524 | Before Emacs 26.1 child processes were created using ‘fork’ on macOS. |
| 8525 | That needlessly copied GUI resources, which is expensive. The result |
| 8526 | was that forking took about 30 times as long on Darwin than on Linux, |
| 8527 | and because Magit starts many ‘git’ processes that made quite a |
| 8528 | difference. |
| 8529 | |
| 8530 | So make sure that you are using at least Emacs 26.1, in which case |
| 8531 | the faster ‘vfork’ will be used. (The creation of child processes still |
| 8532 | takes about twice as long on Darwin compared to Linux.) See (1) for |
| 8533 | more information. |
| 8534 | |
| 8535 | Additionally, ‘git’ installed from a package manager like ‘brew’ or |
| 8536 | ‘nix’ seems to be slower than the native executable. Profile the ‘git’ |
| 8537 | executable you're running against the one at ‘/usr/bin/git’, and if you |
| 8538 | notice a notable difference try using the latter as |
| 8539 | ‘magit-git-executable’. |
| 8540 | |
| 8541 | 9.2.3 Global Bindings |
| 8542 | --------------------- |
| 8543 | |
| 8544 | -- User Option: magit-define-global-key-bindings |
| 8545 | This option controls which set of Magit key bindings, if any, may |
| 8546 | be added to the global keymap, even before Magit is first used in |
| 8547 | the current Emacs session. |
| 8548 | |
| 8549 | • If the value is ‘nil’, no bindings are added. |
| 8550 | |
| 8551 | • If ‘default’, maybe add: |
| 8552 | |
| 8553 | ‘C-x g’ ‘magit-status’ |
| 8554 | ‘C-x M-g’ ‘magit-dispatch’ |
| 8555 | ‘C-c M-g’ ‘magit-file-dispatch’ |
| 8556 | |
| 8557 | • If ‘recommended’, maybe add: |
| 8558 | |
| 8559 | ‘C-x g’ ‘magit-status’ |
| 8560 | ‘C-c g’ ‘magit-dispatch’ |
| 8561 | ‘C-c f’ ‘magit-file-dispatch’ |
| 8562 | |
| 8563 | These bindings are strongly recommended, but we cannot use |
| 8564 | them by default, because the ‘C-c <LETTER>’ namespace is |
| 8565 | strictly reserved for bindings added by the user (see *note |
| 8566 | (elisp)Key Binding Conventions::). |
| 8567 | |
| 8568 | The bindings in the chosen set may be added when ‘after-init-hook’ |
| 8569 | is run. Each binding is added if, and only if, at that time no |
| 8570 | other key is bound to the same command, and no other command is |
| 8571 | bound to the same key. In other words we try to avoid adding |
| 8572 | bindings that are unnecessary, as well as bindings that conflict |
| 8573 | with other bindings. |
| 8574 | |
| 8575 | Adding these bindings is delayed until ‘after-init-hook’ is run to |
| 8576 | allow users to set the variable anywhere in their init file |
| 8577 | (without having to make sure to do so before ‘magit’ is loaded or |
| 8578 | autoloaded) and to increase the likelihood that all the potentially |
| 8579 | conflicting user bindings have already been added. |
| 8580 | |
| 8581 | To set this variable use either ‘setq’ or the Custom interface. Do |
| 8582 | not use the function ‘customize-set-variable’ because doing that |
| 8583 | would cause Magit to be loaded immediately, when that form is |
| 8584 | evaluated (this differs from ‘custom-set-variables’, which doesn't |
| 8585 | load the libraries that define the customized variables). |
| 8586 | |
| 8587 | Setting this variable has no effect if ‘after-init-hook’ has |
| 8588 | already been run. |
| 8589 | |
| 8590 | ---------- Footnotes ---------- |
| 8591 | |
| 8592 | (1) |
| 8593 | <https://lists.gnu.org/archive/html/bug-gnu-emacs/2017-04/msg00201.html> |
| 8594 | |
| 8595 | |
| 8596 | File: magit.info, Node: Plumbing, Next: FAQ, Prev: Customizing, Up: Top |
| 8597 | |
| 8598 | 10 Plumbing |
| 8599 | *********** |
| 8600 | |
| 8601 | The following sections describe how to use several of Magit's core |
| 8602 | abstractions to extend Magit itself or implement a separate extension. |
| 8603 | |
| 8604 | A few of the low-level features used by Magit have been factored out |
| 8605 | into separate libraries/packages, so that they can be used by other |
| 8606 | packages, without having to depend on Magit. See *note |
| 8607 | (with-editor)Top:: for information about ‘with-editor’. ‘transient’ |
| 8608 | doesn't have a manual yet. |
| 8609 | |
| 8610 | If you are trying to find an unused key that you can bind to a |
| 8611 | command provided by your own Magit extension, then checkout |
| 8612 | <https://github.com/magit/magit/wiki/Plugin-Dispatch-Key-Registry>. |
| 8613 | |
| 8614 | * Menu: |
| 8615 | |
| 8616 | * Calling Git:: |
| 8617 | * Section Plumbing:: |
| 8618 | * Refreshing Buffers:: |
| 8619 | * Conventions:: |
| 8620 | |
| 8621 | |
| 8622 | File: magit.info, Node: Calling Git, Next: Section Plumbing, Up: Plumbing |
| 8623 | |
| 8624 | 10.1 Calling Git |
| 8625 | ================ |
| 8626 | |
| 8627 | Magit provides many specialized functions for calling Git. All of these |
| 8628 | functions are defined in either ‘magit-git.el’ or ‘magit-process.el’ and |
| 8629 | have one of the prefixes ‘magit-run-’, ‘magit-call-’, ‘magit-start-’, or |
| 8630 | ‘magit-git-’ (which is also used for other things). |
| 8631 | |
| 8632 | All of these functions accept an indefinite number of arguments, |
| 8633 | which are strings that specify command line arguments for Git (or in |
| 8634 | some cases an arbitrary executable). These arguments are flattened |
| 8635 | before being passed on to the executable; so instead of strings they can |
| 8636 | also be lists of strings and arguments that are ‘nil’ are silently |
| 8637 | dropped. Some of these functions also require a single mandatory |
| 8638 | argument before these command line arguments. |
| 8639 | |
| 8640 | Roughly speaking, these functions run Git either to get some value or |
| 8641 | for side-effects. The functions that return a value are useful to |
| 8642 | collect the information necessary to populate a Magit buffer, while the |
| 8643 | others are used to implement Magit commands. |
| 8644 | |
| 8645 | The functions in the value-only group always run synchronously, and |
| 8646 | they never trigger a refresh. The function in the side-effect group can |
| 8647 | be further divided into subgroups depending on whether they run Git |
| 8648 | synchronously or asynchronously, and depending on whether they trigger a |
| 8649 | refresh when the executable has finished. |
| 8650 | |
| 8651 | 10.1.1 Getting a Value from Git |
| 8652 | ------------------------------- |
| 8653 | |
| 8654 | These functions run Git in order to get a value, an exit status, or |
| 8655 | output. Of course you could also use them to run Git commands that have |
| 8656 | side-effects, but that should be avoided. |
| 8657 | |
| 8658 | -- Function: magit-git-exit-code &rest args |
| 8659 | Executes git with ARGS and returns its exit code. |
| 8660 | |
| 8661 | -- Function: magit-git-success &rest args |
| 8662 | Executes git with ARGS and returns ‘t’ if the exit code is ‘0’, |
| 8663 | ‘nil’ otherwise. |
| 8664 | |
| 8665 | -- Function: magit-git-failure &rest args |
| 8666 | Executes git with ARGS and returns ‘t’ if the exit code is ‘1’, |
| 8667 | ‘nil’ otherwise. |
| 8668 | |
| 8669 | -- Function: magit-git-true &rest args |
| 8670 | Executes git with ARGS and returns ‘t’ if the first line printed by |
| 8671 | git is the string "true", ‘nil’ otherwise. |
| 8672 | |
| 8673 | -- Function: magit-git-false &rest args |
| 8674 | Executes git with ARGS and returns ‘t’ if the first line printed by |
| 8675 | git is the string "false", ‘nil’ otherwise. |
| 8676 | |
| 8677 | -- Function: magit-git-insert &rest args |
| 8678 | Executes git with ARGS and inserts its output at point. |
| 8679 | |
| 8680 | -- Function: magit-git-string &rest args |
| 8681 | Executes git with ARGS and returns the first line of its output. |
| 8682 | If there is no output or if it begins with a newline character, |
| 8683 | then this returns ‘nil’. |
| 8684 | |
| 8685 | -- Function: magit-git-lines &rest args |
| 8686 | Executes git with ARGS and returns its output as a list of lines. |
| 8687 | Empty lines anywhere in the output are omitted. |
| 8688 | |
| 8689 | -- Function: magit-git-items &rest args |
| 8690 | Executes git with ARGS and returns its null-separated output as a |
| 8691 | list. Empty items anywhere in the output are omitted. |
| 8692 | |
| 8693 | If the value of option ‘magit-git-debug’ is non-‘nil’ and git exits |
| 8694 | with a non-zero exit status, then warn about that in the echo area |
| 8695 | and add a section containing git's standard error in the current |
| 8696 | repository's process buffer. |
| 8697 | |
| 8698 | -- Function: magit-process-git destination &rest args |
| 8699 | Calls Git synchronously in a separate process, returning its exit |
| 8700 | code. DESTINATION specifies how to handle the output, like for |
| 8701 | ‘call-process’, except that file handlers are supported. Enables |
| 8702 | Cygwin's "noglob" option during the call and ensures unix eol |
| 8703 | conversion. |
| 8704 | |
| 8705 | -- Function: magit-process-file process &optional infile buffer display |
| 8706 | &rest args |
| 8707 | Processes files synchronously in a separate process. Identical to |
| 8708 | ‘process-file’ but temporarily enables Cygwin's "noglob" option |
| 8709 | during the call and ensures unix eol conversion. |
| 8710 | |
| 8711 | If an error occurs when using one of the above functions, then that |
| 8712 | is usually due to a bug, i.e., using an argument which is not actually |
| 8713 | supported. Such errors are usually not reported, but when they occur we |
| 8714 | need to be able to debug them. |
| 8715 | |
| 8716 | -- User Option: magit-git-debug |
| 8717 | Whether to report errors that occur when using ‘magit-git-insert’, |
| 8718 | ‘magit-git-string’, ‘magit-git-lines’, or ‘magit-git-items’. This |
| 8719 | does not actually raise an error. Instead a message is shown in |
| 8720 | the echo area, and git's standard error is insert into a new |
| 8721 | section in the current repository's process buffer. |
| 8722 | |
| 8723 | -- Function: magit-git-str &rest args |
| 8724 | This is a variant of ‘magit-git-string’ that ignores the option |
| 8725 | ‘magit-git-debug’. It is mainly intended to be used while handling |
| 8726 | errors in functions that do respect that option. Using such a |
| 8727 | function while handing an error could cause yet another error and |
| 8728 | therefore lead to an infinite recursion. You probably won't ever |
| 8729 | need to use this function. |
| 8730 | |
| 8731 | 10.1.2 Calling Git for Effect |
| 8732 | ----------------------------- |
| 8733 | |
| 8734 | These functions are used to run git to produce some effect. Most Magit |
| 8735 | commands that actually run git do so by using such a function. |
| 8736 | |
| 8737 | Because we do not need to consume git's output when using these |
| 8738 | functions, their output is instead logged into a per-repository buffer, |
| 8739 | which can be shown using ‘$’ from a Magit buffer or ‘M-x magit-process’ |
| 8740 | elsewhere. |
| 8741 | |
| 8742 | These functions can have an effect in two distinct ways. Firstly, |
| 8743 | running git may change something, i.e., create or push a new commit. |
| 8744 | Secondly, that change may require that Magit buffers are refreshed to |
| 8745 | reflect the changed state of the repository. But refreshing isn't |
| 8746 | always desirable, so only some of these functions do perform such a |
| 8747 | refresh after git has returned. |
| 8748 | |
| 8749 | Sometimes it is useful to run git asynchronously. For example, when |
| 8750 | the user has just initiated a push, then there is no reason to make her |
| 8751 | wait until that has completed. In other cases it makes sense to wait |
| 8752 | for git to complete before letting the user do something else. For |
| 8753 | example after staging a change it is useful to wait until after the |
| 8754 | refresh because that also automatically moves to the next change. |
| 8755 | |
| 8756 | The synchronous functions return the exit code, while the |
| 8757 | asynchronous functions return the process object. |
| 8758 | |
| 8759 | -- Function: magit-call-git &rest args |
| 8760 | Calls git synchronously with ARGS. |
| 8761 | |
| 8762 | This function runs the hooks ‘magit-pre-call-git-hook’ and |
| 8763 | ‘magit-post-call-git-functions’. Since ‘magit-run-git’ and |
| 8764 | ‘magit-git’ use this function, they too run these hooks. |
| 8765 | |
| 8766 | -- Function: magit-call-process program &rest args |
| 8767 | Calls PROGRAM synchronously with ARGS. |
| 8768 | |
| 8769 | -- Function: magit-run-git &rest args |
| 8770 | Calls git synchronously with ARGS and then refreshes. |
| 8771 | |
| 8772 | -- Function: magit-run-git-with-input &rest args |
| 8773 | Calls git synchronously with ARGS and sends it the content of the |
| 8774 | current buffer on standard input. |
| 8775 | |
| 8776 | If the current buffer's ‘default-directory’ is on a remote |
| 8777 | filesystem, this function actually runs git asynchronously. But |
| 8778 | then it waits for the process to return, so the function itself is |
| 8779 | synchronous. |
| 8780 | |
| 8781 | -- Function: magit-git &rest args |
| 8782 | Calls git synchronously with ARGS for side-effects only. This |
| 8783 | function does not refresh the buffer. |
| 8784 | |
| 8785 | -- Function: magit-git-wash washer &rest args |
| 8786 | Execute Git with ARGS, inserting washed output at point. Actually |
| 8787 | first insert the raw output at point. If there is no output call |
| 8788 | ‘magit-cancel-section’. Otherwise temporarily narrow the buffer to |
| 8789 | the inserted text, move to its beginning, and then call function |
| 8790 | WASHER with ARGS as its sole argument. |
| 8791 | |
| 8792 | And now for the asynchronous variants. |
| 8793 | |
| 8794 | -- Function: magit-run-git-async &rest args |
| 8795 | Start Git, prepare for refresh, and return the process object. |
| 8796 | ARGS is flattened and then used as arguments to Git. |
| 8797 | |
| 8798 | Display the command line arguments in the echo area. |
| 8799 | |
| 8800 | After Git returns some buffers are refreshed: the buffer that was |
| 8801 | current when this function was called (if it is a Magit buffer and |
| 8802 | still alive), as well as the respective Magit status buffer. |
| 8803 | Unmodified buffers visiting files that are tracked in the current |
| 8804 | repository are reverted if ‘magit-revert-buffers’ is non-‘nil’. |
| 8805 | |
| 8806 | -- Function: magit-run-git-with-editor &rest args |
| 8807 | Export GIT_EDITOR and start Git. Also prepare for refresh and |
| 8808 | return the process object. ARGS is flattened and then used as |
| 8809 | arguments to Git. |
| 8810 | |
| 8811 | Display the command line arguments in the echo area. |
| 8812 | |
| 8813 | After Git returns some buffers are refreshed: the buffer that was |
| 8814 | current when this function was called (if it is a Magit buffer and |
| 8815 | still alive), as well as the respective Magit status buffer. |
| 8816 | |
| 8817 | -- Function: magit-start-git input &rest args |
| 8818 | Start Git, prepare for refresh, and return the process object. |
| 8819 | |
| 8820 | If INPUT is non-‘nil’, it has to be a buffer or the name of an |
| 8821 | existing buffer. The buffer content becomes the processes standard |
| 8822 | input. |
| 8823 | |
| 8824 | Option ‘magit-git-executable’ specifies the Git executable and |
| 8825 | option ‘magit-git-global-arguments’ specifies constant arguments. |
| 8826 | The remaining arguments ARGS specify arguments to Git. They are |
| 8827 | flattened before use. |
| 8828 | |
| 8829 | After Git returns, some buffers are refreshed: the buffer that was |
| 8830 | current when this function was called (if it is a Magit buffer and |
| 8831 | still alive), as well as the respective Magit status buffer. |
| 8832 | Unmodified buffers visiting files that are tracked in the current |
| 8833 | repository are reverted if ‘magit-revert-buffers’ is non-‘nil’. |
| 8834 | |
| 8835 | -- Function: magit-start-process &rest args |
| 8836 | Start PROGRAM, prepare for refresh, and return the process object. |
| 8837 | |
| 8838 | If optional argument INPUT is non-‘nil’, it has to be a buffer or |
| 8839 | the name of an existing buffer. The buffer content becomes the |
| 8840 | processes standard input. |
| 8841 | |
| 8842 | The process is started using ‘start-file-process’ and then setup to |
| 8843 | use the sentinel ‘magit-process-sentinel’ and the filter |
| 8844 | ‘magit-process-filter’. Information required by these functions is |
| 8845 | stored in the process object. When this function returns the |
| 8846 | process has not started to run yet so it is possible to override |
| 8847 | the sentinel and filter. |
| 8848 | |
| 8849 | After the process returns, ‘magit-process-sentinel’ refreshes the |
| 8850 | buffer that was current when ‘magit-start-process’ was called (if |
| 8851 | it is a Magit buffer and still alive), as well as the respective |
| 8852 | Magit status buffer. Unmodified buffers visiting files that are |
| 8853 | tracked in the current repository are reverted if |
| 8854 | ‘magit-revert-buffers’ is non-‘nil’. |
| 8855 | |
| 8856 | -- Variable: magit-this-process |
| 8857 | The child process which is about to start. This can be used to |
| 8858 | change the filter and sentinel. |
| 8859 | |
| 8860 | -- Variable: magit-process-raise-error |
| 8861 | When this is non-‘nil’, then ‘magit-process-sentinel’ raises an |
| 8862 | error if git exits with a non-zero exit status. For debugging |
| 8863 | purposes. |
| 8864 | |
| 8865 | |
| 8866 | File: magit.info, Node: Section Plumbing, Next: Refreshing Buffers, Prev: Calling Git, Up: Plumbing |
| 8867 | |
| 8868 | 10.2 Section Plumbing |
| 8869 | ===================== |
| 8870 | |
| 8871 | 10.2.1 Creating Sections |
| 8872 | ------------------------ |
| 8873 | |
| 8874 | -- Macro: magit-insert-section &rest args |
| 8875 | Insert a section at point. |
| 8876 | |
| 8877 | TYPE is the section type, a symbol. Many commands that act on the |
| 8878 | current section behave differently depending on that type. Also if |
| 8879 | a variable ‘magit-TYPE-section-map’ exists, then use that as the |
| 8880 | text-property ‘keymap’ of all text belonging to the section (but |
| 8881 | this may be overwritten in subsections). TYPE can also have the |
| 8882 | form ‘(eval FORM)’ in which case FORM is evaluated at runtime. |
| 8883 | |
| 8884 | Optional VALUE is the value of the section, usually a string that |
| 8885 | is required when acting on the section. |
| 8886 | |
| 8887 | When optional HIDE is non-‘nil’ collapse the section body by |
| 8888 | default, i.e., when first creating the section, but not when |
| 8889 | refreshing the buffer. Otherwise, expand it by default. This can |
| 8890 | be overwritten using ‘magit-section-set-visibility-hook’. When a |
| 8891 | section is recreated during a refresh, then the visibility of |
| 8892 | predecessor is inherited and HIDE is ignored (but the hook is still |
| 8893 | honored). |
| 8894 | |
| 8895 | BODY is any number of forms that actually insert the section's |
| 8896 | heading and body. Optional NAME, if specified, has to be a symbol, |
| 8897 | which is then bound to the struct of the section being inserted. |
| 8898 | |
| 8899 | Before BODY is evaluated the ‘start’ of the section object is set |
| 8900 | to the value of ‘point’ and after BODY was evaluated its ‘end’ is |
| 8901 | set to the new value of ‘point’; BODY is responsible for moving |
| 8902 | ‘point’ forward. |
| 8903 | |
| 8904 | If it turns out inside BODY that the section is empty, then |
| 8905 | ‘magit-cancel-section’ can be used to abort and remove all traces |
| 8906 | of the partially inserted section. This can happen when creating a |
| 8907 | section by washing Git's output and Git didn't actually output |
| 8908 | anything this time around. |
| 8909 | |
| 8910 | -- Function: magit-insert-heading &rest args |
| 8911 | Insert the heading for the section currently being inserted. |
| 8912 | |
| 8913 | This function should only be used inside ‘magit-insert-section’. |
| 8914 | |
| 8915 | When called without any arguments, then just set the ‘content’ slot |
| 8916 | of the object representing the section being inserted to a marker |
| 8917 | at ‘point’. The section should only contain a single line when |
| 8918 | this function is used like this. |
| 8919 | |
| 8920 | When called with arguments ARGS, which have to be strings, then |
| 8921 | insert those strings at point. The section should not contain any |
| 8922 | text before this happens and afterwards it should again only |
| 8923 | contain a single line. If the ‘face’ property is set anywhere |
| 8924 | inside any of these strings, then insert all of them unchanged. |
| 8925 | Otherwise use the ‘magit-section-heading’ face for all inserted |
| 8926 | text. |
| 8927 | |
| 8928 | The ‘content’ property of the section struct is the end of the |
| 8929 | heading (which lasts from ‘start’ to ‘content’) and the beginning |
| 8930 | of the body (which lasts from ‘content’ to ‘end’). If the value of |
| 8931 | ‘content’ is ‘nil’, then the section has no heading and its body |
| 8932 | cannot be collapsed. If a section does have a heading then its |
| 8933 | height must be exactly one line, including a trailing newline |
| 8934 | character. This isn't enforced; you are responsible for getting it |
| 8935 | right. The only exception is that this function does insert a |
| 8936 | newline character if necessary. |
| 8937 | |
| 8938 | -- Function: magit-cancel-section |
| 8939 | Cancel the section currently being inserted. This exits the |
| 8940 | innermost call to ‘magit-insert-section’ and removes all traces of |
| 8941 | what has already happened inside that call. |
| 8942 | |
| 8943 | -- Function: magit-define-section-jumper sym title &optional value |
| 8944 | Define an interactive function to go to section SYM. TITLE is the |
| 8945 | displayed title of the section. |
| 8946 | |
| 8947 | 10.2.2 Section Selection |
| 8948 | ------------------------ |
| 8949 | |
| 8950 | -- Function: magit-current-section |
| 8951 | Return the section at point. |
| 8952 | |
| 8953 | -- Function: magit-region-sections &optional condition multiple |
| 8954 | Return a list of the selected sections. |
| 8955 | |
| 8956 | When the region is active and constitutes a valid section |
| 8957 | selection, then return a list of all selected sections. This is |
| 8958 | the case when the region begins in the heading of a section and |
| 8959 | ends in the heading of the same section or in that of a sibling |
| 8960 | section. If optional MULTIPLE is non-‘nil’, then the region cannot |
| 8961 | begin and end in the same section. |
| 8962 | |
| 8963 | When the selection is not valid, then return ‘nil’. In this case, |
| 8964 | most commands that can act on the selected sections will instead |
| 8965 | act on the section at point. |
| 8966 | |
| 8967 | When the region looks like it would in any other buffer then the |
| 8968 | selection is invalid. When the selection is valid then the region |
| 8969 | uses the ‘magit-section-highlight’ face. This does not apply to |
| 8970 | diffs where things get a bit more complicated, but even here if the |
| 8971 | region looks like it usually does, then that's not a valid |
| 8972 | selection as far as this function is concerned. |
| 8973 | |
| 8974 | If optional CONDITION is non-‘nil’, then the selection not only has |
| 8975 | to be valid; all selected sections additionally have to match |
| 8976 | CONDITION, or ‘nil’ is returned. See ‘magit-section-match’ for the |
| 8977 | forms CONDITION can take. |
| 8978 | |
| 8979 | -- Function: magit-region-values &optional condition multiple |
| 8980 | Return a list of the values of the selected sections. |
| 8981 | |
| 8982 | Return the values that themselves would be returned by |
| 8983 | ‘magit-region-sections’ (which see). |
| 8984 | |
| 8985 | 10.2.3 Matching Sections |
| 8986 | ------------------------ |
| 8987 | |
| 8988 | ‘M-x magit-describe-section-briefly’ |
| 8989 | Show information about the section at point. This command is |
| 8990 | intended for debugging purposes. |
| 8991 | |
| 8992 | -- Function: magit-section-ident section |
| 8993 | Return an unique identifier for SECTION. The return value has the |
| 8994 | form ‘((TYPE . VALUE)...)’. |
| 8995 | |
| 8996 | -- Function: magit-get-section ident &optional root |
| 8997 | Return the section identified by IDENT. IDENT has to be a list as |
| 8998 | returned by ‘magit-section-ident’. |
| 8999 | |
| 9000 | -- Function: magit-section-match condition &optional section |
| 9001 | Return ‘t’ if SECTION matches CONDITION. SECTION defaults to the |
| 9002 | section at point. If SECTION is not specified and there also is no |
| 9003 | section at point, then return ‘nil’. |
| 9004 | |
| 9005 | CONDITION can take the following forms: |
| 9006 | • ‘(CONDITION...)’ |
| 9007 | |
| 9008 | matches if any of the CONDITIONs matches. |
| 9009 | |
| 9010 | • ‘[CLASS...]’ |
| 9011 | |
| 9012 | matches if the section's class is the same as the first CLASS |
| 9013 | or a subclass of that; the section's parent class matches the |
| 9014 | second CLASS; and so on. |
| 9015 | |
| 9016 | • ‘[* CLASS...]’ |
| 9017 | |
| 9018 | matches sections that match ‘[CLASS...]’ and also recursively |
| 9019 | all their child sections. |
| 9020 | |
| 9021 | • ‘CLASS’ |
| 9022 | |
| 9023 | matches if the section's class is the same as CLASS or a |
| 9024 | subclass of that; regardless of the classes of the parent |
| 9025 | sections. |
| 9026 | |
| 9027 | Each CLASS should be a class symbol, identifying a class that |
| 9028 | derives from ‘magit-section’. For backward compatibility CLASS can |
| 9029 | also be a "type symbol". A section matches such a symbol if the |
| 9030 | value of its ‘type’ slot is ‘eq’. If a type symbol has an entry in |
| 9031 | ‘magit--section-type-alist’, then a section also matches that type |
| 9032 | if its class is a subclass of the class that corresponds to the |
| 9033 | type as per that alist. |
| 9034 | |
| 9035 | Note that it is not necessary to specify the complete section |
| 9036 | lineage as printed by ‘magit-describe-section-briefly’, unless of |
| 9037 | course you want to be that precise. |
| 9038 | |
| 9039 | -- Function: magit-section-value-if condition &optional section |
| 9040 | If the section at point matches CONDITION, then return its value. |
| 9041 | |
| 9042 | If optional SECTION is non-‘nil’ then test whether that matches |
| 9043 | instead. If there is no section at point and SECTION is ‘nil’, |
| 9044 | then return ‘nil’. If the section does not match, then return |
| 9045 | ‘nil’. |
| 9046 | |
| 9047 | See ‘magit-section-match’ for the forms CONDITION can take. |
| 9048 | |
| 9049 | -- Function: magit-section-case &rest clauses |
| 9050 | Choose among clauses on the type of the section at point. |
| 9051 | |
| 9052 | Each clause looks like (CONDITION BODY...). The type of the |
| 9053 | section is compared against each CONDITION; the BODY forms of the |
| 9054 | first match are evaluated sequentially and the value of the last |
| 9055 | form is returned. Inside BODY the symbol ‘it’ is bound to the |
| 9056 | section at point. If no clause succeeds or if there is no section |
| 9057 | at point return ‘nil’. |
| 9058 | |
| 9059 | See ‘magit-section-match’ for the forms CONDITION can take. |
| 9060 | Additionally a CONDITION of ‘t’ is allowed in the final clause and |
| 9061 | matches if no other CONDITION match, even if there is no section at |
| 9062 | point. |
| 9063 | |
| 9064 | -- Variable: magit-root-section |
| 9065 | The root section in the current buffer. All other sections are |
| 9066 | descendants of this section. The value of this variable is set by |
| 9067 | ‘magit-insert-section’ and you should never modify it. |
| 9068 | |
| 9069 | For diff related sections a few additional tools exist. |
| 9070 | |
| 9071 | -- Function: magit-diff-type &optional section |
| 9072 | Return the diff type of SECTION. |
| 9073 | |
| 9074 | The returned type is one of the symbols ‘staged’, ‘unstaged’, |
| 9075 | ‘committed’, or ‘undefined’. This type serves a similar purpose as |
| 9076 | the general type common to all sections (which is stored in the |
| 9077 | ‘type’ slot of the corresponding ‘magit-section’ struct) but takes |
| 9078 | additional information into account. When the SECTION isn't |
| 9079 | related to diffs and the buffer containing it also isn't a |
| 9080 | diff-only buffer, then return ‘nil’. |
| 9081 | |
| 9082 | Currently the type can also be one of ‘tracked’ and ‘untracked’, |
| 9083 | but these values are not handled explicitly in every place they |
| 9084 | should be. A possible fix could be to just return ‘nil’ here. |
| 9085 | |
| 9086 | The section has to be a ‘diff’ or ‘hunk’ section, or a section |
| 9087 | whose children are of type ‘diff’. If optional SECTION is ‘nil’, |
| 9088 | return the diff type for the current section. In buffers whose |
| 9089 | major mode is ‘magit-diff-mode’ SECTION is ignored and the type is |
| 9090 | determined using other means. In ‘magit-revision-mode’ buffers the |
| 9091 | type is always ‘committed’. |
| 9092 | |
| 9093 | -- Function: magit-diff-scope &optional section strict |
| 9094 | Return the diff scope of SECTION or the selected section(s). |
| 9095 | |
| 9096 | A diff's "scope" describes what part of a diff is selected, it is a |
| 9097 | symbol, one of ‘region’, ‘hunk’, ‘hunks’, ‘file’, ‘files’, or |
| 9098 | ‘list’. Do not confuse this with the diff "type", as returned by |
| 9099 | ‘magit-diff-type’. |
| 9100 | |
| 9101 | If optional SECTION is non-‘nil’, then return the scope of that, |
| 9102 | ignoring the sections selected by the region. Otherwise return the |
| 9103 | scope of the current section, or if the region is active and |
| 9104 | selects a valid group of diff related sections, the type of these |
| 9105 | sections, i.e., ‘hunks’ or ‘files’. If SECTION (or if the current |
| 9106 | section that is ‘nil’) is a ‘hunk’ section and the region starts |
| 9107 | and ends inside the body of a that section, then the type is |
| 9108 | ‘region’. |
| 9109 | |
| 9110 | If optional STRICT is non-‘nil’ then return ‘nil’ if the diff type |
| 9111 | of the section at point is ‘untracked’ or the section at point is |
| 9112 | not actually a ‘diff’ but a ‘diffstat’ section. |
| 9113 | |
| 9114 | |
| 9115 | File: magit.info, Node: Refreshing Buffers, Next: Conventions, Prev: Section Plumbing, Up: Plumbing |
| 9116 | |
| 9117 | 10.3 Refreshing Buffers |
| 9118 | ======================= |
| 9119 | |
| 9120 | All commands that create a new Magit buffer or change what is being |
| 9121 | displayed in an existing buffer do so by calling ‘magit-mode-setup’. |
| 9122 | Among other things, that function sets the buffer local values of |
| 9123 | ‘default-directory’ (to the top-level of the repository), |
| 9124 | ‘magit-refresh-function’, and ‘magit-refresh-args’. |
| 9125 | |
| 9126 | Buffers are refreshed by calling the function that is the local value |
| 9127 | of ‘magit-refresh-function’ (a function named ‘magit-*-refresh-buffer’, |
| 9128 | where ‘*’ may be something like ‘diff’) with the value of |
| 9129 | ‘magit-refresh-args’ as arguments. |
| 9130 | |
| 9131 | -- Macro: magit-mode-setup buffer switch-func mode refresh-func |
| 9132 | &optional refresh-args |
| 9133 | This function displays and selects BUFFER, turns on MODE, and |
| 9134 | refreshes a first time. |
| 9135 | |
| 9136 | This function displays and optionally selects BUFFER by calling |
| 9137 | ‘magit-mode-display-buffer’ with BUFFER, MODE and SWITCH-FUNC as |
| 9138 | arguments. Then it sets the local value of |
| 9139 | ‘magit-refresh-function’ to REFRESH-FUNC and that of |
| 9140 | ‘magit-refresh-args’ to REFRESH-ARGS. Finally it creates the |
| 9141 | buffer content by calling REFRESH-FUNC with REFRESH-ARGS as |
| 9142 | arguments. |
| 9143 | |
| 9144 | All arguments are evaluated before switching to BUFFER. |
| 9145 | |
| 9146 | -- Function: magit-mode-display-buffer buffer mode &optional |
| 9147 | switch-function |
| 9148 | This function display BUFFER in some window and select it. BUFFER |
| 9149 | may be a buffer or a string, the name of a buffer. The buffer is |
| 9150 | returned. |
| 9151 | |
| 9152 | Unless BUFFER is already displayed in the selected frame, store the |
| 9153 | previous window configuration as a buffer local value, so that it |
| 9154 | can later be restored by ‘magit-mode-bury-buffer’. |
| 9155 | |
| 9156 | The buffer is displayed and selected using SWITCH-FUNCTION. If |
| 9157 | that is ‘nil’ then ‘pop-to-buffer’ is used if the current buffer's |
| 9158 | major mode derives from ‘magit-mode’. Otherwise ‘switch-to-buffer’ |
| 9159 | is used. |
| 9160 | |
| 9161 | -- Variable: magit-refresh-function |
| 9162 | The value of this buffer-local variable is the function used to |
| 9163 | refresh the current buffer. It is called with ‘magit-refresh-args’ |
| 9164 | as arguments. |
| 9165 | |
| 9166 | -- Variable: magit-refresh-args |
| 9167 | The list of arguments used by ‘magit-refresh-function’ to refresh |
| 9168 | the current buffer. ‘magit-refresh-function’ is called with these |
| 9169 | arguments. |
| 9170 | |
| 9171 | The value is usually set using ‘magit-mode-setup’, but in some |
| 9172 | cases it's also useful to provide commands that can change the |
| 9173 | value. For example, the ‘magit-diff-refresh’ transient can be used |
| 9174 | to change any of the arguments used to display the diff, without |
| 9175 | having to specify again which differences should be shown, but |
| 9176 | ‘magit-diff-more-context’, ‘magit-diff-less-context’ and |
| 9177 | ‘magit-diff-default-context’ change just the ‘-U<N>’ argument. In |
| 9178 | both case this is done by changing the value of this variable and |
| 9179 | then calling this ‘magit-refresh-function’. |
| 9180 | |
| 9181 | |
| 9182 | File: magit.info, Node: Conventions, Prev: Refreshing Buffers, Up: Plumbing |
| 9183 | |
| 9184 | 10.4 Conventions |
| 9185 | ================ |
| 9186 | |
| 9187 | Also see *note Completion and Confirmation::. |
| 9188 | |
| 9189 | 10.4.1 Theming Faces |
| 9190 | -------------------- |
| 9191 | |
| 9192 | The default theme uses blue for local branches, green for remote |
| 9193 | branches, and goldenrod (brownish yellow) for tags. When creating a new |
| 9194 | theme, you should probably follow that example. If your theme already |
| 9195 | uses other colors, then stick to that. |
| 9196 | |
| 9197 | In older releases these reference faces used to have a background |
| 9198 | color and a box around them. The basic default faces no longer do so, |
| 9199 | to make Magit buffers much less noisy, and you should follow that |
| 9200 | example at least with regards to boxes. (Boxes were used in the past to |
| 9201 | work around a conflict between the highlighting overlay and text |
| 9202 | property backgrounds. That's no longer necessary because highlighting |
| 9203 | no longer causes other background colors to disappear.) Alternatively |
| 9204 | you can keep the background color and/or box, but then have to take |
| 9205 | special care to adjust ‘magit-branch-current’ accordingly. By default |
| 9206 | it looks mostly like ‘magit-branch-local’, but with a box (by default |
| 9207 | the former is the only face that uses a box, exactly so that it sticks |
| 9208 | out). If the former also uses a box, then you have to make sure that it |
| 9209 | differs in some other way from the latter. |
| 9210 | |
| 9211 | The most difficult faces to theme are those related to diffs, |
| 9212 | headings, highlighting, and the region. There are faces that fall into |
| 9213 | all four groups - expect to spend some time getting this right. |
| 9214 | |
| 9215 | The ‘region’ face in the default theme, in both the light and dark |
| 9216 | variants, as well as in many other themes, distributed with Emacs or by |
| 9217 | third-parties, is very ugly. It is common to use a background color |
| 9218 | that really sticks out, which is ugly but if that were the only problem |
| 9219 | then it would be acceptable. Unfortunately many themes also set the |
| 9220 | foreground color, which ensures that all text within the region is |
| 9221 | readable. Without doing that there might be cases where some foreground |
| 9222 | color is too close to the region background color to still be readable. |
| 9223 | But it also means that text within the region loses all syntax |
| 9224 | highlighting. |
| 9225 | |
| 9226 | I consider the work that went into getting the ‘region’ face right to |
| 9227 | be a good indicator for the general quality of a theme. My |
| 9228 | recommendation for the ‘region’ face is this: use a background color |
| 9229 | slightly different from the background color of the ‘default’ face, and |
| 9230 | do not set the foreground color at all. So for a light theme you might |
| 9231 | use a light (possibly tinted) gray as the background color of ‘default’ |
| 9232 | and a somewhat darker gray for the background of ‘region’. That should |
| 9233 | usually be enough to not collide with the foreground color of any other |
| 9234 | face. But if some other faces also set a light gray as background |
| 9235 | color, then you should also make sure it doesn't collide with those (in |
| 9236 | some cases it might be acceptable though). |
| 9237 | |
| 9238 | Magit only uses the ‘region’ face when the region is "invalid" by its |
| 9239 | own definition. In a Magit buffer the region is used to either select |
| 9240 | multiple sibling sections, so that commands which support it act on all |
| 9241 | of these sections instead of just the current section, or to select |
| 9242 | lines within a single hunk section. In all other cases, the section is |
| 9243 | considered invalid and Magit won't act on it. But such invalid sections |
| 9244 | happen, either because the user has not moved point enough yet to make |
| 9245 | it valid or because she wants to use a non-magit command to act on the |
| 9246 | region, e.g., ‘kill-region’. |
| 9247 | |
| 9248 | So using the regular ‘region’ face for invalid sections is a feature. |
| 9249 | It tells the user that Magit won't be able to act on it. It's |
| 9250 | acceptable if that face looks a bit odd and even (but less so) if it |
| 9251 | collides with the background colors of section headings and other things |
| 9252 | that have a background color. |
| 9253 | |
| 9254 | Magit highlights the current section. If a section has subsections, |
| 9255 | then all of them are highlighted. This is done using faces that have |
| 9256 | "highlight" in their names. For most sections, |
| 9257 | ‘magit-section-highlight’ is used for both the body and the heading. |
| 9258 | Like the ‘region’ face, it should only set the background color to |
| 9259 | something similar to that of ‘default’. The highlight background color |
| 9260 | must be different from both the ‘region’ background color and the |
| 9261 | ‘default’ background color. |
| 9262 | |
| 9263 | For diff related sections Magit uses various faces to highlight |
| 9264 | different parts of the selected section(s). Note that hunk headings, |
| 9265 | unlike all other section headings, by default have a background color, |
| 9266 | because it is useful to have very visible separators between hunks. |
| 9267 | That face ‘magit-diff-hunk-heading’, should be different from both |
| 9268 | ‘magit-diff-hunk-heading-highlight’ and ‘magit-section-highlight’, as |
| 9269 | well as from ‘magit-diff-context’ and ‘magit-diff-context-highlight’. |
| 9270 | By default we do that by changing the foreground color. Changing the |
| 9271 | background color would lead to complications, and there are already |
| 9272 | enough we cannot get around. (Also note that it is generally a good |
| 9273 | idea for section headings to always be bold, but only for sections that |
| 9274 | have subsections). |
| 9275 | |
| 9276 | When there is a valid region selecting diff-related sibling sections, |
| 9277 | i.e., multiple files or hunks, then the bodies of all these sections use |
| 9278 | the respective highlight faces, but additionally the headings instead |
| 9279 | use one of the faces ‘magit-diff-file-heading-selection’ or |
| 9280 | ‘magit-diff-hunk-heading-selection’. These faces have to be different |
| 9281 | from the regular highlight variants to provide explicit visual |
| 9282 | indication that the region is active. |
| 9283 | |
| 9284 | When theming diff related faces, start by setting the option |
| 9285 | ‘magit-diff-refine-hunk’ to ‘all’. You might personally prefer to only |
| 9286 | refine the current hunk or not use hunk refinement at all, but some of |
| 9287 | the users of your theme want all hunks to be refined, so you have to |
| 9288 | cater to that. |
| 9289 | |
| 9290 | (Also turn on ‘magit-diff-highlight-indentation’, |
| 9291 | ‘magit-diff-highlight-trailing’, and ‘magit-diff-paint-whitespace’; and |
| 9292 | insert some whitespace errors into the code you use for testing.) |
| 9293 | |
| 9294 | For added lines you have to adjust three faces: ‘magit-diff-added’, |
| 9295 | ‘magit-diff-added-highlight’, and ‘diff-refined-added’. Make sure that |
| 9296 | the latter works well with both of the former, as well as ‘smerge-other’ |
| 9297 | and ‘diff-added’. Then do the same for the removed lines, context |
| 9298 | lines, lines added by us, and lines added by them. Also make sure the |
| 9299 | respective added, removed, and context faces use approximately the same |
| 9300 | saturation for both the highlighted and unhighlighted variants. Also |
| 9301 | make sure the file and diff headings work nicely with context lines |
| 9302 | (e.g., make them look different). Line faces should set both the |
| 9303 | foreground and the background color. For example, for added lines use |
| 9304 | two different greens. |
| 9305 | |
| 9306 | It's best if the foreground color of both the highlighted and the |
| 9307 | unhighlighted variants are the same, so you will need to have to find a |
| 9308 | color that works well on the highlight and unhighlighted background, the |
| 9309 | refine background, and the highlight context background. When there is |
| 9310 | an hunk internal region, then the added- and removed-lines background |
| 9311 | color is used only within that region. Outside the region the |
| 9312 | highlighted context background color is used. This makes it easier to |
| 9313 | see what is being staged. With an hunk internal region the hunk heading |
| 9314 | is shown using ‘magit-diff-hunk-heading-selection’, and so are the thin |
| 9315 | lines that are added around the lines that fall within the region. The |
| 9316 | background color of that has to be distinct enough from the various |
| 9317 | other involved background colors. |
| 9318 | |
| 9319 | Nobody said this would be easy. If your theme restricts itself to a |
| 9320 | certain set of colors, then you should make an exception here. |
| 9321 | Otherwise it would be impossible to make the diffs look good in each and |
| 9322 | every variation. Actually you might want to just stick to the default |
| 9323 | definitions for these faces. You have been warned. Also please note |
| 9324 | that if you do not get this right, this will in some cases look to users |
| 9325 | like bugs in Magit - so please do it right or not at all. |
| 9326 | |
| 9327 | |
| 9328 | File: magit.info, Node: FAQ, Next: Debugging Tools, Prev: Plumbing, Up: Top |
| 9329 | |
| 9330 | Appendix A FAQ |
| 9331 | ************** |
| 9332 | |
| 9333 | The next two nodes lists frequently asked questions. For a list of |
| 9334 | frequently *and recently* asked questions, i.e., questions that haven't |
| 9335 | made it into the manual yet, see |
| 9336 | <https://github.com/magit/magit/wiki/FAQ>. |
| 9337 | |
| 9338 | Please also see *note Debugging Tools::. |
| 9339 | |
| 9340 | * Menu: |
| 9341 | |
| 9342 | * FAQ - How to ...?:: |
| 9343 | * FAQ - Issues and Errors:: |
| 9344 | |
| 9345 | |
| 9346 | File: magit.info, Node: FAQ - How to ...?, Next: FAQ - Issues and Errors, Up: FAQ |
| 9347 | |
| 9348 | A.1 FAQ - How to ...? |
| 9349 | ===================== |
| 9350 | |
| 9351 | A.1.1 How to pronounce Magit? |
| 9352 | ----------------------------- |
| 9353 | |
| 9354 | Either ‘mu[m's] git’ or ‘magi{c => t}’ is fine. |
| 9355 | |
| 9356 | The slogan is "It's Magit! The magical Git client", so it makes |
| 9357 | sense to pronounce Magit like magic, while taking into account that C |
| 9358 | and T do not sound the same. |
| 9359 | |
| 9360 | The German "Magie" is not pronounced the same as the English "magic", |
| 9361 | so if you speak German, then you can use the above rationale to justify |
| 9362 | using the former pronunciation; ‘Mag{ie => it}’. |
| 9363 | |
| 9364 | You can also choose to use the former pronunciation just because you |
| 9365 | like it better. |
| 9366 | |
| 9367 | Also see <https://magit.vc/assets/videos/magic.mp4>. Also see |
| 9368 | <https://emacs.stackexchange.com/questions/13696>. |
| 9369 | |
| 9370 | A.1.2 How to show git's output? |
| 9371 | ------------------------------- |
| 9372 | |
| 9373 | To show the output of recently run git commands, press ‘$’ (or, if that |
| 9374 | isn't available, use ‘M-x magit-process-buffer’). This shows a buffer |
| 9375 | containing a section per git invocation; as always press ‘TAB’ to expand |
| 9376 | or collapse them. |
| 9377 | |
| 9378 | By default, git's output is only inserted into the process buffer if |
| 9379 | it is run for side-effects. When the output is consumed in some way, |
| 9380 | also inserting it into the process buffer would be too expensive. For |
| 9381 | debugging purposes, it's possible to do so anyway, using ‘M-x |
| 9382 | magit-toggle-git-debug’. |
| 9383 | |
| 9384 | A.1.3 How to install the gitman info manual? |
| 9385 | -------------------------------------------- |
| 9386 | |
| 9387 | Git's manpages can be exported as an info manual called ‘gitman’. |
| 9388 | Magit's own info manual links to nodes in that manual instead of the |
| 9389 | actual manpages, simply because Info doesn't support linking to |
| 9390 | manpages. |
| 9391 | |
| 9392 | Unfortunately some distributions do not install the ‘gitman’ manual |
| 9393 | by default and you would have to install a separate documentation |
| 9394 | package to get it. |
| 9395 | |
| 9396 | Magit patches info, adding the ability to visit links to the ‘gitman’ |
| 9397 | info manual, by instead viewing the respective manpage. If you prefer |
| 9398 | that approach, then set the value of ‘magit-view-git-manual-method’ to |
| 9399 | one of the supported Emacs packages ‘man’ or ‘woman’, e.g.: |
| 9400 | |
| 9401 | (setq magit-view-git-manual-method 'man) |
| 9402 | |
| 9403 | A.1.4 How to show diffs for gpg-encrypted files? |
| 9404 | ------------------------------------------------ |
| 9405 | |
| 9406 | Git supports showing diffs for encrypted files, but has to be told to do |
| 9407 | so. Since Magit just uses Git to get the diffs, configuring Git also |
| 9408 | affects the diffs displayed inside Magit. |
| 9409 | |
| 9410 | git config --global diff.gpg.textconv "gpg --no-tty --decrypt" |
| 9411 | echo "*.gpg filter=gpg diff=gpg" > .gitattributes |
| 9412 | |
| 9413 | A.1.5 How does branching and pushing work? |
| 9414 | ------------------------------------------ |
| 9415 | |
| 9416 | Please see *note Branching:: and |
| 9417 | <https://emacsair.me/2016/01/18/magit-2.4> |
| 9418 | |
| 9419 | A.1.6 Should I disable VC? |
| 9420 | -------------------------- |
| 9421 | |
| 9422 | If you don't use VC (the built-in version control interface) then you |
| 9423 | might be tempted to disable it, not least because we used to recommend |
| 9424 | that you do that. |
| 9425 | |
| 9426 | We no longer recommend that you disable VC. Doing so would break |
| 9427 | useful third-party packages (such as ‘diff-hl’), which depend on VC |
| 9428 | being enabled. |
| 9429 | |
| 9430 | If you choose to disable VC anyway, then you can do so by changing |
| 9431 | the value of ‘vc-handled-backends’. |
| 9432 | |
| 9433 | A.1.7 The diff/log is filtered to one file; how do I show all changes. |
| 9434 | ---------------------------------------------------------------------- |
| 9435 | |
| 9436 | The diff arguments used in the current buffer can be changed using the |
| 9437 | ‘magit-diff-refresh’ menu on ‘D’. |
| 9438 | |
| 9439 | The log arguments used in the current buffer can be changed using the |
| 9440 | ‘magit-log-refresh’ menu on ‘L’. |
| 9441 | |
| 9442 | |
| 9443 | File: magit.info, Node: FAQ - Issues and Errors, Prev: FAQ - How to ...?, Up: FAQ |
| 9444 | |
| 9445 | A.2 FAQ - Issues and Errors |
| 9446 | =========================== |
| 9447 | |
| 9448 | A.2.1 Magit is slow |
| 9449 | ------------------- |
| 9450 | |
| 9451 | See *note Performance:: and *note I changed several thousand files at |
| 9452 | once and now Magit is unusable::. |
| 9453 | |
| 9454 | A.2.2 I changed several thousand files at once and now Magit is unusable |
| 9455 | ------------------------------------------------------------------------ |
| 9456 | |
| 9457 | Magit is currently not expected to work well under such conditions. It |
| 9458 | sure would be nice if it did. Reaching satisfactory performance under |
| 9459 | such conditions will require some heavy refactoring. This is no small |
| 9460 | task but I hope to eventually find the time to make it happen. |
| 9461 | |
| 9462 | But for now we recommend you use the command line to complete this |
| 9463 | one commit. Also see *note Performance::. |
| 9464 | |
| 9465 | A.2.3 I am having problems committing |
| 9466 | ------------------------------------- |
| 9467 | |
| 9468 | That likely means that Magit is having problems finding an appropriate |
| 9469 | ‘emacsclient’ executable. See *note (with-editor)Configuring |
| 9470 | With-Editor:: and *note (with-editor)Debugging::. |
| 9471 | |
| 9472 | A.2.4 I am using MS Windows and cannot push with Magit |
| 9473 | ------------------------------------------------------ |
| 9474 | |
| 9475 | It's almost certain that Magit is only incidental to this issue. It is |
| 9476 | much more likely that this is a configuration issue, even if you can |
| 9477 | push on the command line. |
| 9478 | |
| 9479 | Detailed setup instructions can be found at |
| 9480 | <https://github.com/magit/magit/wiki/Pushing-with-Magit-from-Windows>. |
| 9481 | |
| 9482 | A.2.5 I am using macOS and SOMETHING works in shell, but not in Magit |
| 9483 | --------------------------------------------------------------------- |
| 9484 | |
| 9485 | This usually occurs because Emacs doesn't have the same environment |
| 9486 | variables as your shell. Try installing and configuring |
| 9487 | <https://github.com/purcell/exec-path-from-shell>. By default it |
| 9488 | synchronizes ‘$PATH’, which helps Magit find the same ‘git’ as the one |
| 9489 | you are using on the shell. |
| 9490 | |
| 9491 | If SOMETHING is "passphrase caching with gpg-agent for commit and/or |
| 9492 | tag signing", then you'll also need to synchronize ‘$GPG_AGENT_INFO’. |
| 9493 | |
| 9494 | A.2.6 Expanding a file to show the diff causes it to disappear |
| 9495 | -------------------------------------------------------------- |
| 9496 | |
| 9497 | This is probably caused by a customization of a ‘diff.*’ Git variable. |
| 9498 | You probably set that variable for a reason, and should therefore only |
| 9499 | undo that setting in Magit by customizing ‘magit-git-global-arguments’. |
| 9500 | |
| 9501 | A.2.7 Point is wrong in the ‘COMMIT_EDITMSG’ buffer |
| 9502 | --------------------------------------------------- |
| 9503 | |
| 9504 | Neither Magit nor ‘git-commit.el’ fiddle with point in the buffer used |
| 9505 | to write commit messages, so something else must be doing it. |
| 9506 | |
| 9507 | You have probably globally enabled a mode, which restores point in |
| 9508 | file-visiting buffers. It might be a bit surprising, but when you write |
| 9509 | a commit message, then you are actually editing a file. |
| 9510 | |
| 9511 | So you have to figure out which package is doing it. ‘saveplace’, |
| 9512 | ‘pointback’, and ‘session’ are likely candidates. These snippets might |
| 9513 | help: |
| 9514 | |
| 9515 | (setq session-name-disable-regexp "\\(?:\\`'\\.git/[A-Z_]+\\'\\)") |
| 9516 | |
| 9517 | (with-eval-after-load 'pointback |
| 9518 | (lambda () |
| 9519 | (when (or git-commit-mode git-rebase-mode) |
| 9520 | (pointback-mode -1)))) |
| 9521 | |
| 9522 | A.2.8 The mode-line information isn't always up-to-date |
| 9523 | ------------------------------------------------------- |
| 9524 | |
| 9525 | Magit is not responsible for the version control information that is |
| 9526 | being displayed in the mode-line and looks something like ‘Git-master’. |
| 9527 | The built-in "Version Control" package, also known as "VC", updates that |
| 9528 | information, and can be told to do so more often: |
| 9529 | |
| 9530 | (setq auto-revert-check-vc-info t) |
| 9531 | |
| 9532 | But doing so isn't good for performance. For more (overly |
| 9533 | optimistic) information see *note (emacs)VC Mode Line::. |
| 9534 | |
| 9535 | If you don't really care about seeing this information in the |
| 9536 | mode-line, but just don't want to see _incorrect_ information, then |
| 9537 | consider simply not displaying it in the mode-line: |
| 9538 | |
| 9539 | (setq-default mode-line-format |
| 9540 | (delete '(vc-mode vc-mode) mode-line-format)) |
| 9541 | |
| 9542 | A.2.9 A branch and tag sharing the same name breaks SOMETHING |
| 9543 | ------------------------------------------------------------- |
| 9544 | |
| 9545 | Or more generally, ambiguous refnames break SOMETHING. |
| 9546 | |
| 9547 | Magit assumes that refs are named non-ambiguously across the |
| 9548 | "refs/heads/", "refs/tags/", and "refs/remotes/" namespaces (i.e., all |
| 9549 | the names remain unique when those prefixes are stripped). We consider |
| 9550 | ambiguous refnames unsupported and recommend that you use a |
| 9551 | non-ambiguous naming scheme. However, if you do work with a repository |
| 9552 | that has ambiguous refnames, please report any issues you encounter, so |
| 9553 | that we can investigate whether there is a simple fix. |
| 9554 | |
| 9555 | A.2.10 My Git hooks work on the command-line but not inside Magit |
| 9556 | ----------------------------------------------------------------- |
| 9557 | |
| 9558 | When Magit calls ‘git’ it adds a few global arguments including |
| 9559 | ‘--literal-pathspecs’ and the ‘git’ process started by Magit then passes |
| 9560 | that setting on to other ‘git’ process it starts itself. It does so by |
| 9561 | setting the environment variable ‘GIT_LITERAL_PATHSPECS’, not by calling |
| 9562 | subprocesses with the ‘--literal-pathspecs’ argument. You can therefore |
| 9563 | override this setting in hook scripts using ‘unset |
| 9564 | GIT_LITERAL_PATHSPECS’. |
| 9565 | |
| 9566 | A.2.11 ‘git-commit-mode’ isn't used when committing from the command-line |
| 9567 | ------------------------------------------------------------------------- |
| 9568 | |
| 9569 | The reason for this is that ‘git-commit.el’ has not been loaded yet |
| 9570 | and/or that the server has not been started yet. These things have |
| 9571 | always already been taken care of when you commit from Magit because in |
| 9572 | order to do so, Magit has to be loaded and doing that involves loading |
| 9573 | ‘git-commit’ and starting the server. |
| 9574 | |
| 9575 | If you want to commit from the command-line, then you have to take |
| 9576 | care of these things yourself. Your ‘init.el’ file should contain: |
| 9577 | |
| 9578 | (require 'git-commit) |
| 9579 | (server-mode) |
| 9580 | |
| 9581 | Instead of '(require 'git-commit)' you may also use: |
| 9582 | |
| 9583 | (load "/path/to/magit-autoloads.el") |
| 9584 | |
| 9585 | You might want to do that because loading ‘git-commit’ causes large |
| 9586 | parts of Magit to be loaded. |
| 9587 | |
| 9588 | There are also some variations of ‘(server-mode)’ that you might want |
| 9589 | to try. Personally I use: |
| 9590 | |
| 9591 | (use-package server |
| 9592 | :config (or (server-running-p) (server-mode))) |
| 9593 | |
| 9594 | Now you can use: |
| 9595 | |
| 9596 | $ emacs& |
| 9597 | $ EDITOR=emacsclient git commit |
| 9598 | |
| 9599 | However you cannot use: |
| 9600 | |
| 9601 | $ killall emacs |
| 9602 | $ EDITOR="emacsclient --alternate-editor emacs" git commit |
| 9603 | |
| 9604 | This will actually end up using ‘emacs’, not ‘emacsclient’. If you |
| 9605 | do this, then you can still edit the commit message but |
| 9606 | ‘git-commit-mode’ won't be used and you have to exit ‘emacs’ to finish |
| 9607 | the process. |
| 9608 | |
| 9609 | Tautology ahead. If you want to be able to use ‘emacsclient’ to |
| 9610 | connect to a running ‘emacs’ instance, even though no ‘emacs’ instance |
| 9611 | is running, then you cannot use ‘emacsclient’ directly. |
| 9612 | |
| 9613 | Instead you have to create a script that does something like this: |
| 9614 | |
| 9615 | Try to use ‘emacsclient’ (without using ‘--alternate-editor’). If |
| 9616 | that succeeds, do nothing else. Otherwise start ‘emacs &’ (and |
| 9617 | ‘init.el’ must call ‘server-start’) and try to use ‘emacsclient’ again. |
| 9618 | |
| 9619 | A.2.12 Point ends up inside invisible text when jumping to a file-visiting buffer |
| 9620 | --------------------------------------------------------------------------------- |
| 9621 | |
| 9622 | This can happen when you type ‘RET’ on a hunk to visit the respective |
| 9623 | file at the respective position. One solution to this problem is to use |
| 9624 | ‘global-reveal-mode’. It makes sure that text around point is always |
| 9625 | visible. If that is too drastic for your taste, then you may instead |
| 9626 | use ‘magit-diff-visit-file-hook’ to reveal the text, possibly using |
| 9627 | ‘reveal-post-command’ or for Org buffers ‘org-reveal’. |
| 9628 | |
| 9629 | A.2.13 I am no longer able to save popup defaults |
| 9630 | ------------------------------------------------- |
| 9631 | |
| 9632 | Magit used to use Magit-Popup to implement the transient popup menus. |
| 9633 | Now it used Transient instead, which is Magit-Popup's successor. |
| 9634 | |
| 9635 | In the older Magit-Popup menus, it was possible to save user settings |
| 9636 | (e.g., setting the gpg signing key for commits) by using ‘C-c C-c’ in |
| 9637 | the popup buffer. This would dismiss the popup, but save the settings |
| 9638 | as the defaults for future popups. |
| 9639 | |
| 9640 | When switching to Transient menus, this functionality is now |
| 9641 | available via ‘C-x C-s’ instead; the ‘C-x’ prefix has other options as |
| 9642 | well when using Transient, which will be displayed when it is typed. |
| 9643 | See <https://docs.magit.vc/transient/Saving-Values.html#Saving-Values> |
| 9644 | for more details. |
| 9645 | |
| 9646 | |
| 9647 | File: magit.info, Node: Debugging Tools, Next: Keystroke Index, Prev: FAQ, Up: Top |
| 9648 | |
| 9649 | B Debugging Tools |
| 9650 | ***************** |
| 9651 | |
| 9652 | Magit and its dependencies provide a few debugging tools, and we |
| 9653 | appreciate it very much if you use those tools before reporting an |
| 9654 | issue. Please include all relevant output when reporting an issue. |
| 9655 | |
| 9656 | ‘M-x magit-version’ |
| 9657 | This command shows the currently used versions of Magit, Git, and |
| 9658 | Emacs in the echo area. Non-interactively this just returns the |
| 9659 | Magit version. |
| 9660 | |
| 9661 | ‘M-x magit-emacs-Q-command’ |
| 9662 | This command shows a debugging shell command in the echo area and |
| 9663 | adds it to the kill ring. Paste that command into a shell and run |
| 9664 | it. |
| 9665 | |
| 9666 | This shell command starts ‘emacs’ with only ‘magit’ and its |
| 9667 | dependencies loaded. Neither your configuration nor other |
| 9668 | installed packages are loaded. This makes it easier to determine |
| 9669 | whether some issue lays with Magit or something else. |
| 9670 | |
| 9671 | If you run Magit from its Git repository, then you should be able |
| 9672 | to use ‘make emacs-Q’ instead of the output of this command. |
| 9673 | |
| 9674 | ‘M-x magit-toggle-git-debug’ |
| 9675 | This command toggles whether additional git errors are reported. |
| 9676 | |
| 9677 | Magit basically calls git for one of these two reasons: for |
| 9678 | side-effects or to do something with its standard output. |
| 9679 | |
| 9680 | When git is run for side-effects then its output, including error |
| 9681 | messages, go into the process buffer which is shown when using ‘$’. |
| 9682 | |
| 9683 | When git's output is consumed in some way, then it would be too |
| 9684 | expensive to also insert it into this buffer, but with this command |
| 9685 | that can be enabled temporarily. In that case, if git returns with |
| 9686 | a non-zero exit status, then at least its standard error is |
| 9687 | inserted into this buffer. |
| 9688 | |
| 9689 | Also note that just because git exits with a non-zero status and |
| 9690 | prints an error message, that usually doesn't mean that it is an |
| 9691 | error as far as Magit is concerned, which is another reason we |
| 9692 | usually hide these error messages. Whether some error message is |
| 9693 | relevant in the context of some unexpected behavior has to be |
| 9694 | judged on a case by case basis. |
| 9695 | |
| 9696 | ‘M-x magit-toggle-verbose-refresh’ |
| 9697 | This command toggles whether Magit refreshes buffers verbosely. |
| 9698 | Enabling this helps figuring out which sections are bottlenecks. |
| 9699 | The additional output can be found in the ‘*Messages*’ buffer. |
| 9700 | |
| 9701 | ‘M-x magit-toggle-subprocess-record’ |
| 9702 | This command toggles whether subprocess invocations are recorded. |
| 9703 | |
| 9704 | When enabled, all subprocesses started by ‘magit-process-file’ are |
| 9705 | logged into the buffer specified by |
| 9706 | ‘magit-process-record-buffer-name’ using the format |
| 9707 | ‘magit-process-record-entry-format’. This is for debugging |
| 9708 | purposes. |
| 9709 | |
| 9710 | This is in addition to and distinct from the default logging done |
| 9711 | by default, and additional logging enabled with |
| 9712 | ‘magit-toggle-git-debug’. |
| 9713 | |
| 9714 | ‘M-x magit-debug-git-executable’ |
| 9715 | This command displays a buffer containing information about the |
| 9716 | available and used ‘git’ executable(s), and can be useful when |
| 9717 | investigating ‘exec-path’ issues. |
| 9718 | |
| 9719 | Also see *note Git Executable::. |
| 9720 | |
| 9721 | ‘M-x magit-profile-refresh-buffer’ |
| 9722 | This command profiles refreshing the current Magit buffer and then |
| 9723 | displays the results. |
| 9724 | |
| 9725 | ‘M-x magit-toggle-profiling’ |
| 9726 | This command starts profiling Magit and Forge, or if profiling is |
| 9727 | already in progress, it instead stops that and displays the |
| 9728 | results. |
| 9729 | |
| 9730 | ‘M-x with-editor-debug’ |
| 9731 | This command displays a buffer containing information about the |
| 9732 | available and used ‘emacsclient’ executable(s), and can be useful |
| 9733 | when investigating why Magit (or rather ‘with-editor’) cannot find |
| 9734 | an appropriate ‘emacsclient’ executable. |
| 9735 | |
| 9736 | Also see *note (with-editor)Debugging::. |
| 9737 | |
| 9738 | Please also see *note FAQ::. |
| 9739 | |
| 9740 | |
| 9741 | File: magit.info, Node: Keystroke Index, Next: Function and Command Index, Prev: Debugging Tools, Up: Top |
| 9742 | |
| 9743 | Appendix C Keystroke Index |
| 9744 | ************************** |
| 9745 | |
| 9746 | [index ] |
| 9747 | * Menu: |
| 9748 | |
| 9749 | * -: Logging. (line 163) |
| 9750 | * - <1>: Diffing. (line 187) |
| 9751 | * :: Running Git. (line 99) |
| 9752 | * !: Running Git. (line 87) |
| 9753 | * ! !: Running Git. (line 91) |
| 9754 | * ! a: Running Git. (line 127) |
| 9755 | * ! b: Running Git. (line 130) |
| 9756 | * ! g: Running Git. (line 133) |
| 9757 | * ! k: Running Git. (line 124) |
| 9758 | * ! m: Running Git. (line 136) |
| 9759 | * ! p: Running Git. (line 99) |
| 9760 | * ! s: Running Git. (line 108) |
| 9761 | * ! S: Running Git. (line 112) |
| 9762 | * ^: Sections. (line 50) |
| 9763 | * +: Logging. (line 160) |
| 9764 | * + <1>: Diffing. (line 190) |
| 9765 | * =: Logging. (line 155) |
| 9766 | * >: Sparse checkouts. (line 17) |
| 9767 | * > a: Sparse checkouts. (line 39) |
| 9768 | * > d: Sparse checkouts. (line 50) |
| 9769 | * > e: Sparse checkouts. (line 21) |
| 9770 | * > r: Sparse checkouts. (line 44) |
| 9771 | * > s: Sparse checkouts. (line 33) |
| 9772 | * $: Running Git. (line 20) |
| 9773 | * 0: Diffing. (line 193) |
| 9774 | * 1: Sections. (line 173) |
| 9775 | * 2: Sections. (line 173) |
| 9776 | * 3: Sections. (line 173) |
| 9777 | * 4: Sections. (line 173) |
| 9778 | * 5: Repository List. (line 119) |
| 9779 | * a: Applying. (line 34) |
| 9780 | * A: Cherry Picking. (line 9) |
| 9781 | * A A: Cherry Picking. (line 17) |
| 9782 | * A a: Cherry Picking. (line 23) |
| 9783 | * A A <1>: Cherry Picking. (line 85) |
| 9784 | * A a <1>: Cherry Picking. (line 91) |
| 9785 | * A d: Cherry Picking. (line 51) |
| 9786 | * A h: Cherry Picking. (line 40) |
| 9787 | * A n: Cherry Picking. (line 62) |
| 9788 | * A s: Cherry Picking. (line 72) |
| 9789 | * A s <1>: Cherry Picking. (line 88) |
| 9790 | * B: Bisecting. (line 9) |
| 9791 | * b: Blaming. (line 115) |
| 9792 | * b <1>: Branching. (line 63) |
| 9793 | * b <2>: Rebasing. (line 216) |
| 9794 | * B B: Bisecting. (line 16) |
| 9795 | * B b: Bisecting. (line 38) |
| 9796 | * b b: Branching. (line 97) |
| 9797 | * b C: Branching. (line 81) |
| 9798 | * b c: Branching. (line 113) |
| 9799 | * B g: Bisecting. (line 42) |
| 9800 | * B k: Bisecting. (line 52) |
| 9801 | * b k: Branching. (line 188) |
| 9802 | * b l: Branching. (line 119) |
| 9803 | * B m: Bisecting. (line 46) |
| 9804 | * b m: Branching. (line 199) |
| 9805 | * b n: Branching. (line 104) |
| 9806 | * B r: Bisecting. (line 57) |
| 9807 | * b r: Branching. (line 204) |
| 9808 | * B s: Bisecting. (line 32) |
| 9809 | * b s: Branching. (line 141) |
| 9810 | * b S: Branching. (line 168) |
| 9811 | * b x: Branching. (line 173) |
| 9812 | * c: Blaming. (line 141) |
| 9813 | * C: Cloning Repository. (line 20) |
| 9814 | * c <1>: Committing. (line 21) |
| 9815 | * c <2>: Rebasing. (line 205) |
| 9816 | * C >: Cloning Repository. (line 38) |
| 9817 | * c a: Committing. (line 59) |
| 9818 | * c A: Committing. (line 141) |
| 9819 | * C b: Cloning Repository. (line 44) |
| 9820 | * C C: Cloning Repository. (line 28) |
| 9821 | * c c: Committing. (line 29) |
| 9822 | * C d: Cloning Repository. (line 55) |
| 9823 | * C e: Cloning Repository. (line 61) |
| 9824 | * c e: Committing. (line 45) |
| 9825 | * c f: Committing. (line 119) |
| 9826 | * c F: Committing. (line 192) |
| 9827 | * C m: Cloning Repository. (line 48) |
| 9828 | * c n: Committing. (line 153) |
| 9829 | * C s: Cloning Repository. (line 32) |
| 9830 | * c s: Committing. (line 130) |
| 9831 | * c S: Committing. (line 204) |
| 9832 | * c w: Committing. (line 65) |
| 9833 | * c W: Committing. (line 167) |
| 9834 | * C-<return>: Visiting Files and Blobs. |
| 9835 | (line 64) |
| 9836 | * C-<tab>: Sections. (line 148) |
| 9837 | * C-c C-a: Committing. (line 415) |
| 9838 | * C-c C-b: Logging. (line 116) |
| 9839 | * C-c C-b <1>: Diffing. (line 209) |
| 9840 | * C-c C-c: Logging. (line 297) |
| 9841 | * C-c C-c <1>: Committing. (line 303) |
| 9842 | * C-c C-c <2>: Rebasing. (line 128) |
| 9843 | * C-c C-d: Diffing. (line 200) |
| 9844 | * C-c C-d <1>: Committing. (line 339) |
| 9845 | * C-c C-e: Diffing. (line 235) |
| 9846 | * C-c C-f: Logging. (line 119) |
| 9847 | * C-c C-f <1>: Diffing. (line 212) |
| 9848 | * C-c C-i: Committing. (line 412) |
| 9849 | * C-c C-k: Logging. (line 302) |
| 9850 | * C-c C-k <1>: Committing. (line 307) |
| 9851 | * C-c C-k <2>: Rebasing. (line 132) |
| 9852 | * C-c C-n: Logging. (line 122) |
| 9853 | * C-c C-o: Committing. (line 427) |
| 9854 | * C-c C-p: Committing. (line 430) |
| 9855 | * C-c C-r: Committing. (line 418) |
| 9856 | * C-c C-s: Committing. (line 421) |
| 9857 | * C-c C-t: Diffing. (line 226) |
| 9858 | * C-c C-t <1>: Committing. (line 424) |
| 9859 | * C-c C-w: Committing. (line 347) |
| 9860 | * C-c f: Commands for Buffers Visiting Files. |
| 9861 | (line 52) |
| 9862 | * C-c f , c: Commands for Buffers Visiting Files. |
| 9863 | (line 52) |
| 9864 | * C-c f , k: Commands for Buffers Visiting Files. |
| 9865 | (line 52) |
| 9866 | * C-c f , r: Commands for Buffers Visiting Files. |
| 9867 | (line 52) |
| 9868 | * C-c f , x: Commands for Buffers Visiting Files. |
| 9869 | (line 52) |
| 9870 | * C-c f B: Blaming. (line 28) |
| 9871 | * C-c f b: Blaming. (line 28) |
| 9872 | * C-c f B <1>: Commands for Buffers Visiting Files. |
| 9873 | (line 52) |
| 9874 | * C-c f b <1>: Commands for Buffers Visiting Files. |
| 9875 | (line 52) |
| 9876 | * C-c f B b: Blaming. (line 28) |
| 9877 | * C-c f B e: Blaming. (line 28) |
| 9878 | * C-c f B f: Blaming. (line 28) |
| 9879 | * C-c f B q: Blaming. (line 28) |
| 9880 | * C-c f B r: Blaming. (line 28) |
| 9881 | * C-c f c: Commands for Buffers Visiting Files. |
| 9882 | (line 52) |
| 9883 | * C-c f D: Commands for Buffers Visiting Files. |
| 9884 | (line 52) |
| 9885 | * C-c f d: Commands for Buffers Visiting Files. |
| 9886 | (line 52) |
| 9887 | * C-c f e: Blaming. (line 28) |
| 9888 | * C-c f e <1>: Commands for Buffers Visiting Files. |
| 9889 | (line 52) |
| 9890 | * C-c f f: Blaming. (line 28) |
| 9891 | * C-c f f <1>: Commands for Buffers Visiting Files. |
| 9892 | (line 52) |
| 9893 | * C-c f g: Commands for Buffers Visiting Files. |
| 9894 | (line 52) |
| 9895 | * C-c f G: Commands for Buffers Visiting Files. |
| 9896 | (line 52) |
| 9897 | * C-c f L: Commands for Buffers Visiting Files. |
| 9898 | (line 52) |
| 9899 | * C-c f l: Commands for Buffers Visiting Files. |
| 9900 | (line 52) |
| 9901 | * C-c f M: Commands for Buffers Visiting Files. |
| 9902 | (line 52) |
| 9903 | * C-c f m: Commands for Buffers Visiting Files. |
| 9904 | (line 52) |
| 9905 | * C-c f n: Commands for Buffers Visiting Files. |
| 9906 | (line 52) |
| 9907 | * C-c f p: Commands for Buffers Visiting Files. |
| 9908 | (line 52) |
| 9909 | * C-c f q: Blaming. (line 28) |
| 9910 | * C-c f q <1>: Commands for Buffers Visiting Files. |
| 9911 | (line 52) |
| 9912 | * C-c f r: Blaming. (line 28) |
| 9913 | * C-c f r <1>: Commands for Buffers Visiting Files. |
| 9914 | (line 52) |
| 9915 | * C-c f s: Commands for Buffers Visiting Files. |
| 9916 | (line 52) |
| 9917 | * C-c f s <1>: Commands for Buffers Visiting Files. |
| 9918 | (line 52) |
| 9919 | * C-c f t: Commands for Buffers Visiting Files. |
| 9920 | (line 52) |
| 9921 | * C-c f u: Commands for Buffers Visiting Files. |
| 9922 | (line 52) |
| 9923 | * C-c f u <1>: Commands for Buffers Visiting Files. |
| 9924 | (line 52) |
| 9925 | * C-c f v: Commands for Buffers Visiting Files. |
| 9926 | (line 52) |
| 9927 | * C-c f V: Commands for Buffers Visiting Files. |
| 9928 | (line 52) |
| 9929 | * C-c g: Transient Commands. (line 20) |
| 9930 | * C-c M-g: Commands for Buffers Visiting Files. |
| 9931 | (line 58) |
| 9932 | * C-c M-g , c: Commands for Buffers Visiting Files. |
| 9933 | (line 86) |
| 9934 | * C-c M-g , k: Commands for Buffers Visiting Files. |
| 9935 | (line 82) |
| 9936 | * C-c M-g , r: Commands for Buffers Visiting Files. |
| 9937 | (line 78) |
| 9938 | * C-c M-g , x: Commands for Buffers Visiting Files. |
| 9939 | (line 74) |
| 9940 | * C-c M-g B: Blaming. (line 34) |
| 9941 | * C-c M-g b: Blaming. (line 45) |
| 9942 | * C-c M-g B <1>: Commands for Buffers Visiting Files. |
| 9943 | (line 144) |
| 9944 | * C-c M-g B b: Blaming. (line 45) |
| 9945 | * C-c M-g B e: Blaming. (line 76) |
| 9946 | * C-c M-g B f: Blaming. (line 68) |
| 9947 | * C-c M-g B q: Blaming. (line 87) |
| 9948 | * C-c M-g B r: Blaming. (line 60) |
| 9949 | * C-c M-g c: Commands for Buffers Visiting Files. |
| 9950 | (line 186) |
| 9951 | * C-c M-g D: Commands for Buffers Visiting Files. |
| 9952 | (line 91) |
| 9953 | * C-c M-g d: Commands for Buffers Visiting Files. |
| 9954 | (line 101) |
| 9955 | * C-c M-g e: Blaming. (line 76) |
| 9956 | * C-c M-g e <1>: Commands for Buffers Visiting Files. |
| 9957 | (line 192) |
| 9958 | * C-c M-g f: Blaming. (line 68) |
| 9959 | * C-c M-g g: Commands for Buffers Visiting Files. |
| 9960 | (line 173) |
| 9961 | * C-c M-g G: Commands for Buffers Visiting Files. |
| 9962 | (line 182) |
| 9963 | * C-c M-g L: Commands for Buffers Visiting Files. |
| 9964 | (line 116) |
| 9965 | * C-c M-g l: Commands for Buffers Visiting Files. |
| 9966 | (line 126) |
| 9967 | * C-c M-g M: Commands for Buffers Visiting Files. |
| 9968 | (line 139) |
| 9969 | * C-c M-g n: Commands for Buffers Visiting Files. |
| 9970 | (line 160) |
| 9971 | * C-c M-g p: Commands for Buffers Visiting Files. |
| 9972 | (line 156) |
| 9973 | * C-c M-g q: Blaming. (line 87) |
| 9974 | * C-c M-g r: Blaming. (line 60) |
| 9975 | * C-c M-g s: Commands for Buffers Visiting Files. |
| 9976 | (line 63) |
| 9977 | * C-c M-g s <1>: Commands for Buffers Visiting Files. |
| 9978 | (line 63) |
| 9979 | * C-c M-g t: Commands for Buffers Visiting Files. |
| 9980 | (line 136) |
| 9981 | * C-c M-g u: Commands for Buffers Visiting Files. |
| 9982 | (line 69) |
| 9983 | * C-c M-g u <1>: Commands for Buffers Visiting Files. |
| 9984 | (line 69) |
| 9985 | * C-c M-g v: Commands for Buffers Visiting Files. |
| 9986 | (line 163) |
| 9987 | * C-c M-g V: Commands for Buffers Visiting Files. |
| 9988 | (line 167) |
| 9989 | * C-c M-i: Committing. (line 434) |
| 9990 | * C-c M-s: Committing. (line 318) |
| 9991 | * C-c TAB: Sections. (line 148) |
| 9992 | * C-w: Common Commands. (line 22) |
| 9993 | * C-x g: Status Buffer. (line 23) |
| 9994 | * C-x M-g: Transient Commands. (line 20) |
| 9995 | * C-x u: Rebasing. (line 223) |
| 9996 | * d: Diffing. (line 22) |
| 9997 | * D: Diffing. (line 105) |
| 9998 | * d c: Diffing. (line 82) |
| 9999 | * d d: Diffing. (line 27) |
| 10000 | * D f: Diffing. (line 170) |
| 10001 | * D F: Diffing. (line 174) |
| 10002 | * D g: Diffing. (line 110) |
| 10003 | * d p: Diffing. (line 75) |
| 10004 | * d r: Diffing. (line 49) |
| 10005 | * D r: Diffing. (line 166) |
| 10006 | * d s: Diffing. (line 67) |
| 10007 | * D s: Diffing. (line 114) |
| 10008 | * d t: Diffing. (line 86) |
| 10009 | * D t: Diffing. (line 127) |
| 10010 | * D T: Diffing. (line 146) |
| 10011 | * d u: Diffing. (line 72) |
| 10012 | * d w: Diffing. (line 62) |
| 10013 | * D w: Diffing. (line 120) |
| 10014 | * DEL: Logging. (line 146) |
| 10015 | * DEL <1>: Diffing. (line 267) |
| 10016 | * DEL <2>: Blaming. (line 103) |
| 10017 | * DEL <3>: Rebasing. (line 146) |
| 10018 | * e: Ediffing. (line 10) |
| 10019 | * E: Ediffing. (line 21) |
| 10020 | * e <1>: Rebasing. (line 167) |
| 10021 | * E c: Ediffing. (line 100) |
| 10022 | * E i: Ediffing. (line 94) |
| 10023 | * E m: Ediffing. (line 33) |
| 10024 | * E M: Ediffing. (line 48) |
| 10025 | * E r: Ediffing. (line 25) |
| 10026 | * E s: Ediffing. (line 87) |
| 10027 | * E t: Ediffing. (line 79) |
| 10028 | * E u: Ediffing. (line 91) |
| 10029 | * E w: Ediffing. (line 97) |
| 10030 | * E z: Ediffing. (line 103) |
| 10031 | * f: Repository List. (line 115) |
| 10032 | * f <1>: Rebasing. (line 184) |
| 10033 | * F: Rebasing. (line 189) |
| 10034 | * f <2>: Fetching. (line 10) |
| 10035 | * F <1>: Pulling. (line 10) |
| 10036 | * f a: Fetching. (line 45) |
| 10037 | * f C: Branching. (line 81) |
| 10038 | * F C: Branching. (line 81) |
| 10039 | * f e: Fetching. (line 34) |
| 10040 | * F e: Pulling. (line 28) |
| 10041 | * f m: Fetching. (line 48) |
| 10042 | * f o: Fetching. (line 37) |
| 10043 | * f p: Fetching. (line 15) |
| 10044 | * F p: Pulling. (line 14) |
| 10045 | * f r: Fetching. (line 41) |
| 10046 | * f u: Fetching. (line 22) |
| 10047 | * F u: Pulling. (line 21) |
| 10048 | * F U: Pulling. (line 34) |
| 10049 | * g: Modes and Buffers. (line 265) |
| 10050 | * G: Modes and Buffers. (line 273) |
| 10051 | * H: Sections. (line 350) |
| 10052 | * I: Creating Repository. (line 7) |
| 10053 | * j: Logging. (line 127) |
| 10054 | * j <1>: Diffing. (line 254) |
| 10055 | * k: Running Git. (line 27) |
| 10056 | * k <1>: Applying. (line 40) |
| 10057 | * k <2>: Rebasing. (line 201) |
| 10058 | * k <3>: Stashing. (line 114) |
| 10059 | * l: Logging. (line 28) |
| 10060 | * L: Logging. (line 75) |
| 10061 | * L <1>: Logging. (line 103) |
| 10062 | * L <2>: Logging. (line 263) |
| 10063 | * l <1>: Rebasing. (line 240) |
| 10064 | * l a: Logging. (line 59) |
| 10065 | * l b: Logging. (line 56) |
| 10066 | * L d: Logging. (line 277) |
| 10067 | * L g: Logging. (line 80) |
| 10068 | * l h: Logging. (line 38) |
| 10069 | * l H: Logging. (line 342) |
| 10070 | * l l: Logging. (line 33) |
| 10071 | * l L: Logging. (line 53) |
| 10072 | * L L: Logging. (line 97) |
| 10073 | * L L <1>: Logging. (line 271) |
| 10074 | * L l: Logging. (line 274) |
| 10075 | * l o: Logging. (line 47) |
| 10076 | * l O: Logging. (line 339) |
| 10077 | * l r: Logging. (line 336) |
| 10078 | * L s: Logging. (line 84) |
| 10079 | * l u: Logging. (line 41) |
| 10080 | * L w: Logging. (line 90) |
| 10081 | * m: Repository List. (line 109) |
| 10082 | * m <1>: Merging. (line 10) |
| 10083 | * M: Remotes. (line 17) |
| 10084 | * m a: Merging. (line 46) |
| 10085 | * m a <1>: Merging. (line 97) |
| 10086 | * M a: Remotes. (line 51) |
| 10087 | * M C: Remotes. (line 35) |
| 10088 | * m d: Merging. (line 60) |
| 10089 | * m e: Merging. (line 32) |
| 10090 | * M k: Remotes. (line 63) |
| 10091 | * m m: Merging. (line 18) |
| 10092 | * m m <1>: Merging. (line 92) |
| 10093 | * m n: Merging. (line 40) |
| 10094 | * m p: Merging. (line 81) |
| 10095 | * M p: Remotes. (line 66) |
| 10096 | * M P: Remotes. (line 70) |
| 10097 | * M r: Remotes. (line 55) |
| 10098 | * m s: Merging. (line 73) |
| 10099 | * M u: Remotes. (line 59) |
| 10100 | * M-<tab>: Sections. (line 163) |
| 10101 | * M-1: Sections. (line 179) |
| 10102 | * M-2: Sections. (line 179) |
| 10103 | * M-3: Sections. (line 179) |
| 10104 | * M-4: Sections. (line 179) |
| 10105 | * M-n: Sections. (line 46) |
| 10106 | * M-n <1>: Committing. (line 326) |
| 10107 | * M-n <2>: Rebasing. (line 161) |
| 10108 | * M-p: Sections. (line 41) |
| 10109 | * M-p <1>: Committing. (line 321) |
| 10110 | * M-p <2>: Rebasing. (line 158) |
| 10111 | * M-w: Blaming. (line 134) |
| 10112 | * M-w <1>: Common Commands. (line 39) |
| 10113 | * magit-run-hooks-from-githooks: Running Git. (line 225) |
| 10114 | * magit-user-githook-file: Running Git. (line 238) |
| 10115 | * MM: Rebasing. (line 248) |
| 10116 | * Mt: Rebasing. (line 254) |
| 10117 | * n: Sections. (line 38) |
| 10118 | * n <1>: Blaming. (line 118) |
| 10119 | * N: Blaming. (line 121) |
| 10120 | * n <2>: Rebasing. (line 155) |
| 10121 | * n <3>: Minor Mode for Buffers Visiting Blobs. |
| 10122 | (line 17) |
| 10123 | * o: Submodules. (line 56) |
| 10124 | * O: Subtree. (line 9) |
| 10125 | * o a: Submodules. (line 69) |
| 10126 | * o d: Submodules. (line 94) |
| 10127 | * O e: Subtree. (line 37) |
| 10128 | * O e p: Subtree. (line 48) |
| 10129 | * O e s: Subtree. (line 52) |
| 10130 | * o f: Submodules. (line 100) |
| 10131 | * O i: Subtree. (line 13) |
| 10132 | * O i a: Subtree. (line 24) |
| 10133 | * O i c: Subtree. (line 28) |
| 10134 | * O i f: Subtree. (line 34) |
| 10135 | * O i m: Subtree. (line 31) |
| 10136 | * o l: Submodules. (line 97) |
| 10137 | * o p: Submodules. (line 81) |
| 10138 | * o r: Submodules. (line 75) |
| 10139 | * o s: Submodules. (line 89) |
| 10140 | * o u: Submodules. (line 85) |
| 10141 | * p: Sections. (line 33) |
| 10142 | * p <1>: Blaming. (line 124) |
| 10143 | * P: Blaming. (line 127) |
| 10144 | * p <2>: Rebasing. (line 152) |
| 10145 | * P <1>: Pushing. (line 10) |
| 10146 | * p <3>: Minor Mode for Buffers Visiting Blobs. |
| 10147 | (line 13) |
| 10148 | * P C: Branching. (line 81) |
| 10149 | * P e: Pushing. (line 29) |
| 10150 | * P m: Pushing. (line 45) |
| 10151 | * P o: Pushing. (line 33) |
| 10152 | * P p: Pushing. (line 15) |
| 10153 | * P r: Pushing. (line 37) |
| 10154 | * P t: Pushing. (line 52) |
| 10155 | * P T: Pushing. (line 59) |
| 10156 | * P u: Pushing. (line 22) |
| 10157 | * q: Modes and Buffers. (line 206) |
| 10158 | * q <1>: Logging. (line 110) |
| 10159 | * q <2>: Blaming. (line 130) |
| 10160 | * q <3>: Minor Mode for Buffers Visiting Blobs. |
| 10161 | (line 20) |
| 10162 | * r: Rebasing. (line 10) |
| 10163 | * r <1>: Rebasing. (line 164) |
| 10164 | * r a: Rebasing. (line 121) |
| 10165 | * r e: Rebasing. (line 42) |
| 10166 | * r e <1>: Rebasing. (line 117) |
| 10167 | * r f: Rebasing. (line 84) |
| 10168 | * r i: Rebasing. (line 81) |
| 10169 | * r k: Rebasing. (line 101) |
| 10170 | * r m: Rebasing. (line 93) |
| 10171 | * r p: Rebasing. (line 28) |
| 10172 | * r r: Rebasing. (line 107) |
| 10173 | * r s: Rebasing. (line 47) |
| 10174 | * r s <1>: Rebasing. (line 113) |
| 10175 | * r u: Rebasing. (line 35) |
| 10176 | * r w: Rebasing. (line 97) |
| 10177 | * RET: Repository List. (line 106) |
| 10178 | * RET <1>: References Buffer. (line 159) |
| 10179 | * RET <2>: Visiting Files and Blobs. |
| 10180 | (line 41) |
| 10181 | * RET <3>: Blaming. (line 91) |
| 10182 | * RET <4>: Rebasing. (line 136) |
| 10183 | * s: Staging and Unstaging. |
| 10184 | (line 29) |
| 10185 | * S: Staging and Unstaging. |
| 10186 | (line 36) |
| 10187 | * s <1>: Rebasing. (line 170) |
| 10188 | * S <1>: Rebasing. (line 175) |
| 10189 | * S-<tab>: Sections. (line 167) |
| 10190 | * SPC: Logging. (line 137) |
| 10191 | * SPC <1>: Diffing. (line 264) |
| 10192 | * SPC <2>: Blaming. (line 94) |
| 10193 | * SPC <3>: Rebasing. (line 140) |
| 10194 | * t: Rebasing. (line 243) |
| 10195 | * t <1>: Tagging. (line 9) |
| 10196 | * T: Notes. (line 9) |
| 10197 | * T a: Notes. (line 47) |
| 10198 | * T c: Notes. (line 43) |
| 10199 | * t k: Tagging. (line 37) |
| 10200 | * T m: Notes. (line 35) |
| 10201 | * t p: Tagging. (line 43) |
| 10202 | * T p: Notes. (line 28) |
| 10203 | * t r: Tagging. (line 18) |
| 10204 | * T r: Notes. (line 21) |
| 10205 | * t t: Tagging. (line 14) |
| 10206 | * T T: Notes. (line 14) |
| 10207 | * TAB: Sections. (line 144) |
| 10208 | * u: Repository List. (line 112) |
| 10209 | * u <1>: Staging and Unstaging. |
| 10210 | (line 42) |
| 10211 | * U: Staging and Unstaging. |
| 10212 | (line 50) |
| 10213 | * v: Applying. (line 47) |
| 10214 | * V: Cherry Picking. (line 98) |
| 10215 | * V a: Cherry Picking. (line 126) |
| 10216 | * V s: Cherry Picking. (line 123) |
| 10217 | * V V: Cherry Picking. (line 106) |
| 10218 | * V v: Cherry Picking. (line 111) |
| 10219 | * V V <1>: Cherry Picking. (line 120) |
| 10220 | * W: Plain Patches. (line 7) |
| 10221 | * w: Maildir Patches. (line 9) |
| 10222 | * w a: Plain Patches. (line 20) |
| 10223 | * w a <1>: Maildir Patches. (line 23) |
| 10224 | * w a <2>: Maildir Patches. (line 38) |
| 10225 | * W c: Plain Patches. (line 12) |
| 10226 | * w m: Maildir Patches. (line 20) |
| 10227 | * W s: Plain Patches. (line 26) |
| 10228 | * w s: Maildir Patches. (line 34) |
| 10229 | * w w: Maildir Patches. (line 14) |
| 10230 | * w w <1>: Maildir Patches. (line 31) |
| 10231 | * x: Rebasing. (line 208) |
| 10232 | * x <1>: Resetting. (line 9) |
| 10233 | * X f: Resetting. (line 44) |
| 10234 | * X h: Resetting. (line 24) |
| 10235 | * X i: Resetting. (line 33) |
| 10236 | * X k: Resetting. (line 28) |
| 10237 | * X m: Resetting. (line 15) |
| 10238 | * X s: Resetting. (line 19) |
| 10239 | * X w: Resetting. (line 39) |
| 10240 | * X w <1>: Wip Modes. (line 59) |
| 10241 | * Y: Logging. (line 382) |
| 10242 | * y: References Buffer. (line 7) |
| 10243 | * y <1>: Rebasing. (line 220) |
| 10244 | * y c: References Buffer. (line 25) |
| 10245 | * y o: References Buffer. (line 30) |
| 10246 | * y r: References Buffer. (line 34) |
| 10247 | * y y: References Buffer. (line 21) |
| 10248 | * z: Stashing. (line 9) |
| 10249 | * Z: Worktree. (line 9) |
| 10250 | * z a: Stashing. (line 52) |
| 10251 | * z b: Stashing. (line 101) |
| 10252 | * z B: Stashing. (line 106) |
| 10253 | * Z b: Worktree. (line 13) |
| 10254 | * Z c: Worktree. (line 16) |
| 10255 | * z f: Stashing. (line 111) |
| 10256 | * Z g: Worktree. (line 26) |
| 10257 | * z i: Stashing. (line 20) |
| 10258 | * z I: Stashing. (line 42) |
| 10259 | * z k: Stashing. (line 94) |
| 10260 | * Z k: Worktree. (line 22) |
| 10261 | * z l: Stashing. (line 117) |
| 10262 | * Z m: Worktree. (line 19) |
| 10263 | * z p: Stashing. (line 72) |
| 10264 | * z v: Stashing. (line 98) |
| 10265 | * z w: Stashing. (line 24) |
| 10266 | * z W: Stashing. (line 46) |
| 10267 | * z x: Stashing. (line 30) |
| 10268 | * z z: Stashing. (line 14) |
| 10269 | * z Z: Stashing. (line 36) |
| 10270 | |
| 10271 | |
| 10272 | File: magit.info, Node: Function and Command Index, Next: Variable Index, Prev: Keystroke Index, Up: Top |
| 10273 | |
| 10274 | Appendix D Function and Command Index |
| 10275 | ************************************* |
| 10276 | |
| 10277 | [index ] |
| 10278 | * Menu: |
| 10279 | |
| 10280 | * bug-reference-mode: Committing. (line 481) |
| 10281 | * forward-line: Rebasing. (line 155) |
| 10282 | * git-commit-ack: Committing. (line 415) |
| 10283 | * git-commit-cc: Committing. (line 427) |
| 10284 | * git-commit-check-style-conventions: Committing. (line 533) |
| 10285 | * git-commit-insert-pseudo-header: Committing. (line 412) |
| 10286 | * git-commit-next-message: Committing. (line 326) |
| 10287 | * git-commit-prev-message: Committing. (line 321) |
| 10288 | * git-commit-propertize-diff: Committing. (line 473) |
| 10289 | * git-commit-reported: Committing. (line 430) |
| 10290 | * git-commit-review: Committing. (line 418) |
| 10291 | * git-commit-save-message: Committing. (line 318) |
| 10292 | * git-commit-save-message <1>: Committing. (line 459) |
| 10293 | * git-commit-setup-changelog-support: Committing. (line 462) |
| 10294 | * git-commit-signoff: Committing. (line 421) |
| 10295 | * git-commit-suggested: Committing. (line 434) |
| 10296 | * git-commit-test: Committing. (line 424) |
| 10297 | * git-commit-turn-on-auto-fill: Committing. (line 466) |
| 10298 | * git-commit-turn-on-flyspell: Committing. (line 469) |
| 10299 | * git-rebase-alter: Rebasing. (line 189) |
| 10300 | * git-rebase-backward-line: Rebasing. (line 152) |
| 10301 | * git-rebase-break: Rebasing. (line 216) |
| 10302 | * git-rebase-edit: Rebasing. (line 167) |
| 10303 | * git-rebase-exec: Rebasing. (line 208) |
| 10304 | * git-rebase-fixup: Rebasing. (line 184) |
| 10305 | * git-rebase-insert: Rebasing. (line 220) |
| 10306 | * git-rebase-kill-line: Rebasing. (line 201) |
| 10307 | * git-rebase-label: Rebasing. (line 240) |
| 10308 | * git-rebase-merge: Rebasing. (line 248) |
| 10309 | * git-rebase-merge-toggle-editmsg: Rebasing. (line 254) |
| 10310 | * git-rebase-move-line-down: Rebasing. (line 161) |
| 10311 | * git-rebase-move-line-up: Rebasing. (line 158) |
| 10312 | * git-rebase-pick: Rebasing. (line 205) |
| 10313 | * git-rebase-reset: Rebasing. (line 243) |
| 10314 | * git-rebase-reword: Rebasing. (line 164) |
| 10315 | * git-rebase-show-commit: Rebasing. (line 136) |
| 10316 | * git-rebase-show-or-scroll-down: Rebasing. (line 146) |
| 10317 | * git-rebase-show-or-scroll-up: Rebasing. (line 140) |
| 10318 | * git-rebase-squash: Rebasing. (line 170) |
| 10319 | * git-rebase-squish: Rebasing. (line 175) |
| 10320 | * git-rebase-undo: Rebasing. (line 223) |
| 10321 | * magit-add-section-hook: Sections. (line 310) |
| 10322 | * magit-after-save-refresh-status: Modes and Buffers. (line 294) |
| 10323 | * magit-am: Maildir Patches. (line 9) |
| 10324 | * magit-am-abort: Maildir Patches. (line 38) |
| 10325 | * magit-am-apply-maildir: Maildir Patches. (line 20) |
| 10326 | * magit-am-apply-patches: Maildir Patches. (line 14) |
| 10327 | * magit-am-continue: Maildir Patches. (line 31) |
| 10328 | * magit-am-skip: Maildir Patches. (line 34) |
| 10329 | * magit-apply: Applying. (line 34) |
| 10330 | * magit-bisect: Bisecting. (line 9) |
| 10331 | * magit-bisect-bad: Bisecting. (line 38) |
| 10332 | * magit-bisect-good: Bisecting. (line 42) |
| 10333 | * magit-bisect-mark: Bisecting. (line 46) |
| 10334 | * magit-bisect-reset: Bisecting. (line 57) |
| 10335 | * magit-bisect-run: Bisecting. (line 32) |
| 10336 | * magit-bisect-skip: Bisecting. (line 52) |
| 10337 | * magit-bisect-start: Bisecting. (line 16) |
| 10338 | * magit-blame: Blaming. (line 28) |
| 10339 | * magit-blame <1>: Blaming. (line 34) |
| 10340 | * magit-blame <2>: Blaming. (line 115) |
| 10341 | * magit-blame <3>: Commands for Buffers Visiting Files. |
| 10342 | (line 52) |
| 10343 | * magit-blame <4>: Commands for Buffers Visiting Files. |
| 10344 | (line 144) |
| 10345 | * magit-blame-addition: Blaming. (line 28) |
| 10346 | * magit-blame-addition <1>: Blaming. (line 45) |
| 10347 | * magit-blame-additions: Commands for Buffers Visiting Files. |
| 10348 | (line 52) |
| 10349 | * magit-blame-copy-hash: Blaming. (line 134) |
| 10350 | * magit-blame-cycle-style: Blaming. (line 141) |
| 10351 | * magit-blame-echo: Blaming. (line 28) |
| 10352 | * magit-blame-echo <1>: Blaming. (line 76) |
| 10353 | * magit-blame-echo <2>: Commands for Buffers Visiting Files. |
| 10354 | (line 52) |
| 10355 | * magit-blame-next-chunk: Blaming. (line 118) |
| 10356 | * magit-blame-next-chunk-same-commit: Blaming. (line 121) |
| 10357 | * magit-blame-previous-chunk: Blaming. (line 124) |
| 10358 | * magit-blame-previous-chunk-same-commit: Blaming. (line 127) |
| 10359 | * magit-blame-quit: Blaming. (line 28) |
| 10360 | * magit-blame-quit <1>: Blaming. (line 87) |
| 10361 | * magit-blame-quit <2>: Blaming. (line 130) |
| 10362 | * magit-blame-quit <3>: Commands for Buffers Visiting Files. |
| 10363 | (line 52) |
| 10364 | * magit-blame-removal: Blaming. (line 28) |
| 10365 | * magit-blame-removal <1>: Blaming. (line 60) |
| 10366 | * magit-blame-removal <2>: Commands for Buffers Visiting Files. |
| 10367 | (line 52) |
| 10368 | * magit-blame-reverse: Blaming. (line 28) |
| 10369 | * magit-blame-reverse <1>: Blaming. (line 68) |
| 10370 | * magit-blame-reverse <2>: Commands for Buffers Visiting Files. |
| 10371 | (line 52) |
| 10372 | * magit-blob-next: Commands for Buffers Visiting Files. |
| 10373 | (line 52) |
| 10374 | * magit-blob-next <1>: Commands for Buffers Visiting Files. |
| 10375 | (line 160) |
| 10376 | * magit-blob-next <2>: Minor Mode for Buffers Visiting Blobs. |
| 10377 | (line 17) |
| 10378 | * magit-blob-previous: Commands for Buffers Visiting Files. |
| 10379 | (line 52) |
| 10380 | * magit-blob-previous <1>: Commands for Buffers Visiting Files. |
| 10381 | (line 156) |
| 10382 | * magit-blob-previous <2>: Minor Mode for Buffers Visiting Blobs. |
| 10383 | (line 13) |
| 10384 | * magit-blob-visit-file: Commands for Buffers Visiting Files. |
| 10385 | (line 52) |
| 10386 | * magit-blob-visit-file <1>: Commands for Buffers Visiting Files. |
| 10387 | (line 167) |
| 10388 | * magit-branch: Branching. (line 63) |
| 10389 | * magit-branch-and-checkout: Branching. (line 113) |
| 10390 | * magit-branch-checkout: Branching. (line 119) |
| 10391 | * magit-branch-configure: Branching. (line 81) |
| 10392 | * magit-branch-create: Branching. (line 104) |
| 10393 | * magit-branch-delete: Branching. (line 188) |
| 10394 | * magit-branch-or-checkout: Branching. (line 325) |
| 10395 | * magit-branch-orphan: Branching. (line 321) |
| 10396 | * magit-branch-rename: Branching. (line 199) |
| 10397 | * magit-branch-reset: Branching. (line 173) |
| 10398 | * magit-branch-shelve: Branching. (line 465) |
| 10399 | * magit-branch-spinoff: Branching. (line 141) |
| 10400 | * magit-branch-spinout: Branching. (line 168) |
| 10401 | * magit-branch-unshelve: Branching. (line 475) |
| 10402 | * magit-builtin-completing-read: Completion Confirmation and the Selection. |
| 10403 | (line 354) |
| 10404 | * magit-bundle: Bundle. (line 8) |
| 10405 | * magit-bury-or-kill-buffer: Minor Mode for Buffers Visiting Blobs. |
| 10406 | (line 20) |
| 10407 | * magit-call-git: Calling Git. (line 138) |
| 10408 | * magit-call-process: Calling Git. (line 145) |
| 10409 | * magit-cancel-section: Section Plumbing. (line 73) |
| 10410 | * magit-checkout: Branching. (line 97) |
| 10411 | * magit-checkout-remote-ref: Branching. (line 204) |
| 10412 | * magit-cherry: Logging. (line 382) |
| 10413 | * magit-cherry-apply: Cherry Picking. (line 23) |
| 10414 | * magit-cherry-copy: Cherry Picking. (line 17) |
| 10415 | * magit-cherry-donate: Cherry Picking. (line 51) |
| 10416 | * magit-cherry-harvest: Cherry Picking. (line 40) |
| 10417 | * magit-cherry-pick: Cherry Picking. (line 9) |
| 10418 | * magit-cherry-spinoff: Cherry Picking. (line 72) |
| 10419 | * magit-cherry-spinout: Cherry Picking. (line 62) |
| 10420 | * magit-clone: Cloning Repository. (line 20) |
| 10421 | * magit-clone-bare: Cloning Repository. (line 44) |
| 10422 | * magit-clone-mirror: Cloning Repository. (line 48) |
| 10423 | * magit-clone-regular: Cloning Repository. (line 28) |
| 10424 | * magit-clone-shallow: Cloning Repository. (line 32) |
| 10425 | * magit-clone-shallow-exclude: Cloning Repository. (line 61) |
| 10426 | * magit-clone-shallow-since: Cloning Repository. (line 55) |
| 10427 | * magit-clone-sparse: Cloning Repository. (line 38) |
| 10428 | * magit-commit: Committing. (line 21) |
| 10429 | * magit-commit <1>: Commands for Buffers Visiting Files. |
| 10430 | (line 52) |
| 10431 | * magit-commit <2>: Commands for Buffers Visiting Files. |
| 10432 | (line 186) |
| 10433 | * magit-commit-alter: Committing. (line 141) |
| 10434 | * magit-commit-amend: Committing. (line 59) |
| 10435 | * magit-commit-augment: Committing. (line 153) |
| 10436 | * magit-commit-create: Committing. (line 29) |
| 10437 | * magit-commit-extend: Committing. (line 45) |
| 10438 | * magit-commit-fixup: Committing. (line 119) |
| 10439 | * magit-commit-instant-fixup: Committing. (line 192) |
| 10440 | * magit-commit-instant-squash: Committing. (line 204) |
| 10441 | * magit-commit-revise: Committing. (line 167) |
| 10442 | * magit-commit-reword: Committing. (line 65) |
| 10443 | * magit-commit-squash: Committing. (line 130) |
| 10444 | * magit-completing-read: Completion Confirmation and the Selection. |
| 10445 | (line 359) |
| 10446 | * magit-copy-buffer-revision: Common Commands. (line 39) |
| 10447 | * magit-copy-diff-as-kill: Applying. (line 55) |
| 10448 | * magit-copy-section-value: Common Commands. (line 22) |
| 10449 | * magit-current-section: Section Plumbing. (line 85) |
| 10450 | * magit-cycle-margin-style: Logging. (line 274) |
| 10451 | * magit-debug-git-executable: Running Git. (line 193) |
| 10452 | * magit-debug-git-executable <1>: Debugging Tools. (line 69) |
| 10453 | * magit-define-section-jumper: Section Plumbing. (line 78) |
| 10454 | * magit-describe-section: Sections. (line 350) |
| 10455 | * magit-describe-section-briefly: Sections. (line 367) |
| 10456 | * magit-describe-section-briefly <1>: Section Plumbing. (line 124) |
| 10457 | * magit-diff: Diffing. (line 22) |
| 10458 | * magit-diff <1>: Commands for Buffers Visiting Files. |
| 10459 | (line 52) |
| 10460 | * magit-diff <2>: Commands for Buffers Visiting Files. |
| 10461 | (line 91) |
| 10462 | * magit-diff-buffer-file: Commands for Buffers Visiting Files. |
| 10463 | (line 52) |
| 10464 | * magit-diff-buffer-file <1>: Commands for Buffers Visiting Files. |
| 10465 | (line 101) |
| 10466 | * magit-diff-default-context: Diffing. (line 193) |
| 10467 | * magit-diff-dwim: Diffing. (line 27) |
| 10468 | * magit-diff-edit-hunk-commit: Diffing. (line 235) |
| 10469 | * magit-diff-flip-revs: Diffing. (line 170) |
| 10470 | * magit-diff-less-context: Diffing. (line 187) |
| 10471 | * magit-diff-more-context: Diffing. (line 190) |
| 10472 | * magit-diff-paths: Diffing. (line 75) |
| 10473 | * magit-diff-range: Diffing. (line 49) |
| 10474 | * magit-diff-refresh: Diffing. (line 105) |
| 10475 | * magit-diff-refresh <1>: Diffing. (line 110) |
| 10476 | * magit-diff-save-default-arguments: Diffing. (line 120) |
| 10477 | * magit-diff-scope: Section Plumbing. (line 228) |
| 10478 | * magit-diff-set-default-arguments: Diffing. (line 114) |
| 10479 | * magit-diff-show-or-scroll-down: Logging. (line 146) |
| 10480 | * magit-diff-show-or-scroll-down <1>: Blaming. (line 103) |
| 10481 | * magit-diff-show-or-scroll-up: Logging. (line 137) |
| 10482 | * magit-diff-show-or-scroll-up <1>: Blaming. (line 94) |
| 10483 | * magit-diff-staged: Diffing. (line 67) |
| 10484 | * magit-diff-switch-range-type: Diffing. (line 166) |
| 10485 | * magit-diff-toggle-file-filter: Diffing. (line 174) |
| 10486 | * magit-diff-toggle-fontify-hunk: Diffing. (line 146) |
| 10487 | * magit-diff-toggle-refine-hunk: Diffing. (line 127) |
| 10488 | * magit-diff-trace-definition: Diffing. (line 226) |
| 10489 | * magit-diff-type: Section Plumbing. (line 206) |
| 10490 | * magit-diff-unstaged: Diffing. (line 72) |
| 10491 | * magit-diff-visit-file: Visiting Files and Blobs. |
| 10492 | (line 41) |
| 10493 | * magit-diff-visit-file-other-frame: Visiting Files and Blobs. |
| 10494 | (line 85) |
| 10495 | * magit-diff-visit-file-other-window: Visiting Files and Blobs. |
| 10496 | (line 84) |
| 10497 | * magit-diff-visit-worktree-file: Visiting Files and Blobs. |
| 10498 | (line 64) |
| 10499 | * magit-diff-visit-worktree-file-other-frame: Visiting Files and Blobs. |
| 10500 | (line 87) |
| 10501 | * magit-diff-visit-worktree-file-other-window: Visiting Files and Blobs. |
| 10502 | (line 86) |
| 10503 | * magit-diff-while-committing: Diffing. (line 200) |
| 10504 | * magit-diff-while-committing <1>: Committing. (line 339) |
| 10505 | * magit-diff-working-tree: Diffing. (line 62) |
| 10506 | * magit-disable-section-inserter: Per-Repository Configuration. |
| 10507 | (line 31) |
| 10508 | * magit-discard: Applying. (line 40) |
| 10509 | * magit-dispatch: Transient Commands. (line 20) |
| 10510 | * magit-display-buffer: Modes and Buffers. (line 38) |
| 10511 | * magit-display-buffer-fullcolumn-most-v1: Modes and Buffers. (line 100) |
| 10512 | * magit-display-buffer-fullframe-status-topleft-v1: Modes and Buffers. |
| 10513 | (line 91) |
| 10514 | * magit-display-buffer-fullframe-status-v1: Modes and Buffers. |
| 10515 | (line 86) |
| 10516 | * magit-display-buffer-same-window-except-diff-v1: Modes and Buffers. |
| 10517 | (line 81) |
| 10518 | * magit-display-buffer-traditional: Modes and Buffers. (line 74) |
| 10519 | * magit-display-repository-buffer: Common Commands. (line 9) |
| 10520 | * magit-display-repository-buffer <1>: Commands for Buffers Visiting Files. |
| 10521 | (line 52) |
| 10522 | * magit-display-repository-buffer <2>: Commands for Buffers Visiting Files. |
| 10523 | (line 182) |
| 10524 | * magit-ediff: Ediffing. (line 21) |
| 10525 | * magit-ediff-compare: Ediffing. (line 25) |
| 10526 | * magit-ediff-dwim: Ediffing. (line 10) |
| 10527 | * magit-ediff-resolve-all: Ediffing. (line 48) |
| 10528 | * magit-ediff-resolve-rest: Ediffing. (line 33) |
| 10529 | * magit-ediff-show-commit: Ediffing. (line 100) |
| 10530 | * magit-ediff-show-staged: Ediffing. (line 94) |
| 10531 | * magit-ediff-show-stash: Ediffing. (line 103) |
| 10532 | * magit-ediff-show-unstaged: Ediffing. (line 91) |
| 10533 | * magit-ediff-show-working-tree: Ediffing. (line 97) |
| 10534 | * magit-ediff-stage: Ediffing. (line 87) |
| 10535 | * magit-edit-line-commit: Commands for Buffers Visiting Files. |
| 10536 | (line 52) |
| 10537 | * magit-edit-line-commit <1>: Commands for Buffers Visiting Files. |
| 10538 | (line 192) |
| 10539 | * magit-emacs-Q-command: Debugging Tools. (line 16) |
| 10540 | * magit-fetch: Fetching. (line 10) |
| 10541 | * magit-fetch-all: Fetching. (line 45) |
| 10542 | * magit-fetch-branch: Fetching. (line 37) |
| 10543 | * magit-fetch-from-pushremote: Fetching. (line 15) |
| 10544 | * magit-fetch-from-upstream: Fetching. (line 22) |
| 10545 | * magit-fetch-modules: Fetching. (line 48) |
| 10546 | * magit-fetch-modules <1>: Submodules. (line 100) |
| 10547 | * magit-fetch-other: Fetching. (line 34) |
| 10548 | * magit-fetch-refspec: Fetching. (line 41) |
| 10549 | * magit-file-checkout: Resetting. (line 44) |
| 10550 | * magit-file-checkout <1>: Commands for Buffers Visiting Files. |
| 10551 | (line 52) |
| 10552 | * magit-file-checkout <2>: Commands for Buffers Visiting Files. |
| 10553 | (line 86) |
| 10554 | * magit-file-delete: Commands for Buffers Visiting Files. |
| 10555 | (line 52) |
| 10556 | * magit-file-delete <1>: Commands for Buffers Visiting Files. |
| 10557 | (line 82) |
| 10558 | * magit-file-dispatch: Commands for Buffers Visiting Files. |
| 10559 | (line 52) |
| 10560 | * magit-file-dispatch <1>: Commands for Buffers Visiting Files. |
| 10561 | (line 58) |
| 10562 | * magit-file-rename: Commands for Buffers Visiting Files. |
| 10563 | (line 52) |
| 10564 | * magit-file-rename <1>: Commands for Buffers Visiting Files. |
| 10565 | (line 78) |
| 10566 | * magit-file-stage: Commands for Buffers Visiting Files. |
| 10567 | (line 52) |
| 10568 | * magit-file-stage <1>: Commands for Buffers Visiting Files. |
| 10569 | (line 63) |
| 10570 | * magit-file-unstage: Commands for Buffers Visiting Files. |
| 10571 | (line 52) |
| 10572 | * magit-file-unstage <1>: Commands for Buffers Visiting Files. |
| 10573 | (line 69) |
| 10574 | * magit-file-untrack: Commands for Buffers Visiting Files. |
| 10575 | (line 52) |
| 10576 | * magit-file-untrack <1>: Commands for Buffers Visiting Files. |
| 10577 | (line 74) |
| 10578 | * magit-find-file: Visiting Files and Blobs. |
| 10579 | (line 19) |
| 10580 | * magit-find-file <1>: Commands for Buffers Visiting Files. |
| 10581 | (line 52) |
| 10582 | * magit-find-file <2>: Commands for Buffers Visiting Files. |
| 10583 | (line 163) |
| 10584 | * magit-find-file-other-frame: Visiting Files and Blobs. |
| 10585 | (line 29) |
| 10586 | * magit-find-file-other-window: Visiting Files and Blobs. |
| 10587 | (line 24) |
| 10588 | * magit-generate-buffer-name-default-function: Modes and Buffers. |
| 10589 | (line 141) |
| 10590 | * magit-get-section: Section Plumbing. (line 131) |
| 10591 | * magit-git: Calling Git. (line 160) |
| 10592 | * magit-git-command: Running Git. (line 99) |
| 10593 | * magit-git-command-topdir: Running Git. (line 91) |
| 10594 | * magit-git-exit-code: Calling Git. (line 37) |
| 10595 | * magit-git-failure: Calling Git. (line 44) |
| 10596 | * magit-git-false: Calling Git. (line 52) |
| 10597 | * magit-git-insert: Calling Git. (line 56) |
| 10598 | * magit-git-items: Calling Git. (line 68) |
| 10599 | * magit-git-lines: Calling Git. (line 64) |
| 10600 | * magit-git-mergetool: Running Git. (line 136) |
| 10601 | * magit-git-mergetool <1>: Ediffing. (line 79) |
| 10602 | * magit-git-str: Calling Git. (line 102) |
| 10603 | * magit-git-string: Calling Git. (line 59) |
| 10604 | * magit-git-success: Calling Git. (line 40) |
| 10605 | * magit-git-true: Calling Git. (line 48) |
| 10606 | * magit-git-wash: Calling Git. (line 164) |
| 10607 | * magit-go-backward: Logging. (line 116) |
| 10608 | * magit-go-backward <1>: Diffing. (line 209) |
| 10609 | * magit-go-forward: Logging. (line 119) |
| 10610 | * magit-go-forward <1>: Diffing. (line 212) |
| 10611 | * magit-hunk-set-window-start: Sections. (line 69) |
| 10612 | * magit-init: Creating Repository. (line 7) |
| 10613 | * magit-insert-am-sequence: Status Buffer. (line 140) |
| 10614 | * magit-insert-assume-unchanged-files: Status Buffer. (line 255) |
| 10615 | * magit-insert-bisect-log: Status Buffer. (line 154) |
| 10616 | * magit-insert-bisect-output: Status Buffer. (line 148) |
| 10617 | * magit-insert-bisect-rest: Status Buffer. (line 151) |
| 10618 | * magit-insert-diff-filter-header: Status Buffer. (line 315) |
| 10619 | * magit-insert-error-header: Status Buffer. (line 306) |
| 10620 | * magit-insert-head-branch-header: Status Buffer. (line 318) |
| 10621 | * magit-insert-heading: Section Plumbing. (line 45) |
| 10622 | * magit-insert-ignored-files: Status Buffer. (line 249) |
| 10623 | * magit-insert-local-branches: References Buffer. (line 244) |
| 10624 | * magit-insert-merge-log: Status Buffer. (line 132) |
| 10625 | * magit-insert-modules: Status Buffer. (line 357) |
| 10626 | * magit-insert-modules-overview: Status Buffer. (line 375) |
| 10627 | * magit-insert-modules-unpulled-from-pushremote: Status Buffer. |
| 10628 | (line 390) |
| 10629 | * magit-insert-modules-unpulled-from-upstream: Status Buffer. (line 385) |
| 10630 | * magit-insert-modules-unpushed-to-pushremote: Status Buffer. (line 400) |
| 10631 | * magit-insert-modules-unpushed-to-upstream: Status Buffer. (line 395) |
| 10632 | * magit-insert-push-branch-header: Status Buffer. (line 325) |
| 10633 | * magit-insert-rebase-sequence: Status Buffer. (line 136) |
| 10634 | * magit-insert-recent-commits: Status Buffer. (line 261) |
| 10635 | * magit-insert-remote-branches: References Buffer. (line 247) |
| 10636 | * magit-insert-remote-header: Status Buffer. (line 338) |
| 10637 | * magit-insert-repo-header: Status Buffer. (line 335) |
| 10638 | * magit-insert-section: Section Plumbing. (line 9) |
| 10639 | * magit-insert-sequencer-sequence: Status Buffer. (line 144) |
| 10640 | * magit-insert-skip-worktree-files: Status Buffer. (line 252) |
| 10641 | * magit-insert-staged-changes: Status Buffer. (line 160) |
| 10642 | * magit-insert-stashes: Status Buffer. (line 163) |
| 10643 | * magit-insert-status-headers: Status Buffer. (line 127) |
| 10644 | * magit-insert-status-headers <1>: Status Buffer. (line 292) |
| 10645 | * magit-insert-tags: References Buffer. (line 250) |
| 10646 | * magit-insert-tags-header: Status Buffer. (line 329) |
| 10647 | * magit-insert-tracked-files: Status Buffer. (line 246) |
| 10648 | * magit-insert-unpulled-cherries: Status Buffer. (line 270) |
| 10649 | * magit-insert-unpulled-from-pushremote: Status Buffer. (line 173) |
| 10650 | * magit-insert-unpulled-from-upstream: Status Buffer. (line 169) |
| 10651 | * magit-insert-unpushed-cherries: Status Buffer. (line 276) |
| 10652 | * magit-insert-unpushed-to-pushremote: Status Buffer. (line 189) |
| 10653 | * magit-insert-unpushed-to-upstream: Status Buffer. (line 185) |
| 10654 | * magit-insert-unpushed-to-upstream-or-recent: Status Buffer. (line 177) |
| 10655 | * magit-insert-unstaged-changes: Status Buffer. (line 157) |
| 10656 | * magit-insert-untracked-files: Status Buffer. (line 199) |
| 10657 | * magit-insert-upstream-branch-header: Status Buffer. (line 321) |
| 10658 | * magit-insert-user-header: Status Buffer. (line 345) |
| 10659 | * magit-jump-to-diffstat-or-diff: Diffing. (line 254) |
| 10660 | * magit-list-repositories: Repository List. (line 6) |
| 10661 | * magit-list-submodules: Submodules. (line 18) |
| 10662 | * magit-list-submodules <1>: Submodules. (line 97) |
| 10663 | * magit-log: Logging. (line 28) |
| 10664 | * magit-log <1>: Commands for Buffers Visiting Files. |
| 10665 | (line 52) |
| 10666 | * magit-log <2>: Commands for Buffers Visiting Files. |
| 10667 | (line 116) |
| 10668 | * magit-log-all: Logging. (line 59) |
| 10669 | * magit-log-all-branches: Logging. (line 56) |
| 10670 | * magit-log-branches: Logging. (line 53) |
| 10671 | * magit-log-buffer-file: Commands for Buffers Visiting Files. |
| 10672 | (line 52) |
| 10673 | * magit-log-buffer-file <1>: Commands for Buffers Visiting Files. |
| 10674 | (line 126) |
| 10675 | * magit-log-bury-buffer: Logging. (line 110) |
| 10676 | * magit-log-current: Logging. (line 33) |
| 10677 | * magit-log-double-commit-limit: Logging. (line 160) |
| 10678 | * magit-log-half-commit-limit: Logging. (line 163) |
| 10679 | * magit-log-head: Logging. (line 38) |
| 10680 | * magit-log-maybe-show-more-commits: Sections. (line 82) |
| 10681 | * magit-log-maybe-update-blob-buffer: Sections. (line 96) |
| 10682 | * magit-log-maybe-update-revision-buffer: Sections. (line 89) |
| 10683 | * magit-log-merged: Commands for Buffers Visiting Files. |
| 10684 | (line 52) |
| 10685 | * magit-log-merged <1>: Commands for Buffers Visiting Files. |
| 10686 | (line 139) |
| 10687 | * magit-log-move-to-parent: Logging. (line 122) |
| 10688 | * magit-log-move-to-revision: Logging. (line 127) |
| 10689 | * magit-log-other: Logging. (line 47) |
| 10690 | * magit-log-refresh: Logging. (line 75) |
| 10691 | * magit-log-refresh <1>: Logging. (line 80) |
| 10692 | * magit-log-refresh <2>: Logging. (line 103) |
| 10693 | * magit-log-related: Logging. (line 41) |
| 10694 | * magit-log-save-default-arguments: Logging. (line 90) |
| 10695 | * magit-log-select-pick: Logging. (line 297) |
| 10696 | * magit-log-select-quit: Logging. (line 302) |
| 10697 | * magit-log-set-default-arguments: Logging. (line 84) |
| 10698 | * magit-log-toggle-commit-limit: Logging. (line 155) |
| 10699 | * magit-log-trace-definition: Commands for Buffers Visiting Files. |
| 10700 | (line 52) |
| 10701 | * magit-log-trace-definition <1>: Commands for Buffers Visiting Files. |
| 10702 | (line 136) |
| 10703 | * magit-margin-settings: Logging. (line 263) |
| 10704 | * magit-maybe-set-dedicated: Modes and Buffers. (line 121) |
| 10705 | * magit-merge: Merging. (line 10) |
| 10706 | * magit-merge <1>: Merging. (line 92) |
| 10707 | * magit-merge-abort: Merging. (line 97) |
| 10708 | * magit-merge-absorb: Merging. (line 46) |
| 10709 | * magit-merge-dissolve: Merging. (line 60) |
| 10710 | * magit-merge-editmsg: Merging. (line 32) |
| 10711 | * magit-merge-nocommit: Merging. (line 40) |
| 10712 | * magit-merge-plain: Merging. (line 18) |
| 10713 | * magit-merge-preview: Merging. (line 81) |
| 10714 | * magit-merge-squash: Merging. (line 73) |
| 10715 | * magit-mode-bury-buffer: Modes and Buffers. (line 206) |
| 10716 | * magit-mode-display-buffer: Refreshing Buffers. (line 32) |
| 10717 | * magit-mode-quit-window: Modes and Buffers. (line 233) |
| 10718 | * magit-mode-setup: Refreshing Buffers. (line 17) |
| 10719 | * magit-notes: Notes. (line 9) |
| 10720 | * magit-notes-edit: Notes. (line 14) |
| 10721 | * magit-notes-merge: Notes. (line 35) |
| 10722 | * magit-notes-merge-abort: Notes. (line 47) |
| 10723 | * magit-notes-merge-commit: Notes. (line 43) |
| 10724 | * magit-notes-prune: Notes. (line 28) |
| 10725 | * magit-notes-remove: Notes. (line 21) |
| 10726 | * magit-parent-status: Status Buffer. (line 100) |
| 10727 | * magit-patch: Plain Patches. (line 7) |
| 10728 | * magit-patch-apply: Plain Patches. (line 20) |
| 10729 | * magit-patch-apply <1>: Maildir Patches. (line 23) |
| 10730 | * magit-patch-create: Plain Patches. (line 12) |
| 10731 | * magit-patch-save: Plain Patches. (line 26) |
| 10732 | * magit-pop-revision-stack: Committing. (line 347) |
| 10733 | * magit-process-buffer: Running Git. (line 20) |
| 10734 | * magit-process-file: Calling Git. (line 84) |
| 10735 | * magit-process-git: Calling Git. (line 77) |
| 10736 | * magit-process-kill: Running Git. (line 27) |
| 10737 | * magit-profile-refresh-buffer: Debugging Tools. (line 76) |
| 10738 | * magit-pull: Pulling. (line 10) |
| 10739 | * magit-pull-branch: Pulling. (line 28) |
| 10740 | * magit-pull-from-pushremote: Pulling. (line 14) |
| 10741 | * magit-pull-from-upstream: Pulling. (line 21) |
| 10742 | * magit-pull-into-upstream: Pulling. (line 34) |
| 10743 | * magit-push: Pushing. (line 10) |
| 10744 | * magit-push-current: Pushing. (line 29) |
| 10745 | * magit-push-current-to-pushremote: Pushing. (line 15) |
| 10746 | * magit-push-current-to-upstream: Pushing. (line 22) |
| 10747 | * magit-push-implicitly: Pushing. (line 74) |
| 10748 | * magit-push-matching: Pushing. (line 45) |
| 10749 | * magit-push-other: Pushing. (line 33) |
| 10750 | * magit-push-refspecs: Pushing. (line 37) |
| 10751 | * magit-push-tag: Pushing. (line 59) |
| 10752 | * magit-push-tags: Pushing. (line 52) |
| 10753 | * magit-push-to-remote: Pushing. (line 91) |
| 10754 | * magit-rebase: Rebasing. (line 10) |
| 10755 | * magit-rebase-abort: Rebasing. (line 121) |
| 10756 | * magit-rebase-autosquash: Rebasing. (line 84) |
| 10757 | * magit-rebase-branch: Rebasing. (line 42) |
| 10758 | * magit-rebase-continue: Rebasing. (line 107) |
| 10759 | * magit-rebase-edit: Rebasing. (line 117) |
| 10760 | * magit-rebase-edit-commit: Rebasing. (line 93) |
| 10761 | * magit-rebase-interactive: Rebasing. (line 81) |
| 10762 | * magit-rebase-onto-pushremote: Rebasing. (line 28) |
| 10763 | * magit-rebase-onto-upstream: Rebasing. (line 35) |
| 10764 | * magit-rebase-remove-commit: Rebasing. (line 101) |
| 10765 | * magit-rebase-reword-commit: Rebasing. (line 97) |
| 10766 | * magit-rebase-skip: Rebasing. (line 113) |
| 10767 | * magit-rebase-subset: Rebasing. (line 47) |
| 10768 | * magit-reflog-current: Logging. (line 336) |
| 10769 | * magit-reflog-head: Logging. (line 342) |
| 10770 | * magit-reflog-other: Logging. (line 339) |
| 10771 | * magit-refresh: Modes and Buffers. (line 265) |
| 10772 | * magit-refresh-all: Modes and Buffers. (line 273) |
| 10773 | * magit-refs-set-show-commit-count: References Buffer. (line 34) |
| 10774 | * magit-region-sections: Section Plumbing. (line 88) |
| 10775 | * magit-region-values: Section Plumbing. (line 114) |
| 10776 | * magit-remote: Remotes. (line 17) |
| 10777 | * magit-remote-add: Remotes. (line 51) |
| 10778 | * magit-remote-configure: Remotes. (line 35) |
| 10779 | * magit-remote-prune: Remotes. (line 66) |
| 10780 | * magit-remote-prune-refspecs: Remotes. (line 70) |
| 10781 | * magit-remote-remove: Remotes. (line 63) |
| 10782 | * magit-remote-rename: Remotes. (line 55) |
| 10783 | * magit-remote-set-url: Remotes. (line 59) |
| 10784 | * magit-repolist-column-branch: Repository List. (line 55) |
| 10785 | * magit-repolist-column-branches: Repository List. (line 62) |
| 10786 | * magit-repolist-column-flag: Repository List. (line 68) |
| 10787 | * magit-repolist-column-flags: Repository List. (line 80) |
| 10788 | * magit-repolist-column-ident: Repository List. (line 44) |
| 10789 | * magit-repolist-column-path: Repository List. (line 48) |
| 10790 | * magit-repolist-column-stashes: Repository List. (line 65) |
| 10791 | * magit-repolist-column-unpulled-from-pushremote: Repository List. |
| 10792 | (line 91) |
| 10793 | * magit-repolist-column-unpulled-from-upstream: Repository List. |
| 10794 | (line 87) |
| 10795 | * magit-repolist-column-unpushed-to-pushremote: Repository List. |
| 10796 | (line 99) |
| 10797 | * magit-repolist-column-unpushed-to-upstream: Repository List. |
| 10798 | (line 95) |
| 10799 | * magit-repolist-column-upstream: Repository List. (line 58) |
| 10800 | * magit-repolist-column-version: Repository List. (line 51) |
| 10801 | * magit-repolist-fetch: Repository List. (line 115) |
| 10802 | * magit-repolist-find-file-other-frame: Repository List. (line 119) |
| 10803 | * magit-repolist-mark: Repository List. (line 109) |
| 10804 | * magit-repolist-status: Repository List. (line 106) |
| 10805 | * magit-repolist-unmark: Repository List. (line 112) |
| 10806 | * magit-reset-hard: Resetting. (line 24) |
| 10807 | * magit-reset-index: Staging and Unstaging. |
| 10808 | (line 78) |
| 10809 | * magit-reset-index <1>: Resetting. (line 33) |
| 10810 | * magit-reset-keep: Resetting. (line 28) |
| 10811 | * magit-reset-mixed: Resetting. (line 15) |
| 10812 | * magit-reset-quickly: Resetting. (line 9) |
| 10813 | * magit-reset-soft: Resetting. (line 19) |
| 10814 | * magit-reset-worktree: Resetting. (line 39) |
| 10815 | * magit-reset-worktree <1>: Wip Modes. (line 59) |
| 10816 | * magit-restore-window-configuration: Modes and Buffers. (line 223) |
| 10817 | * magit-reverse: Applying. (line 47) |
| 10818 | * magit-reverse-in-index: Staging and Unstaging. |
| 10819 | (line 58) |
| 10820 | * magit-revert: Cherry Picking. (line 98) |
| 10821 | * magit-revert-and-commit: Cherry Picking. (line 106) |
| 10822 | * magit-revert-no-commit: Cherry Picking. (line 111) |
| 10823 | * magit-run: Running Git. (line 87) |
| 10824 | * magit-run-git: Calling Git. (line 148) |
| 10825 | * magit-run-git-async: Calling Git. (line 173) |
| 10826 | * magit-run-git-gui: Running Git. (line 133) |
| 10827 | * magit-run-git-hook: Running Git. (line 255) |
| 10828 | * magit-run-git-with-editor: Calling Git. (line 185) |
| 10829 | * magit-run-git-with-input: Calling Git. (line 151) |
| 10830 | * magit-run-gitk: Running Git. (line 124) |
| 10831 | * magit-run-gitk-all: Running Git. (line 127) |
| 10832 | * magit-run-gitk-branches: Running Git. (line 130) |
| 10833 | * magit-save-window-configuration: Modes and Buffers. (line 112) |
| 10834 | * magit-section-backward: Sections. (line 33) |
| 10835 | * magit-section-backward-siblings: Sections. (line 41) |
| 10836 | * magit-section-case: Section Plumbing. (line 184) |
| 10837 | * magit-section-cycle: Sections. (line 148) |
| 10838 | * magit-section-cycle-diffs: Sections. (line 163) |
| 10839 | * magit-section-cycle-global: Sections. (line 167) |
| 10840 | * magit-section-forward: Sections. (line 38) |
| 10841 | * magit-section-forward-siblings: Sections. (line 46) |
| 10842 | * magit-section-hide: Sections. (line 189) |
| 10843 | * magit-section-hide-children: Sections. (line 201) |
| 10844 | * magit-section-ident: Section Plumbing. (line 127) |
| 10845 | * magit-section-match: Section Plumbing. (line 135) |
| 10846 | * magit-section-set-window-start: Sections. (line 76) |
| 10847 | * magit-section-show: Sections. (line 186) |
| 10848 | * magit-section-show-children: Sections. (line 196) |
| 10849 | * magit-section-show-headings: Sections. (line 192) |
| 10850 | * magit-section-show-level-1: Sections. (line 173) |
| 10851 | * magit-section-show-level-1-all: Sections. (line 179) |
| 10852 | * magit-section-show-level-2: Sections. (line 173) |
| 10853 | * magit-section-show-level-2-all: Sections. (line 179) |
| 10854 | * magit-section-show-level-3: Sections. (line 173) |
| 10855 | * magit-section-show-level-3-all: Sections. (line 179) |
| 10856 | * magit-section-show-level-4: Sections. (line 173) |
| 10857 | * magit-section-show-level-4-all: Sections. (line 179) |
| 10858 | * magit-section-toggle: Sections. (line 144) |
| 10859 | * magit-section-toggle-children: Sections. (line 204) |
| 10860 | * magit-section-up: Sections. (line 50) |
| 10861 | * magit-section-value-if: Section Plumbing. (line 174) |
| 10862 | * magit-sequence-abort: Cherry Picking. (line 91) |
| 10863 | * magit-sequence-abort <1>: Cherry Picking. (line 126) |
| 10864 | * magit-sequence-continue: Cherry Picking. (line 85) |
| 10865 | * magit-sequence-continue <1>: Cherry Picking. (line 120) |
| 10866 | * magit-sequence-skip: Cherry Picking. (line 88) |
| 10867 | * magit-sequence-skip <1>: Cherry Picking. (line 123) |
| 10868 | * magit-shell-command: Running Git. (line 112) |
| 10869 | * magit-shell-command-topdir: Running Git. (line 108) |
| 10870 | * magit-show-commit: Diffing. (line 82) |
| 10871 | * magit-show-commit <1>: Blaming. (line 91) |
| 10872 | * magit-show-commit-removing-file: Commands for Buffers Visiting Files. |
| 10873 | (line 108) |
| 10874 | * magit-show-refs: References Buffer. (line 7) |
| 10875 | * magit-show-refs-current: References Buffer. (line 25) |
| 10876 | * magit-show-refs-head: References Buffer. (line 21) |
| 10877 | * magit-show-refs-other: References Buffer. (line 30) |
| 10878 | * magit-snapshot-both: Stashing. (line 36) |
| 10879 | * magit-snapshot-index: Stashing. (line 42) |
| 10880 | * magit-snapshot-worktree: Stashing. (line 46) |
| 10881 | * magit-sparse-checkout: Sparse checkouts. (line 17) |
| 10882 | * magit-sparse-checkout-add: Sparse checkouts. (line 39) |
| 10883 | * magit-sparse-checkout-disable: Sparse checkouts. (line 50) |
| 10884 | * magit-sparse-checkout-enable: Sparse checkouts. (line 21) |
| 10885 | * magit-sparse-checkout-reapply: Sparse checkouts. (line 44) |
| 10886 | * magit-sparse-checkout-set: Sparse checkouts. (line 33) |
| 10887 | * magit-stage: Staging and Unstaging. |
| 10888 | (line 29) |
| 10889 | * magit-stage-files: Staging and Unstaging. |
| 10890 | (line 90) |
| 10891 | * magit-stage-files <1>: Commands for Buffers Visiting Files. |
| 10892 | (line 52) |
| 10893 | * magit-stage-files <2>: Commands for Buffers Visiting Files. |
| 10894 | (line 63) |
| 10895 | * magit-stage-modified: Staging and Unstaging. |
| 10896 | (line 36) |
| 10897 | * magit-start-git: Calling Git. (line 196) |
| 10898 | * magit-start-process: Calling Git. (line 214) |
| 10899 | * magit-stash: Stashing. (line 9) |
| 10900 | * magit-stash-apply: Stashing. (line 52) |
| 10901 | * magit-stash-both: Stashing. (line 14) |
| 10902 | * magit-stash-branch: Stashing. (line 101) |
| 10903 | * magit-stash-branch-here: Stashing. (line 106) |
| 10904 | * magit-stash-clear: Stashing. (line 114) |
| 10905 | * magit-stash-drop: Stashing. (line 94) |
| 10906 | * magit-stash-format-patch: Stashing. (line 111) |
| 10907 | * magit-stash-index: Stashing. (line 20) |
| 10908 | * magit-stash-keep-index: Stashing. (line 30) |
| 10909 | * magit-stash-list: Stashing. (line 117) |
| 10910 | * magit-stash-pop: Stashing. (line 72) |
| 10911 | * magit-stash-show: Diffing. (line 86) |
| 10912 | * magit-stash-show <1>: Stashing. (line 98) |
| 10913 | * magit-stash-worktree: Stashing. (line 24) |
| 10914 | * magit-stashes-maybe-update-stash-buffer: Sections. (line 116) |
| 10915 | * magit-status: Status Buffer. (line 23) |
| 10916 | * magit-status-here: Commands for Buffers Visiting Files. |
| 10917 | (line 52) |
| 10918 | * magit-status-here <1>: Commands for Buffers Visiting Files. |
| 10919 | (line 173) |
| 10920 | * magit-status-maybe-update-blob-buffer: Sections. (line 111) |
| 10921 | * magit-status-maybe-update-revision-buffer: Sections. (line 101) |
| 10922 | * magit-status-maybe-update-stash-buffer: Sections. (line 106) |
| 10923 | * magit-status-quick: Status Buffer. (line 74) |
| 10924 | * magit-submodule: Submodules. (line 56) |
| 10925 | * magit-submodule-add: Submodules. (line 69) |
| 10926 | * magit-submodule-populate: Submodules. (line 81) |
| 10927 | * magit-submodule-register: Submodules. (line 75) |
| 10928 | * magit-submodule-synchronize: Submodules. (line 89) |
| 10929 | * magit-submodule-unpopulate: Submodules. (line 94) |
| 10930 | * magit-submodule-update: Submodules. (line 85) |
| 10931 | * magit-subtree: Subtree. (line 9) |
| 10932 | * magit-subtree-add: Subtree. (line 24) |
| 10933 | * magit-subtree-add-commit: Subtree. (line 28) |
| 10934 | * magit-subtree-export: Subtree. (line 37) |
| 10935 | * magit-subtree-import: Subtree. (line 13) |
| 10936 | * magit-subtree-merge: Subtree. (line 31) |
| 10937 | * magit-subtree-pull: Subtree. (line 34) |
| 10938 | * magit-subtree-push: Subtree. (line 48) |
| 10939 | * magit-subtree-split: Subtree. (line 52) |
| 10940 | * magit-switch-to-repository-buffer: Common Commands. (line 6) |
| 10941 | * magit-switch-to-repository-buffer-other-frame: Common Commands. |
| 10942 | (line 8) |
| 10943 | * magit-switch-to-repository-buffer-other-window: Common Commands. |
| 10944 | (line 7) |
| 10945 | * magit-tag: Tagging. (line 9) |
| 10946 | * magit-tag-create: Tagging. (line 14) |
| 10947 | * magit-tag-delete: Tagging. (line 37) |
| 10948 | * magit-tag-prune: Tagging. (line 43) |
| 10949 | * magit-tag-release: Tagging. (line 18) |
| 10950 | * magit-toggle-buffer-lock: Modes and Buffers. (line 18) |
| 10951 | * magit-toggle-git-debug: Running Git. (line 32) |
| 10952 | * magit-toggle-git-debug <1>: Debugging Tools. (line 29) |
| 10953 | * magit-toggle-margin: Logging. (line 97) |
| 10954 | * magit-toggle-margin <1>: Logging. (line 271) |
| 10955 | * magit-toggle-margin-details: Logging. (line 277) |
| 10956 | * magit-toggle-profiling: Debugging Tools. (line 80) |
| 10957 | * magit-toggle-subprocess-record: Debugging Tools. (line 56) |
| 10958 | * magit-toggle-verbose-refresh: Debugging Tools. (line 51) |
| 10959 | * magit-unstage: Staging and Unstaging. |
| 10960 | (line 42) |
| 10961 | * magit-unstage-all: Staging and Unstaging. |
| 10962 | (line 50) |
| 10963 | * magit-unstage-files: Staging and Unstaging. |
| 10964 | (line 97) |
| 10965 | * magit-unstage-files <1>: Commands for Buffers Visiting Files. |
| 10966 | (line 52) |
| 10967 | * magit-unstage-files <2>: Commands for Buffers Visiting Files. |
| 10968 | (line 69) |
| 10969 | * magit-version: Running Git. (line 197) |
| 10970 | * magit-version <1>: Debugging Tools. (line 11) |
| 10971 | * magit-visit-ref: References Buffer. (line 159) |
| 10972 | * magit-wip-commit: Wip Modes. (line 80) |
| 10973 | * magit-wip-log: Wip Modes. (line 42) |
| 10974 | * magit-wip-log-current: Wip Modes. (line 50) |
| 10975 | * magit-worktree: Worktree. (line 9) |
| 10976 | * magit-worktree-branch: Worktree. (line 16) |
| 10977 | * magit-worktree-checkout: Worktree. (line 13) |
| 10978 | * magit-worktree-delete: Worktree. (line 22) |
| 10979 | * magit-worktree-move: Worktree. (line 19) |
| 10980 | * magit-worktree-status: Worktree. (line 26) |
| 10981 | * scroll-down: Diffing. (line 267) |
| 10982 | * scroll-up: Diffing. (line 264) |
| 10983 | * with-editor-cancel: Committing. (line 307) |
| 10984 | * with-editor-cancel <1>: Rebasing. (line 132) |
| 10985 | * with-editor-debug: Debugging Tools. (line 85) |
| 10986 | * with-editor-finish: Committing. (line 303) |
| 10987 | * with-editor-finish <1>: Rebasing. (line 128) |
| 10988 | * with-editor-usage-message: Committing. (line 484) |
| 10989 | |
| 10990 | |
| 10991 | File: magit.info, Node: Variable Index, Prev: Function and Command Index, Up: Top |
| 10992 | |
| 10993 | Appendix E Variable Index |
| 10994 | ************************* |
| 10995 | |
| 10996 | [index ] |
| 10997 | * Menu: |
| 10998 | |
| 10999 | * auto-revert-buffer-list-filter: Modes and Buffers. (line 396) |
| 11000 | * auto-revert-interval: Modes and Buffers. (line 392) |
| 11001 | * auto-revert-mode: Modes and Buffers. (line 380) |
| 11002 | * auto-revert-stop-on-user-input: Modes and Buffers. (line 388) |
| 11003 | * auto-revert-use-notify: Modes and Buffers. (line 369) |
| 11004 | * auto-revert-verbose: Modes and Buffers. (line 417) |
| 11005 | * branch.autoSetupMerge: Branching. (line 412) |
| 11006 | * branch.autoSetupRebase: Branching. (line 426) |
| 11007 | * branch.NAME.description: Branching. (line 383) |
| 11008 | * branch.NAME.merge: Branching. (line 351) |
| 11009 | * branch.NAME.pushRemote: Branching. (line 370) |
| 11010 | * branch.NAME.rebase: Branching. (line 361) |
| 11011 | * branch.NAME.remote: Branching. (line 356) |
| 11012 | * core.notesRef: Notes. (line 53) |
| 11013 | * git-commit-finish-query-functions: Committing. (line 518) |
| 11014 | * git-commit-known-pseudo-headers: Committing. (line 408) |
| 11015 | * git-commit-major-mode: Committing. (line 445) |
| 11016 | * git-commit-post-finish-hook: Committing. (line 487) |
| 11017 | * git-commit-setup-hook: Committing. (line 454) |
| 11018 | * git-commit-style-convention-checks: Committing. (line 538) |
| 11019 | * git-commit-summary-max-length: Committing. (line 513) |
| 11020 | * git-rebase-auto-advance: Rebasing. (line 226) |
| 11021 | * git-rebase-confirm-cancel: Rebasing. (line 232) |
| 11022 | * git-rebase-show-instructions: Rebasing. (line 229) |
| 11023 | * global-auto-revert-mode: Modes and Buffers. (line 343) |
| 11024 | * magit-auto-revert-immediately: Modes and Buffers. (line 352) |
| 11025 | * magit-auto-revert-mode: Modes and Buffers. (line 339) |
| 11026 | * magit-auto-revert-tracked-only: Modes and Buffers. (line 374) |
| 11027 | * magit-bisect-show-graph: Bisecting. (line 63) |
| 11028 | * magit-blame-disable-modes: Blaming. (line 165) |
| 11029 | * magit-blame-echo-style: Blaming. (line 151) |
| 11030 | * magit-blame-goto-chunk-hook: Blaming. (line 170) |
| 11031 | * magit-blame-read-only: Blaming. (line 161) |
| 11032 | * magit-blame-styles: Blaming. (line 147) |
| 11033 | * magit-blame-time-format: Blaming. (line 157) |
| 11034 | * magit-branch-adjust-remote-upstream-alist: Branching. (line 270) |
| 11035 | * magit-branch-direct-configure: Branching. (line 69) |
| 11036 | * magit-branch-name-suggestions: Branching. (line 223) |
| 11037 | * magit-branch-prefer-remote-upstream: Branching. (line 226) |
| 11038 | * magit-branch-read-upstream-first: Branching. (line 218) |
| 11039 | * magit-buffer-name-format: Modes and Buffers. (line 150) |
| 11040 | * magit-bury-buffer-function: Modes and Buffers. (line 215) |
| 11041 | * magit-cherry-margin: Logging. (line 385) |
| 11042 | * magit-clone-always-transient: Cloning Repository. (line 12) |
| 11043 | * magit-clone-default-directory: Cloning Repository. (line 84) |
| 11044 | * magit-clone-name-alist: Cloning Repository. (line 94) |
| 11045 | * magit-clone-set-remote-head: Cloning Repository. (line 66) |
| 11046 | * magit-clone-set-remote.pushDefault: Cloning Repository. (line 75) |
| 11047 | * magit-clone-url-format: Cloning Repository. (line 114) |
| 11048 | * magit-commit-ask-to-stage: Committing. (line 225) |
| 11049 | * magit-commit-diff-inhibit-same-window: Committing. (line 240) |
| 11050 | * magit-commit-extend-override-date: Committing. (line 280) |
| 11051 | * magit-commit-reword-override-date: Committing. (line 284) |
| 11052 | * magit-commit-show-diff: Committing. (line 221) |
| 11053 | * magit-commit-squash-confirm: Committing. (line 269) |
| 11054 | * magit-common-git-post-commit-functions: Running Git. (line 265) |
| 11055 | * magit-completing-read-function: Completion Confirmation and the Selection. |
| 11056 | (line 340) |
| 11057 | * magit-define-global-key-bindings: Essential Settings. (line 239) |
| 11058 | * magit-diff-adjust-tab-width: Diffing. (line 319) |
| 11059 | * magit-diff-buffer-file-locked: Commands for Buffers Visiting Files. |
| 11060 | (line 111) |
| 11061 | * magit-diff-extra-stat-arguments: Diffing. (line 414) |
| 11062 | * magit-diff-fontify-hunk: Diffing. (line 286) |
| 11063 | * magit-diff-hide-trailing-cr-characters: Diffing. (line 379) |
| 11064 | * magit-diff-highlight-hunk-region-functions: Diffing. (line 382) |
| 11065 | * magit-diff-highlight-indentation: Diffing. (line 365) |
| 11066 | * magit-diff-highlight-trailing: Diffing. (line 361) |
| 11067 | * magit-diff-paint-whitespace: Diffing. (line 340) |
| 11068 | * magit-diff-paint-whitespace-lines: Diffing. (line 354) |
| 11069 | * magit-diff-refine-hunk: Diffing. (line 272) |
| 11070 | * magit-diff-refine-ignore-whitespace: Diffing. (line 282) |
| 11071 | * magit-diff-specify-hunk-foreground: Diffing. (line 307) |
| 11072 | * magit-diff-unmarked-lines-keep-foreground: Diffing. (line 407) |
| 11073 | * magit-diff-use-indicator-faces: Diffing. (line 312) |
| 11074 | * magit-diff-visit-prefer-worktree: Visiting Files and Blobs. |
| 11075 | (line 92) |
| 11076 | * magit-diff-visit-previous-blob: Visiting Files and Blobs. |
| 11077 | (line 126) |
| 11078 | * magit-direct-use-buffer-arguments: Transient Arguments and Buffer Variables. |
| 11079 | (line 73) |
| 11080 | * magit-display-buffer-function: Modes and Buffers. (line 57) |
| 11081 | * magit-display-buffer-noselect: Modes and Buffers. (line 49) |
| 11082 | * magit-dwim-selection: Completion Confirmation and the Selection. |
| 11083 | (line 222) |
| 11084 | * magit-ediff-dwim-resolve-function: Ediffing. (line 105) |
| 11085 | * magit-ediff-dwim-show-on-hunks: Ediffing. (line 111) |
| 11086 | * magit-ediff-quit-hook: Ediffing. (line 124) |
| 11087 | * magit-ediff-show-stash-with-index: Ediffing. (line 118) |
| 11088 | * magit-format-file-function: Diffing. (line 424) |
| 11089 | * magit-generate-buffer-name-function: Modes and Buffers. (line 131) |
| 11090 | * magit-git-debug: Calling Git. (line 95) |
| 11091 | * magit-git-executable: Running Git. (line 164) |
| 11092 | * magit-git-global-arguments: Running Git. (line 204) |
| 11093 | * magit-githook-directory: Running Git. (line 241) |
| 11094 | * magit-keep-region-overlay: Completion Confirmation and the Selection. |
| 11095 | (line 294) |
| 11096 | * magit-list-refs-sortby: Completion Confirmation and the Selection. |
| 11097 | (line 404) |
| 11098 | * magit-log-auto-more: Logging. (line 165) |
| 11099 | * magit-log-buffer-file-locked: Commands for Buffers Visiting Files. |
| 11100 | (line 131) |
| 11101 | * magit-log-margin: Logging. (line 223) |
| 11102 | * magit-log-margin-show-committer-date: Logging. (line 255) |
| 11103 | * magit-log-section-commit-count: Status Buffer. (line 265) |
| 11104 | * magit-log-select-margin: Logging. (line 304) |
| 11105 | * magit-log-show-color-graph-limit: Logging. (line 174) |
| 11106 | * magit-log-show-refname-after-summary: Logging. (line 170) |
| 11107 | * magit-log-show-signatures-limit: Logging. (line 180) |
| 11108 | * magit-log-trace-definition-function: Diffing. (line 228) |
| 11109 | * magit-module-sections-hook: Status Buffer. (line 364) |
| 11110 | * magit-module-sections-nested: Status Buffer. (line 367) |
| 11111 | * magit-no-confirm: Completion Confirmation and the Selection. |
| 11112 | (line 21) |
| 11113 | * magit-pop-revision-stack-format: Committing. (line 374) |
| 11114 | * magit-post-clone-hook: Cloning Repository. (line 133) |
| 11115 | * magit-post-commit-hook: Committing. (line 229) |
| 11116 | * magit-post-display-buffer-hook: Modes and Buffers. (line 117) |
| 11117 | * magit-pre-display-buffer-hook: Modes and Buffers. (line 108) |
| 11118 | * magit-prefer-remote-upstream: Branching. (line 449) |
| 11119 | * magit-prefix-use-buffer-arguments: Transient Arguments and Buffer Variables. |
| 11120 | (line 65) |
| 11121 | * magit-process-raise-error: Calling Git. (line 239) |
| 11122 | * magit-pull-or-fetch: Fetching. (line 52) |
| 11123 | * magit-push-options: Pushing. (line 102) |
| 11124 | * magit-reflog-margin: Logging. (line 344) |
| 11125 | * magit-refresh-args: Refreshing Buffers. (line 52) |
| 11126 | * magit-refresh-buffer-hook: Modes and Buffers. (line 280) |
| 11127 | * magit-refresh-function: Refreshing Buffers. (line 47) |
| 11128 | * magit-refresh-status-buffer: Modes and Buffers. (line 285) |
| 11129 | * magit-refs-filter-alist: References Buffer. (line 137) |
| 11130 | * magit-refs-focus-column-width: References Buffer. (line 75) |
| 11131 | * magit-refs-margin: References Buffer. (line 89) |
| 11132 | * magit-refs-margin-for-tags: References Buffer. (line 112) |
| 11133 | * magit-refs-pad-commit-counts: References Buffer. (line 45) |
| 11134 | * magit-refs-primary-column-width: References Buffer. (line 63) |
| 11135 | * magit-refs-sections-hook: References Buffer. (line 241) |
| 11136 | * magit-refs-show-commit-count: References Buffer. (line 36) |
| 11137 | * magit-refs-show-remote-prefix: References Buffer. (line 57) |
| 11138 | * magit-remote-add-set-remote.pushDefault: Remotes. (line 86) |
| 11139 | * magit-remote-direct-configure: Remotes. (line 23) |
| 11140 | * magit-remote-git-executable: Running Git. (line 170) |
| 11141 | * magit-repolist-columns: Repository List. (line 15) |
| 11142 | * magit-repository-directories: Status Buffer. (line 57) |
| 11143 | * magit-revision-filter-files-on-follow: Diffing. (line 484) |
| 11144 | * magit-revision-insert-related-refs: Diffing. (line 435) |
| 11145 | * magit-revision-show-gravatars: Diffing. (line 444) |
| 11146 | * magit-revision-use-dedicated-buffers: Diffing. (line 502) |
| 11147 | * magit-revision-use-hash-sections: Diffing. (line 460) |
| 11148 | * magit-root-section: Section Plumbing. (line 199) |
| 11149 | * magit-save-repository-buffers: Modes and Buffers. (line 314) |
| 11150 | * magit-section-cache-visibility: Sections. (line 229) |
| 11151 | * magit-section-initial-visibility-alist: Sections. (line 213) |
| 11152 | * magit-section-movement-hook: Sections. (line 63) |
| 11153 | * magit-section-set-visibility-hook: Sections. (line 239) |
| 11154 | * magit-section-show-child-count: Sections. (line 389) |
| 11155 | * magit-section-visibility-indicators: Sections. (line 256) |
| 11156 | * magit-shell-command-verbose-prompt: Running Git. (line 117) |
| 11157 | * magit-stashes-margin: Stashing. (line 119) |
| 11158 | * magit-status-file-list-limit: Status Buffer. (line 236) |
| 11159 | * magit-status-headers-hook: Status Buffer. (line 297) |
| 11160 | * magit-status-margin: Status Buffer. (line 408) |
| 11161 | * magit-status-sections-hook: Status Buffer. (line 115) |
| 11162 | * magit-status-show-untracked-files: Status Buffer. (line 203) |
| 11163 | * magit-submodule-list-columns: Submodules. (line 25) |
| 11164 | * magit-this-process: Calling Git. (line 235) |
| 11165 | * magit-uniquify-buffer-names: Modes and Buffers. (line 190) |
| 11166 | * magit-unstage-committed: Staging and Unstaging. |
| 11167 | (line 52) |
| 11168 | * magit-update-other-window-delay: Sections. (line 121) |
| 11169 | * magit-visit-ref-behavior: References Buffer. (line 168) |
| 11170 | * magit-wip-merge-branch: Wip Modes. (line 99) |
| 11171 | * magit-wip-mode: Wip Modes. (line 30) |
| 11172 | * magit-wip-mode-lighter: Wip Modes. (line 93) |
| 11173 | * magit-wip-namespace: Wip Modes. (line 86) |
| 11174 | * notes.displayRef: Notes. (line 57) |
| 11175 | * pull.rebase: Branching. (line 391) |
| 11176 | * remote.NAME.fetch: Remotes. (line 108) |
| 11177 | * remote.NAME.followRemoteHEAD: Remotes. (line 128) |
| 11178 | * remote.NAME.push: Remotes. (line 117) |
| 11179 | * remote.NAME.pushurl: Remotes. (line 112) |
| 11180 | * remote.NAME.tagOpts: Remotes. (line 121) |
| 11181 | * remote.NAME.url: Remotes. (line 104) |
| 11182 | * remote.pushDefault: Branching. (line 403) |
| 11183 | |
| 11184 | |
| 11185 | |
| 11186 | Tag Table: |
| 11187 | Node: Top776 |
| 11188 | Node: Introduction3572 |
| 11189 | Node: Installation8272 |
| 11190 | Node: Installing from Melpa8600 |
| 11191 | Node: Installing from the Git Repository9671 |
| 11192 | Node: Post-Installation Tasks12866 |
| 11193 | Node: Getting Started14147 |
| 11194 | Node: Interface Concepts19954 |
| 11195 | Node: Modes and Buffers20333 |
| 11196 | Ref: Switching Buffers21831 |
| 11197 | Ref: Naming Buffers26483 |
| 11198 | Ref: Quitting Windows29456 |
| 11199 | Ref: Automatic Refreshing of Magit Buffers31259 |
| 11200 | Ref: Automatic Saving of File-Visiting Buffers33989 |
| 11201 | Ref: Automatic Reverting of File-Visiting Buffers34984 |
| 11202 | Ref: Risk of Reverting Automatically39801 |
| 11203 | Node: Sections42068 |
| 11204 | Ref: Section Movement42873 |
| 11205 | Ref: Section Visibility48239 |
| 11206 | Ref: Section Hooks55249 |
| 11207 | Ref: Section Types and Values57570 |
| 11208 | Ref: Section Options59535 |
| 11209 | Node: Transient Commands59914 |
| 11210 | Node: Transient Arguments and Buffer Variables61388 |
| 11211 | Node: Completion Confirmation and the Selection68397 |
| 11212 | Ref: Action Confirmation68658 |
| 11213 | Ref: Completion and Confirmation77015 |
| 11214 | Ref: The Selection80052 |
| 11215 | Ref: The hunk-internal region82789 |
| 11216 | Ref: Support for Completion Frameworks83713 |
| 11217 | Ref: Additional Completion Options87786 |
| 11218 | Node: Mouse Support88236 |
| 11219 | Node: Running Git88812 |
| 11220 | Ref: Viewing Git Output88932 |
| 11221 | Ref: Git Process Status90923 |
| 11222 | Ref: Running Git Manually92021 |
| 11223 | Ref: Git Executable94594 |
| 11224 | Ref: Global Git Arguments97481 |
| 11225 | Ref: Mapping Git Hooks to Lisp Hooks98196 |
| 11226 | Node: Inspecting102004 |
| 11227 | Node: Status Buffer103151 |
| 11228 | Ref: Status Sections107948 |
| 11229 | Ref: Status File List Sections111410 |
| 11230 | Ref: Status Log Sections113980 |
| 11231 | Ref: Status Header Sections115009 |
| 11232 | Ref: Status Module Sections117500 |
| 11233 | Ref: Status Options119874 |
| 11234 | Node: Repository List121149 |
| 11235 | Node: Logging126134 |
| 11236 | Ref: Refreshing Logs128865 |
| 11237 | Ref: Log Buffer130209 |
| 11238 | Ref: Log Margin134926 |
| 11239 | Ref: Select from Log137989 |
| 11240 | Ref: Reflog140111 |
| 11241 | Ref: Cherries141664 |
| 11242 | Node: Diffing143440 |
| 11243 | Ref: Refreshing Diffs147385 |
| 11244 | Ref: Commands Available in Diffs152663 |
| 11245 | Ref: Diff Options155058 |
| 11246 | Ref: Revision Buffer162559 |
| 11247 | Node: Ediffing166792 |
| 11248 | Node: References Buffer172836 |
| 11249 | Ref: References Sections183399 |
| 11250 | Node: Bisecting184184 |
| 11251 | Node: Visiting Files and Blobs186708 |
| 11252 | Ref: General-Purpose Visit Commands187150 |
| 11253 | Ref: Visiting Files and Blobs from a Diff187968 |
| 11254 | Node: Blaming193216 |
| 11255 | Node: Manipulating200194 |
| 11256 | Node: Creating Repository200536 |
| 11257 | Node: Cloning Repository201073 |
| 11258 | Node: Staging and Unstaging207512 |
| 11259 | Ref: Staging from File-Visiting Buffers211440 |
| 11260 | Node: Applying212455 |
| 11261 | Node: Committing215004 |
| 11262 | Ref: Initiating a Commit215629 |
| 11263 | Ref: Creating a new commit215941 |
| 11264 | Ref: Editing the last commit216051 |
| 11265 | Ref: Editing any reachable commit218030 |
| 11266 | Ref: Editing any reachable commit and rebasing immediately222443 |
| 11267 | Ref: Options used by commit commands224091 |
| 11268 | Ref: Used by all or most commit commands224163 |
| 11269 | Ref: Used by all squash and fixup commands226392 |
| 11270 | Ref: Used by specific commit commands226946 |
| 11271 | Ref: Editing Commit Messages227270 |
| 11272 | Ref: Using the Revision Stack229824 |
| 11273 | Ref: Commit Pseudo Headers232784 |
| 11274 | Ref: Commit Mode and Hooks233936 |
| 11275 | Ref: Commit Message Conventions236645 |
| 11276 | Node: Branching238533 |
| 11277 | Ref: The Two Remotes238654 |
| 11278 | Ref: Branch Commands241219 |
| 11279 | Ref: Branch Git Variables254793 |
| 11280 | Ref: Auxiliary Branch Commands260038 |
| 11281 | Node: Merging261055 |
| 11282 | Node: Resolving Conflicts265404 |
| 11283 | Node: Rebasing270774 |
| 11284 | Ref: Editing Rebase Sequences275971 |
| 11285 | Ref: Information About In-Progress Rebase281200 |
| 11286 | Ref: Rebasing-Footnote-1290192 |
| 11287 | Node: Cherry Picking290788 |
| 11288 | Ref: Reverting295096 |
| 11289 | Node: Resetting296456 |
| 11290 | Node: Stashing298280 |
| 11291 | Node: Transferring304519 |
| 11292 | Node: Remotes304741 |
| 11293 | Ref: Remote Commands304838 |
| 11294 | Ref: Remote Git Variables308782 |
| 11295 | Node: Fetching310715 |
| 11296 | Node: Pulling313198 |
| 11297 | Node: Pushing314736 |
| 11298 | Node: Plain Patches319656 |
| 11299 | Node: Maildir Patches321127 |
| 11300 | Node: Miscellaneous322606 |
| 11301 | Node: Tagging322952 |
| 11302 | Node: Notes324845 |
| 11303 | Node: Submodules327180 |
| 11304 | Ref: Listing Submodules327341 |
| 11305 | Ref: Submodule Transient329402 |
| 11306 | Node: Subtree331755 |
| 11307 | Node: Worktree333686 |
| 11308 | Node: Sparse checkouts335001 |
| 11309 | Node: Bundle337773 |
| 11310 | Node: Common Commands338148 |
| 11311 | Node: Wip Modes340774 |
| 11312 | Ref: Wip Graph345348 |
| 11313 | Node: Commands for Buffers Visiting Files347594 |
| 11314 | Node: Minor Mode for Buffers Visiting Blobs356266 |
| 11315 | Node: Customizing357429 |
| 11316 | Node: Per-Repository Configuration359021 |
| 11317 | Node: Essential Settings361275 |
| 11318 | Ref: Safety361564 |
| 11319 | Ref: Performance363239 |
| 11320 | Ref: Log Performance366030 |
| 11321 | Ref: Diff Performance367329 |
| 11322 | Ref: Refs Buffer Performance368670 |
| 11323 | Ref: Committing Performance369243 |
| 11324 | Ref: Microsoft Windows Performance370223 |
| 11325 | Ref: MacOS Performance371310 |
| 11326 | Ref: Global Bindings372193 |
| 11327 | Ref: Essential Settings-Footnote-1374366 |
| 11328 | Node: Plumbing374448 |
| 11329 | Node: Calling Git375273 |
| 11330 | Ref: Getting a Value from Git376732 |
| 11331 | Ref: Calling Git for Effect380350 |
| 11332 | Node: Section Plumbing386497 |
| 11333 | Ref: Creating Sections386649 |
| 11334 | Ref: Section Selection390459 |
| 11335 | Ref: Matching Sections392156 |
| 11336 | Node: Refreshing Buffers398058 |
| 11337 | Node: Conventions401198 |
| 11338 | Ref: Theming Faces401362 |
| 11339 | Node: FAQ409395 |
| 11340 | Node: FAQ - How to ...?409831 |
| 11341 | Ref: How to pronounce Magit?409964 |
| 11342 | Ref: How to show git's output?410656 |
| 11343 | Ref: How to install the gitman info manual?411273 |
| 11344 | Ref: How to show diffs for gpg-encrypted files?412078 |
| 11345 | Ref: How does branching and pushing work?412487 |
| 11346 | Ref: Should I disable VC?412651 |
| 11347 | Ref: The diff/log is filtered to one file; how do I show all changes413134 |
| 11348 | Node: FAQ - Issues and Errors413506 |
| 11349 | Ref: Magit is slow413651 |
| 11350 | Ref: I changed several thousand files at once and now Magit is unusable413797 |
| 11351 | Ref: I am having problems committing414336 |
| 11352 | Ref: I am using MS Windows and cannot push with Magit414601 |
| 11353 | Ref: I am using macOS and SOMETHING works in shell but not in Magit414999 |
| 11354 | Ref: Expanding a file to show the diff causes it to disappear415586 |
| 11355 | Ref: Point is wrong in the COMMIT_EDITMSG buffer415936 |
| 11356 | Ref: The mode-line information isn't always up-to-date416760 |
| 11357 | Ref: A branch and tag sharing the same name breaks SOMETHING417591 |
| 11358 | Ref: My Git hooks work on the command-line but not inside Magit418239 |
| 11359 | Ref: git-commit-mode isn't used when committing from the command-line418831 |
| 11360 | Ref: Point ends up inside invisible text when jumping to a file-visiting buffer420819 |
| 11361 | Ref: I am no longer able to save popup defaults421411 |
| 11362 | Node: Debugging Tools422204 |
| 11363 | Node: Keystroke Index426139 |
| 11364 | Node: Function and Command Index464600 |
| 11365 | Node: Variable Index516688 |
| 11366 | |
| 11367 | End Tag Table |
| 11368 | |
| 11369 | |
| 11370 | Local Variables: |
| 11371 | coding: utf-8 |
| 11372 | End: |