.emacs.d.git - Gitblit

Chizi123

2018-11-21 e75a20334813452c6912c090d70a0de2c805f94d

commit \| author \| age
5cb5f7	1	This is magit.info, produced by makeinfo version 6.5 from magit.texi.
C	2
	3	Copyright (C) 2015-2018 Jonas Bernoulli <jonas@bernoul.li>
	4
	5	You can redistribute this document and/or modify it under the terms
	6	of the GNU General Public License as published by the Free Software
	7	Foundation, either version 3 of the License, or (at your option)
	8	any later version.
	9
	10	This document is distributed in the hope that it will be useful,
	11	but WITHOUT ANY WARRANTY; without even the implied warranty of
	12	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
	13	General Public License for more details.
	14
	15	INFO-DIR-SECTION Emacs
	16	START-INFO-DIR-ENTRY
	17	* Magit: (magit). Using Git from Emacs with Magit.
	18	END-INFO-DIR-ENTRY
	19
	20
	21	File: magit.info, Node: Top, Next: Introduction, Up: (dir)
	22
	23	Magit User Manual
	24	*****************
	25
	26	Magit is an interface to the version control system Git, implemented as
	27	an Emacs package. Magit aspires to be a complete Git porcelain. While
	28	we cannot (yet) claim that Magit wraps and improves upon each and every
	29	Git command, it is complete enough to allow even experienced Git users
	30	to perform almost all of their daily version control tasks directly from
	31	within Emacs. While many fine Git clients exist, only Magit and Git
	32	itself deserve to be called porcelains.
	33
	34	This manual is for Magit version 2.90.1 (v2.90.1-9-gd2c84d9a5+1).
	35
	36	Copyright (C) 2015-2018 Jonas Bernoulli <jonas@bernoul.li>
	37
	38	You can redistribute this document and/or modify it under the terms
	39	of the GNU General Public License as published by the Free Software
	40	Foundation, either version 3 of the License, or (at your option)
	41	any later version.
	42
	43	This document is distributed in the hope that it will be useful,
	44	but WITHOUT ANY WARRANTY; without even the implied warranty of
	45	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
	46	General Public License for more details.
	47
	48	* Menu:
	49
	50	* Introduction::
	51	* Installation::
	52	* Getting Started::
	53	* Interface Concepts::
	54	* Inspecting::
	55	* Manipulating::
	56	* Transferring::
	57	* Miscellaneous::
	58	* Customizing::
	59	* Plumbing::
	60	* FAQ::
	61	* Debugging Tools::
	62	* Keystroke Index::
	63	* Command Index::
	64	* Function Index::
	65	* Variable Index::
	66
	67	— The Detailed Node Listing —
	68
	69	Installation
	70
	71	* Installing from Melpa::
	72	* Installing from the Git Repository::
	73	* Post-Installation Tasks::
	74
	75	Interface Concepts
	76
	77	* Modes and Buffers::
	78	* Sections::
	79	* Popup Buffers and Prefix Commands::
	80	* Completion, Confirmation and the Selection: Completion Confirmation and the Selection.
	81	* Running Git::
	82
	83	Modes and Buffers
	84
	85	* Switching Buffers::
	86	* Naming Buffers::
	87	* Quitting Windows::
	88	* Automatic Refreshing of Magit Buffers::
	89	* Automatic Saving of File-Visiting Buffers::
	90	* Automatic Reverting of File-Visiting Buffers::
	91
	92
	93	Sections
	94
	95	* Section Movement::
	96	* Section Visibility::
	97	* Section Hooks::
	98	* Section Types and Values::
	99	* Section Options::
	100
	101
	102	Completion, Confirmation and the Selection
	103
	104	* Action Confirmation::
	105	* Completion and Confirmation::
	106	* The Selection::
	107	* The hunk-internal region::
	108	* Support for Completion Frameworks::
	109	* Additional Completion Options::
	110
	111
	112	Running Git
	113
	114	* Viewing Git Output::
	115	* Git Process Status::
	116	* Running Git Manually::
	117	* Git Executable::
	118	* Global Git Arguments::
	119
	120
	121	Inspecting
	122
	123	* Status Buffer::
	124	* Repository List::
	125	* Logging::
	126	* Diffing::
	127	* Ediffing::
	128	* References Buffer::
	129	* Bisecting::
	130	* Visiting Blobs::
	131	* Blaming::
	132
	133	Status Buffer
	134
	135	* Status Sections::
	136	* Status Header Sections::
	137	* Status Module Sections::
	138	* Status Options::
	139
	140
	141	Logging
	142
	143	* Refreshing Logs::
	144	* Log Buffer::
	145	* Log Margin::
	146	* Select from Log::
	147	* Reflog::
	148	* Cherries::
	149
	150
	151	Diffing
	152
	153	* Refreshing Diffs::
	154	* Diff Buffer::
	155	* Diff Options::
	156	* Revision Buffer::
	157
	158
	159	References Buffer
	160
	161	* References Sections::
	162
	163
	164	Manipulating
	165
	166	* Repository Setup::
	167	* Staging and Unstaging::
	168	* Applying::
	169	* Committing::
	170	* Branching::
	171	* Merging::
	172	* Resolving Conflicts::
	173	* Rebasing::
	174	* Cherry Picking::
	175	* Resetting::
	176	* Stashing::
	177
	178	Staging and Unstaging
	179
	180	* Staging from File-Visiting Buffers::
	181
	182
	183	Committing
	184
	185	* Initiating a Commit::
	186	* Editing Commit Messages::
	187
	188
	189	Branching
	190
	191	* The Two Remotes::
	192	* The Branch Popup::
	193	* The Branch Config Popup::
	194	* Auxiliary Branch Commands::
	195
	196
	197	Rebasing
	198
	199	* Editing Rebase Sequences::
	200	* Information About In-Progress Rebase::
	201
	202
	203	Cherry Picking
	204
	205	* Reverting::
	206
	207
	208	Transferring
	209
	210	* Remotes::
	211	* Fetching::
	212	* Pulling::
	213	* Pushing::
	214	* Creating and Sending Patches::
	215	* Applying Patches::
	216
	217	Remotes
	218
	219	* The Remote Popup::
	220	* The Remote Config Popup::
	221
	222
	223	Miscellaneous
	224
	225	* Tagging::
	226	* Notes::
	227	* Submodules::
	228	* Subtree::
	229	* Worktree::
	230	* Common Commands::
	231	* Wip Modes::
	232	* Minor Mode for Buffers Visiting Files::
	233	* Minor Mode for Buffers Visiting Blobs::
	234
	235	Submodules
	236
	237	* Listing Submodules::
	238	* Submodule Popup::
	239
	240
	241	Wip Modes
	242
	243	* Wip Graph::
	244	* Legacy Wip Modes::
	245
	246
	247	Customizing
	248
	249	* Per-Repository Configuration::
	250	* Essential Settings::
	251
	252	Essential Settings
	253
	254	* Safety::
	255	* Performance::
	256
	257
	258	Plumbing
	259
	260	* Calling Git::
	261	* Section Plumbing::
	262	* Refreshing Buffers::
	263	* Conventions::
	264
	265	Calling Git
	266
	267	* Getting a Value from Git::
	268	* Calling Git for Effect::
	269
	270
	271	Section Plumbing
	272
	273	* Creating Sections::
	274	* Section Selection::
	275	* Matching Sections::
	276
	277
	278	Conventions
	279
	280	* Theming Faces::
	281
	282
	283	FAQ
	284
	285	* FAQ - How to ...?::
	286	* FAQ - Issues and Errors::
	287
	288	FAQ - How to ...?
	289
	290	* How to show git's output?::
	291	* How to install the gitman info manual?::
	292	* How to show diffs for gpg-encrypted files?::
	293	* How does branching and pushing work?::
	294	* Can Magit be used as ediff-version-control-package?::
	295
	296
	297	FAQ - Issues and Errors
	298
	299	* Magit is slow::
	300	* I changed several thousand files at once and now Magit is unusable::
	301	* I am having problems committing::
	302	* I am using MS Windows and cannot push with Magit::
	303	* I am using OS X and SOMETHING works in shell, but not in Magit: I am using OS X and SOMETHING works in shell but not in Magit.
	304	* Diffs contain control sequences::
	305	* Expanding a file to show the diff causes it to disappear::
	306	* Point is wrong in the COMMIT_EDITMSG buffer::
	307	* The mode-line information isn't always up-to-date::
	308	* A branch and tag sharing the same name breaks SOMETHING::
	309	* My Git hooks work on the command-line but not inside Magit::
	310	* git-commit-mode isn't used when committing from the command-line::
	311	* Point ends up inside invisible text when jumping to a file-visiting buffer::
	312
	313
	314
	315
	316	File: magit.info, Node: Introduction, Next: Installation, Prev: Top, Up: Top
	317
	318	1 Introduction
	319	**************
	320
	321	Magit is an interface to the version control system Git, implemented as
	322	an Emacs package. Magit aspires to be a complete Git porcelain. While
	323	we cannot (yet) claim that Magit wraps and improves upon each and every
	324	Git command, it is complete enough to allow even experienced Git users
	325	to perform almost all of their daily version control tasks directly from
	326	within Emacs. While many fine Git clients exist, only Magit and Git
	327	itself deserve to be called porcelains.
	328
	329	Staging and otherwise applying changes is one of the most important
	330	features in a Git porcelain and here Magit outshines anything else,
	331	including Git itself. Git’s own staging interface (‘git add --patch’)
	332	is so cumbersome that many users only use it in exceptional cases. In
	333	Magit staging a hunk or even just part of a hunk is as trivial as
	334	staging all changes made to a file.
	335
	336	The most visible part of Magit’s interface is the status buffer,
	337	which displays information about the current repository. Its content is
	338	created by running several Git commands and making their output
	339	actionable. Among other things, it displays information about the
	340	current branch, lists unpulled and unpushed changes and contains
	341	sections displaying the staged and unstaged changes. That might sound
	342	noisy, but, since sections are collapsible, it’s not.
	343
	344	To stage or unstage a change one places the cursor on the change and
	345	then types ‘s’ or ‘u’. The change can be a file or a hunk, or when the
	346	region is active (i.e. when there is a selection) several files or
	347	hunks, or even just part of a hunk. The change or changes that these
	348	commands - and many others - would act on are highlighted.
	349
	350	Magit also implements several other "apply variants" in addition to
	351	staging and unstaging. One can discard or reverse a change, or apply it
	352	to the working tree. Git’s own porcelain only supports this for staging
	353	and unstaging and you would have to do something like ‘git diff ... \|
	354	??? \| git apply ...’ to discard, revert, or apply a single hunk on the
	355	command line. In fact that’s exactly what Magit does internally (which
	356	is what lead to the term "apply variants").
	357
	358	Magit isn’t just for Git experts, but it does assume some prior
	359	experience with Git as well as Emacs. That being said, many users have
	360	reported that using Magit was what finally taught them what Git is
	361	capable of and how to use it to its fullest. Other users wished they
	362	had switched to Emacs sooner so that they would have gotten their hands
	363	on Magit earlier.
	364
	365	While one has to know the basic features of Emacs to be able to make
	366	full use of Magit, acquiring just enough Emacs skills doesn’t take long
	367	and is worth it, even for users who prefer other editors. Vim users are
	368	advised to give Evil (https://bitbucket.org/lyro/evil/wiki/Home), the
	369	"Extensible VI Layer for Emacs", and Spacemacs
	370	(https://github.com/syl20bnr/spacemacs), an "Emacs starter-kit focused
	371	on Evil" a try.
	372
	373	Magit provides a consistent and efficient Git porcelain. After a
	374	short learning period, you will be able to perform most of your daily
	375	version control tasks faster than you would on the command line. You
	376	will likely also start using features that seemed too daunting in the
	377	past.
	378
	379	Magit fully embraces Git. It exposes many advanced features using a
	380	simple but flexible interface instead of only wrapping the trivial ones
	381	like many GUI clients do. Of course Magit supports logging, cloning,
	382	pushing, and other commands that usually don’t fail in spectacular ways;
	383	but it also supports tasks that often cannot be completed in a single
	384	step. Magit fully supports tasks such as merging, rebasing,
	385	cherry-picking, reverting, and blaming by not only providing a command
	386	to initiate these tasks but also by displaying context sensitive
	387	information along the way and providing commands that are useful for
	388	resolving conflicts and resuming the sequence after doing so.
	389
	390	Magit wraps and in many cases improves upon at least the following
	391	Git porcelain commands: ‘add’, ‘am’, ‘bisect’, ‘blame’, ‘branch’,
	392	‘checkout’, ‘cherry’, ‘cherry-pick’, ‘clean’, ‘clone’, ‘commit’,
	393	‘config’, ‘describe’, ‘diff’, ‘fetch’, ‘format-patch’, ‘init’, ‘log’,
	394	‘merge’, ‘merge-tree’, ‘mv’, ‘notes’, ‘pull’, ‘rebase’, ‘reflog’,
	395	‘remote’, ‘request-pull’, ‘reset’, ‘revert’, ‘rm’, ‘show’, ‘stash’,
	396	‘submodule’, ‘subtree’, ‘tag’, and ‘worktree.’ Many more Magit porcelain
	397	commands are implemented on top of Git plumbing commands.
	398
	399
	400	File: magit.info, Node: Installation, Next: Getting Started, Prev: Introduction, Up: Top
	401
	402	2 Installation
	403	**************
	404
	405	Magit can be installed using Emacs’ package manager or manually from its
	406	development repository.
	407
	408	* Menu:
	409
	410	* Installing from Melpa::
	411	* Installing from the Git Repository::
	412	* Post-Installation Tasks::
	413
	414
	415	File: magit.info, Node: Installing from Melpa, Next: Installing from the Git Repository, Up: Installation
	416
	417	2.1 Installing from Melpa
	418	=========================
	419
	420	Magit is available from Melpa and Melpa-Stable. If you haven’t used
	421	Emacs’ package manager before, then it is high time you familiarize
	422	yourself with it by reading the documentation in the Emacs manual, see
	423	*note (emacs)Packages::. Then add one of the archives to
	424	‘package-archives’:
	425
	426	• To use Melpa:
	427
	428	(require 'package)
	429	(add-to-list 'package-archives
	430	'("melpa" . "http://melpa.org/packages/") t)
	431
	432	• To use Melpa-Stable:
	433
	434	(require 'package)
	435	(add-to-list 'package-archives
	436	'("melpa-stable" . "http://stable.melpa.org/packages/") t)
	437
	438	Once you have added your preferred archive, you need to update the
	439	local package list using:
	440
	441	M-x package-refresh-contents RET
	442
	443	Once you have done that, you can install Magit and its dependencies
	444	using:
	445
	446	M-x package-install RET magit RET
	447
	448	Now see *note Post-Installation Tasks::.
	449
	450
	451	File: magit.info, Node: Installing from the Git Repository, Next: Post-Installation Tasks, Prev: Installing from Melpa, Up: Installation
	452
	453	2.2 Installing from the Git Repository
	454	======================================
	455
	456	Magit depends on the ‘dash’, ‘ghub’, ‘graphql’, ‘magit-popup’, ‘treepy’
	457	and ‘with-editor’ libraries which are available from Melpa and
	458	Melpa-Stable. Install them using ‘M-x package-install RET <package>
	459	RET’. Of course you may also install them manually from their
	460	repository.
	461
	462	Then clone the Magit repository:
	463
	464	$ git clone https://github.com/magit/magit.git ~/.emacs.d/site-lisp/magit
	465	$ cd ~/.emacs.d/site-lisp/magit
	466
	467	Then compile the libraries and generate the info manuals:
	468
	469	$ make
	470
	471	If you haven’t installed ‘dash’, ‘ghub’, ‘graphql’, ‘magit-popup’,
	472	‘treepy’ and ‘with-editor’ from Melpa or at
	473	‘/path/to/magit/../<package>’, then you have to tell ‘make’ where to
	474	find them. To do so create the file ‘/path/to/magit/config.mk’ with the
	475	following content before running ‘make’:
	476
	477	LOAD_PATH = -L /path/to/magit/lisp
	478	LOAD_PATH += -L /path/to/dash
	479	LOAD_PATH += -L /path/to/ghub
	480	LOAD_PATH += -L /path/to/graphql
	481	LOAD_PATH += -L /path/to/magit-popup
	482	LOAD_PATH += -L /path/to/treepy
	483	LOAD_PATH += -L /path/to/with-editor
	484
	485	Finally add this to your init file:
	486
	487	(add-to-list 'load-path "~/.emacs.d/site-lisp/magit/lisp")
	488	(require 'magit)
	489
	490	(with-eval-after-load 'info
	491	(info-initialize)
	492	(add-to-list 'Info-directory-list
	493	"~/.emacs.d/site-lisp/magit/Documentation/"))
	494
	495	Note that you have to add the ‘lisp’ subdirectory to the ‘load-path’,
	496	not the top-level of the repository, and that elements of ‘load-path’
	497	should not end with a slash, while those of ‘Info-directory-list’
	498	should.
	499
	500	Instead of requiring the feature ‘magit’, you could load just the
	501	autoload definitions, by loading the file ‘magit-autoloads.el’.
	502
	503	(load "/path/to/magit/lisp/magit-autoloads")
	504
	505	Instead of running Magit directly from the repository by adding that
	506	to the ‘load-path’, you might want to instead install it in some other
	507	directory using ‘sudo make install’ and setting ‘load-path’ accordingly.
	508
	509	To update Magit use:
	510
	511	$ git pull
	512	$ make
	513
	514	At times it might be necessary to run ‘make clean all’ instead.
	515
	516	To view all available targets use ‘make help’.
	517
	518	Now see *note Post-Installation Tasks::.
	519
	520
	521	File: magit.info, Node: Post-Installation Tasks, Prev: Installing from the Git Repository, Up: Installation
	522
	523	2.3 Post-Installation Tasks
	524	===========================
	525
	526	After installing Magit you should verify that you are indeed using the
	527	Magit, Git, and Emacs releases you think you are using. It’s best to
	528	restart Emacs before doing so, to make sure you are not using an
	529	outdated value for ‘load-path’.
	530
	531	M-x magit-version RET
	532
	533	should display something like
	534
	535	Magit 2.8.0, Git 2.10.2, Emacs 25.1.1, gnu/linux
	536
	537	Then you might also want to read about options that many users likely
	538	want to customize. See *note Essential Settings::.
	539
	540	To be able to follow cross references to Git manpages found in this
	541	manual, you might also have to manually install the ‘gitman’ info
	542	manual, or advice ‘Info-follow-nearest-node’ to instead open the actual
	543	manpage. See *note How to install the gitman info manual?::.
	544
	545	If you are completely new to Magit then see *note Getting Started::.
	546
	547	If you run into problems, then please see the *note FAQ::. Also see
	548	the *note Debugging Tools::.
	549
	550	And last but not least please consider making a donation, to ensure
	551	that I can keep working on Magit. See <https://magit.vc/donations>.
	552	for various donation options.
	553
	554
	555	File: magit.info, Node: Getting Started, Next: Interface Concepts, Prev: Installation, Up: Top
	556
	557	3 Getting Started
	558	*****************
	559
	560	This short tutorial describes the most essential features that many
	561	Magitians use on a daily basis. It only scratches the surface but
	562	should be enough to get you started.
	563
	564	IMPORTANT: It is safest if you clone some repository just for this
	565	tutorial. Alternatively you can use an existing local repository, but
	566	if you do that, then you should commit all uncommitted changes before
	567	proceeding.
	568
	569	To display information about the current Git repository, type ‘M-x
	570	magit-status RET’. You will be using this command a lot, and should
	571	therefore give it a global key binding. This is what we recommend:
	572
	573	(global-set-key (kbd "C-x g") 'magit-status)
	574
	575	Most Magit commands are commonly invoked from the status buffer. It
	576	can be considered the primary interface for interacting with Git using
	577	Magit. Many other Magit buffers may exist at a given time, but they are
	578	often created from this buffer.
	579
	580	Depending on what state your repository is in, this buffer may
	581	contain sections titled "Staged changes", "Unstaged changes", "Unmerged
	582	into origin/master", "Unpushed to origin/master", and many others.
	583
	584	Since we are starting from a safe state, which you can easily return
	585	to (by doing a ‘git reset --hard PRE-MAGIT-STATE’), there currently are
	586	not staged or unstaged changes. Edit some files and save the changes.
	587	Then go back to the status buffer, while at the same time refreshing it,
	588	by typing ‘C-x g’. (When the status buffer, or any Magit buffer for
	589	that matter, is the current buffer, then you can also use just ‘g’ to
	590	refresh it).
	591
	592	Move between sections using ‘p’ and ‘n’. Note that the bodies of
	593	some sections are hidden. Type ‘TAB’ to expand or collapse the section
	594	at point. You can also use ‘C-tab’ to cycle the visibility of the
	595	current section and its children. Move to a file section inside the
	596	section named "Unstaged changes" and type ‘s’ to stage the changes you
	597	have made to that file. That file now appears under "Staged changes".
	598
	599	Magit can stage and unstage individual hunks, not just complete
	600	files. Move to the file you have just staged, expand it using ‘TAB’,
	601	move to one of the hunks using ‘n’, and unstage just that by typing ‘u’.
	602	Note how the staging (‘s’) and unstaging (‘u’) commands operate on the
	603	change at point. Many other commands behave the same way.
	604
	605	You can also un-/stage just part of a hunk. Inside the body of a
	606	hunk section (move there using ‘C-n’), set the mark using ‘C-SPC’ and
	607	move down until some added and/or removed lines fall inside the region
	608	but not all of them. Again type ‘s’ to stage.
	609
	610	It is also possible to un-/stage multiple files at once. Move to a
	611	file section, type ‘C-SPC’, move to the next file using ‘n’, and then
	612	‘s’ to stage both files. Note that both the mark and point have to be
	613	on the headings of sibling sections for this to work. If the region
	614	looks like it does in other buffers, then it doesn’t select Magit
	615	sections that can be acted on as a unit.
	616
	617	And then of course you want to commit your changes. Type ‘c’. This
	618	shows the committing popup buffer featuring various commit variants and
	619	arguments that can be passed to ‘git commit’. Do not worry about those
	620	for now. We want to create a "normal" commit, which is done by typing
	621	‘c’ again.
	622
	623	Now two new buffers appear. One is for writing the commit message,
	624	the other shows a diff with the changes that you are about to committed.
	625	Write a message and then type ‘C-c C-c’ to actually create the commit.
	626
	627	You probably don’t want to push the commit you just created because
	628	you just committed some random changes, but if that is not the case you
	629	could push it by typing ‘P’ to bring up the push popup and then ‘p’ to
	630	push to a branch with the same name as the local branch onto the remote
	631	configured as the push-remote. (If the push-remote is not configured
	632	yet, then you would first be prompted for the remote to push to.)
	633
	634	So far we have mentioned the commit, push, and log popups. These are
	635	probably among the popups you will be using the most, but many others
	636	exist. To show a popup that lists all other popups (as well as the
	637	various apply commands and some other fundamental commands), type ‘h’.
	638	Try a few.
	639
	640	The key bindings in that popup correspond to the bindings in Magit
	641	buffers, including but not limited to the status buffer. So you could
	642	type ‘h d’ to bring up the diff popup, but once you remember that "d"
	643	stands for "diff", you would usually do so by just typing ‘d’. But the
	644	"popup of popups" is useful even once you have memorized all the
	645	bindings, as it can provide easy access to Magit commands from non-Magit
	646	buffers. You should create a global key binding for this command too:
	647
	648	(global-set-key (kbd "C-x M-g") 'magit-dispatch-popup)
	649
	650	In the same vein, you might also want to enable
	651	‘global-magit-file-mode’ to get some more Magit key bindings in regular
	652	file-visiting buffers (see *note Minor Mode for Buffers Visiting
	653	Files::).
	654
	655	It is not necessary that you do so now, but if you stick with Magit,
	656	then it is highly recommended that you read the next section too.
	657
	658
	659	File: magit.info, Node: Interface Concepts, Next: Inspecting, Prev: Getting Started, Up: Top
	660
	661	4 Interface Concepts
	662	********************
	663
	664	* Menu:
	665
	666	* Modes and Buffers::
	667	* Sections::
	668	* Popup Buffers and Prefix Commands::
	669	* Completion, Confirmation and the Selection: Completion Confirmation and the Selection.
	670	* Running Git::
	671
	672
	673	File: magit.info, Node: Modes and Buffers, Next: Sections, Up: Interface Concepts
	674
	675	4.1 Modes and Buffers
	676	=====================
	677
	678	Magit provides several major-modes. For each of these modes there
	679	usually exists only one buffer per repository. Separate modes and thus
	680	buffers exist for commits, diffs, logs, and some other things.
	681
	682	Besides these special purpose buffers, there also exists an overview
	683	buffer, called the status buffer. It’s usually from this buffer that
	684	the user invokes Git commands, or creates or visits other buffers.
	685
	686	In this manual we often speak about "Magit buffers". By that we mean
	687	buffers whose major-modes derive from ‘magit-mode’.
	688
	689	‘M-x magit-toggle-buffer-lock’ (‘magit-toggle-buffer-lock’)
	690
	691	This command locks the current buffer to its value or if the buffer
	692	is already locked, then it unlocks it.
	693
	694	Locking a buffer to its value prevents it from being reused to
	695	display another value. The name of a locked buffer contains its
	696	value, which allows telling it apart from other locked buffers and
	697	the unlocked buffer.
	698
	699	Not all Magit buffers can be locked to their values; for example,
	700	it wouldn’t make sense to lock a status buffer.
	701
	702	There can only be a single unlocked buffer using a certain
	703	major-mode per repository. So when a buffer is being unlocked and
	704	another unlocked buffer already exists for that mode and
	705	repository, then the former buffer is instead deleted and the
	706	latter is displayed in its place.
	707
	708	* Menu:
	709
	710	* Switching Buffers::
	711	* Naming Buffers::
	712	* Quitting Windows::
	713	* Automatic Refreshing of Magit Buffers::
	714	* Automatic Saving of File-Visiting Buffers::
	715	* Automatic Reverting of File-Visiting Buffers::
	716
	717
	718	File: magit.info, Node: Switching Buffers, Next: Naming Buffers, Up: Modes and Buffers
	719
	720	4.1.1 Switching Buffers
	721	-----------------------
	722
	723	-- Function: magit-display-buffer buffer
	724
	725	This function is a wrapper around ‘display-buffer’ and is used to
	726	display any Magit buffer. It displays BUFFER in some window and,
	727	unlike ‘display-buffer’, also selects that window, provided
	728	‘magit-display-buffer-noselect’ is ‘nil’. It also runs the hooks
	729	mentioned below.
	730
	731	-- Variable: magit-display-buffer-noselect
	732
	733	When this is non-nil, then ‘magit-display-buffer’ only displays the
	734	buffer but forgoes also selecting the window. This variable should
	735	not be set globally, it is only intended to be let-bound, by code
	736	that automatically updates "the other window". This is used for
	737	example when the revision buffer is updated when you move inside
	738	the log buffer.
	739
	740	-- User Option: magit-display-buffer-function
	741
	742	The function specified here is called by ‘magit-display-buffer’
	743	with one argument, a buffer, to actually display that buffer. This
	744	function should call ‘display-buffer’ with that buffer as first and
	745	a list of display actions as second argument.
	746
	747	Magit provides several functions, listed below, that are suitable
	748	values for this option. If you want to use different rules, then a
	749	good way of doing that is to start with a copy of one of these
	750	functions and then adjust it to your needs.
	751
	752	Instead of using a wrapper around ‘display-buffer’, that function
	753	itself can be used here, in which case the display actions have to
	754	be specified by adding them to ‘display-buffer-alist’ instead.
	755
	756	To learn about display actions, see *note (elisp)Choosing a Window
	757	for Display::.
	758
	759	-- Function: magit-display-buffer-traditional buffer
	760
	761	This function is the current default value of the option
	762	‘magit-display-buffer-function’. Before that option and this
	763	function were added, the behavior was hard-coded in many places all
	764	over the code base but now all the rules are contained in this one
	765	function (except for the "noselect" special case mentioned above).
	766
	767	-- Function: magit-display-buffer-same-window-except-diff-v1
	768
	769	This function displays most buffers in the currently selected
	770	window. If a buffer’s mode derives from ‘magit-diff-mode’ or
	771	‘magit-process-mode’, it is displayed in another window.
	772
	773	-- Function: magit-display-buffer-fullframe-status-v1
	774
	775	This function fills the entire frame when displaying a status
	776	buffer. Otherwise, it behaves like
	777	‘magit-display-buffer-traditional’.
	778
	779	-- Function: magit-display-buffer-fullframe-status-topleft-v1
	780
	781	This function fills the entire frame when displaying a status
	782	buffer. It behaves like ‘magit-display-buffer-fullframe-status-v1’
	783	except that it displays buffers that derive from ‘magit-diff-mode’
	784	or ‘magit-process-mode’ to the top or left of the current buffer
	785	rather than to the bottom or right. As a result, Magit buffers
	786	tend to pop up on the same side as they would if
	787	‘magit-display-buffer-traditional’ were in use.
	788
	789	-- Function: magit-display-buffer-fullcolumn-most-v1
	790
	791	This function displays most buffers so that they fill the entire
	792	height of the frame. However, the buffer is displayed in another
	793	window if (1) the buffer’s mode derives from ‘magit-process-mode’,
	794	or (2) the buffer’s mode derives from ‘magit-diff-mode’, provided
	795	that the mode of the current buffer derives from ‘magit-log-mode’
	796	or ‘magit-cherry-mode’.
	797
	798	-- User Option: magit-pre-display-buffer-hook
	799
	800	This hook is run by ‘magit-display-buffer’ before displaying the
	801	buffer.
	802
	803	-- Function: magit-save-window-configuration
	804
	805	This function saves the current window configuration. Later when
	806	the buffer is buried, it may be restored by
	807	‘magit-restore-window-configuration’.
	808
	809	-- User Option: magit-post-display-buffer-hook
	810
	811	This hook is run by ‘magit-display-buffer’ after displaying the
	812	buffer.
	813
	814	-- Function: magit-maybe-set-dedicated
	815
	816	This function remembers if a new window had to be created to
	817	display the buffer, or whether an existing window was reused. This
	818	information is later used by ‘magit-mode-quit-window’, to determine
	819	whether the window should be deleted when its last Magit buffer is
	820	buried.
	821
	822
	823	File: magit.info, Node: Naming Buffers, Next: Quitting Windows, Prev: Switching Buffers, Up: Modes and Buffers
	824
	825	4.1.2 Naming Buffers
	826	--------------------
	827
	828	-- User Option: magit-generate-buffer-name-function
	829
	830	The function used to generate the names of Magit buffers.
	831
	832	Such a function should take the options
	833	‘magit-uniquify-buffer-names’ as well as ‘magit-buffer-name-format’
	834	into account. If it doesn’t, then should be clearly stated in the
	835	doc-string. And if it supports %-sequences beyond those mentioned
	836	in the doc-string of the option ‘magit-buffer-name-format’, then
	837	its own doc-string should describe the additions.
	838
	839	-- Function: magit-generate-buffer-name-default-function mode
	840
	841	This function returns a buffer name suitable for a buffer whose
	842	major-mode is MODE and which shows information about the repository
	843	in which ‘default-directory’ is located.
	844
	845	This function uses ‘magit-buffer-name-format’ and supporting all of
	846	the %-sequences mentioned the documentation of that option. It
	847	also respects the option ‘magit-uniquify-buffer-names’.
	848
	849	-- User Option: magit-buffer-name-format
	850
	851	The format string used to name Magit buffers.
	852
	853	At least the following %-sequences are supported:
	854
	855	• ‘%m’
	856
	857	The name of the major-mode, but with the ‘-mode’ suffix
	858	removed.
	859
	860	• ‘%M’
	861
	862	Like ‘%m’ but abbreviate ‘magit-status-mode’ as ‘magit’.
	863
	864	• ‘%v’
	865
	866	The value the buffer is locked to, in parentheses, or an empty
	867	string if the buffer is not locked to a value.
	868
	869	• ‘%V’
	870
	871	Like ‘%v’, but the string is prefixed with a space, unless it
	872	is an empty string.
	873
	874	• ‘%t’
	875
	876	The top-level directory of the working tree of the repository,
	877	or if ‘magit-uniquify-buffer-names’ is non-nil an abbreviation
	878	of that.
	879
	880	• ‘%x’
	881
	882	If ‘magit-uniquify-buffer-names’ is nil "*", otherwise the
	883	empty string. Due to limitations of the ‘uniquify’ package,
	884	buffer names must end with the path.
	885
	886	• ‘%T’
	887
	888	Obsolete, use "%t%x" instead. Like ‘%t’, but append an
	889	asterisk if and only if ‘magit-uniquify-buffer-names’ is nil.
	890
	891	The value should always contain ‘%m’ or ‘%M’, ‘%v’ or ‘%V’, and
	892	‘%t’ (or the obsolete ‘%T’). If ‘magit-uniquify-buffer-names’ is
	893	non-nil, then the value must end with ‘%t’ or ‘%t%x’ (or the
	894	obsolete ‘%T’). See issue #2841.
	895
	896	-- User Option: magit-uniquify-buffer-names
	897
	898	This option controls whether the names of Magit buffers are
	899	uniquified. If the names are not being uniquified, then they
	900	contain the full path of the top-level of the working tree of the
	901	corresponding repository. If they are being uniquified, then they
	902	end with the basename of the top-level, or if that would conflict
	903	with the name used for other buffers, then the names of all these
	904	buffers are adjusted until they no longer conflict.
	905
	906	This is done using the ‘uniquify’ package; customize its options to
	907	control how buffer names are uniquified.
	908
	909
	910	File: magit.info, Node: Quitting Windows, Next: Automatic Refreshing of Magit Buffers, Prev: Naming Buffers, Up: Modes and Buffers
	911
	912	4.1.3 Quitting Windows
	913	----------------------
	914
	915	‘q’ (‘magit-mode-bury-buffer’)
	916
	917	This command buries the current Magit buffer. With a prefix
	918	argument, it instead kills the buffer.
	919
	920	-- User Option: magit-bury-buffer-function
	921
	922	The function used to actually bury or kill the current buffer.
	923
	924	‘magit-mode-bury-buffer’ calls this function with one argument. If
	925	the argument is non-nil, then the function has to kill the current
	926	buffer. Otherwise it has to bury it alive. The default value
	927	currently is ‘magit-restore-window-configuration’.
	928
	929	-- Function: magit-restore-window-configuration kill-buffer
	930
	931	Bury or kill the current buffer using ‘quit-window’, which is
	932	called with KILL-BUFFER as first and the selected window as second
	933	argument.
	934
	935	Then restore the window configuration that existed right before the
	936	current buffer was displayed in the selected frame. Unfortunately
	937	that also means that point gets adjusted in all the buffers, which
	938	are being displayed in the selected frame.
	939
	940	-- Function: magit-mode-quit-window kill-buffer
	941
	942	Bury or kill the current buffer using ‘quit-window’, which is
	943	called with KILL-BUFFER as first and the selected window as second
	944	argument.
	945
	946	Then, if the window was originally created to display a Magit
	947	buffer and the buried buffer was the last remaining Magit buffer
	948	that was ever displayed in the window, then that is deleted.
	949
	950
	951	File: magit.info, Node: Automatic Refreshing of Magit Buffers, Next: Automatic Saving of File-Visiting Buffers, Prev: Quitting Windows, Up: Modes and Buffers
	952
	953	4.1.4 Automatic Refreshing of Magit Buffers
	954	-------------------------------------------
	955
	956	After running a command which may change the state of the current
	957	repository, the current Magit buffer and the corresponding status buffer
	958	are refreshed. The status buffer may optionally be automatically
	959	refreshed whenever a buffer is saved to a file inside the respective
	960	repository.
	961
	962	Automatically refreshing Magit buffers ensures that the displayed
	963	information is up-to-date most of the time but can lead to a noticeable
	964	delay in big repositories. Other Magit buffers are not refreshed to
	965	keep the delay to a minimum and also because doing so can sometimes be
	966	undesirable.
	967
	968	Buffers can also be refreshed explicitly, which is useful in buffers
	969	that weren’t current during the last refresh and after changes were made
	970	to the repository outside of Magit.
	971
	972	‘g’ (‘magit-refresh’)
	973
	974	This command refreshes the current buffer if its major mode derives
	975	from ‘magit-mode’ as well as the corresponding status buffer.
	976
	977	If the option ‘magit-revert-buffers’ calls for it, then it also
	978	reverts all unmodified buffers that visit files being tracked in
	979	the current repository.
	980
	981	‘G’ (‘magit-refresh-all’)
	982
	983	This command refreshes all Magit buffers belonging to the current
	984	repository and also reverts all unmodified buffers that visit files
	985	being tracked in the current repository.
	986
	987	The file-visiting buffers are always reverted, even if
	988	‘magit-revert-buffers’ is nil.
	989
	990	-- User Option: magit-refresh-buffer-hook
	991
	992	This hook is run in each Magit buffer that was refreshed during the
	993	current refresh - normally the current buffer and the status
	994	buffer.
	995
	996	-- User Option: magit-refresh-status-buffer
	997
	998	When this option is non-nil, then the status buffer is
	999	automatically refreshed after running git for side-effects, in
	1000	addition to the current Magit buffer, which is always refreshed
	1001	automatically.
	1002
	1003	Only set this to nil after exhausting all other options to improve
	1004	performance.
	1005
	1006	-- Function: magit-after-save-refresh-status
	1007
	1008	This function is intended to be added to ‘after-save-hook’. After
	1009	doing that the corresponding status buffer is refreshed whenever a
	1010	buffer is saved to a file inside a repository.
	1011
	1012	Note that refreshing a Magit buffer is done by re-creating its
	1013	contents from scratch, which can be slow in large repositories. If
	1014	you are not satisfied with Magit’s performance, then you should
	1015	obviously not add this function to that hook.
	1016
	1017
	1018	File: magit.info, Node: Automatic Saving of File-Visiting Buffers, Next: Automatic Reverting of File-Visiting Buffers, Prev: Automatic Refreshing of Magit Buffers, Up: Modes and Buffers
	1019
	1020	4.1.5 Automatic Saving of File-Visiting Buffers
	1021	-----------------------------------------------
	1022
	1023	File-visiting buffers are by default saved at certain points in time.
	1024	This doesn’t guarantee that Magit buffers are always up-to-date, but,
	1025	provided one only edits files by editing them in Emacs and uses only
	1026	Magit to interact with Git, one can be fairly confident. When in doubt
	1027	or after outside changes, type ‘g’ (‘magit-refresh’) to save and refresh
	1028	explicitly.
	1029
	1030	-- User Option: magit-save-repository-buffers
	1031
	1032	This option controls whether file-visiting buffers are saved before
	1033	certain events.
	1034
	1035	If this is non-nil then all modified file-visiting buffers
	1036	belonging to the current repository may be saved before running
	1037	commands, before creating new Magit buffers, and before explicitly
	1038	refreshing such buffers. If this is ‘dontask’ then this is done
	1039	without user intervention. If it is ‘t’ then the user has to
	1040	confirm each save.
	1041
	1042
	1043	File: magit.info, Node: Automatic Reverting of File-Visiting Buffers, Prev: Automatic Saving of File-Visiting Buffers, Up: Modes and Buffers
	1044
	1045	4.1.6 Automatic Reverting of File-Visiting Buffers
	1046	--------------------------------------------------
	1047
	1048	By default Magit automatically reverts buffers that are visiting files
	1049	that are being tracked in a Git repository, after they have changed on
	1050	disk. When using Magit one often changes files on disk by running git,
	1051	i.e. "outside Emacs", making this a rather important feature.
	1052
	1053	For example, if you discard a change in the status buffer, then that
	1054	is done by running ‘git apply --reverse ...’, and Emacs considers the
	1055	file to have "changed on disk". If Magit did not automatically revert
	1056	the buffer, then you would have to type ‘M-x revert-buffer RET RET’ in
	1057	the visiting buffer before you could continue making changes.
	1058
	1059	-- User Option: magit-auto-revert-mode
	1060
	1061	When this mode is enabled, then buffers that visit tracked files,
	1062	are automatically reverted after the visited files changed on disk.
	1063
	1064	-- User Option: global-auto-revert-mode
	1065
	1066	When this mode is enabled, then any file-visiting buffer is
	1067	automatically reverted after the visited file changed on disk.
	1068
	1069	If you like buffers that visit tracked files to be automatically
	1070	reverted, then you might also like any buffer to be reverted, not
	1071	just those visiting tracked files. If that is the case, then
	1072	enable this mode _instead of_ ‘magit-auto-revert-mode’.
	1073
	1074	-- User Option: magit-auto-revert-immediately
	1075
	1076	This option controls whether Magit reverts buffers immediately.
	1077
	1078	If this is non-nil and either ‘global-auto-revert-mode’ or
	1079	‘magit-auto-revert-mode’ is enabled, then Magit immediately reverts
	1080	buffers by explicitly calling ‘auto-revert-buffers’ after running
	1081	git for side-effects.
	1082
	1083	If ‘auto-revert-use-notify’ is non-nil (and file notifications are
	1084	actually supported), then ‘magit-auto-revert-immediately’ does not
	1085	have to be non-nil, because the reverts happen immediately anyway.
	1086
	1087	If ‘magit-auto-revert-immediately’ and ‘auto-revert-use-notify’ are
	1088	both ‘nil’, then reverts happen after ‘auto-revert-interval’
	1089	seconds of user inactivity. That is not desirable.
	1090
	1091	-- User Option: auto-revert-use-notify
	1092
	1093	This option controls whether file notification functions should be
	1094	used. Note that this variable unfortunately defaults to ‘t’ even
	1095	on systems on which file notifications cannot be used.
	1096
	1097	-- User Option: magit-auto-revert-tracked-only
	1098
	1099	This option controls whether ‘magit-auto-revert-mode’ only reverts
	1100	tracked files or all files that are located inside Git
	1101	repositories, including untracked files and files located inside
	1102	Git’s control directory.
	1103
	1104	-- Command: auto-revert-mode
	1105
	1106	The global mode ‘magit-auto-revert-mode’ works by turning on this
	1107	local mode in the appropriate buffers (but
	1108	‘global-auto-revert-mode’ is implemented differently). You can
	1109	also turn it on or off manually, which might be necessary if Magit
	1110	does not notice that a previously untracked file now is being
	1111	tracked or vice-versa.
	1112
	1113	-- User Option: auto-revert-stop-on-user-input
	1114
	1115	This option controls whether the arrival of user input suspends the
	1116	automatic reverts for ‘auto-revert-interval’ seconds.
	1117
	1118	-- User Option: auto-revert-interval
	1119
	1120	This option controls for how many seconds Emacs waits before
	1121	resuming suspended reverts.
	1122
	1123	-- User Option: auto-revert-buffer-list-filter
	1124
	1125	This option specifies an additional filter used by
	1126	‘auto-revert-buffers’ to determine whether a buffer should be
	1127	reverted or not.
	1128
	1129	This option is provided by ‘magit’, which also redefines
	1130	‘auto-revert-buffers’ to respect it. Magit users who do not turn
	1131	on the local mode ‘auto-revert-mode’ themselves, are best served by
	1132	setting the value to ‘magit-auto-revert-repository-buffers-p’.
	1133
	1134	However the default is nil, to not disturb users who do use the
	1135	local mode directly. If you experience delays when running Magit
	1136	commands, then you should consider using one of the predicates
	1137	provided by Magit - especially if you also use Tramp.
	1138
	1139	Users who do turn on ‘auto-revert-mode’ in buffers in which Magit
	1140	doesn’t do that for them, should likely not use any filter. Users
	1141	who turn on ‘global-auto-revert-mode’, do not have to worry about
	1142	this option, because it is disregarded if the global mode is
	1143	enabled.
	1144
	1145	-- User Option: auto-revert-verbose
	1146
	1147	This option controls whether Emacs reports when a buffer has been
	1148	reverted.
	1149
	1150	The options with the ‘auto-revert-’ prefix are located in the Custom
	1151	group named ‘auto-revert’. The other, magit-specific, options are
	1152	located in the ‘magit’ group.
	1153
	1154	* Menu:
	1155
	1156	* Risk of Reverting Automatically::
	1157
	1158
	1159	File: magit.info, Node: Risk of Reverting Automatically, Up: Automatic Reverting of File-Visiting Buffers
	1160
	1161	Risk of Reverting Automatically
	1162	...............................
	1163
	1164	For the vast majority users automatically reverting file-visiting
	1165	buffers after they have changed on disk is harmless.
	1166
	1167	If a buffer is modified (i.e. it contains changes that haven’t been
	1168	saved yet), then Emacs would refuse to automatically revert it. If you
	1169	save a previously modified buffer, then that results in what is seen by
	1170	Git as an uncommitted change. Git would then refuse to carry out any
	1171	commands that would cause these changes to be lost. In other words, if
	1172	there is anything that could be lost, then either Git or Emacs would
	1173	refuse to discard the changes.
	1174
	1175	However if you do use file-visiting buffers as a sort of ad hoc
	1176	"staging area", then the automatic reverts could potentially cause data
	1177	loss. So far I have only heard from one user who uses such a workflow.
	1178
	1179	An example: You visit some file in a buffer, edit it, and save the
	1180	changes. Then, outside of Emacs (or at least not using Magit or by
	1181	saving the buffer) you change the file on disk again. At this point the
	1182	buffer is the only place where the intermediate version still exists.
	1183	You have saved the changes to disk, but that has since been overwritten.
	1184	Meanwhile Emacs considers the buffer to be unmodified (because you have
	1185	not made any changes to it since you last saved it to the visited file)
	1186	and therefore would not object to it being automatically reverted. At
	1187	this point an Auto-Revert mode would kick in. It would check whether
	1188	the buffer is modified and since that is not the case it would revert
	1189	it. The intermediate version would be lost. (Actually you could still
	1190	get it back using the ‘undo’ command.)
	1191
	1192	If your workflow depends on Emacs preserving the intermediate version
	1193	in the buffer, then you have to disable all Auto-Revert modes. But
	1194	please consider that such a workflow would be dangerous even without
	1195	using an Auto-Revert mode, and should therefore be avoided. If Emacs
	1196	crashed or if you quit Emacs by mistake, then you would also lose the
	1197	buffer content. There would be no autosave file still containing the
	1198	intermediate version (because that was deleted when you saved the
	1199	buffer) and you would not be asked whether you want to save the buffer
	1200	(because it isn’t modified).
	1201
	1202
	1203	File: magit.info, Node: Sections, Next: Popup Buffers and Prefix Commands, Prev: Modes and Buffers, Up: Interface Concepts
	1204
	1205	4.2 Sections
	1206	============
	1207
	1208	Magit buffers are organized into nested sections, which can be collapsed
	1209	and expanded, similar to how sections are handled in Org mode. Each
	1210	section also has a type, and some sections also have a value. For each
	1211	section type there can also be a local keymap, shared by all sections of
	1212	that type.
	1213
	1214	Taking advantage of the section value and type, many commands operate
	1215	on the current section, or when the region is active and selects
	1216	sections of the same type, all of the selected sections. Commands that
	1217	only make sense for a particular section type (as opposed to just
	1218	behaving differently depending on the type) are usually bound in section
	1219	type keymaps.
	1220
	1221	* Menu:
	1222
	1223	* Section Movement::
	1224	* Section Visibility::
	1225	* Section Hooks::
	1226	* Section Types and Values::
	1227	* Section Options::
	1228
	1229
	1230	File: magit.info, Node: Section Movement, Next: Section Visibility, Up: Sections
	1231
	1232	4.2.1 Section Movement
	1233	----------------------
	1234
	1235	To move within a section use the usual keys (‘C-p’, ‘C-n’, ‘C-b’, ‘C-f’
	1236	etc), whose global bindings are not shadowed. To move to another
	1237	section use the following commands.
	1238
	1239	‘p’ (‘magit-section-backward’)
	1240
	1241	When not at the beginning of a section, then move to the beginning
	1242	of the current section. At the beginning of a section, instead
	1243	move to the beginning of the previous visible section.
	1244
	1245	‘n’ (‘magit-section-forward’)
	1246
	1247	Move to the beginning of the next visible section.
	1248
	1249	‘M-p’ (‘magit-section-backward-siblings’)
	1250
	1251	Move to the beginning of the previous sibling section. If there is
	1252	no previous sibling section, then move to the parent section
	1253	instead.
	1254
	1255	‘M-n’ (‘magit-section-forward-siblings’)
	1256
	1257	Move to the beginning of the next sibling section. If there is no
	1258	next sibling section, then move to the parent section instead.
	1259
	1260	‘^’ (‘magit-section-up’)
	1261
	1262	Move to the beginning of the parent of the current section.
	1263
	1264	The above commands all call the hook ‘magit-section-movement-hook’.
	1265	Any of the functions listed below can be used as members of this hook.
	1266
	1267	-- Variable: magit-section-movement-hook
	1268
	1269	This hook is run by all of the above movement commands, after
	1270	arriving at the destination.
	1271
	1272	-- Function: magit-hunk-set-window-start
	1273
	1274	This hook function ensures that the beginning of the current
	1275	section is visible, provided it is a ‘hunk’ section. Otherwise, it
	1276	does nothing. This function is a member of the hook’s default
	1277	value.
	1278
	1279	-- Function: magit-section-set-window-start
	1280
	1281	This hook function ensures that the beginning of the current
	1282	section is visible, regardless of the section’s type. If you add
	1283	this to ‘magit-section-movement-hook’, then you must remove the
	1284	hunk-only variant in turn.
	1285
	1286	-- Function: magit-log-maybe-show-more-commits
	1287
	1288	This hook function only has an effect in log buffers, and ‘point’
	1289	is on the "show more" section. If that is the case, then it
	1290	doubles the number of commits that are being shown. This function
	1291	is a member of the hook’s default value.
	1292
	1293	-- Function: magit-log-maybe-update-revision-buffer
	1294
	1295	When moving inside a log buffer, then this function updates the
	1296	revision buffer, provided it is already being displayed in another
	1297	window of the same frame. This function is a member of the hook’s
	1298	default value.
	1299
	1300	-- Function: magit-log-maybe-update-blob-buffer
	1301
	1302	When moving inside a log buffer and another window of the same
	1303	frame displays a blob buffer, then this function instead displays
	1304	the blob buffer for the commit at point in that window.
	1305
	1306	-- Function: magit-status-maybe-update-revision-buffer
	1307
	1308	When moving inside a status buffer, then this function updates the
	1309	revision buffer, provided it is already being displayed in another
	1310	window of the same frame.
	1311
	1312	-- Function: magit-status-maybe-update-blob-buffer
	1313
	1314	When moving inside a status buffer and another window of the same
	1315	frame displays a blob buffer, then this function instead displays
	1316	the blob buffer for the commit at point in that window.
	1317
	1318	-- User Option: magit-update-other-window-delay
	1319
	1320	Delay before automatically updating the other window.
	1321
	1322	When moving around in certain buffers, then certain other buffers,
	1323	which are being displayed in another window, may optionally be
	1324	updated to display information about the section at point.
	1325
	1326	When holding down a key to move by more than just one section, then
	1327	that would update that buffer for each section on the way. To
	1328	prevent that, updating the revision buffer is delayed, and this
	1329	option controls for how long. For optimal experience you might
	1330	have to adjust this delay and/or the keyboard repeat rate and delay
	1331	of your graphical environment or operating system.
	1332
	1333
	1334	File: magit.info, Node: Section Visibility, Next: Section Hooks, Prev: Section Movement, Up: Sections
	1335
	1336	4.2.2 Section Visibility
	1337	------------------------
	1338
	1339	Magit provides many commands for changing the visibility of sections,
	1340	but all you need to get started are the next two.
	1341
	1342	‘TAB’ (‘magit-section-toggle’)
	1343
	1344	Toggle the visibility of the body of the current section.
	1345
	1346	‘C-<tab>’ (‘magit-section-cycle’)
	1347
	1348	Cycle the visibility of current section and its children.
	1349
	1350	‘M-<tab>’ (‘magit-section-cycle-diffs’)
	1351
	1352	Cycle the visibility of diff-related sections in the current
	1353	buffer.
	1354
	1355	‘S-<tab>’ (‘magit-section-cycle-global’)
	1356
	1357	Cycle the visibility of all sections in the current buffer.
	1358
	1359	‘1’ (‘magit-section-show-level-1’)
	1360	‘2’ (‘magit-section-show-level-2’)
	1361	‘3’ (‘magit-section-show-level-3’)
	1362	‘4’ (‘magit-section-show-level-4’)
	1363
	1364	Show sections surrounding the current section up to level N.
	1365
	1366	‘M-1’ (‘magit-section-show-level-1-all’)
	1367	‘M-2’ (‘magit-section-show-level-2-all’)
	1368	‘M-3’ (‘magit-section-show-level-3-all’)
	1369	‘M-4’ (‘magit-section-show-level-4-all’)
	1370
	1371	Show all sections up to level N.
	1372
	1373	Some functions, which are used to implement the above commands, are
	1374	also exposed as commands themselves. By default no keys are bound to
	1375	these commands, as they are generally perceived to be much less useful.
	1376	But your mileage may vary.
	1377
	1378	-- Command: magit-section-show
	1379
	1380	Show the body of the current section.
	1381
	1382	-- Command: magit-section-hide
	1383
	1384	Hide the body of the current section.
	1385
	1386	-- Command: magit-section-show-headings
	1387
	1388	Recursively show headings of children of the current section. Only
	1389	show the headings. Previously shown text-only bodies are hidden.
	1390
	1391	-- Command: magit-section-show-children
	1392
	1393	Recursively show the bodies of children of the current section.
	1394	With a prefix argument show children down to the level of the
	1395	current section, and hide deeper children.
	1396
	1397	-- Command: magit-section-hide-children
	1398
	1399	Recursively hide the bodies of children of the current section.
	1400
	1401	-- Command: magit-section-toggle-children
	1402
	1403	Toggle visibility of bodies of children of the current section.
	1404
	1405	When a buffer is first created then some sections are shown expanded
	1406	while others are not. This is hard coded. When a buffer is refreshed
	1407	then the previous visibility is preserved. The initial visibility of
	1408	certain sections can also be overwritten using the hook
	1409	‘magit-section-set-visibility-hook’.
	1410
	1411	-- User Option: magit-section-initial-visibility-alist
	1412
	1413	This options can be used to override the initial visibility of
	1414	sections. In the future it will also be used to define the
	1415	defaults, but currently a section’s default is still hardcoded.
	1416
	1417	The value is an alist. Each element maps a section type or lineage
	1418	to the initial visibility state for such sections. The state has
	1419	to be one of ‘show’ or ‘hide’, or a function that returns one of
	1420	these symbols. A function is called with the section as the only
	1421	argument.
	1422
	1423	Use the command ‘magit-describe-section-briefly’ to determine a
	1424	section’s lineage or type. The vector in the output is the section
	1425	lineage and the type is the first element of that vector.
	1426	Wildcards can be used, see ‘magit-section-match’.
	1427
	1428	-- User Option: magit-section-cache-visibility
	1429
	1430	This option controls for which sections the previous visibility
	1431	state should be restored if a section disappears and later appears
	1432	again. The value is a boolean or a list of section types. If t,
	1433	then the visibility of all sections is cached. Otherwise this is
	1434	only done for sections whose type matches one of the listed types.
	1435
	1436	This requires that the function ‘magit-section-cached-visibility’
	1437	is a member of ‘magit-section-set-visibility-hook’.
	1438
	1439	-- Variable: magit-section-set-visibility-hook
	1440
	1441	This hook is run when first creating a buffer and also when
	1442	refreshing an existing buffer, and is used to determine the
	1443	visibility of the section currently being inserted.
	1444
	1445	Each function is called with one argument, the section being
	1446	inserted. It should return ‘hide’ or ‘show’, or to leave the
	1447	visibility undefined ‘nil’. If no function decides on the
	1448	visibility and the buffer is being refreshed, then the visibility
	1449	is preserved; or if the buffer is being created, then the hard
	1450	coded default is used.
	1451
	1452	Usually this should only be used to set the initial visibility but
	1453	not during refreshes. If ‘magit-insert-section--oldroot’ is
	1454	non-nil, then the buffer is being refreshed and these functions
	1455	should immediately return ‘nil’.
	1456
	1457
	1458	File: magit.info, Node: Section Hooks, Next: Section Types and Values, Prev: Section Visibility, Up: Sections
	1459
	1460	4.2.3 Section Hooks
	1461	-------------------
	1462
	1463	Which sections are inserted into certain buffers is controlled with
	1464	hooks. This includes the status and the refs buffers. For other
	1465	buffers, e.g. log and diff buffers, this is not possible. The command
	1466	‘magit-describe-section’ can be used to see which hook (if any) was
	1467	responsible for inserting the section at point.
	1468
	1469	For buffers whose sections can be customized by the user, a hook
	1470	variable called ‘magit-TYPE-sections-hook’ exists. This hook should be
	1471	changed using ‘magit-add-section-hook’. Avoid using ‘add-hooks’ or the
	1472	Custom interface.
	1473
	1474	The various available section hook variables are described later in
	1475	this manual along with the appropriate "section inserter functions".
	1476
	1477	-- Function: magit-add-section-hook hook function &optional at append
	1478	local
	1479
	1480	Add the function FUNCTION to the value of section hook HOOK.
	1481
	1482	Add FUNCTION at the beginning of the hook list unless optional
	1483	APPEND is non-nil, in which case FUNCTION is added at the end. If
	1484	FUNCTION already is a member then move it to the new location.
	1485
	1486	If optional AT is non-nil and a member of the hook list, then add
	1487	FUNCTION next to that instead. Add before or after AT, or replace
	1488	AT with FUNCTION depending on APPEND. If APPEND is the symbol
	1489	‘replace’, then replace AT with FUNCTION. For any other non-nil
	1490	value place FUNCTION right after AT. If nil, then place FUNCTION
	1491	right before AT. If FUNCTION already is a member of the list but
	1492	AT is not, then leave FUNCTION where ever it already is.
	1493
	1494	If optional LOCAL is non-nil, then modify the hook’s buffer-local
	1495	value rather than its global value. This makes the hook local by
	1496	copying the default value. That copy is then modified.
	1497
	1498	HOOK should be a symbol. If HOOK is void, it is first set to nil.
	1499	HOOK’s value must not be a single hook function. FUNCTION should
	1500	be a function that takes no arguments and inserts one or multiple
	1501	sections at point, moving point forward. FUNCTION may choose not
	1502	to insert its section(s), when doing so would not make sense. It
	1503	should not be abused for other side-effects.
	1504
	1505	To remove a function from a section hook, use ‘remove-hook’.
	1506
	1507
	1508	File: magit.info, Node: Section Types and Values, Next: Section Options, Prev: Section Hooks, Up: Sections
	1509
	1510	4.2.4 Section Types and Values
	1511	------------------------------
	1512
	1513	Each section has a type, for example ‘hunk’, ‘file’, and ‘commit’.
	1514	Instances of certain section types also have a value. The value of a
	1515	section of type ‘file’, for example, is a file name.
	1516
	1517	Users usually do not have to worry about a section’s type and value,
	1518	but knowing them can be handy at times.
	1519
	1520	‘M-x magit-describe-section-briefly’ (‘magit-describe-section-briefly’)
	1521
	1522	Show information about the section at point in the echo area, as
	1523	"#<magit-section VALUE [TYPE PARENT-TYPE...] BEGINNING-END>".
	1524
	1525	Many commands behave differently depending on the type of the section
	1526	at point and/or somehow consume the value of that section. But that is
	1527	only one of the reasons why the same key may do something different,
	1528	depending on what section is current.
	1529
	1530	Additionally for each section type a keymap might be defined, named
	1531	‘magit-TYPE-section-map’. That keymap is used as text property keymap
	1532	of all text belonging to any section of the respective type. If such a
	1533	map does not exist for a certain type, then you can define it yourself,
	1534	and it will automatically be used.
	1535
	1536
	1537	File: magit.info, Node: Section Options, Prev: Section Types and Values, Up: Sections
	1538
	1539	4.2.5 Section Options
	1540	---------------------
	1541
	1542	This section describes options that have an effect on more than just a
	1543	certain type of sections. As you can see there are not many of those.
	1544
	1545	-- User Option: magit-section-show-child-count
	1546
	1547	Whether to append the number of children to section headings. This
	1548	only affects sections that could benefit from this information.
	1549
	1550
	1551	File: magit.info, Node: Popup Buffers and Prefix Commands, Next: Completion Confirmation and the Selection, Prev: Sections, Up: Interface Concepts
	1552
	1553	4.3 Popup Buffers and Prefix Commands
	1554	=====================================
	1555
	1556	Many Magit commands are implemented using popup buffers. First the
	1557	user invokes a popup or prefix command, which causes a popup buffer
	1558	with the available infix arguments and suffix commands to be
	1559	displayed. The user then optionally toggles/sets some arguments and
	1560	finally invokes one of the suffix commands.
	1561
	1562	This is implemented in the library ‘magit-popup’. Earlier releases
	1563	used the library ‘magit-key-mode’. A future release will switch to a
	1564	yet-to-be-written successor, which will likely be named ‘transient’.
	1565
	1566	Because ‘magit-popup’ can also be used by other packages without
	1567	having to depend on all of Magit, it is documented in its own manual.
	1568	See *note (magit-popup)Top::.
	1569
	1570	‘C-c C-c’ (‘magit-dispatch-popup’)
	1571
	1572	This popup command shows a buffer featuring all other Magit popup
	1573	commands as well as some other commands that are not popup commands
	1574	themselves.
	1575
	1576	This command is also, or especially, useful outside Magit buffers, so
	1577	you should setup a global binding:
	1578
	1579	(global-set-key (kbd "C-x M-g") 'magit-dispatch-popup)
	1580
	1581	Most popups set their initial arguments according to the
	1582	corresponding ‘magit-*-arguments’ variable. Two popups, the log and
	1583	diff popups (see note Logging:: and note Diffing::), may behave a bit
	1584	differently, depending on the value of ‘magit-use-sticky-arguments’.
	1585
	1586	-- User Option: magit-use-sticky-arguments
	1587
	1588	This option controls how diff and log commands reuse arguments from
	1589	existing buffers.
	1590
	1591	When ‘t’ (the default value), the log or diff popup reuses the
	1592	arguments from the current repository’s log or diff buffer,
	1593	respectively. When no log or diff buffer exists for the current
	1594	repository, these popups use the default value of
	1595	‘magit-log-arguments’ or ‘magit-diff-arguments’.
	1596
	1597	When ‘current’, log and diff popups will only reuse the arguments
	1598	if the current buffer is derived from ‘magit-log-mode’ or
	1599	‘magit-diff-mode’, respectively.
	1600
	1601	When ‘nil’, the default value of ‘magit-log-arguments’ or
	1602	‘magit-diff-arguments’ is always used.
	1603
	1604
	1605	File: magit.info, Node: Completion Confirmation and the Selection, Next: Running Git, Prev: Popup Buffers and Prefix Commands, Up: Interface Concepts
	1606
	1607	4.4 Completion, Confirmation and the Selection
	1608	==============================================
	1609
	1610	* Menu:
	1611
	1612	* Action Confirmation::
	1613	* Completion and Confirmation::
	1614	* The Selection::
	1615	* The hunk-internal region::
	1616	* Support for Completion Frameworks::
	1617	* Additional Completion Options::
	1618
	1619
	1620	File: magit.info, Node: Action Confirmation, Next: Completion and Confirmation, Up: Completion Confirmation and the Selection
	1621
	1622	4.4.1 Action Confirmation
	1623	-------------------------
	1624
	1625	By default many actions that could potentially lead to data loss have to
	1626	be confirmed. This includes many very common actions, so this can
	1627	quickly become annoying. Many of these actions can be undone and if you
	1628	have thought about how to undo certain mistakes, then it should be safe
	1629	to disable confirmation for the respective actions.
	1630
	1631	The option ‘magit-no-confirm’ can be used to tell Magit to perform
	1632	certain actions without the user having to confirm them. Note that
	1633	while this option can only be used to disable confirmation for a
	1634	specific set of actions, the next section explains another way of
	1635	telling Magit to ask fewer questions.
	1636
	1637	-- User Option: magit-no-confirm
	1638
	1639	The value of this option is a list of symbols, representing actions
	1640	that do not have to be confirmed by the user before being carried
	1641	out.
	1642
	1643	By default many potentially dangerous commands ask the user for
	1644	confirmation. Each of the below symbols stands for an action
	1645	which, when invoked unintentionally or without being fully aware of
	1646	the consequences, could lead to tears. In many cases there are
	1647	several commands that perform variations of a certain action, so we
	1648	don’t use the command names but more generic symbols.
	1649
	1650	• Applying changes:
	1651
	1652	• ‘discard’ Discarding one or more changes (i.e. hunks or
	1653	the complete diff for a file) loses that change,
	1654	obviously.
	1655
	1656	• ‘reverse’ Reverting one or more changes can usually be
	1657	undone by reverting the reversion.
	1658
	1659	• ‘stage-all-changes’, ‘unstage-all-changes’ When there are
	1660	both staged and unstaged changes, then un-/staging
	1661	everything would destroy that distinction. Of course
	1662	that also applies when un-/staging a single change, but
	1663	then less is lost and one does that so often that having
	1664	to confirm every time would be unacceptable.
	1665
	1666	• Files:
	1667
	1668	• ‘delete’ When a file that isn’t yet tracked by Git is
	1669	deleted, then it is completely lost, not just the last
	1670	changes. Very dangerous.
	1671
	1672	• ‘trash’ Instead of deleting a file it can also be move to
	1673	the system trash. Obviously much less dangerous than
	1674	deleting it.
	1675
	1676	Also see option ‘magit-delete-by-moving-to-trash’.
	1677
	1678	• ‘resurrect’ A deleted file can easily be resurrected by
	1679	"deleting" the deletion, which is done using the same
	1680	command that was used to delete the same file in the
	1681	first place.
	1682
	1683	• ‘untrack’ Untracking a file can be undone by tracking it
	1684	again.
	1685
	1686	• ‘rename’ Renaming a file can easily be undone.
	1687
	1688	• Sequences:
	1689
	1690	• ‘reset-bisect’ Aborting (known to Git as "resetting") a
	1691	bisect operation loses all information collected so far.
	1692
	1693	• ‘abort-rebase’ Aborting a rebase throws away all already
	1694	modified commits, but it’s possible to restore those from
	1695	the reflog.
	1696
	1697	• ‘abort-merge’ Aborting a merge throws away all conflict
	1698	resolutions which have already been carried out by the
	1699	user.
	1700
	1701	• ‘merge-dirty’ Merging with a dirty worktree can make it
	1702	hard to go back to the state before the merge was
	1703	initiated.
	1704
	1705	• References:
	1706
	1707	• ‘delete-unmerged-branch’ Once a branch has been deleted,
	1708	it can only be restored using low-level recovery tools
	1709	provided by Git. And even then the reflog is gone. The
	1710	user always has to confirm the deletion of a branch by
	1711	accepting the default choice (or selecting another
	1712	branch), but when a branch has not been merged yet, also
	1713	make sure the user is aware of that.
	1714
	1715	• ‘delete-pr-branch’ When deleting a branch that was
	1716	created from a pull request and if no other branches
	1717	still exist on that remote, then ‘magit-branch-delete’
	1718	offers to delete the remote as well. This should be safe
	1719	because it only happens if no other refs exist in the
	1720	remotes namespace, and you can recreate the remote if
	1721	necessary.
	1722
	1723	• ‘drop-stashes’ Dropping a stash is dangerous because Git
	1724	stores stashes in the reflog. Once a stash is removed,
	1725	there is no going back without using low-level recovery
	1726	tools provided by Git. When a single stash is dropped,
	1727	then the user always has to confirm by accepting the
	1728	default (or selecting another). This action only
	1729	concerns the deletion of multiple stashes at once.
	1730
	1731	• Edit published history:
	1732
	1733	Without adding these symbols here, you will be warned before
	1734	editing commits that have already been pushed to one of the
	1735	branches listed in ‘magit-published-branches’.
	1736
	1737	• ‘amend-published’ Affects most commands that amend to
	1738	"HEAD".
	1739
	1740	• ‘rebase-published’ Affects commands that perform
	1741	interactive rebases. This includes commands from the
	1742	commit popup that modify a commit other than "HEAD",
	1743	namely the various fixup and squash variants.
	1744
	1745	• ‘edit-published’ Affects the commands
	1746	‘magit-edit-line-commit’ and
	1747	‘magit-diff-edit-hunk-commit’. These two commands make
	1748	it quite easy to accidentally edit a published commit, so
	1749	you should think twice before configuring them not to ask
	1750	for confirmation.
	1751
	1752	To disable confirmation completely, add all three symbols here
	1753	or set ‘magit-published-branches’ to ‘nil’.
	1754
	1755	• Various:
	1756
	1757	• ‘kill-process’ There seldom is a reason to kill a
	1758	process.
	1759
	1760	• Global settings:
	1761
	1762	Instead of adding all of the above symbols to the value of
	1763	this option, you can also set it to the atom ‘t’, which has
	1764	the same effect as adding all of the above symbols. Doing
	1765	that most certainly is a bad idea, especially because other
	1766	symbols might be added in the future. So even if you don’t
	1767	want to be asked for confirmation for any of these actions,
	1768	you are still better of adding all of the respective symbols
	1769	individually.
	1770
	1771	When ‘magit-wip-before-change-mode’ is enabled, then the
	1772	following actions can be undone fairly easily: ‘discard’,
	1773	‘reverse’, ‘stage-all-changes’, and ‘unstage-all-changes’. If
	1774	and only if this mode is enabled, then ‘safe-with-wip’ has the
	1775	same effect as adding all of these symbols individually.
	1776
	1777
	1778	File: magit.info, Node: Completion and Confirmation, Next: The Selection, Prev: Action Confirmation, Up: Completion Confirmation and the Selection
	1779
	1780	4.4.2 Completion and Confirmation
	1781	---------------------------------
	1782
	1783	Many Magit commands ask the user to select from a list of possible
	1784	things to act on, while offering the most likely choice as the default.
	1785	For many of these commands the default is the thing at point, provided
	1786	that it actually is a valid thing to act on. For many commands that act
	1787	on a branch, the current branch serves as the default if there is no
	1788	branch at point.
	1789
	1790	These commands combine asking for confirmation and asking for a
	1791	target to act on into a single action. The user can confirm the default
	1792	target using ‘RET’ or abort using ‘C-g’. This is similar to a
	1793	‘y-or-n-p’ prompt, but the keys to confirm or abort differ.
	1794
	1795	At the same time the user is also given the opportunity to select
	1796	another target, which is useful because for some commands and/or in some
	1797	situations you might want to select the action before selecting the
	1798	target by moving to it.
	1799
	1800	However you might find that for some commands you always want to use
	1801	the default target, if any, or even that you want the command to act on
	1802	the default without requiring any confirmation at all. The option
	1803	‘magit-dwim-selection’ can be used to configure certain commands to that
	1804	effect.
	1805
	1806	Note that when the region is active then many commands act on the
	1807	things that are selected using a mechanism based on the region, in many
	1808	cases after asking for confirmation. This region-based mechanism is
	1809	called the "selection" and is described in detail in the next section.
	1810	When a selection exists that is valid for the invoked command, then that
	1811	command never offers to act on something else, and whether it asks for
	1812	confirmation is not controlled by this option.
	1813
	1814	Also note that Magit asks for confirmation of certain actions that
	1815	are not coupled with completion (or the selection). Such dialogs are
	1816	also not affected by this option and are described in the previous
	1817	section.
	1818
	1819	-- User Option: magit-dwim-selection
	1820
	1821	This option can be used to tell certain commands to use the thing at
	1822	point instead of asking the user to select a candidate to act on, with
	1823	or without confirmation.
	1824
	1825	The value has the form ‘((COMMAND nil\|PROMPT DEFAULT)...)’.
	1826
	1827	• COMMAND is the command that should not prompt for a choice. To
	1828	have an effect, the command has to use the function
	1829	‘magit-completing-read’ or a utility function which in turn uses
	1830	that function.
	1831
	1832	• If the command uses ‘magit-completing-read’ multiple times, then
	1833	PROMPT can be used to only affect one of these uses. PROMPT, if
	1834	non-nil, is a regular expression that is used to match against the
	1835	PROMPT argument passed to ‘magit-completing-read’.
	1836
	1837	• DEFAULT specifies how to use the default. If it is ‘t’, then the
	1838	DEFAULT argument passed to ‘magit-completing-read’ is used without
	1839	confirmation. If it is ‘ask’, then the user is given a chance to
	1840	abort. DEFAULT can also be ‘nil’, in which case the entry has no
	1841	effect.
	1842
	1843
	1844	File: magit.info, Node: The Selection, Next: The hunk-internal region, Prev: Completion and Confirmation, Up: Completion Confirmation and the Selection
	1845
	1846	4.4.3 The Selection
	1847	-------------------
	1848
	1849	If the region is active, then many Magit commands act on the things that
	1850	are selected using a mechanism based on the region instead of one single
	1851	thing. When the region is not active, then these commands act on the
	1852	thing at point or read a single thing to act on. This is described in
	1853	the previous section — this section only covers how multiple things are
	1854	selected, how that is visualized, and how certain commands behave when
	1855	that is the case.
	1856
	1857	Magit’s mechanism for selecting multiple things, or rather sections
	1858	that represent these things, is based on the Emacs region, but the area
	1859	that Magit considers to be selected is typically larger than the region
	1860	and additional restrictions apply.
	1861
	1862	Magit makes a distinction between a region that qualifies as forming
	1863	a valid Magit selection and a region that does not. If the region does
	1864	not qualify, then it is displayed as it is in other Emacs buffers. If
	1865	the region does qualify as a Magit selection, then the selection is
	1866	always visualized, while the region itself is only visualized if it
	1867	begins and ends on the same line.
	1868
	1869	For a region to qualify as a Magit selection, it must begin in the
	1870	heading of one section and end in the heading of a sibling section.
	1871	Note that if the end of the region is at the very beginning of section
	1872	heading (i.e. at the very beginning of a line) then that section is
	1873	considered to be inside the selection.
	1874
	1875	This is not consistent with how the region is normally treated in
	1876	Emacs — if the region ends at the beginning of a line, then that line is
	1877	outside the region. Due to how Magit visualizes the selection, it
	1878	should be obvious that this difference exists.
	1879
	1880	Not every command acts on every valid selection. Some commands do
	1881	not even consider the location of point, others may act on the section
	1882	at point but not support acting on the selection, and even commands that
	1883	do support the selection of course only do so if it selects things that
	1884	they can act on.
	1885
	1886	This is the main reason why the selection must include the section at
	1887	point. Even if a selection exists, the invoked command may disregard
	1888	it, in which case it may act on the current section only. It is much
	1889	safer to only act on the current section but not the other selected
	1890	sections than it is to act on the current section instead of the
	1891	selected sections. The latter would be much more surprising and if the
	1892	current section always is part of the selection, then that cannot
	1893	happen.
	1894
	1895	-- Variable: magit-keep-region-overlay
	1896
	1897	This variable controls whether the region is visualized as usual
	1898	even when a valid Magit selection or a hunk-internal region exists.
	1899	See the doc-string for more information.
	1900
	1901
	1902	File: magit.info, Node: The hunk-internal region, Next: Support for Completion Frameworks, Prev: The Selection, Up: Completion Confirmation and the Selection
	1903
	1904	4.4.4 The hunk-internal region
	1905	------------------------------
	1906
	1907	Somewhat related to the Magit selection described in the previous
	1908	section is the hunk-internal region.
	1909
	1910	Like the selection, the hunk-internal region is based on the Emacs
	1911	region but causes that region to not be visualized as it would in other
	1912	Emacs buffers, and includes the line on which the region ends even if it
	1913	ends at the very beginning of that line.
	1914
	1915	Unlike the selection, which is based on a region that must begin in
	1916	the heading of one section and ends in the section of a sibling section,
	1917	the hunk-internal region must begin inside the body of a hunk section
	1918	and end in the body of the same section.
	1919
	1920	The hunk-internal region is honored by "apply" commands, which can,
	1921	among other targets, act on a hunk. If the hunk-internal region is
	1922	active, then such commands act only on the marked part of the hunk
	1923	instead of on the complete hunk.
	1924
	1925
	1926	File: magit.info, Node: Support for Completion Frameworks, Next: Additional Completion Options, Prev: The hunk-internal region, Up: Completion Confirmation and the Selection
	1927
	1928	4.4.5 Support for Completion Frameworks
	1929	---------------------------------------
	1930
	1931	The built-in option ‘completing-read-function’ specifies the low-level
	1932	function used by ‘completing-read’ to ask a user to select from a list
	1933	of choices. Its default value is ‘completing-read-default’.
	1934	Alternative completion frameworks typically activate themselves by
	1935	substituting their own implementation.
	1936
	1937	Mostly for historic reasons Magit provides a similar option named
	1938	‘magit-completing-read-function’, which only controls the low-level
	1939	function used by ‘magit-completing-read’. This option also makes it
	1940	possible to use a different completing mechanism for Magit than for the
	1941	rest of Emacs, but doing that is not recommend.
	1942
	1943	You most likely don’t have to customize the magit-specific option to
	1944	use an alternative completion framework. For example, if you enable
	1945	‘ivy-mode’, then Magit will respect that, and if you enable ‘helm-mode’,
	1946	then you are done too.
	1947
	1948	However if you want to use Ido, then ‘ido-mode’ won’t do the trick.
	1949	You will also have to install the ‘ido-completing-read+’ package and use
	1950	‘magit-ido-completing-read’ as ‘magit-completing-read-function’.
	1951
	1952	-- User Option: magit-completing-read-function
	1953
	1954	The value of this variable is the low-level function used to
	1955	perform completion by code that uses ‘magit-completing-read’ (as
	1956	opposed to the built-in ‘completing-read’).
	1957
	1958	The default value, ‘magit-builtin-completing-read’, is suitable for
	1959	the standard completion mechanism, ‘ivy-mode’, and ‘helm-mode’ at
	1960	least.
	1961
	1962	The built-in ‘completing-read’ and ‘completing-read-default’ are
	1963	not suitable to be used here. ‘magit-builtin-completing-read’
	1964	performs some additional work, and any function used in its place
	1965	has to do the same.
	1966
	1967	-- Function: magit-builtin-completing-read prompt choices &optional
	1968	predicate require-match initial-input hist def
	1969
	1970	This function performs completion using the built-in
	1971	‘completion-read’ and does some additional magit-specific work.
	1972
	1973	-- Function: magit-ido-completing-read prompt choices &optional
	1974	predicate require-match initial-input hist def
	1975
	1976	This function performs completion using ‘ido-completing-read+’ from
	1977	the package by the same name (which you have to explicitly install)
	1978	and does some additional magit-specific work.
	1979
	1980	We have to use ‘ido-completing-read+’ instead of the
	1981	‘ido-completing-read’ that comes with Ido itself, because the
	1982	latter, while intended as a drop-in replacement, cannot serve that
	1983	purpose because it violates too many of the implicit conventions.
	1984
	1985	-- Function: magit-completing-read prompt choices &optional predicate
	1986	require-match initial-input hist def fallback
	1987
	1988	This is the function that Magit commands use when they need the
	1989	user to select a single thing to act on. The arguments have the
	1990	same meaning as for ‘completing-read’, except for FALLBACK, which
	1991	is unique to this function and is described below.
	1992
	1993	Instead of asking the user to choose from a list of possible
	1994	candidates, this function may just return the default specified by
	1995	DEF, with or without requiring user confirmation. Whether that is
	1996	the case depends on PROMPT, ‘this-command’ and
	1997	‘magit-dwim-selection’. See the documentation of the latter for
	1998	more information.
	1999
	2000	If it does read a value in the minibuffer, then this function acts
	2001	similar to ‘completing-read’, except for the following:
	2002
	2003	• If REQUIRE-MATCH is ‘nil’ and the user exits without a choice,
	2004	then ‘nil’ is returned instead of an empty string.
	2005
	2006	• If REQUIRE-MATCH is non-nil and the users exits without a
	2007	choice, an user-error is raised.
	2008
	2009	• FALLBACK specifies a secondary default that is only used if
	2010	the primary default DEF is ‘nil’. The secondary default is
	2011	not subject to ‘magit-dwim-selection’ — if DEF is ‘nil’ but
	2012	FALLBACK is not, then this function always asks the user to
	2013	choose a candidate, just as if both defaults were ‘nil’.
	2014
	2015	• ": " is appended to PROMPT.
	2016
	2017	• PROMPT is modified to end with \" (default DEF\|FALLBACK): \"
	2018	provided that DEF or FALLBACK is non-nil, that neither
	2019	‘ivy-mode’ nor ‘helm-mode’ is enabled, and that
	2020	‘magit-completing-read-function’ is set to its default value
	2021	of ‘magit-builtin-completing-read’.
	2022
	2023
	2024	File: magit.info, Node: Additional Completion Options, Prev: Support for Completion Frameworks, Up: Completion Confirmation and the Selection
	2025
	2026	4.4.6 Additional Completion Options
	2027	-----------------------------------
	2028
	2029	-- User Option: magit-list-refs-sortby
	2030
	2031	For many commands that read a ref or refs from the user, the value
	2032	of this option can be used to control the order of the refs. Valid
	2033	values include any key accepted by the ‘--sort’ flag of ‘git
	2034	for-each-ref’. By default, refs are sorted alphabetically by their
	2035	full name (e.g., "refs/heads/master").
	2036
	2037
	2038	File: magit.info, Node: Running Git, Prev: Completion Confirmation and the Selection, Up: Interface Concepts
	2039
	2040	4.5 Running Git
	2041	===============
	2042
	2043	* Menu:
	2044
	2045	* Viewing Git Output::
	2046	* Git Process Status::
	2047	* Running Git Manually::
	2048	* Git Executable::
	2049	* Global Git Arguments::
	2050
	2051
	2052	File: magit.info, Node: Viewing Git Output, Next: Git Process Status, Up: Running Git
	2053
	2054	4.5.1 Viewing Git Output
	2055	------------------------
	2056
	2057	Magit runs Git either for side-effects (e.g. when pushing) or to get
	2058	some value (e.g. the name of the current branch).
	2059
	2060	When Git is run for side-effects, the process output is logged in a
	2061	per-repository log buffer, which can be consulted using the
	2062	‘magit-process’ command when things don’t go as expected.
	2063
	2064	The output/errors for up to ‘magit-process-log-max’ Git commands are
	2065	retained.
	2066
	2067	‘$’ (‘magit-process’)
	2068
	2069	This commands displays the process buffer for the current
	2070	repository.
	2071
	2072	Inside that buffer, the usual key bindings for navigating and showing
	2073	sections are available. There is one additional command.
	2074
	2075	‘k’ (‘magit-process-kill’)
	2076
	2077	This command kills the process represented by the section at point.
	2078
	2079	-- User Option: magit-git-debug
	2080
	2081	When this is non-nil then the output of all calls to git are logged
	2082	in the process buffer. This is useful when debugging, otherwise it
	2083	just negatively affects performance.
	2084
	2085
	2086	File: magit.info, Node: Git Process Status, Next: Running Git Manually, Prev: Viewing Git Output, Up: Running Git
	2087
	2088	4.5.2 Git Process Status
	2089	------------------------
	2090
	2091	When a Git process is running for side-effects, Magit displays an
	2092	indicator in the mode line, using the ‘magit-mode-line-process’ face.
	2093
	2094	If the Git process exits successfully, the process indicator is
	2095	removed from the mode line immediately.
	2096
	2097	In the case of a Git error, the process indicator is not removed, but
	2098	is instead highlighted with the ‘magit-mode-line-process-error’ face,
	2099	and the error details from the process buffer are provided as a tooltip
	2100	for mouse users. This error indicator persists in the mode line until
	2101	the next magit buffer refresh.
	2102
	2103	If you do not wish process errors to be indicated in the mode line,
	2104	customize the ‘magit-process-display-mode-line-error’ user option.
	2105
	2106	Process errors are additionally indicated at the top of the status
	2107	buffer.
	2108
	2109
	2110	File: magit.info, Node: Running Git Manually, Next: Git Executable, Prev: Git Process Status, Up: Running Git
	2111
	2112	4.5.3 Running Git Manually
	2113	--------------------------
	2114
	2115	While Magit provides many Emacs commands to interact with Git, it does
	2116	not cover everything. In those cases your existing Git knowledge will
	2117	come in handy. Magit provides some commands for running arbitrary Git
	2118	commands by typing them into the minibuffer, instead of having to switch
	2119	to a shell.
	2120
	2121	‘!’ (‘magit-run-popup’)
	2122
	2123	Shows the popup buffer featuring the below suffix commands.
	2124
	2125	‘! !’ (‘magit-git-command-topdir’)
	2126
	2127	This command reads a command from the user and executes it in the
	2128	top-level directory of the current working tree.
	2129
	2130	The string "git " is used as initial input when prompting the user
	2131	for the command. It can be removed to run another command.
	2132
	2133	‘! p’ (‘magit-git-command’)
	2134
	2135	This command reads a command from the user and executes it in
	2136	‘default-directory’. With a prefix argument the command is
	2137	executed in the top-level directory of the current working tree
	2138	instead.
	2139
	2140	The string "git " is used as initial input when prompting the user
	2141	for the command. It can be removed to run another command.
	2142
	2143	‘! s’ (‘magit-shell-command-topdir’)
	2144
	2145	This command reads a command from the user and executes it in the
	2146	top-level directory of the current working tree.
	2147
	2148	‘! S’ (‘magit-shell-command’)
	2149
	2150	This command reads a command from the user and executes it in
	2151	‘default-directory’. With a prefix argument the command is
	2152	executed in the top-level directory of the current working tree
	2153	instead.
	2154
	2155	-- User Option: magit-shell-command-verbose-prompt
	2156
	2157	Whether the prompt, used by the the above commands when reading a
	2158	shell command, shows the directory in which it will be run.
	2159
	2160	These suffix commands start external gui tools.
	2161
	2162	‘! k’ (‘magit-run-gitk’)
	2163
	2164	This command runs ‘gitk’ in the current repository.
	2165
	2166	‘! a’ (‘magit-run-gitk-all’)
	2167
	2168	This command runs ‘gitk --all’ in the current repository.
	2169
	2170	‘! b’ (‘magit-run-gitk-branches’)
	2171
	2172	This command runs ‘gitk --branches’ in the current repository.
	2173
	2174	‘! g’ (‘magit-run-git-gui’)
	2175
	2176	This command runs ‘git gui’ in the current repository.
	2177
	2178
	2179	File: magit.info, Node: Git Executable, Next: Global Git Arguments, Prev: Running Git Manually, Up: Running Git
	2180
	2181	4.5.4 Git Executable
	2182	--------------------
	2183
	2184	Except on MS Windows, Magit defaults to running Git without specifying
	2185	the path to the git executable. Instead the first executable found by
	2186	Emacs on ‘exec-path’ is used (whose value in turn is set based on the
	2187	value of the environment variable ‘$PATH’ when Emacs was started).
	2188
	2189	This has the advantage that it continues to work even when using
	2190	Tramp to connect to a remote machine on which the executable is found in
	2191	a different place. The downside is that if you have multiple versions
	2192	of Git installed, then you might end up using another version than the
	2193	one you think you are using.
	2194
	2195	‘M-x magit-version’ (‘magit-version’)
	2196
	2197	This command shows the currently used versions of Magit, Git, and
	2198	Emacs in the echo area. Non-interactively this just returns the
	2199	Magit version.
	2200
	2201	When the ‘system-type’ is ‘windows-nt’, then ‘magit-git-executable’
	2202	is set to an absolute path when Magit is first loaded. This is
	2203	necessary because Git on that platform comes with several wrapper
	2204	scripts for the actual git binary, which are also placed on ‘$PATH’, and
	2205	using one of these wrappers instead of the binary would degrade
	2206	performance horribly.
	2207
	2208	If Magit doesn’t find the correct executable then you can work
	2209	around that by setting ‘magit-git-executable’ to an absolute path. But
	2210	note that doing so is a kludge. It is better to make sure the order in
	2211	the environment variable ‘$PATH’ is correct, and that Emacs is started
	2212	with that environment in effect. The command
	2213	‘magit-debug-git-executable’ can be useful to find out where Emacs is
	2214	searching for git. If you have to connect from Windows to a non-Windows
	2215	machine, then you must change the value to "git".
	2216
	2217	-- User Option: magit-git-executable
	2218
	2219	The git executable used by Magit, either the full path to the
	2220	executable or the string "git" to let Emacs find the executable
	2221	itself, using the standard mechanism for doing such things.
	2222
	2223	‘M-x magit-debug-git-executable’ (‘magit-debug-git-executable’)
	2224
	2225	Display a buffer with information about ‘magit-git-executable’.
	2226
	2227
	2228	File: magit.info, Node: Global Git Arguments, Prev: Git Executable, Up: Running Git
	2229
	2230	4.5.5 Global Git Arguments
	2231	--------------------------
	2232
	2233	-- User Option: magit-git-global-arguments
	2234
	2235	The arguments set here are used every time the git executable is
	2236	run as a subprocess. They are placed right after the executable
	2237	itself and before the git command - as in ‘git HERE... COMMAND
	2238	REST’. For valid arguments see *note (gitman)git::.
	2239
	2240	Be careful what you add here, especially if you are using Tramp to
	2241	connect to servers with ancient Git versions. Never remove
	2242	anything that is part of the default value, unless you really know
	2243	what you are doing. And think very hard before adding something;
	2244	it will be used every time Magit runs Git for any purpose.
	2245
	2246
	2247	File: magit.info, Node: Inspecting, Next: Manipulating, Prev: Interface Concepts, Up: Top
	2248
	2249	5 Inspecting
	2250	************
	2251
	2252	The functionality provided by Magit can be roughly divided into three
	2253	groups: inspecting existing data, manipulating existing data or adding
	2254	new data, and transferring data. Of course that is a rather crude
	2255	distinction that often falls short, but it’s more useful than no
	2256	distinction at all. This section is concerned with inspecting data, the
	2257	next two with manipulating and transferring it. Then follows a section
	2258	about miscellaneous functionality, which cannot easily be fit into this
	2259	distinction.
	2260
	2261	Of course other distinctions make sense too, e.g. Git’s distinction
	2262	between porcelain and plumbing commands, which for the most part is
	2263	equivalent to Emacs’ distinction between interactive commands and
	2264	non-interactive functions. All of the sections mentioned before are
	2265	mainly concerned with the porcelain – Magit’s plumbing layer is
	2266	described later.
	2267
	2268	* Menu:
	2269
	2270	* Status Buffer::
	2271	* Repository List::
	2272	* Logging::
	2273	* Diffing::
	2274	* Ediffing::
	2275	* References Buffer::
	2276	* Bisecting::
	2277	* Visiting Blobs::
	2278	* Blaming::
	2279
	2280
	2281	File: magit.info, Node: Status Buffer, Next: Repository List, Up: Inspecting
	2282
	2283	5.1 Status Buffer
	2284	=================
	2285
	2286	While other Magit buffers contain e.g. one particular diff or one
	2287	particular log, the status buffer contains the diffs for staged and
	2288	unstaged changes, logs for unpushed and unpulled commits, lists of
	2289	stashes and untracked files, and information related to the current
	2290	branch.
	2291
	2292	During certain incomplete operations – for example when a merge
	2293	resulted in a conflict – additional information is displayed that helps
	2294	proceeding with or aborting the operation.
	2295
	2296	The command ‘magit-status’ displays the status buffer belonging to
	2297	the current repository in another window. This command is used so often
	2298	that it should be bound globally. We recommend using ‘C-x g’:
	2299
	2300	(global-set-key (kbd "C-x g") 'magit-status)
	2301
	2302	‘C-x g’ (‘magit-status’)
	2303
	2304	Show the status of the current Git repository in a buffer. With a
	2305	prefix argument prompt for a repository to be shown. With two
	2306	prefix arguments prompt for an arbitrary directory. If that
	2307	directory isn’t the root of an existing repository, then offer to
	2308	initialize it as a new repository.
	2309
	2310	-- User Option: magit-repository-directories
	2311
	2312	List of directories that are Git repositories or contain Git
	2313	repositories.
	2314
	2315	Each element has the form ‘(DIRECTORY . DEPTH)’. DIRECTORY has to
	2316	be a directory or a directory file-name, a string. DEPTH, an
	2317	integer, specifies the maximum depth to look for Git repositories.
	2318	If it is 0, then only add DIRECTORY itself.
	2319
	2320	-- User Option: magit-repository-directories-depth
	2321
	2322	The maximum depth to look for Git repositories. This option is
	2323	obsolete and only used for elements of the option
	2324	‘magit-repository-directories’ (which see) that don’t specify the
	2325	depth directly.
	2326
	2327	-- Command: ido-enter-magit-status
	2328
	2329	From an Ido prompt used to open a file, instead drop into
	2330	‘magit-status’. This is similar to ‘ido-magic-delete-char’, which,
	2331	despite its name, usually causes a Dired buffer to be created.
	2332
	2333	To make this command available, use something like:
	2334
	2335	(add-hook 'ido-setup-hook
	2336	(lambda ()
	2337	(define-key ido-completion-map
	2338	(kbd \"C-x g\") 'ido-enter-magit-status)))
	2339
	2340	Starting with Emacs 25.1 the Ido keymaps are defined just once
	2341	instead of every time Ido is invoked, so now you can modify it like
	2342	pretty much every other keymap:
	2343
	2344	(define-key ido-common-completion-map
	2345	(kbd \"C-x g\") 'ido-enter-magit-status)
	2346
	2347	* Menu:
	2348
	2349	* Status Sections::
	2350	* Status Header Sections::
	2351	* Status Module Sections::
	2352	* Status Options::
	2353
	2354
	2355	File: magit.info, Node: Status Sections, Next: Status Header Sections, Up: Status Buffer
	2356
	2357	5.1.1 Status Sections
	2358	---------------------
	2359
	2360	The contents of status buffers is controlled using the hook
	2361	‘magit-status-sections-hook’. See *note Section Hooks:: to learn about
	2362	such hooks and how to customize them.
	2363
	2364	-- User Option: magit-status-sections-hook
	2365
	2366	Hook run to insert sections into a status buffer.
	2367
	2368	The first function on that hook by default is
	2369	‘magit-insert-status-headers’; it is described in the next section. By
	2370	default the following functions are also members of that hook:
	2371
	2372	-- Function: magit-insert-merge-log
	2373
	2374	Insert section for the on-going merge. Display the heads that are
	2375	being merged. If no merge is in progress, do nothing.
	2376
	2377	-- Function: magit-insert-rebase-sequence
	2378
	2379	Insert section for the on-going rebase sequence. If no such
	2380	sequence is in progress, do nothing.
	2381
	2382	-- Function: magit-insert-am-sequence
	2383
	2384	Insert section for the on-going patch applying sequence. If no
	2385	such sequence is in progress, do nothing.
	2386
	2387	-- Function: magit-insert-sequencer-sequence
	2388
	2389	Insert section for the on-going cherry-pick or revert sequence. If
	2390	no such sequence is in progress, do nothing.
	2391
	2392	-- Function: magit-insert-bisect-output
	2393
	2394	While bisecting, insert section with output from ‘git bisect’.
	2395
	2396	-- Function: magit-insert-bisect-rest
	2397
	2398	While bisecting, insert section visualizing the bisect state.
	2399
	2400	-- Function: magit-insert-bisect-log
	2401
	2402	While bisecting, insert section logging bisect progress.
	2403
	2404	-- Function: magit-insert-untracked-files
	2405
	2406	Maybe insert a list or tree of untracked files.
	2407
	2408	Do so depending on the value of ‘status.showUntrackedFiles’. Note
	2409	that even if the value is ‘all’, Magit still initially only shows
	2410	directories. But the directory sections can then be expanded using
	2411	‘TAB’.
	2412
	2413	-- Function: magit-insert-unstaged-changes
	2414
	2415	Insert section showing unstaged changes.
	2416
	2417	-- Function: magit-insert-staged-changes
	2418
	2419	Insert section showing staged changes.
	2420
	2421	-- Function: magit-insert-stashes &optional ref heading
	2422
	2423	Insert the ‘stashes’ section showing reflog for "refs/stash". If
	2424	optional REF is non-nil show reflog for that instead. If optional
	2425	HEADING is non-nil use that as section heading instead of
	2426	"Stashes:".
	2427
	2428	-- Function: magit-insert-unpulled-from-upstream
	2429
	2430	Insert section showing commits that haven’t been pulled from the
	2431	upstream branch yet.
	2432
	2433	-- Function: magit-insert-unpulled-from-pushremote
	2434
	2435	Insert section showing commits that haven’t been pulled from the
	2436	push-remote branch yet.
	2437
	2438	-- Function: magit-insert-unpushed-to-upstream
	2439
	2440	Insert section showing commits that haven’t been pushed to the
	2441	upstream yet.
	2442
	2443	-- Function: magit-insert-unpushed-to-pushremote
	2444
	2445	Insert section showing commits that haven’t been pushed to the
	2446	push-remote yet.
	2447
	2448	The following functions can also be added to the above hook:
	2449
	2450	-- Function: magit-insert-tracked-files
	2451
	2452	Insert a tree of tracked files.
	2453
	2454	-- Function: magit-insert-ignored-files
	2455
	2456	Insert a tree of ignored files.
	2457
	2458	If the first element of ‘magit-diff-section-arguments’ is a
	2459	directory, then limit the list to files below that. The value of
	2460	that variable can be set using ‘D = f <DIRECTORY> RET g’.
	2461
	2462	-- Function: magit-insert-unpulled-or-recent-commits
	2463
	2464	Insert section showing unpulled or recent commits. If an upstream
	2465	is configured for the current branch and it is ahead of the current
	2466	branch, then show the missing commits. Otherwise, show the last
	2467	‘magit-log-section-commit-count’ commits.
	2468
	2469	-- Function: magit-insert-recent-commits
	2470
	2471	Insert section showing the last ‘magit-log-section-commit-count’
	2472	commits.
	2473
	2474	-- User Option: magit-log-section-commit-count
	2475
	2476	How many recent commits ‘magit-insert-recent-commits’ and
	2477	‘magit-insert-unpulled-or-recent-commits’ (provided there are no
	2478	unpulled commits) show.
	2479
	2480	-- Function: magit-insert-unpulled-cherries
	2481
	2482	Insert section showing unpulled commits. Like
	2483	‘magit-insert-unpulled-commits’ but prefix each commit that has not
	2484	been applied yet (i.e. a commit with a patch-id not shared with
	2485	any local commit) with "+", and all others with "-".
	2486
	2487	-- Function: magit-insert-unpushed-cherries
	2488
	2489	Insert section showing unpushed commits. Like
	2490	‘magit-insert-unpushed-commits’ but prefix each commit which has
	2491	not been applied to upstream yet (i.e. a commit with a patch-id
	2492	not shared with any upstream commit) with "+" and all others with
	2493	"-".
	2494
	2495	See *note References Buffer:: for some more section inserters, which
	2496	could be used here.
	2497
	2498
	2499	File: magit.info, Node: Status Header Sections, Next: Status Module Sections, Prev: Status Sections, Up: Status Buffer
	2500
	2501	5.1.2 Status Header Sections
	2502	----------------------------
	2503
	2504	The contents of status buffers is controlled using the hook
	2505	‘magit-status-sections-hook’ (see *note Status Sections::).
	2506
	2507	By default ‘magit-insert-status-headers’ is the first member of that
	2508	hook variable.
	2509
	2510	-- Function: magit-insert-status-headers
	2511
	2512	Insert headers sections appropriate for ‘magit-status-mode’
	2513	buffers. The sections are inserted by running the functions on the
	2514	hook ‘magit-status-headers-hook’.
	2515
	2516	-- User Option: magit-status-headers-hook
	2517
	2518	Hook run to insert headers sections into the status buffer.
	2519
	2520	This hook is run by ‘magit-insert-status-headers’, which in turn
	2521	has to be a member of ‘magit-status-sections-hook’ to be used at
	2522	all.
	2523
	2524	By default the following functions are members of the above hook:
	2525
	2526	-- Function: magit-insert-error-header
	2527
	2528	Insert a header line showing the message about the Git error that
	2529	just occurred.
	2530
	2531	This function is only aware of the last error that occur when Git
	2532	was run for side-effects. If, for example, an error occurs while
	2533	generating a diff, then that error won’t be inserted. Refreshing
	2534	the status buffer causes this section to disappear again.
	2535
	2536	-- Function: magit-insert-diff-filter-header
	2537
	2538	Insert a header line showing the effective diff filters.
	2539
	2540	-- Function: magit-insert-head-branch-header
	2541
	2542	Insert a header line about the current branch or detached ‘HEAD’.
	2543
	2544	-- Function: magit-insert-upstream-branch-header
	2545
	2546	Insert a header line about the branch that is usually pulled into
	2547	the current branch.
	2548
	2549	-- Function: magit-insert-push-branch-header
	2550
	2551	Insert a header line about the branch that the current branch is
	2552	usually pushed to.
	2553
	2554	-- Function: magit-insert-tags-header
	2555
	2556	Insert a header line about the current and/or next tag, along with
	2557	the number of commits between the tag and ‘HEAD’.
	2558
	2559	The following functions can also be added to the above hook:
	2560
	2561	-- Function: magit-insert-repo-header
	2562
	2563	Insert a header line showing the path to the repository top-level.
	2564
	2565	-- Function: magit-insert-remote-header
	2566
	2567	Insert a header line about the remote of the current branch.
	2568
	2569	If no remote is configured for the current branch, then fall back
	2570	showing the "origin" remote, or if that does not exist the first
	2571	remote in alphabetic order.
	2572
	2573	-- Function: magit-insert-user-header
	2574
	2575	Insert a header line about the current user.
	2576
	2577
	2578	File: magit.info, Node: Status Module Sections, Next: Status Options, Prev: Status Header Sections, Up: Status Buffer
	2579
	2580	5.1.3 Status Module Sections
	2581	----------------------------
	2582
	2583	The contents of status buffers is controlled using the hook
	2584	‘magit-status-sections-hook’ (see *note Status Sections::).
	2585
	2586	By default ‘magit-insert-modules’ is _not_ a member of that hook
	2587	variable.
	2588
	2589	-- Function: magit-insert-modules
	2590
	2591	Insert submodule sections.
	2592
	2593	Hook ‘magit-module-sections-hook’ controls which module sections
	2594	are inserted, and option ‘magit-module-sections-nested’ controls
	2595	whether they are wrapped in an additional section.
	2596
	2597	-- User Option: magit-module-sections-hook
	2598
	2599	Hook run by ‘magit-insert-modules’.
	2600
	2601	-- User Option: magit-module-sections-nested
	2602
	2603	This option controls whether ‘magit-insert-modules’ wraps inserted
	2604	sections in an additional section.
	2605
	2606	If this is non-nil, then only a single top-level section is
	2607	inserted. If it is nil, then all sections listed in
	2608	‘magit-module-sections-hook’ become top-level sections.
	2609
	2610	-- Function: magit-insert-modules-overview
	2611
	2612	Insert sections for all submodules. For each section insert the
	2613	path, the branch, and the output of ‘git describe --tags’, or,
	2614	failing that, the abbreviated HEAD commit hash.
	2615
	2616	Press ‘RET’ on such a submodule section to show its own status
	2617	buffer. Press ‘RET’ on the "Modules" section to display a list of
	2618	submodules in a separate buffer. This shows additional information
	2619	not displayed in the super-repository’s status buffer.
	2620
	2621	-- Function: magit-insert-modules-unpulled-from-upstream
	2622
	2623	Insert sections for modules that haven’t been pulled from the
	2624	upstream yet. These sections can be expanded to show the
	2625	respective commits.
	2626
	2627	-- Function: magit-insert-modules-unpulled-from-pushremote
	2628
	2629	Insert sections for modules that haven’t been pulled from the
	2630	push-remote yet. These sections can be expanded to show the
	2631	respective commits.
	2632
	2633	-- Function: magit-insert-modules-unpushed-to-upstream
	2634
	2635	Insert sections for modules that haven’t been pushed to the
	2636	upstream yet. These sections can be expanded to show the
	2637	respective commits.
	2638
	2639	-- Function: magit-insert-modules-unpushed-to-pushremote
	2640
	2641	Insert sections for modules that haven’t been pushed to the
	2642	push-remote yet. These sections can be expanded to show the
	2643	respective commits.
	2644
	2645
	2646	File: magit.info, Node: Status Options, Prev: Status Module Sections, Up: Status Buffer
	2647
	2648	5.1.4 Status Options
	2649	--------------------
	2650
	2651	-- User Option: magit-status-refresh-hook
	2652
	2653	Hook run after a status buffer has been refreshed.
	2654
	2655	-- User Option: magit-status-margin
	2656
	2657	This option specifies whether the margin is initially shown in
	2658	Magit-Status mode buffers and how it is formatted.
	2659
	2660	The value has the form ‘(INIT STYLE WIDTH AUTHOR AUTHOR-WIDTH)’.
	2661
	2662	• If INIT is non-nil, then the margin is shown initially.
	2663
	2664	• STYLE controls how to format the committer date. It can be
	2665	one of ‘age’ (to show the age of the commit),
	2666	‘age-abbreviated’ (to abbreviate the time unit to a
	2667	character), or a string (suitable for ‘format-time-string’) to
	2668	show the actual date.
	2669
	2670	• WIDTH controls the width of the margin. This exists for
	2671	forward compatibility and currently the value should not be
	2672	changed.
	2673
	2674	• AUTHOR controls whether the name of the author is also shown
	2675	by default.
	2676
	2677	• AUTHOR-WIDTH has to be an integer. When the name of the
	2678	author is shown, then this specifies how much space is used to
	2679	do so.
	2680
	2681	-- User Option: magit-log-section-args
	2682
	2683	Additional Git arguments used when creating log sections. Only
	2684	‘--graph’, ‘--decorate’, and ‘--show-signature’ are supported.
	2685	This option is only a temporary kludge and will be removed.
	2686
	2687	Note that due to an issue in Git the use of ‘--graph’ is very slow
	2688	with long histories, so you probably don’t want to add this here.
	2689
	2690	Also see the proceeding section for more options concerning status
	2691	buffers.
	2692
	2693
	2694	File: magit.info, Node: Repository List, Next: Logging, Prev: Status Buffer, Up: Inspecting
	2695
	2696	5.2 Repository List
	2697	===================
	2698
	2699	-- Command: magit-list-repositories
	2700
	2701	This command displays a list of repositories in a separate buffer.
	2702
	2703	The options ‘magit-repository-directories’ and
	2704	‘magit-repository-directories-depth’ control which repositories are
	2705	displayed.
	2706
	2707	-- User Option: magit-repolist-columns
	2708
	2709	This option controls what columns are displayed by the command
	2710	‘magit-list-repositories’ and how they are displayed.
	2711
	2712	Each element has the form ‘(HEADER WIDTH FORMAT PROPS)’.
	2713
	2714	HEADER is the string displayed in the header. WIDTH is the width
	2715	of the column. FORMAT is a function that is called with one
	2716	argument, the repository identification (usually its basename), and
	2717	with ‘default-directory’ bound to the toplevel of its working tree.
	2718	It has to return a string to be inserted or nil. PROPS is an alist
	2719	that supports the keys ‘:right-align’ and ‘:pad-right’.
	2720
	2721	The following functions can be added to the above option:
	2722
	2723	-- Function: magit-repolist-column-ident
	2724
	2725	This function inserts the identification of the repository.
	2726	Usually this is just its basename.
	2727
	2728	-- Function: magit-repolist-column-path
	2729
	2730	This function inserts the absolute path of the repository.
	2731
	2732	-- Function: magit-repolist-column-version
	2733
	2734	This function inserts a description of the repository’s ‘HEAD’
	2735	revision.
	2736
	2737	-- Function: magit-repolist-column-unpulled-from-upstream
	2738
	2739	This function inserts the number of upstream commits not in the
	2740	current branch.
	2741
	2742	-- Function: magit-repolist-column-unpulled-from-pushremote
	2743
	2744	This function inserts the number of commits in the push branch but
	2745	not the current branch.
	2746
	2747	-- Function: magit-repolist-column-unpushed-to-upstream
	2748
	2749	This function inserts the number of commits in the current branch
	2750	but not its upstream.
	2751
	2752	-- Function: magit-repolist-column-unpushed-to-pushremote
	2753
	2754	This function inserts the number of commits in the current branch
	2755	but not its push branch.
	2756
	2757
	2758	File: magit.info, Node: Logging, Next: Diffing, Prev: Repository List, Up: Inspecting
	2759
	2760	5.3 Logging
	2761	===========
	2762
	2763	The status buffer contains logs for the unpushed and unpulled commits,
	2764	but that obviously isn’t enough. The prefix command ‘magit-log-popup’,
	2765	on ‘l’, features several suffix commands, which show a specific log in a
	2766	separate log buffer.
	2767
	2768	Like other popups, the log popup also features several arguments that
	2769	can be changed before invoking one of the suffix commands. However, in
	2770	the case of the log popup, these arguments may be taken from those
	2771	currently in use in the current repository’s log buffer, depending on
	2772	the value of ‘magit-use-sticky-arguments’ (see *note Popup Buffers and
	2773	Prefix Commands::).
	2774
	2775	For information about the various arguments, see *note
	2776	(gitman)git-log::.
	2777
	2778	The switch ‘++order=VALUE’ is converted to one of
	2779	‘--author-date-order’, ‘--date-order’, or ‘--topo-order’ before being
	2780	passed to ‘git log’.
	2781
	2782	The log popup also features several reflog commands. See *note
	2783	Reflog::.
	2784
	2785	‘l’ (‘magit-log-popup’)
	2786
	2787	This prefix command shows the following suffix commands along with
	2788	the appropriate infix arguments in a popup buffer.
	2789
	2790	‘l l’ (‘magit-log-current’)
	2791
	2792	Show log for the current branch. When ‘HEAD’ is detached or with a
	2793	prefix argument, show log for one or more revs read from the
	2794	minibuffer.
	2795
	2796	‘l o’ (‘magit-log-other’)
	2797
	2798	Show log for one or more revs read from the minibuffer. The user
	2799	can input any revision or revisions separated by a space, or even
	2800	ranges, but only branches, tags, and a representation of the commit
	2801	at point are available as completion candidates.
	2802
	2803	‘l h’ (‘magit-log-head’)
	2804
	2805	Show log for ‘HEAD’.
	2806
	2807	‘l L’ (‘magit-log-branches’)
	2808
	2809	Show log for all local branches and ‘HEAD’.
	2810
	2811	‘l b’ (‘magit-log-all-branches’)
	2812
	2813	Show log for all local and remote branches and ‘HEAD’.
	2814
	2815	‘l a’ (‘magit-log-all’)
	2816
	2817	Show log for all references and ‘HEAD’.
	2818
	2819	Two additional commands that show the log for the file or blob that
	2820	is being visited in the current buffer exists, see *note Minor Mode for
	2821	Buffers Visiting Files::. The command ‘magit-cherry’ also shows a log,
	2822	see *note Cherries::.
	2823
	2824	* Menu:
	2825
	2826	* Refreshing Logs::
	2827	* Log Buffer::
	2828	* Log Margin::
	2829	* Select from Log::
	2830	* Reflog::
	2831	* Cherries::
	2832
	2833
	2834	File: magit.info, Node: Refreshing Logs, Next: Log Buffer, Up: Logging
	2835
	2836	5.3.1 Refreshing Logs
	2837	---------------------
	2838
	2839	The prefix command ‘magit-log-refresh-popup’, on ‘L’, can be used to
	2840	change the log arguments used in the current buffer, without changing
	2841	which log is shown. This works in dedicated log buffers, but also in
	2842	the status buffer.
	2843
	2844	‘L’ (‘magit-log-refresh-popup’)
	2845
	2846	This prefix command shows the following suffix commands along with
	2847	the appropriate infix arguments in a popup buffer.
	2848
	2849	‘L g’ (‘magit-log-refresh’)
	2850
	2851	This suffix command sets the local log arguments for the current
	2852	buffer.
	2853
	2854	‘L s’ (‘magit-log-set-default-arguments’)
	2855
	2856	This suffix command sets the default log arguments for buffers of
	2857	the same type as that of the current buffer. Other existing
	2858	buffers of the same type are not affected because their local
	2859	values have already been initialized.
	2860
	2861	‘L w’ (‘magit-log-save-default-arguments’)
	2862
	2863	This suffix command sets the default log arguments for buffers of
	2864	the same type as that of the current buffer, and saves the value
	2865	for future sessions. Other existing buffers of the same type are
	2866	not affected because their local values have already been
	2867	initialized.
	2868
	2869	‘L t’ (‘magit-toggle-margin’)
	2870
	2871	Show or hide the margin.
	2872
	2873
	2874	File: magit.info, Node: Log Buffer, Next: Log Margin, Prev: Refreshing Logs, Up: Logging
	2875
	2876	5.3.2 Log Buffer
	2877	----------------
	2878
	2879	‘L’ (‘magit-log-refresh-popup’)
	2880
	2881	This prefix command shows the following suffix commands along with
	2882	the appropriate infix arguments in a popup buffer. See *note
	2883	Refreshing Logs::.
	2884
	2885	‘q’ (‘magit-log-bury-buffer’)
	2886
	2887	Bury the current buffer or the revision buffer in the same frame.
	2888	Like ‘magit-mode-bury-buffer’ (which see) but with a negative
	2889	prefix argument instead bury the revision buffer, provided it is
	2890	displayed in the current frame.
	2891
	2892	‘C-c C-b’ (‘magit-go-backward’)
	2893
	2894	Move backward in current buffer’s history.
	2895
	2896	‘C-c C-f’ (‘magit-go-forward’)
	2897
	2898	Move forward in current buffer’s history.
	2899
	2900	‘C-c C-n’ (‘magit-log-move-to-parent’)
	2901
	2902	Move to a parent of the current commit. By default, this is the
	2903	first parent, but a numeric prefix can be used to specify another
	2904	parent.
	2905
	2906	‘SPC’ (‘magit-diff-show-or-scroll-up’)
	2907
	2908	Update the commit or diff buffer for the thing at point.
	2909
	2910	Either show the commit or stash at point in the appropriate buffer,
	2911	or if that buffer is already being displayed in the current frame
	2912	and contains information about that commit or stash, then instead
	2913	scroll the buffer up. If there is no commit or stash at point,
	2914	then prompt for a commit.
	2915
	2916	‘DEL’ (‘magit-diff-show-or-scroll-down’)
	2917
	2918	Update the commit or diff buffer for the thing at point.
	2919
	2920	Either show the commit or stash at point in the appropriate buffer,
	2921	or if that buffer is already being displayed in the current frame
	2922	and contains information about that commit or stash, then instead
	2923	scroll the buffer down. If there is no commit or stash at point,
	2924	then prompt for a commit.
	2925
	2926	‘=’ (‘magit-log-toggle-commit-limit’)
	2927
	2928	Toggle the number of commits the current log buffer is limited to.
	2929	If the number of commits is currently limited, then remove that
	2930	limit. Otherwise set it to 256.
	2931
	2932	‘+’ (‘magit-log-double-commit-limit’)
	2933
	2934	Double the number of commits the current log buffer is limited to.
	2935
	2936	‘-’ (‘magit-log-half-commit-limit’)
	2937
	2938	Half the number of commits the current log buffer is limited to.
	2939
	2940	-- User Option: magit-log-auto-more
	2941
	2942	Insert more log entries automatically when moving past the last
	2943	entry. Only considered when moving past the last entry with
	2944	‘magit-goto-*-section’ commands.
	2945
	2946	-- User Option: magit-log-show-refname-after-summary
	2947
	2948	Whether to show the refnames after the commit summaries. This is
	2949	useful if you use really long branch names.
	2950
	2951	Magit displays references in logs a bit differently from how Git does
	2952	it.
	2953
	2954	Local branches are blue and remote branches are green. Of course
	2955	that depends on the used theme, as do the colors used for other types of
	2956	references. The current branch has a box around it, as do remote
	2957	branches that are their respective remote’s ‘HEAD’ branch.
	2958
	2959	If a local branch and its push-target point at the same commit, then
	2960	their names are combined to preserve space and to make that relationship
	2961	visible. For example:
	2962
	2963	origin/feature
	2964	[green][blue-]
	2965
	2966	instead of
	2967
	2968	feature origin/feature
	2969	[blue-] [green-------]
	2970
	2971	Also note that while the popup features the ‘--show-signature’
	2972	argument, that won’t actually be used when enabled, because Magit
	2973	defaults to use just one line per commit. Instead the commit colorized
	2974	to indicate the validity of the signed commit object, using the faces
	2975	named ‘magit-signature-*’ (which see).
	2976
	2977	For a description of ‘magit-log-margin’ see *note Log Margin::.
	2978
	2979
	2980	File: magit.info, Node: Log Margin, Next: Select from Log, Prev: Log Buffer, Up: Logging
	2981
	2982	5.3.3 Log Margin
	2983	----------------
	2984
	2985	In buffers which show one or more logs, it is possible to show
	2986	additional information about each commit in the margin. The options
	2987	used to configure the margin are named ‘magit-INFIX-margin’, where INFIX
	2988	is the same as in the respective major-mode ‘magit-INFIX-mode’. In
	2989	regular log buffers that would be ‘magit-log-margin’.
	2990
	2991	-- User Option: magit-log-margin
	2992
	2993	This option specifies whether the margin is initially shown in
	2994	Magit-Log mode buffers and how it is formatted.
	2995
	2996	The value has the form ‘(INIT STYLE WIDTH AUTHOR AUTHOR-WIDTH)’.
	2997
	2998	• If INIT is non-nil, then the margin is shown initially.
	2999
	3000	• STYLE controls how to format the committer date. It can be
	3001	one of ‘age’ (to show the age of the commit),
	3002	‘age-abbreviated’ (to abbreviate the time unit to a
	3003	character), or a string (suitable for ‘format-time-string’) to
	3004	show the actual date.
	3005
	3006	• WIDTH controls the width of the margin. This exists for
	3007	forward compatibility and currently the value should not be
	3008	changed.
	3009
	3010	• AUTHOR controls whether the name of the author is also shown
	3011	by default.
	3012
	3013	• AUTHOR-WIDTH has to be an integer. When the name of the
	3014	author is shown, then this specifies how much space is used to
	3015	do so.
	3016
	3017	You can change the STYLE and AUTHOR-WIDTH of all ‘magit-INFIX-margin’
	3018	options to the same values by customizing ‘magit-log-margin’ before
	3019	‘magit’ is loaded. If you do that, then the respective values for the
	3020	other options will default to what you have set for that variable.
	3021	Likewise if you set INIT in ‘magit-log-margin’ to ‘nil’, then that is
	3022	used in the default of all other options. But setting it to ‘t’, i.e.
	3023	re-enforcing the default for that option, does not carry to other
	3024	options.
	3025
	3026	‘L’ (‘magit-margin-popup’)
	3027
	3028	This prefix command features the following commands for changing
	3029	the appearance of the margin.
	3030
	3031	In some buffers that support the margin, "L" is bound to
	3032	‘magit-log-refresh-popup’, but that popup features the same commands,
	3033	and then some other unrelated commands.
	3034
	3035	‘L L’ (‘magit-toggle-margin’)
	3036
	3037	This command shows or hides the margin.
	3038
	3039	‘L l’ (‘magit-cycle-margin-style’)
	3040
	3041	This command cycles the style used for the margin.
	3042
	3043	‘L d’ (‘magit-toggle-margin-details’)
	3044
	3045	This command shows or hides details in the margin.
	3046
	3047
	3048	File: magit.info, Node: Select from Log, Next: Reflog, Prev: Log Margin, Up: Logging
	3049
	3050	5.3.4 Select from Log
	3051	---------------------
	3052
	3053	When the user has to select a recent commit that is reachable from
	3054	‘HEAD’, using regular completion would be inconvenient (because most
	3055	humans cannot remember hashes or "HEAD~5", at least not without double
	3056	checking). Instead a log buffer is used to select the commit, which has
	3057	the advantage that commits are presented in order and with the commit
	3058	message.
	3059
	3060	Such selection logs are used when selecting the beginning of a rebase
	3061	and when selecting the commit to be squashed into.
	3062
	3063	In addition to the key bindings available in all log buffers, the
	3064	following additional key bindings are available in selection log
	3065	buffers:
	3066
	3067	‘C-c C-c’ (‘magit-log-select-pick’)
	3068
	3069	Select the commit at point and act on it. Call
	3070	‘magit-log-select-pick-function’ with the selected commit as
	3071	argument.
	3072
	3073	‘C-c C-k’ (‘magit-log-select-quit’)
	3074
	3075	Abort selecting a commit, don’t act on any commit.
	3076
	3077	-- User Option: magit-log-select-margin
	3078
	3079	This option specifies whether the margin is initially shown in
	3080	Magit-Log-Select mode buffers and how it is formatted.
	3081
	3082	The value has the form ‘(INIT STYLE WIDTH AUTHOR AUTHOR-WIDTH)’.
	3083
	3084	• If INIT is non-nil, then the margin is shown initially.
	3085
	3086	• STYLE controls how to format the committer date. It can be
	3087	one of ‘age’ (to show the age of the commit),
	3088	‘age-abbreviated’ (to abbreviate the time unit to a
	3089	character), or a string (suitable for ‘format-time-string’) to
	3090	show the actual date.
	3091
	3092	• WIDTH controls the width of the margin. This exists for
	3093	forward compatibility and currently the value should not be
	3094	changed.
	3095
	3096	• AUTHOR controls whether the name of the author is also shown
	3097	by default.
	3098
	3099	• AUTHOR-WIDTH has to be an integer. When the name of the
	3100	author is shown, then this specifies how much space is used to
	3101	do so.
	3102
	3103
	3104	File: magit.info, Node: Reflog, Next: Cherries, Prev: Select from Log, Up: Logging
	3105
	3106	5.3.5 Reflog
	3107	------------
	3108
	3109	Also see *note (gitman)git-reflog::.
	3110
	3111	These reflog commands are available from the log popup. See *note
	3112	Logging::.
	3113
	3114	‘l r’ (‘magit-reflog-current’)
	3115
	3116	Display the reflog of the current branch.
	3117
	3118	‘l O’ (‘magit-reflog-other’)
	3119
	3120	Display the reflog of a branch or another ref.
	3121
	3122	‘l H’ (‘magit-reflog-head’)
	3123
	3124	Display the ‘HEAD’ reflog.
	3125
	3126	-- User Option: magit-reflog-margin
	3127
	3128	This option specifies whether the margin is initially shown in
	3129	Magit-Reflog mode buffers and how it is formatted.
	3130
	3131	The value has the form ‘(INIT STYLE WIDTH AUTHOR AUTHOR-WIDTH)’.
	3132
	3133	• If INIT is non-nil, then the margin is shown initially.
	3134
	3135	• STYLE controls how to format the committer date. It can be
	3136	one of ‘age’ (to show the age of the commit),
	3137	‘age-abbreviated’ (to abbreviate the time unit to a
	3138	character), or a string (suitable for ‘format-time-string’) to
	3139	show the actual date.
	3140
	3141	• WIDTH controls the width of the margin. This exists for
	3142	forward compatibility and currently the value should not be
	3143	changed.
	3144
	3145	• AUTHOR controls whether the name of the author is also shown
	3146	by default.
	3147
	3148	• AUTHOR-WIDTH has to be an integer. When the name of the
	3149	author is shown, then this specifies how much space is used to
	3150	do so.
	3151
	3152
	3153	File: magit.info, Node: Cherries, Prev: Reflog, Up: Logging
	3154
	3155	5.3.6 Cherries
	3156	--------------
	3157
	3158	Cherries are commits that haven’t been applied upstream (yet), and are
	3159	usually visualized using a log. Each commit is prefixed with ‘-’ if it
	3160	has an equivalent in the upstream and ‘+’ if it does not, i.e. if it is
	3161	a cherry.
	3162
	3163	The command ‘magit-cherry’ shows cherries for a single branch, but
	3164	the references buffer (see *note References Buffer::) can show cherries
	3165	for multiple "upstreams" at once.
	3166
	3167	Also see *note (gitman)git-reflog::.
	3168
	3169	‘Y’ (‘magit-cherry’)
	3170
	3171	Show commits that are in a certain branch but that have not been
	3172	merged in the upstream branch.
	3173
	3174	-- User Option: magit-cherry-margin
	3175
	3176	This option specifies whether the margin is initially shown in
	3177	Magit-Cherry mode buffers and how it is formatted.
	3178
	3179	The value has the form ‘(INIT STYLE WIDTH AUTHOR AUTHOR-WIDTH)’.
	3180
	3181	• If INIT is non-nil, then the margin is shown initially.
	3182
	3183	• STYLE controls how to format the committer date. It can be
	3184	one of ‘age’ (to show the age of the commit),
	3185	‘age-abbreviated’ (to abbreviate the time unit to a
	3186	character), or a string (suitable for ‘format-time-string’) to
	3187	show the actual date.
	3188
	3189	• WIDTH controls the width of the margin. This exists for
	3190	forward compatibility and currently the value should not be
	3191	changed.
	3192
	3193	• AUTHOR controls whether the name of the author is also shown
	3194	by default.
	3195
	3196	• AUTHOR-WIDTH has to be an integer. When the name of the
	3197	author is shown, then this specifies how much space is used to
	3198	do so.
	3199
	3200
	3201	File: magit.info, Node: Diffing, Next: Ediffing, Prev: Logging, Up: Inspecting
	3202
	3203	5.4 Diffing
	3204	===========
	3205
	3206	The status buffer contains diffs for the staged and unstaged commits,
	3207	but that obviously isn’t enough. The prefix command ‘magit-diff-popup’,
	3208	on ‘d’, features several suffix commands, which show a specific diff in
	3209	a separate diff buffer.
	3210
	3211	Like other popups, the diff popup also features several arguments
	3212	that can be changed before invoking one of the suffix commands.
	3213	However, in the case of the diff popup, these arguments may be taken
	3214	from those currently in use in the current repository’s log buffer,
	3215	depending on the value of ‘magit-use-sticky-arguments’ (see *note Popup
	3216	Buffers and Prefix Commands::).
	3217
	3218	Also see *note (gitman)git-diff::.
	3219
	3220	‘d’ (‘magit-diff-popup’)
	3221
	3222	This prefix command shows the following suffix commands along with
	3223	the appropriate infix arguments in a popup buffer.
	3224
	3225	‘d d’ (‘magit-diff-dwim’)
	3226
	3227	Show changes for the thing at point.
	3228
	3229	‘d r’ (‘magit-diff-range’)
	3230
	3231	Show differences between two commits.
	3232
	3233	RANGE should be a range (A..B or A...B) but can also be a single
	3234	commit. If one side of the range is omitted, then it defaults to
	3235	‘HEAD’. If just a commit is given, then changes in the working
	3236	tree relative to that commit are shown.
	3237
	3238	If the region is active, use the revisions on the first and last
	3239	line of the region. With a prefix argument, instead of diffing the
	3240	revisions, choose a revision to view changes along, starting at the
	3241	common ancestor of both revisions (i.e., use a "..." range).
	3242
	3243	‘d w’ (‘magit-diff-working-tree’)
	3244
	3245	Show changes between the current working tree and the ‘HEAD’
	3246	commit. With a prefix argument show changes between the working
	3247	tree and a commit read from the minibuffer.
	3248
	3249	‘d s’ (‘magit-diff-staged’)
	3250
	3251	Show changes between the index and the ‘HEAD’ commit. With a
	3252	prefix argument show changes between the index and a commit read
	3253	from the minibuffer.
	3254
	3255	‘d u’ (‘magit-diff-unstaged’)
	3256
	3257	Show changes between the working tree and the index.
	3258
	3259	‘d p’ (‘magit-diff-paths’)
	3260
	3261	Show changes between any two files on disk.
	3262
	3263	All of the above suffix commands update the repository’s diff buffer.
	3264	The diff popup also features two commands which show differences in
	3265	another buffer:
	3266
	3267	‘d c’ (‘magit-show-commit’)
	3268
	3269	Show the commit at point. If there is no commit at point or with a
	3270	prefix argument, prompt for a commit.
	3271
	3272	‘d t’ (‘magit-stash-show’)
	3273
	3274	Show all diffs of a stash in a buffer.
	3275
	3276	Two additional commands that show the diff for the file or blob that
	3277	is being visited in the current buffer exists, see *note Minor Mode for
	3278	Buffers Visiting Files::.
	3279
	3280	* Menu:
	3281
	3282	* Refreshing Diffs::
	3283	* Diff Buffer::
	3284	* Diff Options::
	3285	* Revision Buffer::
	3286
	3287
	3288	File: magit.info, Node: Refreshing Diffs, Next: Diff Buffer, Up: Diffing
	3289
	3290	5.4.1 Refreshing Diffs
	3291	----------------------
	3292
	3293	The prefix command ‘magit-diff-refresh-popup’, on ‘D’, can be used to
	3294	change the diff arguments used in the current buffer, without changing
	3295	which diff is shown. This works in dedicated diff buffers, but also in
	3296	the status buffer.
	3297
	3298	‘D’ (‘magit-diff-refresh-popup’)
	3299
	3300	This prefix command shows the following suffix commands along with
	3301	the appropriate infix arguments in a popup buffer.
	3302
	3303	‘D g’ (‘magit-diff-refresh’)
	3304
	3305	This suffix command sets the local diff arguments for the current
	3306	buffer.
	3307
	3308	‘D s’ (‘magit-diff-set-default-arguments’)
	3309
	3310	This suffix command sets the default diff arguments for buffers of
	3311	the same type as that of the current buffer. Other existing
	3312	buffers of the same type are not affected because their local
	3313	values have already been initialized.
	3314
	3315	‘D w’ (‘magit-diff-save-default-arguments’)
	3316
	3317	This suffix command sets the default diff arguments for buffers of
	3318	the same type as that of the current buffer, and saves the value
	3319	for future sessions. Other existing buffers of the same type are
	3320	not affected because their local values have already been
	3321	initialized.
	3322
	3323	‘D t’ (‘magit-diff-toggle-refine-hunk’)
	3324
	3325	This command toggles hunk refinement on or off.
	3326
	3327	‘D r’ (‘magit-diff-switch-range-type’)
	3328
	3329	This command converts the diff range type from "revA..revB" to
	3330	"revB...revA", or vice versa.
	3331
	3332	‘D f’ (‘magit-diff-flip-revs’)
	3333
	3334	This command swaps revisions in the diff range from "revA..revB" to
	3335	"revB..revA", or vice versa.
	3336
	3337	‘D F’ (‘magit-diff-toggle-file-filter’)
	3338
	3339	This command toggles the file restriction of the diffs in the
	3340	current buffer, allowing you to quickly switch between viewing all
	3341	the changes in the commit and the restricted subset. As a special
	3342	case, when this command is called from a log buffer, it toggles the
	3343	file restriction in the repository’s revision buffer, which is
	3344	useful when you display a revision from a log buffer that is
	3345	restricted to a file or files.
	3346
	3347	In addition to the above popup, which allows changing any of the
	3348	supported arguments, there also exist some commands which change a
	3349	particular argument.
	3350
	3351	‘-’ (‘magit-diff-less-context’)
	3352
	3353	This command decreases the context for diff hunks by COUNT lines.
	3354
	3355	‘+’ (‘magit-diff-more-context’)
	3356
	3357	This command increases the context for diff hunks by COUNT lines.
	3358
	3359	‘0’ (‘magit-diff-default-context’)
	3360
	3361	This command resets the context for diff hunks to the default
	3362	height.
	3363
	3364	The following commands quickly change what diff is being displayed
	3365	without having to using one of the diff popups.
	3366
	3367	‘C-c C-d’ (‘magit-diff-while-committing’)
	3368
	3369	While committing, this command shows the changes that are about to
	3370	be committed. While amending, invoking the command again toggles
	3371	between showing just the new changes or all the changes that will
	3372	be committed.
	3373
	3374	This binding is available in the diff buffer as well as the commit
	3375	message buffer.
	3376
	3377	‘C-c C-b’ (‘magit-go-backward’)
	3378
	3379	This command moves backward in current buffer’s history.
	3380
	3381	‘C-c C-f’ (‘magit-go-forward’)
	3382
	3383	This command moves forward in current buffer’s history.
	3384
	3385
	3386	File: magit.info, Node: Diff Buffer, Next: Diff Options, Prev: Refreshing Diffs, Up: Diffing
	3387
	3388	5.4.2 Diff Buffer
	3389	-----------------
	3390
	3391	These commands are available in diff buffers.
	3392
	3393	‘RET’ (‘magit-diff-visit-file’)
	3394
	3395	From a diff, visit the corresponding file at the appropriate
	3396	position.
	3397
	3398	If the diff shows changes in the worktree, the index, or ‘HEAD’,
	3399	then visit the actual file. Otherwise, when the diff is about an
	3400	older commit or a range, then visit the appropriate blob.
	3401
	3402	If point is on a removed line, then visit the blob for the first
	3403	parent of the commit which removed that line, i.e. the last commit
	3404	where that line still existed. Otherwise visit the blob for the
	3405	commit whose changes are being shown.
	3406
	3407	Interactively, when the file or blob to be displayed is already
	3408	being displayed in another window of the same frame, then just
	3409	select that window and adjust point. Otherwise, or with a prefix
	3410	argument, display the buffer in another window. The meaning of the
	3411	prefix argument can be inverted or further modified using the
	3412	option ‘magit-display-file-buffer-function’.
	3413
	3414	Non-interactively the optional OTHER-WINDOW argument is taken
	3415	literally. DISPLAY-FN can be used to specify the display function
	3416	explicitly, in which case OTHER-WINDOW is ignored.
	3417
	3418	The optional FORCE-WORKTREE means to force visiting the worktree
	3419	version of the file. To do this interactively use the command
	3420	‘magit-diff-visit-file-worktree’ instead.
	3421
	3422	-- User Option: magit-diff-visit-previous-blob
	3423
	3424	This option controls whether ‘magit-diff-visit-file’ may visit the
	3425	previous blob. When this is ‘t’ and point is on a removed line in
	3426	a diff for a committed change, then ‘magit-diff-visit-file’ visits
	3427	the blob from the last revision which still had that line.
	3428
	3429	Currently this is only supported for committed changes, for staged
	3430	and unstaged changes ‘magit-diff-visit-file’ always visits the file
	3431	in the working tree.
	3432
	3433	‘C-<return>’ (‘magit-diff-visit-file-worktree’)
	3434
	3435	From a diff, visit the corresponding file at the appropriate
	3436	position.
	3437
	3438	When the file is already being displayed in another window of the
	3439	same frame, then just select that window and adjust point. With a
	3440	prefix argument also display in another window.
	3441
	3442	The actual file in the worktree is visited. The positions in the
	3443	hunk headers get less useful the "older" the changes are, and as a
	3444	result, jumping to the appropriate position gets less reliable.
	3445
	3446	Also see ‘magit-diff-visit-file’, which visits the respective blob,
	3447	unless the diff shows changes in the worktree, the index, or
	3448	‘HEAD’.
	3449
	3450	-- Command: magit-diff-visit-file-other-window
	3451
	3452	From a diff, visit the corresponding file at the appropriate
	3453	position in another window.
	3454
	3455	‘C-c C-t’ (‘magit-diff-trace-definition’)
	3456
	3457	From a diff, show log for the definition at point.
	3458
	3459	-- User Option: magit-log-trace-definition-function
	3460
	3461	The function used by ‘magit-log-trace-definition’ to determine the
	3462	function at point. For major-modes that have special needs, you
	3463	could set that using the mode’s hook.
	3464
	3465	‘C-c C-e’ (‘magit-diff-edit-hunk-commit’)
	3466
	3467	From a hunk, edit the respective commit and visit the file.
	3468
	3469	First visit the file being modified by the hunk at the correct
	3470	location using ‘magit-diff-visit-file’. This actually visits a
	3471	blob. When point is on a diff header, not within an individual
	3472	hunk, then this visits the blob the first hunk is about.
	3473
	3474	Then invoke ‘magit-edit-line-commit’, which uses an interactive
	3475	rebase to make the commit editable, or if that is not possible
	3476	because the commit is not reachable from ‘HEAD’ by checking out
	3477	that commit directly. This also causes the actual worktree file to
	3478	be visited.
	3479
	3480	Neither the blob nor the file buffer are killed when finishing the
	3481	rebase. If that is undesirable, then it might be better to use
	3482	‘magit-rebase-edit-command’ instead of this command.
	3483
	3484	‘j’ (‘magit-jump-to-diffstat-or-diff’)
	3485
	3486	Jump to the diffstat or diff. When point is on a file inside the
	3487	diffstat section, then jump to the respective diff section.
	3488	Otherwise, jump to the diffstat section or a child thereof.
	3489
	3490	‘SPC’ (‘scroll-up’)
	3491
	3492	Scroll text upward.
	3493
	3494	‘DEL’ (‘scroll-down’)
	3495
	3496	Scroll text downward.
	3497
	3498
	3499	File: magit.info, Node: Diff Options, Next: Revision Buffer, Prev: Diff Buffer, Up: Diffing
	3500
	3501	5.4.3 Diff Options
	3502	------------------
	3503
	3504	-- User Option: magit-diff-refine-hunk
	3505
	3506	Whether to show word-granularity differences within diff hunks.
	3507
	3508	• ‘nil’ never show fine differences.
	3509
	3510	• ‘t’ show fine differences for the current diff hunk only.
	3511
	3512	• ‘all’ show fine differences for all displayed diff hunks.
	3513
	3514	-- User Option: magit-diff-adjust-tab-width
	3515
	3516	Whether to adjust the width of tabs in diffs.
	3517
	3518	Determining the correct width can be expensive if it requires
	3519	opening large and/or many files, so the widths are cached in the
	3520	variable ‘magit-diff--tab-width-cache’. Set that to nil to
	3521	invalidate the cache.
	3522
	3523	• ‘nil’ Never adjust tab width. Use ‘tab-width’s value from the
	3524	Magit buffer itself instead.
	3525
	3526	• ‘t’ If the corresponding file-visiting buffer exits, then use
	3527	‘tab-width’’s value from that buffer. Doing this is cheap, so
	3528	this value is used even if a corresponding cache entry exists.
	3529
	3530	• ‘always’ If there is no such buffer, then temporarily visit
	3531	the file to determine the value.
	3532
	3533	• NUMBER Like ‘always’, but don’t visit files larger than NUMBER
	3534	bytes.
	3535
	3536	-- User Option: magit-diff-paint-whitespace
	3537
	3538	Specify where to highlight whitespace errors.
	3539
	3540	See ‘magit-diff-highlight-trailing’,
	3541	‘magit-diff-highlight-indentation’. The symbol ‘t’ means in all
	3542	diffs, ‘status’ means only in the status buffer, and nil means
	3543	nowhere.
	3544
	3545	-- User Option: magit-diff-highlight-trailing
	3546
	3547	Whether to highlight whitespace at the end of a line in diffs.
	3548	Used only when ‘magit-diff-paint-whitespace’ is non-nil.
	3549
	3550	-- User Option: magit-diff-highlight-indentation
	3551
	3552	Highlight the "wrong" indentation style. Used only when
	3553	‘magit-diff-paint-whitespace’ is non-nil.
	3554
	3555	The value is a list of cons cells. The car is a regular
	3556	expression, and the cdr is the value that applies to repositories
	3557	whose directory matches the regular expression. If more than one
	3558	element matches, then the last element in the list applies. The
	3559	default value should therefore come first in the list.
	3560
	3561	If the value is ‘tabs’, highlight indentation with tabs. If the
	3562	value is an integer, highlight indentation with at least that many
	3563	spaces. Otherwise, highlight neither.
	3564
	3565	-- User Option: magit-diff-hide-trailing-cr-characters
	3566
	3567	Whether to hide ^M characters at the end of a line in diffs.
	3568
	3569	-- User Option: magit-diff-highlight-hunk-region-functions
	3570
	3571	This option specifies the functions used to highlight the
	3572	hunk-internal region.
	3573
	3574	‘magit-diff-highlight-hunk-region-dim-outside’ overlays the outside
	3575	of the hunk internal selection with a face that causes the added
	3576	and removed lines to have the same background color as context
	3577	lines. This function should not be removed from the value of this
	3578	option.
	3579
	3580	‘magit-diff-highlight-hunk-region-using-overlays’ and
	3581	‘magit-diff-highlight-hunk-region-using-underline’ emphasize the
	3582	region by placing delimiting horizontal lines before and after it.
	3583	Both of these functions have glitches which cannot be fixed due to
	3584	limitations of Emacs’ display engine. For more information see
	3585	<https://github.com/magit/magit/issues/2758> ff.
	3586
	3587	Instead of, or in addition to, using delimiting horizontal lines,
	3588	to emphasize the boundaries, you may which to emphasize the text
	3589	itself, using ‘magit-diff-highlight-hunk-region-using-face’.
	3590
	3591	In terminal frames it’s not possible to draw lines as the overlay
	3592	and underline variants normally do, so there they fall back to
	3593	calling the face function instead.
	3594
	3595	-- User Option: magit-diff-unmarked-lines-keep-foreground
	3596
	3597	This option controls whether added and removed lines outside the
	3598	hunk-internal region only lose their distinct background color or
	3599	also the foreground color. Whether the outside of the region is
	3600	dimmed at all depends on
	3601	‘magit-diff-highlight-hunk-region-functions’.
	3602
	3603
	3604	File: magit.info, Node: Revision Buffer, Prev: Diff Options, Up: Diffing
	3605
	3606	5.4.4 Revision Buffer
	3607	---------------------
	3608
	3609	-- User Option: magit-revision-insert-related-refs
	3610
	3611	Whether to show related branches in revision buffers.
	3612
	3613	• ‘nil’ Don’t show any related branches.
	3614
	3615	• ‘t’ Show related local branches.
	3616
	3617	• ‘all’ Show related local and remote branches.
	3618
	3619	• ‘mixed’ Show all containing branches and local merged
	3620	branches.
	3621
	3622	-- User Option: magit-revision-show-gravatars
	3623
	3624	Whether to show gravatar images in revision buffers.
	3625
	3626	If ‘nil’, then don’t insert any gravatar images. If ‘t’, then
	3627	insert both images. If ‘author’ or ‘committer’, then insert only
	3628	the respective image.
	3629
	3630	If you have customized the option ‘magit-revision-header-format’
	3631	and want to insert the images then you might also have to specify
	3632	where to do so. In that case the value has to be a cons-cell of
	3633	two regular expressions. The car specifies where to insert the
	3634	author’s image. The top half of the image is inserted right after
	3635	the matched text, the bottom half on the next line in the same
	3636	column. The cdr specifies where to insert the committer’s image,
	3637	accordingly. Either the car or the cdr may be nil."
	3638
	3639	-- User Option: magit-revision-use-hash-sections
	3640
	3641	Whether to turn hashes inside the commit message into sections.
	3642
	3643	If non-nil, then hashes inside the commit message are turned into
	3644	‘commit’ sections. There is a trade off to be made between
	3645	performance and reliability:
	3646
	3647	• ‘slow’ calls git for every word to be absolutely sure.
	3648
	3649	• ‘quick’ skips words less than seven characters long.
	3650
	3651	• ‘quicker’ additionally skips words that don’t contain a
	3652	number.
	3653
	3654	• ‘quickest’ uses all words that are at least seven characters
	3655	long and which contain at least one number as well as at least
	3656	one letter.
	3657
	3658	If nil, then no hashes are turned into sections, but you can still
	3659	visit the commit at point using "RET".
	3660
	3661	The diffs shown in the revision buffer may be automatically
	3662	restricted to a subset of the changed files. If the revision buffer is
	3663	displayed from a log buffer, the revision buffer will share the same
	3664	file restriction as that log buffer (also see the command
	3665	‘magit-diff-toggle-file-filter’). Note, however, that the log’s file
	3666	restriction will be ignored when ‘magit-log-arguments’ includes
	3667	‘--follow’. In this case, the ‘-u’ argument of the log popup can be
	3668	used to show the file-restricted diffs inline.
	3669
	3670	If the revision buffer is not displayed from a log buffer, the file
	3671	restriction is determined by the file restriction in the repository’s
	3672	diff buffer, if it exists, and the value of the option
	3673	‘magit-use-sticky-arguments’.
	3674
	3675
	3676	File: magit.info, Node: Ediffing, Next: References Buffer, Prev: Diffing, Up: Inspecting
	3677
	3678	5.5 Ediffing
	3679	============
	3680
	3681	This section describes how to enter Ediff from Magit buffers. For
	3682	information on how to use Ediff itself, see *note (ediff)Top::.
	3683
	3684	‘e’ (‘magit-ediff-dwim’)
	3685
	3686	Compare, stage, or resolve using Ediff.
	3687
	3688	This command tries to guess what file, and what commit or range the
	3689	user wants to compare, stage, or resolve using Ediff. It might
	3690	only be able to guess either the file, or range/commit, in which
	3691	case the user is asked about the other. It might not always guess
	3692	right, in which case the appropriate ‘magit-ediff-*’ command has to
	3693	be used explicitly. If it cannot read the user’s mind at all, then
	3694	it asks the user for a command to run.
	3695
	3696	‘E’ (‘magit-ediff-popup’)
	3697
	3698	This prefix command shows the following suffix commands in a popup
	3699	buffer.
	3700
	3701	‘E r’ (‘magit-ediff-compare’)
	3702
	3703	Compare two revisions of a file using Ediff.
	3704
	3705	If the region is active, use the revisions on the first and last
	3706	line of the region. With a prefix argument, instead of diffing the
	3707	revisions, choose a revision to view changes along, starting at the
	3708	common ancestor of both revisions (i.e., use a "..." range).
	3709
	3710	‘E m’ (‘magit-ediff-resolve’)
	3711
	3712	Resolve outstanding conflicts in a file using Ediff, defaulting to
	3713	the file at point.
	3714
	3715	Provided that the value of ‘merge.conflictstyle’ is ‘diff3’, you
	3716	can view the file’s merge-base revision using ‘/’ in the Ediff
	3717	control buffer.
	3718
	3719	In the rare event that you want to manually resolve all conflicts,
	3720	including those already resolved by Git, use
	3721	‘ediff-merge-revisions-with-ancestor’.
	3722
	3723	‘E s’ (‘magit-ediff-stage’)
	3724
	3725	Stage and unstage changes to a file using Ediff, defaulting to the
	3726	file at point.
	3727
	3728	‘E u’ (‘magit-ediff-show-unstaged’)
	3729
	3730	Show unstaged changes to a file using Ediff.
	3731
	3732	‘E i’ (‘magit-ediff-show-staged’)
	3733
	3734	Show staged changes to a file using Ediff.
	3735
	3736	‘E w’ (‘magit-ediff-show-working-tree’)
	3737
	3738	Show changes in a file between ‘HEAD’ and working tree using Ediff.
	3739
	3740	‘E c’ (‘magit-ediff-show-commit’)
	3741
	3742	Show changes to a file introduced by a commit using Ediff.
	3743
	3744	‘E z’ (‘magit-ediff-show-stash’)
	3745
	3746	Show changes to a file introduced by a stash using Ediff.
	3747
	3748	-- User Option: magit-ediff-dwim-show-on-hunks
	3749
	3750	This option controls what command ‘magit-ediff-dwim’ calls when
	3751	point is on uncommitted hunks. When nil, always run
	3752	‘magit-ediff-stage’. Otherwise, use ‘magit-ediff-show-staged’ and
	3753	‘magit-ediff-show-unstaged’ to show staged and unstaged changes,
	3754	respectively.
	3755
	3756	-- User Option: magit-ediff-show-stash-with-index
	3757
	3758	This option controls whether ‘magit-ediff-show-stash’ includes a
	3759	buffer containing the file’s state in the index at the time the
	3760	stash was created. This makes it possible to tell which changes in
	3761	the stash were staged.
	3762
	3763	-- User Option: magit-ediff-quit-hook
	3764
	3765	This hook is run after quitting an Ediff session that was created
	3766	using a Magit command. The hook functions are run inside the Ediff
	3767	control buffer, and should not change the current buffer.
	3768
	3769	This is similar to ‘ediff-quit-hook’ but takes the needs of Magit
	3770	into account. The regular ‘ediff-quit-hook’ is ignored by Ediff
	3771	sessions that were created using a Magit command.
	3772
	3773
	3774	File: magit.info, Node: References Buffer, Next: Bisecting, Prev: Ediffing, Up: Inspecting
	3775
	3776	5.6 References Buffer
	3777	=====================
	3778
	3779	‘y’ (‘magit-show-refs-popup’)
	3780
	3781	List and compare references in a dedicated buffer. By default all
	3782	refs are compared with ‘HEAD’, but with a prefix argument this
	3783	command instead acts as a prefix command and shows the following
	3784	suffix commands along with the appropriate infix arguments in a
	3785	popup buffer.
	3786
	3787	‘y y’ (‘magit-show-refs-head’)
	3788
	3789	List and compare references in a dedicated buffer. Refs are
	3790	compared with ‘HEAD’.
	3791
	3792	‘y c’ (‘magit-show-refs-current’)
	3793
	3794	List and compare references in a dedicated buffer. Refs are
	3795	compared with the current branch or ‘HEAD’ if it is detached.
	3796
	3797	‘y o’ (‘magit-show-refs’)
	3798
	3799	List and compare references in a dedicated buffer. Refs are
	3800	compared with a branch read from the user.
	3801
	3802	-- User Option: magit-refs-show-commit-count
	3803
	3804	Whether to show commit counts in Magit-Refs mode buffers.
	3805
	3806	• ‘all’ Show counts for branches and tags.
	3807
	3808	• ‘branch’ Show counts for branches only.
	3809
	3810	• ‘nil’ Never show counts.
	3811
	3812	The default is ‘nil’ because anything else can be very expensive.
	3813
	3814	-- User Option: magit-refs-pad-commit-counts
	3815
	3816	Whether to pad all commit counts on all sides in Magit-Refs mode
	3817	buffers.
	3818
	3819	If this is nil, then some commit counts are displayed right next to
	3820	one of the branches that appear next to the count, without any
	3821	space in between. This might look bad if the branch name faces
	3822	look too similar to ‘magit-dimmed’.
	3823
	3824	If this is non-nil, then spaces are placed on both sides of all
	3825	commit counts.
	3826
	3827	-- User Option: magit-refs-show-remote-prefix
	3828
	3829	Whether to show the remote prefix in lists of remote branches.
	3830
	3831	Showing the prefix is redundant because the name of the remote is
	3832	already shown in the heading preceding the list of its branches.
	3833
	3834	-- User Option: magit-refs-primary-column-width
	3835
	3836	Width of the primary column in ‘magit-refs-mode’ buffers. The
	3837	primary column is the column that contains the name of the branch
	3838	that the current row is about.
	3839
	3840	If this is an integer, then the column is that many columns wide.
	3841	Otherwise it has to be a cons-cell of two integers. The first
	3842	specifies the minimal width, the second the maximal width. In that
	3843	case the actual width is determined using the length of the names
	3844	of the shown local branches. (Remote branches and tags are not
	3845	taken into account when calculating to optimal width.)
	3846
	3847	-- User Option: magit-refs-focus-column-width
	3848
	3849	Width of the focus column in ‘magit-refs-mode’ buffers.
	3850
	3851	The focus column is the first column, which marks one branch
	3852	(usually the current branch) as the focused branch using ‘*’ or
	3853	‘@’. For each other reference, this column optionally shows how
	3854	many commits it is ahead of the focused branch and ‘<’, or if it
	3855	isn’t ahead then the commits it is behind and ‘>’, or if it isn’t
	3856	behind either, then a ‘=’.
	3857
	3858	This column may also display only ‘*’ or ‘@’ for the focused
	3859	branch, in which case this option is ignored. Use ‘L v’ to change
	3860	the verbosity of this column.
	3861
	3862	-- User Option: magit-refs-margin
	3863
	3864	This option specifies whether the margin is initially shown in
	3865	Magit-Refs mode buffers and how it is formatted.
	3866
	3867	The value has the form ‘(INIT STYLE WIDTH AUTHOR AUTHOR-WIDTH)’.
	3868
	3869	• If INIT is non-nil, then the margin is shown initially.
	3870
	3871	• STYLE controls how to format the committer date. It can be
	3872	one of ‘age’ (to show the age of the commit),
	3873	‘age-abbreviated’ (to abbreviate the time unit to a
	3874	character), or a string (suitable for ‘format-time-string’) to
	3875	show the actual date.
	3876
	3877	• WIDTH controls the width of the margin. This exists for
	3878	forward compatibility and currently the value should not be
	3879	changed.
	3880
	3881	• AUTHOR controls whether the name of the author is also shown
	3882	by default.
	3883
	3884	• AUTHOR-WIDTH has to be an integer. When the name of the
	3885	author is shown, then this specifies how much space is used to
	3886	do so.
	3887
	3888	-- User Option: magit-refs-margin-for-tags
	3889
	3890	This option specifies whether to show information about tags in the
	3891	margin. This is disabled by default because it is slow if there
	3892	are many tags.
	3893
	3894	The following variables control how individual refs are displayed.
	3895	If you change one of these variables (especially the "%c" part), then
	3896	you should also change the others to keep things aligned. The following
	3897	%-sequences are supported:
	3898
	3899	• ‘%a’ Number of commits this ref has over the one we compare to.
	3900
	3901	• ‘%b’ Number of commits the ref we compare to has over this one.
	3902
	3903	• ‘%c’ Number of commits this ref has over the one we compare to.
	3904	For the ref which all other refs are compared this is instead "@",
	3905	if it is the current branch, or "#" otherwise.
	3906
	3907	• ‘%C’ For the ref which all other refs are compared this is "@", if
	3908	it is the current branch, or "#" otherwise. For all other refs "
	3909	".
	3910
	3911	• ‘%h’ Hash of this ref’s tip.
	3912
	3913	• ‘%m’ Commit summary of the tip of this ref.
	3914
	3915	• ‘%n’ Name of this ref.
	3916
	3917	• ‘%u’ Upstream of this local branch.
	3918
	3919	• ‘%U’ Upstream of this local branch and additional local vs.
	3920	upstream information.
	3921
	3922	-- User Option: magit-refs-filter-alist
	3923
	3924	This alist controls which tags and branches are omitted from being
	3925	displayed in ‘magit-refs-mode’ buffers. If it is ‘nil’, then all
	3926	refs are displayed (subject to ‘magit-refs-sections-hook’).
	3927
	3928	All keys are tried in order until one matches. Then its value is
	3929	used and subsequent elements are ignored. If the value is non-nil,
	3930	then the reference is displayed, otherwise it is not. If no
	3931	element matches, then the reference is displayed.
	3932
	3933	A key can either be a regular expression that the refname has to
	3934	match, or a function that takes the refname as only argument and
	3935	returns a boolean. Contrary to how they are displayed in the
	3936	buffer, for comparison each tag begins with "tags/" and each remote
	3937	branch with "<remote>/".
	3938
	3939	‘RET’ (‘magit-visit-ref’)
	3940
	3941	This command visits the reference or revision at point in another
	3942	buffer. If there is no revision at point or with a prefix argument
	3943	then it prompts for a revision.
	3944
	3945	This command behaves just like ‘magit-show-commit’ as described
	3946	above, except if point is on a reference in a ‘magit-refs-mode’
	3947	buffer, in which case the behavior may be different, but only if
	3948	you have customized the option ‘magit-visit-ref-behavior’.
	3949
	3950	-- User Option: magit-visit-ref-behavior
	3951
	3952	This option controls how ‘magit-visit-ref’ behaves in
	3953	‘magit-refs-mode’ buffers.
	3954
	3955	By default ‘magit-visit-ref’ behaves like ‘magit-show-commit’, in
	3956	all buffers, including ‘magit-refs-mode’ buffers. When the type of
	3957	the section at point is ‘commit’ then "RET" is bound to
	3958	‘magit-show-commit’, and when the type is either ‘branch’ or ‘tag’
	3959	then it is bound to ‘magit-visit-ref’.
	3960
	3961	"RET" is one of Magit’s most essential keys and at least by default
	3962	it should behave consistently across all of Magit, especially
	3963	because users quickly learn that it does something very harmless;
	3964	it shows more information about the thing at point in another
	3965	buffer.
	3966
	3967	However "RET" used to behave differently in ‘magit-refs-mode’
	3968	buffers, doing surprising things, some of which cannot really be
	3969	described as "visit this thing". If you’ve grown accustomed this
	3970	behavior, you can restore it by adding one or more of the below
	3971	symbols to the value of this option. But keep in mind that by
	3972	doing so you don’t only introduce inconsistencies, you also lose
	3973	some functionality and might have to resort to ‘M-x
	3974	magit-show-commit’ to get it back.
	3975
	3976	‘magit-visit-ref’ looks for these symbols in the order in which
	3977	they are described here. If the presence of a symbol applies to
	3978	the current situation, then the symbols that follow do not affect
	3979	the outcome.
	3980
	3981	• ‘focus-on-ref’
	3982
	3983	With a prefix argument update the buffer to show commit counts
	3984	and lists of cherry commits relative to the reference at point
	3985	instead of relative to the current buffer or ‘HEAD’.
	3986
	3987	Instead of adding this symbol, consider pressing "C-u y o
	3988	RET".
	3989
	3990	• ‘create-branch’
	3991
	3992	If point is on a remote branch, then create a new local branch
	3993	with the same name, use the remote branch as its upstream, and
	3994	then check out the local branch.
	3995
	3996	Instead of adding this symbol, consider pressing "b c RET
	3997	RET", like you would do in other buffers.
	3998
	3999	• ‘checkout-any’
	4000
	4001	Check out the reference at point. If that reference is a tag
	4002	or a remote branch, then this results in a detached ‘HEAD’.
	4003
	4004	Instead of adding this symbol, consider pressing "b b RET",
	4005	like you would do in other buffers.
	4006
	4007	• ‘checkout-branch’
	4008
	4009	Check out the local branch at point.
	4010
	4011	Instead of adding this symbol, consider pressing "b b RET",
	4012	like you would do in other buffers.
	4013
	4014	* Menu:
	4015
	4016	* References Sections::
	4017
	4018
	4019	File: magit.info, Node: References Sections, Up: References Buffer
	4020
	4021	5.6.1 References Sections
	4022	-------------------------
	4023
	4024	The contents of references buffers is controlled using the hook
	4025	‘magit-refs-sections-hook’. See *note Section Hooks:: to learn about
	4026	such hooks and how to customize them. All of the below functions are
	4027	members of the default value. Note that it makes much less sense to
	4028	customize this hook than it does for the respective hook used for the
	4029	status buffer.
	4030
	4031	-- User Option: magit-refs-sections-hook
	4032
	4033	Hook run to insert sections into a references buffer.
	4034
	4035	-- Function: magit-insert-local-branches
	4036
	4037	Insert sections showing all local branches.
	4038
	4039	-- Function: magit-insert-remote-branches
	4040
	4041	Insert sections showing all remote-tracking branches.
	4042
	4043	-- Function: magit-insert-tags
	4044
	4045	Insert sections showing all tags.
	4046
	4047
	4048	File: magit.info, Node: Bisecting, Next: Visiting Blobs, Prev: References Buffer, Up: Inspecting
	4049
	4050	5.7 Bisecting
	4051	=============
	4052
	4053	Also see *note (gitman)git-bisect::.
	4054
	4055	‘B’ (‘magit-bisect-popup’)
	4056
	4057	This prefix command shows the following suffix commands in a popup
	4058	buffer.
	4059
	4060	When bisecting is not in progress, then the popup buffer features the
	4061	following commands.
	4062
	4063	‘B B’ (‘magit-bisect-start’)
	4064
	4065	Start a bisect session.
	4066
	4067	Bisecting a bug means to find the commit that introduced it. This
	4068	command starts such a bisect session by asking for a known good and
	4069	a bad commit.
	4070
	4071	‘B s’ (‘magit-bisect-run’)
	4072
	4073	Bisect automatically by running commands after each step.
	4074
	4075	When bisecting is in progress, then the popup buffer features these
	4076	commands instead.
	4077
	4078	‘B b’ (‘magit-bisect-bad’)
	4079
	4080	Mark the current commit as bad. Use this after you have asserted
	4081	that the commit does contain the bug in question.
	4082
	4083	‘B g’ (‘magit-bisect-good’)
	4084
	4085	Mark the current commit as good. Use this after you have asserted
	4086	that the commit does not contain the bug in question.
	4087
	4088	‘B k’ (‘magit-bisect-skip’)
	4089
	4090	Skip the current commit. Use this if for some reason the current
	4091	commit is not a good one to test. This command lets Git choose a
	4092	different one.
	4093
	4094	‘B r’ (‘magit-bisect-reset’)
	4095
	4096	After bisecting, cleanup bisection state and return to original
	4097	‘HEAD’.
	4098
	4099	By default the status buffer shows information about the ongoing
	4100	bisect session.
	4101
	4102	-- User Option: magit-bisect-show-graph
	4103
	4104	This option controls whether a graph is displayed for the log of
	4105	commits that still have to be bisected.
	4106
	4107
	4108	File: magit.info, Node: Visiting Blobs, Next: Blaming, Prev: Bisecting, Up: Inspecting
	4109
	4110	5.8 Visiting Blobs
	4111	==================
	4112
	4113	‘M-x magit-find-file’ (‘magit-find-file’)
	4114
	4115	View FILE from REV. Switch to a buffer visiting blob REV:FILE,
	4116	creating one if none already exists.
	4117
	4118	‘M-x magit-find-file-other-window’ (‘magit-find-file-other-window’)
	4119
	4120	View FILE from REV, in another window. Like ‘magit-find-file’, but
	4121	create a new window or reuse an existing one.
	4122
	4123
	4124	File: magit.info, Node: Blaming, Prev: Visiting Blobs, Up: Inspecting
	4125
	4126	5.9 Blaming
	4127	===========
	4128
	4129	Also see *note (gitman)git-blame::.
	4130
	4131	To start blaming you can use ‘M-x’ in a file-visiting buffer to
	4132	invoke one of the following commands. You can also invoke these
	4133	commands using the blame popup, which is available on ‘b’ in
	4134	file-visiting buffers that already contain blame information and, also
	4135	on ‘b’, in all blob-visiting buffers. You can also enter the blame
	4136	popup from the file popup, which is available on ‘C-c M-g’, provided
	4137	‘magit-file-mode’ is enabled, see *note Minor Mode for Buffers Visiting
	4138	Files::.
	4139
	4140	-- Command: magit-blame-addition
	4141
	4142	This command augments each line or chunk of lines in the current
	4143	file- or blob-visiting buffer with information about what commits
	4144	last touched these lines.
	4145
	4146	If the buffer visits a revision of that file, then history up to
	4147	that revision is considered. Otherwise, the file’s full history is
	4148	considered, including uncommitted changes.
	4149
	4150	If Magit-Blame mode is already turned on in the current buffer then
	4151	blaming is done recursively, by visiting REVISION:FILE (using
	4152	‘magit-find-file’), where REVISION is a parent of the revision that
	4153	added the current line or chunk of lines.
	4154
	4155	-- Command: magit-blame-echo
	4156
	4157	This command is like ‘magit-blame-addition’ except that it doesn’t
	4158	turn on ‘read-only-mode’ and that it initially uses the
	4159	visualization style specified by option ‘magit-blame-echo-style’.
	4160
	4161	-- Command: magit-blame-removal
	4162
	4163	This command augments each line or chunk of lines in the current
	4164	blob-visiting buffer with information about the revision that
	4165	removes it. It cannot be used in file-visiting buffers.
	4166
	4167	Like ‘magit-blame-addition’, this command can be used recursively.
	4168
	4169	-- Command: magit-blame-reverse
	4170
	4171	This command augments each line or chunk of lines in the current
	4172	file- or blob-visiting buffer with information about the last
	4173	revision in which a line still existed.
	4174
	4175	Like ‘magit-blame-addition’, this command can be used recursively.
	4176
	4177	The following key bindings are available when Magit-Blame mode is
	4178	enabled and Read-Only mode is not enabled. These commands are also
	4179	available in other buffers; here only the behavior is described that is
	4180	relevant in file-visiting buffers that are being blamed.
	4181
	4182	‘RET’ (‘magit-show-commit’)
	4183
	4184	This command shows the commit that last touched the line at point.
	4185
	4186	‘SPC’ (‘magit-diff-show-or-scroll-up’)
	4187
	4188	This command updates the commit buffer.
	4189
	4190	This either shows the commit that last touched the line at point in
	4191	the appropriate buffer, or if that buffer is already being
	4192	displayed in the current frame and if that buffer contains
	4193	information about that commit, then the buffer is scrolled up
	4194	instead.
	4195
	4196	‘DEL’ (‘magit-diff-show-or-scroll-down’)
	4197
	4198	This command updates the commit buffer.
	4199
	4200	This either shows the commit that last touched the line at point in
	4201	the appropriate buffer, or if that buffer is already being
	4202	displayed in the current frame and if that buffer contains
	4203	information about that commit, then the buffer is scrolled down
	4204	instead.
	4205
	4206	The following key bindings are available when Magit-Blame mode is
	4207	enabled and Read-Only mode is not enabled.
	4208
	4209	‘b’ (‘magit-blame-popup’)
	4210
	4211	This prefix command shows the above suffix command along with the
	4212	appropriate infix arguments in a popup buffer.
	4213
	4214	‘n’ (‘magit-blame-next-chunk’)
	4215
	4216	This command moves to the next chunk.
	4217
	4218	‘N’ (‘magit-blame-next-chunk-same-commit’)
	4219
	4220	This command moves to the next chunk from the same commit.
	4221
	4222	‘p’ (‘magit-blame-previous-chunk’)
	4223
	4224	This command moves to the previous chunk.
	4225
	4226	‘P’ (‘magit-blame-previous-chunk-same-commit’)
	4227
	4228	This command moves to the previous chunk from the same commit.
	4229
	4230	‘q’ (‘magit-blame-quit’)
	4231
	4232	This command turns off Magit-Blame mode. If the buffer was created
	4233	during a recursive blame, then it also kills the buffer.
	4234
	4235	‘M-w’ (‘magit-blame-copy-hash’)
	4236
	4237	This command saves the hash of the current chunk’s commit to the
	4238	kill ring.
	4239
	4240	When the region is active, the command saves the region’s content
	4241	instead of the hash, like ‘kill-ring-save’ would.
	4242
	4243	‘c’ (‘magit-blame-cycle-style’)
	4244
	4245	This command changes how blame information is visualized in the
	4246	current buffer by cycling through the styles specified using the
	4247	option ‘magit-blame-styles’.
	4248
	4249	Blaming is also controlled using the following options.
	4250
	4251	-- User Option: magit-blame-styles
	4252
	4253	This option defines a list of styles used to visualize blame
	4254	information. For now see its doc-string to learn more.
	4255
	4256	-- User Option: magit-blame-echo-style
	4257
	4258	This option specifies the blame visualization style used by the
	4259	command ‘magit-blame-echo’. This must be a symbol that is used as
	4260	the identifier for one of the styles defined in
	4261	‘magit-blame-styles’.
	4262
	4263	-- User Option: magit-blame-time-format
	4264
	4265	This option specifies the format string used to display times when
	4266	showing blame information.
	4267
	4268	-- User Option: magit-blame-read-only
	4269
	4270	This option controls whether blaming a buffer also makes
	4271	temporarily read-only.
	4272
	4273	-- User Option: magit-blame-disable-modes
	4274
	4275	This option lists incompatible minor-modes that should be disabled
	4276	temporarily when a buffer contains blame information. They are
	4277	enabled again when the buffer no longer shows blame information.
	4278
	4279	-- User Option: magit-blame-goto-chunk-hook
	4280
	4281	This hook is run when moving between chunks.
	4282
	4283
	4284	File: magit.info, Node: Manipulating, Next: Transferring, Prev: Inspecting, Up: Top
	4285
	4286	6 Manipulating
	4287	**************
	4288
	4289	* Menu:
	4290
	4291	* Repository Setup::
	4292	* Staging and Unstaging::
	4293	* Applying::
	4294	* Committing::
	4295	* Branching::
	4296	* Merging::
	4297	* Resolving Conflicts::
	4298	* Rebasing::
	4299	* Cherry Picking::
	4300	* Resetting::
	4301	* Stashing::
	4302
	4303
	4304	File: magit.info, Node: Repository Setup, Next: Staging and Unstaging, Up: Manipulating
	4305
	4306	6.1 Repository Setup
	4307	====================
	4308
	4309	‘M-x magit-init’ (‘magit-init’)
	4310
	4311	This command initializes a repository and then shows the status
	4312	buffer for the new repository.
	4313
	4314	If the directory is below an existing repository, then the user has
	4315	to confirm that a new one should be created inside. If the
	4316	directory is the root of the existing repository, then the user has
	4317	to confirm that it should be reinitialized.
	4318
	4319	‘M-x magit-clone’ (‘magit-clone’)
	4320
	4321	This command clones a repository and then shows the status buffer
	4322	for the new repository.
	4323
	4324	The user is queried for a remote url and a local directory.
	4325
	4326	-- User Option: magit-clone-set-remote.pushDefault
	4327
	4328	Whether to set the value of ‘remote.pushDefault’ after cloning.
	4329
	4330	If ‘t’, then set without asking. If ‘nil’, then don’t set. If
	4331	‘ask’, then ask the user every time she clones a repository.
	4332
	4333
	4334	File: magit.info, Node: Staging and Unstaging, Next: Applying, Prev: Repository Setup, Up: Manipulating
	4335
	4336	6.2 Staging and Unstaging
	4337	=========================
	4338
	4339	Like Git, Magit can of course stage and unstage complete files. Unlike
	4340	Git, it also allows users to gracefully un-/stage individual hunks and
	4341	even just part of a hunk. To stage individual hunks and parts of hunks
	4342	using Git directly, one has to use the very modal and rather clumsy
	4343	interface of a ‘git add --interactive’ session.
	4344
	4345	With Magit, on the other hand, one can un-/stage individual hunks by
	4346	just moving point into the respective section inside a diff displayed in
	4347	the status buffer or a separate diff buffer and typing ‘s’ or ‘u’. To
	4348	operate on just parts of a hunk, mark the changes that should be
	4349	un-/staged using the region and then press the same key that would be
	4350	used to un-/stage. To stage multiple files or hunks at once use a
	4351	region that starts inside the heading of such a section and ends inside
	4352	the heading of a sibling section of the same type.
	4353
	4354	Besides staging and unstaging, Magit also provides several other
	4355	"apply variants" that can also operate on a file, multiple files at
	4356	once, a hunk, multiple hunks at once, and on parts of a hunk. These
	4357	apply variants are described in the next section.
	4358
	4359	You can also use Ediff to stage and unstage. See *note Ediffing::.
	4360
	4361	‘s’ (‘magit-stage’)
	4362
	4363	Add the change at point to the staging area.
	4364
	4365	With a prefix argument and an untracked file (or files) at point,
	4366	stage the file but not its content. This makes it possible to
	4367	stage only a subset of the new file’s changes.
	4368
	4369	‘S’ (‘magit-stage-modified’)
	4370
	4371	Stage all changes to files modified in the worktree. Stage all new
	4372	content of tracked files and remove tracked files that no longer
	4373	exist in the working tree from the index also. With a prefix
	4374	argument also stage previously untracked (but not ignored) files.
	4375
	4376	‘u’ (‘magit-unstage’)
	4377
	4378	Remove the change at point from the staging area.
	4379
	4380	Only staged changes can be unstaged. But by default this command
	4381	performs an action that is somewhat similar to unstaging, when it
	4382	is called on a committed change: it reverses the change in the
	4383	index but not in the working tree.
	4384
	4385	‘U’ (‘magit-unstage-all’)
	4386
	4387	Remove all changes from the staging area.
	4388
	4389	-- User Option: magit-unstage-committed
	4390
	4391	This option controls whether ‘magit-unstage’ "unstages" committed
	4392	changes by reversing them in the index but not the working tree.
	4393	The alternative is to raise an error.
	4394
	4395	‘M-x magit-reverse-in-index’ (‘magit-reverse-in-index’)
	4396
	4397	This command reverses the committed change at point in the index
	4398	but not the working tree. By default no key is bound directly to
	4399	this command, but it is indirectly called when ‘u’
	4400	(‘magit-unstage’) is pressed on a committed change.
	4401
	4402	This allows extracting a change from ‘HEAD’, while leaving it in
	4403	the working tree, so that it can later be committed using a
	4404	separate commit. A typical workflow would be:
	4405
	4406	• Optionally make sure that there are no uncommitted changes.
	4407
	4408	• Visit the ‘HEAD’ commit and navigate to the change that should
	4409	not have been included in that commit.
	4410
	4411	• Type ‘u’ (‘magit-unstage’) to reverse it in the index. This
	4412	assumes that ‘magit-unstage-committed-changes’ is non-nil.
	4413
	4414	• Type ‘c e’ to extend ‘HEAD’ with the staged changes, including
	4415	those that were already staged before.
	4416
	4417	• Optionally stage the remaining changes using ‘s’ or ‘S’ and
	4418	then type ‘c c’ to create a new commit.
	4419
	4420	‘M-x magit-reset-index’ (‘magit-reset-index’)
	4421
	4422	Reset the index to some commit. The commit is read from the user
	4423	and defaults to the commit at point. If there is no commit at
	4424	point, then it defaults to ‘HEAD’.
	4425
	4426	* Menu:
	4427
	4428	* Staging from File-Visiting Buffers::
	4429
	4430
	4431	File: magit.info, Node: Staging from File-Visiting Buffers, Up: Staging and Unstaging
	4432
	4433	6.2.1 Staging from File-Visiting Buffers
	4434	----------------------------------------
	4435
	4436	Fine-grained un-/staging has to be done from the status or a diff
	4437	buffer, but it’s also possible to un-/stage all changes made to the file
	4438	visited in the current buffer right from inside that buffer.
	4439
	4440	‘M-x magit-stage-file’ (‘magit-stage-file’)
	4441
	4442	When invoked inside a file-visiting buffer, then stage all changes
	4443	to that file. In a Magit buffer, stage the file at point if any.
	4444	Otherwise prompt for a file to be staged. With a prefix argument
	4445	always prompt the user for a file, even in a file-visiting buffer
	4446	or when there is a file section at point.
	4447
	4448	‘M-x magit-unstage-file’ (‘magit-unstage-file’)
	4449
	4450	When invoked inside a file-visiting buffer, then unstage all
	4451	changes to that file. In a Magit buffer, unstage the file at point
	4452	if any. Otherwise prompt for a file to be unstaged. With a prefix
	4453	argument always prompt the user for a file, even in a file-visiting
	4454	buffer or when there is a file section at point.
	4455
	4456
	4457	File: magit.info, Node: Applying, Next: Committing, Prev: Staging and Unstaging, Up: Manipulating
	4458
	4459	6.3 Applying
	4460	============
	4461
	4462	Magit provides several "apply variants": stage, unstage, discard,
	4463	reverse, and "regular apply". At least when operating on a hunk they
	4464	are all implemented using ‘git apply’, which is why they are called
	4465	"apply variants".
	4466
	4467	• Stage. Apply a change from the working tree to the index. The
	4468	change also remains in the working tree.
	4469
	4470	• Unstage. Remove a change from the index. The change remains in
	4471	the working tree.
	4472
	4473	• Discard. On a staged change, remove it from the working tree and
	4474	the index. On an unstaged change, remove it from the working tree
	4475	only.
	4476
	4477	• Reverse. Reverse a change in the working tree. Both committed and
	4478	staged changes can be reversed. Unstaged changes cannot be
	4479	reversed. Discard them instead.
	4480
	4481	• Apply. Apply a change to the working tree. Both committed and
	4482	staged changes can be applied. Unstaged changes cannot be applied
	4483	- as they already have been applied.
	4484
	4485	The previous section described the staging and unstaging commands.
	4486	What follows are the commands which implement the remaining apply
	4487	variants.
	4488
	4489	‘a’ (‘magit-apply’)
	4490
	4491	Apply the change at point to the working tree.
	4492
	4493	With a prefix argument fallback to a 3-way merge. Doing so causes
	4494	the change to be applied to the index as well.
	4495
	4496	‘k’ (‘magit-discard’)
	4497
	4498	Remove the change at point from the working tree.
	4499
	4500	‘v’ (‘magit-reverse’)
	4501
	4502	Reverse the change at point in the working tree.
	4503
	4504	With a prefix argument fallback to a 3-way merge. Doing so causes
	4505	the change to be applied to the index as well.
	4506
	4507	With a prefix argument all apply variants attempt a 3-way merge when
	4508	appropriate (i.e. when ‘git apply’ is used internally).
	4509
	4510
	4511	File: magit.info, Node: Committing, Next: Branching, Prev: Applying, Up: Manipulating
	4512
	4513	6.4 Committing
	4514	==============
	4515
	4516	When the user initiates a commit, Magit calls ‘git commit’ without any
	4517	arguments, so Git has to get it from the user. It creates the file
	4518	‘.git/COMMIT_EDITMSG’ and then opens that file in an editor. Magit
	4519	arranges for that editor to be the Emacsclient. Once the user finishes
	4520	the editing session, the Emacsclient exits and Git creates the commit
	4521	using the file’s content as message.
	4522
	4523	* Menu:
	4524
	4525	* Initiating a Commit::
	4526	* Editing Commit Messages::
	4527
	4528
	4529	File: magit.info, Node: Initiating a Commit, Next: Editing Commit Messages, Up: Committing
	4530
	4531	6.4.1 Initiating a Commit
	4532	-------------------------
	4533
	4534	Also see *note (gitman)git-commit::.
	4535
	4536	‘c’ (‘magit-commit-popup’)
	4537
	4538	This prefix command shows the following suffix commands along with
	4539	the appropriate infix arguments in a popup buffer.
	4540
	4541	‘c c’ (‘magit-commit-create’)
	4542
	4543	Create a new commit on ‘HEAD’. With a prefix argument amend to the
	4544	commit at ‘HEAD’ instead.
	4545
	4546	‘c a’ (‘magit-commit-amend’)
	4547
	4548	Amend the last commit.
	4549
	4550	‘c e’ (‘magit-commit-extend’)
	4551
	4552	Amend the last commit, without editing the message. With a prefix
	4553	argument keep the committer date, otherwise change it. The option
	4554	‘magit-commit-extend-override-date’ can be used to inverse the
	4555	meaning of the prefix argument.
	4556
	4557	Non-interactively respect the optional OVERRIDE-DATE argument and
	4558	ignore the option.
	4559
	4560	‘c w’ (‘magit-commit-reword’)
	4561
	4562	Reword the last commit, ignoring staged changes. With a prefix
	4563	argument keep the committer date, otherwise change it. The option
	4564	‘magit-commit-reword-override-date’ can be used to inverse the
	4565	meaning of the prefix argument.
	4566
	4567	Non-interactively respect the optional OVERRIDE-DATE argument and
	4568	ignore the option.
	4569
	4570	‘c f’ (‘magit-commit-fixup’)
	4571
	4572	Create a fixup commit.
	4573
	4574	With a prefix argument the target commit has to be confirmed.
	4575	Otherwise the commit at point may be used without confirmation
	4576	depending on the value of option ‘magit-commit-squash-confirm’.
	4577
	4578	‘c F’ (‘magit-commit-instant-fixup’)
	4579
	4580	Create a fixup commit and instantly rebase.
	4581
	4582	‘c s’ (‘magit-commit-squash’)
	4583
	4584	Create a squash commit, without editing the squash message.
	4585
	4586	With a prefix argument the target commit has to be confirmed.
	4587	Otherwise the commit at point may be used without confirmation
	4588	depending on the value of option ‘magit-commit-squash-confirm’.
	4589
	4590	‘c S’ (‘magit-commit-instant-squash’)
	4591
	4592	Create a squash commit and instantly rebase.
	4593
	4594	‘c A’ (‘magit-commit-augment’)
	4595
	4596	Create a squash commit, editing the squash message.
	4597
	4598	With a prefix argument the target commit has to be confirmed.
	4599	Otherwise the commit at point may be used without confirmation
	4600	depending on the value of option ‘magit-commit-squash-confirm’.
	4601
	4602	-- User Option: magit-commit-ask-to-stage
	4603
	4604	Whether to ask to stage all unstaged changes when committing and
	4605	nothing is staged.
	4606
	4607	-- User Option: magit-commit-extend-override-date
	4608
	4609	Whether using ‘magit-commit-extend’ changes the committer date.
	4610
	4611	-- User Option: magit-commit-reword-override-date
	4612
	4613	Whether using ‘magit-commit-reword’ changes the committer date.
	4614
	4615	-- User Option: magit-commit-squash-confirm
	4616
	4617	Whether the commit targeted by squash and fixup has to be
	4618	confirmed. When non-nil then the commit at point (if any) is used
	4619	as default choice. Otherwise it has to be confirmed. This option
	4620	only affects ‘magit-commit-squash’ and ‘magit-commit-fixup’. The
	4621	"instant" variants always require confirmation because making an
	4622	error while using those is harder to recover from.
	4623
	4624
	4625	File: magit.info, Node: Editing Commit Messages, Prev: Initiating a Commit, Up: Committing
	4626
	4627	6.4.2 Editing Commit Messages
	4628	-----------------------------
	4629
	4630	After initiating a commit as described in the previous section, two new
	4631	buffers appear. One shows the changes that are about to committed,
	4632	while the other is used to write the message. All regular editing
	4633	commands are available in the commit message buffer. This section only
	4634	describes the additional commands.
	4635
	4636	Commit messages are edited in an edit session - in the background Git
	4637	is waiting for the editor, in our case the Emacsclient, to save the
	4638	commit message in a file (in most cases ‘.git/COMMIT_EDITMSG’) and then
	4639	return. If the Emacsclient returns with a non-zero exit status then Git
	4640	does not create the commit. So the most important commands are those
	4641	for finishing and aborting the commit.
	4642
	4643	‘C-c C-c’ (‘with-editor-finish’)
	4644
	4645	Finish the current editing session by returning with exit code 0.
	4646	Git then creates the commit using the message it finds in the file.
	4647
	4648	‘C-c C-k’ (‘with-editor-cancel’)
	4649
	4650	Cancel the current editing session by returning with exit code 1.
	4651	Git then cancels the commit, but leaves the file untouched.
	4652
	4653	In addition to being used by Git, these messages may also be stored
	4654	in a ring that persists until Emacs is closed. By default the message
	4655	is stored at the beginning and the end of an edit session (regardless of
	4656	whether the session is finished successfully or was canceled). It is
	4657	sometimes useful to bring back messages from that ring.
	4658
	4659	‘C-c M-s’ (‘git-commit-save-message’)
	4660
	4661	Save the current buffer content to the commit message ring.
	4662
	4663	‘M-p’ (‘git-commit-prev-message’)
	4664
	4665	Cycle backward through the commit message ring, after saving the
	4666	current message to the ring. With a numeric prefix ARG, go back
	4667	ARG comments.
	4668
	4669	‘M-n’ (‘git-commit-next-message’)
	4670
	4671	Cycle forward through the commit message ring, after saving the
	4672	current message to the ring. With a numeric prefix ARG, go back
	4673	ARG comments.
	4674
	4675	By default the diff for the changes that are about to be committed
	4676	are automatically shown when invoking the commit. When amending to an
	4677	existing commit it may be useful to show either the changes that are
	4678	about to be added to that commit or to show those changes together with
	4679	those that are already committed.
	4680
	4681	‘C-c C-d’ (‘magit-diff-while-committing’)
	4682
	4683	While committing, show the changes that are about to be committed.
	4684	While amending, invoking the command again toggles between showing
	4685	just the new changes or all the changes that will be committed.
	4686
	4687	‘C-c C-w’ (‘magit-pop-revision-stack’)
	4688
	4689	This command inserts a representation of a revision into the
	4690	current buffer. It can be used inside buffers used to write commit
	4691	messages but also in other buffers such as buffers used to edit
	4692	emails or ChangeLog files.
	4693
	4694	By default this command pops the revision which was last added to
	4695	the ‘magit-revision-stack’ and inserts it into the current buffer
	4696	according to ‘magit-pop-revision-stack-format’. Revisions can be
	4697	put on the stack using ‘magit-copy-section-value’ and
	4698	‘magit-copy-buffer-revision’.
	4699
	4700	If the stack is empty or with a prefix argument it instead reads a
	4701	revision in the minibuffer. By using the minibuffer history this
	4702	allows selecting an item which was popped earlier or to insert an
	4703	arbitrary reference or revision without first pushing it onto the
	4704	stack.
	4705
	4706	When reading the revision from the minibuffer, then it might not be
	4707	possible to guess the correct repository. When this command is
	4708	called inside a repository (e.g. while composing a commit
	4709	message), then that repository is used. Otherwise (e.g. while
	4710	composing an email) then the repository recorded for the top
	4711	element of the stack is used (even though we insert another
	4712	revision). If not called inside a repository and with an empty
	4713	stack, or with two prefix arguments, then read the repository in
	4714	the minibuffer too.
	4715
	4716	-- User Option: magit-pop-revision-stack-format
	4717
	4718	This option controls how the command ‘magit-pop-revision-stack’
	4719	inserts a revision into the current buffer.
	4720
	4721	The entries on the stack have the format ‘(HASH TOPLEVEL)’ and this
	4722	option has the format ‘(POINT-FORMAT EOB-FORMAT INDEX-REGEXP)’, all
	4723	of which may be nil or a string (though either one of EOB-FORMAT or
	4724	POINT-FORMAT should be a string, and if INDEX-REGEXP is non-nil,
	4725	then the two formats should be too).
	4726
	4727	First INDEX-REGEXP is used to find the previously inserted entry,
	4728	by searching backward from point. The first submatch must match
	4729	the index number. That number is incremented by one, and becomes
	4730	the index number of the entry to be inserted. If you don’t want to
	4731	number the inserted revisions, then use nil for INDEX-REGEXP.
	4732
	4733	If INDEX-REGEXP is non-nil then both POINT-FORMAT and EOB-FORMAT
	4734	should contain \"%N\", which is replaced with the number that was
	4735	determined in the previous step.
	4736
	4737	Both formats, if non-nil and after removing %N, are then expanded
	4738	using ‘git show –format=FORMAT ...’ inside TOPLEVEL.
	4739
	4740	The expansion of POINT-FORMAT is inserted at point, and the
	4741	expansion of EOB-FORMAT is inserted at the end of the buffer (if
	4742	the buffer ends with a comment, then it is inserted right before
	4743	that).
	4744
	4745	Some projects use pseudo headers in commit messages. Magit colorizes
	4746	such headers and provides some commands to insert such headers.
	4747
	4748	-- User Option: git-commit-known-pseudo-headers
	4749
	4750	A list of Git pseudo headers to be highlighted.
	4751
	4752	‘C-c C-a’ (‘git-commit-ack’)
	4753
	4754	Insert a header acknowledging that you have looked at the commit.
	4755
	4756	‘C-c C-r’ (‘git-commit-review’)
	4757
	4758	Insert a header acknowledging that you have reviewed the commit.
	4759
	4760	‘C-c C-s’ (‘git-commit-signoff’)
	4761
	4762	Insert a header to sign off the commit.
	4763
	4764	‘C-c C-t’ (‘git-commit-test’)
	4765
	4766	Insert a header acknowledging that you have tested the commit.
	4767
	4768	‘C-c C-o’ (‘git-commit-cc’)
	4769
	4770	Insert a header mentioning someone who might be interested.
	4771
	4772	‘C-c C-p’ (‘git-commit-reported’)
	4773
	4774	Insert a header mentioning the person who reported the issue being
	4775	fixed by the commit.
	4776
	4777	‘C-c C-i’ (‘git-commit-suggested’)
	4778
	4779	Insert a header mentioning the person who suggested the change.
	4780
	4781	‘git-commit-mode’ is a minor mode that is only used to establish the
	4782	above key bindings. This allows using an arbitrary major mode when
	4783	editing the commit message. It’s even possible to use a different major
	4784	mode in different repositories, which is useful when different projects
	4785	impose different commit message conventions.
	4786
	4787	-- User Option: git-commit-major-mode
	4788
	4789	The value of this option is the major mode used to edit Git commit
	4790	messages.
	4791
	4792	Because ‘git-commit-mode’ is a minor mode, we don’t use its mode hook
	4793	to setup the buffer, except for the key bindings. All other setup
	4794	happens in the function ‘git-commit-setup’, which among other things
	4795	runs the hook ‘git-commit-setup-hook’. The following functions are
	4796	suitable for that hook.
	4797
	4798	-- User Option: git-commit-setup-hook
	4799
	4800	Hook run at the end of ‘git-commit-setup’.
	4801
	4802	-- Function: magit-revert-buffers &optional force
	4803
	4804	Revert unmodified file-visiting buffers of the current repository.
	4805
	4806	If either ‘magit-revert-buffers’ is non-nil and
	4807	‘inhibit-magit-revert’ is nil, or if optional FORCE is non-nil,
	4808	then revert all unmodified buffers that visit files being tracked
	4809	in the current repository.
	4810
	4811	-- Function: git-commit-save-message
	4812
	4813	Save the current buffer content to the commit message ring.
	4814
	4815	-- Function: git-commit-setup-changelog-support
	4816
	4817	After this function is called, ChangeLog entries are treated as
	4818	paragraphs.
	4819
	4820	-- Function: git-commit-turn-on-auto-fill
	4821
	4822	Turn on ‘auto-fill-mode’ and set ‘fill-column’ to the value of
	4823	‘git-commit-fill-column’.
	4824
	4825	-- Function: git-commit-turn-on-flyspell
	4826
	4827	Turn on Flyspell mode. Also prevent comments from being checked
	4828	and finally check current non-comment text.
	4829
	4830	-- Function: git-commit-propertize-diff
	4831
	4832	Propertize the diff shown inside the commit message buffer. Git
	4833	inserts such diffs into the commit message template when the
	4834	‘--verbose’ argument is used. Magit’s commit popup by default does
	4835	not offer that argument because the diff that is shown in a
	4836	separate buffer is more useful. But some users disagree, which is
	4837	why this function exists.
	4838
	4839	-- Function: with-editor-usage-message
	4840
	4841	Show usage information in the echo area.
	4842
	4843	Magit also helps with writing good commit messages by complaining
	4844	when certain rules are violated.
	4845
	4846	-- User Option: git-commit-summary-max-length
	4847
	4848	The intended maximal length of the summary line of commit messages.
	4849	Characters beyond this column are colorized to indicate that this
	4850	preference has been violated.
	4851
	4852	-- User Option: git-commit-fill-column
	4853
	4854	Column beyond which automatic line-wrapping should happen in commit
	4855	message buffers.
	4856
	4857	-- User Option: git-commit-finish-query-functions
	4858
	4859	List of functions called to query before performing commit.
	4860
	4861	The commit message buffer is current while the functions are
	4862	called. If any of them returns nil, then the commit is not
	4863	performed and the buffer is not killed. The user should then fix
	4864	the issue and try again.
	4865
	4866	The functions are called with one argument. If it is non-nil then
	4867	that indicates that the user used a prefix argument to force
	4868	finishing the session despite issues. Functions should usually
	4869	honor this wish and return non-nil.
	4870
	4871	-- Function: git-commit-check-style-conventions
	4872
	4873	Check for violations of certain basic style conventions. For each
	4874	violation ask the user if she wants to proceed anyway. This makes
	4875	sure the summary line isn’t too long and that the second line is
	4876	empty.
	4877
	4878	To show no diff while committing remove ‘magit-commit-diff’ from
	4879	‘server-switch-hook’.
	4880
	4881
	4882	File: magit.info, Node: Branching, Next: Merging, Prev: Committing, Up: Manipulating
	4883
	4884	6.5 Branching
	4885	=============
	4886
	4887	* Menu:
	4888
	4889	* The Two Remotes::
	4890	* The Branch Popup::
	4891	* The Branch Config Popup::
	4892	* Auxiliary Branch Commands::
	4893
	4894
	4895	File: magit.info, Node: The Two Remotes, Next: The Branch Popup, Up: Branching
	4896
	4897	6.5.1 The Two Remotes
	4898	---------------------
	4899
	4900	The upstream branch of some local branch is the branch into which the
	4901	commits on that local branch should eventually be merged, usually
	4902	something like ‘origin/master’. For the ‘master’ branch itself the
	4903	upstream branch and the branch it is being pushed to, are usually the
	4904	same remote branch. But for a feature branch the upstream branch and
	4905	the branch it is being pushed to should differ.
	4906
	4907	The commits on feature branches too should _eventually_ end up in a
	4908	remote branch such as ‘origin/master’ or ‘origin/maint’. Such a branch
	4909	should therefore be used as the upstream. But feature branches
	4910	shouldn’t be pushed directly to such branches. Instead a feature branch
	4911	‘my-feature’ is usually pushed to ‘my-fork/my-feature’ or if you are a
	4912	contributor ‘origin/my-feature’. After the new feature has been
	4913	reviewed, the maintainer merges the feature into ‘master’. And finally
	4914	‘master’ (not ‘my-feature’ itself) is pushed to ‘origin/master’.
	4915
	4916	But new features seldom are perfect on the first try, and so feature
	4917	branches usually have to be reviewed, improved, and re-pushed several
	4918	times. Pushing should therefore be easy to do, and for that reason many
	4919	Git users have concluded that it is best to use the remote branch to
	4920	which the local feature branch is being pushed as its upstream.
	4921
	4922	But luckily Git has long ago gained support for a push-remote which
	4923	can be configured separately from the upstream branch, using the
	4924	variables ‘branch.<name>.pushRemote’ and ‘remote.pushDefault’. So we no
	4925	longer have to choose which of the two remotes should be used as "the
	4926	remote".
	4927
	4928	Each of the fetching, pulling, and pushing popups features three
	4929	commands that act on the current branch and some other branch. Of
	4930	these, ‘p’ is bound to a command which acts on the push-remote, ‘u’ is
	4931	bound to a command which acts on the upstream, and ‘e’ is bound to a
	4932	command which acts on any other branch. The status buffer shows
	4933	unpushed and unpulled commits for both the push-remote and the upstream.
	4934
	4935	It’s fairly simple to configure these two remotes. The values of all
	4936	the variables that are related to fetching, pulling, and pushing (as
	4937	well as some other branch-related variables) can be inspected and
	4938	changed using the popup ‘magit-branch-config-popup’, which is a
	4939	sub-popup of many popups that deal with branches. It is also possible
	4940	to set the push-remote or upstream while pushing (see *note Pushing::).
	4941
	4942
	4943	File: magit.info, Node: The Branch Popup, Next: The Branch Config Popup, Prev: The Two Remotes, Up: Branching
	4944
	4945	6.5.2 The Branch Popup
	4946	----------------------
	4947
	4948	The popup ‘magit-branch-popup’ is used to create and checkout branches,
	4949	and to make changes to existing branches. It is not used to fetch,
	4950	pull, merge, rebase, or push branches, i.e. this popup deals with
	4951	branches themselves, not with the commits reachable from them. Those
	4952	features are available from separate popups.
	4953
	4954	‘b’ (‘magit-branch-popup’)
	4955
	4956	This prefix command shows the following suffix commands in a popup
	4957	buffer.
	4958
	4959	By default it also displays the values of some branch-related Git
	4960	variables and allows changing their values, just like the
	4961	specialized ‘magit-branch-config-popup’ does.
	4962
	4963	-- User Option: magit-branch-popup-show-variables
	4964
	4965	Whether the ‘magit-branch-popup’ shows Git variables. This
	4966	defaults to t to avoid changing key bindings. When set to nil, no
	4967	variables are displayed directly in this popup, and the sub-popup
	4968	‘magit-branch-config-popup’ has to be used instead to view and
	4969	change branch related variables.
	4970
	4971	‘b C’ (‘magit-branch-config-popup’)
	4972
	4973	This command shows branch related variables in a separate popup.
	4974	By default this asks the user for which branch the variables should
	4975	be shown. When ‘magit-branch-popup-show-variables’ is ‘nil’, then
	4976	it shows the variables for the current branch, unless a prefix
	4977	argument is used.
	4978
	4979	‘b b’ (‘magit-checkout’)
	4980
	4981	Checkout a revision read in the minibuffer and defaulting to the
	4982	branch or arbitrary revision at point. If the revision is a local
	4983	branch then that becomes the current branch. If it is something
	4984	else then ‘HEAD’ becomes detached. Checkout fails if the working
	4985	tree or the staging area contain changes.
	4986
	4987	‘b n’ (‘magit-branch-create’)
	4988
	4989	Create a new branch. The user is asked for a branch or arbitrary
	4990	revision to use as the starting point of the new branch. When a
	4991	branch name is provided, then that becomes the upstream branch of
	4992	the new branch. The name of the new branch is also read in the
	4993	minibuffer.
	4994
	4995	Also see option ‘magit-branch-prefer-remote-upstream’.
	4996
	4997	‘b c’ (‘magit-branch-and-checkout’)
	4998
	4999	This command creates a new branch like ‘magit-branch’, but then
	5000	also checks it out.
	5001
	5002	Also see option ‘magit-branch-prefer-remote-upstream’.
	5003
	5004	‘b l’ (‘magit-branch-checkout’)
	5005
	5006	This command checks out an existing or new local branch. It reads
	5007	a branch name from the user offering all local branches and a
	5008	subset of remote branches as candidates. Remote branches for which
	5009	a local branch by the same name exists are omitted from the list of
	5010	candidates. The user can also enter a completely new branch name.
	5011
	5012	• If the user selects an existing local branch, then that is
	5013	checked out.
	5014
	5015	• If the user selects a remote branch, then it creates and
	5016	checks out a new local branch with the same name, and
	5017	configures the selected remote branch as the push target.
	5018
	5019	• If the user enters a new branch name, then it creates and
	5020	checks that out, after also reading the starting-point from
	5021	the user.
	5022
	5023	In the latter two cases the upstream is also set. Whether it is
	5024	set to the chosen starting point or something else depends on the
	5025	value of ‘magit-branch-adjust-remote-upstream-alist’.
	5026
	5027	‘b s’ (‘magit-branch-spinoff’)
	5028
	5029	This command creates and checks out a new branch starting at and
	5030	tracking the current branch. That branch in turn is reset to the
	5031	last commit it shares with its upstream. If the current branch has
	5032	no upstream or no unpushed commits, then the new branch is created
	5033	anyway and the previously current branch is not touched.
	5034
	5035	This is useful to create a feature branch after work has already
	5036	began on the old branch (likely but not necessarily "master").
	5037
	5038	If the current branch is a member of the value of option
	5039	‘magit-branch-prefer-remote-upstream’ (which see), then the current
	5040	branch will be used as the starting point as usual, but the
	5041	upstream of the starting-point may be used as the upstream of the
	5042	new branch, instead of the starting-point itself.
	5043
	5044	If optional FROM is non-nil, then the source branch is reset to
	5045	‘FROM~’, instead of to the last commit it shares with its upstream.
	5046	Interactively, FROM is only ever non-nil, if the region selects
	5047	some commits, and among those commits, FROM is the commit that is
	5048	the fewest commits ahead of the source branch.
	5049
	5050	The commit at the other end of the selection actually does not
	5051	matter, all commits between FROM and ‘HEAD’ are moved to the new
	5052	branch. If FROM is not reachable from ‘HEAD’ or is reachable from
	5053	the source branch’s upstream, then an error is raised.
	5054
	5055	‘b Y’ (‘magit-branch-pull-request’)
	5056
	5057	This command creates and configures a new branch from a Github
	5058	pull-request, creating and configuring a new remote if necessary.
	5059
	5060	The name of the local branch is the same as the name of the remote
	5061	branch that you are being asked to merge, unless the contributor
	5062	could not be bother to properly name the branch before opening the
	5063	pull-request. The most likely such case is when you are being
	5064	asked to merge something like "fork/master" into "origin/master".
	5065	In such cases the local branch will be named "pr-N", where ‘N’ is
	5066	the pull-request number.
	5067
	5068	These variables are always set by this command:
	5069
	5070	• ‘branch.<name>.pullRequest’ is set to the pull-request number.
	5071
	5072	• ‘branch.<name>.pullRequestRemote’ is set to the remote on
	5073	which the pull-request branch is located.
	5074
	5075	• ‘branch.<name>.pushRemote’ is set to the same remote as
	5076	‘branch.<name>.pullRequestRemote’ if that is possible,
	5077	otherwise it is set to the upstream remote.
	5078
	5079	• ‘branch.<name>.description’ is set to the pull-request title.
	5080
	5081	• ‘branch.<name>.rebase’ is set to ‘true’ because there should
	5082	be no merge commits among the commits in a pull-request.
	5083
	5084	This command also configures the upstream and the push-remote of
	5085	the local branch that it creates.
	5086
	5087	The branch against which the pull-request was opened, is always
	5088	used as the upstream. This makes it easy to see what commits you
	5089	are being asked to merge in the section titled something like
	5090	"Unmerged into origin/master".
	5091
	5092	Like for other commands that create a branch it depends on the
	5093	option ‘magit-branch-prefer-remote-upstream’ whether the remote
	5094	branch itself or the respective local branch is used as the
	5095	upstream, so this section may also be titled e.g. "Unmerged into
	5096	master".
	5097
	5098	When necessary and possible, then the remote pull-request branch is
	5099	configured to be used as the push-target. This makes it easy to
	5100	see what further changes the contributor has made since you last
	5101	reviewed their changes in the section titled something like
	5102	"Unpulled from origin/new-feature" or "Unpulled from
	5103	fork/new-feature".
	5104
	5105	• If the pull-request branch is located in the upstream
	5106	repository, then you probably have set ‘remote.pushDefault’ to
	5107	that repository. However some users like to set that variable
	5108	to their personal fork, even if they have push access to the
	5109	upstream, so ‘branch.<name>.pushRemote’ is set anyway.
	5110
	5111	• If the pull-request branch is located inside a fork, then you
	5112	are usually able to push to that branch, because Github by
	5113	default allows the recipient of a pull-request to push to the
	5114	remote pull-request branch even if it is located in a fork.
	5115	The contributor has to explicitly disable this.
	5116
	5117	• If you are not allowed to push to the pull-request branch
	5118	on the fork, then a branch by the same name located in
	5119	the upstream repository is configured as the push-target.
	5120
	5121	• A — sadly rather common — special case is when the
	5122	contributor didn’t bother to use a dedicated branch for
	5123	the pull-request.
	5124
	5125	The most likely such case is when you are being asked to
	5126	merge something like "fork/master" into "origin/master".
	5127	The special push permission mentioned above is never
	5128	granted for the branch that is the repository’s default
	5129	branch, and that would almost certainly be the case in
	5130	this scenario.
	5131
	5132	To enable you to easily push somewhere anyway, the local
	5133	branch is named "pr-N" (where ‘N’ is the pull-request
	5134	number) and the upstream repository is used as the
	5135	push-remote.
	5136
	5137	• Finally, if you are allowed to push to the pull-request
	5138	branch and the contributor had the foresight to use a
	5139	dedicated branch, then the fork is configured as the
	5140	push-remote.
	5141
	5142	The push-remote is configured using
	5143	‘branch.<name>.pushRemote’, even if the used value is
	5144	identical to that of ‘remote.pushDefault’, just in case you
	5145	change the value of the latter later on. Additionally the
	5146	variable ‘branch.<name>.pullRequestRemote’ is set to the
	5147	remote on which the pull-request branch is located.
	5148
	5149	When you later delete the local pull-request branch, then you are
	5150	offered to also delete the corresponding remote, provided it is not
	5151	the upstream remote and that the tracking branch that corresponds
	5152	to the deleted branch is the only remaining tracked branch. If you
	5153	don’t confirm, then only the tracking branch itself is deleted in
	5154	addition to the local branch.
	5155
	5156	Do not delete the tracking branch instead of the local branch. The
	5157	cleanup mentioned in the previous paragraph is not performed if you
	5158	do that.
	5159
	5160	‘b y’ (‘magit-checkout-pull-request’)
	5161
	5162	This command creates and configures a new branch from a pull
	5163	request, the same way ‘magit-branch-pull-request’ does.
	5164	Additionally it checks out the new branch.
	5165
	5166	‘b x’ (‘magit-branch-reset’)
	5167
	5168	This command resets a branch, defaulting to the branch at point, to
	5169	the tip of another branch or any other commit.
	5170
	5171	When the branch being reset is the current branch, then a hard
	5172	reset is performed. If there are any uncommitted changes, then the
	5173	user has to confirm the reset because those changes would be lost.
	5174
	5175	This is useful when you have started work on a feature branch but
	5176	realize it’s all crap and want to start over.
	5177
	5178	When resetting to another branch and a prefix argument is used,
	5179	then the target branch is set as the upstream of the branch that is
	5180	being reset.
	5181
	5182	‘b k’ (‘magit-branch-delete’)
	5183
	5184	Delete one or multiple branches. If the region marks multiple
	5185	branches, then offer to delete those. Otherwise, prompt for a
	5186	single branch to be deleted, defaulting to the branch at point.
	5187
	5188	‘b r’ (‘magit-branch-rename’)
	5189
	5190	Rename a branch. The branch and the new name are read in the
	5191	minibuffer. With prefix argument the branch is renamed even if
	5192	that name conflicts with an existing branch.
	5193
	5194	-- User Option: magit-branch-read-upstream-first
	5195
	5196	When creating a branch, whether to read the upstream branch before
	5197	the name of the branch that is to be created. The default is
	5198	‘nil’, and I recommend you leave it at that.
	5199
	5200	-- User Option: magit-branch-prefer-remote-upstream
	5201
	5202	This option specifies whether remote upstreams are favored over
	5203	local upstreams when creating new branches.
	5204
	5205	When a new branch is created, then the branch, commit, or stash at
	5206	point is suggested as the starting point of the new branch, or if
	5207	there is no such revision at point the current branch. In either
	5208	case the user may choose another starting point.
	5209
	5210	If the chosen starting point is a branch, then it may also be set
	5211	as the upstream of the new branch, depending on the value of the
	5212	Git variable ‘branch.autoSetupMerge’. By default this is done for
	5213	remote branches, but not for local branches.
	5214
	5215	You might prefer to always use some remote branch as upstream. If
	5216	the chosen starting point is (1) a local branch, (2) whose name
	5217	matches a member of the value of this option, (3) the upstream of
	5218	that local branch is a remote branch with the same name, and (4)
	5219	that remote branch can be fast-forwarded to the local branch, then
	5220	the chosen branch is used as starting point, but its own upstream
	5221	is used as the upstream of the new branch.
	5222
	5223	Members of this option’s value are treated as branch names that
	5224	have to match exactly unless they contain a character that makes
	5225	them invalid as a branch name. Recommended characters to use to
	5226	trigger interpretation as a regexp are "*" and "^". Some other
	5227	characters which you might expect to be invalid, actually are not,
	5228	e.g. ".+$" are all perfectly valid. More precisely, if ‘git
	5229	check-ref-format –branch STRING’ exits with a non-zero status, then
	5230	treat STRING as a regexp.
	5231
	5232	Assuming the chosen branch matches these conditions you would end
	5233	up with with e.g.:
	5234
	5235	feature --upstream--> origin/master
	5236
	5237	instead of
	5238
	5239	feature --upstream--> master --upstream--> origin/master
	5240
	5241	Which you prefer is a matter of personal preference. If you do
	5242	prefer the former, then you should add branches such as ‘master’,
	5243	‘next’, and ‘maint’ to the value of this options.
	5244
	5245	-- User Option: magit-branch-adjust-remote-upstream-alist
	5246
	5247	The value of this option is an alist of branches to be used as the
	5248	upstream when branching a remote branch.
	5249
	5250	When creating a local branch from an ephemeral branch located on a
	5251	remote, e.g. a feature or hotfix branch, then that remote branch
	5252	should usually not be used as the upstream branch, since the
	5253	push-remote already allows accessing it and having both the
	5254	upstream and the push-remote reference the same related branch
	5255	would be wasteful. Instead a branch like "maint" or "master"
	5256	should be used as the upstream.
	5257
	5258	This option allows specifying the branch that should be used as the
	5259	upstream when branching certain remote branches. The value is an
	5260	alist of the form ‘((UPSTREAM . RULE)...)’. The first matching
	5261	element is used, the following elements are ignored.
	5262
	5263	UPSTREAM is the branch to be used as the upstream for branches
	5264	specified by RULE. It can be a local or a remote branch.
	5265
	5266	RULE can either be a regular expression, matching branches whose
	5267	upstream should be the one specified by UPSTREAM. Or it can be a
	5268	list of the only branches that should not use UPSTREAM; all other
	5269	branches will. Matching is done after stripping the remote part of
	5270	the name of the branch that is being branched from.
	5271
	5272	If you use a finite set of non-ephemeral branches across all your
	5273	repositories, then you might use something like:
	5274
	5275	(("origin/master" "master" "next" "maint"))
	5276
	5277	Or if the names of all your ephemeral branches contain a slash, at
	5278	least in some repositories, then a good value could be:
	5279
	5280	(("origin/master" . "/"))
	5281
	5282	Of course you can also fine-tune:
	5283
	5284	(("origin/maint" . "\\`hotfix/")
	5285	("origin/master" . "\\`feature/"))
	5286
	5287	-- Command: magit-branch-orphan
	5288
	5289	This command creates and checks out a new orphan branch with
	5290	contents from a given revision.
	5291
	5292	-- Command: magit-branch-or-checkout
	5293
	5294	This command is a hybrid between ‘magit-checkout’ and
	5295	‘magit-branch-and-checkout’ and is intended as a replacement for
	5296	the former in ‘magit-branch-popup’.
	5297
	5298	It first asks the user for an existing branch or revision. If the
	5299	user input actually can be resolved as a branch or revision, then
	5300	it checks that out, just like ‘magit-checkout’ would.
	5301
	5302	Otherwise it creates and checks out a new branch using the input as
	5303	its name. Before doing so it reads the starting-point for the new
	5304	branch. This is similar to what ‘magit-branch-and-checkout’ does.
	5305
	5306	To use this command instead of ‘magit-checkout’ add this to your
	5307	init file:
	5308
	5309	(magit-remove-popup-key 'magit-branch-popup :action ?b)
	5310	(magit-define-popup-action 'magit-branch-popup
	5311	?b "Checkout" 'magit-branch-or-checkout
	5312	'magit-branch t)
	5313
	5314
	5315	File: magit.info, Node: The Branch Config Popup, Next: Auxiliary Branch Commands, Prev: The Branch Popup, Up: Branching
	5316
	5317	6.5.3 The Branch Config Popup
	5318	-----------------------------
	5319
	5320	-- Command: magit-branch-config-popup
	5321
	5322	This prefix command shows the following branch-related Git
	5323	variables in a popup buffer. The values can be changed from that
	5324	buffer.
	5325
	5326	This popup is a sub-popup of several popups that deal with
	5327	branches, including ‘magit-branch-popup’, ‘magit-pull-popup’,
	5328	‘magit-fetch-popup’, ‘magit-pull-and-fetch-popup’, and
	5329	‘magit-push-popup’. In all of these popups "C" is bound to this
	5330	popup.
	5331
	5332	The following variables are used to configure a specific branch. The
	5333	values are being displayed for the current branch (if any). To change
	5334	the value for another branch invoke ‘magit-branch-config-popup’ with a
	5335	prefix argument.
	5336
	5337	-- Variable: branch.NAME.merge
	5338
	5339	Together with ‘branch.NAME.remote’ this variable defines the
	5340	upstream branch of the local branch named NAME. The value of this
	5341	variable is the full reference of the upstream _branch_.
	5342
	5343	-- Variable: branch.NAME.remote
	5344
	5345	Together with ‘branch.NAME.merge’ this variable defines the
	5346	upstream branch of the local branch named NAME. The value of this
	5347	variable is the name of the upstream _remote_.
	5348
	5349	-- Variable: branch.NAME.rebase
	5350
	5351	This variable controls whether pulling into the branch named NAME
	5352	is done by rebasing or by merging the fetched branch.
	5353
	5354	• When ‘true’ then pulling is done by rebasing.
	5355
	5356	• When ‘false’ then pulling is done by merging.
	5357
	5358	• When undefined then the value of ‘pull.rebase’ is used. The
	5359	default of that variable is ‘false’.
	5360
	5361	-- Variable: branch.NAME.pushRemote
	5362
	5363	This variable specifies the remote that the branch named NAME is
	5364	usually pushed to. The value has to be the name of an existing
	5365	remote.
	5366
	5367	It is not possible to specify the name of _branch_ to push the
	5368	local branch to. The name of the remote branch is always the same
	5369	as the name of the local branch.
	5370
	5371	If this variable is undefined but ‘remote.pushDefault’ is defined,
	5372	then the value of the latter is used. By default
	5373	‘remote.pushDefault’ is undefined.
	5374
	5375	-- Variable: branch.NAME.description
	5376
	5377	This variable can be used to describe the branch named NAME. That
	5378	description is used e.g. when turning the branch into a series of
	5379	patches.
	5380
	5381	The following variables specify defaults which are used if the above
	5382	branch-specific variables are not set.
	5383
	5384	-- Variable: pull.rebase
	5385
	5386	This variable specifies whether pulling is done by rebasing or by
	5387	merging. It can be overwritten using ‘branch.NAME.rebase’.
	5388
	5389	• When ‘true’ then pulling is done by rebasing.
	5390
	5391	• When ‘false’ (the default) then pulling is done by merging.
	5392
	5393	Since it is never a good idea to merge the upstream branch into a
	5394	feature or hotfix branch and most branches are such branches, you
	5395	should consider setting this to ‘true’, and ‘branch.master.rebase’
	5396	to ‘false’.
	5397
	5398	-- Variable: remote.pushDefault
	5399
	5400	This variable specifies what remote the local branches are usually
	5401	pushed to. This can be overwritten per branch using
	5402	‘branch.NAME.pushRemote’.
	5403
	5404	The following variables are used during the creation of a branch and
	5405	control whether the various branch-specific variables are automatically
	5406	set at this time.
	5407
	5408	-- Variable: branch.autoSetupMerge
	5409
	5410	This variable specifies under what circumstances creating a branch
	5411	NAME should result in the variables ‘branch.NAME.merge’ and
	5412	‘branch.NAME.remote’ being set according to the starting point used
	5413	to create the branch. If the starting point isn’t a branch, then
	5414	these variables are never set.
	5415
	5416	• When ‘always’ then the variables are set regardless of whether
	5417	the starting point is a local or a remote branch.
	5418
	5419	• When ‘true’ (the default) then the variables are set when the
	5420	starting point is a remote branch, but not when it is a local
	5421	branch.
	5422
	5423	• When ‘false’ then the variables are never set.
	5424
	5425	-- Variable: branch.autoSetupRebase
	5426
	5427	This variable specifies whether creating a branch NAME should
	5428	result in the variable ‘branch.NAME.rebase’ being set to ‘true’.
	5429
	5430	• When ‘always’ then the variable is set regardless of whether
	5431	the starting point is a local or a remote branch.
	5432
	5433	• When ‘local’ then the variable are set when the starting point
	5434	is a local branch, but not when it is a remote branch.
	5435
	5436	• When ‘remote’ then the variable are set when the starting
	5437	point is a remote branch, but not when it is a local branch.
	5438
	5439	• When ‘never’ (the default) then the variable is never set.
	5440
	5441	Note that the respective commands always change the repository-local
	5442	values. If you want to change the global value, which is used when the
	5443	local value is undefined, then you have to do so on the command line,
	5444	e.g.:
	5445
	5446	git config --global remote.autoSetupMerge always
	5447
	5448	For more information about these variables you should also see
	5449
	5450	note (gitman)git-config::. Also see note (gitman)git-branch::. ,
	5451	note (gitman)git-checkout::. and note Pushing::.
	5452
	5453	-- User Option: magit-prefer-remote-upstream
	5454
	5455	This option controls whether commands that read a branch from the
	5456	user and then set it as the upstream branch, offer a local or a
	5457	remote branch as default completion candidate, when they have the
	5458	choice.
	5459
	5460	This affects all commands that use ‘magit-read-upstream-branch’ or
	5461	‘magit-read-starting-point’, which includes all commands that
	5462	change the upstream and many which create new branches.
	5463
	5464
	5465	File: magit.info, Node: Auxiliary Branch Commands, Prev: The Branch Config Popup, Up: Branching
	5466
	5467	6.5.4 Auxiliary Branch Commands
	5468	-------------------------------
	5469
	5470	These commands are not available from the branch popup by default.
	5471
	5472	-- Command: magit-branch-shelve
	5473
	5474	This command shelves a branch. This is done by deleting the
	5475	branch, and creating a new reference "refs/shelved/BRANCH-NAME"
	5476	pointing at the same commit as the branch pointed at. If the
	5477	deleted branch had a reflog, then that is preserved as the reflog
	5478	of the new reference.
	5479
	5480	This is useful if you want to move a branch out of sight, but are
	5481	not ready to completely discard it yet.
	5482
	5483	-- Command: magit-branch-unshelve
	5484
	5485	This command unshelves a branch that was previously shelved using
	5486	‘magit-branch-shelve’. This is done by deleting the reference
	5487	"refs/shelved/BRANCH-NAME" and creating a branch "BRANCH-NAME"
	5488	pointing at the same commit as the deleted reference pointed at.
	5489	If the deleted reference had a reflog, then that is restored as the
	5490	reflog of the branch.
	5491
	5492
	5493	File: magit.info, Node: Merging, Next: Resolving Conflicts, Prev: Branching, Up: Manipulating
	5494
	5495	6.6 Merging
	5496	===========
	5497
	5498	Also see *note (gitman)git-merge::. For information on how to resolve
	5499	merge conflicts see the next section.
	5500
	5501	‘m’ (‘magit-merge-popup’)
	5502
	5503	This prefix command shows the following suffix commands along with
	5504	the appropriate infix arguments in a popup buffer.
	5505
	5506	When no merge is in progress, then the popup buffer features the
	5507	following commands.
	5508
	5509	‘m m’ (‘magit-merge-plain’)
	5510
	5511	This command merges another branch or an arbitrary revision into
	5512	the current branch. The branch or revision to be merged is read in
	5513	the minibuffer and defaults to the branch at point.
	5514
	5515	Unless there are conflicts or a prefix argument is used, then the
	5516	resulting merge commit uses a generic commit message, and the user
	5517	does not get a chance to inspect or change it before the commit is
	5518	created. With a prefix argument this does not actually create the
	5519	merge commit, which makes it possible to inspect how conflicts were
	5520	resolved and to adjust the commit message.
	5521
	5522	‘m e’ (‘magit-merge-editmsg’)
	5523
	5524	This command merges another branch or an arbitrary revision into
	5525	the current branch and opens a commit message buffer, so that the
	5526	user can make adjustments. The commit is not actually created
	5527	until the user finishes with ‘C-c C-c’.
	5528
	5529	‘m n’ (‘magit-merge-nocommit’)
	5530
	5531	This command merges another branch or an arbitrary revision into
	5532	the current branch, but does not actually create the merge commit.
	5533	The user can then further adjust the merge, even when automatic
	5534	conflict resolution succeeded and/or adjust the commit message.
	5535
	5536	‘m a’ (‘magit-merge-absorb’)
	5537
	5538	This command merges another local branch into the current branch
	5539	and then removes the former.
	5540
	5541	Before the source branch is merged, it is first force pushed to its
	5542	push-remote, provided the respective remote branch already exists.
	5543	This ensures that the respective pull-request (if any) won’t get
	5544	stuck on some obsolete version of the commits that are being
	5545	merged. Finally, if ‘magit-branch-pull-request’ was used to create
	5546	the merged branch, then the respective remote branch is also
	5547	removed.
	5548
	5549	‘m i’ (‘magit-merge-into’)
	5550
	5551	This command merges the current branch into another local branch
	5552	and then removes the former. The latter becomes the new current
	5553	branch.
	5554
	5555	Before the source branch is merged, it is first force pushed to its
	5556	push-remote, provided the respective remote branch already exists.
	5557	This ensures that the respective pull-request (if any) won’t get
	5558	stuck on some obsolete version of the commits that are being
	5559	merged. Finally, if ‘magit-branch-pull-request’ was used to create
	5560	the merged branch, then the respective remote branch is also
	5561	removed.
	5562
	5563	‘m s’ (‘magit-merge-squash’)
	5564
	5565	This command squashes the changes introduced by another branch or
	5566	an arbitrary revision into the current branch. This only applies
	5567	the changes made by the squashed commits. No information is
	5568	preserved that would allow creating an actual merge commit.
	5569	Instead of this command you should probably use a command from the
	5570	apply popup.
	5571
	5572	‘m p’ (‘magit-merge-preview’)
	5573
	5574	This command shows a preview of merging another branch or an
	5575	arbitrary revision into the current branch.
	5576
	5577	When a merge is in progress, then the popup buffer features these
	5578	commands instead.
	5579
	5580	‘m m’ (‘magit-merge’)
	5581
	5582	After the user resolved conflicts, this command proceeds with the
	5583	merge. If some conflicts weren’t resolved, then this command
	5584	fails.
	5585
	5586	‘m a’ (‘magit-merge-abort’)
	5587
	5588	This command aborts the current merge operation.
	5589
	5590
	5591	File: magit.info, Node: Resolving Conflicts, Next: Rebasing, Prev: Merging, Up: Manipulating
	5592
	5593	6.7 Resolving Conflicts
	5594	=======================
	5595
	5596	When merging branches (or otherwise combining or changing history)
	5597	conflicts can occur. If you edited two completely different parts of
	5598	the same file in two branches and then merge one of these branches into
	5599	the other, then Git can resolve that on its own, but if you edit the
	5600	same area of a file, then a human is required to decide how the two
	5601	versions, or "sides of the conflict", are to be combined into one.
	5602
	5603	Here we can only provide a brief introduction to the subject and
	5604	point you toward some tools that can help. If you are new to this, then
	5605	please also consult Git’s own documentation as well as other resources.
	5606
	5607	If a file has conflicts and Git cannot resolve them by itself, then
	5608	it puts both versions into the affected file along with special markers
	5609	whose purpose is to denote the boundaries of the unresolved part of the
	5610	file and between the different versions. These boundary lines begin
	5611	with the strings consisting of six times the same character, one of ‘<’,
	5612	‘\|’, ‘=’ and ‘>’ and are followed by information about the source of the
	5613	respective versions, e.g.:
	5614
	5615	<<<<<<< HEAD
	5616	Take the blue pill.
	5617	=======
	5618	Take the red pill.
	5619	>>>>>>> feature
	5620
	5621	In this case you have chosen to take the red pill on one branch and
	5622	on another you picked the blue pill. Now that you are merging these two
	5623	diverging branches, Git cannot possibly know which pill you want to
	5624	take.
	5625
	5626	To resolve that conflict you have to create a version of the affected
	5627	area of the file by keeping only one of the sides, possibly by editing
	5628	it in order to bring in the changes from the other side, remove the
	5629	other versions as well as the markers, and then stage the result. A
	5630	possible resolution might be:
	5631
	5632	Take both pills.
	5633
	5634	Often it is useful to see not only the two sides of the conflict but
	5635	also the "original" version from before the same area of the file was
	5636	modified twice on different branches. Instruct Git to insert that
	5637	version as well by running this command once:
	5638
	5639	git config --global merge.conflictStyle diff3
	5640
	5641	The above conflict might then have looked like this:
	5642
	5643	<<<<<<< HEAD
	5644	Take the blue pill.
	5645	\|\|\|\|\|\|\| merged common ancestors
	5646	Take either the blue or the red pill, but not both.
	5647	=======
	5648	Take the red pill.
	5649	>>>>>>> feature
	5650
	5651	If that were the case, then the above conflict resolution would not
	5652	have been correct, which demonstrates why seeing the original version
	5653	alongside the conflicting versions can be useful.
	5654
	5655	You can perform the conflict resolution completely by hand, but Emacs
	5656	also provides some packages that help in the process: Smerge, Ediff
	5657	(note (ediff)Top::), and Emerge (note (emacs)Emerge::). Magit does
	5658	not provide its own tools for conflict resolution, but it does make
	5659	using Smerge and Ediff more convenient. (Ediff supersedes Emerge, so
	5660	you probably don’t want to use the latter anyway.)
	5661
	5662	In the Magit status buffer, files with unresolved conflicts are
	5663	listed in the "Unstaged changes" and/or "Staged changes" sections. They
	5664	are prefixed with the word "unmerged", which in this context essentially
	5665	is a synonym for "unresolved".
	5666
	5667	Pressing ‘RET’ while point is on such a file section shows a buffer
	5668	visiting that file, turns on ‘smerge-mode’ in that buffer, and places
	5669	point inside the first area with conflicts. You should then resolve
	5670	that conflict using regular edit commands and/or Smerge commands.
	5671
	5672	Unfortunately Smerge does not have a manual, but you can get a list
	5673	of commands and binding ‘C-c ^ C-h’ and press ‘RET’ while point is on a
	5674	command name to read its documentation.
	5675
	5676	Normally you would edit one version and then tell Smerge to keep only
	5677	that version. Use ‘C-c ^ m’ (‘smerge-keep-mine’) to keep the ‘HEAD’
	5678	version or ‘C-c ^ o’ (‘smerge-keep-other’) to keep the version that
	5679	follows "\|\|\|\|\|\|\|". Then use ‘C-c ^ n’ to move to the next conflicting
	5680	area in the same file. Once you are done resolving conflicts, return to
	5681	the Magit status buffer. The file should now be shown as "modified", no
	5682	longer as "unmerged", because Smerge automatically stages the file when
	5683	you save the buffer after resolving the last conflict.
	5684
	5685	Alternatively you could use Ediff, which uses separate buffers for
	5686	the different versions of the file. To resolve conflicts in a file
	5687	using Ediff press ‘e’ while point is on such a file in the status
	5688	buffer.
	5689
	5690	Ediff can be used for other purposes as well. For more information
	5691	on how to enter Ediff from Magit, see *note Ediffing::. Explaining how
	5692	to use Ediff is beyond the scope of this manual, instead see *note
	5693	(ediff)Top::.
	5694
	5695	If you are unsure whether you should Smerge or Ediff, then use the
	5696	former. It is much easier to understand and use, and except for truly
	5697	complex conflicts, the latter is usually overkill.
	5698
	5699
	5700	File: magit.info, Node: Rebasing, Next: Cherry Picking, Prev: Resolving Conflicts, Up: Manipulating
	5701
	5702	6.8 Rebasing
	5703	============
	5704
	5705	Also see *note (gitman)git-rebase::. For information on how to resolve
	5706	conflicts that occur during rebases see the preceding section.
	5707
	5708	‘r’ (‘magit-rebase-popup’)
	5709
	5710	This prefix command shows the following suffix commands along with
	5711	the appropriate infix arguments in a popup buffer.
	5712
	5713	When no rebase is in progress, then the popup buffer features the
	5714	following commands.
	5715
	5716	Using one of these commands _starts_ a rebase sequence. Git might
	5717	then stop somewhere along the way, either because you told it to do so,
	5718	or because applying a commit failed due to a conflict. When that
	5719	happens, then the status buffer shows information about the rebase
	5720	sequence which is in progress in a section similar to a log section.
	5721	See *note Information About In-Progress Rebase::.
	5722
	5723	‘r p’ (‘magit-rebase-onto-pushremote’)
	5724
	5725	Rebase the current branch onto ‘branch.<name>.pushRemote’. If that
	5726	variable is unset, then rebase onto ‘remote.pushDefault’.
	5727
	5728	‘r u’ (‘magit-rebase-onto-upstream’)
	5729
	5730	Rebase the current branch onto its upstream branch.
	5731
	5732	‘r e’ (‘magit-rebase-branch’)
	5733
	5734	Rebase the current branch onto a branch read in the minibuffer.
	5735	All commits that are reachable from head but not from the selected
	5736	branch TARGET are being rebased."
	5737
	5738	‘r s’ (‘magit-rebase-subset’)
	5739
	5740	Start a non-interactive rebase sequence with commits from START to
	5741	‘HEAD’ onto NEWBASE. START has to be selected from a list of
	5742	recent commits.
	5743
	5744	By default Magit uses the ‘--autostash’ argument, which causes
	5745	uncommitted changes to be stored in a stash before the rebase begins.
	5746	These changes are restored after the rebase completes and if possible
	5747	the stash is removed. If the stash does not apply cleanly, then the
	5748	stash is not removed. In case something goes wrong when resolving the
	5749	conflicts, this allows you to start over.
	5750
	5751	Even though one of the actions is dedicated to interactive rebases,
	5752	the popup also features the infix argument ‘--interactive’. This can be
	5753	used to turn one of the other, non-interactive rebase variants into an
	5754	interactive rebase.
	5755
	5756	For example if you want to clean up a feature branch and at the same
	5757	time rebase it onto ‘master’, then you could use ‘r-iu’. But we
	5758	recommend that you instead do that in two steps. First use ‘ri’ to
	5759	cleanup the feature branch, and then in a second step ‘ru’ to rebase it
	5760	onto ‘master’. That way if things turn out to be more complicated than
	5761	you thought and/or you make a mistake and have to start over, then you
	5762	only have to redo half the work.
	5763
	5764	Explicitly enabling ‘--interactive’ won’t have an effect on the
	5765	following commands as they always use that argument anyway, even if it
	5766	is not enabled in the popup.
	5767
	5768	‘r i’ (‘magit-rebase-interactive’)
	5769
	5770	Start an interactive rebase sequence.
	5771
	5772	‘r f’ (‘magit-rebase-autosquash’)
	5773
	5774	Combine squash and fixup commits with their intended targets.
	5775
	5776	‘r m’ (‘magit-rebase-edit-commit’)
	5777
	5778	Edit a single older commit using rebase.
	5779
	5780	‘r w’ (‘magit-rebase-reword-commit’)
	5781
	5782	Reword a single older commit using rebase.
	5783
	5784	‘r k’ (‘magit-rebase-remove-commit’)
	5785
	5786	Remove a single older commit using rebase.
	5787
	5788	When a rebase is in progress, then the popup buffer features these
	5789	commands instead.
	5790
	5791	‘r r’ (‘magit-rebase-continue’)
	5792
	5793	Restart the current rebasing operation.
	5794
	5795	In some cases this pops up a commit message buffer for you do edit.
	5796	With a prefix argument the old message is reused as-is.
	5797
	5798	‘r s’ (‘magit-rebase-skip’)
	5799
	5800	Skip the current commit and restart the current rebase operation.
	5801
	5802	‘r e’ (‘magit-rebase-edit’)
	5803
	5804	Edit the todo list of the current rebase operation.
	5805
	5806	‘r a’ (‘magit-rebase-abort’)
	5807
	5808	Abort the current rebase operation, restoring the original branch.
	5809
	5810	* Menu:
	5811
	5812	* Editing Rebase Sequences::
	5813	* Information About In-Progress Rebase::
	5814
	5815
	5816	File: magit.info, Node: Editing Rebase Sequences, Next: Information About In-Progress Rebase, Up: Rebasing
	5817
	5818	6.8.1 Editing Rebase Sequences
	5819	------------------------------
	5820
	5821	‘C-c C-c’ (‘with-editor-finish’)
	5822
	5823	Finish the current editing session by returning with exit code 0.
	5824	Git then uses the rebase instructions it finds in the file.
	5825
	5826	‘C-c C-k’ (‘with-editor-cancel’)
	5827
	5828	Cancel the current editing session by returning with exit code 1.
	5829	Git then forgoes starting the rebase sequence.
	5830
	5831	‘RET’ (‘git-rebase-show-commit’)
	5832
	5833	Show the commit on the current line in another buffer and select
	5834	that buffer.
	5835
	5836	‘SPC’ (‘git-rebase-show-or-scroll-up’)
	5837
	5838	Show the commit on the current line in another buffer without
	5839	selecting that buffer. If the revision buffer is already visible
	5840	in another window of the current frame, then instead scroll that
	5841	window up.
	5842
	5843	‘DEL’ (‘git-rebase-show-or-scroll-down’)
	5844
	5845	Show the commit on the current line in another buffer without
	5846	selecting that buffer. If the revision buffer is already visible
	5847	in another window of the current frame, then instead scroll that
	5848	window down.
	5849
	5850	‘p’ (‘git-rebase-backward-line’)
	5851
	5852	Move to previous line.
	5853
	5854	‘n’ (‘forward-line’)
	5855
	5856	Move to next line.
	5857
	5858	‘M-p’ (‘git-rebase-move-line-up’)
	5859
	5860	Move the current commit (or command) up.
	5861
	5862	‘M-n’ (‘git-rebase-move-line-down’)
	5863
	5864	Move the current commit (or command) down.
	5865
	5866	‘r’ (‘git-rebase-reword’)
	5867
	5868	Edit message of commit on current line.
	5869
	5870	‘e’ (‘git-rebase-edit’)
	5871
	5872	Stop at the commit on the current line.
	5873
	5874	‘s’ (‘git-rebase-squash’)
	5875
	5876	Meld commit on current line into previous commit, and edit message.
	5877
	5878	‘f’ (‘git-rebase-fixup’)
	5879
	5880	Meld commit on current line into previous commit, discarding the
	5881	current commit’s message.
	5882
	5883	‘k’ (‘git-rebase-kill-line’)
	5884
	5885	Kill the current action line.
	5886
	5887	‘c’ (‘git-rebase-pick’)
	5888
	5889	Use commit on current line.
	5890
	5891	‘x’ (‘git-rebase-exec’)
	5892
	5893	Insert a shell command to be run after the proceeding commit.
	5894
	5895	If there already is such a command on the current line, then edit
	5896	that instead. With a prefix argument insert a new command even
	5897	when there already is one on the current line. With empty input
	5898	remove the command on the current line, if any.
	5899
	5900	‘y’ (‘git-rebase-insert’)
	5901
	5902	Read an arbitrary commit and insert it below current line.
	5903
	5904	‘C-x u’ (‘git-rebase-undo’)
	5905
	5906	Undo some previous changes. Like ‘undo’ but works in read-only
	5907	buffers.
	5908
	5909	-- User Option: git-rebase-auto-advance
	5910
	5911	Whether to move to next line after changing a line.
	5912
	5913	-- User Option: git-rebase-show-instructions
	5914
	5915	Whether to show usage instructions inside the rebase buffer.
	5916
	5917	-- User Option: git-rebase-confirm-cancel
	5918
	5919	Whether confirmation is required to cancel.
	5920
	5921
	5922	File: magit.info, Node: Information About In-Progress Rebase, Prev: Editing Rebase Sequences, Up: Rebasing
	5923
	5924	6.8.2 Information About In-Progress Rebase
	5925	------------------------------------------
	5926
	5927	While a rebase sequence is in progress, the status buffer features a
	5928	section that lists the commits that have already been applied as well as
	5929	the commits that still have to be applied.
	5930
	5931	The commits are split in two halves. When rebase stops at a commit,
	5932	either because the user has to deal with a conflict or because s/he
	5933	explicitly requested that rebase stops at that commit, then point is
	5934	placed on the commit that separates the two groups, i.e. on ‘HEAD’.
	5935	The commits above it have not been applied yet, while the ‘HEAD’ and the
	5936	commits below it have already been applied. In between these two groups
	5937	of applied and yet-to-be applied commits, there sometimes is a commit
	5938	which has been dropped.
	5939
	5940	Each commit is prefixed with a word and these words are additionally
	5941	shown in different colors to indicate the status of the commits.
	5942
	5943	The following colors are used:
	5944
	5945	• Yellow commits have not been applied yet.
	5946
	5947	• Gray commits have already been applied.
	5948
	5949	• The blue commit is the ‘HEAD’ commit.
	5950
	5951	• The green commit is the commit the rebase sequence stopped at. If
	5952	this is the same commit as ‘HEAD’ (e.g. because you haven’t done
	5953	anything yet after rebase stopped at the commit, then this commit
	5954	is shown in blue, not green). There can only be a green and a
	5955	blue commit at the same time, if you create one or more new commits
	5956	after rebase stops at a commit.
	5957
	5958	• Red commits have been dropped. They are shown for reference only,
	5959	e.g. to make it easier to diff.
	5960
	5961	Of course these colors are subject to the color-theme in use.
	5962
	5963	The following words are used:
	5964
	5965	• Commits prefixed with ‘pick’, ‘reword’, ‘edit’, ‘squash’, and
	5966	‘fixup’ have not been applied yet. These words have the same
	5967	meaning here as they do in the buffer used to edit the rebase
	5968	sequence. See *note Editing Rebase Sequences::.
	5969
	5970	• Commits prefixed with ‘done’ and ‘onto’ have already been applied.
	5971	It is possible for such a commit to be the ‘HEAD’, in which case it
	5972	is blue. Otherwise it is grey.
	5973
	5974	• The commit prefixed with ‘onto’ is the commit on top of which
	5975	all the other commits are being re-applied. This commit
	5976	itself did not have to be re-applied, it is the commit rebase
	5977	did rewind to before starting to re-apply other commits.
	5978
	5979	• Commits prefixed with ‘done’ have already been re-applied.
	5980	This includes commits that have been re-applied but also new
	5981	commits that you have created during the rebase.
	5982
	5983	• All other commits, those not prefixed with any of the above words,
	5984	are in some way related to the commit at which rebase stopped.
	5985
	5986	To determine whether a commit is related to the stopped-at commit
	5987	their hashes, trees and patch-ids (1) are being compared. The
	5988	commit message is not used for this purpose.
	5989
	5990	Generally speaking commits that are related to the stopped-at
	5991	commit can have any of the used colors, though not all color/word
	5992	combinations are possible.
	5993
	5994	Words used for stopped-at commits are:
	5995
	5996	• When a commit is prefixed with ‘void’, then that indicates
	5997	that Magit knows for sure that all the changes in that commit
	5998	have been applied using several new commits. This commit is
	5999	no longer reachable from ‘HEAD’, and it also isn’t one of the
	6000	commits that will be applied when resuming the session.
	6001
	6002	• When a commit is prefixed with ‘join’, then that indicates
	6003	that the rebase sequence stopped at that commit due to a
	6004	conflict - you now have to join (merge) the changes with what
	6005	has already been applied. In a sense this is the commit
	6006	rebase stopped at, but while its effect is already in the
	6007	index and in the worktree (with conflict markers), the commit
	6008	itself has not actually been applied yet (it isn’t the
	6009	‘HEAD’). So it is shown in yellow, like the other commits
	6010	that still have to be applied.
	6011
	6012	• When a commit is prefixed with ‘stop’ or a _blue_ or _green_
	6013	‘same’, then that indicates that rebase stopped at this
	6014	commit, that it is still applied or has been applied again,
	6015	and that at least its patch-id is unchanged.
	6016
	6017	• When a commit is prefixed with ‘stop’, then that
	6018	indicates that rebase stopped at that commit because you
	6019	requested that earlier, and its patch-id is unchanged.
	6020	It might even still be the exact same commit.
	6021
	6022	• When a commit is prefixed with a _blue_ or _green_
	6023	‘same’, then that indicates that while its tree or hash
	6024	changed, its patch-id did not. If it is blue, then it is
	6025	the ‘HEAD’ commit (as always for blue). When it is
	6026	green, then it no longer is ‘HEAD’ because other commit
	6027	have been created since (but before continuing the
	6028	rebase).
	6029
	6030	• When a commit is prefixed with ‘goal’, a _yellow_ ‘same,’ or
	6031	‘work’, then that indicates that rebase applied that commit
	6032	but that you then reset ‘HEAD’ to an earlier commit (likely to
	6033	split it up into multiple commits), and that there are some
	6034	uncommitted changes remaining which likely (but not
	6035	necessarily) originate from that commit.
	6036
	6037	• When a commit is prefixed with ‘goal’, then that
	6038	indicates that it is still possible to create a new
	6039	commit with the exact same tree (the "goal") without
	6040	manually editing any files, by committing the index, or
	6041	by staging all changes and then committing that. This is
	6042	the case when the original tree still exists in the index
	6043	or worktree in untainted form.
	6044
	6045	• When a commit is prefixed with a yellow ‘same’, then that
	6046	indicates that it is no longer possible to create a
	6047	commit with the exact same tree, but that it is still
	6048	possible to create a commit with the same patch-id. This
	6049	would be the case if you created a new commit with other
	6050	changes, but the changes from the original commit still
	6051	exist in the index or working tree in untainted form.
	6052
	6053	• When a commit is prefixed with ‘work’, then that
	6054	indicates that you reset ‘HEAD’ to an earlier commit, and
	6055	that there are some staged and/or unstaged changes
	6056	(likely, but not necessarily) originating from that
	6057	commit. However it is no longer possible to create a new
	6058	commit with the same tree or at least the same patch-id
	6059	because you have already made other changes.
	6060
	6061	• When a commit is prefixed with ‘poof’ or ‘gone’, then that
	6062	indicates that rebase applied that commit but that you then
	6063	reset ‘HEAD’ to an earlier commit (likely to split it up into
	6064	multiple commits), and that there are no uncommitted changes.
	6065
	6066	• When a commit is prefixed with ‘poof’, then that
	6067	indicates that it is no longer reachable from ‘HEAD’, but
	6068	that it has been replaced with one or more commits, which
	6069	together have the exact same effect.
	6070
	6071	• When a commit is prefixed with ‘gone’, then that
	6072	indicates that it is no longer reachable from ‘HEAD’ and
	6073	that we also cannot determine whether its changes are
	6074	still in effect in one or more new commits. They might
	6075	be, but if so, then there must also be other changes
	6076	which makes it impossible to know for sure.
	6077
	6078	Do not worry if you do not fully understand the above. That’s okay,
	6079	you will acquire a good enough understanding through practice.
	6080
	6081	For other sequence operations such as cherry-picking, a similar
	6082	section is displayed, but they lack some of the features described
	6083	above, due to limitations in the git commands used to implement them.
	6084	Most importantly these sequences only support "picking" a commit but not
	6085	other actions such as "rewording", and they do not keep track of the
	6086	commits which have already been applied.
	6087
	6088	---------- Footnotes ----------
	6089
	6090	(1) The patch-id is a hash of the _changes_ introduced by a commit.
	6091	It differs from the hash of the commit itself, which is a hash of the
	6092	result of applying that change (i.e. the resulting trees and blobs) as
	6093	well as author and committer information, the commit message, and the
	6094	hashes of the parents of the commit. The patch-id hash on the other
	6095	hand is created only from the added and removed lines, even line numbers
	6096	and whitespace changes are ignored when calculating this hash. The
	6097	patch-ids of two commits can be used to answer the question "Do these
	6098	commits make the same change?".
	6099
	6100
	6101	File: magit.info, Node: Cherry Picking, Next: Resetting, Prev: Rebasing, Up: Manipulating
	6102
	6103	6.9 Cherry Picking
	6104	==================
	6105
	6106	Also see *note (gitman)git-cherry-pick::.
	6107
	6108	‘A’ (‘magit-cherry-pick-popup’)
	6109
	6110	This prefix command shows the following suffix commands along with
	6111	the appropriate infix arguments in a popup buffer.
	6112
	6113	When no cherry-pick or revert is in progress, then the popup buffer
	6114	features the following commands.
	6115
	6116	‘A A’ (‘magit-cherry-copy’)
	6117
	6118	This command copies COMMITS from another branch onto the current
	6119	branch. If the region selects multiple commits, then those are
	6120	copied, without prompting. Otherwise the user is prompted for a
	6121	commit or range, defaulting to the commit at point.
	6122
	6123	‘A a’ (‘magit-cherry-apply’)
	6124
	6125	This command applies the changes in COMMITS from another branch
	6126	onto the current branch. If the region selects multiple commits,
	6127	then those are used, without prompting. Otherwise the user is
	6128	prompted for a commit or range, defaulting to the commit at point.
	6129
	6130	This command also has a top-level binding, which can be invoked
	6131	without using the popup by typing ‘a’ at the top-level.
	6132
	6133	The following commands not only apply some commits to some branch,
	6134	but also remove them from some other branch. The removal is performed
	6135	using either ‘git-update-ref’ or if necessary ‘git-rebase’. Both
	6136	applying commits as well as removing them using ‘git-rebase’ can lead to
	6137	conflicts. If that happens, then these commands abort and you not only
	6138	have to resolve the conflicts but also finish the process the same way
	6139	you would have to if these commands didn’t exist at all.
	6140
	6141	‘A h’ (‘magit-cherry-harvest’)
	6142
	6143	This command moves the selected COMMITS that must be located on
	6144	another BRANCH onto the current branch instead, removing them from
	6145	the former. When this command succeeds, then the same branch is
	6146	current as before.
	6147
	6148	Applying the commits on the current branch or removing them from
	6149	the other branch can lead to conflicts. When that happens, then
	6150	this command stops and you have to resolve the conflicts and then
	6151	finish the process manually.
	6152
	6153	‘A d’ (‘magit-cherry-donate’)
	6154
	6155	This command moves the selected COMMITS from the current branch
	6156	onto another existing BRANCH, removing them from the former. When
	6157	this command succeeds, then the same branch is current as before.
	6158
	6159	Applying the commits on the other branch or removing them from the
	6160	current branch can lead to conflicts. When that happens, then this
	6161	command stops and you have to resolve the conflicts and then finish
	6162	the process manually.
	6163
	6164	‘A n’ (‘magit-cherry-spinout’)
	6165
	6166	This command moves the selected COMMITS from the current branch
	6167	onto a new branch BRANCH, removing them from the former. When this
	6168	command succeeds, then the same branch is current as before.
	6169
	6170	Applying the commits on the other branch or removing them from the
	6171	current branch can lead to conflicts. When that happens, then this
	6172	command stops and you have to resolve the conflicts and then finish
	6173	the process manually.
	6174
	6175	‘A s’ (‘magit-cherry-spinoff’)
	6176
	6177	This command moves the selected COMMITS from the current branch
	6178	onto a new branch BRANCH, removing them from the former. When this
	6179	command succeeds, then the new branch is checked out.
	6180
	6181	Applying the commits on the other branch or removing them from the
	6182	current branch can lead to conflicts. When that happens, then this
	6183	command stops and you have to resolve the conflicts and then finish
	6184	the process manually.
	6185
	6186	When a cherry-pick or revert is in progress, then the popup buffer
	6187	features these commands instead.
	6188
	6189	‘A A’ (‘magit-sequence-continue’)
	6190
	6191	Resume the current cherry-pick or revert sequence.
	6192
	6193	‘A s’ (‘magit-sequence-skip’)
	6194
	6195	Skip the stopped at commit during a cherry-pick or revert sequence.
	6196
	6197	‘A a’ (‘magit-sequence-abort’)
	6198
	6199	Abort the current cherry-pick or revert sequence. This discards
	6200	all changes made since the sequence started.
	6201
	6202	* Menu:
	6203
	6204	* Reverting::
	6205
	6206
	6207	File: magit.info, Node: Reverting, Up: Cherry Picking
	6208
	6209	6.9.1 Reverting
	6210	---------------
	6211
	6212	‘V’ (‘magit-revert-popup’)
	6213
	6214	This prefix command shows the following suffix commands along with
	6215	the appropriate infix arguments in a popup buffer.
	6216
	6217	When no cherry-pick or revert is in progress, then the popup buffer
	6218	features the following commands.
	6219
	6220	‘V V’ (‘magit-revert-and-commit’)
	6221
	6222	Revert a commit by creating a new commit. Prompt for a commit,
	6223	defaulting to the commit at point. If the region selects multiple
	6224	commits, then revert all of them, without prompting.
	6225
	6226	‘V v’ (‘magit-revert-no-commit’)
	6227
	6228	Revert a commit by applying it in reverse to the working tree.
	6229	Prompt for a commit, defaulting to the commit at point. If the
	6230	region selects multiple commits, then revert all of them, without
	6231	prompting.
	6232
	6233	When a cherry-pick or revert is in progress, then the popup buffer
	6234	features these commands instead.
	6235
	6236	‘V A’ (‘magit-sequence-continue’)
	6237
	6238	Resume the current cherry-pick or revert sequence.
	6239
	6240	‘V s’ (‘magit-sequence-skip’)
	6241
	6242	Skip the stopped at commit during a cherry-pick or revert sequence.
	6243
	6244	‘V a’ (‘magit-sequence-abort’)
	6245
	6246	Abort the current cherry-pick or revert sequence. This discards
	6247	all changes made since the sequence started.
	6248
	6249
	6250	File: magit.info, Node: Resetting, Next: Stashing, Prev: Cherry Picking, Up: Manipulating
	6251
	6252	6.10 Resetting
	6253	==============
	6254
	6255	Also see *note (gitman)git-reset::.
	6256
	6257	‘x’ (‘magit-reset-quickly’)
	6258
	6259	Reset the ‘HEAD’ and index to some commit read from the user and
	6260	defaulting to the commit at point, and possibly also reset the
	6261	working tree. With a prefix argument reset the working tree
	6262	otherwise don’t.
	6263
	6264	‘X m’ (‘magit-reset-mixed’)
	6265
	6266	Reset the ‘HEAD’ and index to some commit read from the user and
	6267	defaulting to the commit at point. The working tree is kept as-is.
	6268
	6269	‘X s’ (‘magit-reset-soft’)
	6270
	6271	Reset the ‘HEAD’ to some commit read from the user and defaulting
	6272	to the commit at point. The index and the working tree are kept
	6273	as-is.
	6274
	6275	‘X h’ (‘magit-reset-hard’)
	6276
	6277	Reset the ‘HEAD’, index, and working tree to some commit read from
	6278	the user and defaulting to the commit at point.
	6279
	6280	‘X i’ (‘magit-reset-index’)
	6281
	6282	Reset the index to some commit read from the user and defaulting to
	6283	the commit at point. Keep the ‘HEAD’ and working tree as-is, so if
	6284	the commit refers to the ‘HEAD’, then this effectively unstages all
	6285	changes.
	6286
	6287	‘X w’ (‘magit-reset-worktree’)
	6288
	6289	Reset the working tree to some commit read from the user and
	6290	defaulting to the commit at point. Keep the ‘HEAD’ and index
	6291	as-is.
	6292
	6293	‘X f’ (‘magit-file-checkout’)
	6294
	6295	Update file in the working tree and index to the contents from a
	6296	revision. Both the revision and file are read from the user.
	6297
	6298
	6299	File: magit.info, Node: Stashing, Prev: Resetting, Up: Manipulating
	6300
	6301	6.11 Stashing
	6302	=============
	6303
	6304	Also see *note (gitman)git-stash::.
	6305
	6306	‘z’ (‘magit-stash-popup’)
	6307
	6308	This prefix command shows the following suffix commands along with
	6309	the appropriate infix arguments in a popup buffer.
	6310
	6311	‘z z’ (‘magit-stash-both’)
	6312
	6313	Create a stash of the index and working tree. Untracked files are
	6314	included according to popup arguments. One prefix argument is
	6315	equivalent to ‘--include-untracked’ while two prefix arguments are
	6316	equivalent to ‘--all’.
	6317
	6318	‘z i’ (‘magit-stash-index’)
	6319
	6320	Create a stash of the index only. Unstaged and untracked changes
	6321	are not stashed.
	6322
	6323	‘z w’ (‘magit-stash-worktree’)
	6324
	6325	Create a stash of unstaged changes in the working tree. Untracked
	6326	files are included according to popup arguments. One prefix
	6327	argument is equivalent to ‘--include-untracked’ while two prefix
	6328	arguments are equivalent to ‘--all’.
	6329
	6330	‘z x’ (‘magit-stash-keep-index’)
	6331
	6332	Create a stash of the index and working tree, keeping index intact.
	6333	Untracked files are included according to popup arguments. One
	6334	prefix argument is equivalent to ‘--include-untracked’ while two
	6335	prefix arguments are equivalent to ‘--all’.
	6336
	6337	‘z Z’ (‘magit-snapshot-both’)
	6338
	6339	Create a snapshot of the index and working tree. Untracked files
	6340	are included according to popup arguments. One prefix argument is
	6341	equivalent to ‘--include-untracked’ while two prefix arguments are
	6342	equivalent to ‘--all’.
	6343
	6344	‘z I’ (‘magit-snapshot-index’)
	6345
	6346	Create a snapshot of the index only. Unstaged and untracked
	6347	changes are not stashed.
	6348
	6349	‘z W’ (‘magit-snapshot-worktree’)
	6350
	6351	Create a snapshot of unstaged changes in the working tree.
	6352	Untracked files are included according to popup arguments. One
	6353	prefix argument is equivalent to ‘--include-untracked’ while two
	6354	prefix arguments are equivalent to ‘--all’-.
	6355
	6356	‘z a’ (‘magit-stash-apply’)
	6357
	6358	Apply a stash to the working tree. Try to preserve the stash
	6359	index. If that fails because there are staged changes, apply
	6360	without preserving the stash index.
	6361
	6362	‘z p’ (‘magit-stash-pop’)
	6363
	6364	Apply a stash to the working tree and remove it from stash list.
	6365	Try to preserve the stash index. If that fails because there are
	6366	staged changes, apply without preserving the stash index and forgo
	6367	removing the stash.
	6368
	6369	‘z k’ (‘magit-stash-drop’)
	6370
	6371	Remove a stash from the stash list. When the region is active,
	6372	offer to drop all contained stashes.
	6373
	6374	‘z v’ (‘magit-stash-show’)
	6375
	6376	Show all diffs of a stash in a buffer.
	6377
	6378	‘z b’ (‘magit-stash-branch’)
	6379
	6380	Create and checkout a new BRANCH from STASH. The branch starts at
	6381	the commit that was current when the stash was created.
	6382
	6383	‘z B’ (‘magit-stash-branch-here’)
	6384
	6385	Create and checkout a new BRANCH using ‘magit-branch’ with the
	6386	current branch or ‘HEAD’ as the starting-point. Then apply STASH,
	6387	dropping it if it applies cleanly.
	6388
	6389	‘z f’ (‘magit-stash-format-patch’)
	6390
	6391	Create a patch from STASH.
	6392
	6393	‘k’ (‘magit-stash-clear’)
	6394
	6395	Remove all stashes saved in REF’s reflog by deleting REF.
	6396
	6397	‘z l’ (‘magit-stash-list’)
	6398
	6399	List all stashes in a buffer.
	6400
	6401	-- User Option: magit-stashes-margin
	6402
	6403	This option specifies whether the margin is initially shown in
	6404	stashes buffers and how it is formatted.
	6405
	6406	The value has the form ‘(INIT STYLE WIDTH AUTHOR AUTHOR-WIDTH)’.
	6407
	6408	• If INIT is non-nil, then the margin is shown initially.
	6409
	6410	• STYLE controls how to format the committer date. It can be
	6411	one of ‘age’ (to show the age of the commit),
	6412	‘age-abbreviated’ (to abbreviate the time unit to a
	6413	character), or a string (suitable for ‘format-time-string’) to
	6414	show the actual date.
	6415
	6416	• WIDTH controls the width of the margin. This exists for
	6417	forward compatibility and currently the value should not be
	6418	changed.
	6419
	6420	• AUTHOR controls whether the name of the author is also shown
	6421	by default.
	6422
	6423	• AUTHOR-WIDTH has to be an integer. When the name of the
	6424	author is shown, then this specifies how much space is used to
	6425	do so.
	6426
	6427
	6428	File: magit.info, Node: Transferring, Next: Miscellaneous, Prev: Manipulating, Up: Top
	6429
	6430	7 Transferring
	6431	**************
	6432
	6433	* Menu:
	6434
	6435	* Remotes::
	6436	* Fetching::
	6437	* Pulling::
	6438	* Pushing::
	6439	* Creating and Sending Patches::
	6440	* Applying Patches::
	6441
	6442
	6443	File: magit.info, Node: Remotes, Next: Fetching, Up: Transferring
	6444
	6445	7.1 Remotes
	6446	===========
	6447
	6448	* Menu:
	6449
	6450	* The Remote Popup::
	6451	* The Remote Config Popup::
	6452
	6453
	6454	File: magit.info, Node: The Remote Popup, Next: The Remote Config Popup, Up: Remotes
	6455
	6456	7.1.1 The Remote Popup
	6457	----------------------
	6458
	6459	The popup ‘magit-remote-popup’ is used to add remotes and to make
	6460	changes to existing remotes. This popup only deals with remotes
	6461	themselves, not with branches or the transfer of commits. Those
	6462	features are available from separate popups.
	6463
	6464	Also see *note (gitman)git-remote::.
	6465
	6466	‘M’ (‘magit-remote-popup’)
	6467
	6468	This prefix command shows the following suffix commands along with
	6469	the appropriate infix arguments in a popup buffer.
	6470
	6471	-- User Option: magit-remote-popup-show-variables
	6472
	6473	This option controls whether the ‘magit-remote-popup’ shows remote
	6474	related Git variables. When set to nil, no variables are displayed
	6475	directly in this popup, and the sub-popup
	6476	‘magit-remote-config-popup’ has to be used instead to view and
	6477	change remote related variables.
	6478
	6479	‘M C’ (‘magit-remote-config-popup’)
	6480
	6481	This command shows remote related variables in a separate popup.
	6482	By default this asks the user for which remote the variables should
	6483	be shown. When ‘magit-remote-popup-show-variables’ is ‘nil’, then
	6484	it shows the variables for the upstream of the current branch or
	6485	"origin" it that branch has no remote upstream. To select another
	6486	remote use a prefix argument.
	6487
	6488	‘M a’ (‘magit-remote-add’)
	6489
	6490	This command add a remote and fetches it. The remote name and url
	6491	are read in the minibuffer.
	6492
	6493	‘M r’ (‘magit-remote-rename’)
	6494
	6495	This command renames a remote. Both the old and the new names are
	6496	read in the minibuffer.
	6497
	6498	‘M u’ (‘magit-remote-set-url’)
	6499
	6500	This command changes the url of a remote. Both the remote and the
	6501	new url are read in the minibuffer.
	6502
	6503	‘M k’ (‘magit-remote-remove’)
	6504
	6505	This command deletes a remote, read in the minibuffer.
	6506
	6507	‘M p’ (‘magit-remote-prune’)
	6508
	6509	This command removes stale remote-tracking branches for a remote
	6510	read in the minibuffer.
	6511
	6512	‘M P’ (‘magit-remote-prune-refspecs’)
	6513
	6514	This command removes stale refspecs for a remote read in the
	6515	minibuffer.
	6516
	6517	A refspec is stale if there no longer exists at least one branch on
	6518	the remote that would be fetched due to that refspec. A stale
	6519	refspec is problematic because its existence causes Git to refuse
	6520	to fetch according to the remaining non-stale refspecs.
	6521
	6522	If only stale refspecs remain, then this command offers to either
	6523	delete the remote or to replace the stale refspecs with the default
	6524	refspec ("+refs/heads/:refs/remotes/REMOTE/").
	6525
	6526	This command also removes the remote-tracking branches that were
	6527	created due to the now stale refspecs. Other stale branches are
	6528	not removed.
	6529
	6530	-- User Option: magit-remote-add-set-remote.pushDefault
	6531
	6532	This option controls whether the user is asked whether they want to
	6533	set ‘remote.pushDefault’ after adding a remote.
	6534
	6535	If ‘ask’, then users is always ask. If ‘ask-if-unset’, then the
	6536	user is only if the variable isn’t set already. If ‘nil’, then the
	6537	user isn’t asked and the variable isn’t set. If the value is a
	6538	string, then the variable is set without the user being asked,
	6539	provided that the name of the added remote is equal to that string
	6540	and the variable isn’t already set.
	6541
	6542
	6543	File: magit.info, Node: The Remote Config Popup, Prev: The Remote Popup, Up: Remotes
	6544
	6545	7.1.2 The Remote Config Popup
	6546	-----------------------------
	6547
	6548	-- Command: magit-remote-config-popup
	6549
	6550	This prefix command shows the following remote-related Git
	6551	variables in a popup buffer. The values can be changed from that
	6552	buffer.
	6553
	6554	This popup is a sub-popup of the ‘magit-remote-popup’ in which "C"
	6555	is bound to this popup.
	6556
	6557	The following variables are used to configure a specific remote. The
	6558	values are being displayed for the upstream remote of the current
	6559	branch. To change the value for another remote invoke
	6560	‘magit-remote-config-popup’ with a prefix argument.
	6561
	6562	-- Variable: remote.NAME.url
	6563
	6564	This variable specifies the url of the remote named NAME. It can
	6565	have multiple values.
	6566
	6567	-- Variable: remote.NAME.fetch
	6568
	6569	The refspec used when fetching from the remote named NAME. It can
	6570	have multiple values.
	6571
	6572	-- Variable: remote.NAME.pushurl
	6573
	6574	This variable specifies the url used for fetching from the remote
	6575	named NAME. If it is not specified, then ‘remote.NAME.url’ is used
	6576	instead. It can have multiple values.
	6577
	6578	-- Variable: remote.NAME.push
	6579
	6580	The refspec used when pushing to the remote named NAME. It can
	6581	have multiple values.
	6582
	6583	-- Variable: remote.NAME.tagOpts
	6584
	6585	This variable specifies what tags are fetched by default. If the
	6586	value is ‘--no-tags’ then no tags are fetched. If the value is
	6587	‘--tags’, then all tags are fetched. If this variable has not
	6588	value, then only tags are fetched that are reachable from fetched
	6589	branches.
	6590
	6591
	6592	File: magit.info, Node: Fetching, Next: Pulling, Prev: Remotes, Up: Transferring
	6593
	6594	7.2 Fetching
	6595	============
	6596
	6597	For information about the differences between the _upstream_ and the
	6598	_push-remote_, see *note Branching::.
	6599
	6600	Also see *note (gitman)git-fetch::.
	6601
	6602	‘f’ (‘magit-fetch-popup’)
	6603
	6604	This prefix command shows the following suffix commands along with
	6605	the appropriate infix arguments in a popup buffer.
	6606
	6607	‘f p’ (‘magit-fetch-from-pushremote’)
	6608
	6609	Fetch from the push-remote of the current branch.
	6610
	6611	‘f u’ (‘magit-fetch-from-upstream’)
	6612
	6613	Fetch from the upstream of the current branch.
	6614
	6615	‘f e’ (‘magit-fetch-other’)
	6616
	6617	Fetch from another repository.
	6618
	6619	‘f o’ (‘magit-fetch-branch’)
	6620
	6621	Fetch a branch from a remote, both of which are read from the
	6622	minibuffer.
	6623
	6624	‘f r’ (‘magit-fetch-refspec’)
	6625
	6626	Fetch from a remote using an explicit refspec, both of which are
	6627	read from the minibuffer.
	6628
	6629	‘f a’ (‘magit-fetch-all’)
	6630
	6631	Fetch from all remotes.
	6632
	6633	‘f m’ (‘magit-submodule-fetch’)
	6634
	6635	Fetch all submodules. With a prefix argument fetch all remotes of
	6636	all submodules.
	6637
	6638	Instead of using one popup for fetching and another for pulling, you
	6639	could also use ‘magit-pull-and-fetch-popup’. See its doc-string for
	6640	more information.
	6641
	6642
	6643	File: magit.info, Node: Pulling, Next: Pushing, Prev: Fetching, Up: Transferring
	6644
	6645	7.3 Pulling
	6646	===========
	6647
	6648	For information about the differences between the _upstream_ and the
	6649	_push-remote_, see *note Branching::.
	6650
	6651	Also see *note (gitman)git-pull::.
	6652
	6653	‘F’ (‘magit-pull-popup’)
	6654
	6655	This prefix command shows the following suffix commands in a popup
	6656	buffer.
	6657
	6658	‘F p’ (‘magit-pull-from-pushremote’)
	6659
	6660	Pull from the push-remote of the current branch.
	6661
	6662	‘F u’ (‘magit-pull-from-upstream’)
	6663
	6664	Pull from the upstream of the current branch.
	6665
	6666	‘F e’ (‘magit-pull-branch’)
	6667
	6668	Pull from a branch read in the minibuffer.
	6669
	6670	Instead of using one popup for fetching and another for pulling, you
	6671	could also use ‘magit-pull-and-fetch-popup’. See its doc-string for
	6672	more information.
	6673
	6674
	6675	File: magit.info, Node: Pushing, Next: Creating and Sending Patches, Prev: Pulling, Up: Transferring
	6676
	6677	7.4 Pushing
	6678	===========
	6679
	6680	For information about the differences between the _upstream_ and the
	6681	_push-remote_, see *note Branching::.
	6682
	6683	Also see *note (gitman)git-push::.
	6684
	6685	‘P’ (‘magit-push-popup’)
	6686
	6687	This prefix command shows the following suffix commands along with
	6688	the appropriate infix arguments in a popup buffer.
	6689
	6690	‘P p’ (‘magit-push-current-to-pushremote’)
	6691
	6692	Push the current branch to ‘branch.<name>.pushRemote’ or if that is
	6693	unset to ‘remote.pushDefault’.
	6694
	6695	When ‘magit-push-current-set-remote-if-missing’ is non-nil and the
	6696	push-remote is not configured, then read the push-remote from the
	6697	user, set it, and then push to it. With a prefix argument the
	6698	push-remote can be changed before pushed to it.
	6699
	6700	‘P u’ (‘magit-push-current-to-upstream’)
	6701
	6702	Push the current branch to its upstream branch.
	6703
	6704	When ‘magit-push-current-set-remote-if-missing’ is non-nil and the
	6705	push-remote is not configured, then read the upstream from the
	6706	user, set it, and then push to it. With a prefix argument the
	6707	push-remote can be changed before pushed to it.
	6708
	6709	‘P e’ (‘magit-push-current’)
	6710
	6711	Push the current branch to a branch read in the minibuffer.
	6712
	6713	‘P o’ (‘magit-push-other’)
	6714
	6715	Push an arbitrary branch or commit somewhere. Both the source and
	6716	the target are read in the minibuffer.
	6717
	6718	‘P r’ (‘magit-push-refspecs’)
	6719
	6720	Push one or multiple refspecs to a remote, both of which are read
	6721	in the minibuffer.
	6722
	6723	To use multiple refspecs, separate them with commas. Completion is
	6724	only available for the part before the colon, or when no colon is
	6725	used.
	6726
	6727	‘P m’ (‘magit-push-matching’)
	6728
	6729	Push all matching branches to another repository. If multiple
	6730	remotes exit, then read one from the user. If just one exists, use
	6731	that without requiring confirmation.
	6732
	6733	‘P t’ (‘magit-push-tags’)
	6734
	6735	Push all tags to another repository. If only one remote exists,
	6736	then push to that. Otherwise prompt for a remote, offering the
	6737	remote configured for the current branch as default.
	6738
	6739	‘P T’ (‘magit-push-tag’)
	6740
	6741	Push a tag to another repository.
	6742
	6743	Two more push commands exist, which by default are not available from
	6744	the push popup. See their doc-strings for instructions on how to add
	6745	them to the popup.
	6746
	6747	-- Command: magit-push-implicitly args
	6748
	6749	Push somewhere without using an explicit refspec.
	6750
	6751	This command simply runs ‘git push -v [ARGS]’. ARGS are the
	6752	arguments specified in the popup buffer. No explicit refspec
	6753	arguments are used. Instead the behavior depends on at least these
	6754	Git variables: ‘push.default’, ‘remote.pushDefault’,
	6755	‘branch.<branch>.pushRemote’, ‘branch.<branch>.remote’,
	6756	‘branch.<branch>.merge’, and ‘remote.<remote>.push’.
	6757
	6758	-- Command: magit-push-to-remote remote args
	6759
	6760	Push to the remote REMOTE without using an explicit refspec. The
	6761	remote is read in the minibuffer.
	6762
	6763	This command simply runs ‘git push -v [ARGS] REMOTE’. ARGS are the
	6764	arguments specified in the popup buffer. No refspec arguments are
	6765	used. Instead the behavior depends on at least these Git
	6766	variables: ‘push.default’, ‘remote.pushDefault’,
	6767	‘branch.<branch>.pushRemote’, ‘branch.<branch>.remote’,
	6768	‘branch.<branch>.merge’, and ‘remote.<remote>.push’.
	6769
	6770	-- User Option: magit-push-current-set-remote-if-missing
	6771
	6772	This option controls whether missing remotes are configured before
	6773	pushing.
	6774
	6775	When ‘nil’, then the command ‘magit-push-current-to-pushremote’ and
	6776	‘magit-push-current-to-upstream’ do not appear in the push popup if
	6777	the push-remote resp. upstream is not configured. If the user
	6778	invokes one of these commands anyway, then it raises an error.
	6779
	6780	When ‘non-nil’, then these commands always appear in the push
	6781	popup. But if the required configuration is missing, then they do
	6782	appear in a way that indicates that this is the case. If the user
	6783	invokes one of them, then it asks for the necessary configuration,
	6784	stores the configuration, and then uses it to push a first time.
	6785
	6786	This option also affects whether the argument ‘--set-upstream’ is
	6787	available in the popup. If the value is ‘non-nil’, then that
	6788	argument is redundant. But note that changing the value of this
	6789	option does not take affect immediately, the argument will only be
	6790	added or removed after restarting Emacs.
	6791
	6792
	6793	File: magit.info, Node: Creating and Sending Patches, Next: Applying Patches, Prev: Pushing, Up: Transferring
	6794
	6795	7.5 Creating and Sending Patches
	6796	================================
	6797
	6798	‘W’ (‘magit-patch-popup’)
	6799
	6800	This prefix command shows the following suffix commands along with
	6801	the appropriate infix arguments in a popup buffer.
	6802
	6803	‘W p’ (‘magit-format-patch’)
	6804
	6805	Create patches for a set commits. If the region marks commits,
	6806	then create patches for those. Otherwise prompt for a range or a
	6807	single commit, defaulting to the commit at point.
	6808
	6809	‘W r’ (‘magit-request-pull’)
	6810
	6811	Request that upstream pulls from your public repository.
	6812
	6813	It is also possible to save a plain patch file by using ‘C-x C-w’
	6814	inside a ‘magit-diff-mode’ or ‘magit-revision-mode’ buffer.
	6815
	6816
	6817	File: magit.info, Node: Applying Patches, Prev: Creating and Sending Patches, Up: Transferring
	6818
	6819	7.6 Applying Patches
	6820	====================
	6821
	6822	Also see note (gitman)git-am::. and note (gitman)git-apply::.
	6823
	6824	‘w’ (‘magit-am-popup’)
	6825
	6826	This prefix command shows the following suffix commands along with
	6827	the appropriate infix arguments in a popup buffer.
	6828
	6829	‘w w’ (‘magit-am-apply-patches’)
	6830
	6831	Apply one or more patches. If the region marks files, then apply
	6832	those patches. Otherwise read a file name in the minibuffer
	6833	defaulting to the file at point.
	6834
	6835	‘w m’ (‘magit-am-apply-maildir’)
	6836
	6837	Apply the patches from a maildir.
	6838
	6839	When an "am" operation is in progress, then the popup buffer features
	6840	these commands instead.
	6841
	6842	‘w w’ (‘magit-am-continue’)
	6843
	6844	Resume the current patch applying sequence.
	6845
	6846	‘w s’ (‘magit-am-skip’)
	6847
	6848	Skip the stopped at patch during a patch applying sequence.
	6849
	6850	‘w a’ (‘magit-am-abort’)
	6851
	6852	Abort the current patch applying sequence. This discards all
	6853	changes made since the sequence started.
	6854
	6855	In addition to the commands listed at the top, the "am" popup also
	6856	has a binding for the related "patch" popup.
	6857
	6858	‘w a’ (‘magit-patch-apply-popup’)
	6859
	6860	This prefix command shows the following suffix commands along with
	6861	the appropriate infix arguments in a popup buffer.
	6862
	6863	‘w a a’ (‘magit-patch-apply’)
	6864
	6865	This command applies a simple patch file, which may not contain any
	6866	Git metadata in addition to the actual diff.
	6867
	6868
	6869	File: magit.info, Node: Miscellaneous, Next: Customizing, Prev: Transferring, Up: Top
	6870
	6871	8 Miscellaneous
	6872	***************
	6873
	6874	* Menu:
	6875
	6876	* Tagging::
	6877	* Notes::
	6878	* Submodules::
	6879	* Subtree::
	6880	* Worktree::
	6881	* Common Commands::
	6882	* Wip Modes::
	6883	* Minor Mode for Buffers Visiting Files::
	6884	* Minor Mode for Buffers Visiting Blobs::
	6885
	6886
	6887	File: magit.info, Node: Tagging, Next: Notes, Up: Miscellaneous
	6888
	6889	8.1 Tagging
	6890	===========
	6891
	6892	Also see *note (gitman)git-tag::.
	6893
	6894	‘t’ (‘magit-tag-popup’)
	6895
	6896	This prefix command shows the following suffix commands along with
	6897	the appropriate infix arguments in a popup buffer.
	6898
	6899	‘t t’ (‘magit-tag-create’)
	6900
	6901	Create a new tag with the given NAME at REV. With a prefix
	6902	argument annotate the tag.
	6903
	6904	‘t k’ (‘magit-tag-delete’)
	6905
	6906	Delete one or more tags. If the region marks multiple tags (and
	6907	nothing else), then offer to delete those. Otherwise, prompt for a
	6908	single tag to be deleted, defaulting to the tag at point.
	6909
	6910	‘t p’ (‘magit-tag-prune’)
	6911
	6912	Offer to delete tags missing locally from REMOTE, and vice versa.
	6913
	6914	-- Command: magit-tag-release
	6915
	6916	Create an opinionated release tag.
	6917
	6918	Assume version tags that match "\\‘v?[0-9]\*\\’". Prompt for the
	6919	name of the new tag using the highest existing tag as initial input
	6920	and call "git tag –annotate –sign -m MSG" TAG, regardless of
	6921	whether these arguments are enabled in the popup. Given a TAG
	6922	"v1.2.3" and a repository "/path/to/foo-bar", the MESSAGE would be
	6923	"Foo-Bar 1.2.3".
	6924
	6925	Because it is so opinionated, this command is not available from
	6926	the tag popup by default.
	6927
	6928
	6929	File: magit.info, Node: Notes, Next: Submodules, Prev: Tagging, Up: Miscellaneous
	6930
	6931	8.2 Notes
	6932	=========
	6933
	6934	Also see *note (gitman)git-notes::.
	6935
	6936	‘T’ (‘magit-notes-popup’)
	6937
	6938	This prefix command shows the following suffix commands along with
	6939	the appropriate infix arguments in a popup buffer.
	6940
	6941	‘T T’ (‘magit-notes-edit’)
	6942
	6943	Edit the note attached to a commit, defaulting to the commit at
	6944	point.
	6945
	6946	By default use the value of Git variable ‘core.notesRef’ or
	6947	"refs/notes/commits" if that is undefined.
	6948
	6949	‘T r’ (‘magit-notes-remove’)
	6950
	6951	Remove the note attached to a commit, defaulting to the commit at
	6952	point.
	6953
	6954	By default use the value of Git variable ‘core.notesRef’ or
	6955	"refs/notes/commits" if that is undefined.
	6956
	6957	‘T p’ (‘magit-notes-prune’)
	6958
	6959	Remove notes about unreachable commits.
	6960
	6961	It is possible to merge one note ref into another. That may result
	6962	in conflicts which have to resolved in the temporary worktree
	6963	".git/NOTES_MERGE_WORKTREE".
	6964
	6965	‘T m’ (‘magit-notes-merge’)
	6966
	6967	Merge the notes of a ref read from the user into the current notes
	6968	ref. The current notes ref is the value of Git variable
	6969	‘core.notesRef’ or "refs/notes/commits" if that is undefined.
	6970
	6971	When a notes merge is in progress then the popup features the
	6972	following suffix commands, instead of those listed above.
	6973
	6974	‘T c’ (‘magit-notes-merge-commit’)
	6975
	6976	Commit the current notes ref merge, after manually resolving
	6977	conflicts.
	6978
	6979	‘T a’ (‘magit-notes-merge-abort’)
	6980
	6981	Abort the current notes ref merge.
	6982
	6983	The following variables control what notes reference ‘magit-notes-*’,
	6984	‘git notes’ and ‘git show’ act on and display. Both the local and
	6985	global values are displayed and can be modified.
	6986
	6987	-- Variable: core.notesRef
	6988
	6989	This variable specifies the notes ref that is displayed by default
	6990	and which commands act on by default.
	6991
	6992	-- Variable: notes.displayRef
	6993
	6994	This variable specifies additional notes ref to be displayed in
	6995	addition to the ref specified by ‘core.notesRef’. It can have
	6996	multiple values and may end with ‘*’ to display all refs in the
	6997	‘refs/notes/’ namespace (or ‘**’ if some names contain slashes).
	6998
	6999
	7000	File: magit.info, Node: Submodules, Next: Subtree, Prev: Notes, Up: Miscellaneous
	7001
	7002	8.3 Submodules
	7003	==============
	7004
	7005	Also see *note (gitman)git-submodule::.
	7006
	7007	* Menu:
	7008
	7009	* Listing Submodules::
	7010	* Submodule Popup::
	7011
	7012
	7013	File: magit.info, Node: Listing Submodules, Next: Submodule Popup, Up: Submodules
	7014
	7015	8.3.1 Listing Submodules
	7016	------------------------
	7017
	7018	The command ‘magit-list-submodules’ displays a list of the current
	7019	repository’s submodules in a separate buffer. It’s also possible to
	7020	display information about submodules directly in the status buffer of
	7021	the super-repository by adding ‘magit-insert-submodules’ to the hook
	7022	‘magit-status-sections-hook’ as described in *note Status Module
	7023	Sections::.
	7024
	7025	-- Command: magit-list-submodules
	7026
	7027	This command displays a list of the current repository’s submodules
	7028	in a separate buffer.
	7029
	7030	It can be invoked by pressing ‘RET’ on the section titled
	7031	"Modules".
	7032
	7033	-- User Option: magit-submodule-list-columns
	7034
	7035	This option controls what columns are displayed by the command
	7036	‘magit-list-submodules’ and how they are displayed.
	7037
	7038	Each element has the form ‘(HEADER WIDTH FORMAT PROPS)’.
	7039
	7040	HEADER is the string displayed in the header. WIDTH is the width
	7041	of the column. FORMAT is a function that is called with one
	7042	argument, the repository identification (usually its basename), and
	7043	with ‘default-directory’ bound to the toplevel of its working tree.
	7044	It has to return a string to be inserted or nil. PROPS is an alist
	7045	that supports the keys ‘:right-align’ and ‘:pad-right’.
	7046
	7047	-- Function: magit-insert-submodules
	7048
	7049	Insert sections for all submodules. For each section insert the
	7050	path, the branch, and the output of ‘git describe --tags’, or,
	7051	failing that, the abbreviated HEAD commit hash.
	7052
	7053	Press ‘RET’ on such a submodule section to show its own status
	7054	buffer. Press ‘RET’ on the "Modules" section to display a list of
	7055	submodules in a separate buffer. This shows additional information
	7056	not displayed in the super-repository’s status buffer.
	7057
	7058
	7059	File: magit.info, Node: Submodule Popup, Prev: Listing Submodules, Up: Submodules
	7060
	7061	8.3.2 Submodule Popup
	7062	---------------------
	7063
	7064	‘o’ (‘magit-submodule-popup’)
	7065
	7066	This prefix command shows the following suffix commands along with
	7067	the appropriate infix arguments in a popup buffer.
	7068
	7069	Some of the below commands default to act on the modules that are
	7070	selected using the region. For brevity their description talk about
	7071	"the selected modules", but if no modules are selected, then they act on
	7072	the current module instead, or if point isn’t on a module, then the read
	7073	a single module to act on. With a prefix argument these commands ignore
	7074	the selection and the current module and instead act on all suitable
	7075	modules.
	7076
	7077	‘o a’ (‘magit-submodule-add’)
	7078
	7079	This commands adds the repository at URL as a module. Optional
	7080	PATH is the path to the module relative to the root of the
	7081	super-project. If it is nil then the path is determined based on
	7082	URL.
	7083
	7084	‘o r’ (‘magit-submodule-register’)
	7085
	7086	This command registers the selected modules by copying their urls
	7087	from ".gitmodules" to "$GIT_DIR/config". These values can then be
	7088	edited before running ‘magit-submodule-populate’. If you don’t
	7089	need to edit any urls, then use the latter directly.
	7090
	7091	‘o p’ (‘magit-submodule-populate’)
	7092
	7093	This command creates the working directory or directories of the
	7094	selected modules, checking out the recorded commits.
	7095
	7096	‘o u’ (‘magit-submodule-update’)
	7097
	7098	This command updates the selected modules checking out the recorded
	7099	commits.
	7100
	7101	‘o s’ (‘magit-submodule-synchronize’)
	7102
	7103	This command synchronizes the urls of the selected modules, copying
	7104	the values from ".gitmodules" to the ".git/config" of the
	7105	super-project as well those of the modules.
	7106
	7107	‘o d’ (‘magit-submodule-unpopulate’)
	7108
	7109	This command removes the working directory of the selected modules.
	7110
	7111	‘o l’ (‘magit-list-submodules’)
	7112
	7113	This command displays a list of the current repository’s modules.
	7114
	7115	‘o f’ (‘magit-fetch-modules’)
	7116
	7117	This command fetches all modules.
	7118
	7119	Option ‘magit-fetch-modules-jobs’ controls how many submodules are
	7120	being fetched in parallel. Also fetch the super-repository,
	7121	because ‘git fetch’ does not support not doing that. With a prefix
	7122	argument fetch all remotes.
	7123
	7124
	7125	File: magit.info, Node: Subtree, Next: Worktree, Prev: Submodules, Up: Miscellaneous
	7126
	7127	8.4 Subtree
	7128	===========
	7129
	7130	Also see *note (gitman)git-subtree::.
	7131
	7132	‘O’ (‘magit-tree-popup’)
	7133
	7134	This prefix command shows the following suffix commands along with
	7135	the appropriate infix arguments in a popup buffer.
	7136
	7137	Most infix arguments only apply to some of the ‘git subtree’
	7138	subcommands. When an argument that does not apply to the invoked
	7139	command is set, then it is silently ignored.
	7140
	7141	When the ‘--prefix’ argument is set in the popup buffer, then that is
	7142	used. Otherwise the prefix is read in the minibuffer.
	7143
	7144	‘O a’ (‘magit-subtree-add’)
	7145
	7146	Add COMMIT from REPOSITORY as a new subtree at PREFIX.
	7147
	7148	‘O c’ (‘magit-subtree-add-commit’)
	7149
	7150	Add COMMIT as a new subtree at PREFIX.
	7151
	7152	‘O m’ (‘magit-subtree-merge’)
	7153
	7154	Merge COMMIT into the PREFIX subtree.
	7155
	7156	‘O f’ (‘magit-subtree-pull’)
	7157
	7158	Pull COMMIT from REPOSITORY into the PREFIX subtree.
	7159
	7160	‘O p’ (‘magit-subtree-push’)
	7161
	7162	Extract the history of the subtree PREFIX and push it to REF on
	7163	REPOSITORY.
	7164
	7165	‘O s’ (‘magit-subtree-split’)
	7166
	7167	Extract the history of the subtree PREFIX.
	7168
	7169
	7170	File: magit.info, Node: Worktree, Next: Common Commands, Prev: Subtree, Up: Miscellaneous
	7171
	7172	8.5 Worktree
	7173	============
	7174
	7175	Also see *note (gitman)git-worktree::.
	7176
	7177	‘%’ (‘magit-worktree-popup’)
	7178
	7179	This prefix command shows the following suffix commands in a popup
	7180	buffer.
	7181
	7182	‘% b’ (‘magit-worktree-checkout’)
	7183
	7184	Checkout BRANCH in a new worktree at PATH.
	7185
	7186	‘% c’ (‘magit-worktree-branch’)
	7187
	7188	Create a new BRANCH and check it out in a new worktree at PATH.
	7189
	7190	‘% p’ (‘magit-worktree-checkout-pull-request’)
	7191
	7192	Create, configure and checkout a new worktree from a pull-request.
	7193
	7194	This is like ‘magit-checkout-pull-request’ (which see) except that
	7195	it also creates a new worktree.
	7196
	7197	‘% k’ (‘magit-worktree-delete’)
	7198
	7199	Delete a worktree, defaulting to the worktree at point. The
	7200	primary worktree cannot be deleted.
	7201
	7202	‘% g’ (‘magit-worktree-status’)
	7203
	7204	Show the status for the worktree at point.
	7205
	7206	If there is no worktree at point, then read one in the minibuffer.
	7207	If the worktree at point is the one whose status is already being
	7208	displayed in the current buffer, then show it in Dired instead.
	7209
	7210
	7211	File: magit.info, Node: Common Commands, Next: Wip Modes, Prev: Worktree, Up: Miscellaneous
	7212
	7213	8.6 Common Commands
	7214	===================
	7215
	7216	These are some of the commands that can be used in all buffers whose
	7217	major-modes derive from ‘magit-mode’. There are other common commands
	7218	beside the ones below, but these didn’t fit well anywhere else.
	7219
	7220	‘M-w’ (‘magit-copy-section-value’)
	7221
	7222	This command saves the value of the current section to the
	7223	‘kill-ring’, and, provided that the current section is a commit,
	7224	branch, or tag section, it also pushes the (referenced) revision to
	7225	the ‘magit-revision-stack’.
	7226
	7227	When the current section is a branch or a tag, and a prefix
	7228	argument is used, then it saves the revision at its tip to the
	7229	‘kill-ring’ instead of the reference name.
	7230
	7231	‘C-w’ (‘magit-copy-buffer-revision’)
	7232
	7233	This command saves the revision being displayed in the current
	7234	buffer to the ‘kill-ring’ and also pushes it to the
	7235	‘magit-revision-stack’. It is mainly intended for use in
	7236	‘magit-revision-mode’ buffers, the only buffers where it is always
	7237	unambiguous exactly which revision should be saved.
	7238
	7239	Most other Magit buffers usually show more than one revision, in
	7240	some way or another, so this command has to select one of them, and
	7241	that choice might not always be the one you think would have been
	7242	the best pick.
	7243
	7244	Outside of Magit ‘M-w’ and ‘C-w’ are usually bound to
	7245	‘kill-ring-save’ and ‘kill-region’, and these commands would also be
	7246	useful in Magit buffers. Therefore when the region is active, then both
	7247	of these commands behave like ‘kill-ring-save’ instead of as described
	7248	above.
	7249
	7250
	7251	File: magit.info, Node: Wip Modes, Next: Minor Mode for Buffers Visiting Files, Prev: Common Commands, Up: Miscellaneous
	7252
	7253	8.7 Wip Modes
	7254	=============
	7255
	7256	Git keeps committed changes around long enough for users to recover
	7257	changes they have accidentally deleted. It does so by not garbage
	7258	collecting any committed but no longer referenced objects for a certain
	7259	period of time, by default 30 days.
	7260
	7261	But Git does not keep track of uncommitted changes in the working
	7262	tree and not even the index (the staging area). Because Magit makes it
	7263	so convenient to modify uncommitted changes, it also makes it easy to
	7264	shoot yourself in the foot in the process.
	7265
	7266	For that reason Magit provides a global mode that saves tracked
	7267	files to work-in-progress references after or before certain actions.
	7268	(At present untracked files are never saved and for technical reasons
	7269	nothing is saved before the first commit has been created).
	7270
	7271	Two separate work-in-progress references are used to track the state
	7272	of the index and of the working tree: ‘refs/wip/index/<branchref>’ and
	7273	‘refs/wip/wtree/<branchref>’, where ‘<branchref>’ is the full ref of the
	7274	current branch, e.g. ‘refs/heads/master’. When the ‘HEAD’ is detached
	7275	then ‘HEAD’ is used in place of ‘<branchref>’.
	7276
	7277	Checking out another branch (or detaching ‘HEAD’) causes the use of
	7278	different wip refs for subsequent changes.
	7279
	7280	-- User Option: magit-wip-mode
	7281
	7282	When this mode is enabled, then uncommitted changes are committed
	7283	to dedicated work-in-progress refs whenever appropriate (i.e. when
	7284	dataloss would be a possibility otherwise).
	7285
	7286	Setting this variable directly does not take effect; either use the
	7287	Custom interface to do so or call the respective mode function.
	7288
	7289	For historic reasons this mode is implemented on top of four other
	7290	‘magit-wip-*’ modes, which can also be used individually, if you
	7291	want finer control over when the wip refs are updated; but that is
	7292	discouraged. See *note Legacy Wip Modes::.
	7293
	7294	To view the log for a branch and its wip refs use the commands
	7295	‘magit-wip-log’ and ‘magit-wip-log-current’. You should use ‘--graph’
	7296	when using these commands.
	7297
	7298	-- Command: magit-wip-log
	7299
	7300	This command shows the log for a branch and its wip refs. With a
	7301	negative prefix argument only the worktree wip ref is shown.
	7302
	7303	The absolute numeric value of the prefix argument controls how many
	7304	"branches" of each wip ref are shown. This is only relevant if the
	7305	value of ‘magit-wip-merge-branch’ is ‘nil’.
	7306
	7307	-- Command: magit-wip-log-current
	7308
	7309	This command shows the log for the current branch and its wip refs.
	7310	With a negative prefix argument only the worktree wip ref is shown.
	7311
	7312	The absolute numeric value of the prefix argument controls how many
	7313	"branches" of each wip ref are shown. This is only relevant if the
	7314	value of ‘magit-wip-merge-branch’ is ‘nil’.
	7315
	7316	‘X w’ (‘magit-reset-worktree’)
	7317
	7318	This command resets the working tree to some commit read from the
	7319	user and defaulting to the commit at point, while keeping the
	7320	‘HEAD’ and index as-is.
	7321
	7322	This can be used to restore files to the state committed to a wip
	7323	ref. Note that this will discard any unstaged changes that might
	7324	have existed before invoking this command (but of course only after
	7325	committing that to the working tree wip ref).
	7326
	7327	Note that even if you enable ‘magit-wip-mode’ this won’t give you
	7328	perfect protection. The most likely scenario for losing changes despite
	7329	the use of ‘magit-wip-mode’ is making a change outside Emacs and then
	7330	destroying it also outside Emacs. In some such a scenario, Magit, being
	7331	an Emacs package, didn’t get the opportunity to keep you from shooting
	7332	yourself in the foot.
	7333
	7334	When you are unsure whether Magit did commit a change to the wip
	7335	refs, then you can explicitly request that all changes to all tracked
	7336	files are being committed.
	7337
	7338	‘M-x magit-wip-commit’ (‘magit-wip-commit’)
	7339
	7340	This command commits all changes to all tracked files to the index
	7341	and working tree work-in-progress refs. Like the modes described
	7342	above, it does not commit untracked files, but it does check all
	7343	tracked files for changes. Use this command when you suspect that
	7344	the modes might have overlooked a change made outside Emacs/Magit.
	7345
	7346	-- User Option: magit-wip-namespace
	7347
	7348	The namespace used for work-in-progress refs. It has to end with a
	7349	slash. The wip refs are named ‘<namespace>index/<branchref>’ and
	7350	‘<namespace>wtree/<branchref>’. When snapshots are created while
	7351	the ‘HEAD’ is detached then ‘HEAD’ is used in place of
	7352	‘<branchref>’.
	7353
	7354	-- User Option: magit-wip-mode-lighter
	7355
	7356	Mode-line lighter for ‘magit-wip--mode’.
	7357
	7358	* Menu:
	7359
	7360	* Wip Graph::
	7361	* Legacy Wip Modes::
	7362
	7363
	7364	File: magit.info, Node: Wip Graph, Next: Legacy Wip Modes, Up: Wip Modes
	7365
	7366	8.7.1 Wip Graph
	7367	---------------
	7368
	7369	-- User Option: magit-wip-merge-branch
	7370
	7371	This option controls whether the current branch is merged into the
	7372	wip refs after a new commit was created on the branch.
	7373
	7374	If non-nil and the current branch has new commits, then it is
	7375	merged into the wip ref before creating a new wip commit. This
	7376	makes it easier to inspect wip history and the wip commits are
	7377	never garbage collected.
	7378
	7379	If nil and the current branch has new commits, then the wip ref is
	7380	reset to the tip of the branch before creating a new wip commit.
	7381	With this setting wip commits are eventually garbage collected.
	7382
	7383	When ‘magit-wip-merge-branch’ is ‘t’, then the history looks like
	7384	this:
	7385
	7386	---------- refs/wip/index/refs/heads/master
	7387	/ / /
	7388	A-----B-----C refs/heads/master
	7389
	7390	When ‘magit-wip-merge-branch’ is ‘nil’, then creating a commit on the
	7391	real branch and then making a change causes the wip refs to be recreated
	7392	to fork from the new commit. But the old commits on the wip refs are
	7393	not lost. They are still available from the reflog. To make it easier
	7394	to see when the fork point of a wip ref was changed, an additional
	7395	commit with the message "restart autosaving" is created on it (‘xxO’
	7396	commits below are such boundary commits).
	7397
	7398	Starting with
	7399
	7400	BI0---BI1 refs/wip/index/refs/heads/master
	7401	/
	7402	A---B refs/heads/master
	7403	\
	7404	BW0---BW1 refs/wip/wtree/refs/heads/master
	7405
	7406	and committing the staged changes and editing and saving a file would
	7407	result in
	7408
	7409	BI0---BI1 refs/wip/index/refs/heads/master
	7410	/
	7411	A---B---C refs/heads/master
	7412	\ \
	7413	\ CW0---CW1 refs/wip/wtree/refs/heads/master
	7414	\
	7415	BW0---BW1 refs/wip/wtree/refs/heads/master@{2}
	7416
	7417	The fork-point of the index wip ref is not changed until some change
	7418	is being staged. Likewise just checking out a branch or creating a
	7419	commit does not change the fork-point of the working tree wip ref. The
	7420	fork-points are not adjusted until there actually is a change that
	7421	should be committed to the respective wip ref.
	7422
	7423
	7424	File: magit.info, Node: Legacy Wip Modes, Prev: Wip Graph, Up: Wip Modes
	7425
	7426	8.7.2 Legacy Wip Modes
	7427	----------------------
	7428
	7429	It is recommended that you use the mode ‘magit-wip-mode’ (which see) and
	7430	ignore the existence of the following modes, which are preserved for
	7431	historic reasons.
	7432
	7433	Setting the following variables directly does not take effect; either
	7434	use the Custom interface to do so or call the respective mode functions.
	7435
	7436	-- User Option: magit-wip-after-save-mode
	7437
	7438	When this mode is enabled, then saving a buffer that visits a file
	7439	tracked in a Git repository causes its current state to be
	7440	committed to the working tree wip ref for the current branch.
	7441
	7442	-- User Option: magit-wip-after-apply-mode
	7443
	7444	When this mode is enabled, then applying (i.e. staging, unstaging,
	7445	discarding, reversing, and regularly applying) a change to a file
	7446	tracked in a Git repository causes its current state to be
	7447	committed to the index and/or working tree wip refs for the current
	7448	branch.
	7449
	7450	If you only ever edit files using Emacs and only ever interact with
	7451	Git using Magit, then the above two modes should be enough to protect
	7452	each and every change from accidental loss. In practice nobody does
	7453	that. Two additional modes exists that do commit to the wip refs before
	7454	making changes that could cause the loss of earlier changes.
	7455
	7456	-- User Option: magit-wip-before-change-mode
	7457
	7458	When this mode is enabled, then certain commands commit the
	7459	existing changes to the files they are about to make changes to.
	7460
	7461	-- User Option: magit-wip-initial-backup-mode
	7462
	7463	When this mode is enabled, then the current version of a file is
	7464	committed to the worktree wip ref before the buffer visiting that
	7465	file is saved for the first time since the buffer was created.
	7466
	7467	This backs up the same version of the file that ‘backup-buffer’
	7468	would save. While ‘backup-buffer’ uses a backup file, this mode
	7469	uses the same worktree wip ref as used by the other Magit Wip
	7470	modes. Like ‘backup-buffer’, it only does this once; unless you
	7471	kill the buffer and visit the file again only one backup will be
	7472	created per Emacs session.
	7473
	7474	This mode ignores the variables that affect ‘backup-buffer’ and can
	7475	be used along-side that function, which is recommended because it
	7476	only backs up files that are tracked in a Git repository.
	7477
	7478	-- User Option: magit-wip-after-save-local-mode-lighter
	7479
	7480	Mode-line lighter for ‘magit-wip-after-save-local-mode’.
	7481
	7482	-- User Option: magit-wip-after-apply-mode-lighter
	7483
	7484	Mode-line lighter for ‘magit-wip-after-apply-mode’.
	7485
	7486	-- User Option: magit-wip-before-change-mode-lighter
	7487
	7488	Mode-line lighter for ‘magit-wip-before-change-mode’.
	7489
	7490	-- User Option: magit-wip-initial-backup-mode-lighter
	7491
	7492	Mode-line lighter for ‘magit-wip-initial-backup-mode’.
	7493
	7494
	7495	File: magit.info, Node: Minor Mode for Buffers Visiting Files, Next: Minor Mode for Buffers Visiting Blobs, Prev: Wip Modes, Up: Miscellaneous
	7496
	7497	8.8 Minor Mode for Buffers Visiting Files
	7498	=========================================
	7499
	7500	The ‘magit-file-mode’ enables certain Magit features in file-visiting
	7501	buffers belonging to a Git repository. It should be enabled globally
	7502	using ‘global-magit-file-mode’. Currently this mode only establishes a
	7503	few key bindings, but this might be extended in the future.
	7504
	7505	-- User Option: magit-file-mode
	7506
	7507	Whether to establish certain Magit key bindings in all
	7508	file-visiting buffers belonging to a Git repository. This
	7509	establishes the bindings suggested in *note Getting Started:: (but
	7510	only for file-visiting buffers), and additionally binds ‘C-c M-g’
	7511	to ‘magit-file-popup’.
	7512
	7513	‘C-c M-g’ (‘magit-file-popup’)
	7514
	7515	This prefix command shows a popup buffer featuring suffix commands
	7516	that operate on the file being visited in the current buffer.
	7517
	7518	‘C-c M-g s’ (‘magit-stage-file’)
	7519
	7520	Stage all changes to the file being visited in the current buffer.
	7521
	7522	‘C-c M-g u’ (‘magit-unstage-file’)
	7523
	7524	Unstage all changes to the file being visited in the current
	7525	buffer.
	7526
	7527	‘C-c M-g c’ (‘magit-commit-popup’)
	7528
	7529	This prefix command shows suffix commands along with the
	7530	appropriate infix arguments in a popup buffer. See *note
	7531	Initiating a Commit::.
	7532
	7533	‘C-c M-g D’ (‘magit-diff-buffer-file-popup’)
	7534
	7535	This prefix command shows the same suffix commands and infix
	7536	arguments in a popup buffer as ‘magit-diff-popup’. But this
	7537	variant has to be called from a file-visiting buffer and the
	7538	visited file is automatically used in the popup to limit the diff
	7539	to that file.
	7540
	7541	‘C-c M-g d’ (‘magit-diff-buffer-file’)
	7542
	7543	This command shows the diff for the file of blob that the current
	7544	buffer visits.
	7545
	7546	-- User Option: magit-diff-buffer-file-locked
	7547
	7548	This option controls whether ‘magit-diff-buffer-file’ uses a
	7549	dedicated buffer. See *note Modes and Buffers::.
	7550
	7551	‘C-c M-g L’ (‘magit-log-buffer-file-popup’)
	7552
	7553	This prefix command shows the same suffix commands and infix
	7554	arguments in a popup buffer as ‘magit-log-popup’. But this variant
	7555	has to be called from a file-visiting buffer and the visited file
	7556	is automatically used in the popup to limit the log to that file.
	7557
	7558	‘C-c M-g l’ (‘magit-log-buffer-file’)
	7559
	7560	This command shows the log for the file of blob that the current
	7561	buffer visits. Renames are followed when a prefix argument is used
	7562	or when ‘--follow’ is part of ‘magit-log-arguments’. When the
	7563	region is active, the log is restricted to the selected line range.
	7564
	7565	‘C-c M-g t’ (‘magit-log-trace-definition’)
	7566
	7567	This command shows the log for the definition at point.
	7568
	7569	-- User Option: magit-log-buffer-file-locked
	7570
	7571	This option controls whether ‘magit-log-buffer-file’ uses a
	7572	dedicated buffer. See *note Modes and Buffers::.
	7573
	7574	‘C-c M-g B’ (‘magit-blame-popup’)
	7575
	7576	This prefix command shows all blaming suffix command along with the
	7577	appropriate infix arguments in a popup buffer. See *note
	7578	Blaming::.
	7579
	7580	‘C-c M-g b’ (‘magit-blame-addition’)
	7581
	7582	This command shows for each line the revision in which it was
	7583	added.
	7584
	7585	‘C-c M-g r’ (‘magit-blame-removal’)
	7586
	7587	This command shows for each line the revision in which it was
	7588	removed. This command is only available in blob-visiting buffers.
	7589
	7590	‘C-c M-g f’ (‘magit-blame-reverse’)
	7591
	7592	This command shows for each line the last revision in which it
	7593	still exists. This command is only available in blob-visiting
	7594	buffers.
	7595
	7596	‘C-c M-g e’ (‘magit-edit-line-commit’)
	7597
	7598	This command makes the commit editable that added the current line.
	7599
	7600	With a prefix argument it makes the commit editable that removes
	7601	the line, if any. The commit is determined using ‘git blame’ and
	7602	made editable using ‘git rebase --interactive’ if it is reachable
	7603	from ‘HEAD’, or by checking out the commit (or a branch that points
	7604	at it) otherwise.
	7605
	7606	‘C-c M-g p’ (‘magit-blob-previous’)
	7607
	7608	Visit the previous blob which modified the current file.
	7609
	7610	There are a few additional commands that operate on a single file but
	7611	are not available from the file popup by default:
	7612
	7613	-- Command: magit-file-rename
	7614
	7615	This command renames a file read from the user.
	7616
	7617	-- Command: magit-file-delete
	7618
	7619	This command deletes a file read from the user.
	7620
	7621	-- Command: magit-file-untrack
	7622
	7623	This command untracks a file read from the user.
	7624
	7625	-- Command: magit-file-checkout
	7626
	7627	This command updates a file in the working tree and index to the
	7628	contents from a revision. Both the revision and file are read from
	7629	the user.
	7630
	7631	You could add them to the popup like so:
	7632
	7633	(magit-define-popup-action 'magit-file-popup
	7634	?R "Rename file" 'magit-file-rename)
	7635	(magit-define-popup-action 'magit-file-popup
	7636	?K "Delete file" 'magit-file-delete)
	7637	(magit-define-popup-action 'magit-file-popup
	7638	?U "Untrack file" 'magit-file-untrack)
	7639	(magit-define-popup-action 'magit-file-popup
	7640	?C "Checkout file" 'magit-file-checkout)
	7641
	7642
	7643	File: magit.info, Node: Minor Mode for Buffers Visiting Blobs, Prev: Minor Mode for Buffers Visiting Files, Up: Miscellaneous
	7644
	7645	8.9 Minor Mode for Buffers Visiting Blobs
	7646	=========================================
	7647
	7648	The ‘magit-blob-mode’ enables certain Magit features in blob-visiting
	7649	buffers. Such buffers can be created using ‘magit-find-file’ and some
	7650	of the commands mentioned below, which also take care of turning on this
	7651	minor mode. Currently this mode only establishes a few key bindings,
	7652	but this might be extended.
	7653
	7654	‘p’ (‘magit-blob-previous’)
	7655
	7656	Visit the previous blob which modified the current file.
	7657
	7658	‘n’ (‘magit-blob-next’)
	7659
	7660	Visit the next blob which modified the current file.
	7661
	7662	‘q’ (‘magit-kill-this-buffer’)
	7663
	7664	Kill the current buffer.
	7665
	7666
	7667	File: magit.info, Node: Customizing, Next: Plumbing, Prev: Miscellaneous, Up: Top
	7668
	7669	9 Customizing
	7670	*************
	7671
	7672	Both Git and Emacs are highly customizable. Magit is both a Git
	7673	porcelain as well as an Emacs package, so it makes sense to customize it
	7674	using both Git variables as well as Emacs options. However this
	7675	flexibility doesn’t come without problems, including but not limited to
	7676	the following.
	7677
	7678	• Some Git variables automatically have an effect in Magit without
	7679	requiring any explicit support. Sometimes that is desirable - in
	7680	other cases, it breaks Magit.
	7681
	7682	When a certain Git setting breaks Magit but you want to keep using
	7683	that setting on the command line, then that can be accomplished by
	7684	overriding the value for Magit only by appending something like
	7685	‘("-c" "some.variable=compatible-value")’ to
	7686	‘magit-git-global-arguments’.
	7687
	7688	• Certain settings like ‘fetch.prune=true’ are respected by Magit
	7689	commands (because they simply call the respective Git command) but
	7690	their value is not reflected in the respective popup buffers. In
	7691	this case the ‘--prune’ argument in ‘magit-fetch-popup’ might be
	7692	active or inactive depending on the value of
	7693	‘magit-fetch-arguments’ only, but that doesn’t keep the Git
	7694	variable from being honored by the suffix commands anyway. So
	7695	pruning might happen despite the ‘--prune’ arguments being
	7696	displayed in a way that seems to indicate that no pruning will
	7697	happen.
	7698
	7699	I intend to address these and similar issues in a future release.
	7700
	7701	* Menu:
	7702
	7703	* Per-Repository Configuration::
	7704	* Essential Settings::
	7705
	7706
	7707	File: magit.info, Node: Per-Repository Configuration, Next: Essential Settings, Up: Customizing
	7708
	7709	9.1 Per-Repository Configuration
	7710	================================
	7711
	7712	Magit can be configured on a per-repository level using both Git
	7713	variables as well as Emacs options.
	7714
	7715	To set a Git variable for one repository only, simply set it in
	7716	‘/path/to/repo/.git/config’ instead of ‘$HOME/.gitconfig’ or
	7717	‘/etc/gitconfig’. See *note (gitman)git-config::.
	7718
	7719	Similarly, Emacs options can be set for one repository only by
	7720	editing ‘/path/to/repo/.dir-locals.el’. See *note (emacs)Directory
	7721	Variables::. For example to disable automatic refreshes of
	7722	file-visiting buffers in just one huge repository use this:
	7723
	7724	• ‘/path/to/huge/repo/.dir-locals.el’
	7725
	7726	((nil . ((magit-refresh-buffers . nil))))
	7727
	7728	If you want to apply the same settings to several, but not all,
	7729	repositories then keeping the repository-local config files in sync
	7730	would quickly become annoying. To avoid that you can create config
	7731	files for certain classes of repositories (e.g. "huge repositories")
	7732	and then include those files in the per-repository config files. For
	7733	example:
	7734
	7735	• ‘/path/to/huge/repo/.git/config’
	7736
	7737	[include]
	7738	path = /path/to/huge-gitconfig
	7739
	7740	• ‘/path/to/huge-gitconfig’
	7741
	7742	[status]
	7743	showUntrackedFiles = no
	7744
	7745	• ‘$HOME/.emacs.d/init.el’
	7746
	7747	(dir-locals-set-class-variables 'huge-git-repository
	7748	'((nil . ((magit-refresh-buffers . nil)))))
	7749
	7750	(dir-locals-set-directory-class
	7751	"/path/to/huge/repo/" 'huge-git-repository)
	7752
	7753
	7754	File: magit.info, Node: Essential Settings, Prev: Per-Repository Configuration, Up: Customizing
	7755
	7756	9.2 Essential Settings
	7757	======================
	7758
	7759	The next two sections list and discuss several variables that many users
	7760	might want to customize, for safety and/or performance reasons.
	7761
	7762	* Menu:
	7763
	7764	* Safety::
	7765	* Performance::
	7766
	7767
	7768	File: magit.info, Node: Safety, Next: Performance, Up: Essential Settings
	7769
	7770	9.2.1 Safety
	7771	------------
	7772
	7773	This section discusses various variables that you might want to change
	7774	(or not change) for safety reasons.
	7775
	7776	Git keeps committed changes around long enough for users to recover
	7777	changes they have accidentally been deleted. It does not do the same
	7778	for uncommitted changes in the working tree and not even the index
	7779	(the staging area). Because Magit makes it so easy to modify
	7780	uncommitted changes, it also makes it easy to shoot yourself in the foot
	7781	in the process. For that reason Magit provides three global modes that
	7782	save tracked files to work-in-progress references after or before
	7783	certain actions. See *note Wip Modes::.
	7784
	7785	These modes are not enabled by default because of performance
	7786	concerns. Instead a lot of potentially destructive commands require
	7787	confirmation every time they are used. In many cases this can be
	7788	disabled by adding a symbol to ‘magit-no-confirm’ (see *note Completion
	7789	and Confirmation::). If you enable the various wip modes then you
	7790	should add ‘safe-with-wip’ to this list.
	7791
	7792	Similarly it isn’t necessary to require confirmation before moving a
	7793	file to the system trash - if you trashed a file by mistake then you can
	7794	recover it from the there. Option ‘magit-delete-by-moving-to-trash’
	7795	controls whether the system trash is used, which is the case by default.
	7796	Nevertheless, ‘trash’ isn’t a member of ‘magit-no-confirm’ - you might
	7797	want to change that.
	7798
	7799	By default buffers visiting files are automatically reverted when the
	7800	visited file changes on disk. This isn’t as risky as it might seem, but
	7801	to make an informed decision you should see *note Risk of Reverting
	7802	Automatically::.
	7803
	7804
	7805	File: magit.info, Node: Performance, Prev: Safety, Up: Essential Settings
	7806
	7807	9.2.2 Performance
	7808	-----------------
	7809
	7810	After Magit has run ‘git’ for side-effects, it also refreshes the
	7811	current Magit buffer and the respective status buffer. This is
	7812	necessary because otherwise outdated information might be displayed
	7813	without the user noticing. Magit buffers are updated by recreating
	7814	their content from scratch, which makes updating simpler and less
	7815	error-prone, but also more costly. Keeping it simple and just
	7816	re-creating everything from scratch is an old design decision and
	7817	departing from that will require major refactoring.
	7818
	7819	I plan to do that in time for the next major release. I also intend
	7820	to create logs and diffs asynchronously, which should also help a lot
	7821	but also requires major refactoring.
	7822
	7823	Meanwhile you can tell Magit to only automatically refresh the
	7824	current Magit buffer, but not the status buffer. If you do that, then
	7825	the status buffer is only refreshed automatically if it is the current
	7826	buffer.
	7827
	7828	(setq magit-refresh-status-buffer nil)
	7829
	7830	You should also check whether any third-party packages have added
	7831	anything to ‘magit-refresh-buffer-hook’, ‘magit-status-refresh-hook’,
	7832	‘magit-pre-refresh-hook’, and ‘magit-post-refresh-hook’. If so, then
	7833	check whether those additions impact performance significantly. Setting
	7834	‘magit-refresh-verbose’ and then inspecting the output in the
	7835	‘Messages’ buffer, should help doing so.
	7836
	7837	Magit also reverts buffers for visited files located inside the
	7838	current repository when the visited file changes on disk. That is
	7839	implemented on top of ‘auto-revert-mode’ from the built-in library
	7840	‘autorevert’. To figure out whether that impacts performance, check
	7841	whether performance is significantly worse, when many buffers exist
	7842	and/or when some buffers visit files using TRAMP. If so, then this
	7843	should help.
	7844
	7845	(setq auto-revert-buffer-list-filter
	7846	'magit-auto-revert-repository-buffers-p)
	7847
	7848	For alternative approaches see *note Automatic Reverting of
	7849	File-Visiting Buffers::.
	7850
	7851	If you have enabled any features that are disabled by default, then
	7852	you should check whether they impact performance significantly. It’s
	7853	likely that they were not enabled by default because it is known that
	7854	they reduce performance at least in large repositories.
	7855
	7856	If performance is only slow inside certain unusually large
	7857	repositories, then you might want to disable certain features on a
	7858	per-repository or per-repository-class basis only. See *note
	7859	Per-Repository Configuration::.
	7860
	7861	* Menu:
	7862
	7863	* Microsoft Windows Performance::
	7864	* MacOS Performance::
	7865
	7866	Log Performance
	7867	...............
	7868
	7869	When showing logs, Magit limits the number of commits initially shown in
	7870	the hope that this avoids unnecessary work. When using ‘--graph’ is
	7871	used, then this unfortunately does not have the desired effect for large
	7872	histories. Junio, Git’s maintainer, said on the git mailing list
	7873	(<http://www.spinics.net/lists/git/msg232230.html>): "‘--graph’ wants to
	7874	compute the whole history and the max-count only affects the output
	7875	phase after ‘--graph’ does its computation".
	7876
	7877	In other words, it’s not that Git is slow at outputting the
	7878	differences, or that Magit is slow at parsing the output - the problem
	7879	is that Git first goes outside and has a smoke.
	7880
	7881	We actually work around this issue by limiting the number of commits
	7882	not only by using ‘-<N>’ but by also using a range. But unfortunately
	7883	that’s not always possible.
	7884
	7885	In repositories with more than a few thousand commits ‘--graph’
	7886	should never be a member of ‘magit-log-section-arguments’. That
	7887	variable is used in the status buffer which is refreshed every time you
	7888	run any Magit command.
	7889
	7890	Using ‘--color --graph’ is even slower. Magit uses code that is part
	7891	of Emacs to turn control characters into faces. That code is pretty
	7892	slow and this is quite noticeable when showing a log with many branches
	7893	and merges. For that reason ‘--color’ is not enabled by default
	7894	anymore. Consider leaving it at that.
	7895
	7896	Diff Performance
	7897	................
	7898
	7899	If diffs are slow, then consider turning off some optional diff features
	7900	by setting all or some of the following variables to ‘nil’:
	7901	‘magit-diff-highlight-indentation’, ‘magit-diff-highlight-trailing’,
	7902	‘magit-diff-paint-whitespace’, ‘magit-diff-highlight-hunk-body’, and
	7903	‘magit-diff-refine-hunk’.
	7904
	7905	When showing a commit instead of some arbitrary diff, then some
	7906	additional information is displayed. Calculating this information can
	7907	be quite expensive given certain circumstances. If looking at a commit
	7908	using ‘magit-revision-mode’ takes considerably more time than looking at
	7909	the same commit in ‘magit-diff-mode’, then consider setting
	7910	‘magit-revision-insert-related-refs’ to ‘nil’.
	7911
	7912	Refs Buffer Performance
	7913	.......................
	7914
	7915	When refreshing the "references buffer" is slow, then that’s usually
	7916	because several hundred refs are being displayed. The best way to
	7917	address that is to display fewer refs, obviously.
	7918
	7919	If you are not, or only mildly, interested in seeing the list of
	7920	tags, then start by not displaying them:
	7921
	7922	(remove-hook 'magit-refs-sections-hook 'magit-insert-tags)
	7923
	7924	Then you should also make sure that the listed remote branches
	7925	actually all exist. You can do so by pruning branches which no longer
	7926	exist using ‘f-pa’.
	7927
	7928	Committing Performance
	7929	......................
	7930
	7931	When you initiate a commit, then Magit by default automatically shows a
	7932	diff of the changes you are about to commit. For large commits this can
	7933	take a long time, which is especially distracting when you are
	7934	committing large amounts of generated data which you don’t actually
	7935	intend to inspect before committing. This behavior can be turned off
	7936	using:
	7937
	7938	(remove-hook 'server-switch-hook 'magit-commit-diff)
	7939
	7940	Then you can type ‘C-c C-d’ to show the diff when you actually want
	7941	to see it, but only then. Alternatively you can leave the hook alone
	7942	and just type ‘C-g’ in those cases when it takes too long to generate
	7943	the diff. If you do that, then you will end up with a broken diff
	7944	buffer, but doing it this way has the advantage that you usually get to
	7945	see the diff, which is useful because it increases the odds that you
	7946	spot potential issues.
	7947
	7948	The Built-In VC Package
	7949	.......................
	7950
	7951	Emacs comes with a version control interface called "VC", see *note
	7952	(emacs)Version Control::. It is enabled be default, and if you don’t
	7953	use it in addition to Magit, then you should disable it to keep it from
	7954	performing unnecessary work:
	7955
	7956	(setq vc-handled-backends nil)
	7957
	7958	You can also disable its use for Git but keep using it when using
	7959	another version control system:
	7960
	7961	(setq vc-handled-backends (delq 'Git vc-handled-backends))
	7962