From bdf9a71ab7baa2b1de9abcfd5df1a9107a55d141 Mon Sep 17 00:00:00 2001 From: Jack Jamison Date: Sun, 5 Jul 2026 01:19:30 -0400 Subject: add a bunch of emacs packages HELP --- .config/emacs/lisp/magit/docs/.orgconfig | 18 + .config/emacs/lisp/magit/docs/AUTHORS.md | 428 + .config/emacs/lisp/magit/docs/BACKERS.md | 1402 +++ .config/emacs/lisp/magit/docs/Makefile | 208 + .config/emacs/lisp/magit/docs/RelNotes/0.5.1.txt | 11 + .config/emacs/lisp/magit/docs/RelNotes/0.6.1.txt | 24 + .config/emacs/lisp/magit/docs/RelNotes/0.7.0.txt | 70 + .config/emacs/lisp/magit/docs/RelNotes/0.8.0.txt | 55 + .config/emacs/lisp/magit/docs/RelNotes/0.8.1.txt | 28 + .config/emacs/lisp/magit/docs/RelNotes/0.8.2.txt | 27 + .config/emacs/lisp/magit/docs/RelNotes/1.0.0.txt | 84 + .config/emacs/lisp/magit/docs/RelNotes/1.1.0.txt | 112 + .config/emacs/lisp/magit/docs/RelNotes/1.1.1.txt | 25 + .config/emacs/lisp/magit/docs/RelNotes/1.1.2.txt | 33 + .config/emacs/lisp/magit/docs/RelNotes/1.2.0.txt | 73 + .config/emacs/lisp/magit/docs/RelNotes/1.2.1.txt | 15 + .config/emacs/lisp/magit/docs/RelNotes/1.2.2.txt | 17 + .config/emacs/lisp/magit/docs/RelNotes/1.4.0.txt | 231 + .config/emacs/lisp/magit/docs/RelNotes/1.4.1.txt | 31 + .config/emacs/lisp/magit/docs/RelNotes/1.4.2.txt | 23 + .config/emacs/lisp/magit/docs/RelNotes/2.1.0.txt | 433 + .config/emacs/lisp/magit/docs/RelNotes/2.10.0.txt | 85 + .config/emacs/lisp/magit/docs/RelNotes/2.10.1.txt | 57 + .config/emacs/lisp/magit/docs/RelNotes/2.10.2.txt | 47 + .config/emacs/lisp/magit/docs/RelNotes/2.10.3.txt | 41 + .config/emacs/lisp/magit/docs/RelNotes/2.11.0.txt | 210 + .config/emacs/lisp/magit/docs/RelNotes/2.12.0.txt | 645 ++ .config/emacs/lisp/magit/docs/RelNotes/2.12.1.txt | 16 + .config/emacs/lisp/magit/docs/RelNotes/2.13.0.txt | 122 + .config/emacs/lisp/magit/docs/RelNotes/2.13.1.txt | 34 + .config/emacs/lisp/magit/docs/RelNotes/2.2.0.txt | 219 + .config/emacs/lisp/magit/docs/RelNotes/2.2.1.txt | 45 + .config/emacs/lisp/magit/docs/RelNotes/2.2.2.txt | 45 + .config/emacs/lisp/magit/docs/RelNotes/2.3.0.txt | 251 + .config/emacs/lisp/magit/docs/RelNotes/2.3.1.txt | 31 + .config/emacs/lisp/magit/docs/RelNotes/2.4.0.txt | 147 + .config/emacs/lisp/magit/docs/RelNotes/2.4.1.txt | 31 + .config/emacs/lisp/magit/docs/RelNotes/2.5.0.txt | 122 + .config/emacs/lisp/magit/docs/RelNotes/2.6.0.txt | 134 + .config/emacs/lisp/magit/docs/RelNotes/2.6.1.txt | 40 + .config/emacs/lisp/magit/docs/RelNotes/2.6.2.txt | 52 + .config/emacs/lisp/magit/docs/RelNotes/2.7.0.txt | 81 + .config/emacs/lisp/magit/docs/RelNotes/2.8.0.txt | 128 + .config/emacs/lisp/magit/docs/RelNotes/2.9.0.txt | 437 + .config/emacs/lisp/magit/docs/RelNotes/2.90.0.org | 423 + .config/emacs/lisp/magit/docs/RelNotes/2.90.1.org | 39 + .config/emacs/lisp/magit/docs/RelNotes/3.0.0.org | 686 ++ .config/emacs/lisp/magit/docs/RelNotes/3.1.0.org | 58 + .config/emacs/lisp/magit/docs/RelNotes/3.2.0.org | 85 + .config/emacs/lisp/magit/docs/RelNotes/3.2.1.org | 12 + .config/emacs/lisp/magit/docs/RelNotes/3.3.0.org | 137 + .config/emacs/lisp/magit/docs/RelNotes/4.0.0.org | 532 ++ .config/emacs/lisp/magit/docs/htmlxref.cnf | 42 + .config/emacs/lisp/magit/docs/magit-section.org | 309 + .config/emacs/lisp/magit/docs/magit.org | 9641 +++++++++++++++++++++ 55 files changed, 18332 insertions(+) create mode 100644 .config/emacs/lisp/magit/docs/.orgconfig create mode 100644 .config/emacs/lisp/magit/docs/AUTHORS.md create mode 100644 .config/emacs/lisp/magit/docs/BACKERS.md create mode 100644 .config/emacs/lisp/magit/docs/Makefile create mode 100644 .config/emacs/lisp/magit/docs/RelNotes/0.5.1.txt create mode 100644 .config/emacs/lisp/magit/docs/RelNotes/0.6.1.txt create mode 100644 .config/emacs/lisp/magit/docs/RelNotes/0.7.0.txt create mode 100644 .config/emacs/lisp/magit/docs/RelNotes/0.8.0.txt create mode 100644 .config/emacs/lisp/magit/docs/RelNotes/0.8.1.txt create mode 100644 .config/emacs/lisp/magit/docs/RelNotes/0.8.2.txt create mode 100644 .config/emacs/lisp/magit/docs/RelNotes/1.0.0.txt create mode 100644 .config/emacs/lisp/magit/docs/RelNotes/1.1.0.txt create mode 100644 .config/emacs/lisp/magit/docs/RelNotes/1.1.1.txt create mode 100644 .config/emacs/lisp/magit/docs/RelNotes/1.1.2.txt create mode 100644 .config/emacs/lisp/magit/docs/RelNotes/1.2.0.txt create mode 100644 .config/emacs/lisp/magit/docs/RelNotes/1.2.1.txt create mode 100644 .config/emacs/lisp/magit/docs/RelNotes/1.2.2.txt create mode 100644 .config/emacs/lisp/magit/docs/RelNotes/1.4.0.txt create mode 100644 .config/emacs/lisp/magit/docs/RelNotes/1.4.1.txt create mode 100644 .config/emacs/lisp/magit/docs/RelNotes/1.4.2.txt create mode 100644 .config/emacs/lisp/magit/docs/RelNotes/2.1.0.txt create mode 100644 .config/emacs/lisp/magit/docs/RelNotes/2.10.0.txt create mode 100644 .config/emacs/lisp/magit/docs/RelNotes/2.10.1.txt create mode 100644 .config/emacs/lisp/magit/docs/RelNotes/2.10.2.txt create mode 100644 .config/emacs/lisp/magit/docs/RelNotes/2.10.3.txt create mode 100644 .config/emacs/lisp/magit/docs/RelNotes/2.11.0.txt create mode 100644 .config/emacs/lisp/magit/docs/RelNotes/2.12.0.txt create mode 100644 .config/emacs/lisp/magit/docs/RelNotes/2.12.1.txt create mode 100644 .config/emacs/lisp/magit/docs/RelNotes/2.13.0.txt create mode 100644 .config/emacs/lisp/magit/docs/RelNotes/2.13.1.txt create mode 100644 .config/emacs/lisp/magit/docs/RelNotes/2.2.0.txt create mode 100644 .config/emacs/lisp/magit/docs/RelNotes/2.2.1.txt create mode 100644 .config/emacs/lisp/magit/docs/RelNotes/2.2.2.txt create mode 100644 .config/emacs/lisp/magit/docs/RelNotes/2.3.0.txt create mode 100644 .config/emacs/lisp/magit/docs/RelNotes/2.3.1.txt create mode 100644 .config/emacs/lisp/magit/docs/RelNotes/2.4.0.txt create mode 100644 .config/emacs/lisp/magit/docs/RelNotes/2.4.1.txt create mode 100644 .config/emacs/lisp/magit/docs/RelNotes/2.5.0.txt create mode 100644 .config/emacs/lisp/magit/docs/RelNotes/2.6.0.txt create mode 100644 .config/emacs/lisp/magit/docs/RelNotes/2.6.1.txt create mode 100644 .config/emacs/lisp/magit/docs/RelNotes/2.6.2.txt create mode 100644 .config/emacs/lisp/magit/docs/RelNotes/2.7.0.txt create mode 100644 .config/emacs/lisp/magit/docs/RelNotes/2.8.0.txt create mode 100644 .config/emacs/lisp/magit/docs/RelNotes/2.9.0.txt create mode 100644 .config/emacs/lisp/magit/docs/RelNotes/2.90.0.org create mode 100644 .config/emacs/lisp/magit/docs/RelNotes/2.90.1.org create mode 100644 .config/emacs/lisp/magit/docs/RelNotes/3.0.0.org create mode 100644 .config/emacs/lisp/magit/docs/RelNotes/3.1.0.org create mode 100644 .config/emacs/lisp/magit/docs/RelNotes/3.2.0.org create mode 100644 .config/emacs/lisp/magit/docs/RelNotes/3.2.1.org create mode 100644 .config/emacs/lisp/magit/docs/RelNotes/3.3.0.org create mode 100644 .config/emacs/lisp/magit/docs/RelNotes/4.0.0.org create mode 100644 .config/emacs/lisp/magit/docs/htmlxref.cnf create mode 100644 .config/emacs/lisp/magit/docs/magit-section.org create mode 100644 .config/emacs/lisp/magit/docs/magit.org (limited to '.config/emacs/lisp/magit/docs') diff --git a/.config/emacs/lisp/magit/docs/.orgconfig b/.config/emacs/lisp/magit/docs/.orgconfig new file mode 100644 index 0000000..9b1e67f --- /dev/null +++ b/.config/emacs/lisp/magit/docs/.orgconfig @@ -0,0 +1,18 @@ +# -*- mode:org -*- +# Copyright (C) 2021-2026 Jonas Bernoulli +# SPDX-License-Identifier: GPL-3.0-or-later +# URL: https://github.com/emacscollective/org-macros +# Visit that to see these macros in a human-readable format. + +#+language: en + +#+options: H:4 num:3 toc:2 compact-itemx:t +#+property: header-args :eval never + +#+macro: year (eval (format-time-string "%Y")) +#+macro: version (eval (if-let ((tag (ignore-errors (car (process-lines "git" "describe" "--exact-match"))))) (concat "version " (substring tag 1)) (or (ignore-errors (car (process-lines "git" "describe"))) (concat "version " (or $1 ""))))) +#+macro: kbd (eval (format "@@texinfo:@kbd{@@%s@@texinfo:}@@" (let (case-fold-search) (replace-regexp-in-string (regexp-opt '("BS" "TAB" "RET" "ESC" "SPC" "DEL" "LFD" "DELETE" "SHIFT" "Ctrl" "Meta" "Alt" "Cmd" "Super" "UP" "LEFT" "RIGHT" "DOWN") 'words) "@@texinfo:@key{@@\\&@@texinfo:}@@" $1 t)))) +#+macro: kbdvar (eval (format "@@texinfo:@kbd{@@%s@@texinfo:}@@" (let (case-fold-search) (replace-regexp-in-string "<\\([a-zA-Z-]+\\)>" "@@texinfo:@var{@@\\1@@texinfo:}@@" (replace-regexp-in-string (regexp-opt '("BS" "TAB" "RET" "ESC" "SPC" "DEL" "LFD" "DELETE" "SHIFT" "Ctrl" "Meta" "Alt" "Cmd" "Super" "UP" "LEFT" "RIGHT" "DOWN") 'words) "@@texinfo:@key{@@\\&@@texinfo:}@@" $1 t) t)))) +#+macro: codevar (eval (format "@@texinfo:@code{@@%s@@texinfo:}@@" (let (case-fold-search) (replace-regexp-in-string "\\([A-Z][A-Z-]+\\)" "@@texinfo:@var{@@\\&@@texinfo:}@@" $1 t)))) +#+macro: var @@texinfo:@var{@@$1@@texinfo:}@@ +#+macro: dfn @@texinfo:@dfn{@@$1@@texinfo:}@@ diff --git a/.config/emacs/lisp/magit/docs/AUTHORS.md b/.config/emacs/lisp/magit/docs/AUTHORS.md new file mode 100644 index 0000000..e1673d2 --- /dev/null +++ b/.config/emacs/lisp/magit/docs/AUTHORS.md @@ -0,0 +1,428 @@ +The following people have contributed to Magit. +For statistics see https://stats.magit.vc/magit/authors.html. + +Authors +------- + +- Marius Vollmer +- Jonas Bernoulli + +Active Maintainers +------------------ + +- Jonas Bernoulli +- Kyle Meyer + +Former Maintainers +------------------ + +- Nicolas Dudebout +- Noam Postavsky +- Peter J. Weisberg +- Phil Jackson +- Rémi Vanicat +- Yann Hodique + +All Contributors +---------------- + +- Aaron Culich +- Aaron L. Zeng +- Aaron Madlon-Kay +- Abdo Roig-Maranges +- Adam Benanti +- Adam Jones +- Adam Kruszewski +- Adam Porter +- Adam Spiers +- Adeodato Simó +- Ævar Arnfjörð Bjarmason +- Alan Falloon +- Alban Gruin +- Aleksey Uimanov +- Alexander Gramiak +- Alexander Miller +- Alex Branham +- Alex Dunn +- Alexey Voinov +- Alex Kost +- Alex Kreisher +- Alex Ott +- Allen Li +- Andreas Fuchs +- Andreas Liljeqvist +- Andreas Rottmann +- Andrei Chițu +- Andrew Eggenberger +- Andrew Kirkpatrick +- Andrew Psaltis +- Andrew Schwartzmeyer +- Andrew Zipperer +- Andrey Smirnov +- Andriy Kmit' +- Andy Sawyer +- Angel de Vicente +- Aria Edmonds +- Arialdo Martini +- Arnau Roig Ninerola +- Ashlynn Anderson +- Barak A. Pearlmutter +- Bar Magal +- Bart Bakker +- Basil L. Contovounesios +- Bastian Beischer +- Bastian Beranek +- Benjamin Motz +- Ben North +- Ben Walton +- Ben Zanin +- Bob Uhl +- Boruch Baum +- Bradley Wright +- Brandon W Maister +- Brennan Vincent +- Brian Leung +- Brian Warner +- Bryan Shell +- Buster Copley +- Cameron Chaparro +- Carl Lieberman +- Chillar Anand +- Chris Bernard +- Chris Done +- Chris LaRose +- Chris Moore +- Chris Ring +- Chris Shoemaker +- Christian Dietrich +- Christian Kluge +- Christian Tietze +- Christophe Junke +- Christopher Carlile +- Christopher Monsanto +- Clément Pit-Claudel +- Cornelius Mika +- Craig Andera +- Curt Brune +- Daanturo +- Dale Hagglund +- Damien Cassou +- Dan Davison +- Dan Erikson +- Daniel Brockman +- Daniel Farina +- Daniel Fleischer +- Daniel Gröber +- Daniel Hackney +- Daniel Kraus +- Daniel Mai +- Daniel Martín +- Daniel Mendler +- Daniel Nagy +- Dan Kessler +- Dan LaManna +- Danny Zhu +- Dato Simó +- David Abrahams +- David Ellison +- David Hull +- David L. Rager +- David Wallin +- Dean Kariniemi +- Dennis Paskorz +- Divye Kapoor +- Dominique Quatravaux +- Duianto Vebotci +- Eli Barzilay +- Ellis Kenyo +- Eric +- Eric Davis +- Eric Prud'hommeaux +- Eric Schulte +- Erik Anderson +- Eugene Mikhaylov +- Evan Torrie +- Evgkeni Sampelnikof +- Eyal Lotem +- Eyal Soha +- Fabian Wiget +- Felix Geller +- Felix Yan +- Feng Li +- Florian Ragwitz +- Franklin Delehelle +- Frédéric Giquel +- Fritz Grabo +- Fritz Stelzer +- gemmaro +- Geoff Shannon +- George Kadianakis +- Géza Herman +- Graham Clark +- Graham Dobbins +- Greg A. Woods +- Greg Lucas +- Gregory Heytings +- Greg Sexton +- Greg Steuck +- Guillaume Martres +- Hannu Koivisto +- Hans-Peter Deifel +- hokomo +- Huon Wilson +- Hussein Ait-Lahcen +- Ian Eure +- Ian Milligan +- Ilya Grigoriev +- Iñaki Arenaza +- Ingmar Sittl +- Ingo Lohmar +- Ioan-Adrian Ratiu +- Ivan Brennan +- Jacob Ilsø +- Jan Tatarik +- Jasper St. Pierre +- JD Smith +- Jean-Louis Giordano +- Jeff Bellegarde +- Jeff Dairiki +- Jeremy Meng +- Jeremy Sowden +- Jesse Alama +- Jim Blandy +- Joakim Jalap +- Johannes Altmanninger +- Johannes Maier +- Johann Klähn +- John Mastro +- John Morris +- John Wiegley +- Jonas Bernoulli +- Jonas Galvão Xavier +- Jonathan Arnett +- Jonathan del Strother +- Jonathan Leech-Pepin +- Jonathan Roes +- Jonathon McKitrick +- Jon Vanderwijk +- Jordan Galby +- Jordan Greenberg +- Jorge Israel Peña +- Josh Elsasser +- Josiah Schwab +- Julien Danjou +- Justin Burkett +- Justin Caratzas +- Justin Guenther +- Justin Thomas +- Kan-Ru Chen +- Kenny Ballou +- Keshav Kini +- Kevin Brubeck Unhammer +- Kevin J. Foley +- Kévin Le Gouguec +- Kimberly Wolk +- Knut Olav Bøhmer +- Kyle Meyer +- Laurent Laffont +- Laverne Schrock +- Leandro Facchinetti +- Lele Gaifax +- Lénaïc Huard +- Leo Liu +- Leonardo Etcheverry +- Leo Vivier +- Li Chen +- Lingchao Xin +- Lin Sun +- Li-Yun Chang +- Lluís Vilanova +- Loic Dachary +- Louis Roché +- Lucius Chen +- Luís Oliveira +- Luke Amdor +- Magnar Sveen +- Magnus Malm +- Mak Kolybabi +- Manuel Vázquez Acosta +- Marcel Wolf +- Marc Herbert +- Marcin Bachry +- Marco Craveiro +- Marco Wahl +- Marc Sherry +- Marian Schubert +- Mario Rodas +- Marius Vollmer +- Mark Hepburn +- Mark Karpov +- Mark Oteiza +- Markus Beppler +- Martin Joerg +- Martin Polden +- Matt Beshara +- Matthew Fluet +- Matthew Kraai +- Matthieu Hauglustaine +- Matus Goljer +- Maxim Cournoyer +- Michael Fogleman +- Michael Griffiths +- Michael Heerdegen +- Michal Sojka +- Miciah Masters +- Miles Bader +- Miloš Mošić +- Mitchel Humpherys +- Moritz Bunkus +- Nacho Barrientos +- Naoya Yamashita +- Natalie Weizenbaum +- Nguyễn Tuấn Anh +- Nic Ferier +- Nicholas Vollmer +- Nick Alcock +- Nick Alexander +- Nick Dimiduk +- Nicklas Lindgren +- Nicolas Dudebout +- Nicolas Petton +- Nicolas Richard +- Nikita Leshenko +- Nikolay Martynov +- Noam Postavsky +- N. Troy de Freitas +- Ola Nilsson +- Ole Arndt +- Oleh Krehel +- Orivej Desh +- Óscar Fuentes +- Pancho Horrillo +- Park Zhou +- Paul Pogonyshev +- Paul Stadig +- Pavel Holejsovsky +- Pekka Pessi +- Pengji Zhang +- Peter Eisentraut +- Peter Jaros +- Peter J. Weisberg +- Peter Vasil +- Philippe Cavalaria +- Philippe Vaucher +- Philipp Fehre +- Philipp Haselwarter +- Philipp Stephani +- Philip Weaver +- Phil Jackson +- Phil Sainty +- Pierre Neidhardt +- Pieter Praet +- Pieter van Oostrum +- Prathamesh Sonpatki +- Pratyush Yadav +- Pritam Baral +- rabio +- Radon Rosborough +- Rafael Laboissiere +- Rahul Rameshbabu +- Raimon Grau +- Ramkumar Ramachandra +- Remco van 't Veer +- Rémi Vanicat +- René Stadler +- Richard Kim +- Richard Sent +- Robert Boone +- Robert Irelan +- Robin Green +- Roey Darwish Dror +- Roger Crew +- Roland Marchand +- Romain Francoise +- Ron Parker +- Roy Crihfield +- Rüdiger Sonderfeld +- Russell Black +- Ryan C. Thompson +- Sam Cedarbaum +- Samuel Bronson +- Samuel W. Flint +- Sanjoy Das +- Sean Allred +- Sean Bryant +- Sean Farley +- Sean Whitton +- Sebastian Wiesner +- Sébastien Gross +- Seong-Kook Shin +- Sergey Pashinin +- Sergey Vinokurov +- Servilio Afre Puentes +- shoefone +- Shuguang Sun +- Siavash Askari Nasr +- Silent Sphere +- Simon Pintarelli +- Stefan Kangas +- Štěpán Němec +- Steven Chow +- Steven E. Harris +- Steven Thomas +- Steven Vancoillie +- Steve Purcell +- StrawberryTea +- Suhail Shergill +- Sylvain Rousseau +- Syohei Yoshida +- Szunti +- Takafumi Arakaki +- Tassilo Horn +- TEC +- Teemu Likonen +- Teruki Shigitani +- Thierry Volpiatto +- Thomas A Caswell +- Thomas Fini Hansen +- Thomas Frössman +- Thomas Jost +- Thomas Riccardi +- Tibor Simko +- Timo Juhani Lindfors +- Tim Perkins +- Tim Wraight +- Ting-Yu Lin +- Tom Feist +- Toon Claes +- Topi Miettinen +- Troy Hinckley +- Tsuyoshi Kitamoto +- Tunc Uzlu +- Ulrich Müller +- Vineet Naik +- Vitaly Ostashov +- Vladimir Ivanov +- Vladimir Panteleev +- Vladimir Sedach +- Waqar Hameed +- Wei Huang +- Wilfred Hughes +- Win Treese +- Wojciech Siewierski +- Wouter Bolsterlee +- X4lldux +- Xavier Noria +- Xavier Young +- Xu Chunyang +- Yann Herklotz +- Yann Hodique +- Ynilu +- York Zhao +- Yuichi Higashi +- Yuri Khan +- Zach Latta +- zakora +- Zhu Zihao +- ziggy +- zilongshanren diff --git a/.config/emacs/lisp/magit/docs/BACKERS.md b/.config/emacs/lisp/magit/docs/BACKERS.md new file mode 100644 index 0000000..847fc22 --- /dev/null +++ b/.config/emacs/lisp/magit/docs/BACKERS.md @@ -0,0 +1,1402 @@ +Thanks to your contributions and enthusiastic support +the Magit [crowdfunding campaign][1] was a huge success! + +A special thanks goes to [Mojotech][2], [Directangular][3] and +[Google Open Source][4] for their very generous contributions. + +[1]: https://www.kickstarter.com/projects/1681258897/its-magit-the-magical-git-client +[2]: https://www.mojotech.com +[3]: https://www.directangular.com +[4]: https://opensource.google.com + +I would also like to thank each one of the almost two thousand +other backers. It was very motivating to learn that so many users +care that much about Magit and the well-being of its maintainer. + +Thanks! + +Jonas Bernoulli + + +------------------------------------------------------------ + + +These are some of the 1987 backers: + +(If you backed the campaign and would like to be mentioned +here but are not, then please fill out the backer survey.) + +- 4xrsJCr9 +- <3 +- @amirrajan +- @arthurnn +- @nietaki +- @seriousben +- A.I. +- A.Weiher +- Aaditya Sood +- Aaron Jacobs +- Aaron Lee +- Aaron Madlon-Kay +- Aaron Mathews +- Aaron Schumacher +- Abdullah Alleweeth +- Abhijit Rao +- Abrahán Fernández Nieto +- Ada +- Adam Benzan +- Adam Bobrow +- Adam Collard +- Adam Olsen +- Adam Patterson +- Adam Shannon +- Adam Sjøgren +- Adriaan Leijnse +- Adrian Bradd +- Al Scott +- Alan Pavičić +- Alan Pearce +- Alan Shutko +- Alastair Rankine +- Alberto Donato +- Aleix Conchillo Flaque +- Aleksandar Simić +- Aleksandr Ivanov +- Aleksei Fedotov +- Alex Bennée +- Alex Branham +- Alex Dempsey +- Alex Ermolov +- Alex Murray +- Alex Reinhart +- Alex Schroeder +- Alex Speed Kjeldsen +- Alex Wiles +- Alex ter Weele +- Alexander Berezovsky +- Alexander Goldstein +- Alexander Lamaison +- Alexander Simms +- Alexander Stankov +- Alexandre Bertails +- Alexandre Duret-Lutz +- Alexandre Héaumé +- Alexandre Julliard +- Alexey Egorov +- Alexey Kapustin +- Alexis Marie Wright +- Aleš Bizjak +- Alfredo Aguirre +- Allen Short +- Amin Bandali +- Anatolii Smolianinov +- Anatolij Prihosko +- Anatoly Kudinov +- Andre Aberer +- Andrea Crotti +- Andrea Di Persio +- Andreas Aronsson +- Andreas J +- Andreas Marschke +- Andreas Textor +- Andreas Vollert +- Andreas Zweili +- Andrej Depperschmidt +- Andres Mariscal +- Andrew C May +- Andrew Childs +- Andrew Cowper +- Andrew Cox +- Andrew Evans +- Andrew Fray +- Andrew Grytsenko +- Andrew J Cosgriff +- Andrew Macgregor +- Andrew McDermott +- Andrew Mullins +- Andrew Sanchez +- Andrew Schwartzmeyer +- Andrew Shugarts +- Andrew Slough +- Andrew Sullivan +- Andrew Talbot +- Andrew Tropin +- Andrew Watts +- Andrzej Skiba +- András Simonyi +- Andy Bold +- Andy Drop +- Andy Moreland +- Anntoin +- Anonymous +- Anselm Lingnau +- Anthony Cowley +- Anthony Hobbs +- Anticrisis +- Anton Orlov +- Antoni Batchelli +- Antonio Miranda +- Aran Cox +- Arjen Wiersma +- Arjun +- Arnaud Meuret +- Arne Brasseur +- Arne Redlich +- Arong Pan +- Arthur A. Gleckler +- Arthur Leonard Andersen +- Artur Malabarba +- Artyom Kazak +- Ash +- Asherah +- Asilata Bapat +- Audun Gevelt +- August Lilleaas +- Axie Infinity +- Azundris +- Baishampayan Ghose +- Balaji Sivaraman +- Baldur +- Barak +- Barry Gitarts +- Barry McLarnon +- Bas Alberts +- Bascht +- Ben Hollis +- Ben Leggett +- Ben Plantinga +- Ben Swift +- Benaiah Mischenko +- Benedek Fazekas +- Benedikt Terhechte +- Beni Cherniavsky-Paskin +- Benjamin Beckwith +- Benjamin Hipple +- Benjamin Klüglein +- Benjamin Kudria +- Benjamin Ragheb +- Benjamin Savs +- Benoit Daffos +- Biao Xie +- Bill Stilwell +- Bjarke Vad +- Björn Larsson +- Bob Duke +- Bob Sun +- Bob Uhl +- Bobby Burden III +- Bodil Stokke +- Boris Dušek +- Boyd Adamson +- Bozhidar Batsov +- Brandon Adams +- Brandon Belew +- Brandon Dixon +- Brandon Fulk +- Brandon Orther +- Brendan Fahy +- Brendan Jackman +- Brendan Kirby +- Brett Witty +- Brian Brunswick +- Brian Carlson +- Brian Cobb +- Brian Danilko +- Brian Gruber +- Brian Hicks +- Brian James Rubinton +- Brian Leonard +- Brian Sniffen +- Brian Warner +- Bridger Howell +- Brooke Mitchell +- Bruce Ravel +- Bruno Jacquet +- Bryan Gilbert +- Bryan Willson Berry +- Bryce Kerley +- Cai Kechao +- Caibin Chen +- Caleb McCaffery +- Calogero Lo Leggio +- Cameron Higby-Naquin +- Cameron Stitt +- Carl Lange +- Carlo Sciolla +- Carlos Antonio Neira Bustos +- Carlos Rocha +- Carsten Strotmann +- Carsten.Koenig@hotmail.de +- Caspar +- Cena Mayo +- Chad Stovern +- Chaitanya Koparkar +- Chandan Rajendra +- Chao Liu from GRASP Lab, UPenn +- Charl P. Botha +- Charles L.G. Comstock +- Charlie Brodie +- Charlie McMackin +- Chas B. +- Chase Wang +- Chen Rotem Levy +- Chris Charles +- Chris Douty +- Chris Gray +- Chris Hanson +- Chris Johnson Bidler +- Chris Lample +- Chris Lindholm +- Chris Mann +- Chris McDevitt +- Chris McGrath +- Chris Nyland +- Chris R (offby1@) +- Chris Sims +- Chris Taylor +- Christian 'gicmo' Kellner +- Christian Berg +- Christian Johansen +- Christian Johansson +- Christian Lenke +- Christian Romney +- Christian Zang +- Christine und Arne Köhn +- Christoffer Schultz Jensen +- Christoph Egger +- Christoph Lange +- Christoph Paa +- Christophe Garion +- Christophe Junke +- Christophe Troestler +- Christophe Vu-Brugier +- Christopher Adams +- Christopher Genovese +- Christopher Giroir +- Christopher Jenkins +- Christopher Jordan +- Christopher M. Becker +- Cicero Jones +- Clay Haapala +- Cliff Wulfman +- Clément Pit-Claudel +- Cody Canning +- Colin McLear +- Colin P. D. Powell +- Constantine Khrulev +- Correl Roush +- Courtland Jones +- Craig Andera +- Craig Hawco +- Curt Brune +- D. Sere +- Damian Dobroczynski +- Damien G. +- Damien Merenne +- Damien Pollet +- Dan Davison +- Dan Forest +- Dan Harms +- Dan Jones +- Dan LaManna +- Dan Torop +- Danger Salad +- Daniel +- Daniel Bowman +- Daniel Caixinha +- Daniel Cowgill +- Daniel Gempesaw +- Daniel Grady +- Daniel J. Rothblatt +- Daniel Kraus +- Daniel Luna +- Daniel Ma +- Daniel Mai +- Daniel Martín +- Daniel Molina +- Daniel Moore (drmrd) +- Daniel S. F. Alves +- Daniel Skarda +- Daniel Tamai +- Daniel V +- Daniel de Haas +- Daniël de Kok +- Darren Aldredge +- Darryl Okahata +- Dave Aitken +- Dave Churchill +- Dave Kochbeck +- Dave Liepmann +- Dave Pearson +- Dave Pretty +- Dave Rolsky +- David Arnold +- David Berg Marklund +- David Duncan +- David Ellison +- David Goldfarb +- David Hodges +- David Hull +- David Krauser +- David Leimbach +- David Mayfield +- David Pathakjee +- David Radkowski +- David Robillard +- David S. Rosenberg +- David Scarpetti +- David Stone +- David Vázquez +- David Wen Riccardi-Zhu +- David Zuber +- Davidbrcz +- Davide Restivo +- Dean Sellis +- Deepu Mohan Puthrote +- Denis Haine +- Derek Chen-Becker +- Derek Scherger +- Derek Slager +- Derek Upham +- Devin +- Diane Trout +- DictatorBob +- Diego Vicente Martín +- Dieter Komendera +- Diez Roggisch +- Difrex +- Dimitre Liotev +- Dimitris Platis +- Dirk Breuer +- Divan Santana +- Dmitry Alexeev +- Dmitry Dzema +- Dmitry Lazurkin +- Dmitry Polyanitsa +- Dmitry Tymchuk +- Dominique Dumont +- Don Spencer +- DonBørn +- Doru Mihai Leonte +- Doug MacEachern +- Dr. Jobo +- Drew Raines +- Durant Schoon +- Dustin Maas +- Dustin Paluch +- Dylan Fitzgerald +- Dylan Moore +- Eddie Hillenbrand +- Eduardo Apolinario +- Eduardo Ruiz Macias +- Edward Faulkner +- Edward Knyshov +- Edward Steere +- Edwin Stearns +- Elaina Martineau +- Eli Naeher +- Elias Castegren +- Elis ""etu"" Hirwing +- Elsa Gonsiorowski +- Emanuel Tannert +- Emil Bergström +- Emil Klarskov +- Emil Lundmark +- Emilio y Marcelo +- Emre Sevinç +- Eric B. Decker +- Eric Brown +- Eric E. Moore +- Eric Hogberg +- Eric Hopkins +- Eric Seidel +- Erik Anderson +- Erik Edrosa +- Erik Nordlund +- Erik Pischel +- Erik Swanson +- Erik W. B. +- Erik Winkels +- Erkki Seppälä +- Erwin Junge +- Esben Sparre Andreasen +- Ethan Feldman +- Ethan Glasser-Camp +- Ettore Berardi +- Eugene Rwagasore +- Eugene Tan +- Evan Rowley +- Evgeniy Tyurkin +- Ewan Dawson +- Ezekiel Elin +- Fabian +- Fabian Otto +- Felipe M. +- Felix Panozzo +- Fernando Dobladez +- Fernando Varesi +- Fitz Elliott +- Flavien COGEZ +- Florian Adamsky +- Florian Bruhin (The Compiler) +- Florian Kempenich +- Florian Schmaus +- Florian Stock +- Florian Ulivi +- Foivos Zakkak +- Foxtur +- Fran Burstall +- Francesc Elies +- Francesc Rocher +- Frank Roland +- František Haifler +- François Morlet +- Fred Akalin +- Fred Boiteux +- Fred Kroon +- Frederic Dumont +- Frederik Banis +- Frederik Beaujean +- Fritz Grabo +- Frontside Software +- Fumitaka Tokumitsu +- Gabriel Adomnicai +- Gabriel J. Pérez Irizarry +- Gaby Launay +- Galder Zamarreño +- Galin Yordanov +- Garvin Guan +- Gary Trakhman +- Gavin Mercer +- Geoff MacIntosh +- Geoff Pado +- Geoff Wozniak +- Geoffrey J. Teale +- George Pittarelli +- Gerard Paapu +- Gerard Ryan +- Gergely Nagy +- Gergely Polonkai +- Giang-Son Nguyen +- Giorgos Logiotatidis +- Giovanni Azua +- Gitty McGitface +- Gitty McGitface +- Glenn R. Martin +- Gordon Freeman +- Gordon Gustafson +- Greece <3 magit +- Greg Chevalley +- Greg Leppert +- Gregg Hernandez +- Guido Schmidt +- Guilhem Doulcier +- Guillaume Ayoub +- Guillaume Marceau +- Guillermo Ramos +- GuiltyDolphin +- Gustav Wikström +- Gwenhael Le Moine +- Harald Hvaal +- Hector Castro +- Henri Jones +- Henrik Ahlgren +- Henrik Kjerringvåg +- Henrik Renlund +- Henry Laxen +- Henry Robinson +- Henry Walshaw +- Hertz +- Herwig Stuetz +- Hiren Shah +- Hiroki Kiyohara +- Hiroshi Tsutsui +- Hoel +- Holger Dürer +- Horst Gutmann +- Hung Pham +- Hynek Schlawack +- Håkan Nilsson +- Ian Johnson +- Ian Kerins +- Ian McCowan +- Ian Warford +- Ibrahim Awwal +- Icarus Sparry +- Igor Bronshteyn +- Igor Kupczyński +- Ikuru K +- Ilja Kocken +- Illia Shestakov +- Ingar Almklov +- Ionov Valentine +- Isaac Karth +- Israel Herraiz +- Itamar Ravid +- Itamar Turner-Trauring +- Iulian Costan +- Ivan Kanis +- Ivan Timokhin +- Ivo Reyes Román +- J Alexander Feldman-Crough +- Jacek Generowicz +- Jack Angers +- Jack Kelly +- Jack Letourneau +- Jack Moffitt +- Jack Nai-Chieh Chou +- Jack Wong +- Jacob Covington +- Jacob Ilsø Christensen +- Jacob Moeller +- Jacob O'Donnell +- Jaga Santagostino +- Jaidev Sridhar +- Jake McCrary +- Jakub Chmielarz +- Jakub Narębski +- James Felix Black +- James Ferguson +- James Orr +- James Sharman +- James Tranovich +- James Valleroy +- Jamie McClymont +- Jamie Nicol +- Jan Mas Rovira +- Jan Rychter +- Jan Seeger +- Jan Vincent Liwanag +- Jangseop Shin +- Jared Miller +- Jarno Malmari +- Jarrett P +- Jason Blevins +- Jason Orendorff +- Jasper Spaans +- Jeff Bauer +- Jeff McCarrell +- Jeff Tecca +- Jeff Waltzer +- Jeff Whitmire +- Jeff Workman +- Jeffrey I. Schiller +- Jeffrey Panczyk +- Jennifer Kowalsky +- Jens-Peter Thiry +- Jeremiah Peschka +- Jeremy Burks +- Jeremy Huffman +- Jeroen AH +- Jeroen Faijdherbe +- Jeroen Tiebout +- Jessica Claire Edwards +- Jethro Kuan +- Jiashu Wang +- Jim Blandy +- Jim Menard +- Jingcheng Xu +- Jiten K. Pathy +- Joachim 'Troglobit' Nilsson +- Joakim Ohlrogge +- Joakim Verona +- Joao Azevedo +- Joe Balancio +- Joe DeVivo +- Joe Gallo +- Joe Kiniry +- Joerg Jaspert (Ganneff) +- Johan Bay +- Johan Ekenberg +- Johan Forsberg +- Johan K. Jensen +- Johan S. +- Johan Sandblom +- Johan Sternerup +- Johannes 'ksjogo' Goslar +- Johannes Beigel +- Johannes Grødem +- Johannes Rainer +- Johannes W. +- John Anthony +- John Cinnamond +- John D. Hume +- John Giannelos +- John Haman +- John Krumpotick +- John Mastro +- John Peloquin +- John Urquhart Ferguson +- Johnny Chadda +- Jojo +- Jon Irving +- Jon M. Dugan +- Jon Raphaelson +- Jon Snader +- Jonas Ransjö +- Jonas Serych +- Jonas Strømsodd +- Jonathan Arnett (J3RN) +- Jonathan Lai +- Jonathan Miller +- Jonathan Rothberg +- Jonathan del Strother +- Joonas Sarajärvi +- Joost Diepenmaat +- Jordan Galby +- Jordan Mulcahey +- Jordon Biondo +- Joren Van Onder +- Jorge Dias +- Jorge Santiago +- Jos +- Josep Egea +- Joseph Churchill +- Joseph Garvin +- Joseph Jaoudi +- Joseph Mingrone +- Josh Berry +- Josh Comer +- Josh Elsasser +- Josh Lipschultz +- Josh Medeski +- Josh Mōller-Mara +- Josh Skidmore +- Josh Tilles +- Josh Valentine +- Joshua B. Smith +- Joshua E Cook +- Joshua F. McMichael +- Josiah Schwab +- Jostein Kjønigsen +- Jouni K. Seppänen +- Joël Franusic +- Juan E. Maya +- Juan Edi +- Juan Pedro Bolívar Puente (https://sinusoid.al) +- Julian Kniephoff +- Julien Blanchard +- Julio Borja Barra +- Justin Guenther +- Justin Kaipada +- Justin Schell +- Justin Smestad +- Justin Talbott +- Justin Wood +- Justine Tunney +- Jörg Ramb +- Jürgen Hackl +- Kaloian Doganov +- Kamen Naydenov +- Kamil & Hassan +- Kara Woo +- Karl Voit +- Karthikeyan S +- Katherine Lai +- Kaushal Modi +- Kaushik Chakraborty (kaychaks) +- Kavita Varsani +- Kazushige Hosokawa +- Kazuya Sakakihara +- Keiichi Watanabe +- Keith Amidon +- Keith Mantell +- Kelly McLaughlin +- Ken Olstad +- Kent Primrose +- Kevin Christen +- Kevin D Saunders +- Kevin Grimes, II +- Kevin J Foley +- Kevin Kelley +- Kevin Orr +- Khan Thompson +- Kieran Healy +- Kieran Trezona-le Comte +- Kim Frederiksen +- Kim Gräsman +- Kiran Kulkarni +- Klāvs Taube +- Konrad Voelkel +- Koray Al +- Kostiantyn Rybnikov +- Kridsada Thanabulpong +- Krista Victorsen +- Kristoffer +- Kungsgeten +- Kushal Pisavadia +- Kyle Brooks +- Kyle Machulis (qDot) +- Kyle Oba +- Kyle Purdon +- Kyle Schwab +- Kyle Sexton +- Kévin Le Gouguec +- Lardière Sébastien +- Lars Hesel Christensen +- Laurence Rochfort +- Laurent Charignon +- Laurent Gatto +- Leandro Cardoso +- Lefteris Karapetsas +- LegoNigel +- Leo Breebaart +- Leo C. Stein +- Leo Martel +- Leron Culbreath +- Les Jones +- Levi I. Tan Ong +- Liam Stewart +- Luca Manzoni +- Lucas Meyers +- Lucian Mogosanu +- Ludwig PACIFICI +- Luis Miguel Castañeda +- Luis Osa +- Luke Amdor +- Luke Francl +- Lute Kamstra +- Luís Oliveira +- Léo Gillot-Lamure +- M. Ian Graham +- Maarten Grachten +- Maciek Swiech, PhD +- Magit is full of magic! +- Magnar Sveen +- Magnus Malm +- Magnus Nyberg (nxtr) +- Mahinshaw@gmail.com +- Mak Kolybabi +- Maksym Planeta +- Man Roy +- Mandy +- Manfred Kroehnert +- Manish Sharma +- Mansur Ziatdinov +- Manuel Alonso +- Manuel Frischknecht +- Manuel Kallenbach +- Manuel Uberti +- Marc Massar +- Marc Nijdam +- Marc Sherry +- Marc T. Henry de Frahan +- Marcel Bollmann +- Marcello Nicoletti +- Marcin Cieślak +- Marcin Swieczkowski +- Marco Dalla Stella +- Marco Wahl +- Marcus Geiger +- Marcus Klemm +- Marcus Puchalla +- Mark A. Hershberger +- Mark Faldborg +- Mark Hepburn +- Mark Jeffcoat +- Mark Meredith +- Mark Ranallo +- Mark Schaake +- Mark Stradling +- Mark Tran +- Mark Triggs +- Markus Fix +- Marshall Quander +- Mart van de Wege +- Marten Lienen +- Marti Bolivar +- Martin Buchmann +- Martin Frost +- Martin Geisler +- Martin Huschenbett +- Martin Luethi +- Martin Mauch +- Martin Myrseth +- Martin Polak +- Martin Rechsteiner +- Martin Yrjölä +- Martin Šlouf +- Martino Visintin +- Martins Grunskis +- Mary Jo Brodzik +- Masayuki Onjo +- Mateusz Probachta (beetleman) +- Mathew Robinson +- Mathieu Corbin +- Mathieu Tartare +- Matija Zezelj +- Matt Curtis +- Matt Haffner +- Matt Kramer +- Matt Savoie +- Matt Usifer +- Matthew Bregg +- Matthew Curry +- Matthew Fluet +- Matthew Gregg +- Matthew Hitchman +- Matthew Piziak +- Matthew Plant +- Matthew Wells +- Matthias Güdemann +- Matthias Nüßler +- Matti Niemenmaa +- Mattias Bengtsson +- Matías Aguirre +- Mauricio Aldazosa Mariaca +- Mauricio Collares +- Max B. Hansson +- Max Diefenbach +- Max Regan +- Max Tweddell +- Max Willsey +- Maxim Ivanov +- Maxim Rurenko +- Mayank Jain +- Meiyo Peng +- Melioratus +- Menno Finlay-Smits +- Micah Anderson +- Michael Abrahams +- Michael Droettboom +- Michael Engelhardt +- Michael Gracie +- Michael Griffiths +- Michael Hansen +- Michael Kleehammer +- Michael Krasnyk +- Michael McCracken +- Michael Moreno +- Michael Overmeyer +- Michael Sloan +- Michael Welsh Duggan +- Michal Buczko +- Michał Politowski +- Mickaël Salihi +- Miguel Fernandes +- Mihai Rinzis +- Mikael Kermorgant +- Mikael Springer +- Mike Ashley +- Mike Crowe +- Mike Danylchuk +- Mike Gulick +- Mike Hewitson +- Mike Monette +- Mike T. Miller +- Mike Travers +- Mike Wagg +- Mike Zamansky +- Mikhail Pankov +- Mikhail Pontus +- Mikko Värri +- Miks Kalnins (MaikuMori) +- Milan Zamazal +- Miles Clark +- Miloš Mošić +- Mingwei Zhang +- Miranda Dobbs +- Mirzhan Irkegulov +- Mitchell A. Gordon +- Mitchell Bright +- Mitsutaka Takeda +- Mohammed Ismail Ansari (myTerminal) +- Moiz Bookwala +- Moritz Bunkus +- Morten Slot Kristensen +- Mr. Wacky +- Mrinal Purohit +- Murilo Pereira +- Murphy McMahon +- Nab Inno +- Nat Knight +- Nate Eagleson +- Nathan Collins +- Nathan Hitchings +- Nathan Sain +- Naupaka Zimmerman +- Neil Baylis +- Neil Durant +- Neurolit +- Niall Dooley (doolio) +- Nick Alcock +- Nick Fitzgerald +- Nick Higham +- Nick Spain +- Nicolas Dudebout +- Nicolas Ha +- Nicolas Hafner +- Nicolas Morey-Chaisemartin +- Nicolò Balzarotti +- Niels Widger +- Nikita Dudnik +- Nikita Leshenko +- Nikk Folts +- Niko Felger +- Nikolai Nespor +- Nikos Fertakis +- Nils +- Nils Grunwald +- Nils Pascal Illenseer +- Niluge_KiWi +- Nishioka Wataru +- Nishiyama Nobuyuki +- Noah Hoffman +- Noel Markham +- Norbert Kiesel +- Norman Walsh +- Norman Yamada +- Ola Nilsson +- Ole Jørgen Brønner +- Ole petter Orhagen +- Oleg Ivanov +- Oleg Kostyuchenko +- Oleg Matrokhin +- Oliver Caldwell +- Oliver Eidel +- Oliver Holworthy +- Oliver Marks +- Oliver Reiter +- Olivier Berger +- Olivier Tharan +- Olivier Yiptong +- Ollie Charles (ocharles) +- Onorio Catenacci +- P. Kunze +- Paolo G. Giarrusso +- Pasi Heikkinen +- Patrick Brown +- Patrick Chung +- Patrick Haun +- Patrick Kelley +- Patrick Nguyen +- Patrick Thomson +- Paul Hankes Drielsma +- Paul Healy +- Paul Kalupnieks +- Paul Oliver +- Paul R. Jorgensen +- Paul Reiter +- Paul Young +- Pavel Khlopin +- Pavel Panchekha +- Pawan Dubey +- Paweł Damasiewicz +- Paweł Kapała +- Pedro Pinto +- Pedro Romano +- Per Bergqwist +- Peter Borocz +- Peter Brachwitz +- Peter Buckley +- Peter C. Norton +- Peter Cheng +- Peter Christensen +- Peter Perron +- Peter Vasil +- Phil Austin +- Phil Dixon +- Phil Sung +- Philip Sequeira +- Philip Tran +- Philipp Baschke +- Philipp Klippel +- Philippe Bernery +- Philippe Cavalaria +- Philippe Vaucher +- Pierre Lrz +- Pierre Neidhardt +- Praveen Perera +- Radon Rosborough +- Rafal Kowalski +- Ramanathan Sivagurunathan +- Rami Massoud +- Rami Ylimäki +- Raniere Silva +- Rasmus Rygaard +- Ray Hixson +- Remco +- Remote Viewer +- Renat Galimov +- Renato Aguiar +- Rey Wright +- Rhys Powell +- Riccardo Cambiassi +- Richard Bonichon +- Richard Murri +- Richard Petri +- Richard Thames +- Rickard Sundin +- Riverprawn +- Rob Donnelly +- Robert Boone +- Robert Helgesson +- Robert Postill +- Robert Steward +- Robert Stuttaford +- Robin Neatherway +- Rodrigo +- Roland Reckel +- Romain Deterre +- Roman Kashitsyn +- Romario López +- Ron Lusk +- Ronan Barzic +- Rory Gibson +- Rory Molinari +- Ross Donaldson +- Ross Lonstein +- Rouven Czerwinski +- Royall Spence +- Ruben Bakker +- Ruben Maher +- Rupert Swarbrick +- Russell Healy +- Rutger Prins +- Ruud +- Ryan C. Thompson +- Ryan Eschinger +- Ryan Kaskel +- Ryan Mulligan +- Ryan Prior +- Ryan Seals +- Ryan Shaw +- Rémi Vanicat +- Rörd Hinrichsen +- Rúnar Berg Baugsson Sigríðarson +- SM +- SabreWolfy +- Sagun Khatri +- Saint Aardvark the Carpeted +- Sajith Sasidharan +- Sam Bleckley +- Sam Blumenthal +- Sam Brightman +- Sam Halliday +- Sam Pillsworth +- Samuel Cole +- Samuel Evans-Powell +- Samuel Tonini +- Sangho Na +- Santi de Ledesma +- Saul Reynolds-Haertle +- Sayash K +- Scott Barron +- Scott Determan +- Scott Dubinsky +- Scott Jacobsen +- Scott Ross +- Sean Allred +- Sean Andrews +- Sean Bowman +- Sean Grove (@sgrove) +- Sean J Williamson +- Sean McAfee +- Sean Patrick Hagen +- Sean Smith +- Seb Kri +- Sebastian Nørgaard +- Sebastian Schlag +- Sergey Kostrukov +- Sergey Timanin +- Shane Celis +- Shaun Lee +- Shigenobu Nishikawa +- Shingo Fukuyama +- Shmulik Regev +- Shreyas Ragavan +- Shubhang Mani +- ShuffelBag +- Shun Yu +- Simon Altschuler +- Simon Benfold +- Simon Brown +- Simon Fenton +- Simon Gregersen +- Simon Génier +- Simon Law +- Sir Garbagetruck +- Skip +- Slava Barinov +- Sliim +- Spruce Bondera +- Stefan Arentz +- Steffen Weinreich +- Stelian Ionescu +- Stephan Schmitt +- Stephan Schubert +- Stephen C. Gilardi +- Stephen Childs +- Stephen Pegoraro +- Stephen Whipple +- Stephen York +- Steven Rémot +- Stian Eikeland +- Stig Brautaset +- StupidCodeFactory +- Stéfan van der Walt +- Sumit J +- Superbil +- Sven Koschnicke +- Sven Rubben +- Sverre Johansen +- Swaroop C H +- Sylvain Rousseau +- Szabolcs Szilágyi +- Sébastien André +- Søren Lund +- Taavi Tani +- Takaaki Ishikawa +- Takeshi Teshima +- Tamas K. Papp +- Tarjei Bærland +- Tassilo Horn +- Taylor Skidmore +- TeMPOraL +- Terje Sten Bjerkseth +- Tero Paloheimo +- The Mad Hatter +- Thomas A Caswell +- Thomas Felber +- Thomas Gazagnaire +- Thomas Hisch +- Thomas Moulia +- Thomas Skardal +- Thommy H. +- Thor Adam +- Tiago Luchini +- Tianxiang Xiong +- Tibor Csögör +- Tilmann Singer +- Tim Howes +- Tim Johns +- Tim Perkins (@tprk77) +- Tim Scheer +- Tim Zallin +- Ting-Yu Lin +- Titus von der Malsburg +- Tjaart van der Walt +- Tobias Fankhänel +- Tom Lyons (tbl3rd) +- Tom Ridge +- Tom Talbot +- Tom W. +- Tom van der Sommen +- Tomasz Legutko +- Tomás Solar Castro +- Tony Finch +- Tony Kemp +- Toon Claes +- Topher Brown +- Tore Brede +- Travis B. Hartwell +- Travis Luckenbaugh +- Travis Poulsen +- Tresi Arvizo +- Trevoke +- Trevor Spiteri +- Tritlo +- Troy Hinckley +- Tuomas Kareinen +- Tushar Tyagi +- Tyler Romeo +- Tyler Sellon +- USAMI Kenta (tadsan, zonuexe) +- Umar Arshad +- Vaibhav Jain +- Valtteri +- Varun Madiath +- Vedang Manerikar +- Venkateswara Rao Mandela +- Victor Arias +- Victor Shulyak +- Victory Ejevika +- Vincent Demeester +- Vincent Pomageot +- Vindaar +- Vitor Capela +- Vivek Das Mohapatra +- Vlad +- Vlad Buslov +- Vladimir Shemankov +- Volker Haas +- Václav Haisman +- Wei Tang +- Wei-ju Wu +- Wendel Scardua +- Wes Hardaker +- Wilfred Hughes +- Will Fleming +- Will Hughes +- Will Newton +- Will Roe +- Willi Ballenthin +- William Casarin +- William Henney +- William Oberndorfer +- Willy Lee +- Willy Rempel +- Wolfgang Stief +- Xi Omicron Sigma +- Xi Shen +- Xuan Bi +- Yanko Simeonov - Zecho +- Yasushi SHOJI (""yashi"") +- Yen, Tzu-Hsi +- Yolanda Cadalbert +- YoungFrog +- Yu Miura +- Yuquan Fu +- Yuri Albuquerque +- Yuri Bronshtein +- Yuri Khan +- Yuta Yamada +- Yuuki Harano +- Zach Ingbretsen +- Zach Kost-Smith +- Zachary Kim +- Zachary Stevens +- ZaharK +- Zev Blut +- Zhiming Wang +- Zotan +- Zsolt Botykai +- agzam.ibragimov@gmail.com +- alex@olkhovskiy.com +- anderspree +- andrew.smirnov@gmail.com +- andron94 +- aneesh.kumar@gmail.com +- apeyroux +- baby-gnu.org +- bigjust +- bmac +- brandon.eltiste@gmail.com +- bsdmatburt@gmail.com +- bzg +- cbbrowne +- cfuhrman@gmail.com +- chpeer +- cmacrae +- cms +- comandante345 +- danmilon +- db48x +- designernasser@gmail.com +- dgoeke@gmail.com +- djeis +- dlowe +- dom.parry@gmail.com +- elseorand +- empty +- enderozcan +- frank.patz@gmail.com +- frankyxhl +- gabriele.lana@gmail.com +- gaetano +- gdcosta@gmail.com +- genehack +- george.l +- gingeralesy +- gmasgras@gmail.com +- goosetherumfoodle +- greetings_from_italy +- gregory@brusick.ch +- gsnewmark +- haff +- hensansi +- hugurp +- ilitzroth@gmail.com +- iwan +- jakobj +- jao +- jarvisschultz +- joesmoe10@gmail.com +- jonas.bulow@gmail.com +- jonasac +- joranvar +- jvshahid +- jward +- jwerak +- k-sunako +- kalle.lindqvist@mykolab.com +- karate expert +- karronoli +- kenneth@geisshirt.dk +- kiwanami +- kltm +- krvkir +- l26wangca@gmail.com +- laduke +- lambdageek +- lischenko +- lobachevsky +- luke@balooga.com +- mail.urfi@gmail.com +- manojm.321@gmail.com +- marco 'rho lambda pi' rolappe +- mats manet +- mds2 +- mgdelacroix +- miguelgr +- milan.v.mitrovic@gmail.com +- mr.adtaylor@gmail.com +- n2o +- netWorms +- nick.lanham.nexus@gmail.com +- ninesigns +- nivekuil +- noonker +- nyyManni +- ojab +- oppenlander +- pancho horrillo +- paralin +- patrickwinter@posteo.ch +- pcmantz@mcpantz.org +- pepone.onrez@gmail.com +- peter ""git push -f"" aaser +- pitometsu +- rafael@micubiculo.com +- rails-to-cosmos +- ray keung +- rdomigan +- realloc() +- roomkey.com +- rouadec +- runejuhl +- sbaker617 +- shapr +- shino +- simon.leinen@gmail.com +- snowball +- sponrad +- stask +- steffen@g7n.dk +- taku0 +- tanzoniteblack +- thirteen37 +- thomas.stenhaug@gmail.com +- thomasf@jossystem.se +- toby cabot +- tomterl +- trobanga +- trocster +- turnspike.com +- tuxtimo +- tzz@lifelogs.com +- umejam +- vaartis +- vargonaut +- vincenzo.disomma@gmail.com +- wtp +- www.drinkiwiki.com +- yewton +- yoshinori kawahara +- zerth +- Álvaro González Sotillo +- Åsmund Grammeltvedt +- Étienne BERSAC +- Étienne Deparis +- Ömer Yildiz +- Łukasz Korecki diff --git a/.config/emacs/lisp/magit/docs/Makefile b/.config/emacs/lisp/magit/docs/Makefile new file mode 100644 index 0000000..5b606de --- /dev/null +++ b/.config/emacs/lisp/magit/docs/Makefile @@ -0,0 +1,208 @@ +-include ../config.mk +include ../default.mk + +.PHONY: install clean AUTHORS.md stats + +## Build ############################################################# + +docs: texi info html html-dir pdf + +texi: $(TEXIPAGES) +info: $(INFOPAGES) dir +html: $(HTMLFILES) +html-dir: $(HTMLTOPS) +pdf: $(PDFFILES) +epub: $(EPUBFILES) + +ORG_EVAL += --load ol-man --eval "(progn $$ORG_MAN_EXPORT)" +ORG_EVAL += --eval "(setq indent-tabs-mode nil)" +ORG_EVAL += --eval "(setq org-src-preserve-indentation nil)" +ORG_EVAL += --eval "\ +(defun org-texinfo--sanitize-content (text)\ + (replace-regexp-in-string \"[@@{}]\" \"@@\\&\" text))" +ORG_EVAL += --funcall org-texinfo-export-to-texinfo + +redo-docs: + @touch $(ORGPAGES) + @make docs + +.revdesc: ; +_ := $(shell test "$(REVDESC)" = "$$(cat .revdesc 2> /dev/null)" ||\ + echo "$(REVDESC)" > .revdesc) + +%.texi: %.org .orgconfig .revdesc + @printf "Generating $@\n" + @$(EMACS_ORG) $< $(ORG_EVAL) + +%.info: %.texi + @printf "Generating $@\n" + @$(MAKEINFO) --no-split $< -o $@ + +dir: magit.info magit-section.info + @printf "Generating dir\n" + @echo $^ | xargs -n 1 $(INSTALL_INFO) --dir=$@ + +HTML_FIXUP_CSS = '//a\ +\ +\n\ +\n\ +\n\ +\n\ +\n' +HTML_FIXUP_ONLOAD = 's///' +HTML_FIXUP_MENU = '/<\/body>/i
<\/div>' + +%.html: %.texi + @printf "Generating $@\n" + @$(MAKEINFO) --html --no-split $(MANUAL_HTML_ARGS) $< + @sed -i -e $(HTML_FIXUP_CSS) -e $(HTML_FIXUP_ONLOAD) -e $(HTML_FIXUP_MENU) $@ + +%/index.html: %.texi + @$(RMDIR) $(HTMLDIRS) + @printf "Generating magit/*.html\n" + @$(MAKEINFO) --html -o $(PKG)/ $(MANUAL_HTML_ARGS) magit.texi + @for f in $$(find magit -name '*.html') ; do \ + sed -i -e $(HTML_FIXUP_CSS) -e $(HTML_FIXUP_ONLOAD) -e $(HTML_FIXUP_MENU) $$f ; \ + done + @printf "Generating magit-section/*.html\n" + @$(MAKEINFO) --html -o $(PKG)-section/ $(MANUAL_HTML_ARGS) magit-section.texi + @for f in $$(find magit-section -name '*.html') ; do \ + sed -i -e $(HTML_FIXUP_CSS) -e $(HTML_FIXUP_ONLOAD) -e $(HTML_FIXUP_MENU) $$f ; \ + done + +%.pdf: %.texi + @printf "Generating $@\n" + @texi2pdf --clean $< > /dev/null + +%.epub: %.texi + @printf "Generating $@\n" + @$(MAKEINFO) --docbook $< -o epub.xml + @xsltproc $(DOCBOOK_XSL) epub.xml 2> /dev/null + @echo "application/epub+zip" > mimetype + @zip -X --quiet --recurse-paths -0 $@ mimetype + @zip -X --quiet --recurse-paths -9 --no-dir-entries $@ META-INF OEBPS + @$(RMDIR) $(EPUBTRASH) + +## Install ########################################################### + +install: install-info install-docs + +install-docs: install-info + @$(MKDIR) $(DESTDIR)$(docdir) + $(CP) AUTHORS.md $(DESTDIR)$(docdir) + +install-info: info + @$(MKDIR) $(DESTDIR)$(infodir) + $(CP) $(INFOPAGES) $(DESTDIR)$(infodir) + +## Clean ############################################################# + +clean: + @printf " Cleaning docs/*...\n" + @$(RMDIR) dir $(INFOPAGES) $(HTMLFILES) $(HTMLDIRS) $(PDFFILES) + @$(RMDIR) $(EPUBFILES) $(EPUBTRASH) + @$(RMDIR) $(GENSTATS_DIR) + +## Release management ################################################ + +authors: AUTHORS.md + +AUTHORS.md: + @printf "Generating AUTHORS.md..." + @test -e $(TOP).git \ + && (printf "$$AUTHORS_HEADER\n" > $@ \ + && git log --pretty=format:'- %aN' | sort -u | \ + grep -v dependabot >> $@ \ + && printf "done\n" ; ) \ + || printf "FAILED (non-fatal)\n" + @git commit --gpg-sign -m "AUTHORS.md: Update list of contributors" \ + -o -- $@ ../.mailmap && git show --pretty= -p HEAD || true + +DOCS_DOMAIN = docs.$(DOMAIN) +SNAP_TARGET = $(subst .,_,$(DOCS_DOMAIN)):devel/ +DOCS_TARGET = $(subst .,_,$(DOCS_DOMAIN)): + +publish: redo-docs + @printf "Publishing snapshot manual...\n" + @cp $(PKG).pdf $(PKG)/$(PKG).pdf + @cp $(PKG)-section.pdf $(PKG)-section/$(PKG)-section.pdf + @$(RCLONE) sync $(RCLONE_ARGS) $(PKG) $(SNAP_TARGET)/$(PKG)/ + @$(RCLONE) sync $(RCLONE_ARGS) $(PKG)-section $(SNAP_TARGET)/$(PKG)-section/ + +release: redo-docs + @printf "Publishing release manual...\n" + @cp $(PKG).pdf $(PKG)/$(PKG).pdf + @cp $(PKG)-section.pdf $(PKG)-section/$(PKG)-section.pdf + @$(RCLONE) sync $(RCLONE_ARGS) $(PKG) $(DOCS_TARGET)/$(PKG)/ + @$(RCLONE) sync $(RCLONE_ARGS) $(PKG)-section $(DOCS_TARGET)/$(PKG)-section/ + +## Statistics ######################################################## + +STAT_DOMAIN = stats.$(DOMAIN) +STAT_TARGET = $(subst .,_,$(STAT_DOMAIN)):$(PKG)/ + +stats: + @printf "Generating statistics\n" + @$(GITSTATS) $(GITSTATS_ARGS) $(TOP) $(GITSTATS_DIR) + +stats-upload: + @printf "Uploading statistics...\n" + @$(RCLONE) sync $(RCLONE_ARGS) stats $(STAT_TARGET) + +## Lisp ############################################################## + +# When making changes here, then also adjust the copy in magit-base.el. +define ORG_MAN_EXPORT +(define-advice org-man-export (:around (fn link description format) gitman) + (if (and (eq format 'texinfo) ;' + (string-match-p "\\`git" link)) + (replace-regexp-in-string "%s" link " +@ifinfo +@ref{%s,,,gitman,}. +@end ifinfo +@ifhtml +@html +the %s(1) manpage. +@end html +@end ifhtml +@iftex +the %s(1) manpage. +@end iftex +") + (funcall fn link description format))) +endef +export ORG_MAN_EXPORT + +## Templates ######################################################### + +define AUTHORS_HEADER +The following people have contributed to Magit. +For statistics see https://$(STAT_DOMAIN)/magit/authors.html. + +Authors +------- + +- Marius Vollmer +- Jonas Bernoulli + +Active Maintainers +------------------ + +- Jonas Bernoulli +- Kyle Meyer + +Former Maintainers +------------------ + +- Nicolas Dudebout +- Noam Postavsky +- Peter J. Weisberg +- Phil Jackson +- Rémi Vanicat +- Yann Hodique + +All Contributors +---------------- + +endef +export AUTHORS_HEADER diff --git a/.config/emacs/lisp/magit/docs/RelNotes/0.5.1.txt b/.config/emacs/lisp/magit/docs/RelNotes/0.5.1.txt new file mode 100644 index 0000000..d08cdb0 --- /dev/null +++ b/.config/emacs/lisp/magit/docs/RelNotes/0.5.1.txt @@ -0,0 +1,11 @@ +Magit v0.5.1 Release Notes +========================== + +This is the first release of Magit. Enjoy! + +Released 14 August 2008 by Marius Vollmer. + +Authors +------- + + 157 Marius Vollmer diff --git a/.config/emacs/lisp/magit/docs/RelNotes/0.6.1.txt b/.config/emacs/lisp/magit/docs/RelNotes/0.6.1.txt new file mode 100644 index 0000000..a58c3ba --- /dev/null +++ b/.config/emacs/lisp/magit/docs/RelNotes/0.6.1.txt @@ -0,0 +1,24 @@ +Magit v0.6.1 Release Notes +========================== + +Released 16 October 2008 by Marius Vollmer. + +Changes since v0.5.1 +-------------------- + +Almost everything has changed. Some highlights: + + * Magit now works with Git 1.6.0. (John Wiegley) + + * Support for interactive rewriting. + + * Sections can be shown and hidden. + + * Staging, unstaging, applying, reverting and discarding changes can + now be done line-by-line, not only hunk-by-hunk. + +Authors +------- + + 212 Marius Vollmer + - John Wiegley diff --git a/.config/emacs/lisp/magit/docs/RelNotes/0.7.0.txt b/.config/emacs/lisp/magit/docs/RelNotes/0.7.0.txt new file mode 100644 index 0000000..d035539 --- /dev/null +++ b/.config/emacs/lisp/magit/docs/RelNotes/0.7.0.txt @@ -0,0 +1,70 @@ +Magit v0.7.0 Release Notes +========================== + +Released 8 March 2009 by Marius Vollmer. + +Changes since v0.6.1 +-------------------- + + * Tagging, on 't' and 'T'. + + * Stashing, on 'z' and 'Z'. + + * Wazzup, on 'w'. Wazzup gives you an overview over how other + branches relate to the current one. + + * There is more control over pushing. 'P' now takes a prefix argument + and pushing a branch without a default remote will ask for one. + + * Logs have changed a bit: 'l' shows the traditional brief log, and + 'L' shows a more verbose log. Use the prefix arg to specify the + range of the log. + + * M-x magit-status doesn't prompt anymore for a directory when invoked + from within a Git repository. Use C-u to force a prompt. + + * When you have nothing staged, 'c' will now explicitly ask whether to + commit everything instead of just going ahead and do it. This can + be customized. + + * The digit keys '1', '2', '3', and '4' now show sections on the + respective level and hide everything below. With Meta, they work on + all sections; without, they work only on sections that are a parent + or child of the current section. + + * Typing '+' and '-' will change the size of hunks, via the "-U" + option to git diff. '0' resets hunks to their default size. + + * Typing 'k' on the "Untracked files" section title will offer to + delete all untracked files. + + * Magit understands a bit of git-svn: the status buffer shows unpushed + and unpulled commits, 'N r' runs git svn rebase, and 'N c' runs git + svn dcommit. + + * Magit now also works when the directory is accessed via tramp. + + * M-x magit-status can also create new repositories when given a + directory that is not a Git repository. + + * Magit works better with oldish Gits that don't understand "--graph", + for example. + + * The name of the Git program and common options for it can be + customized. + +Authors +------- + + 107 Marius Vollmer + 18 John Wiegley + 9 Alexey Voinov + 5 Marcin Bachry + 3 Rémi Vanicat + 2 Alex Ott + 2 René Stadler + 2 Steve Purcell + 1 Daniel Farina + 1 David Wallin + 1 Ian Eure + 1 Jesse Alama diff --git a/.config/emacs/lisp/magit/docs/RelNotes/0.8.0.txt b/.config/emacs/lisp/magit/docs/RelNotes/0.8.0.txt new file mode 100644 index 0000000..3ce415f --- /dev/null +++ b/.config/emacs/lisp/magit/docs/RelNotes/0.8.0.txt @@ -0,0 +1,55 @@ +Magit v0.8.0 Release Notes +========================== + +Released 7 May 2010 by Phil Jackson. + +Changes since v0.7.0 +-------------------- + + * By setting magit-repo-dirs, you can get better repo completion. + Magit will offer all subdirectories (up to magit-repo-dirs level + deep) of the listed directories when magit-status asks for a + directory to work on. You can get the old behavior with a double + prefix to magit-status. + + * Hitting 'c' or 'C' while resolving a conflict in the middle of a + rebase will offer to continue the rebase instead of trying to commit + your changes. + + * Pulling will ask which branch to pull from when you don't have a + default branch configured. + + * Switching to a remote branch will offer to create a local tracking + branch for it. + + * Hitting C-c C-s while editing a commit message will toggle the + "--signoff" option. + + * Hitting 's' on the "Untracked files" section title will stage all + untracked files. + + * Hitting 'C-u S' will stage all untracked and tracked files. + + * Performance improvements in the status buffer. + + * Bug fixes to make Magit work better with newer Gits. + +Authors +------- + + 66 Phil Jackson + 53 Marius Vollmer + 27 Rémi Vanicat + 7 Alexey Voinov + 5 Hannu Koivisto + 5 Roger Crew + 4 John Wiegley + 4 Moritz Bunkus + 3 Ben Walton + 2 Marcin Bachry + 2 Óscar Fuentes + 1 David Abrahams + 1 Leo Liu + 1 Pavel Holejsovsky + 1 Ramkumar Ramachandra + 1 Steve Purcell diff --git a/.config/emacs/lisp/magit/docs/RelNotes/0.8.1.txt b/.config/emacs/lisp/magit/docs/RelNotes/0.8.1.txt new file mode 100644 index 0000000..95b204f --- /dev/null +++ b/.config/emacs/lisp/magit/docs/RelNotes/0.8.1.txt @@ -0,0 +1,28 @@ +Magit v0.8.1 Release Notes +========================== + +Released 10 June 2010 by Phil Jackson. + +Changes since v0.8.0 +-------------------- + + * New library `rebase-mode.el'. Edit Git rebase files. + + * New commands `magit-log-all' and `magit-log-first-parent'. + + * New command `magit-git-command'. Run any Git command. + + * `magit-remote-update' learned to fetch just the current remote. + + * `magit-tag' learned to place the tag on something other than HEAD. + +Authors +------- + + 55 Phil Jackson + 7 Rémi Vanicat + 7 Ævar Arnfjörð Bjarmason + 4 Natalie Weizenbaum + 2 Ramkumar Ramachandra + 1 Mark Hepburn + 1 Moritz Bunkus diff --git a/.config/emacs/lisp/magit/docs/RelNotes/0.8.2.txt b/.config/emacs/lisp/magit/docs/RelNotes/0.8.2.txt new file mode 100644 index 0000000..9367486 --- /dev/null +++ b/.config/emacs/lisp/magit/docs/RelNotes/0.8.2.txt @@ -0,0 +1,27 @@ +Magit v0.8.2 Release Notes +========================== + +Released 10 July 2010 by Phil Jackson. + +Changes since v0.8.1 +-------------------- + + * Use shorter more human readable representations for refs. + + * Optionally show refs for remote branches the way Git would. + + * Tell VC to update the mode-line for us. + +Authors +------- + + 21 Phil Jackson + 18 Natalie Weizenbaum + 2 Alan Falloon + 2 Moritz Bunkus + 2 Rémi Vanicat + 1 Alex Ott + 1 Leo Liu + 1 Sean Bryant + 1 Ævar Arnfjörð Bjarmason + 1 Óscar Fuentes diff --git a/.config/emacs/lisp/magit/docs/RelNotes/1.0.0.txt b/.config/emacs/lisp/magit/docs/RelNotes/1.0.0.txt new file mode 100644 index 0000000..92f9175 --- /dev/null +++ b/.config/emacs/lisp/magit/docs/RelNotes/1.0.0.txt @@ -0,0 +1,84 @@ +Magit v1.0.0 Release Notes +========================== + +Released 23 March 2011 by Phil Jackson. + +Changes since v0.8.2 +-------------------- + + * New library `magit-key-mode.el'. From a popup buffer dispatch + Magit/Emacs commands which wrap Git commands and select the + arguments passed to Git. Group various sets of related commands + in new menus and adjust them accordingly. + + * New library `magit-svn.el' based on code previously in `magit.el'. + Improve the implementation. Control `git svn' from Magit. + + * New library `magit-topgit.el' based on code previously in + `magit.el'. Improve the implementation. Control TopGit from Magit. + + * Provide a wrapper for `completing-read'. Support using iswitchb to + do completion. + + * Fixed and improved information shown during a rebase. + + * New macro `magit-define-inserter' to define functions which insert + sections. + + * New macro `magit-add-action'. A hook-like extension mechanism for + commands that behave differently based on the type of the section + at point. + + * New macro `magit-define-command'. Like `defun' but also define + a hook in addition to the function/command. If a hook function + succeeds do not run the function body as passed to this macro. + + * New commands `magit-add-change-log-entry' + and `magit-add-change-log-entry-other-window'. + + * New command `magit-change-what-branch-tracks'. + + * New commands `magit-run-git-gui' and `magit-run-gitk'. + + * Various new submodule commands. + + * Various new branch commands. + + * Various new log commands. Remove some old log commands. + + * Make reflog commands more like the log commands. + + * Numerous bugfixes and tweaks. + +Authors +------- + + 197 Phil Jackson + 27 Natalie Weizenbaum + 25 Óscar Fuentes + 22 Moritz Bunkus + 20 Rémi Vanicat + 17 Aaron Culich + 10 Timo Juhani Lindfors + 8 Ramkumar Ramachandra + 8 Ævar Arnfjörð Bjarmason + 6 Yann Hodique + 5 Hannu Koivisto + 5 Julien Danjou + 5 Peter J. Weisberg + 4 Leo Liu + 3 Robin Green + 2 Brian Warner + 2 Christian Kluge + 2 Marc Herbert + 1 Andreas Fuchs + 1 Chris Bernard + 1 David Abrahams + 1 Dominique Quatravaux + 1 John Wiegley + 1 Paul Stadig + 1 Philip Weaver + 1 Remco van 't Veer + 1 Robert Boone + 1 Rüdiger Sonderfeld + 1 Tom Feist diff --git a/.config/emacs/lisp/magit/docs/RelNotes/1.1.0.txt b/.config/emacs/lisp/magit/docs/RelNotes/1.1.0.txt new file mode 100644 index 0000000..762d202 --- /dev/null +++ b/.config/emacs/lisp/magit/docs/RelNotes/1.1.0.txt @@ -0,0 +1,112 @@ +Magit v1.1.0 Release Notes +========================== + +Released 23 December 2011 by Yann Hodique. + +Changes since v1.0.0 +-------------------- + + * Added distinct faces for various different kinds of refs. + + * Completely redesigned existing faces. + + * Added library `magit-classic-theme.el' for users who like the old + faces better. + + * Share many more key bindings between all Magit modes. Previously + many commands were only available in certain buffers, even though + they are useful in all Magit buffers. + + * Added library `magit-simple-keys.el' for users who don't like the + popups. + + * Added support for using Ido to do completion. + + * Added support for Ediff. + + * Added shell script `magit'. + + * Added library `magit-bisect.el'. + + * Added library `magit-stgit.el'. + + * Added mode `magit-svn-mode'. + + * Added mode `magit-topgit-mode'. + + * Added mode `magit-rebase-mode'. + + * Added buttons to commit buffer to cycle to commits which were + previously shown. The commands are `magit-show-commit-backward' + and `magit-show-commit-forward. + + * Defined backward compatibility implementations of some Emacs + functions. + + * Type changes are now shown in diffs. + + * Added option `magit-set-upstream-on-push'. + + * Added option `magit-default-tracking-name-function'. + + * Added option `magit-log-auto-more'. + + * Added option `magit-create-branch-behaviour'. + + * Added option `magit-status-buffer-switch-function'. + + * Added option `magit-rewrite-inclusive'. + + * Added options `magit-highlight-trailing-whitespace' and + `magit-highlight-indentation'. + + * Added command `magit-show'. Visit REVISION:FILE. + + * Added command `magit-delete-branch-forced'. + + * Added command `magit-log-edit-toggle-author'. + + * `magit-reset-working-tree' learned to remove untracked files. + + * `magit-push' learned to set the upstream branch. + +Authors +------- + + 152 Peter J. Weisberg + 55 Yann Hodique + 18 Phil Jackson + 18 Pieter Praet + 18 Rémi Vanicat + 12 Moritz Bunkus + 10 Lluís Vilanova + 8 Eli Barzilay + 7 Nicolas Dudebout + 6 Roger Crew + 5 Štěpán Němec + 3 David Abrahams + 3 Hannu Koivisto + 3 Jeff Bellegarde + 3 Rüdiger Sonderfeld + 2 Alan Falloon + 2 Andreas Rottmann + 2 Andrew Kirkpatrick + 2 Craig Andera + 2 Jasper St. Pierre + 1 Andrey Smirnov + 1 Bastian Beischer + 1 Chris Moore + 1 Daniel Brockman + 1 Eric Davis + 1 George Kadianakis + 1 Kimberly Wolk + 1 Luke Amdor + 1 Luís Borges de Oliveira + 1 Marc Herbert + 1 Marco Craveiro + 1 Ramkumar Ramachandra + 1 Steve Purcell + 1 Thomas Jost + 1 Tibor Simko + 1 Tom Feist + 1 Ævar Arnfjörð Bjarmason diff --git a/.config/emacs/lisp/magit/docs/RelNotes/1.1.1.txt b/.config/emacs/lisp/magit/docs/RelNotes/1.1.1.txt new file mode 100644 index 0000000..21b3baf --- /dev/null +++ b/.config/emacs/lisp/magit/docs/RelNotes/1.1.1.txt @@ -0,0 +1,25 @@ +Magit v1.1.1 Release Notes +========================== + +Released 14 January 2012 by Yann Hodique. + +Changes since v1.1.0 +-------------------- + + * `magit-svn-get-local-ref' learned to expand branch specs containing + braces. + + * `magit-log-edit' learned to amend and create commits with no message. + + * Several other fixes and improvements. + +Authors +------- + + 6 Nicolas Dudebout + 6 Yann Hodique + 1 Graham Clark + 1 Justin Caratzas + 1 Peter J. Weisberg + 1 Ryan C. Thompson + 1 Timo Juhani Lindfors diff --git a/.config/emacs/lisp/magit/docs/RelNotes/1.1.2.txt b/.config/emacs/lisp/magit/docs/RelNotes/1.1.2.txt new file mode 100644 index 0000000..4950edc --- /dev/null +++ b/.config/emacs/lisp/magit/docs/RelNotes/1.1.2.txt @@ -0,0 +1,33 @@ +Magit v1.1.2 Release Notes +========================== + +Released 23 September 2012 by Yann Hodique. + +Changes since v1.1.1 +-------------------- + + * Modes now have proper mode-line lighters. + + * Hook variables are now defined semi-explicitly. + + * Uninteresting refs are no longer shown in logs. + + * The deprecated `assoc' library is no longer used. + + * Several other fixes and improvements. + +Authors +------- + + 13 Yann Hodique + 9 Peter J. Weisberg + 2 Jonas Bernoulli + 2 Ramkumar Ramachandra + 1 Bradley Wright + 1 Bryan Shell + 1 Damien Cassou + 1 Eric Davis + 1 John Wiegley + 1 Nic Ferier + 1 Nick Alcock + 1 Rémi Vanicat diff --git a/.config/emacs/lisp/magit/docs/RelNotes/1.2.0.txt b/.config/emacs/lisp/magit/docs/RelNotes/1.2.0.txt new file mode 100644 index 0000000..b27f259 --- /dev/null +++ b/.config/emacs/lisp/magit/docs/RelNotes/1.2.0.txt @@ -0,0 +1,73 @@ +Magit v1.2.0 Release Notes +========================== + +Released 23 September 2012 by Yann Hodique. + +Changes since v1.1.2 +-------------------- + + * Rewrote the branch manager. + + * Diffs are optionally refined using `diff-refine-hunk'. + + * Added library `magit-blame.el' defining new mode + `magit-blame-mode'. + + * Added library `magit-wip.el' defining new modes + `magit-wip-save-mode' and `magit-wip-mode'. + + * New section movement commands; `magit-goto-next-sibling-section' + and `magit-goto-previous-sibling-section'. + + * Added command `magit-file-log'. + + * Added command `magit-manual-merge'. + + * `magit-delete-branch-force' was merged into `magit-delete-branch'. + + * `magit-move-branch' learned to force the rename. + + * `magit-reset-working-tree' learned to remove ignored files. + + * `magit-pull' learned to set `branch.BRANCH.merge'. + + * `magit-log-edit' learned to respect GIT_AUTHOR_EMAIL, + GIT_AUTHOR_NAME and GIT_AUTHOR_DATE. + + * `magit-visit-item' learned to visit untracked files, diffs and + hunks. + + * Added option `magit-sha1-abbrev-length'. + +Authors +------- + + 157 Yann Hodique + 61 Nicolas Dudebout + 14 Peter J. Weisberg + 12 Jonas Bernoulli + 10 Ryan C. Thompson + 7 Miles Bader + 6 Damien Cassou + 5 Samuel Bronson + 4 Dale Hagglund + 4 Eli Barzilay + 4 Takafumi Arakaki + 4 rabio + 3 Leonardo Etcheverry + 3 Nick Alcock + 3 Rémi Vanicat + 3 Rüdiger Sonderfeld + 2 Graham Clark + 2 Hans-Peter Deifel + 2 Moritz Bunkus + 1 Andreas Liljeqvist + 1 Christian Dietrich + 1 Christopher Monsanto + 1 Daniel Hackney + 1 Hannu Koivisto + 1 John Wiegley + 1 Jonathan Roes + 1 Ole Arndt + 1 Ron Parker + 1 Suhail Shergill diff --git a/.config/emacs/lisp/magit/docs/RelNotes/1.2.1.txt b/.config/emacs/lisp/magit/docs/RelNotes/1.2.1.txt new file mode 100644 index 0000000..6e255bf --- /dev/null +++ b/.config/emacs/lisp/magit/docs/RelNotes/1.2.1.txt @@ -0,0 +1,15 @@ +Magit v1.2.1 Release Notes +========================== + +Released 23 May 2014 by Jonas Bernoulli. + +Changes since v1.2.0 +-------------------- + + * `magit-delete-directory' was rewritten to deal with an incompatible + change in `delete-directory' in Emacs v24.4. + +Authors +------- + + 1 Jonas Bernoulli diff --git a/.config/emacs/lisp/magit/docs/RelNotes/1.2.2.txt b/.config/emacs/lisp/magit/docs/RelNotes/1.2.2.txt new file mode 100644 index 0000000..e529dc9 --- /dev/null +++ b/.config/emacs/lisp/magit/docs/RelNotes/1.2.2.txt @@ -0,0 +1,17 @@ +Magit v1.2.2 Release Notes +========================== + +Released 23 October 2014 by Jonas Bernoulli. + +Changes since v1.2.1 +-------------------- + + * `magit-delete-directory' uses itself when deleting recursively, + instead of `org-delete-directory' which it was copied from. + + * Many byte-compile warnings were addressed. + +Authors +------- + + 5 Jonas Bernoulli diff --git a/.config/emacs/lisp/magit/docs/RelNotes/1.4.0.txt b/.config/emacs/lisp/magit/docs/RelNotes/1.4.0.txt new file mode 100644 index 0000000..f0f8d9e --- /dev/null +++ b/.config/emacs/lisp/magit/docs/RelNotes/1.4.0.txt @@ -0,0 +1,231 @@ +Magit v1.4.0 Release Notes +========================== + +Released 1 April 2015 by Jonas Bernoulli. + +This release sits in the middle of a commit marathon that lasted for +more than 4700 commits. + +When I became Magit's new maintainer during the summer of 2013 Magit +was already a big success, but underneath its shiny surface it was +having some serious problems. Over the years the source had gotten +very disorganized and many old abstractions were no longer sufficient. +Unfortunately existing code had almost never been adjusted when new +features had been added, leading to a lot of new code that worked +around limitations of existing code. + +This was clearly not sustainable in the long run, and so I started +cleaning up and replacing the existing abstractions with simpler, yet +often more powerful implementations. Unfortunately his had to happen +incrementally as it was seldom possible to cleanup one area without +making substantial changes elsewhere. Along the way I also addressed +many of the hundreds of feature requests, but that was more of a bonus +- the focus was on getting the codebase ready for future improvements. + +At the beginning of 2014 I moved development to the new next branch. +Working on a branch which was not used by thousands of Melpa users +allowed me to move faster and users were no longer affected by the +occasional regression. But it also meant that I now had to maintain +two branches. In hindsight I should have released the master branch +as 1.3.0 at that time, despite all the known defects it had. + +Since then I have finished the cleanup on the next branch and then +moved on to implement many new features. On the master branch the +focus was on bugfixes and the occasional backport. This release is +based on the master branch. Later this spring 2.1.0 will be released +based on the next branch. + +Compiling a list of all changes in 1.4.0 would by a major amount of +work in itself, so instead the below list is for the most part limited +to major changes, which enabled the user visible changes. Many users +don't have to be told about the new features anyway - they have been +using them for more than a year now. + +Changes since v1.2.2 +-------------------- + + * The libraries `magit-topgit.el', `magit-stgit.el', and + `magit-svn.el' all reincarnated as separate repository. + + * The libraries `magit-classic-theme.el' and `magit-simple-keys.el', + which allowed users to undo some of the changes in older releases, + were removed. + + * The library `rebase-mode.el' was renamed to `git-rebase-mode.el' + and moved to the `magit/git-modes' repository. + + * The library `magit-log-edit-mode.el' was removed and replaced with + `git-commit-mode.el' from the `magit/git-modes' repository. + + * The functionality provided by the library `magit-bisect.el' was + replaced with a new implementation in `magit.el'. + + * The package `cl-lib` is now used instead of the obsolete `cl'. + + * The library `magit.el' no longer lacks any recognizable structure. + + * The macro `magit-define-command' was removed. + The hook that was defined in addition to the command only served + to make things more complicated and the generated doc-string was + insufficient. + + * The use of "section actions" has been reduced to a minimum. + Commands that behave differently depending on the type of the + current section still use `magit-section-case' or in some cases + even `magit-section-action', but the preferred way for users to + add new variants now is to add a new command to the type-specific + section keymap, instead of the hooks defined by + `magit-section-action'. + + * More work is done directly in `magit-with-section'. + Most of the helper functions were removed. These functions + were not intended to be used directly, but that did not keep + contributors from doing so, leading to many inconsistencies. + + * The mode machinery was massively refactored. + Most importantly the new macro `magit-mode-setup' was added, + replacing the old `magit-mode-init' which forgoes most of the + things each and every of its callers has to do, which let to many + inconsistencies + + * The refresh machinery was massively refactored. + A refresh now has to be requested more explicitly by either calling + `magit-refresh' or one of the functions that call Git and then the + former. Also, refreshing now more often correctly preserves point. + + * Washing diffs now takes less cycles. + Previously the code used to wash diffs was very complicated. It + passed around state using many dynamically bound variables, and + called `git diff' many times. Now we call `git diff' once and then + wash its output in one go. + + * Commits and stashes are now washed using the regular diffwasher. + + * Low-level functions for running Git were massively refactored, and + many new variants were added. Previously many callers had to deal + with the gory details themselves (and usually did it badly). + + * The output from processes is now logged in a dedicated buffer. + From this buffer it's also possible to kill a running process. + + * The Wazzup buffer was massively refactored. + All options to optionally make it faster were removed, as it is now + faster out-of-the-box without sacrificing any functionality at all. + + * Many more competing abstractions were unified. + It was common to have one no longer sufficient core abstraction, and + several competing wrapper abstractions. In most cases this has been + replaced with a single, less complex implementation, which serves all + of the current use cases. + + * Refreshing "after a asynchronous process has run" now happens after + the process has actually finished. That was always the intention, + but not what actually used to happen. + + * The commit message is no longer provided when calling `git commit'. + Instead Git populates a file with a template and then uses $EDITOR + to have the user edit that. This did not work so well for a while + but now we succeed in having the emacsclient being used as $EDITOR. + + * A new Branch Manager was added. + + * Log learned to show optionally show author information in the + margin. + + * Terminology with regards to what a tracking branch is, was fixed. + + * When creating a new branch the default choice is what Git would + default to, instead of some silly name. + + * Tools used to test whether Git supports certain features was removed. + Instead we now require a non-ancient version of Git. + + * The shell script `magit' reincarnated as a separate repository. + +Authors +------- + + 1838 Jonas Bernoulli + 171 Yann Hodique + 121 Pieter Praet + 59 Rémi Vanicat + 24 Nicolas Dudebout + 21 Takafumi Arakaki + 16 acple + 14 Phil Jackson + 13 Rüdiger Sonderfeld + 12 Mitchel Humpherys + 8 Servilio Afre Puentes + 7 Ramkumar Ramachandra + 7 Teruki Shigitani + 6 Lluís Vilanova + 6 Sergey Vinokurov + 5 Thierry Volpiatto + 4 Moritz Bunkus + 4 Noam Postavsky + 4 Seong-Kook Shin + 3 Laurent Laffont + 3 Leonardo Etcheverry + 3 Loic Dachary + 3 Raimon Grau + 3 Sébastien Gross + 2 Bastian Beischer + 2 Damien Cassou + 2 Evgkeni Sampelnikof + 2 Greg A. Woods + 2 Greg Sexton + 2 Jesse Alama + 2 Leandro Facchinetti + 2 Nguyễn Tuấn Anh + 2 Nick Alexander + 2 Pekka Pessi + 2 Philippe Vaucher + 2 Rafael Laboissiere + 2 Sebastian Wiesner + 1 Abdo Roig-Maranges + 1 Adam Spiers + 1 Andrei Chițu + 1 Andrew Schwartzmeyer + 1 Brandon W Maister + 1 Chris Done + 1 Chris Ring + 1 Christopher Monsanto + 1 Cornelius Mika + 1 Dan LaManna + 1 David Hull + 1 Dennis Paskorz + 1 Divye Kapoor + 1 Eric Schulte + 1 Felix Geller + 1 Feng Li + 1 Geoff Shannon + 1 Jan Tatarik + 1 Jeff Dairiki + 1 John Wiegley + 1 Jordan Greenberg + 1 Kyle Meyer + 1 Lele Gaifax + 1 Manuel Vázquez Acosta + 1 Marcel Wolf + 1 Marian Schubert + 1 Matus Goljer + 1 Nick Dimiduk + 1 Nicolas Richard + 1 Peter J. Weisberg + 1 Philipp Haselwarter + 1 Prathamesh Sonpatki + 1 Romain Francoise + 1 Roy Crihfield + 1 Sanjoy Das + 1 Sergey Pashinin + 1 Steve Purcell + 1 Steven Chow + 1 Steven Thomas + 1 Thomas Frössman + 1 Thomas Riccardi + 1 Ting-Yu Lin + 1 Wilfred Hughes + 1 Win Treese + 1 York Zhao + 1 aaa707 + 1 Ævar Arnfjörð Bjarmason diff --git a/.config/emacs/lisp/magit/docs/RelNotes/1.4.1.txt b/.config/emacs/lisp/magit/docs/RelNotes/1.4.1.txt new file mode 100644 index 0000000..15dc747 --- /dev/null +++ b/.config/emacs/lisp/magit/docs/RelNotes/1.4.1.txt @@ -0,0 +1,31 @@ +Magit v1.4.1 Release Notes +========================== + +Released 12 April 2015 by Jonas Bernoulli. + +This is a bugfix release. + +Changes since v1.4.0 +-------------------- + + * The external library `magit-log-edit.el' is no longer supported. + If it is still installed, then instruct the user to remove it. + + * The function `magit-maybe-show-setup-instructions' is now run even + when `magit' has not been loaded by the time `after-init-hook' ran. + + * Invalid `:package-version' keywords in option definitions were + fixed. In some cases the value was "2.1.0" instead of "1.4.0". + + * Some unnecessary obsolete-variable definitions were removed. + + * Running tests on Travis CI was fixed. + + * The Makefile, README.md, and release notes received minor fixes + and cleanup. + +Authors +------- + + 9 Jonas Bernoulli + 1 Noam Postavsky diff --git a/.config/emacs/lisp/magit/docs/RelNotes/1.4.2.txt b/.config/emacs/lisp/magit/docs/RelNotes/1.4.2.txt new file mode 100644 index 0000000..b50f1a8 --- /dev/null +++ b/.config/emacs/lisp/magit/docs/RelNotes/1.4.2.txt @@ -0,0 +1,23 @@ +Magit v1.4.2 Release Notes +========================== + +Released 8 June 2015 by Jonas Bernoulli. + +This is a bugfix release. + +Changes since v1.4.1 +-------------------- + + * Automatic revers of file-visiting buffers now works again in Emacs + version 24.5. It was broken due to an incompatible change in that + Emacs release. + + * Git's reflogs sometimes end with bogus entries. We now work around + that when listing stashes. + +Authors +------- + + 11 Jonas Bernoulli + 1 Peter Vasil + 1 Steven E. Harris diff --git a/.config/emacs/lisp/magit/docs/RelNotes/2.1.0.txt b/.config/emacs/lisp/magit/docs/RelNotes/2.1.0.txt new file mode 100644 index 0000000..85e8d41 --- /dev/null +++ b/.config/emacs/lisp/magit/docs/RelNotes/2.1.0.txt @@ -0,0 +1,433 @@ +Magit v2.1.0 Release Notes +========================== + +Released 1 July 2015 by Jonas Bernoulli. + +This release marks the end of a commit marathon that lasted for more +than 4700 commits. It is the first major release in over two and a +half years. The last major release was 1.2.0, which was released +under old leadership. Version 1.4.0, which I released earlier this +year, for the most part consisted of changes that prepared for this +release (so you might want to read the respective release notes too). + +This release comes with many new and exciting features, but the most +important change is the massive increase in consistency both in the +user interface and the internal abstractions. + +Magit always provided a very intuitive staging interface, which is +vastly superior to `git add --interactive'. This release extends this +to other apply variants. Starting with this release, other areas have +also begun to be more than just incremental improvements over what Git +itself provides. But this is still limited to certain features which +have gotten more attention than others (most prominently rebasing). + +Interlude +--------- + +The code base is finally in a state that allows me to concentrate on +implementing my vision of what version control could be like. But +this will only be possible if, unlike during the last two and a half +years, I am being paid for my work. + +I intend to run a fund-raising campaign, but you can already donate +now (see http://magit.vc/donations.html). I am also looking for +corporate sponsorship and/or employment. One area where Magit +actually lags behind other Git clients is integration with Git hosting +platforms and code review tools. I hope that these platforms have an +interest in being supported by the best Git client and are willing to +pay for it. + +I am very interested in a job that would let me work on Magit *and* on +other projects, which would benefit from the skills I have acquired +integrating two complex systems and dealing with all the social and +technical challenges that arise when running a popular project. + +Changes since v1.4.0 +-------------------- + + * A new manual has been added. It's much more comprehensive than the + old manual and instead of just documenting the various commands and + options, it also explains concepts and plumbing functions, and + comes with extensive indices for commands, functions, and options. + + Actually three new manuals were added; the packages `magit-popup' + and `with-editor' are documented in separate manuals. + + The manuals are written in Org mode and then exported to Texinfo. + + * Performance is much better now. In most cases this was achieved by + delaying work until it is actually needed. Most importantly diffs + are only partially washed until being fully expanded. Some + features come in a fancy and in a fast variant; when that is the + case, we now usually default to the fast variant. + + * Many options can now be set on a per-repository basis, and the + manual describes how to do so. (Actually this was always possible + but, because it was undocumented, nobody did it.) It's possible to + define "repository classes", e.g. "huge repositories", and then add + the respective repositories to that class. This is very useful in + order to turn off certain features only in repositories where they + would have a negative impact on performance, without having to do + it for each repository individually. + + * Many faces have been simplified. Most importantly, section heading + faces no longer set a background color (except for hunk headings) + and instead just use the default background. Refname faces no + longer set the background color or the box property. + + * Many, probably the majority of, functions, variables, and faces + have been renamed, which was necessary because there was very + little consistency before. + + Most importantly, the names of commands and options now begin with + a prefix that includes the name of the respective git sub-command. + For example, the names of all commands and options related to + diffing now begin with `magit-diff-'. + + Many plumbing functions and variables were also renamed. In some + cases, that also lead to shared prefixes, such as `magit-process-', + `magit-mode-', `magit-git-', and `magit-insert-'. But many + plumbing functions and variables continue to use names whose only + common part is the `magit-' prefix. + + Future renames will be performed at well defined times and obsolete + function/variable definitions will be provided for backward + compatibility. No renames are planned at present. + + * The external libraries `git-commit-mode.el' and `git-rebase-mode.el' + are no longer required and have to be uninstalled because they + conflict with their successors `git-commit.el' and `git-rebase.el', + which are now maintained inside the Magit repository instead of the + Git-Modes repository. + + The library `git-commit.el' can be used without Magit, so it is + distributed as a separate Elpa package. However, `git-rebase.el' + now depends on several Magit libraries and is therefore distributed + as part of the `magit' package. + + * The library `magit-key-mode.el' was removed and replaced with + `magit-popup.el'. The new implementation is much more flexible and + easier to use than the old one. Major new features include setting + default arguments directly inside the popup and macros for defining + new popups and extending existing popups. + + This new library can also be used by packages that are not related + to Magit and is therefore available as a separate Elpa package. + + * The library `with-editor.el' was added. Its purpose is to use the + emacsclient as $GIT_EDITOR when git is started as a subprocess and + requires an editor. This is used while committing and rebasing. + This also works over Tramp, where a "sleeping editor" shell script + is used to communicate over standard output instead of a socket + like the emacsclient does. + + The `1.4.0' release already supported this, but this release splits + this feature into a separate library. And now that it is a separate + library, it can also be used by packages that are not related to + Magit. `with-editor.el' is distributed as a separate Elpa package. + + * All libraries are now located in the new `lisp/' subdirectory. + + * The library `magit.el' has been split into many new libraries. + The code base is now much better organized. Together with the + description of plumbing commands in the manual, this should make it + much easier for contributors to get started. + + * The library `magit-wip.el' has been rewritten from scratch and no + longer depends on the external and unmaintained shell script from + https://github.com/bartman/git-wip. + + * There are now three different modes that commit to the + work-in-progress refs before/after certain events, and in addition + to the old working tree wip refs, these modes now also commit to + index wip refs. When these new modes are turned on, Git's + protection of committed (but dangling) changes is effectively + extended to uncommitted changes (which some exceptions). These + modes are not enabled by default due to performance concerns. + + * The library `magit-blame.el' has been rewritten from scratch. The + new implementation can blame recursively, jump to the next/previous + chunk from the same commit, replace headings with separator lines, + scroll the revision buffer for the chunk at point (like log buffers), + and fine-tune the arguments for `git blame' using a popup. + + * The new library `magit-ediff.el' replaces the old Ediff support. + The new implementation comes with a dwim command and a popup, and + it relies less on high-level functions provided by VC and Ediff + itself, because many of those turned out to be unsuitable. + + * The popular third-party library `dash.el' is now required. This + is the only mandatory external dependency now, except for Git and + Emacs themselves, of course. + + * When using Ido inside Magit, users now have to install the + third-party library `ido-completing-read+.el'. This is necessary + because the function `ido-completing-read', which is part of the + built-in library `ido.el', is not a sufficient drop-in replacement + for `completing-read'. + + * The new macro `magit-insert-section' replaces `magit-with-section'. + The macros `magit-cmd-insert-section' and `magit-git-insert-section' + were removed without a direct replacement. + + * The new functions `magit-insert' and `magit-put-face-property' take + care of working around the fact that negative overlay priorities + are not supported, i.e., that overlays always take precedence + against text properties. Previously this was done in various + places, and not always correctly (e.g., in some cases overlays did + not evaporate). + + * The section visibility and movement commands were rewritten from + scratch. All those commands now share the prefix `magit-section-' + and edge cases are handled better. New commands were added that + allow cycling the visibility of sections and their children. From + a user perspective Magit's section handling is now quite similar to + that of Org mode. + + * The macro `magit-section-action' was removed. The related macro + `magit-section-case' still exists and will continue to do so. The + action variant provided user-customizable hooks, but these hooks + were rarely, if ever, used. Instead of such action hooks, users who + wish to extend Magit now have to use type-specific section keymaps. + + * Section highlighting was rewritten from scratch. The new + implementation uses hooks to allow washing certain section types + differently than others - without obfuscating the simple cases. + Washing diffs is much more complicated than washing all other + sections, and that part has been factored out. The washing of + all other section types is now quite simple. + + * The appearance of the region now indicates whether it is valid as a + selection. As far as Magit is concerned, valid selections are hunk + internal regions and regions that mark sibling sections of the same + type. When a region does not satisfy one of these, then it is + displayed the sames as in other buffers and Magit cannot act on it. + + * The new option `magit-no-confirm' makes it easy to forgo having to + confirm potentially dangerous actions. Many of these actions are + only dangerous for users who don't know how to undo them. When the + wip modes are turned on, many more previously fatal actions can be + easily undone. Adding `safe-with-wip' here makes it unnecessary to + confirm these actions. + + * The new Refs buffer combines the features of the old Wazzup and + Branch Manager buffers into one, more powerful and efficient + synthesis. For each reference, cherries can be shown by expanding + the ref section, but unlike in the Wazzup buffer, the cherries are + not calculated until the expansion happens, making it vastly more + efficient. Besides local and remote branches, the buffer now also + lists tags, and users can add additional sections listing other + refs, e.g., stashes. The format of refs headers is now + customizable. + + * File-visiting buffers are now reverted without using code from the + built-in `autorevert.el` library. The function we previously used + was intended for internal use only and indeed, changes made there + broke Magit in the past. + + * The new option `magit-revert-buffers' controls whether and how + buffers visiting tracked files are reverted. As before, such + buffers are reverted by default. But by default this is now done + rather noisily to encourage users to read the doc-string and + pick what is right for them. It's now also possible to revert + asynchronously and for the user to be asked every time there are + buffers that could be reverted. This option replaces + `magit-auto-revert-mode`. + + * Many new section inserters are available. Some are variations of + default inserters; `magit-insert-unpulled-cherries', for example, is + like `magit-insert-unpulled-commits' but prefixes each commit with + "+" or "-" to indicate its "cherry state". Other inserters are + completely new (e.g., `magit-insert-unpulled-module-commits'). + + * The header sections in status buffers can now be customized using + the new `magit-status-headers-hook'. This is an additional section + insertion hook; separating it from `magit-status-sections-hook' + gives users complete control over what information is displayed in + the headers, while still making the first header the parent section + of all the other header lines. + + * Many commands that previously could only act on the section at + point can now act on all sections selected by a region, which can + span sibling sections of the same type. + + * Many commands now more intelligently dwim based on the section at + point. + + * Where it makes sense, completion and confirmation have been merged + into a single user action. Many commands that previously allowed + carrying out or aborting some action now also allow the user to act + on something different from the default choice. Where one + previously had to confirm with `yes RET', one now confirms with just + `RET' (to accept the default choice, which previously was the only + choice). + + * The distinction between the various "apply variants" has been + clearly worked out, and they now all provide the same feature set. + The variants are: stage, unstage, discard, reverse, and "regular + apply". In all cases, it is possible to act on a file or hunk, or + part of a hunk. When acting on the hunk level, all variants are + implemented on top of `git apply', thus the name "apply variants". + + Un-/staging has always been one of Magit's most beloved features, + and this release takes it to the next level by making the other + apply variants just as consistent, powerful, and intuitive to use. + + All apply variants are context aware, meaning that, for example, the + stage variant knows that an already staged change cannot be staged. + That leads to better error messages. + + * The committing prefix now features additional variants. It was + already possible to quickly create a fixup or squash commit; the + new variants do that and then also instantly perform a rebase to + actually combine these commits with their intended target commits. + + * Rebase sequences are now initiated from the new rebasing prefix. + Several rebasing variants exist, of course including basic + "rebase onto something" and interactive rebase. Other variants + automatically detect and combine squash and fixup commits with + their intended targets. Others let the user edit or reword a + single commit, without having to go through the steps that are + irrelevant in these cases. + + * When a rebase sequence stops at a commit, then the rebasing prefix + instead features suffix commands for continuing, editing, or + aborting the sequence; or skipping the current commit. + + * When a rebase sequence stops, the status buffer displays a list of + the already applied and yet-to-be applied commits. These commits + can be acted on like those in logs. + + * Cherry-picking, reverting, and applying patches using `git am' are + treated the same way as rebasing. A prefix command features + several variants to initiate the sequence. When a sequence is in + progress, then the same prefix instead features suffix commands for + continuing or aborting the sequence, and the status buffer lists + the relevant commits. + + * The magit-specific "rewriting" feature has been removed because it + was a hybrid of "rebasing" and "cherry-picking" and vastly + inferior to both of them. + + * The merging prefix features several new convenient merge variants. + + * Merges can now be previewed before actually carrying them out. + + * When a merge results in conflicts then the commits being merged are + listed in the status buffer, making it easier to review conflicting + changes in the context they were created. + + * Its now possible to discard one side of a conflict directly from + the hunk containing the conflict, using the regular discard key + `k'. It's also possible to restore a conflict. + + * When using an existing branch as the starting-point of a new + branch, it is now automatically configured as the upstream branch. + + * The branching prefix now features suffix commands for un-/setting + the upstream branch. Previously this was coupled with pushing in + a truly obscure way. + + * Branch descriptions can now be displayed in the refs or status + buffer, and the description can be edited using a suffix command + from the branching prefix. + + * The URL of a remote can now be changed from the remoting prefix. + + * A new pulling prefix command was added, which features several new + pulling variants. Previously only one pulling command existed and + it had to be controlled using prefix arguments, which was very + cumbersome. + + * A new pushing prefix command was added, which features several new + pushing variants. Previously only one pushing command existed and + it had to be controlled using prefix arguments, which was very + cumbersome. + + * The various tagging commands are now suffix commands of the new + tagging prefix command. + + * It is now possible to stash, or create a snapshot from, just the + staged or the unstaged changes, instead of both. Suffix commands + for branching, listing, and showing stashes were added to the + stashing prefix + + * When creating stashes the new implementation in `magit-wip.el' is + used instead of `git stash'. This allows the user to create + snapshot stashes without touching any files in the working tree. + + * The submodule prefix now features new suffix commands for adding, + setting up, and fetching modules. + + * Submodules with unmerged commits can now be displayed in the status + buffer. Sections representing submodules can be expanded to show + their unpulled commits. These commits can be acted on like commits + belonging to the super-project. + + * Support for displaying diffs inside the log buffer instead of in a + separate diff buffer has been removed. It might come back one day, + but the old implementation had just fallen behind regular one-line + log too much. + + * The logging prefix features many new infix arguments and suffix + commands, which can now be combined in more flexible ways than + before. + + * Many commands that previously read a single commit, branch, or + file in the minibuffer, can now read multiple, comma-separated items + from the user, while providing completion candidates for all of + them. Likewise, when selecting a range, completion is available + for the second commit too. + + * All of Git's reset variants are now exposed as individual commands, + but not all of them have a key binding by default. + +This was just the tip of the iceberg. + +Authors +------- + + 2187 Jonas Bernoulli + 28 Sebastian Wiesner + 25 Kyle Meyer + 19 Noam Postavsky + 17 Pieter Praet + 12 Rémi Vanicat + 9 Florian Ragwitz + 5 Philippe Vaucher + 5 Ramkumar Ramachandra + 4 Cornelius Mika + 4 Kan-Ru Chen + 4 Syohei Yoshida + 3 Alex Dunn + 3 Alex Kost + 3 Nicolas Richard + 2 Eric Schulte + 2 Ingo Lohmar + 2 Mitchel Humpherys + 2 Peter Eisentraut + 2 Ryan C. Thompson + 1 Adeodato Simó + 1 Andrew Schwartzmeyer + 1 Andy Sawyer + 1 Bradley Wright + 1 Guillaume Martres + 1 John Mastro + 1 John Wiegley + 1 Julien Danjou + 1 Lingchao Xin + 1 Mark Oteiza + 1 Michael Fogleman + 1 Michael Griffiths + 1 Michal Sojka + 1 Natalie Weizenbaum + 1 Oleh Krehel + 1 Peter Vasil + 1 Rüdiger Sonderfeld + 1 Steven E. Harris + 1 Teemu Likonen + 1 Thomas A Caswell + 1 Tim Perkins + 1 Tim Wraight + 1 Wei Huang + 1 Xavier Noria diff --git a/.config/emacs/lisp/magit/docs/RelNotes/2.10.0.txt b/.config/emacs/lisp/magit/docs/RelNotes/2.10.0.txt new file mode 100644 index 0000000..bb42609 --- /dev/null +++ b/.config/emacs/lisp/magit/docs/RelNotes/2.10.0.txt @@ -0,0 +1,85 @@ +Magit v2.10.0 Release Notes +=========================== + +Released 4 January 2017 by Jonas Bernoulli. + +We are pleased to announce the release of Magit version 2.10.0, +representing 85 commits by six people over one month. + +Also see https://emacsair.me/2017/01/04/magit-2.10. + +Changes since v2.9.0 +-------------------- + +* Many new, well organized, libraries were added, consisting of code + that was previously located inside a messier "magit.el". #2908 + +* The function `magit-display-buffer' now sets the focus on the frame + used to display the selected window. #2865 + +* The Custom groups are better organized now. New groups were added, + but many options also moved between groups that already existed + before. 422d776e, 33c5c1ca + +* Many Custom groups and options now link to the relevant Info nodes + and to other relevant groups. 810d7fb4 + +* Many doc-strings were improved, added, and fixed. 47aae617 + +* Added the function `magit-repolist-column-dirty', which can be added + to `magit-repolist-columns' and `magit-submodule-list-columns'. #2907 + +* The obsolete variable `magit-repository-directory-depth' is no + longer defined as an option. 09993c39 + +* The obsolete hook variable `magit-status-refresh-hook' is no longer + defined explicitly. 7e96e831 + +Fixes since v2.9.0 +------------------ + +* Customizations of hooks were ignored, if the `custom-set-variables' + form was evaluated before the Magit libraries were loaded. #2902 + +* When rebase stopped at a commit, point was no longer placed on that + commit. #2884 + +* When creating a commit, `magit-display-buffer-fullcolumn-most-v1' + filled the entire frame, hiding the commit message buffer. #2891 + +* The commands `magit-reflog' and `magit-reflog-current' reported + a revision's reflog as empty when the name of a file in the + repository, relative to the top-level directory, matched the + revision name. 5264ffcb + +* The function `magit-repolist-column-upstream' returned the current + branch instead of its upstream. 46acbd6d + +* The functions `magit-repolist-column-unpulled-from-upstream' and + `magit-repolist-column-unpushed-to-upstream' raised a type error + if the upstream was configured but did not exist. #2904 + +* The default values of the options `magit-submodule-list-columns' + and `magit-repolist-columns' didn't match the documentation and the + Custom type. But the code that that uses these values is resilient + against that defect and so the only effect was that the values were + reported as mismatched in the Custom interface. 79f6af23 + +* The Custom type of option `magit-update-other-window-delay' didn't + match the default value. eb6d8bde + +* The shell command generated by `magit-emacs-Q-command' could end + up trying to load a directory as a library, due to a bug in Emacs. + 83980c66, debbugs#16406 + +This release also contains documentation updates and typo fixes. + +Authors +------- + + 68 Jonas Bernoulli + 13 Kyle Meyer + 1 Aleksey Uimanov + 1 Alexander Gramiak + 1 Noam Postavsky + 1 Wouter Bolsterlee diff --git a/.config/emacs/lisp/magit/docs/RelNotes/2.10.1.txt b/.config/emacs/lisp/magit/docs/RelNotes/2.10.1.txt new file mode 100644 index 0000000..7f90600 --- /dev/null +++ b/.config/emacs/lisp/magit/docs/RelNotes/2.10.1.txt @@ -0,0 +1,57 @@ +Magit v2.10.1 Release Notes +=========================== + +Changes since v2.10.0 +--------------------- + +* The command `ido-enter-magit-status' is now being autoloaded. #2918 + +* The minor-mode `bug-reference-mode' is now being suggested when + customizing `magit-revision-mode-hook' and `git-commit-setup-hook'. + e0d57c49 + +* The function `magit-version' can now deal with the Magit libraries + being symlinked to, which is required for the new `straight' package + manager. #2967 + +Fixes since v2.10.0 +------------------- + +* When multiple stashes were selected by the region, responding "no" + when asked to confirm the deletion of these stashes resulted in a + type error. #2917 + +* The function `magit-split-range' choked on ranges if one of the + revisions was omitted, breaking a diff variant and potentially + other uses as well. #2928 + +* The function `magit-commit-setup' called without an argument, which + causes the option `enable-local-variables' to be ignored. #2946 + +* When committing inside a repository that was created using `git + init --separate-git-dir', the diff buffer was empty, instead of + showing the changes about to be committed. For some reason that + git command, unlike other commands that do essentially the same + thing, does not set `core.worktree', which confused Magit. #2955 + +* In the repository list buffer, the columns that are supposed to list + unpushed and unpulled commit counts, were blank. #2960 + +* The command `magit-reflog-head' did not properly format reflog lines + for branch renaming events. 2a268e20 + +* The commands `magit-diff-show-or-scroll-down' and + `magit-diff-or-scroll-up' scrolled instead of updated the revision + or stash buffer, when that already showed the requested reference + but that reference no longer pointed at the same revision. #2966 + +This release also contains typo fixes and other documentation fixes. + +Authors +------- + + 16 Jonas Bernoulli + 4 Kyle Meyer + 2 Alex Kost + 1 Kévin Le Gouguec + 1 Radon Rosborough diff --git a/.config/emacs/lisp/magit/docs/RelNotes/2.10.2.txt b/.config/emacs/lisp/magit/docs/RelNotes/2.10.2.txt new file mode 100644 index 0000000..bcaa040 --- /dev/null +++ b/.config/emacs/lisp/magit/docs/RelNotes/2.10.2.txt @@ -0,0 +1,47 @@ +Magit v2.10.2 Release Notes +=========================== + +Changes since v2.10.1 +--------------------- + +* The new command `git-rebase-noop' adds a noop action during a + rebase. It can be used to make git perform a rebase even if none + of the commits are selected. #2991 + +Fixes since v2.10.1 +------------------- + +* Cherry-picking a commit with multiple parents was not possible, + because "--mainline" was treated as a switch rather than an option, + and because of a too-strict assertion that only single-parent commits + can be cherry-picked. #2978 + +* `magit-abbrev-length' mishandled two edge cases, returning 0 when + called within an empty repository or outside of a repository. + 077740f5 + +* A bug fix in the last release broke the visit-file functionality in + diff buffers displayed while committing. #2988 + +* Diff buffers did not recognize "rev^-n" as a short-hand for + "rev^n..rev" (new in Git v2.11), resulting in the buffer header + incorrectly indicating that the diff was between "rev^-n" and the + working tree. 293f0cc8 + +* In diff buffers created using the dotted range notation, the command + `magit-diff-visit-file' incorrectly swapped which revision was + visited for deleted and added lines. For example, with the range + "rev1..rev2", calling `magit-diff-visit-file' on a deleted line + visited the blob for rev2. c24f32cd + +This release also contains other minor improvements, bug fixes, and +documentation fixes. + +Authors +------- + + 10 Jonas Bernoulli + 9 Kyle Meyer + 1 Ben North + 1 Fabian Wiget + 1 Mark Oteiza diff --git a/.config/emacs/lisp/magit/docs/RelNotes/2.10.3.txt b/.config/emacs/lisp/magit/docs/RelNotes/2.10.3.txt new file mode 100644 index 0000000..1a77c40 --- /dev/null +++ b/.config/emacs/lisp/magit/docs/RelNotes/2.10.3.txt @@ -0,0 +1,41 @@ +Magit v2.10.3 Release Notes +=========================== + +Changes since v2.10.2 +--------------------- + +* The new command `magit-do-async-shell-command' opens the file at + point with `dired-do-async-shell-command'. "&" is now bound to + this command. #2992 + +Fixes since v2.10.2 +------------------- + +* The command `magit-bisect-run' now uses a shell to run the command + entered in response to the "Enter shell command" prompt. #3001 + +* Discarding a renamed file failed if the original file was within a + directory that no longer existed. #2998 + +* When inserting information about a rebase in progress into the + status buffer, "exec" lines were treated as a commit, leading to an + error. #3002 + +* The command `magit-blame' failed in blob-visiting buffers if the + corresponding file no longer exists in the HEAD or the index. + +* The command `magit-remote-add' asked whether to set the new remote + as the `remote.pushDefault', when that variable is already set and + and it was configured not to ask in that case. 4f565039 + +This release also contains typo fixes and documentation improvements. + +Authors +------- + + 10 Jonas Bernoulli + 2 Kyle Meyer + 1 Basil L. Contovounesios + 1 Damien Cassou + 1 Duianto Vebotci + 1 Noam Postavsky diff --git a/.config/emacs/lisp/magit/docs/RelNotes/2.11.0.txt b/.config/emacs/lisp/magit/docs/RelNotes/2.11.0.txt new file mode 100644 index 0000000..5ceb776 --- /dev/null +++ b/.config/emacs/lisp/magit/docs/RelNotes/2.11.0.txt @@ -0,0 +1,210 @@ +Magit v2.11.0 Release Notes +=========================== + +Released 13th September 2017 by Jonas Bernoulli. + +I am pleased to announce the release of Magit version 2.11.0, +representing 303 commits by 26 contributors over six months. + +Also see https://emacsair.me/2017/09/12/magit-2.11. + +Changes since v2.10.3 +--------------------- + +* The popup `magit-remote-popup' now exposes the `-f' switch for `git + remote add', which allows the user to control whether information + from the remote is fetched after the remote is added. The default + behavior is still to fetch after adding a remote (i.e., the switch + is enabled by default). #2997 + +* Added option `magit-list-refs-sortby' to allow more control over the + order of refs in prompts. #2872 + +* The Magit wrappers around the default Emacs completion functions now + override the default behavior of alphabetically sorting choices when + displaying them in the "*Completions*" buffer. In repositories with + many release tags, the new behavior prevents completion prompts from + being dominated by version tags instead of branch names. #2925 + +* The commands `magit-git-command', `magit-git-command-topdir', + `magit-shell-command', and `magit-shell-command-topdir' now use + `read-shell-command' to read the command and a shell to run it. + Packages like `pcmpl-git' and `bash-completion' can now be used + to get command-line completion when using these commands. #2951 + +* The commands `magit-git-command' and `magit-git-command-topdir' can + now call arbitrary commands. The initial-value when reading the + command is "git ", and you can remove that to call something else. + #2951 + +* Added option `magit-shell-command-verbose-prompt'. #2951 + +* The function `magit-branch-or-commit-at-point' now offers the + appropriate default choice in a `magit-merge-preview-mode' buffer + and in blob-visiting buffers. #3039, #3066 + +* On Travis tests are now run against all supported Emacs releases, as + well as against snapshots of the `master' and `emacs-25' branches. + #3046 + +* Added command `magit-debug-git-executable'. #3044 + +* Added new function `magit-display-file-buffer-other-window' to be + used as `magit-display-file-buffer-function'. + +* Added `--mainline' switch to `magit-revert-popup'. #3018 + +* Added `magit-file-checkout' to `magit-reset-popup'. #3052 + +* When a revision is shown from a log buffer, the revision buffer now + inherits the file restriction of the log buffer. #3056 + +* Added new command `magit-diff-toggle-file-filter'. #3062 + +* Added new option `magit-use-sticky-arguments' that provides more + control over how diff and log commands reuse arguments from existing + buffers. #3074 + +* Added imenu support in log, revision, and status buffers. #3022 + +* Added command `magit-abort-dwim` to abort the current operation. + Depending on the context, this will abort a merge, a rebase, a + patch application, a cherry-pick, a revert, or a bisect. #3017 + +* The command `magit-clone' now suggests a directory name that more + closely follows `git clone' when no directory is given. #3079 + +* The commands `magit-subtree-add', `magit-subtree-pull', and + `magit-subtree-push' now offer more completion candidates. #3081 + +* The log buffer now shows the line range restriction (i.e., `-L' + argument) in its header. #3075 + +* Added new functions `magit-repolist-column-branches' and + `magit-repolist-column-stashes', which insert the count of branches + and stashes into submodules and repository list buffers. By default + they are used in submodule lists but not in the repository list. + +* Text inside brackets in commit messages (including when shown in a + log) are now highlighted using face `magit-keyword'. + +* Invocations of git are cached over the whole body of + `magit-run-git', not just during the status buffer refresh. This + should make staging and unstaging slightly faster. #3096 + +* When reading a value for the `--reuse-message' option, the popup + `magit-commit-popup' now prompts with all ref names, offering + `ORIG_HEAD' as the default if it exists. #3110 + +* Added bookmark support in status, refs, log, reflog, stashes, + cherry, diff, revision, stash, and submodule-list buffers. #3113 + +* Added new function `magit-insert-modules', a wrapper around the + existing `magit-insert-modules-*' functions. Also added options + `magit-module-sections-hook' and `magit-module-sections-nested', + to allow tuning the behavior of this function. #3141 + +* Renamed function `magit-insert-submodules' to + `magit-insert-modules-overview' for consistency with other + `magit-insert-modules-*' functions. #3141 + +* Inserting module sections is much faster now. #3141 + +* Added `--no-verify' switch to `magit-rebase-popup'. #3144 + +* The `--no-verify' switch in `magit-commit-popup' is now bound to "h" + instead of "n" for consistency with `magit-push-popup' and + `magit-rebase-popup'. #3144 + +* Added support for the file "EDIT_DESCRIPTION", which is used instead + of "BRANCH_DESCRIPTION" for editing a branch's description as of Git + 2.13.0. #3149 + +Fixes since v2.10.3 +------------------- + +* Rebasing was sometimes interrupted by an error about the index lock + already being held. This happened because VC asynchronously checks + for files with conflict, which involved using a git command that + grabs the lock. Magit now redefines that VC command to use a git + command that does not grab the lock. #2708, debbugs#21559 + +* Adding an untracked subdirectory as a submodule failed if a remote + was not configured for the subdirectory repository. #3047 + +* Parsing the log buffer failed if the log displayed a ref that + contained parentheses in its name. #3028 + +* Parsing the `git show' and `git log' output for a signed commit + failed with the Git variable `log.showSignature' enabled. #3061 + +* When deleting the current branch, `magit-branch-delete' did not ask + for confirmation in some cases. #3058 + +* When using a non-standard `magit-display-file-buffer-function' that + does not select the window used to display the buffer, then the + point in that window was not adjusted. #3082 + +* `git-rebase-mode' did wrongly assume that there is no space after + the comment character in action lines that are commented out. #3085 + +* The command `magit-show-commit' mistakenly displayed a tag's commit + when point was on a branch with the same name. #3098 + +* The command `magit-log-buffer-file' miscalculated line numbers from + the region. #3075 + +* Staging a link failed when it points to a repository. + +* When setting the upstream of a branch that isn't the current branch, + the user was asked what branch to use as the upstream of the current + branch anyway, even though the correct branch would then be modified. + +* When deleting a branch that is merged into the current branch but + not into its own upstream branch, then the user was not offered to + force the deletion, causing it to fail. #3107 + +* With `find-file-visit-truename' set to a non-nil value, the commands + `magit-status' and `magit-init' failed to detect when their + directory argument was a symlink that resolved to the output of + `magit-toplevel'. #3115 + +* Using an url instead of a remote name as `branch..remote' was + not properly supported, causing issues when trying to pull or push. + #3116 + +* The log margin displayed invalid information for cherries. #3163 + +This release also contains the fixes described in the v2.10.{1,2,3} +release notes, as well as other minor improvements, bug fixes, typo +fixes, and documentation fixes. + +Authors +------- + + 148 Jonas Bernoulli + 93 Kyle Meyer + 15 Damien Cassou + 15 Noam Postavsky + 5 Basil L. Contovounesios + 3 Justin Guenther + 2 Alex Kost + 2 Duianto Vebotci + 2 Radon Rosborough + 2 Štěpán Němec + 1 Adam Benanti + 1 Allen Li + 1 Ben North + 1 Erik Anderson + 1 Eyal Lotem + 1 Fabian Wiget + 1 Ioan-Adrian Ratiu + 1 Jeremy Meng + 1 Justin Burkett + 1 Justin Thomas + 1 Kévin Le Gouguec + 1 Marc Sherry + 1 Mark Karpov + 1 Mark Oteiza + 1 Sean Whitton + 1 Yuri Khan diff --git a/.config/emacs/lisp/magit/docs/RelNotes/2.12.0.txt b/.config/emacs/lisp/magit/docs/RelNotes/2.12.0.txt new file mode 100644 index 0000000..5f1980b --- /dev/null +++ b/.config/emacs/lisp/magit/docs/RelNotes/2.12.0.txt @@ -0,0 +1,645 @@ +Magit v2.12.0 Release Notes +=========================== + +Released 29th March 2018 by Jonas Bernoulli. + +I am pleased to announce the release of Magit version 2.12.0, +representing 610 commits by 30 contributors over six months. + +Also see https://emacsair.me/2018/03/29/magit-2.12. + +Upcoming breaking changes +------------------------- + +* An upcoming release will remove support for older versions of Emacs. + It isn't yet certain in what Magit release that will happen and what + the new minimal version of Emacs will be. You should consider to + update to the latest Emacs release now, or at least to v25.1, which + was released one and a half years ago. + +* Likewise support for older versions of Git is going to be removed. + You should update to at least v2.4, which was released almost three + years ago. Older releases don't get security updates anymore, which + is another reason to update. + +* The option `magit-no-confirm-default' has been demoted to a variable + and will be removed in v2.13.0. Please migrate your customizations + to the new option `magit-dwim-selection'. #3232 + +Changes since v2.11.0 +--------------------- + +* Added new commands `magit-previous-line' and `magit-next-line' as + substitutes for `previous-line' and `next-line'. Magit's selection + mechanism is based on the region but selects an area that is larger + than the region. This causes shift-selection to select two lines on + the first invocation when using the vanilla commands. On section + headings and inside hunk bodies the new magit-specific variants + don't move point on the first invocation and thereby they only + select a single section or line. Which inconsistency you prefer + is a matter of preference. #2912 + + To use the Magit-specific variants add this to your init file: + + (define-key magit-mode-map [remap previous-line] 'magit-previous-line) + (define-key magit-mode-map [remap next-line] 'magit-next-line) + +* The command `magit-refs-popup' now remembers arguments and they are + displayed in the header-line of `magit-refs-mode' buffers. The popup + command still invokes the default action by default when invoked from + another buffer, but when invoked from a `magit-refs-mode' buffer it + now shows the popup. #2898 + +* The module overview section now shows a hash for modules that don't + have a tag and column alignment is optimized. #3160 + +* The diff that is being displayed while committing learned about a + few more special cases. #3095 + +* Added new command `magit-branch-or-checkout' as a potential + substitute for `magit-checkout'. Setup instructions can be found in + the manual. #3104 + +* Added new customizable options `magit-log-highlight-keywords' and + `magit-diff-highlight-keywords', which control whether text inside + brackets is highlighted in magit-log and magit-diff buffers + respectively. #3190 + +* When the names of Magit buffers are not uniquified then their names + now end with an asterisk. When the `uniquify' package is used, then + that still is not possible due to limitations in that package. #2841 + +* When selecting a fixup target then the log graph, which makes it + less likely that you attempt to modify a merged commit, which would + result in the merges being lost when rebasing. c0209c74d + +* Added the existing commands `magit-blame' and `magit-blob-next' to + the `magit-file-popup' popup. + +* Added new command `magit-blame-reverse'. See the updated manual + for information on how to best use this and other blaming commands. + #3055 + +* Keywords in brackets are now being highlighted in `magit-refs-mode' + and `git-rebase-mode' buffers, and the headers of `magit-status-mode' + buffers, like they already were in logs. #3179 + +* Added new variable `magit-buffer-lock-functions' to support + third-party packages in creating Magit-like buffers. #3191 + +* Improve padding of head-line and add new faces `magit-header-line-key' + and `magit-header-line-log-select'. #3194 + +* When a stash has a note attached to it, then show it in the + `magit-stash-mode' buffer. aff2fba8f + +* Added new command `magit-rebase-remove-commit' to the rebase popup. + +* The remote popup can now be used to set various remote related + variables. #3165 + +* Added new commands `magit-patch-apply' and `magit-patch-apply-popup'. + The latter is available from inside `magit-am-popup' ("w"). #2940 + +* Added new command `magit-patch-save' for saving a diff into a patch + file. In diff buffers it is bound to "C-x C-w". #2950 + +* Added new command `magit-stash-branch-here', which — unlike the + existing `magit-stash-branch' — creates a branch that starts at + the current HEAD instead of at the commit that was current when + the stash was created. #2935 + +* Added new command `magit-dired-log' intended to be bound in + `dired-mode-map'. #3011 + +* The list of rebase actions displayed in the status buffer now also + shows "exec" actions. #3003 + +* While it exists, the stash created by `git rebase --autostash' is + now also displayed in the list of stashes. #3146 + +* When the current branch has no upstream or when all commits have + already been pushed there, then the status buffer now shows + `magit-log-section-commit-count' recent commits. If you previously + used `magit-insert-unpulled-from-upstream-or-recent', then remove + that from `magit-status-sections-hook', as it is an obsolete alias + for `magit-insert-unpulled-from-upstream' now. #3227 + +* When switching between showing "Unmerged into " and + "Recent commits", preserve the visibility of that section. #3227 + +* When prompting for a branch to delete, the current branch is no + longer offered as default choice, except in cases where it is likely + that that is actually what the user wants. #2924 + +* Added new popup `magit-worktree-popup' and bound "%" to it. #2927 + +* The commands `magit-file-delete' and `magit-file-untrack' now act on + the selected files and with a prefix argument they force the action. + #2930 + +* When requesting the history of a single file that is no longer being + tracked, use the `--full-history' argument. Otherwise no history at + all would be shown. #3012 + +* Added new option `magit-patch-save-arguments'. #3218 + +* Leading tabs in files no longer cause misalignment in diffs. This + is done by overriding the mechanism used by the display engine to + determine how wide a tab should be, which doesn't work when there + are additional characters before the "leading" tabs that should + count as an additional, but very short tab-stop. #3185 + +* The command `magit-visit-ref' now drops the prefix argument before + calling `magit-show-commit' when appropriate, and when using the + `create-branch' variant and the branch exists, then it offers to + simply checking it out instead of resetting it first. #3009 + +* The output of `magit-list-repositories' is now sorted by module path + instead of module name. b6f6cf4a6 + +* For a long time Magit has supported selecting two or more sibling + sections using the region and then acting on that selection instead + of only on the current section. Single-section selections were not + supported and a region that did not span multiple siblings was not + visualized as a selection. Now that is supported. + + Not every section-aware command was adjusted to take single-section + selections into account because in many cases that would have led to + undesired changes in behavior. #3026 + +* The command `magit-branch-spinoff' now spins off just HEAD when that + constitutes the single-section selection. Previously one could only + spin off all commits that weren't in the upstream yet or at least + two commits. #2920 + +* Added switch `--local-user' to the tag popup. #3237 + +* When discarding untracked files, then offer to delete the buffers + visiting them. #3243 + +* When there is a valid selection based on the region, then the region + itself was never visualized. Now it is, but only if it stays within + a single line. #3249 + +* Added new command `magit-branch-checkout' and bound "l" in the + branch popup to it. This command always checks out a local branch. + Valid inputs are an existing local branch, a remote branch for which + no corresponding local branch exists, and a new branch name that + doesn't match the name of any existing local or remote branch. #2906 + +* The command `magit-show-commit' now offers the revision at point as + the default completion choice if the less generic mechanisms used to + determine the "current" revision fail. This is useful for visiting + revisions mentioned in commit messages. #2949 + +* Hashes inside commit messages are now turned into `commit' sections. + Note that this can be disabled and that even if you do so you can + still visit the commit at point using "RET". #2949 + +* The documentation regarding completion, confirmation, the selection, + and the hunk-internal region was significantly extended. It might + be worth reading that. + +* Added new option `magit-dwim-selection', which allows configuring + commands that would otherwise ask the user to select among possible + candidates to use the default instead, with or without confirmation. + #3232 + +* When there is a stash at point, then the commands `magit-stash-drop' + and `magit-stash-pop' now ask for confirmation. The former command + previously allowed users to select another stash instead and the + latter used to act on the stash at point without giving the user a + chance to abort. These changes are implemented using the new option + `magit-dwim-selection' and can easily be reverted. #2916 + +* Aborting a commit is seen as an error by Git and like all such + errors it was reported to users, which led to confusion and a few + bug reports. Now that non-error is being suppressed. #2932 + +* The option `magit-ref-namespaces' was demoted to a variable and its + format changed. #2923 + +* Some refs that are being displayed in logs are now being compressed + to save space while providing more information. #2923 + +* Added new option `magit-submodule-fetch-jobs'. By default multiple + modules are being fetched in parallel now. #3261 + +* The command `magit-show-commit' now also shows notes specified using + `notes.displayRef', not just those specified using `core.notesRef'. + #2857 + +* The package `magit-popup' is maintained in its own repository now. + 4d5d9bfac + +* The popup `magit-notes-popup' now shows the values of the relevant + variables and allows changing them. #2857 + +* The cherry-picking commands now try to use or not use the + `--mainline' argument as appropriate instead of erroring out. #2980 + +* Added `magit' as an alias for `magit-status' because I have been + told that that improves discoverability. This might or might not + make it easier for users to get started with Magit without taking + a brief glimpse at the documentation. #3290 + +* The command `magit-log-buffer-file' now also works in Dired buffers. + +* The commands `magit-stage-untracked' has been taught about the Borg + package manager. When staging a package repository it now offers to + also assimilate (aka install) that package. dc857e2ed + +* Added new command `magit-browse-pull-request', which reads an open + pull request and then visits it in a browser. For now this only + supports Github, but other Git forges will be supported in the + future. #3134 + +* Added new commands `magit-checkout-pull-request' and + `magit-branch-pull-request' to the branch popup. For now they only + support Github, but other Git forges will be supported in the future. + #3134 + +* The command `magit-branch-delete' now offers to also delete the + corresponding remote after deleting a local branch that was created + with `magit-branch-pull-request' or `magit-checkout-pull-request', + provided that remote has no other tracking branches. #3134 + +* When it is not possible to blame in reverse, then the blame popup + does not offer that command anymore. c6ef61b2e + +* The mode line process indicator, displayed in the mode line when Git + is run for side-effects, is now more visible than before, and is + additionally used to highlight process errors. + + New face `magit-mode-line-process' is applied to the mode line + process indicator to improve the visibility of pending asynchronous + processes (in particular), as Magit remains responsive after + initiating such commands (for instance fetching or rebasing), but + will not update its buffers until the process has completed, which + might take longer than anticipated. Customize this face if you wish + to make this indicator more (or less) visible. #3284 + + If the Git process returns an error, the mode line process indicator + is no longer removed, and new face `magit-mode-line-process-error` + is applied to highlight the error status. Details of the error from + the process buffer are also provided as a tool-tip. The error + indicator will remain visible in the mode line until a magit buffer + is refreshed. If you do not want errors to be indicated in the mode + line, customize the `magit-process-display-mode-line-error' user + option. #3297 + +* When staging and unstaging at the file level and there are arguments + that cause whitespace differences to be hidden, then apply the + visible changes using `git-apply' instead of using `git-add' and + `git-rm' because doing that would also un-/stage the invisible + changes. #3102 + +* Added new command `magit-diff-visit-file-other-window'. It isn't + bound by default because that would result in changes to existing + key bindings, which is something that is frowned upon. To use this + command add something like this to your init file. #2833 + + (define-key magit-file-section-map (kbd "SPC") + 'magit-diff-visit-file-other-window) + (define-key magit-hunk-section-map (kbd "SPC") + 'magit-diff-visit-file-other-window) + +* The widths of tabs in diffs can now be adjusted to match the widths + that would be used in the corresponding file-visiting buffers. This + is disabled by default because it can be expensive to determine the + appropriate values (and also unnecessary when using spaces for + indentation). Use the new option `magit-diff-adjust-tab-width' to + control if and when the tab widths should be adjusted. #2929 + +* Added documentation about how to contribute to the documentation. + +* In the references buffer the remote part of the branch names are now + hidden in the remote specific lists of branches by default, which is + done to preserves space. The option `magit-refs-show-remote-prefix' + can be used to revert this change. + +* The mode `git-commit-mode' now offers three font-lock levels, + including one that is fruitier than the previous font-lock level. + Local and remote branches are shown using different colors now. + 7a50bfdb0 ff + +* When a signed tag points at the shown revision, then the revision + buffer now also contains information about the tag signature. #3015 + +* The commands `magit-remote-remove' and `magit-branch-delete' now + unset the relevant push-remote related variables, which Git fails to + do, unlike for other variable affected by the removal of a remote or + branch. Likewise the command `magit-remote-rename' now renames such + variables. #2850 + +* Depending on the value of the new `magit-branch-rename-push-target' + option the command `magit-branch-rename' may now also preserve the + local branch's push-remote or even rename the push branch on the + remote. The default is to do both. #2850 + +* Added argument `--subject-prefix' to the patch popup. 24ce90832 + +* The section visibility is now being cached for all sections. + Previously this was only done for some sections. When a section + disappeared and later appeared again, then it went back to its + initial visibility. The option `magit-section-cache-visibility' can + be used to restrict the cache to certain sections again. #2780 + +* The section visibility cache can now also remember that a section + should be expanded instead of being hidden when the latter is the + default and the section reappears. Previously only the opposite + was possible. #2780 + +* For `magit-status-mode' and `magit-refs-mode' buffers the visibility + cache now persists when killing the buffer. #2780 + +* Added command `magit-remote-prune-refspec', which is necessary + because Git does not ignore invalid refspecs and instead refuses + to fetch using only the refspecs that are still valid. #3134 + +* Sections are now defined as classes instead of as structs. This + is only a first step towards taking advantage of generic methods. + A few subclasses are already being defined and dedicated slot + accessors have been deprecated in favor of `oref'. 651a9abcc ff + +* When asking the user whether to save modified file-visiting buffers + during a refresh, then also allow them to remember the choice for + the current session. I still think it is better to just always save + by setting the option `magit-save-repository-buffers' to `dontask'. + #3344 + +* The terminology about modules as used by Git is ambiguous. Magit + now avoids the term "initialized" and instead uses the term + "populated" to refer to a module whose working directory exists. + The names of commands have been adjusted accordingly. For example, + unlike "git submodule init", which does *not* actually "initialize" + a module, `magit-submodule-popuplate' does "populate" a module + (using "git submodule update --init"). #2911 + +* Most module commands now default to act on the selected modules or + if no modules are selected the current module, if any. Otherwise + they fall back to read a single module from the user. Previously + some of these commands acted on all modules and it was not possible + to perform the respective actions on a subset of modules. Acting + on all suitable modules is still possible using a prefix argument. + #2911 + +* Many arguments have been added to the module popup. #2911 + +* Added new option `magit-refs-filter-alist', which allows omitting + some references from being displayed in `magit-refs-mode' buffers. + +* Added new command `magit-merge-squash'. #3348 + +* Several new libraries were created from code previously in magit.el. + 0d6389680 + +* Added new commands `magit-merge-absorb' and `magit-merge-into', + which not only merge a local branch into another but also remove + the merged branch. #2922. + +* Added new commands `magit-cherry-harvest', `magit-cherry-donate', + `magit-cherry-spinout' and `magit-cherry-spinoff', which move + commits from one branch to another and also remove them from the + branch where they were previously located. #2921 + +* Added new command `magit-diff-unmerged' and taught `magit-diff-dwim' + about unmerged changes too. #3382 + +* The command `magit-push-refspecs' got its own history variable. + #3361 + +* By default the names of Magit buffers now either have a star at both + ends, or at neither when using the `uniquify' package. 831372a4f + +* Added new commands `magit-branch-shelve' and + `magit-branch-unshelve'. Use them to replace a branch with a less + visible ref while preserving the ref log. This is useful for work + that you probably but not certainly will end up discarding. You + might want to add these commands to the branch popup. 568b11f64 + +* The look of `magit-refs-mode' buffers was changed to save horizontal + space and three new options `magit-refs-primary-column-width', + `magit-refs-focus-column-width' and `magit-refs-pad-commit-counts' + were added. #3378 + +* When the dispatch popup is invoked in non-Magit buffers, then certain + actions that cannot be used there are no longer shown. 83cc91a30 + +* When the dispatch popup is invoked in a file-visiting buffer, then + it now also lists the actions from the file popup. 40361273a + +* Added new variable `magit-log-format-message-function'. #3384 + +* Added commands `magit-commit-reshelve' and `magit-reshelve-since', + replacing and improving upon commands from the `magit-rockstar' + package, which was deprecated. The former changes the dates of HEAD + and the latter those of a range of commits leading up to HEAD. + +* Added argument `--reverse' to the log popup. When that argument is + used, then the incompatible `--graph' is silently dropped. 07e1d69d2 + +* Added new option `magit-log-header-line-function'. #3395 + +* Added new command `magit-remote-prune'. 6258dd92c + +* Added new hook `magit-unwind-refresh-hook', which is like the + existing `magit-post-refresh-hook' except that is runs even if an + error occurs during the refresh. 9f838cc04 + +Fixes since v2.11.0 +------------------- + +* `git-commit-propertize-diff' could end up making the buffer + read-only. 746f2361b + +bc1093846 magit-popup: locally set help-window-select when describing function +c9689c670 magit-popup: locally set another display-buffer variable + +* `git-rebase-mode-show-keybindings' failed to process non-English + usage instructions in interactive rebase buffers. #3175 + +* The refresh cache was not properly invalidated after creating a new + repository. 7a1f1eb44 + +* The `with-editor-mode' minor-mode was sometimes enabled twice in the + same buffer. 9be36868b + +* For bare repositories all files were shown as being deleted in some + contexts. b5f05c457 + +* When a command was invoked from a popup and it set `this-command', + then that was later overwritten. a74c9b9d4 + +* While setting `magit-credential-cache-daemon-socket's initial value + an error occurred when `credential.helper's value is the empty string. + 4b15d5825 + +* Fixup commands did not warn about merges in the rebase range until + after creating the fixup commit. #3176 + +* Instant fixup allowed selecting a commit that is not reachable from + HEAD, which, for the instant variants (but only those), clearly is + a user mistake that should be caught immediately. #3176 + +* If `magit-git-executable' is an absolute path, then an error + occurred in `magit-debug-git-executable'. 9b7e34c29 + +8ed2eb4f5 magit-branch-reset: use magit-local-branch-at-point + +* The previous window configuration was not restored by + `magit-log-select-pick' and `magit-log-select-quit'. #3211 + +* When `magit-branch-spinoff' failed to perform the checkout it + never-the-less attempted to perform the subsequent steps. #3210 + +* Jumping to the correct location in a man page failed for many + switches and options. deb482063 ff + +* The default action of `magit-branch-config-popup' was a command that + isn't even available in the popup. eaa836fe2 + +* The command `magit-branch-spinoff' didn't try to prevent the user + from entering a string containing whitespace as a branch name. + bd6055ab2 + +* The command `magit-commit' failed to commit everything after asking + for confirmation if it is called from a subdirectory. #3221 + +* The command `magit-completing-read' didn't offer any completion + candidates. 387257f20 + +* In some cases an error occurred when showing the remote popup because + the length of the remotes name was not taken into account. a9177e5b9 + +* The command `magit-branch-rename' failed to rename a local branch if + a tag existed with the same name. #3222 + +* The command `magit-file-delete' ignored the prefix argument instead + of forcing the action as intended. 0df686bfd + +* Fixed a broken highlighting special case. #3238 + +* When staging all unstaged changes using "s" on "Unstaged changes" + while there also are staged changes, then the user was not asked for + confirmation. #3238 + +* When reverting a commit users are required to edit the revert + message on some platforms but not on others. #3239 + +* In a secondary worktree `magit-git-dir' failed to return a remote + path when the repository is accessed using Tramp. #3228 + +* When the user chose the default offered by `magit-patch-apply', + then that function failed to expand the file-name so that Git would + understand it. ab00c5ba2 + +* The face `magit-graph' was also used for the commit message, which + only was noticeable when the face was customized. It appears that + nobody ever did that. 47e94767b + +* When `magit-branch-read-upstream-first' is nil, then the value + returned by `magit-branch-read-args' was broken. #3268 + +* Fixed encoding of non-ascii filename arguments to git on + `windows-nt' systems. #3250 + +* A bug in `magit-list-active-notes-refs' slowed down + `magit-show-commit'. #3275 + +* The command `magit-worktree-checkout' wasn't able to checkout + arbitrary commits, just refs. #3277 + +* Due to misunderstood `flyspell' implementation details + `git-commit-turn-on-flyspell' did some unnecessary work and made + claims that are not actually true. 24c966082 + +* When the git executable could not be found, then Magit often claimed + that the user was doing something outside of a Git repository + instead. #3310 + +* The command `magit-submodule-add' always used a kludge that is + only needed when using Ido, resulting in a unnecessary removal + of functionality. 5e43377d2 + +* The function `magit-maybe-save-repository-buffers' in some cases + needlessly redisplayed a message. #3319 + +* The branch description was displayed in weird ways in a few places. + d98c44bd7, 9003b85da + +* When stashing untracked files, then the untracked files in + subdirectories were not removed from the working tree. #3334 + +* The command `magit-worktree-delete' failed to delete a worktree when + its directory no longer existed. #3355 + +* A kludge used to work around a bug in Emacs 24 prevented + `magit-copy-buffer-revision' from deactivating the mark. #3352 + +* When visiting the last blob that still had the line at point in a diff, + then that only jumped to the correct line, but not the correct column. + ebe3b5229 + +* For unpopulated modules `magit-list-submodules' showed information + about the super-repository instead. Now such modules are omitted. + 1c4fa9b14 + +* The commands `magit-am-apply-patches' and `magit-am-apply-maildir' + did not work over Tramp because they passed Tramp file names directly + to git. This was fixed in a way that should prevent similar issues + elsewhere. #3368 + +* The function `magit-branch-commit-at-point' preferred tags over + branches, which is a strange default for most callers. f2b318856 + +* The arguments set in the popup were ignored when displaying tags + in refs buffers. ae007a757 + +* When `magit-diff-section-arguments' calls for it, then all + diff-related sections are supposed to be limited to a subdirectory, + but sections listing untracked and tracked files ignored it. #3376 + +* Saving wip refs often failed because `magit-update-ref' used the + refresh cache. e0e1a44f3 + +* Buffers listing repositories using `tabulated-list-mode' did not + preserve point when being refreshed. 2f0302635 + +This release also contains other minor improvements, bug fixes, typo +fixes, and documentation fixes. + +Authors +------- + + 500 Jonas Bernoulli + 26 Kyle Meyer + 15 Phil Sainty + 13 Alexander Gramiak + 13 Noam Postavsky + 7 Sean Allred + 4 Basil L. Contovounesios + 3 Bastian Beischer + 3 Damien Cassou + 3 Štěpán Němec + 2 Bar Magal + 2 Daniel Mai + 2 Matthew Fluet + 1 Chris LaRose + 1 Daniel Gröber + 1 Daniel Kraus + 1 David Ellison + 1 Fritz Stelzer + 1 Jim Blandy + 1 John Mastro + 1 Kenny Ballou + 1 Matthieu Hauglustaine + 1 Matus Goljer + 1 Orivej Desh + 1 Philipp Stephani + 1 Radon Rosborough + 1 Vladimir Panteleev + 1 Wilfred Hughes + 1 Wouter Bolsterlee + 1 Xu Chunyang diff --git a/.config/emacs/lisp/magit/docs/RelNotes/2.12.1.txt b/.config/emacs/lisp/magit/docs/RelNotes/2.12.1.txt new file mode 100644 index 0000000..a7e0971 --- /dev/null +++ b/.config/emacs/lisp/magit/docs/RelNotes/2.12.1.txt @@ -0,0 +1,16 @@ +Magit v2.12.1 Release Notes +=========================== + +Fixes since v2.12.0 +------------------- + +* Magit 2.12.0 depended on a non-existent Magit-Popup version. + +* Key bindings in `magit-remote-popup' conflicted. + +Authors +------- + + 8 Jonas Bernoulli + 1 Dean Kariniemi + 1 Phil Sainty diff --git a/.config/emacs/lisp/magit/docs/RelNotes/2.13.0.txt b/.config/emacs/lisp/magit/docs/RelNotes/2.13.0.txt new file mode 100644 index 0000000..9b93813 --- /dev/null +++ b/.config/emacs/lisp/magit/docs/RelNotes/2.13.0.txt @@ -0,0 +1,122 @@ +Magit v2.13.0 Release Notes +=========================== + +Released 2nd June 2018 by Jonas Bernoulli. + +I am pleased to announce the release of Magit version 2.13.0, +representing 166 commits by 18 contributors over two months. + +Also see https://emacsair.me/2018/06/02/magit-2.13. + +Upcoming breaking changes +------------------------- + +* This is the last release to support Emacs 24.4. Going forward at + least Emacs 25.1 is required. + +* This is the last release to support Git 1.9.4. Going forward at + least Git 2.4 is required. + +* Many functions and variables that have been declared obsolete for + a while now are going to be removed after this release. + +All of these changes will happen on "master", the development branch. +Note that the snapshot packages on Melpa are built from that branch. +If you cannot update Emacs and/or Git now, then you should pin Magit +to Melpa-Stable to stick with this release (and bugfix releases) for +the time being. + +Breaking changes +---------------- + +* As announced earlier, the obsolete option `magit-no-confirm-default' + has been removed. #3232 + +Changes since v2.12.0 +--------------------- + +* Augmenting a file- or blob-visiting buffer with blame information + was completely rewritten, making the implementation more robust and + adding many new features. It is now possible blame in order to get + an answer to the question "what commits remove these lines". It is + no longer necessary for the buffer to be put into `read-only-mode', + when displaying blame information. New visualization styles were + added and users can define their own styles. New commands to visit + blobs related to the current chunk were added. + +* Added new command `magit-tag-release'. This is a fairly opinionated + command and its only use to you might be to serve as a template for + your own variant. + +* Added new section inserter `magit-insert-ignored-files', which + could be added to `magit-status-sections-hook'. + +* The mode `global-magit-file-mode' is now enabled by default, making + the `magit-file-popup' available on "C-c M-g". 0ec28b97 + +* Added new commands `magit-log-trace-definition' and + `magit-diff-trace-definition', which show a log with diffs about the + definition at point. #2588 + +* Added new commands `magit-edit-line-commit' and + `magit-diff-edit-hunk-commit', which allow editing the commit that + added the line at point. febe79ba 22b13337 + +* The interactive prompts for the various reset commands now indicate + the branch which is going to be reset. #3438 + +* Added new option `magit-published-branches', providing an additional + safety-net. If you try to modify a commit that has been pushed to + one of these branches already, then you are now being asked whether + you really want to do that. Do not rely on this exclusively, there + are edge-cases that are ambiguous and are not always handled as you + might have expected. add4a7f3 ff + +* Gravatar images are now being inserted asynchronously. #3452 + +* After deleting the current worktree, `magit-delete-worktree' now + shows the status buffer for another worktree. d9cd4611 + +* Added new command `magit-worktree-checkout-pull-request'. a3d788ec + +* New variable `magit-get-previous-branch-timeout' limits the amount + of time spent in `magit-get-previous-branch'. #3457 + +Fixes since v2.12.0 +------------------- + +* The recently added command `magit-branch-pull-request' had various + issues concerning pull-requests referencing branches from the + upstream repository. #3416 #3417 #3461 + +* The values of diffstat sections was wrong for sections that + represent renamed files. 66d9558f + +* Time zones were not handled correctly when calculating times for + blame headings. #3443 + +This release also contains the fixes described in the v2.12.1 release +notes, as well as other minor improvements, bug fixes, typo fixes, and +documentation fixes. + +Authors +------- + + 138 Jonas Bernoulli + 6 Kyle Meyer + 2 Alban Gruin + 2 Basil L. Contovounesios + 2 Buster Copley + 2 Christophe Junke + 2 Mario Rodas + 2 Phil Sainty + 1 Aaron Madlon-Kay + 1 Ben North + 1 Dean Kariniemi + 1 Eli Barzilay + 1 Jon Vanderwijk + 1 Jonathan Leech-Pepin + 1 Justin Guenther + 1 Li-Yun Chang + 1 Marc Sherry + 1 Noam Postavsky diff --git a/.config/emacs/lisp/magit/docs/RelNotes/2.13.1.txt b/.config/emacs/lisp/magit/docs/RelNotes/2.13.1.txt new file mode 100644 index 0000000..3447dab --- /dev/null +++ b/.config/emacs/lisp/magit/docs/RelNotes/2.13.1.txt @@ -0,0 +1,34 @@ +Magit v2.13.1 Release Notes +=========================== + +Fixes since v2.13.0 +------------------- + +* The prompt used by `magit-rebase-interactive-assert' was wrong. + 37d76f409 + +* `magit-rebase-autosquash' asked for confirmation when the user + already confirmed earlier. 02e6c75b6 + +* `magit-log-wash-rev` errored in ~magit-cherry-mode~, starting with + Emacs 26.1. 1ee577b35 + +* Magit used a completion function to make the built-in completion + respect the collection's order. Even though that wasn't necessary + for Ivy and Helm it did the same here, which became a problem when a + change in Helm caused fuzzy completion to break in combination with + a completion function. Likewise a change in Ivy caused Magit's sort + order to be ignored, which we work around now. #3476, #3477 + +* When using cygwin, then `git-commit-setup-font-lock' could end up + trying to run git in a non-existent directory. #3505 + +* `magit-insert-modules-unpushed-to-pushremote' failed to insert + anything due to a typo in the used commit range. d4e159f35 + +Authors +------- + + 11 Jonas Bernoulli + 8 Kyle Meyer + 5 Noam Postavsky diff --git a/.config/emacs/lisp/magit/docs/RelNotes/2.2.0.txt b/.config/emacs/lisp/magit/docs/RelNotes/2.2.0.txt new file mode 100644 index 0000000..2b77c4a --- /dev/null +++ b/.config/emacs/lisp/magit/docs/RelNotes/2.2.0.txt @@ -0,0 +1,219 @@ +Magit v2.2.0 Release Notes +========================== + +Released 16 August 2015 by Jonas Bernoulli. + +We are pleased to announce the release of Magit version 2.2.0, +representing 321 commits by 19 people over 6 weeks. + +I would like to thank Kyle Meyer and Noam Postavsky for joining +the developer team and helping me with this release. -- Jonas + +Changes since v2.1.0 +-------------------- + +* The Elpa packages `with-editor' and `magit-popup' now depend on the + package `async' and turn on the mode `async-bytecomp-package-mode'. + If available, the mode is turned on even when these packages have + not been installed from an Elpa archive. It is being turned on in + both of these libraries because any one of them might be the first + package from the Magit repository that is being updated. + + It is possible to prevent the mode from being turned on when loading + these libraries by setting `async-bytecomp-allowed-packages' to nil + before loading them. If you do that, then you must mention that you + have done so when reporting a bug (which might therefore be due to + miscompiled files). + + Turning on `async-bytecomp-package-mode' advises `package--compile', + instructing it to compile Magit and its dependencies (as well as + others packages listed in `async-bytecomp-allowed-packages' and + their dependencies) in a separate Emacs instance. + + Unfortunately it is necessary that we do this because when an old + version of a package is already loaded when a new version is being + installed, then the old version sometimes interferes during + compilation of the new version, leading to miscompiled files. + + This usually does not happen very often, but when updating from + Magit v1 to v2 then it is expected, which is why users were + instructed to uninstall the old version before installing v2.1.0. + Unfortunately many users never saw those instructions, so we have + no choice but to use this approach to get rid of miscompiled files. + +* Two new commands have been added to the diff refresh popup that + allow the range of the previous diff to be manipulated. + `magit-diff-flip-revs' swaps the revisions of the range, and + `magit-diff-switch-range-type' toggles between ".." and "..." range + types. + +* The commands `magit-ediff-show-unstaged', `magit-ediff-show-staged', + `magit-ediff-show-commit', and `magit-ediff-show-working-tree' have + been added to the Ediff popup. + +* New option `magit-ediff-dwim-show-on-hunks' controls whether calling + `magit-ediff-dwim' runs a show variant (`magit-ediff-show-unstaged' + or `magit-ediff-show-staged') rather than `magit-ediff-stage' when + point is on an uncommitted hunk. + +* `magit-diff' and `magit-ediff-compare' no longer prompt the user for + confirmation when constructing a range from the last and first + commits selected by a region. A prefix argument can now be used to + specify that the diff is between the second revision and the common + ancestor of both revisions (i.e., the "..." range type is used). + +* `magit-ediff-*' variants now limit file choices to those that have + changed between the revisions of interest. If only one file has + changed, this file is used without prompting. + +* `magit-diff' and `magit-ediff-compare' now consider the location at + point when choosing the default for the prompt, and this default + value usually corresponds with the actions of their DWIM + counterparts. + +* The key in Ediff popup for `magit-ediff-compare' has changed from + "d" to "r" to be consistent with the key in the diff popup for the + similarly behaved `magit-diff`. + +* Entering a single commit for the range to `magit-ediff-compare' now + compares the commit with the working tree (like `magit-diff' and + `git diff') rather than the previous commit. + +* The popup `magit-diff-refresh-popup' and its suffix commands and + helper functions were fixed. Most importantly file arguments and + diff-type arguments are no longer lost when this popup is used - + it only changes those arguments it is supposed to change. Also + the popup only lists the arguments which can actually be used in + the current buffer (in status buffers fewer are supported than in + diff-only buffers). + +* The popup `magit-diff-popup' and its suffix commands now use the + arguments currently in the `magit-diff-mode' buffer of the current + repository. Previously the arguments were always reset to the + default value of `magit-diff-arguments'. + +* The default values of `magit-diff-section-arguments' and + `magit-diff-arguments' now contain the `--no-ext-diff' switch. + +* New popup `magit-log-refresh-popup' allows changing the log + arguments used in the current buffer. This allows changing the + arguments used in a log buffer without having to specify the + reference(s) again. And it makes it possible to change the log + arguments used in the status buffer, which previously required that + option `magit-log-section-arguments' was customized manually. + +* When a log is displayed for the purpose of having the user select + a commit, then this is now displayed in a buffer separate from the + regular log buffer. New option `magit-log-select-buffer-name-format' + controls the name of that buffer and new option + `magit-log-select-arguments' controls the arguments. + +* The default value of `magit-log-section-arguments' now contains the + `--decorate' switch. + +* `magit-log-buffer-file' respects the log arguments currently in + effect in the repositories log buffer, or if that doesn't exist the + default value of `magit-log-arguments'. Because this command is not + invoked from the log popup, it's now also possible to turn on the + `--follow' using a prefix argument. + +* Log graphs are no longer shown in color by default, because turning + the control sequences into faces is very inefficient. To allow + users to get back the colorful graphs, the `--color' switch has been + added to the log popup. + +* In the refs manager, `RET' on a local branch again "visits" that + branch by checking it out (like in v1.4). With a prefix argument it + instead "visits" the branch by showing information about other refs + relative to the visited one (like in v2.1 even without a prefix + argument). + + When the new option `magit-visit-ref-create' is non-nil, then a + remote branch is "visited" by creating a new local branch that + tracks that remote branch, and checking out that local branch. + +* To avoid losing any standard functionality, `C-w' and `M-w' now + fallback to `kill-ring-save' when the region is active. They also + work in more places and in some cases copy more useful information + than before. + +* New option `magit-push-always-verify' has been added because changes + in v2.1 caused many users to accidentally push to `master' instead + of a remote feature branch as intended. All users should set this + option to nil, but only after having read the documentation. The + commands that respect this option instruct users to consult its + documentation. + +* Moving through a log using `n' and `p' is now much faster because + the revision buffer is no longer recreated for each commit along the + way. Because Emacs does not support key-down-events this had to be + implemented using a timer, which has the unfortunate effect that it + leads to a delay even when only pressing one of these keys briefly + to move by a single line. This delay can be adjusted using the new + option `magit-diff-auto-show-delay'. + +* When creating a new branch, first reading the starting point and + only then the name of the new branch has advantages. But many users + disagree, so the option `magit-branch-read-upstream-first' has been + added. It defaults to t. + +* New commands `magit-wip-log' and `magit-wip-log-current' allow + showing log for a branch and its wip refs (which the various wip + modes commit to). + +* New command `magit-submodule-deinit'. + +* New command `magit-commit-augment' allows the user to pick a commit + to squash into and edit the squash commit message. + +* New push commands `magit-push-implicitly' and `magit-push-quickly'. + +* When reading user input, many commands now offer a better default + choice and better completion candidates. + +* All apply variants now use `--3way' when called with a prefix + argument. + +* Log commands now respect the entries in the .mailmap file. + +* The command `magit-pull-current' now also fetches tags by default. + +* When a file has conflicts then the type of conflict is shown now. + +* New option `magit-log-show-refname-after-summary'. + +* New section inserter `magit-insert-user-header'. + +* New face `magit-section-secondary-heading'. + +* New commands `magit-run-gitk-all' and `magit-run-gitk-branches'. + The existing command `magit-run-gitk' now always calls `gitk' + without any arguments. + +* New commands `magit-shell-command' and `magit-shell-command-topdir'. + +This release also contains various documentation fixes, code +clean-ups, bug fixes, and other small to medium improvements. + +Authors +------- + + 225 Jonas Bernoulli + 67 Kyle Meyer + 8 Noam Postavsky + 3 Mitchel Humpherys + 2 Greg Lucas + 2 Mark Karpov + 2 Yuichi Higashi + 1 Johann Klähn + 1 Josiah Schwab + 1 Kan-Ru Chen + 1 Nicklas Lindgren + 1 Phil Sainty + 1 Richard Kim + 1 Robin Green + 1 Rémi Vanicat + 1 Steven Vancoillie + 1 Thomas Frössman + 1 Ting-Yu Lin + 1 Vineet Naik diff --git a/.config/emacs/lisp/magit/docs/RelNotes/2.2.1.txt b/.config/emacs/lisp/magit/docs/RelNotes/2.2.1.txt new file mode 100644 index 0000000..11771bf --- /dev/null +++ b/.config/emacs/lisp/magit/docs/RelNotes/2.2.1.txt @@ -0,0 +1,45 @@ +Magit v2.2.1 Release Notes +========================== + +Released 24 August 2015 by Jonas Bernoulli. + +This is a bugfix release. + +* The version strings in the manual were not set to "2.2" when v2.2.0 + was released. + +* Some menu bindings were not adjusted when commands were renamed. + +* The "next" tag was never shown in the "Tag(s)" header of the status + buffer. + +* Blaming did not abort gracefully when the user killed the buffer. + +* Blaming failed on indirect buffers. + +* Blaming did not detect when a file was untracked. + +* Blaming passed the wrong line range when the file's buffer was + narrowed. + +* `magit-shell-command-topdir' used `magit-git-command' instead of + `magit-shell-command'. + +* `magit-copy-as-kill' added "nil" to the `kill-ring' when there was + nothing useful to put there. + +* `magit-find-file-hook', `magit-find-index-hook', + `magit-refresh-popup-buffer-hook' were used without being defined + using `defvar'. + +* `magit-format-ref-labels' failed to work around a Git bug, resulting + in refnames not being colorized when `--simplify-by-decoration' is + used. + +This release also contains various documentation fixes. + +Authors +------- + + 16 Jonas Bernoulli + 11 Kyle Meyer diff --git a/.config/emacs/lisp/magit/docs/RelNotes/2.2.2.txt b/.config/emacs/lisp/magit/docs/RelNotes/2.2.2.txt new file mode 100644 index 0000000..1d5ec52 --- /dev/null +++ b/.config/emacs/lisp/magit/docs/RelNotes/2.2.2.txt @@ -0,0 +1,45 @@ +Magit v2.2.2 Release Notes +========================== + +Released 3 September 2015 by Jonas Bernoulli. + +This is a bugfix release. + +* `magit-diff-wash-diff' choked on unmerged binary files. #2211 + +* `magit-blame-popup' did not allow empty input when reading a value + for "-C" or "-M". #2208 + +* The `emacsclient' executables belonging to non-current alternative + installations of Emacs on Debian were not considered when setting + the default value of `with-editor-emacsclient-executable'. #2217 + +* `server-edit', which switches to a buffer preferably one with + another client, was used when finishing or aborting a `with-editor' + session. When `emacsclient' was used to connect to a server and + then a commit or rebase was invoked, then there would be another + client and switching to its buffer after finishing the commit or + rebase would be undesirable. Now we use `server-done' instead. + #2197 + +* When `--stat' abbreviates the name of a file, then that name was + stored in the section object instead of the full name. #2199 + +* `magit-file-relative-name' with non-nil TRACKED failed in Tramp + repositories. #2206 + +* After failing to clone, `magit-clone' also tried to show the status + of the non-existent clone. #2203 + +* `magit-wip-log' did not display a log if the working tree or index + ref did not exist. + +This release also contains various documentation fixes and code +clean-ups. + +Authors +------- + + 29 Jonas Bernoulli + 5 Kyle Meyer + 1 Barak A. Pearlmutter diff --git a/.config/emacs/lisp/magit/docs/RelNotes/2.3.0.txt b/.config/emacs/lisp/magit/docs/RelNotes/2.3.0.txt new file mode 100644 index 0000000..ae09967 --- /dev/null +++ b/.config/emacs/lisp/magit/docs/RelNotes/2.3.0.txt @@ -0,0 +1,251 @@ +Magit v2.3.0 Release Notes +========================== + +Released 28 October 2015 by Jonas Bernoulli. + +We are pleased to announce the release of Magit version 2.3.0, +representing 367 commits by 12 people over 10 weeks. + +Changes since v2.2.0 +-------------------- + +* Added `--interactive' switch to `magit-rebase-popup' so that rebase + variants which normally perform a non-interactive rebase can be used + to perform an interactive rebase too. #2186 + +* Commands that perform an interactive rebase should no longer be used + non-interactively (i.e., they should only be used as commands). #2187 + +* Rebasing commands now can start with a root commit. Root commits + are detected automatically, so users don't have to use the `--root' + switch explicitly. #2187 + +* Added new command `magit-checkout-file'. + +* Added new option `magit-bury-buffer-function' to give users more + control over how Magit buffers are buried, replacing the old binary + option `magit-restore-window-configuration'. The default is still + the same, i.e., `magit-restore-window-configuration' is used. #2193 + +* Added new function `magit-mode-quit-window' as a simpler variant to + `magit-restore-window-configuration'. #2193 + +* Information about related refs in `magit-revision-mode' buffers are + now grouped in the same section as other headers and are formatted + like those other headers instead of like diffstats. The redundant + header which previously grouped the related refs section is gone. + All headers are inserted by the new `magit-insert-revision-headers' + section inserter. #2216 + +* No longer avoid calling git more than absolutely necessary when + creating a `magit-revision-mode' buffer. This simplifies parsing, + makes it simpler to prettify how information is presented, allows + users to customize how and in what order information is presented, + and prepares for faster, asynchronously created diffs. #2216 + +* The various sections in revision buffers are now inserted using new + section inserters named `magit-insert-revision-{*}', all of which + are part of the default value of `magit-revision-sections-hook'. + #2216 + +* The various sections in diff buffers are now inserted using new + section inserters named `magit-insert-diff-{*}', all of which are + part of the default value of `magit-diff-sections-hook'. #2216 + +* Added new option `magit-revision-headers-format' whose value is + passed to `git show --format=' to insert most of the headers, + excluding the related-refs headers. The default value now uses + placeholders which respect information in the file ".mailmap". + #2216 + +* Removed options `magit-revision-show-notes', + `magit-diff-show-xref-buttons', `magit-revision-show-xref-buttons', + `magit-diff-show-diffstat', and `magit-revision-show-diffstat'. + Whether these sections are inserted is now controlled using the + hooks `magit-diff-section-hook' and `magit-revision-section-hook'. + #2216 + +* Gravatar images can now be shown in `magit-revision-buffers'. New + option `magit-revision-show-gravatars' controls whether these images + should be inserted and can also be used to adjust to customizations + of `magit-revision-headers-format'. + + This feature is not enabled by default due to privacy concerns. + + Gravatar images are spliced into two halves which are then displayed + on separate lines. On OS X the splicing has a bug in some Emacs + builds, which causes the top and bottom halves to be interchanged. + Setting the new option `magit-revision-use-gravatar-kludge' to `t' + works around this issue. #2216 + +* After using the region to stage or discard parts of a hunk, point is + now placed on the beginning of the next or previous block of changed + lines. Previously we just jumped to the beginning of the hunk at + the same index as the previous hunk, but that often was very far + away from where point was before the refresh. #2227 + +* The function `magit-toplevel' was refactored and many tests were + added. It now returns the correct value when a symlink to a + sub-directory of a working tree is involved. #2242 + +* New option `magit-keep-region-overlay' allows displaying the region + overlay together with the visualization of a valid Magit selection. + See the doc-string for why we think you shouldn't do that, but if + you disagree then you can now have it your way. #2091 + +* Avoid the inefficiency of `git log --graph --max-count=N REV' (it + calculates the graph for all reachable commits, not just the N + commits), by additionally limiting the history using a range + calculated from REV and N, when possible. #2243 + +* Renamed `magit-file-buffer-mode' to `magit-file-mode'. Related + symbols were renamed accordingly. + +* Added new minor mode `magit-blob-mode' and new commands + `magit-blob-previous' and `magit-blob-next'. #2195 + +* Added new commands `magit-branch-spinoff' and `magit-branch-reset'. + #2191 + +* Added new option `magit-status-expand-stashes'. + +* In addition to `default-directory' also set `list-buffers-directory' + to the top-level of the working tree in Magit buffers, causing that + directory to be displayed in the "File" column of the *Buffer List* + buffer. + +* Added a kludge to keep Cygwin and MYSYS2 executables from expanding + globs when called from a native Windows Emacs executable. #2281 + +* Added a revision stack. The new commands `magit-copy-section-value' + and `magit-copy-buffer-revision', which are intended for use inside + Magit buffers, push an entry to the stack, and the new command + `magit-pop-revision-stack' inserts a representation into an editable + buffer. New option `magit-pop-revision-stack-format' controls how + the representation of the revision is formatted. The old commands + `magit-copy-as-kill' and `magit-copy-buffer-thing-as-kill' have been + removed. #2225 + +* The default values of options `magit-commit-extend-override-date' + and `magit-commit-extend-override-date' changed to `t'. + +* Added new option `magit-log-show-margin'. + +* Added new option `magit-log-remove-graph-args'. #2226 + +* Added support for showing actionable diffs inside logs. #2226 + +* Added basic support for tracing the evolution of a region. #2226 + +* Added new command `magit-stash-format-patch'. + +* All apply variants learned how to apply multiple hunks at once. #2271 + +* Regular apply learned how to apply multiple files at once. #2271 + +* `git-commit-setup' learned to handle Cygwin paths. It had to be + taught about that separately from the rest of Magit, because, for + historic reasons, we try to keep the `git-commit' package usable + without Magit. + +* The signatures of `magit-mode-setup' and `magit-mode-get-buffer' + have changed, and `magit-mode-get-buffer-create' has been removed. + Extensions have to be adjusted accordingly. #2282. + +* All Magit-Mode buffers (including process buffers, but excluding + popup, blob-visiting, and file-visiting buffers, whose major-modes + do not derive from `magit-mode' and therefore aren't "Magit-Mode + buffers") are now displayed using `magit-display-buffer', which is a + wrapper around the low-level `display-buffer'. High-level functions + such as `pop-to-buffer' and `switch-to-buffer' are no longer used to + display Magit buffers. + + `magit-display-buffer' uses the function specified by the new option + `magit-display-buffer-function' to actually display the buffer in + some window. The default value is `magit-display-buffer-traditional'. + By implementing their own variant to wrap around `display-buffer', + users can take complete control over how Magit buffers are displayed. + It's also possible to use `display-buffer' directly and specify the + display actions in `display-buffer-alist'. + + Added new options `magit-pre-display-buffer-hook' and + `magit-post-display-buffer-hook', and removed the options + `magit-status-buffer-switch-function' and + `magit-diff-switch-buffer-function'. #2282 + +* Added new options `magit-generate-buffer-name-function', + `magit-buffer-name-format', and `magit-uniquify-buffer-names', + replacing the various `magit-{*}-buffer-name-format' options. #2282 + +* Added new command `magit-toggle-buffer-lock'. Previously it was + possible to prevent Magit from reusing an existing buffer to display + something else, using the command `magit-rename-buffer' (which was + removed). Now this is done by locking the buffer to its value. + #2282 + +* The status buffer is now always refreshed after running a Magit + command triggers a refresh. Previously that was only the case if + the buffer in which the command was invoked was a Magit buffer too. + +* Added optional support for refreshing the status buffer every time a + buffer visiting a file, which is tracked in the current repository, + is saved. To enable this add `magit-after-save-refresh-buffers' to + `after-save-hook'. + +* Added new functions `magit-log-maybe-update-revision-buffer', + `magit-log-maybe-update-blob-buffer', + `magit-status-maybe-update-revision-buffer', and + `magit-status-maybe-update-blob-buffer', and added some of them to + `magit-section-movement-hook'. Removed the function + `magit-log-maybe-show-commit', which served about the same purpose + as these new functions. Previously one had to customize the option + `magit-diff-auto-show' to control when the other buffer was updated, + now one does so by adding or removing the above functions to or from + `magit-section-movement-hook'. The other window is only ever + updated now, to initially create it, use `SPC'. #2338 + +* Added new hook `magit-process-find-password-functions', with no + default members. These functions, if any, are run when git requests + a password from the user, if there are no such functions, or if they + fail, then the user has to type the password as before. Added new + function `magit-process-password-auth-source'. It can be added to + that hook and uses `auth-source' to get the password from one of the + sources it supports. #2311 + +* Removed broken support for unicode log graphs. + +* `magit-expand-git-file-name' learned to use the output of `mount' to + map Cygwin paths into native Windows paths. `git-commit-setup' now + uses `magit-expand-git-file-name' if available. #2348 + +* Added new function `magit-define-popup-sequence-action' and taught + related functions about `:sequence-actions'. + +* Added new hook `magit-credential-hook' and added new hook function + `magit-maybe-start-credential-cache-daemon' to it. This allows + starting Git's credential daemon separately, which is necessary + because Emacs sends SIGHUP and closes the pty when e.g `git push' + (which started the daemon) finishes. Upon receiving that signal + the daemon terminates. We work around this by starting the daemon + directly before invoking the git subcommand which might need + credentials. #2360 + +This release also contains the changes described in the v2.2.1 and +v2.2.2 release notes, as well as various other documentation fixes, +code clean-ups, bug fixes, and other small to medium improvements. + +Authors +------- + + 305 Jonas Bernoulli + 38 Kyle Meyer + 15 Noam Postavsky + 1 Andriy Kmit' + 1 Barak A. Pearlmutter + 1 Brian Warner + 1 Damien Cassou + 1 John Mastro + 1 Nicolas Petton + 1 Nikolay Martynov + 1 Peter Jaros + 1 Phil Sainty diff --git a/.config/emacs/lisp/magit/docs/RelNotes/2.3.1.txt b/.config/emacs/lisp/magit/docs/RelNotes/2.3.1.txt new file mode 100644 index 0000000..b1d1291 --- /dev/null +++ b/.config/emacs/lisp/magit/docs/RelNotes/2.3.1.txt @@ -0,0 +1,31 @@ +Magit v2.3.1 Release Notes +========================== + +Released 11 November 2015 by Jonas Bernoulli. + +This is a bugfix release. + +* `magit-stash-drop' now shows a message with the hash of the dropped + stash to make it easier to recover from dropping the wrong stash. + +* `magit-revert-buffers' now avoids needlessly connecting to unrelated + hosts. It first checks whether a given file is on the same host as + the repository, and only if that is so it checks whether the file is + located inside the repository, using `file-in-directory-p', which, + for Tramp files, requires connecting to the remote host. + +* `magit-commit-message-buffer' no longer hangs when a symlink to the + repository is involved. + +This release also contains various documentation fixes and code +clean-ups. + +Authors +------- + + 10 Jonas Bernoulli + 3 Noam Postavsky + 2 Kyle Meyer + 1 Carl Lieberman + 1 David L. Rager + 1 Syohei Yoshida diff --git a/.config/emacs/lisp/magit/docs/RelNotes/2.4.0.txt b/.config/emacs/lisp/magit/docs/RelNotes/2.4.0.txt new file mode 100644 index 0000000..bedd075 --- /dev/null +++ b/.config/emacs/lisp/magit/docs/RelNotes/2.4.0.txt @@ -0,0 +1,147 @@ +Magit v2.4.0 Release Notes +========================== + +Released 18 January 2016 by Jonas Bernoulli. + +We are pleased to announce the release of Magit version 2.4.0, +representing 269 commits by 14 people over 12 weeks. + +Also see http://emacsair.me/2016/01/18/magit-2.4. + +Changes since v2.3.0 +-------------------- + +* The new mode `magit-auto-revert-mode', a magit-specific globalized + variant of `auto-revert-mode', replaces the old implementation, which + was configured using the option `magit-revert-buffers'. The new mode + is enabled for all users by default. It may be disabled before + loading magit by setting `magit-auto-revert-mode' (or the obsolete + alias `magit-revert-buffers') to nil. To disable the mode after + loading magit, a call to (magit-auto-revert-mode -1) is required. + #2474 + +* The option `magit-refresh-status-buffer' was added, allowing users + to prevent automatic refreshes of the status buffer for performance + reasons. + +* All of Git's push-related variables are now honored. #2414 + +* In addition to the upstream branch, the push-remote (configured + using `branch..pushRemote' or `remote.pushDefault') is now + also fully supported. #2414 + +* The status buffer now features up to four logs listing unpulled and + unpushed commits. Two for the upstream and two for the push-remote. + #2414 + +* The branch popup now shows the most important Git variables that are + in some way related to branches. The values of these variables can + now be conveniently changed from that popup. #2414 + +* The fetch, pull, push, and rebase popups now feature an action which + acts on the push-remote, another which acts on the upstream, and yet + another which acts on any other source or target. For each of these + actions the respective branch is shown in the popup. + + The actions in the push popup are displayed even if the respective + variables are unset - they then offer to set these variables before + pushing. Setting `magit-push-current-set-remote-if-missing' to nil + disables this. + + Many key bindings were changed for consistency and safety reasons. + Likewise many commands were renamed and their behavior was adjusted. + Some new commands, related to the push-remote, were added. #2414 + +* The command `magit-push-implicitly' was removed from the push popup. + The command's doc-string explains how to put it back. If these + instructions are followed, then the popup shows what will happen if + the command is used. #2453 + +* The command `magit-push-to-remote' was added. The command's + doc-string explains how to add it to the push popup. #2453 + +* The option `magit-push-always-verify' was removed. That was only a + temporary kludge to keep users from shooting themselves in the foot. + This is no longer necessary because one now always sees where one is + about to push to. #2414 + +* The popup command `magit-pull-and-fetch-popup' was added as a + possible replacement for the separate `magit-push-popup' and + `magit-fetch-popup'. #2452 + +* The option `magit-branch-prefer-remote-upstream' was added for users + who prefer to always use remote branches as upstreams. #2447 + +* The options `magit-clone-set-remote.pushDefault' and + `magit-remote-add-set-remote.pushDefault' were added. #2447 + +* When Git is run for side-effects and exits with a non-zero status, + then the respective error message is now inserted into the status + buffer. This should help those users who do not see that message + when it is being displayed in the echo area. + +* Popups gained support for a new event type `:variable', which can be + used to change the value of Git variables. This can only be used in + combination with Magit (just `magit-popup.el' by itself is not + sufficient). #2409 + +* The backward-compatibility kludge `magit-branch-manager' has been + removed. The one and only binding to show the refs buffer now is + "y"; the "b v" binding has been removed. + +* The command `with-editor-finish' now runs the new hook + `with-editor-post-finish-hook'. + +* The command `magit-diff-visit-file' now runs the new hook + `magit-diff-visit-file-hook'. + +* When the upstream branch or push remote is configured but the + respective branch does not actually exist, then that is now reported + in the header of the status buffer. #2390 + +* The header line about the upstream branch in the status buffer is + now prefixed with either "Merge" or "Rebase", depending on the value + of `branch..rebase'. #2390 + +* `magit-define-popup' learned two new arguments, `:setup-function' and + `:refresh-function'. These arguments should be used instead of the + MODE argument, which is now deprecated. #2389 + +* Negative text properties are no longer faked; that was just too ugly + and inefficient. Since v2.1.0 Magit no longer sets the background + color for any faces except for those related to diffs. Third-party + themes which still set the background color of non-diff faces have + to be adjusted, because the background color of these faces would be + shadowed by the highlighting of the current section. This does not + apply to diff-related faces because diff sections are highlighted + differently from other sections. #2387 + +* The commands `git-rebase-move-line-up' and `git-rebase-move-line-down' + have been extended. When a region is active, they now operate on + all lines touched by the region, not just the current line. In + addition, a numeric prefix can now be given to specify how many + lines the current line or selection is moved across. + +* The option `magit-popup-display-action' was added. + +This release also contains the changes described in the v2.3.1 release +notes, as well as various other documentation fixes, code clean-ups, +bug fixes, and other small to medium improvements. + +Authors +------- + + 226 Jonas Bernoulli + 22 Kyle Meyer + 10 Noam Postavsky + 1 Carl Lieberman + 1 Damien Cassou + 1 David L. Rager + 1 John Mastro + 1 Lele Gaifax + 1 Michael Heerdegen + 1 Miloš Mošić + 1 Raimon Grau + 1 Sylvain Rousseau + 1 Syohei Yoshida + 1 Zach Latta diff --git a/.config/emacs/lisp/magit/docs/RelNotes/2.4.1.txt b/.config/emacs/lisp/magit/docs/RelNotes/2.4.1.txt new file mode 100644 index 0000000..872a6df --- /dev/null +++ b/.config/emacs/lisp/magit/docs/RelNotes/2.4.1.txt @@ -0,0 +1,31 @@ +Magit v2.4.1 Release Notes +========================== + +Updates since v2.4.0 +-------------------- + +* Added new utility functions `magit-rev-abbrev', `magit-ref-p', and + `magit-tag-p'. + +Fixes since v2.4.0 +------------------ + +* When determining the emacsclient executable most suitable for the + current emacs instance, With-Editor ignored any executable that is + actually named "emacsclient-snapshot". + +* When determining the most suitable git executable, an error occurred + if "Git for Windows 1.x" is used and an cygpath executable is + available. + +* An error occurred when refreshing the status buffer when there is a + new, staged but not yet committed, submodule. + +This release also contains typofixes. + +Authors +------- + + 9 Jonas Bernoulli + 4 Kyle Meyer + 1 Noam Postavsky diff --git a/.config/emacs/lisp/magit/docs/RelNotes/2.5.0.txt b/.config/emacs/lisp/magit/docs/RelNotes/2.5.0.txt new file mode 100644 index 0000000..cce9fed --- /dev/null +++ b/.config/emacs/lisp/magit/docs/RelNotes/2.5.0.txt @@ -0,0 +1,122 @@ +Magit v2.5.0 Release Notes +========================== + +Released 30 January 2016 by Jonas Bernoulli. + +We are pleased to announce the release of Magit version 2.5.0, +representing 78 commits by 4 contributors over 2 weeks. + +Also see http://emacsair.me/2016/02/10/magit-2.5. + +Changes since v2.4.0 +-------------------- + +* The library `with-editor.el' reincarnated as a separate repository. + + It was already available as a separate package, and since it can be + of use for packages that have absolutely nothing to do with `magit' + it makes sense to maintain it separately. That wasn't done before + because that would have made it harder to change it and its users + within the magit repository in parallel. I expect there will be + few such changes in the future. + +* Added new library `magit-submodule.el'. It contains code that was + previously spread across various libraries. + +* Added new option `auto-revert-buffer-list-filter' and redefined + `auto-revert-buffers' from `autorevert.el' to use it. Added new + predicates `magit-auto-revert-buffer-p' and the more restrictive + `magit-auto-revert-repository-buffer-p', which are both intended + to be used as potential value of the option. + + For now the option defaults to `nil', but that might change in a + future release. When Magit explicitly calls `auto-revert-buffers' + (as opposed to when that is called due to a file notification event + or by a timer), and `auto-revert-buffer-list-filter' is `nil', then + it is let-bound to `magit-auto-revert-repository-buffer-p'. + + Users who use Tramp and experience delays, should consider setting + the option to `magit-auto-revert-repository-buffer-p'. + +* By default, invoking `magit-unstage' on a committed change now + performs an action which is somewhat similar to unstaging. The + change is reverted in the index, but not the working tree. This + allows extracting changes from HEAD. + + Setting the new option `magit-unstage-committed' to nil, disables + this behavior. Attempting to unstage a committed change would then + result in an error again. + +* Because file notifications may arrive with a delay, the option + `magit-auto-revert-immediately' now defaults to `t' even when file + notifications can be used, + +* Like `magit-refresh' already did, `magit-refresh-all' now runs the + hooks `magit-pre-refresh-hook' and `magit-post-refresh-hook'. + +* The heading of the section which lists commits that exist in the + current branch but not in its upstream was changed from "Unpushed + to " to "Unmerged into ", because one usually + should merge into that branch instead of pushing to it. + +* Added new commands `magit-remote-set-head' and + `magit-remote-unset-head'. + +* By default `magit-clone' now deletes the symbolic-ref "origin/HEAD" + right after running `git clone', which insists on creating it. + + The new option `magit-clone-set-remote-head' can be set to `t' to + go back to keeping that symbolic-ref. We default to removing it, + because it does not actually get automatically updated when the + HEAD of the remote changes, which makes it rather pointless. + +* Added new option `magit-prefer-remote-upstream' which controls + whether commands which read the upstream or starting-point from + the user would rather offer a local or a remote branch as default + completion candidate. + +* Added the switch `--cover-letter' to `magit-patch-popup', and taught + `magit-format-patch' to immediately open the letter in a buffer. + +* Added new option `++order' to the various log popups. This option + and its value are converted to `--VALUE-order' before calling `git'. + This option was added instead of the switches `--author-date-order', + `--date-order', and `--topo-order' because adding all three would be + too noisy and because they are mutually exclusive. + +Fixes since v2.4.1 +------------------ + +* Creating a stash in a secondary working tree failed if no other + stash already existed in the repository. + +* Creating a Magit buffer failed if `uniquify-buffer-name-style's + value is `nil'. + +* Resetting a branch to an arbitrary commit caused its upstream + configuration to be mangled. + +* Resetting a branch to another branch caused the former to be + configured as the upstream of the latter. That behavior was + introduced by accident when the argument `--track' was replaced with + the variable `branch.autoSetupMerge' in the popup. Because it would + be undesirable to restore the `--track' argument in the popup, one + now has to use a prefix argument to set the upstream while resetting. + +* The manually set state of the margin in log and reflog buffers was + not preserved and instead reset to the default state when a command + was invoked which changes what log/reflog is being displayed. + +* Pressing RET on a variable in a popup caused an error. + +This release also contains the fixes described in the v2.4.1 release +notes, as well as various typofixes, documentation updates, code +clean-ups, bug fixes, and other small improvements. + +Authors +------- + + 62 Jonas Bernoulli + 9 Kyle Meyer + 4 Noam Postavsky + 3 Alex Dunn diff --git a/.config/emacs/lisp/magit/docs/RelNotes/2.6.0.txt b/.config/emacs/lisp/magit/docs/RelNotes/2.6.0.txt new file mode 100644 index 0000000..c58fdc2 --- /dev/null +++ b/.config/emacs/lisp/magit/docs/RelNotes/2.6.0.txt @@ -0,0 +1,134 @@ +Magit v2.6.0 Release Notes +========================== + +Released 29 March 2016 by Jonas Bernoulli. + +We are pleased to announce the release of Magit version 2.6.0, +representing 77 commits by 7 contributors over 2 months. + +Also see http://emacsair.me/2016/03/29/magit-2.6. + +Updates since v2.5.0 +-------------------- + +* Added a cache, which memorizes the values of some function calls for + the duration of a refresh. This cuts the calls to git in half. + +* Added new option `magit-diff-hide-trailing-cr-characters'. When its + value is non-nil (the default on Windows), then ^M characters at the + end of diff lines are hidden. + +* Added new command `magit-diff-buffer-file-popup' intended for use in + file-visiting buffers. It shows the same popup as `magit-diff-popup' + but starts out already limited to the visited file. + +* Added new command `magit-ediff-show-stash', which is available in + the Ediff popup and will be used when `magit-ediff-dwim' is called + with point on a stash. + +* Added new command `magit-reset-popup' featuring all the available + reset variants. + +* Added new command `magit-push-refspecs', which allows pushing using + one or more comma-separated and refspecs, which are explicitly typed + in the minibuffer. + +* Added new commands `magit-fetch-refspec' and `magit-fetch-branch'. + +* Added new section inserters + `magit-insert-modules-unpulled-from-pushremote' and + `magit-insert-modules-unpushed-to-pushremote', and renamed + `magit-insert-unpulled-module-commits' to + `magit-insert-modules-unpulled-from-upstream' and + `magit-insert-unpushed-module-commits' to + `magit-insert-modules-unpushed-to-upstream'. + +* The command `magit-submodule-add' now allows using a module name + different from the path of the module. + +* If `magit-push-current-set-remote-if-missing's value is `default', + then the command `magit-push-current-to-pushremote' now offers to + set `remote.pushDefault' unless the push-remote is already set in + some way. Previously this command offered to set the local value + `branch.NAME.pushRemote' for all non-nil values of the option. + +* When washing the diff that is to be displayed while writing a + commit message takes too long, then it is now possible to abort that + by pressing `C-g'. Previously that would have aborted the commit. + +* When `magit-process-raise-error' is non-nil, then the displayed + error message now also mentions the `default-directory', which is + useful when using Magit as a library in another packages that runs + git in many different repositories. + +* The `magit-insert-section' macro's TYPE argument can now have the + form `(eval FORM)' instead of a symbol. An atomic TYPE is never + evaluated, but FORM is evaluated at run-time. + +Fixes since v2.5.0 +------------------ + +* Staging hunks/regions belonging to files with CRLF line endings on + Windows (or, to be precise, when `default-process-coding-system' had + CRLF end-of-line conversion) ended up erroneously staging changes + with LF line endings. Magit now ensures line endings are preserved + by enforcing a `process-coding-system' with LF end-of-line + conversion. The new behavior may be disabled by setting the option + `magit-process-ensure-unix-line-ending' to `nil'. + +* If the user sets the variable `magit-auto-revert-mode' or the + obsolete alias `magit-revert-buffers' to nil anytime during startup + (before or after `magit-autorevert' is loaded) then the mode is now + no longer turned on (actually it is explicitly turned off). + +* When a revision buffer was limited to a set of files, its header + line did not say so. + +* The function `magit-run-git-with-input' had stopped calling + `magit-pre-call-git-hook' and logging its git command to the + magit-process buffer. + +* The function `magit-diff-wash-submodule did not handle some less + common cases. + +* The command `magit-section-cycle-diffs' hung when hiding sections. + +* Invoking `magit-commit-popup's default action by invoking the popup + command with a prefix argument failed due to a typo. + +* The command `magit-toggle-buffer-lock' failed if another buffer is + already locked to the same value. + +* The command `magit-clone' did not switch to the cloned repository + before trying to delete the symbolic-ref "origin/HEAD". + +* The commands `magit-insert-unpulled-from-pushremote' and + `magit-insert-unpushed-to-pushremote' missed an edge case when + checking whether their section should be inserted into the status + buffer. + +* The command `magit-merge-preview' did not recognize sections for + added or deleted files. + +* The command `magit-show-stash' did not properly handle untracked + files that were within subdirectories. + +* On `windows-nt' systems, having `mount' in `exec-path' caused Magit + to assume that git is from Cygwin. + +* Added a kludge to work around a bug in Apple's OS X which causes + `file-accessible-directory-p' to return incorrect results. + +This release also contains typofixes, documentation updates, and code +clean-ups. + +Authors +------- + + 53 Jonas Bernoulli + 13 Kyle Meyer + 4 Luís Oliveira + 4 Noam Postavsky + 1 Dan Erikson + 1 Dato Simó + 1 Russell Black diff --git a/.config/emacs/lisp/magit/docs/RelNotes/2.6.1.txt b/.config/emacs/lisp/magit/docs/RelNotes/2.6.1.txt new file mode 100644 index 0000000..075f1c0 --- /dev/null +++ b/.config/emacs/lisp/magit/docs/RelNotes/2.6.1.txt @@ -0,0 +1,40 @@ +Magit v2.6.1 Release Notes +========================== + +Fixes since v2.6.0 +------------------ + +* When a submodule is manually removed without staging the removal, + then the status buffer could no longer be updated. + +* In some cases not all modified submodules were shown in the status + buffer. + +* Visiting a blob did turn on `diff-hl-mode' if the global mode is on. + +* Stash and wipref were needlessly signed if signing is enabled. + +* The command `git-commit-save-message' did not strip diffs produced + by `git commit --verbose'. + +* Diffs produced by `git commit --verbose' were not completely + highlighted in the commit message buffer. + +* When the commit message buffer contains nothing but a single line + that does not end with a newline, then a warning was shown about + there being a non-empty second line. + +* When installing from Melpa, `async-bytecomp-package-mode' was no + longer activated early enough. + +This release also contains documentation updates, typofixes, fixes for +minor bugs, and other small improvements. + +Authors +------- + + 14 Jonas Bernoulli + 5 Kyle Meyer + 1 Fritz Grabo + 1 Ingo Lohmar + 1 Noam Postavsky diff --git a/.config/emacs/lisp/magit/docs/RelNotes/2.6.2.txt b/.config/emacs/lisp/magit/docs/RelNotes/2.6.2.txt new file mode 100644 index 0000000..9433128 --- /dev/null +++ b/.config/emacs/lisp/magit/docs/RelNotes/2.6.2.txt @@ -0,0 +1,52 @@ +Magit v2.6.2 Release Notes +========================== + +Changes since v2.6.1 +-------------------- + +* Added new section inserter `magit-insert-submodules'. For each + submodule it inserts the module path and a description of its tip. + +* When re-adding an already configured but for some reason unstaged + submodule, then `magit-submodule-add' now offers the configured + submodule name as default choice. + +Fixes since v2.6.1 +------------------ + +* When possible `git merge (--no-commit|--edit)' perform fast-forward + merges, which isn't what one would expect. `magit-merge-nocommit' + and `magit-merge-editmsg' now work around that by always using + `--no-ff'. + +* The command `magit-log', when called with `--patch' but without + `--graph', deleted the first two characters of file names in the + diff. + +* When performing an instant fixup/squash, the rebase often failed + because the commit process still held the lock on `index.lock'. + +* The command `magit-submodule-add' offered an invalid default choice + for the module path and allowed selecting a file that isn't a + repository. + +* `git-rebase-mode' failed to prevent `save-place-mode' from having an + effect. + +* The section inserter `magit-insert-unpulled-from-upstream-or-recent' + failed to insert the recent commits instead when no upstream is + configured. + +* Two key bindings in `magit-pull-and-fetch-popup' conflicted. + +* The default value for `magit-cygwin-mount-points' checked if + "git.exe" was a cygwin flavor of git, instead of the (possibly user + customized) value of `magit-git-executable'. + +Authors +------- + + 21 Jonas Bernoulli + 1 John Mastro + 1 Kyle Meyer + 1 Noam Postavsky diff --git a/.config/emacs/lisp/magit/docs/RelNotes/2.7.0.txt b/.config/emacs/lisp/magit/docs/RelNotes/2.7.0.txt new file mode 100644 index 0000000..74c6ce9 --- /dev/null +++ b/.config/emacs/lisp/magit/docs/RelNotes/2.7.0.txt @@ -0,0 +1,81 @@ +Magit v2.7.0 Release Notes +========================== + +Released 19 May 2016 by Jonas Bernoulli. + +We are pleased to announce the release of Magit version 2.7.0, +representing 116 commits by 7 people over 7 weeks. + +Also see http://emacsair.me/2016/05/19/magit-2.7. + +Changes since v2.6.0 +-------------------- + +* Added new popup `magit-subtree-popup' and bound "O" to it. + +* Added new popup `magit-branch-config-popup' and made it available + from the popups `magit-branch-popup', `magit-pull-and-fetch-popup', + `magit-pull-popup', `magit-fetch-popup', and `magit-push-popup'. + + With a prefix argument it reads a branch to be configured in the + minibuffer instead of using the current branch. + +* Added new option `magit-branch-popup-show-variables', defaulting to + t to avoid changing key bindings. When set to nil, no variables are + displayed directly in the `magit-branch-popup', instead the subpopup + `magit-branch-config-popup' has to be used. + +* Added new popup command `magit-log-buffer-file-popup'. + +* Added new command `magit-diff-buffer-file' and new option + `magit-diff-buffer-file-locked'. When the value of the option is + non-nil, the default, then the command uses a dedicated buffer. + +* Added new option `magit-log-buffer-file-locked'. When its value is + non-nil, the default, then `magit-log-buffer-file' uses a dedicated + buffer. + +* Added new commands `magit-worktree-checkout', + `magit-worktree-branch', `magit-worktree-delete', + and `magit-worktree-status'. + +* Added new section inserter `magit-insert-worktrees' + +* The command `magit-clone' now runs asynchronously, which avoids + blocking Emacs and allows handling password prompts. + +* The command `magit-stage' learned to stage an untracked file while + leaving its content unstaged (i.e., `git add --intent-to-add') when + called with a prefix argument. + +* The command `magit-reverse' learned to use `--reject' to ensure that + non-conflicting hunks are applied and that conflicting hunks are put + into reject files. + +* When the command `magit-discard' is used on staged changes, then + that is done by first reversing the changes in the index and then in + the working tree. The second step could fail due to conflicts. Now + the `--reject' argument is used, which ensures that non-conflicting + hunks are applied and that conflicting hunks are put into reject + files. + +* The command `magit-rebase-continue' learned to reuse the old commit + message as-is when called with a prefix argument. + +* In the refs buffer symbolic refs, such as "remotes/origin/HEAD", are + no longer omitted from the lists of local and remote branches. + +This release also contains the fixes described in the v2.6.1 and +v2.6.2 release notes, as well as various other documentation fixes, +code clean-ups, bug fixes, and other small to medium improvements. + +Authors +------- + + 95 Jonas Bernoulli + 10 Kyle Meyer + 7 Noam Postavsky + 1 Bart Bakker + 1 Fritz Grabo + 1 Ingo Lohmar + 1 John Mastro diff --git a/.config/emacs/lisp/magit/docs/RelNotes/2.8.0.txt b/.config/emacs/lisp/magit/docs/RelNotes/2.8.0.txt new file mode 100644 index 0000000..2ca6b70 --- /dev/null +++ b/.config/emacs/lisp/magit/docs/RelNotes/2.8.0.txt @@ -0,0 +1,128 @@ +Magit v2.8.0 Release Notes +========================== + +Released 21 August 2016 by Jonas Bernoulli. + +We are pleased to announce the release of Magit version 2.8.0, +representing 124 commits by 11 people over 3 months. + +Also see http://emacsair.me/2016/08/21/magit-2.8. + +Changes since v2.7.0 +-------------------- + +* Added several new functions that are suitable values for + `magit-display-buffer-function': + `magit-display-buffer-same-window-except-diff-v1', + `magit-display-buffer-fullframe-status-v1', + `magit-display-buffer-fullframe-status-topleft-v1', and + `magit-display-buffer-fullcolumn-most-v1'. + +* Added new commands `magit-list-repositories' and related new option + `magit-repolist-columns'. + +* Added new commands `magit-list-submodules and related new option + `magit-submodule-list-columns'. + +* Added new command `magit-branch-orphan'. + +* Added new command `magit-log-move-to-parent'. + +* Added support for globbing in file arguments of diff and log + commands. + +* Added support for showing and copying bad commit identified by git + bisect. + +* Added new option `magit-log-output-coding-system'. + +* Added new option `magit-no-message', which can be used to suppress + certain messages whose usefulness are being disputed. + +* Taught `magit-find-file-noselect' and `magit-find-index-noselect' to + use Emacs' encoding detection, and enable `revert-buffer' to work in + those buffers. This makes `magit-ediff-*' commands more useful for + files with non-standard encoding. + +* Taught `magit-insert-bisect-rest' to show the log graph by default. + The new option `magit-bisect-show-graph' controls this. + +* Taught `magit-insert-submodules' to display more information. + +* When a refresh causes the previously current hunk section to + disappear, which happens when it was applied in some way, then we + attempt to move to a sibling hunk. When that succeeds, then that is + now considered a proper move and `magit-section-movement-hook' is + called, which in turn may cause the current hunk to be recentered. + +* In addition to the directory, each member of the value of option + `magit-repository-directories' can now specify the depth to look for + repositories inside that directory, overriding the default depth + specified using the option `magit-repository-directories-depth'. + +* Blob visiting buffers can now be reverted, which is useful when they + visit a reference. + +* Command `magit-stage' can now be used outside of Magit buffers. + +* Commands that read a branch or commit from the user now also offer + tags as completion candidates. + +* Taught `magit-insert-worktrees' to use relative filenames. + +Fixes since v2.7.0 +------------------ + +* Function `magit-get-all' did split multi-line values into multiple + values. + +* Function `magit-subtree-read-prefix' which is used in order to read + the `--prefix' argument from the subtree popup was missing. + +* Command `magit-blame' failed when run in a blob buffer for a file + located in a subdirectory. + +* Command `magit-diff-visit-file' didn't visit a blob when called + inside a `magit-stash-mode' buffer. + +* Command `magit-submodule-add' did not allow picking a path that + does not exist yet and read the path before the url. + +* Command `magit-submodule-setup' did update existing modules, which + can cause them to become detached. + +* Command `magit-popup-describe-function' could create an extra window + on wide frames. + +* Commands `magit-diff-show-or-scroll-{up,down}' failed to scroll + stash buffers. + +* Mode `git-rebase-mode' did not respect the Git variable + `core.commentChar'. + +* Sections in the process buffer sometimes had invalid parent + sections, causing movement and visibility commands to fail, and + expected Git errors not to be handled gracefully in some cases. + +* Merges where not performed asynchronously, which made it impossible + to read a passphrase from the user, needed for commit signing. + +* In bare repositories tracked files were listed as deleted. + +This release also contains typofixes, documentation updates, code +clean-ups, bug fixes, and other small to medium improvements. + +Authors +------- + + 59 Jonas Bernoulli + 33 Noam Postavsky + 23 Kyle Meyer + 2 Mario Rodas + 1 Andriy Kmit' + 1 Basil L. Contovounesios + 1 Chris Shoemaker + 1 Ivan Brennan + 1 Laverne Schrock + 1 Samuel W. Flint + 1 Wilfred Hughes diff --git a/.config/emacs/lisp/magit/docs/RelNotes/2.9.0.txt b/.config/emacs/lisp/magit/docs/RelNotes/2.9.0.txt new file mode 100644 index 0000000..d7fa73c --- /dev/null +++ b/.config/emacs/lisp/magit/docs/RelNotes/2.9.0.txt @@ -0,0 +1,437 @@ +Magit v2.9.0 Release Notes +========================== + +Released 7 December 2016 by Jonas Bernoulli. + +We are pleased to announce the release of Magit version 2.9.0, +representing 250 commits by 18 people over 15 weeks. + +Also see https://emacsair.me/2016/12/07/magit-2.9. + +Breaking changes since v2.8.0 +----------------------------- + +* For historic reasons "RET" behaved differently in `magit-refs-mode' + than anywhere else. "RET" is one of Magit's most essential key + bindings and users quickly learn that regardless of what is actually + at point, it always shows more information about that thing in + another buffer. It can be very confusing if the references buffer + breaks this convention. + + Now `magit-visit-ref' behaves just like `magit-show-commit' even in + `magit-refs-mode' buffers. By default at least; you can easily + revert this change using: + + (setq magit-visit-ref-behavior '(checkout-any focus-on-ref)) + + However we recommend that you instead press "b b RET" to checkout + the reference at point, just like you always had to do in other + buffers. And "C-u y o RET" to make commit counts and lists of + cherries commits relative to the reference at point. + + Furthermore the option `magit-visit-ref-create' was removed. If you + previously had that set to `t', then you can achieve the same using: + + (add-to-list 'magit-visit-ref-behavior 'create-branch) + + However we recommend that you instead press "b c RET RET", just like + you always had to do in other buffers. #2868 + +* The option `magit-popup-show-common-commands' now defaults to `nil'. + + This was done to make popups less noisy but increases the odds + that some users will never become aware of the common commands. + To counter that, the usage instructions displayed in the echo area + now also mention the key that can be used to show these commands + temporarily. #2868 + + You can easily revert this change using: + + (setq magit-popup-show-common-commands t) + +* The option `magit-popup-use-prefix-argument' defaults to `default' + now, meaning that the use of a prefix argument causes the popup's + default action to be invoked directly without the popup being shown + first. + + Previously the use of a prefix argument did not invoke the popup + or its default action, and instead informed users that they had to + choose what behavior they wanted and that they had to set the option + accordingly. Doing that was necessary three years ago, when the + default behavior changed when "magit-key-mode.el" was replaced with + "magit-popup.el". Now we don't need that safety net anymore. #2868 + +* If, and only if, point is on a removed line in a diff, then "RET" + now jumps to the last commit which still had that line, not the + commit which removed that line. Staged changes are excluded from + this new behavior because in that case it seems favorable to always + visit the file in the working tree to make further changes. #2755 + + You can easily revert this change using: + + (setq magit-diff-visit-previous-blob nil) + +* The margin that by default is displayed in pure log buffers and + optionally in some other buffers that contain logs is now more + flexible and easier to customize and to change on the fly. + + The popup that "L" is bound to now features three commands that + for changing the appearance of the margin: `magit-toggle-margin', + `magit-toggle-margin-details' and `magit-cycle-margin-style'. + + The binding for `magit-toggle-margin' has changed from "L t" to the + simpler "L L". You can easily revert this change using: + + (magit-change-popup-key 'magit-log-refresh-popup :action ?L ?t) + (magit-change-popup-key 'magit-margin-popup :action ?L ?t) + + For each mode that supports the margin there now exists a dedicated + option named `magit-*-margin', which controls whether the margin is + shown initially, whether the author name is displayed in addition + to the committer date, and how that committer date is formatted. + All of these options can be found in the new `magit-margin' Custom + group. + + It is now possible to show the actual committer date, using a time + format of your choosing. Previously the only option was to display + the age of the commit. + + The old options that were previously used to configure the margin + have been removed. If you have customized `magit-log-show-margin', + `magit-reflog-show-margin' and/or `magit-refs-show-margin', then you + now have to customize the respective new variable whose names do not + contain "-show". The same applies if you have previously changed + the value of `magit-log-margin-spec'. Unfortunately this cannot be + automated because the format of the values has changed and because + the old customizations do not unambiguously map to the new options. + + You might also want to customize the options `magit-status-margin', + `magit-stashes-margin' and `magit-log-select-margin', for all of + which no corresponding `magit-*-show-margin' used to exist. Another + new option is `magit-refs-margin-for-tags'. + + If you choose to display the commit dates instead of the commit + ages in all supported modes, then you should set `magit-log-margin' + before loading `magit'. If you do that then the default values of + the other `magit-*-margin' options will use the same commit date + style without you having to customize each option individually. + #2885, #2792 + +* By default Git-Commit no longer complains about a summary line that + is too long by some standards. You can easily revert this change + using: 2f115d51 + + (add-to-list 'git-commit-style-convention-checks + 'overlong-summary-line) + +* In buffers used to write commit messages `fill-column' is no longer + set to 72. Instead the default value 70 is used (or whatever local + or global value is set up through other means). You can easily + revert this change using: #2848, #2852 + + (setq git-commit-fill-column 72) + +* When it takes too long to parse diffs, then Magit used to stop + expanding diff sections after one second. This was a constant + source of confusion and one second is a very long time anyway, so + this did not really help hiding the slowness, so this kludge was + effectively dropped. You can easily revert this change using: + + (setq magit-diff-expansion-threshold 1.0) + + By the way, improving performance will soon be a priority again. + #2886 + +Changes since v2.8.0 +-------------------- + +* Magit has a new shiny logo! It was created by Dmitriy A. from + Prospect One. Thanks a lot! https://prospectone.io/portfolio/magit + +* The new option `magit-branch-adjust-remote-upstream-alist' can be + used to configure what branch to use as upstream when branching a + remote branch. Without setting this option the upstream ends up + being the same branch as the one referred to by the push-remote. + 85c3053d + +* The per-refresh cache, which is used to save calls to git because + that is surprisingly slow on Windows, has been improved for calls to + `git config'. Instead of just avoiding identical calls to `git + config' as for other sub-commands, we now call `git config --list' + only once per refresh to obtain a list of all variables and their + values. #2743 + +* When visiting a file or blob buffer by pressing "RET" while point is + inside a diff, then the position this jumps to is now accurate (even + when jumping to the file in the working tree from a diff that wasn't + about changes in the working tree). #2828 + +* When visiting a file or blob buffer by pressing "RET" while point is + inside a diff, then the buffer may be widened but only if necessary. + If it isn't necessary to widen the buffer to jump to the appropriate + location, because that position falls into the narrowed region, then + that the buffer isn't widened. #2804, #2818 + +* Hunk refinement is now faster. Users who previously set + `magit-diff-refine-hunk' to `nil' due to performance issues may + find that it now works well even when set to `all'. #2834 + +* The new options `magit-diff-highlight-hunk-region-functions' and + `magit-diff-unmarked-lines-keep-foreground' (which was previously + defined as an undocumented variable) allow tuning the appearance + of the hunk-internal region. + + The new function `magit-diff-highlight-hunk-region-using-face', + provides a new style; it makes the hunk-internal region bold (or + italic). I recommend you customize the above option to use this + function instead of one of the functions mentioned below. + + The new functions `magit-diff-highlight-hunk-region-using-overlays' + and `magit-diff-highlight-hunk-region-using-underline' draw one-pixel + lines before and after the hunk-internal region. Both of these + functions have (different) glitches and due to limitations of Emacs' + display engine it is not possible to fix those. #2293, #2758, #2791 + +* Added command `magit-find-git-config-file' and variants to make it + easier to open a file located in the git directory when ".git" is + a regular file whose contents describe the location of the real git + directory. 8664223c + +* Added command `magit-emacs-Q-command' to make troubleshooting and + bug reporting easier for users not installing from the git + repository. #2856 + +* The command `magit-branch-spinoff' learned to remove only a subset + of commits from the previously current branch, instead of resetting + it to its upstream, when the region selects commits reachable from + HEAD. 1e652b87 + +* The command `magit-branch-delete' now falls back to deleting the + tracking branch when the user attempts to delete a remote branch + which does not actually exist on the remote anymore. #2778 + +* The command `magit-diff-dwim' learned about additional cases. On + a non-current branch it now shows the diff for "CURRENT...BRANCH" + (instead of "BRANCH..CURRENT") and inside a stash buffer it shows + the diff for the commit at point. #2812 + +* The command `magit-push', which "o" is bound to in the push popup, + now offers the push-branch as default choice. Only if that is not + set does it default to the upstream as before. And when pushing a + commit that is reachable from HEAD, then it offers to push to the + push-branch or upstream of the current branch (which still has to + be forced explicitly). #2820 + +* Log commands now support completion of refs in the "refs/tags" and + "refs/pull" namespaces. #2878 + +* Added option `magit-no-confirm-default' to allow specifying commands + which should just use the default choice instead of having the user + confirm that by pressing RET. I recommend you don't use this, but + if you think that the defaults are so good that you always want to + use them, then this might make it a bit easier for you. #2741 + +* Added option `magit-slow-confirm' for users who are afraid they + would answer `y-or-n-p' questions to quickly. One action, deleting + all stashes, now defaults to having to be confirmed with "yes RET". + #2752 + +* Added option `magit-view-git-manual-method' to allow following links + to the Git Info manual by visiting the respective manpage instead. + de38266a + +* The option `magit-branch-prefer-remote-upstream' now also supports + regexps as members instead of only complete branch names. #2823 + +* The option `magit-branch-read-upstream-first' used to be a boolean. + Now it supports a third value `fallback', which means to read the + upstream first like `t', but if the value provided by the user does + not reference an existing revision, then it is treated as the name of + the new branch and the upstream is read using the second prompt, as + if the value of this option were `nil'. #2741 + +* When deleting a stash, the hash is now logged to the process log + buffer in addition to *Messages*, making it more likely that a + user who accidentally deleted a stash would find the information + required to undo that. #2746 + +* The environment variable `INSIDE_EMACS' is now set when calling git. + #2789 + +* `magit-define-popup' now allows specifying `:max-action-columns' per + section by using a function that returns a different value based on + the heading, which is passed as argument. 964fcbe0 + +* Added support for new gpg status letters X, Y, R, and E. #2845 + +* Added `hl-line-mode' to `magit-repolist-hook' and + `magit-submodule-list-hook' and defined those hooks explicitly. + 9f806732 + +* Added the `--gpg-sign=' option to the revert popup. 916e4599 + +* Added the `--sort=' option to the show-refs popup. (Use "C-u y" to + show the popup instead of invoking its default action as "y" does.) + 8ab81f06 + +* Added new faces `git-rebase-comment-heading' + and `git-rebase-comment-hash'. #2769 + +* `whitespace-mode' is not compatible with Magit buffers, where it is + now actively prevented from being turned on by the user. #2821 + +Fixes since v2.8.0 +------------------ + +* The command `magit-list-repositories' failed on empty repositories. + 09fac022 + +* The Git variable `pull.rebase' was ignored when determining whether + the current branch is being rebased onto its upstream in order to + display that information in the status buffer. 9c946ee3 + +* On 32-bit systems `magit-format-log-margin' failed because it tried + to truncate a time float that was too large for that. #2765 + +* On Emacs v25.1 the hunk-internal region flashed briefly on + mouse-down-1 events and the delimiting horizontal lines could end + up having the height of a regular line instead of just a single + pixel. #2758 + +* On Windows, when using a `windows-nt' Emacs together with a cygwin + Git, we failed to instruct Emacs to not use dos shell quoting when + calling git. And if Git wasn't available, then that caused an + error, which prevented Magit from being loaded. #2842 + +* The encoding of commit messages is controlled by the Git variable + `i18n.logOutputEncoding' but we failed to take that into account. + Fixes by setting `i18n.logOutputEncoding' to UTF-8, but only inside + Magit and only for `window-nt'. #2738, #2813 + +* It wasn't taken into account, until a few days after the release, + that as of Git v2.11, the default abbreviation size is no longer + hardcoded as 7 but instead scales with the repository size. #2880 + +* File and directory local variables were not honored in the buffers + used to write commit messages. #2852 + +* The caching mechanism that is supposed to ensure that sections of + unpulled and unpushed commits remain collapsed even when they + disappear was broken for a while. 0ad041c4 + +* Process sentinels did not in all cases ensure that the correct + buffer was current before doing something that assumes that this is + the case. Almost always that did not matter because it was the case + anyway, but if other timers are running then it is possible that + those make the wrong buffer current. #2836 + +* Process sentinels and filters used when blaming assumed that the + `exit' process status indicates success. #2836 + +* The commands `magit-clone' and `magit-init' did not work over Tramp. + #2806, #2807 + +* The commands `magit-worktree-checkout' and `magit-worktree-branch' + did not expand the path they pass to git, which is necessary because + git does not know the meaning of "~/". #2796 + +* The commands which create fixup/squash commands and then immediately + squash them into the target commit did not remove `--gpg-sign' or + add `--no-gpg-sign'. Signing such commits is not only unnecessary; + unless the passphrase was cached earlier, trying to sign resulted in + the process indefinitely waiting for the passphrase to arrive with + no way for the user to actually provide it. #2799 + +* Depending on the value of `magit-save-repository-buffers' the user + might have been asked whether s/he wants to save "git-rebase-todo", + which is never necessary and just a distraction. #2770, #2771 + +* The function `magit-save-repository-buffers' did not follow symlinks. + #2843 + +* Directories whose names begin with a period were filtered out when + using `magit-repository-directories' to calculate a list of repos. + #2830 + +* The user name and email, which are displayed when reading a gpg key + from the user, were not stripped from the chosen value before being + handed off to git. #2761 + +* When the upstream of the current branch is a remote whose url isn't + configured then that caused an error when refreshing the status + buffer. #2858 + +* Buffers visiting a blob used the file's `default-directory' + even when that directory did not exist in the working tree. The + top-level directory is now used as `default-directory' when the + subdirectory does not exist. cfe46766 + +* When visiting a directory by displaying a Dired buffer, we used to + display a buffer for the parent of the directory in question and + placed point on the name of the directory. But the intention always + was to show the Dired buffer for the directory itself. 5665ba94 + +* Visiting or deleting a submodule listed inside "Modules" failed. + The latter is now done by de-initalizing the module. c26b746e + +* In the list of commits that are being rebased in the status buffer, + HEAD was sometimes prefixed with "same" when "stop" would have been + correct. #2877 + +* The highlighting of a non-empty second line in a commit message was + not automatically updated. #2777 + +* When `--force-with-lease' was added to the `magit-push-popup', + `--force' was removed, but sometimes the former just isn't enough. + be39a9ba + +* The face `magit-diff-file-heading-highlight' used to inherit from + `magit-diff-file-heading', which by default makes text bold. That + resulted in the complete current heading to be bold, but only the + file-name part is supposed to be bold. a4b52516 + +* The manual stated that "DEL" in Git Rebase mode was bound to + `magit-diff-show-or-scroll-down', which was not the case. A new + command `git-rebase-show-or-scroll-down` has been added and bound + to "DEL" to provide this functionality. #2863 + +* The function `magit-repolist-status' did not expand the filename + which may be necessary when listing submodules. cc8c1385 + +* The macro `magit-with-temp-index' did honor the refresh cache, even + though its BODY may contain calls to git that are identical to + outside calls during the same refresh, but which are expected to + return a different value due to the use of a different index. #2883 + +* The log margin did not show the author of stashes. #2846 + +* The status header about the upstream did not take + `branch.NAME.rebase' into account. e65f15d0 + +* Highlighting overlays could not be garbage collected until after a + refresh. #2888 + +This release also contains typofixes, documentation updates, +code clean-ups, and other small bug fixes and improvements. + +Authors +------- + + 196 Jonas Bernoulli + 21 Kyle Meyer + 12 Noam Postavsky + 4 Alexander Gramiak + 2 Adam Porter + 2 Marco Wahl + 2 Sean Allred + 1 Allen + 1 Basil L. Contovounesios + 1 Chillar Anand + 1 Graham Dobbins + 1 Joakim Jalap + 1 Josiah Schwab + 1 Keshav Kini + 1 Marian Schubert + 1 Philipp Stephani + 1 Tunc Uzlu + 1 York Zhao diff --git a/.config/emacs/lisp/magit/docs/RelNotes/2.90.0.org b/.config/emacs/lisp/magit/docs/RelNotes/2.90.0.org new file mode 100644 index 0000000..4d9f6e5 --- /dev/null +++ b/.config/emacs/lisp/magit/docs/RelNotes/2.90.0.org @@ -0,0 +1,423 @@ +* Magit v2.90.0 Release Notes + +Released 8th November 2018 by Jonas Bernoulli. + +I am pleased to announce the release of Magit version 2.90.0, +representing 395 commits by 18 contributors over five months. + +Also see https://emacsair.me/2018/11/08/magit-2.90. + +** Breaking changes + +- Dropped support for Emacs 24.4. At least Emacs 25.1 is required + now. + +- Dropped support for Git 1. At least Git 2.0.0 is required now. The + reason 2.0.0 is the new minimal version isn't its roundness but the + discovery that some parts of Magit already depended on that release + for two years. Since we will soon drop support for versions before + (probably) 2.4.0 anyway, we don't add a backward compatibility + kludge for the feature that already requires 2.0.0 but instead bump + the minimal version a first time. + +- Many commands were renamed, making their names longer. The old + names are defined as aliases for now. This is part one of a two + part change. In this release we rename, for example, ~magit-tag~ to + ~magit-tag-create~ and in a later release ~magit-tag-popup~ will be + renamed to ~magit-tag~. #3619 + +- Removed many obsolete variable and function aliases. + +- Removed many obsolete variables that are not mere aliases. + +- Removed ~magit-section~ accessor functions. Use the ~oref~ and ~oset~ + functions instead. + +- The function ~magit-section-when~ has been deprecated in favor + of ~magit-section-match~ or the new ~magit-section-value-if~. The + signatures of some related low-level functions have changed. #3590 + +- The ~submodule~ section type has been renamed to ~module~, same for the + plural variant and the related section-specific keymaps. 35f803c9c, + 59e3891fd + +- Added a new function ~magit-completing-read-multiple*~, which is more + like ~magit-completing-read~ than ~magit-completing-read-multiple~. + Authors of extension should use the new function, which eventually + will replace the old one. cb4d59190 + +** Changes since v2.13.0 + +- Added a new mode ~magit-wip-mode~, which enables automatic committing + to work-in-progress refs whenever that makes sense. Previously + multiple ~magit-wip-*~ modes had to be enabled to accomplish the same. + These modes still exist, the new mode is implemented on top of them, + but their explicit use by the user is discouraged. #3534 + +- Added a new option ~magit-wip-merge-branch~, which causes the current + branch to be merged into its wip refs after creating a new commit on + the current branch. This isn't enabled by default yet because some + additional tooling is required to deal with the fact that this + prevents the wip refs from ever being garbage collected, and results + in unwieldy commit graphs when history manipulation is involved. + #3534 + +- Added new commands ~magit-wip-log-index~ and ~magit-wip-log-worktree~. + #3534 + +- It is now possible to specify the major-mode used to edit commit + messages on a per-repository basis. The same major-mode is also + used to prettify commit messages when displaying existing commit + messages in ~magit-revision-mode~ buffers. + + To set the major-mode to be used for commit messages add an entry + to the appropriate ~.dir-locals.el~ file using ~git-commit-mode~ as + the key, as if that mode were a major-mode. This can also be used + to set other variables in the buffers used to /edit/ commit messages. + + If ~$GIT_WORK_TREE/.git~ is a file, then ~$GIT_WORK_TREE/.dir-locals.el~ + would normally not apply when editing a file inside ~$GIT_DIR~. Magit + uses it anyway unless ~$GIT_DIR/.dir-locals.el~ exists. + + 55ba0534c, d7412da32, c5269547a + +- Added a new major-mode ~git-commit-elisp-text-mode~ intended to be + used when editing commit messages for Elisp projects. It derives + from ~text-mode~ and additionally highlights ~`symbols'~ and "strings". + d7fa6632b + +- Changed the order and the initial visibility of log sections in the + status buffer to optimize for "usefulness". Previously the focus + was on making it more likely that the user did not ignore the less + frequently useful logs, but that was quite annoying because it got + in the way of the more frequently performed tasks. #3518 + +- Added new option ~magit-status-initial-section~, which controls which + section point is placed on when a status buffer is created. The new + default is to place point on the section that follows the headers, + i.e., the second section. This is quite flexible, you might want to + read the doc-string. 87de83da8, #3562, #3518 + +- Added new commands ~magit-commit-absorb~ and ~magit-commit-absorb-popup~. + These commands depend on the ~git-autofixup~ script, which is available + from https://github.com/torbiak/git-autofixup. #3053 + +- Began migrating from using section "types" to using section classes + that can inherit from other classes. #3590 + +- Removed many backward compatibility hacks, which are no longer + necessary. + +- Began to use features and many convenience functions that we + couldn't use before because we still supported Emacs 24.4. + +- ~magit-file-rename~ now reads the target from the same directory as + the source. This is more convenient because removing parts of the + path is easier than adding them again. + +- Added new ~magit-gitignore-popup~ and bound ~I~ to it, making it + possible to use ~i~ for the ~magit-imerge-popup~ from the ~magit-imerge~ + package. + +- Renamed the existing command ~magit-describe-section~ to + ~magit-describe-section-briefly~ and added a new command + ~magit-describe-section~, which pops up a ~*Help*~ buffer, + which contains information about the function and hook + used to insert the section. #3539 + +- Added new ~magit-refname-pullreq~ face and a corresponding entry to + ~magit-ref-namespaces~. + +- Added new option ~magit-log-trace-definition-function~, which allows + specifying the function that ~magit-log-trace-definition~ should use + to determine the function at point. The default is ~which-function~. + Previously the less complete ~add-log-current-defun~ was used. + #3483, 9ff266358 + +- fixup! and squash! are now highlighted like [keywords] in logs. + 426773040 + +- Added new stub commands ~magit-browse-thing~ and ~magit-edit-thing~. + Like other ~magit-*-thing~ functions they are intend to be replaced + in section-specific keymaps. The ~forge~ package will use do so for + these commands. 56fccaca6, 0fa3092eb + +- In case they are bound when Magit is loaded then ~$GIT_DIR~ and + ~$GIT_WORK_TREE~ are unset now. Magit breaks if these variables are + set and the most likely cause for them to be set is a user error. + 2d7d5d840 + +- ~magit-merge-into~ now only offers local branches for completion and + defaults to the upstream. If the upstream is a remote branch then + it defaults to the respective local branch. a52d70198 + +- It is now possible to set the face used to highlight the headings of + certain sections using the new ~heading-highlight-face~ slot. 2319a1e0e + +- The summary line of a commit message and the first line of notes are + now emphasized more to make it more obvious what text is part of the + commit message and what text was added by a note. fda4b936c + +- Detection of the branch at point was improved. #3530 + +- Added new shortstat margin style for logs. Performance isn't good + yet, so you might want to avoid this for long logs. #3035 + +- Added new variable ~magit-perl-executable~ for platforms that put ~perl~ + in unusual places. We use ~perl~ for some one-liners that are embedded + in lisp because we known that it is available because ~git~ depends on + it. #3538 + +- Added new command ~magit-reset-worktree~. The existing ~magit-reset-*~ + commands already implemented the variants supported by ~git reset~, + now Magit also implements the variant missing from that. b4d5c2bee + +- Improved ~magit-process-password-auth-source~'s entry matching. + 60a335e5c + +- Added new hook ~magit-create-buffer~ hook. 2113dfc3d + +- When the user "discards" a file with conflicts then they are asked + which side of the conflict they want to keep. When multiple files + are selected, then it is now possible to decide for all of them at + once. #3553 + +- Added option ~--ignore-submodules~ to diff popups. This option does + not only affect diffs but also the dedicated module sections and can + therefore be used to temporarily hide all information about modules, + which can be expensive to calculate. #3555, #3568 + +- Added ~--graph~ to the default value of ~magit-log-select-arguments~ + instead of hard-coding this argument for some of the users of the + log-select machinery. #3559 + +- The upstream of the current branch is no emphasized in logs, by + default by making it italic. #3573 + +- Added new command ~magit-submodule-remove~ and the new related option + ~magit-submodule-remove-trash-gitdirs~. The default is to not trash + the gitdirs. ~magit-submodule-add~ now offers to reuse an existing + gitdir when re-adding a submodule. #3585 + +- ~magit-submodule-add~ is run asynchronously now. #3585 + +- Information about the running Git process is now also shown in the + mode-line of buffers that were created after the process was + started. 43264c873 + +- Rebase commands that continue a rebase sequence can now use ~git rbr~ + instead of ~git rebase~. To initiate a rebase sequence using ~git rbr~ + you may use https://github.com/fanatoly/magit-rbr. c2cd780b2 + +- The manual is now also available in epub format, but it isn't very + pretty. #3579 + +- Added new hooks ~magit-stage-hook~ and ~magit-unstage-hook~. #3496 + +- Added new hook ~git-commit-post-finish-hook~, a hook that has been + requested many times but which I did not implement before because it + is impossible to make 100% reliable. When the ~emacsclient~ returns, + then that does not mean that the calling process is done too. We + avoid a race condition by waiting for ~HEAD~ to point to a different + commit than it used to point to, before running the hook. If it + takes longer than a second for this to happen, then the hook is not + run. A few unsafe commands are also blacklisted because they + perform other things after creating the commit and that would lead + to another race condition. #3615, d445a3d30, af4bf8df8 + + This hook is used instead of ~with-editor-post-finish-hook~ (on which + the former is build) to merge the current branch into its wip refs + when ~magit-wip-merge-branch~ is non-nil. + +- Added new hook ~magit-post-commit-hook~, which is only run after + running a ~magit-commit-*~ command that does not require the user + to edit the commit message. #3615 + +- ~magit-format-patch~ can now be told to only include the changes to + certain files in the patch. It now also refreshes Magit buffers. + #3601 + +- The list of related refs in ~magit-revision-mode~ buffers is no longer + truncate when it doesn't fit on a single line. Instead users can + now specify the kinds of refs that should be inserted in such + buffers using the option ~magit-revision-insert-related-refs~. #3487 + +- Added new function ~magit-gitdir~ scheduled to replace ~magit-git-dir~ + eventually because the latter has a really strange signature. + 5f407a29a + +- Created new libraries from existing code. 9efcb1e8b ff + +- The option ~magit-revision-show-gravatar~ is now easier to customize. + Customizing it to only show one of the two images actually works + now. f4b8fee66, b82228bc6 + +- The option ~magit-repository-directories~ has a non-nil default value + now. f77d1158b + +- The list of stashes in the status buffer is initially collapsed now. + 4dc1d0593 + +- The commands ~magit-previous-line~ and ~magit-next-line~ are used by + default now. 3ae75c865 + +- Added support for ~--left-right~ output in logs. #3627 + +- Added new option ~magit-with-editor-envvar~. Changing its value from + ~GIT_EDITOR~ to ~GIT_SEQUENCE_EDITOR~ allows users to continue to use + Magit (~git-rebase.el~ actually) to edit rebase sequence but to use + another editor to edit commit messages and such. #3629 + +- Added new option ~magit-clone-default-directory~. #3635 + +- ~magit-ref-namespaces~ is now taken into account when colorizing + branch names in buffers listing refs. #3645 + +- Added new option ~magit-revision-fill-summary-line~. #3610 + +** Fixes since v2.13.0 + +- A confirmation prompt during rebase was wrong. 37d76f409 + +- ~magit-rebase-autosquash~ asked for confirmation when the user already + confirmed earlier. 02e6c75b6 + +- ~magit-commit-add-log~ inserted after the diff that gets inserted if + ~commit.verbose~ is ~true~. #3480 + +- ~magit-log-wash-rev~ errored in ~magit-cherry-mode~, starting with Emacs + 26.1. + +- ~magit-dired-jump~ failed, starting with Emacs 26.1. #3469 + +- Magit used a completion function to make the built-in completion + respect the collection's order. Even though that wasn't necessary + for Ivy and Helm it did the same here, which became a problem when a + change in Helm caused fuzzy completion to break in combination with + a completion function. Likewise a change in Ivy caused Magit's sort + order to be ignored, which we work around now. #3476, #3477 + +- In some edge cases ~magit-branch-pull-request~ used to set Git + variables to invalid values. #3417 + +- The section visibility cache used ~eq~ when it should have used ~equal~. + It also briefly used ~alist-get~, which we cannot do because that did + not take a ~testfn~ argument in Emacs 25. #3495, #3499 + +- Detecting whether a commit has already been pushed to a "publishing" + branch was much slower than it had to be. #3519 + +- ~magit-gitignore-popup~'s autoload definition was broken. + +- When using cygwin, then ~git-commit-setup-font-lock~ could end up + trying to run git in a non-existent directory. #3505 + +- ~magit-completing-read~ did not protect the value of ~this-command~ even + though there is code that assumes it does. #3529 + +- ~magit-read-file-trace~ in some cases claimed that valid user input + was invalid even though it was valid. Now we don't try to validate + it anymore. #3531 + +- We didn't account for the surprising fact that asking whether the + value of a local variable is risky can change point. #3541 + +- ~magit-merge-into~ signaled an error if the upstream of the current + branch isn't configured instead of letting the user pick a target. + #3550 + +- Some of the more complex ~magit-cherry-*~ variants did not abort if + the first step failed. #3556 + +- Trying to visit a commit of a submodule directly from the status + buffer of the super-projects resulted in an error. #3563 + +- ~magit-file-rename~ failed to rename a file that is located at the + top-level of the working tree. #3569 + +- Magit didn't account for ~git rebase -i --root~ corrupting the root + commit's author date field, resulting in its output being corrupted + too. #3574 + +- If given one invalid rev, then ~magit-rev-eq~ returned ~nil~, but when + both revs are invalid, then it returned ~t~. Now it returns ~nil~ in + both cases. + +- In an edge case ~magit-diff-type~ falsely concluded that the + uncommitted changes in a diff buffer already are committed. #2627 + +- ~magit--github-url-p~ failed to return ~t~ for an url for Github + Enterprise instances. #3572 + +- Trying to insert Gravatar images resulted in an error if the service + is not reachable. #3597 + +- ~magit-display-buffer~ always selected the appropriate frame even if + that was already selected. That is undesirable because selecting + a frame has side-effects. f07eb85c6 + +- A key binding was not updated when ~magit-submodule-deinit~ was renamed + to ~magit-submodule-unpopulate~. b06845208 + +- ~magit-submodule-visit~ could end up re-populating the visited module. + 3d794cd01 + +- The third-party ~git-annex~ program converts submodule gitdirs to + symlinks, which we did not account for. #3599 + +- ~magit-bisect-start~ did fail silently when invalid user input, which + flipped the good and bad revisions, instead of providing an + informative error message. #3604 + +- ~magit-bisect-start~ did fail silently when there are uncommitted + changes instead of providing an informative error message. In some + cases it actually is possible to bisect with uncommitted changes but + that would be dangerous and we do not try to detect whether that is + the case and just always error out. #3604 + +- When applying changes, then the ~--unidiff-zero~ and ~-C0~ arguments + were not automatically used when needed. The former wasn't used + because of a bug, the latter because I was not aware that there + was an edge case that makes that necessary. #3608 + +- Backported a fix (from Emacs 27) for an Emacs bug that sometimes + caused ~git rebase~ to fail to acquire the ~index.lock~. #2708, + https://debbugs.gnu.org/cgi/bugreport.cgi?bug=21559 + +- Autoloading ~magit-submodules~ didn't work. #3618 + +- Reverting files failed if the selection contained only binary files. + c7bbe3e9a + +- ~magit-read-repository~ failed when ~magit-repository-directories~ is + non-nil but no repository can be found in those directories. #3636 + +- Attempting to reverse changes to binary files failed with an error + that wasn't informative enough. #3625 + +- When a local branch is being renamed, then ~magit-branch-rename~ used + to also rename the (remote) push-target, which is unsafe in some + cases. Now it always asks the user before doing so. 14c7b1381 + +* Authors + + 333 Jonas Bernoulli + 31 Kyle Meyer + 13 Noam Postavsky + 2 Phil Sainty + 1 Alex Branham + 1 Aria Edmonds + 1 Arialdo Martini + 1 Basil L. Contovounesios + 1 Benjamin Motz + 1 Bob Uhl + 1 Eric Prud'hommeaux + 1 Felix Yan + 1 John Morris + 1 Jordan Galby + 1 Louis Roché + 1 Mak Kolybabi + 1 Miciah Masters + 1 N. Troy de Freitas + 1 Pierre Neidhardt + 1 Raimon Grau diff --git a/.config/emacs/lisp/magit/docs/RelNotes/2.90.1.org b/.config/emacs/lisp/magit/docs/RelNotes/2.90.1.org new file mode 100644 index 0000000..2c601f8 --- /dev/null +++ b/.config/emacs/lisp/magit/docs/RelNotes/2.90.1.org @@ -0,0 +1,39 @@ +* Magit v2.90.1 Release Notes +** Changes since v2.90.0 + +- Added ~bug-reference-mode~ to ~git-commit-setup-hook~. e19e8fb1e + +- The "Version" column in ~magit-submodule-list-mode~ and + ~magit-repolist-mode~ buffers now shows when a repository is dirty. + 0b86dbfd6 + +- Added new command ~magit-log-merged~. This command requires + ~git-when-merged~ (https://github.com/mhagger/git-when-merged). It + isn't bound in ~magit-log-popup~ by default. To add it, you can use + something like + + #+BEGIN_SRC emacs-lisp + (magit-define-popup-action 'magit-log-popup + ?m "Log commit's merge" 'magit-log-merged) + #+END_SRC + + #3657 + +** Fixes since v2.90.0 + +- Bumped the minimal required version of ~git-commit~ to the correct + version. e9bd33758 + +- Dropped the new "v" prefix that we started to add to release tags + starting with the previous release in places where that prefix is + undesirable. f441cf6d7 + +- Staging and unstaging submodules while ~diff.submodule~'s value is ~log~ + broke shortly before the v2.90.0 release. #3654 + +* Authors + + 10 Jonas Bernoulli + 1 Allen Li + 1 Kevin Brubeck Unhammer + 1 Kyle Meyer diff --git a/.config/emacs/lisp/magit/docs/RelNotes/3.0.0.org b/.config/emacs/lisp/magit/docs/RelNotes/3.0.0.org new file mode 100644 index 0000000..0c9883d --- /dev/null +++ b/.config/emacs/lisp/magit/docs/RelNotes/3.0.0.org @@ -0,0 +1,686 @@ +* Magit v3.0.0 Release Notes + +Released 25th May 2021 by Jonas Bernoulli. + +I am pleased to announce the release of Magit version 3.0.0, +representing 1264 commits by 87 contributors over 2.5 years. + +Also see https://emacsair.me/2021/05/25/magit-3.0. + +** Breaking changes + +- Dropped support for Git v2.0 and v2.1. + +- After some users intervened I have decided to NOT drop support for + Emacs 25 in this release as I had intended to do. Emacs 25 should + remain supported for at least a few more releases. + +- Magit now uses Transient instead of Magit-Popup. In the transition + many popups gained new arguments and/or commands, most of which are + not mentioned explicitly in these release notes. Many of these + commands are hidden by default because they are only useful to a + subset of users. See https://emacsair.me/2019/02/14/transient-0.1 + for information about the new Transient library and how to enable + hidden commands, among other things. + +- The commands ~magit-branch-pull-request~, ~magit-checkout-pull-request~ + and ~magit-worktree-checkout-pull-request~ were removed in favor of + improved implementations provided by the new Forge package. (See + https://emacsair.me/2018/12/19/forge-0.1 for more information about + Forge.) + +- ~C-c C-e~ is no longer bound to ~magit-dispatch-popup~. It is bound to + ~magit-edit-thing~ now, so that Forge can add section-specific + bindings using this key. ~magit-dispatch-popup~ has been renamed to + ~magit-dispatch~ and continues to be available on ~h~, ~?~ and ~C-c C-c~. + #3659 + +- ~C-c C-b~ is no longer bound to ~magit-browse-thing~ to avoid a conflict + with ~magit-go-backward~ in diff and log buffers. ~C-c C-w~ (as in web) + is used instead now. #3659 + +- The option ~magit-display-file-buffer-function~ was removed. 8a214c9fb + +- The buffer-local variable ~magit-refresh-arguments~ was replaced with + several variables because ~(nth N magit-refresh-arguments)~ just isn't + very informative. Several related API functions had to be changed + in incompatible ways. This was done by adding new functions and + keeping the old variable and functions around for backward + compatibility. Packages using the obsolete variable and functions + should be adjusted soon. #3836 + +- Magit-Section is now distributed as a separate package, as announced + here: https://emacsair.me/2020/01/23/magit-section. #4003 + +- Magit now adds three global key bindings, which can be prevented + by setting the new option ~magit-define-global-key-bindings~ before + loading ~magit~. Note that if you bind these keys to other commands + anywhere in your init file (even *after* loading ~magit~), then Magit + won't override those bindings. See the options doc-string for + more information. #4237 + +- Magit no longer depends on ~async-bytecomp~ to avoid a certain class + of mystery bugs because this effort backfired. 86eec7ba3 + +- ~global-git-commit-mode~ is no longer autoloaded. Users who commit + from the command-line but still want to use ~git-commit-mode~, might + now have to load ~git-commit~ explicitly in their init file. + 13f20763a + +** Changes since v2.90.0 + +- It isn't always obvious that a section can be expanded, especially + to users who are just getting started with Magit. Mainly to make + it easier for those users, expandable and collapsible sections now + get an indicator in the fringe. + + The new option ~magit-section-visibility-indicator~ can be used to + disable this or to select the alternative style, which shows an + ellipsis at the end of the heading of each expandable section + instead. #3679 + +- The "Version" column in ~magit-submodule-list-mode~ and + ~magit-repolist-mode~ buffers now shows when a repository is dirty. + 0b86dbfd6 + +- Added new command ~magit-log-merged~. This command requires + ~git-when-merged~ (https://github.com/mhagger/git-when-merged). + It is a suffix of ~magit-log~ but is disabled by default. #3657 + +- Added new class slot ~keymap~ to allow other packages to define + section-specific keymaps without naming them ~magit-TYPE-section-map~, + which would mean using a symbol prefix (~magit-~) that does not match + the package name. + +- Added new option ~magit-diff-refine-ignore-whitespace~, overriding and + defaulting to the value of ~smerge-refine-ignore-whitespace~. #3671 + +- Added new option ~magit-diff-paint-whitespace-lines~, which controls + in what kind of lines (added/removed/context) whitespace errors are + highlighted. #3671 + +- It is now possible to show whitespace errors only in uncommitted + changes by setting ~magit-diff-paint-whitespace~ to ~uncommitted~. The + obsolete value ~status~ is treated as a synonym. The intention always + was to allow limiting to uncommitted changes and limiting to changes + shown in the status buffer was the closest approximation readily + available when this feature was first added. #3671 + +- The commands ~magit-commit-instant-fixup~, ~magit-commit-instant-squash~ + and ~magit-rebase-autosquash~ now unconditionally preserve empty + commits that were already present before the autosquash rebase + performed by these commands. This is the safe default; if you want + to drop such commits, then you have to enable ~--autosquash~ in the + popup and then invoke ~magit-rebase-interactive~. #3670 + +- ~magit-rebase-remove-commit~ now supports removing the ~HEAD~ + commit. #4195 + +- The option ~magit-repository-directories~ defaults to ~nil~ again + because the non-nil default added in v2.90.0 led to surprising + changes in behavior. The documentation of this option and the + related ~magit-status~ command were made less ambiguous. #3673 + +- Renamed the face ~git-commit-note~ to ~git-commit-keyword~ because that + is what text in brackets is called elsewhere in Magit and because + the term "note" was ambiguous in this context. The old face name + is still defined as an alias, but that will be removed eventually. + +- The command ~magit-worktree-checkout~ now also offers tags and remote + branches as completion candidates. #3692 + +- The command ~magit-commit-reword~ now always uses ~--allow-empty~ + because when you reword an empty commit, then you have already + confirmed that you are okay with that commit being empty. + +- The new buffer-local variable ~git-commit-need-summary-line~ can + be of use if you want to write Git notes without separating the + first line with an empty line from the rest of the text. #3676 + +- Made ~magit-tag-release~ more flexible and added it as a suffix of + ~magit-tag~. 2d14f84b2 + +- Bound "C-c C-o" (in addition to "C-c C-w") to ~magit-browse-thing~ for + consistency with ~org-open-at-point~'s binding. 1e1193666 + +- ~magit-copy-section-value~ now supports stripping diff markers. #3716 + +- ~magit-insert-*-branch-header~ now colorizes keywords in the message. + 98e328200 + +- ~magit-unstage~ can now unstage files that were staged using + ~--intent-to-add~. #3753 + +- ~magit-read-branch-or-commit~ now offers symbolic refnames such as + ~ORIG_HEAD~ as completion candidates. #3766 + +- ~magit-stage-modified~ and ~magit-unstage-all~ now take the log file + filter into account. #3767 + +- New command ~magit-skip-worktree~ can be used to tell Git to pretend + that the working tree version is up-to-date; ~magit-no-skip-worktree~ + does the opposite. Both commands are available from the + ~magit-gitignore~ prefix but are disabled by default. #3710 + +- ~--rebase-merges~, an option available in Git version 2.18.0 and + later, is now supported. The ~--rebase-merges~ infix of + ~magit-rebase~ is disabled by default. #3762 + +- New command ~git-rebase-break~ inserts a "break" action in the + rebase to-do sequence (available as of Git v2.20). #3762 + +- ~git-rebase-kill-line~ and the commands for changing the action of a + commit line (e.g., ~git-rebase-squash~) learned to work on all lines + selected by the region. #4172 + +- The ~--color-moved~ diff argument is supported now, but isn't + available from the diff transients by default. To enable it + use "C-x l" in those transients. #3424 + +- Added new option ~magit-revision-filter-files-on-follow~ that + controls whether a revision buffer shown from a log shares the log's + file restriction despite ~--follow~ being in the log arguments. + #3680 + +- ~magit-cherry~ is now available from the ~magit-dispatch~ prefix. + ef311f378 + +- ~magit-cherry-spinoff~ now offers the upstream as the default + starting-point. e5a2a0ac2 + +- Added new command ~magit-branch-spinout~. #3794. + +- ~magit-process-password-auth-source~ now allows the use of emails as + usernames. 05d82d501 + +- Added new option ~magit-prefer-push-default~, which controls whether + commands that configure the push-remote do so by setting the value + of ~remote.pushDefault~ or ~branch..pushRemote~. Also removed + option ~magit-remote-set-if-missing~. 07ca042b6 + +- Support for bookmarks was rewritten from scratch. #3836, cd391a035 + +- The new options ~magit-prefix-use-buffer-arguments~ and + ~magit-direct-use-buffer-arguments~ replace the old option + ~magit-use-sticky-arguments~. The default "stickiness" of arguments + has changed. #3836, 0e67ca9eb + +- Like when moving through a log, moving through a list of cherries + now automatically updates the revision or blob buffer. #3836 + +- Added new option ~magit-worktree-read-directory-name-function~. #3820 + +- Basic optional support for ~libgit2~ was added, but because so few + functions are currently implemented using that library, opting in + currently has almost no effect. #3841 + +- ~git bisect~ is now run asynchronously. #3802 + +- ~magit-bisect~ now supports specifying alternate terms. The new + infixes and suffix related to this functionality are disabled by + default. + +- ~magit-branch-or-commit-at-point~ now falls back to an abbreviated + hash instead of something like "master~2", because the latter often + leads to undesirable behavior. fd5eb5b43 + +- ~magit-toggle-buffer-lock~ is now a suffix of both ~magit-diff~ and + ~magit-log~. c09993112 + +- When invoked with a prefix argument, then ~magit-clone~ now acts as a + prefix command. If the new option ~magit-clone-always-transient~ is + non-nil, then it always acts as a prefix command. #3846 + +- Clone commands now accept repository names and similar abbreviations + in addition to complete urls. The new options ~magit-clone-name-alist~ + and ~magit-clone-url-format~ control how the translation is done. #3846 + +- When called from ~magit-dispatch~, then ~magit-diff~ and ~magit-log~ no + longer set the file limit to the file visited in the current buffer. + ccc72469e + +- ~RET~ (~magit-diff-visit-file~) on a committed change now always visits + the respective commit. Previously it did that for all commits + except the ~HEAD~ commit. This made it impossible to visit the ~HEAD~ + commit using this or a related command and also was inconsistent. + + Likewise ~RET~ on an uncommitted removal now visits ~HEAD~, the last + commit that still had those lines. Previously it visited the file + in the working tree, making it difficult to blame the previous + version of modified lines. + + Now ~C-RET~ (~magit-diff-visit-worktree~) has to be used to visit the + file in the working tree for any commit or uncommitted removals. + Setting the new option ~magit-diff-visit-avoid-head-blob~ to a non-nil + value restores the old behavior of ~magit-diff-visit-file~. #3848 + +- ~magit-diff-visit-worktree~ now does a much better job at jumping to + the correct location in the file. c9e5425cd + +- Added new command ~magit-find-file-other-frame~. 9a69c74ca + +- Renamed command ~magit-diff-visit-file-worktree~ to + ~magit-diff-visit-worktree-file~. 4f739cd35 + +- Added new commands ~magit-diff-visit-file-other-frame~, + ~magit-diff-visit-worktree-file-other-window~, and + ~magit-diff-visit-worktree-file-other-frame~. 756d61911, 6704b3248 + +- Added new option ~magit-process-prompt-functions~. #3845 + +- ~magit-find-file~ is now available from ~magit-file-dispatch~. + 9c587d458 + +- ~magit-find-file~ and related commands learned to visit a file from + the worktree or index. #3860 + +- ~magit-find-file~ and related commands learned to go to the position + in the visited file that corresponds to the position in the + previously current buffer. #3860 + +- ~magit-diff-buffer-file~ learned to visit a commit instead of a range + when appropriate. #3860 + +- ~magit-show-commit~ and ~magit-diff-buffer-file~ learned to go to the + position in the diff that corresponds to the position in the + previously current file-visiting buffer. #3860 + +- Added new command ~magit-blob-visit-file~. When visiting a blob, then + it goes to the same location in the respective file in the working + tree. #3860 + +- ~magit-add-change-log-entry{,-other-window}~ learned to extract the + file name from blob-visiting buffers. + +- ~magit-tag-release~ now runs ~git~ asynchronously. #3855 + +- When invoked with two prefix arguments, then ~magit-mode-burry-buffer~ + now also kills all other Magit buffers associated with the current + repository. #3863 + +- ~magit-branch-or-commit-at-point~ was taught about Forge pull-requests. + 9447edd12 + +- When merging a branch that corresponds to a Forge pull-request, then + the commit message is modified to contain the pull-request number. + 15331d7c0 + +- For consistency ~magit-file-rename~ now also renames buffers that + visit untracked files. #3916 + +- Additional history simplification arguments were added to the log + transients. Because only a minority of users will use those, they + were put on levels that are not shown by default. 8f8a2f1cf + +- Added new commands ~magit-assume-unchanged, ~magit-no-assume-unchanged~, + ~magit-jump-to-skip-worktree~ and ~magit-jump-to-assume-unchanged~, and + section inserter ~magit-insert-assume-unchanged-files~. 2d0de8614 ff + +- Magit buffers are now compatible with ~whitespace-mode~ (and other + modes which use font-lock). #3840 + +- Added new command ~magit-status-here~ available from file-visiting + buffers at ~C-c M-g g~. This command tries to go to the position in + the status buffer that corresponds to the position in the current + file-visiting buffer. Setting ~magit-status-goto-file-position~ to + a non-nil value causes ~magit-status~ to behave the same way. #3930 + +- Replaced ~magit-repolist-column-dirty~ with ~magit-repolist-column-flag~ + which allows specifying arbitrary flags and predicates in custom order + using ~magit-repolist-column-flag-alist~. #3936 #3937 + +- The buffer that shows a stash is now updated automatically when + moving through a list of stashes if the user added the new + ~magit-status-maybe-update-stash-buffer~ and/or + ~magit-stashes-maybe-update-stash-buffer~ to + ~magit-section-movement-hook~. #3943 + +- Added new commands ~magit-log-matching-branches~ and + ~magit-log-matching-tags~. #3958, #3983 + +- Added new option ~magit-disable-line-numbers~. #3971 + +- Added new option ~magit-log-margin-show-committer-date~. 1b9995238 + +- Added new command ~magit-worktree-move~ to allow you to move an + existing worktree to a new directory. #3978 + +- Introduced two new faces to customize the appearance of commit messages: + ~magit-diff-revision-summary~ and ~magit-diff-revision-summary-highlight~. + #3988 + +- Commands under the ~magit-gitignore~ prefix now include directories + that contain only untracked files as completion candidates. #3985 + +- Added new command ~magit-toggle-verbose-refresh~. c63ec3920 + +- Added new function ~magit-disable-section-inserter~, which can be used + to disable a section only in the current repository. This mechanism + is useful for exceptionally large repositories. #4017 + +- Added new transient prefix command ~magit-status-jump~ and turned the + existing jumper commands into suffixes. 655950f40 + +- Added new option ~magit-copy-revision-abbreviated~. #4014 + +- Added new transient prefix command ~git-commit-insert-pseudo-header~ + and turned the existing inserter commands into suffixes. e88242679 + +- Added new command ~magit-push-notes-ref~. dff0bca6f + +- The ~--irreversible-delete~ diff argument is supported now, but isn't + available from the diff transients by default. To enable it use + "C-x l" in those transients. #4056 + +- Added new command ~magit-reset-keep~. 0ea8b0ef6 + +- Added new option ~magit-reshelve-since-committer-only~. #4101 + +- Added new command ~magit-commit-absorb~ as an alternative to + ~magit-commit-autofixup~. 9423edc0b + +- Added new option ~magit-status-use-buffer-arguments~. #4046 + +- Added new command ~magit-project-status~. #4173 + +- Added new variable ~magit-process-extreme-logging~ for debugging + purposes. #4217 + +- Taught Isearch and Swiper how to expand Magit sections when the + current match is inside a hidden section and how to close sections + again. #3999 + +- Added new command ~magit-commit-absorb-modules~. 10b4bec53 + +- Added new transient command ~magit-shortlog~. #4262 + +- Added new command ~magit-generate-changelog~. c5e118111 + +- The name of the main branch is no longer hard-coded to "master". + Now we use the value of ~init.defaultBranch~ if that is set and the + named branch exists. If not, then some other names that are + commonly used for the main branch are tried as a potential fallback. + c4494ac0b + +- Added new option ~magit-diff-extra-stat-arguments~. 1bd4fe26e + +- Added support for ~git-credential-manager-core~. #4318 + +- The name of the upstream remote is no longer hard-code to "origin". + See the doc-string of function ~magit-primary-remote~ to learn how to + customize this. f883b62fe + +This release also contains numerous other improvements. + +** Fixes since v2.90.0 + +- Bumped the minimal required version of ~git-commit~ to the correct + version. e9bd33758 + +- Dropped the new "v" prefix that we started to add to release tags + starting with the previous release in places where that prefix is + undesirable. f441cf6d7 + +- Staging and unstaging submodules while ~diff.submodule~'s value is ~log~ + broke shortly before the v2.90.0 release. #3654 + +- When another window is already displaying the file buffer, then + ~magit-display-file-buffer-other-window~ did additionally display + it in the current window. #3662 + +- It was undefined whether highlighting of word-granularity + differences or of whitespace-error had higher priority. #3671 + +- The Custom type definition of ~magit-diff-adjust-tab-width~ was + broken. #3671 + +- In the log-select buffers point was no longer placed on the same + commit as was at point in the buffer from which the command was + invoked. #3674 + +- ~magit-diff-type~ falsely concluded that a diff buffer showed + unstaged changes when diffing a range where the right side resolves + to the same commit as ~HEAD~. #3666 + +- ~magit-log-trace-definition-function~ defaulted to ~which-function~, + which isn't reliable because it used Imenu, which uses a cache but + by default never invalidates. Now we use ~magit-which-function~, a + replacement that never uses an outdated cache. + +- ~magit-log-trace-definition~ didn't account for Git treating "-" + differently from, e.g., "_", leading to false-positives like + "foo-suffix" being considered a match for "foo". + +- ~magit-log-trace-definition~ didn't do the escaping that Git expects + for function names with colons. #4051 + +- A regression in ~magit-log-move-to-parent~ prevented it from doing its + job. #3682 + +- Since v2.11.0 ~magit-log-revision-headers-format~ lines in the log + output (shown via ~++header~) weren't displayed properly when + ~--graph~ was enabled. #4129 + +- ~magit-clone~ didn't run ~magit-credential-hook~. #3683 + +- ~magit-list-repositories~ failed if one of the repositories that it + tries to list is empty. #3686 + +- The summary element from ~git-commit-font-lock-keyword-1~ lost against + the elements of ~git-commit-elisp-text-mode-keywords~, causing the + summary line to lose its special appearance when a "string" or + `symbol' appears in it. + +- ~magit-split-branch-name~ did not take into account that remote names + can contain slashes. #3685 + +- ~magit-which-function~ now simply resets Imenu's cache and then calls + ~which-function~. The old approach that tried to outsmart Imenu was + broken. #3691 + +- ~magit-describe-section-briefly~ did not actually display a section + ident when called interactively, as the docstring claimed. Now it + displays the section ident, which is useful in + ~magit-status-initial-section~. + +- Section movement commands got confused by type change sections being + treated as a special kind of hunk. #3698 + +- ~x-strech-cursor~ was set globally. #3707 + +- ~magit-blame-echo~ was broken. #3720 + +- ~magit-rev-name~ sometimes returned ~nil~ even when it could return a + name and it returned, e.g., "origin/HEAD" instead of "origin/master". + 2042957a7, d500c442 + +- ~magit-insert-*-branch-header~ did not account for empty commit + messages. #3719 + +- ~magit--painted-branch-at-point~ failed in some cases, causing an + error. e7e612e3c + +- In newer Git versions the rebase list shown in the status buffer + could contain duplicated entries for the current commit. 1e1cd0e28 + +- When deleting a remote branch failed, the logic for deciding whether + to prune the local remote-tracking ref was too loose, leading to + false positives. #3650 + +- ~magit-ediff-stage~ offered untracked files as completion candidates + even though it cannot handle those. 8dd612dfb + +- Fix handling of passphrase prompts which are output with leading + carriage return, such as those produced by Openssh 8.0. #3843 + +- The default value for ~magit-view-git-manual-method~ was treated as + invalid. #3873 + +- Unlike other ~magit-*-files~ functions, ~magit-ignored-files~ returned + paths relative to the current directory instead of the top-level of + the repository. 6d3f12d58 + +- Staging a hunk applied the change to the wrong location in rare + cases where repetitive diff context prevented ~git apply~ from + finding the correct location. #3924 + +- Staging a hunk with no context now aborts, as staging a region + within such a hunk already did, to avoid unintended and confusing + results. #3924 + +- Adjusted many faces so that they continue to extend to the edge of + the window as intended. This was made necessary by a backward + incompatible change in Emacs 27. #3986 + +- The ability to stage regions from within intent-to-add files broke + for users running Git v2.19.0 or later due to a change in the + default display of these files in the diff output. #4026 + +- ~magit-stash-branch-here~ applied the stash without checking out the + new branch. d3cee7f8c + +- A regression in v2.90.0 led to ~magit-wip-mode~ committing to "/refs/heads/HEAD" rather than "/HEAD" when on a + detached head. + +- Modifying a file, marking it with a "skip-worktree" or "assume + unchanged" bit, and then modifying it again triggered a failure in + ~magit-wip-commit-worktree~. #4037 + +- ~magit-abbrev-length~ returned an incorrect result when + ~core.abbrev~ was explicitly set to "auto". + +- Calling ~magit-status~ in a repository with a corrupt Git + configuration didn't propagate the error and instead preseted the + directory as though it was uninitialized. #4337 + +- When the status buffer is not shown in any buffer but point is on + a hunk, and editing and saving the respective file causes, that + hunk to disappear or change, then Magit ended up changing point + in the file-visiting buffer. #4196 + +- Various bug fixes to + ~magit-branch-delete~ (3e73ff19d), + ~magit--{upstream,pushbranch}-suffix-predicate~ (0ce7fbbc2), + ~magit-patch-create~ (470272a0f), + ~magit--cherry-spinoff-read-args~ (add276810), + ~magit-refs--insert-cherry-commits~ (3b37e6dc1), + ~magit--{pushbranch,upstream}-suffix-predicate~ (cef3b1217), + ~magit-diff-insert-file-section~ (01cf0c165), + ~magit-insert-unpushed-to-upstream-or-recent~ (02445d6e3), + ~magit-ref-equal~ (46862d9d2), + ~magit-ref-fullname~ (66b85daea), + ~magit-insert-unpulled-from-upstream~ (0363e9bac), + ~magit-git-version~ (0abc761f5), + ~auto-revert-buffers--buffer-list-filter~ (713bd64bf), + ~magit-insert-revision-gravatar~ (1f7e84c26), + ~magit-process-unset-mode-line~ (457a685e5), + ~magit-ido-completing-read~ (f52ab7977), + ~magit-file-untrack~ (0984d77fb), + ~magit-ref-p~ (8b33bc7c7), + ~git-commit-setup~ (675b75ded), + ~magit-{,no-}skip-worktree~ (34d6ac27d), + ~magit-fetch-all~ (904bb82ca), + ~magit-branch-configure~ (7246bf291), + ~magit--maybe-update-blob-buffer~ (1d57893a6), + ~magit-...-maybe-update-...-buffer~ (8d3459b55), + ~magit-read-gpg-secret-key~ (9d68a455d), + ~magit-gitignore-in-subdir~ (8c4e8ed74), + ~magit-save-repository-buffers~ (82136796f), + ~magit-stash-drop~ (a4972766a), + ~magit-ignore-submodules-p~ (a7699f868), + ~magit-log-propertize-keywords~ (ac1ee3df5), + and then I stopped adding to this list. + +This release also contains numerous other bug fixes, typo fixes, and +documentation fixes. + +* Authors + + 1001 Jonas Bernoulli + 120 Kyle Meyer + 10 Basil L. Contovounesios + 9 Noam Postavsky + 5 Vladimir Panteleev + 4 Damien Cassou + 4 Daniel Martín + 4 Sam Cedarbaum + 4 Štěpán Němec + 3 Adam Porter + 3 Benjamin Motz + 3 Kévin Le Gouguec + 2 Alban Gruin + 2 Allen Li + 2 Bastian Beischer + 2 Clément Pit-Claudel + 2 Daniel Fleischer + 2 Evan Torrie + 2 Ingmar Sittl + 2 Leo Vivier + 2 Martin Polden + 2 Naoya Yamashita + 2 Phil Sainty + 2 Philipp Stephani + 2 Radon Rosborough + 2 Ryan C. Thompson + 2 Szunti + 2 Tassilo Horn + 2 Thierry Volpiatto + 2 Troy Hinckley + 2 zilongshanren + 1 Adam Kruszewski + 1 Adam Spiers + 1 Alexander Miller + 1 Andrew Eggenberger + 1 Andrew Psaltis + 1 Andrew Schwartzmeyer + 1 Arnau Roig Ninerola + 1 Ashlynn Anderson + 1 Ben North + 1 Brian Leung + 1 Dan Davison + 1 Danny Zhu + 1 David Ellison + 1 Dominique Quatravaux + 1 Eric + 1 Fritz Grabo + 1 Gregory Heytings + 1 Hussein Ait-Lahcen + 1 Ian Milligan + 1 Ilya Grigoriev + 1 Johann Klähn + 1 Johannes Altmanninger + 1 Jonas Galvão Xavier + 1 Jonathan Arnett + 1 Jonathan del Strother + 1 Jordan Galby + 1 Josh Elsasser + 1 Justin Guenther + 1 Keshav Kini + 1 Kevin Brubeck Unhammer + 1 Kevin J. Foley + 1 Knut Olav Bøhmer + 1 Magnus Malm + 1 Mario Rodas + 1 Martin Joerg + 1 Matthew Kraai + 1 Maxim Cournoyer + 1 Michael Griffiths + 1 Ola x Nilsson + 1 Pancho Horrillo + 1 Philipp Fehre + 1 Pritam Baral + 1 Roey Darwish Dror + 1 Sean Whitton + 1 Simon Pintarelli + 1 Steve Purcell + 1 Thomas Fini Hansen + 1 Topi Miettinen + 1 Tsuyoshi Kitamoto + 1 Vitaly Ostashov + 1 Vladimir Sedach + 1 Wojciech Siewierski + 1 Yann Herklotz + 1 Ynilu + 1 Zhu Zihao + 1 zakora diff --git a/.config/emacs/lisp/magit/docs/RelNotes/3.1.0.org b/.config/emacs/lisp/magit/docs/RelNotes/3.1.0.org new file mode 100644 index 0000000..9467c7b --- /dev/null +++ b/.config/emacs/lisp/magit/docs/RelNotes/3.1.0.org @@ -0,0 +1,58 @@ +* Magit v3.1.0 Release Notes + +Released 1st July 2021 by Jonas Bernoulli. + +I am pleased to announce the release of Magit version 3.1.0, +representing 31 commits by 4 contributors over one month. + +Also see https://emacsair.me/2021/07/01/magit-3.1. + +** Breaking changes + +- The function signature of ~magit-completing-read-multiple~ was not + compatible with that of ~completing-read-multiple~, so we deprecate + it. Use the improved ~magit-completing-read-multiple*~ instead. + #4420 + +- The description of ~magit-merge-into~ in the merge menu was changed + to "dissolve" (from "merge into"). In the future we are going to + change the key binding from "i" to "d" as well, to keep it mnemonic. + We don't make both changes at once in the hope that this makes the + transition easier for existing users. 4c096921f + +** Changes since v3.0.0 + +- Adjusted to changes to Eieio in Emacs 28. a3626277c, 54a0019f3 + +- Added new command ~magit-log-move-to-revision~. #4418 + +- ~A m~ is now also bound to ~magit-merge-squash~. Despite the name it + fits better there. 51152fdec + +** Fixes since v3.0.0 + +- Fixed ~magit-emacs-Q-command~ and ~make build~ for ELPA users. + f50c3aa56 + +- Fixed reading choice in ~magit-process-git-credential-manager-core~. + #4396 + +- ~magit-blame~ didn't account for quoted file names when parsing + output from ~git blame~. #4400 + +- A regression in v3.0.0 prevented ~magit-bisect-run~ from executing + ~git bisect run~ unless ~magit-bisect-start~ was called beforehand. + f592e367d + +- ~magit-log-select-quit~ failed to call ~magit-log-select-quit-function~. + #4423 + +- The entry for pull-requests in ~magit-list-refs-namespaces~ did not + match the ref names used by Forge for that purpose. 4c3373f9a + +* Authors + + 24 Jonas Bernoulli + 3 Kyle Meyer + 1 Siavash Askari Nasr + 1 TEC diff --git a/.config/emacs/lisp/magit/docs/RelNotes/3.2.0.org b/.config/emacs/lisp/magit/docs/RelNotes/3.2.0.org new file mode 100644 index 0000000..11f1ef4 --- /dev/null +++ b/.config/emacs/lisp/magit/docs/RelNotes/3.2.0.org @@ -0,0 +1,85 @@ +* Magit v3.2.0 Release Notes + +Released 1st August 2021 by Jonas Bernoulli. + +I am pleased to announce the release of Magit version 3.2.0, +representing 84 commits by 5 contributors over one month. + +Also see https://emacsair.me/2021/08/01/magit-3.2. + +** Changes since v3.1.0 + +- The default of ~magit-bury-buffer-function~ was changed to + ~magit-mode-quit-window~. #4412 + +- Added new option ~magit-remote-git-executable~ alongside the existing + ~magit-git-executable~. Previously the latter was used for local and + remote ~git~ processes alike, now the former specifies the executable + that is used when Tramp is involved. Using a single variable was + problematic because we had to use an absolute path on Windows for + performance reasons but that path was almost certainly wrong when + using Tramp. #4447 + +- We now use an absolute path for ~magit-git-executable~ on macOS as + well because at least for some macOS users using just the name of + the executable performs horribly. #4447 + +- The section showing openpgp output in the revision buffer is now + collapsible and starts out collapsed for good signatures or when the + certificate is missing. This hopefully makes it more appealing to + enable ~--show-signature~ (and maybe even encourages some authors to + start signing commits). 1e08ac6fd + +- A mode change or rename can now be applied (un-/staged etc.) without + also applying edits to the same file and vice-versa. #4439 + +- Many commands that act on (or default to) the commit at point now + pick that up in a few more places; when the string at point is a + known hash, on a blame chunk, and on a hunk or file inside a log. + d8d3e4813, 40ad7a25c, 402112c6e + +- The default ~magit-pop-revision-stack-format~ now include the + committer date. 1f85297a3 + +- The default ~magit-log-revision-headers-format~ now includes notes. + 33bd79fd45 + +- Added new options ~magit-repolist-sort-key~ + and ~magit-submodule-list-sort-key~. #4409 + +- Added new function ~magit-repolist-column-flags~. 35067f512 + +- Added new option ~magit-ediff-use-indirect-buffers~. #4395 + +- Added new function ~magit-process-git~. fd5cf6173 + +- Added new function ~magit-git-config-p~. 60f82a323 + +** Fixes since v3.1.0 + +- In the normal case ~magit-name-tag~ failed to return the tag. + 14170b4ea + +- ~magit-completing-read-multiple*~ tried to use a variable that is + unbound if ~helm~ isn't loaded. 29b0cb489 + +- Some push commands couldn't deal with remote and branch names that + contain the percent character. #4428 + +- ~magit-git-shortlog~ got stuck in the repository in which it was first + invoked. 384610edb + +- ~magit-commit-augment~ did not support ~--allow-empty~. bbdfd4287 + +- Squash commands didn't fully take ~--author~ into account. 02d2917c6 + +- ~magit-completing-read-multiple*~ conflicted with the ~consult~ package. + #4437 + +* Authors + + 73 Jonas Bernoulli + 6 Kyle Meyer + 2 Boruch Baum + 1 Philippe Cavalaria + 1 Toon Claes diff --git a/.config/emacs/lisp/magit/docs/RelNotes/3.2.1.org b/.config/emacs/lisp/magit/docs/RelNotes/3.2.1.org new file mode 100644 index 0000000..2573a5b --- /dev/null +++ b/.config/emacs/lisp/magit/docs/RelNotes/3.2.1.org @@ -0,0 +1,12 @@ +* Magit v3.2.1 Release Notes + +Released 6st August 2021 by Jonas Bernoulli. + +I am pleased to announce the release of Magit version 3.2.1. + +This is the first release that is available from NonGNU Elpa. It is +identical to version 3.2.0 except for dependency metadata, which had +to be changed so that this package could be released on NonGNU Elpa. + +Also see https://emacsair.me/2021/08/06/nongnu-elpa +and https://elpa.nongnu.org/nongnu/magit.html. diff --git a/.config/emacs/lisp/magit/docs/RelNotes/3.3.0.org b/.config/emacs/lisp/magit/docs/RelNotes/3.3.0.org new file mode 100644 index 0000000..47371b4 --- /dev/null +++ b/.config/emacs/lisp/magit/docs/RelNotes/3.3.0.org @@ -0,0 +1,137 @@ +* Magit v3.3.0 Release Notes + +Released 4th October 2021 by Jonas Bernoulli. + +I am pleased to announce the release of Magit version 3.3.0, +representing 88 commits by 6 contributors over two month. + +Also see https://emacsair.me/2021/10/04/magit-3.3. + +** Breaking changes + +- The last remaining alphabetic keys (both lower- and uppercase) are + now bound in ~magit-mode-map~. ~H~ to ~magit-describe-section~, ~j~ to the + new ~magit-status-quick~ (or ~magit-status-jump~ in status buffers), ~J~ + to the new ~magit-display-repository-buffer~, ~Q~ to ~magit-git-command~ + and ~Z~ to ~magit-worktree~, and once Forge is loaded, then ~N~ to + ~forge-dispatch~. (~Z~ used to be bound to ~magit-stash~, which now is + only available on ~z~.) #4259, 9bec1c54a, e401bd4d3 + +- ~I~ is now bound to ~magit-init~ instead of ~magit-gitignore~, which + continues to be available on ~i~. Users of the ~magit-imerge~ package + (which previously bound ~i~) should consult its library header for a + suggestion on how to resolve the resulting conflict. b54b537db + +** Changes since v3.2.0 + +- No longer automatically add ~--full-history~ when showing a log for a + single file that isn't being tracked anymore. #4381 + +- ~magit-stash-both~ now asks before discarding merge state. #4345 + +- Several infix arguments, which previously could only be disabled + or have a numeric value, can now also be enabled without having + an explicit numeric value. #4379 + +- Added ~-Xignore-space-change~ and ~-Xignore-all-space~ to ~magit-merge~. + Like most newly added expert arguments they have to be explicitly + [[https://docs.magit.vc/transient/Enabling-and-Disabling-Suffixes.html][revealed]]. #4387 + +- Added new command ~magit-status-quick~, which shows the status buffer + but avoids refreshing it for performance reasons. #4259 + +- Added new commands ~magit-display-repository-buffer~ (bound to ~j~ in + Magit buffers) and ~magit-switch-to-repository-buffer~ (bound to ~J~) + and variants for switching to any existing Magit buffer belonging + to the current repository. #4259 + +- Added new command ~magit-dired-am-apply-patches~ for use in Dired. + #4094. + +- Rearranged ~magit-patch~ and added a binding for ~magit-am~. 8ec3a1a21, + 8cadf302b + +- Added new command ~magit-help~ (bound to ~h~ in ~magit-dispatch~), which + simply shows Magit's Info manual. 5bba62629 + +- When listing entries for Imenu, then remove entry counts from group + titles for the benefit of third-party packages that need stable + titles. #4477 + +- Include Forge's ~pullreq~ and ~issue~ sections when listing entries for + Imenu. f4016f734 + +- Bound ~imenu~ in the ~magit-status-jump~ prefix. 678df30c3 + +- Added new transient prefix command ~magit-bundle~, which provides + support for ~git bundle~. #4392 + +- When minibuffer completion allows for a branch or a commit to be + selected and the former is preferred and thus offered as default + then, if possible, offer the commit at point as the first choice + initially accessible with ~next-history-element~. #4291 + +- Bound ~magit-refs-set-show-commit-count~ in the ~magit-show-refs~ + prefix. 2fe42f63d + +- Added new option ~magit-commit-diff-inhibit-same-window~. #4132 + +- Added support for invoking Smerge's "keep" commands when point is on + a hunk in a Magit buffer. They can be invoked using the same key + bindings as in file-visiting buffers or ~RET~, ~u~, ~b~ and ~l~. #4458 + +- Added new command ~magit-remote-unshallow~. #4480 + +- Added new option ~git-commit-use-local-message-ring~. #4503 + +** Fixes since v3.2.0 + +- Make ~magit-branch-remote-head~ and ~magit-branch-current~ fall back + to ~:inverse-video~ when the ~:box~ attribute isn't support, i.e., in + a terminal. If this change does not have any effect for you then + your theme probably changes these faces and should stop doing so. + #4206 + +- In some cases refreshing a buffer caused the cursor to jump to a + different position. #4148 + +- ~magit-convert-filename-for-git~ did not expand absolute filenames, + which is necessary because Git does not understand ~~/~. de1dc8e74 + +- ~magit-rebase~ did not enable ~--autostash~ by default but the + documentation says it does. 421be65a3 + +- ~magit-clone-read-repository~ did not convert filenames before passing + them to Git. 4aa7d2928 + +- Due to a regression in v2.90.0, ~magit-wip-log~ and + ~magit-wip-log-current~ failed to extract the previous tips of the + wip refs from the reflog (which is relevant when + ~~magit-wip-merge-branch~ is nil). c327824b0 + +- An old attempt to avoid needlessly updating section highlighting + did not actually succeed. #3976 + +- An error occurred when first showing a status buffer and + ~which-function-mode~ is enabled because that caused Imenu to collect + items at a time when that is not possible yet. #4481 + +- A change in Git v2.32.0 made it necessary to explicitly filter out + directories when committing to wip worktree refs. #4499 + +- Fixed appearance of Gravatar images by forcing their size instead + relying the service to return the promised size as advertised. + 8771401d4 + +- ~git-commit-setup~ enabled the major-mode after setting local + variables, which caused non-permanent variables to be reset. + ece2cb84d + +* Authors + + 76 Jonas Bernoulli + 8 Kyle Meyer + 1 Daniel Nagy + 1 Franklin Delehelle + 1 Jonathon McKitrick + 1 Lin Sun diff --git a/.config/emacs/lisp/magit/docs/RelNotes/4.0.0.org b/.config/emacs/lisp/magit/docs/RelNotes/4.0.0.org new file mode 100644 index 0000000..68bb6fb --- /dev/null +++ b/.config/emacs/lisp/magit/docs/RelNotes/4.0.0.org @@ -0,0 +1,532 @@ +* Magit v4.0.0 Release Notes + +Released 8th August 2024 by Jonas Bernoulli. + +I am pleased to announce the release of Magit version 4.0.0, +representing 1077 commits by 69 contributors over three years. + +Also see https://emacsair.me/2024/08/09/magit-4.0. + +** Breaking changes + +- Dropped support for Emacs 25. 7c794201c4 + +- Removed several functions, variables and variable values that were obsoleted + in past releases: + - bc18ba942f Removed ~git-commit-fill-column~, obsolete since v2.11.0 + - 6b4f7f5811 Removed ~magit-section-when~, obsolete since v2.90.0 + - a8c92cc35d Removed face aliases, obsolete since v2.12.0 and v3.0.0 + - ed8067830f Removed variables and functions obsolete since v3.3.0 + - 553968346d Removed support for obsolete ~magit-branch-rename-push-target~ values + - b47efecfe6 Removed support for obsolete %-sequence in ~magit-branch-name-format~ + +- Removed library ~magit-libgit.el~, which was only a proof-of-concept, without + Magit actually making use of it. Packagers were discouraged from including + this library in the Magit package, but many disregarded that. Because that + caused issues for many users, it had to be removed. c9fd81217c, 703dfe5812 + +- Completed the switch to a new ~magit-completing-read-multiple~ implementation. + a162b8a71e + +** Changes since v3.3.0 + +- Added many context menus, which can be invoked using the mouse or a key + (~menu~ by default) and are a great way to discover context sensitive commands. + Context menus were added in Emacs 28.1 and are disabled by default. Enable + ~context-menu-mode~ or set ~magit-section-show-context-menu-for-emacs<28~ to ~t~, + if you are still using an older release. [[https://github.com/magit/magit/issues/4645][#4645]] + +- The menu-bar menu, which was severely neglected for many years, finally got a + makeover. It no longer offers a completely random subset of Magit's features. + Now it can be used to invoke most of the commands that could also be invoked + using ~magit-dispatch~; but by means of a small furry animal. 5641d3749c + +- Rewrote Imenu support, which resulted in a few new features and much less + code. 4727dcbe22 ff + +- Move imenu and bookmark support to the independently distributed ~magit-section~ + package, so that it can be used by third-party packages, without having to + depend on the ~magit~ package. [[https://github.com/magit/magit/issues/5104][#5104]] + +- One does not simply change key bindings; at least not as a package maintainer. + ~magit-define-global-key-bindings~ used to be a boolean, now it can be set to + ~recommended~, to opt in to new easier top-level bindings, which do not require + changing modifiers mid-sequence. 8b1f599de4 + +- For the longest time (which is why I don't consider this a bug fix) toggling + a section caused point to move to the beginning of that section. Stop doing + that, unless absolutely necessary. 9d8d5e5603 + +- Added support for displaying errors that occur when washing a section. + Use that for diff and log buffers, so users can investigate what went wrong. + 78a979fde5, 2bd3db69d6, d05b1ed381, a760dd1078 + +- Massively reduced the expansion of the essential macro ~magit-insert-section~, + moving most work to new support functions. [[https://github.com/magit/magit/issues/5130][#5130]] 13e4422584..058ca81497, + ee6fbba360..e2ca80a26e, 3695493ce8..f7cba11588 + +- Avoid expensive and/or unnecessary work, including: + - 8606488578 magit-save-repository-buffers: Rev-parse only once per directory + - ff4710afa6 Deprecate magit-git-dir to avoid needlessly repeating work + - e94b6ebfdb [[https://github.com/magit/magit/issues/4900][#4900]] Record diff-type in magit-diff-mode buffers + - 6852936364 [[https://github.com/magit/magit/issues/4768][#4768]] magit-wip-mode: Speedup activation by avoiding duplicated work + - 241b327b7a [[https://github.com/magit/magit/issues/4974][#4974]] Don't use markers in log buffers + - d536ef9e21 Don't preserve visibility in log buffers + - Limit use of log graphs and signature verification. 545a64c3ee, e32cec06a4 + - d73a3b11db Record child sections in reverse in log buffers + - 6014320c3e magit-module-confirm: Use refresh cache + - fef45b274e magit-insert-child-count: Minor performance tweak + - 4ec4d0272e magit-insert-section--finish: Optimize propertizing leaf sections + - 54d969b62f magit-insert-section--finish: Optimize for leaf sections + - 5544bac955 magit-insert-section--finish: Avoid unnecessary work for root section + - ~magit-turn-on-auto-revert-mode-if-desired~ performs cheaper checks first now. + [[https://github.com/magit/magit/issues/4591][#4591]] + - For performance reasons the "margin" style sadly had to be removed from + ~magit-blame-styles~. 608242086e + +- Added new commands ~git-commit-co-developed~ and ~git-commit-insert-trailer~ + (menu) [[https://github.com/magit/magit/issues/4810][#4810]], ~git-commit-search-message-backward~ and + ~git-commit-search-message-forward~ [[https://github.com/magit/magit/issues/4537][#4537]], ~git-rebase-update-ref~ [[https://github.com/magit/magit/issues/4776][#4776]], + ~magit-back-to-indentation~ [[https://github.com/magit/magit/issues/5183][#5183]], ~magit-git-mergetool~ [[https://github.com/magit/magit/issues/4128][#4128]], + ~magit-jump-to-ignored~ 550d99d86d, ~magit-log-related~ c33ed664e6, + ~magit-mouse-toggle-section~ 949b4a47a4, ~magit-profile-refresh-buffer~ + d520ce3306, ~magit-repolist-fetch~ [[https://github.com/magit/magit/issues/4453][#4453]], ~magit-repolist-find-file-other-frame~ + [[https://github.com/magit/magit/issues/4453][#4453]], ~magit-repolist-mark~ and ~magit-repolist-unmark~ [[https://github.com/magit/magit/issues/4453][#4453]], + ~magit-smerge-keep-all~ [[https://github.com/magit/magit/issues/4756][#4756]], ~magit-stage-buffer-file~ ebd7a0635d, + ~magit-stash-push~ (menu) [[https://github.com/magit/magit/issues/4583][#4583]], ~magit-toggle-git-debug~ 2ed5a06d08, + ~magit-unstage-buffer-file~ ebd7a0635d, ~magit-update-default-branch~ 59833692ed, + and others. + + - Added new transient menu ~magit-sparse-checkout~, which provides an interface + to the ~git sparse-checkout~ command, introduced in Git v2.25. [[https://github.com/magit/magit/issues/4102][#4102]] + + - Added new command ~magit-clone-sparse~, which makes it possible to clone + a repository and then immediately enable a sparse checkout, avoiding a + checkout of the full working tree. [[https://github.com/magit/magit/issues/4102][#4102]] + + - Added new command ~magit-stash-push~, which allows specifying a list of + files to be stashed. [[https://github.com/magit/magit/issues/4583][#4583]] + + - Added new command ~magit-ediff-resolve-all~, an alternative to + ~magit-ediff-resolve-rest~ (formerly known as ~magit-ediff-resolve~). The + new option ~magit-ediff-dwim-resolve-function~ controls which is used by + ~magit-ediff-dwim~ (another new command, ~magit-git-mergetool~, can also be + used). [[https://github.com/magit/magit/issues/4348][#4348]] + + - ~magit-refresh-buffer~ is now defined as a command. 26eac2bcb0 + +- Added new infix arguments: + - Added ~--diff-merges~ to ~magit-diff~ and ~magit-diff-refresh~. [[https://github.com/magit/magit/issues/4989][#4989]] + - Added ~--ff-only~ to ~magit-pull~. f766f68f78 + - Added ~--filter~ to ~magit-clone~ (hidden by default) to support partial + cloning, a feature that is available as of Git v2.17. [[https://github.com/magit/magit/issues/4102][#4102]] + - Added ~--force-rebase~ to ~magit-rebase~. 73b44644f6 + - Added ~--force~ to ~magit-fetch~ and ~magit-pull~. [[https://github.com/magit/magit/issues/5162][#5162]] + - Added ~--ignore-date~ to ~magit-rebase~. 7f03f572d5 + - Added ~--update-refs~ to ~magit-rebase~. 2fee806a01 + +- Added new hooks ~git-commit-post-finish-hook-timeout~ [[https://github.com/magit/magit/issues/4828][#4828]], + ~magit-post-clone-hook~ [[https://github.com/magit/magit/issues/4849][#4849]], ~magit-post-create-buffer-hook~ 26eec13943, and + ~magit-wash-message-hook~ 594bd14614. + +- Added new options ~git-commit-cd-to-toplevel~ [[https://github.com/magit/magit/issues/4973][#4973]], + ~magit-ediff-dwim-resolve-function~ 5a7519fd3d, ~magit-log-color-graph-limit~ + 545a64c3ee, ~magit-log-merged-commit-count~ [[https://github.com/magit/magit/issues/4711][#4711]], + ~magit-log-show-signatures-limit~ e32cec06a4, ~magit-openpgp-default-signing-key~ + 4eed9e1a45, ~magit-process-timestamp-format~ [[https://github.com/magit/magit/issues/4920][#4920]], + ~magit-revision-insert-related-refs-display-alist~ [[https://github.com/magit/magit/issues/4885][#4885]], + ~magit-section-show-context-menu-for-emacs<28~ 0168be9366, and + ~magit-verbose-messages~ 7fbf89cb52. + +- Added new faces ~git-rebase-action~ [[https://github.com/magit/magit/issues/4544][#4544]], ~magit-branch-warning~ bf3bcbe051, and + ~magit-section-child-count~ [[https://github.com/magit/magit/issues/4599][#4599]]; and added built-in faces ~diff-refine-added~ + and ~diff-refine-removed~ to the ~magit-faces~ custom group. + +- Added new function ~git-commit-turn-on-orglink~, intended for use in + ~git-commit-setup-hook~. d122f15edd + +- ~git-commit.el~ no longer depends on ~dash~. bb7b7a4020 + +- Some repository and submodule list columns got a bit fancier. + 3f3980735f 451438dc90 + +- Refreshing a repository or submodule list buffer now restores the previous + position. 1feda0cb1c + +- Added new variable ~magit-submodule-list-predicate~. ceab3124fb + +- ~magit-diff-dwim~ uses a more useful range when showing unpushed and unpulled + changes. 9413847c1a + +- When invoked with a prefix argument, ~magit-fetch-modules~ now acts as a + transient prefix command. fd5b9eadf3 + +- ~magit-cherry-branch~ now supports using a detached HEAD as source. ff3269814c + +- ~git-commit-save-message~ now reports whether the message was actually saved. + dfe3d03a14 + +- Make use of ~with-connection-local-variables~, and for older Emacsen use a + stripped down implementation. [[https://github.com/magit/magit/issues/4568][#4568]] + +- Added some forward compatibility for SHA-256. [[https://github.com/magit/magit/issues/4585][#4585]] + +- Added ~magit-mode-bury-buffer~ to ~magit-dispatch~. 5a2624985a + +- ~magit-tag-release~ learned to extract the version string from the HEAD commit's + message. 429d5c55e8 + +- Improved version display and sorting in repository list buffers. + 53199f2dd5, 68be0584f4 + +- Added support for marking repositories in repository list buffers and acting + on the marked repositories. [[https://github.com/magit/magit/issues/4453][#4453]] + +- Improved internals of the version/feature check caches. On the user visible + side, teach ~magit-zap-caches~ to zap everything, when invoked with a prefix + argument. [[https://github.com/magit/magit/issues/4603][#4603]] + +- When blaming, neighboring chunks about the same commit are now combined into + just one chunk. [[https://github.com/magit/magit/issues/4030][#4030]] + +- Taught ~magit-diff-dwim~ about commits of submodules shown in the status buffer + of the super-repository. [[https://github.com/magit/magit/issues/4151][#4151]] + +- A cherry pick or revert can now be continued when there are unstaged changes + as long as there are no unresolved conflicts, a behavior that more closely + matches the command-line behavior. [[https://github.com/magit/magit/issues/4615][#4615]] + +- ~magit-ediff-read-files~ now tries to detect renames in one-file logs. + b32521d543 + +- Increased use of section type, keymap and binding inheritance. + 70b34f08ab + +- Depend on the Compat package, allowing me to use convenient features that were + added to Emacs over the last few years, without having to wait another few + years, until everybody has updated to a reasonably recent Emacs release. + 571b4346c1 + +- Tag messages and signatures are now turned into sections in commit buffers. + 476383fc8f + +- Work has began on making internal circular dependencies between Magit + libraries a thing of the past. + +- The help text displayed in ~git-rebase-mode~ buffers got a makeover. + 670dad14b5 ff + +- Improved the diff to be shown while committing is determined. [[https://github.com/magit/magit/issues/3246][#3246]] + +- ~magit-reverse~ is now permitted in diff buffers between HEAD and + the working tree. e94b6ebfdb [[https://github.com/magit/magit/issues/5090][#5090]] + +- Registered a ~bookmark-handler-type~ for our handler. adf5848ea7 + +- No longer exit transient while toggling margin or cycling styles. bf0ef3826b + +- ~magit-clone-url-format~ can now be configured to an alist to support servers + that employ different URL schemes. [[https://github.com/magit/magit/issues/4738][#4738]] + +- Repositories hosted on Sourcehut can now be cloned by name. [[https://github.com/magit/magit/issues/4741][#4741]] + +- 564cff8a40 [[https://github.com/magit/magit/issues/4751][#4751]] magit-diff-wash-diffstat: Improve file rename identification +- ce0746ab9f [[https://github.com/magit/magit/issues/4743][#4743]] diff: Mention when a file is a binary +- 1c51352e6f [[https://github.com/magit/magit/issues/4785][#4785]] magit-branch-delete: Improve suggested branch for checkout +- 5d6c01e293 [[https://github.com/magit/magit/issues/4767][#4767]] magit-commit-squash-internal: Restore window conf after showing diff +- 74d14c2d10 magit-log-reflog-re: Handle "rewritten during rebase" +- 2653432bb5 [[https://github.com/magit/magit/issues/4776][#4776]] git-rebase: Support update-ref action +- 161ab48520 [[https://github.com/magit/magit/issues/4810][#4810]] git-commit: Add "Co-developed-by" header +- 99d9b3008a magit-long-lived-branches: New variable +- cd6fbe2887 [[https://github.com/magit/magit/issues/4837][#4837]] magit-branch-read-args: Read another name if chosen branch exists +- 410e4583e0 [[https://github.com/magit/magit/issues/4181][#4181]] Enable navigating broken sections +- b7daf6a2ff [[https://github.com/magit/magit/issues/4905][#4905]] magit-branch-delete: Improve "also on remote?" prompt +- dd2e870b13 [[https://github.com/magit/magit/issues/4823][#4823]] magit-save-repository-buffers: Wip commit all files at once +- b2c4a26b5b [[https://github.com/magit/magit/issues/4923][#4923]] magit-diff-show-or-scroll: Also handle tags +- 85d0554f4f [[https://github.com/magit/magit/issues/4920][#4920]] Optionally display process start time in margin of process buffers +- 2f3740ab68 [[https://github.com/magit/magit/issues/4786][#4786]] If bisect was invoked with --first-parent, use it for rest log too +- 25dbf32d86 [[https://github.com/magit/magit/issues/4781][#4781]] Perform checkouts asynchronously +- 152478b01f magit-branch-or-commit-at-point: Get from unpushed/unpulled sections +- e38500b590 git-commit-header-line-format: New variable +- 09f600fdcd..ebd7a0635d Improved commands for staging and unstaging files. +- 2c2b34d7ac [[https://github.com/magit/magit/issues/4966][#4966]] magit-file-{ignore,tracked}-p: Convert filename for git +- decd5f40dd [[https://github.com/magit/magit/issues/4970][#4970]] magit-stash-pop: Use pop instead of apply +- b3f7e24616 magit-map-sections: New function +- 667deaa74e magit-stage-file: Support staging ignored files +- d46270cb65 [[https://github.com/magit/magit/issues/4990][#4990]] git-commit-setup-font-lock: Set comment-end to the empty string +- 7d4092f00b Apply stash even if "git stash apply" cannot do it +- 186414ae41 [[https://github.com/magit/magit/issues/4998][#4998]] When inserting pseudo header, always prompt with a prefix argument +- ace5ca4401 [[https://github.com/magit/magit/issues/4999][#4999]] magit--imenu-goto-function: New function +- 27099441a0 [[https://github.com/magit/magit/issues/5000][#5000]] Offer textual range at point as next history element +- ae7f5e9fb4 magit-log-refresh: No longer exit transient after any margin command +- dd14e0c3c6 [[https://github.com/magit/magit/issues/5027][#5027]] git-commit: Ignore leading comment when inserting headers +- b436ad3830 git-commit: Replace the term "(pseudo) header" with "trailer" +- 72fbb3a579 magit-stash-read-message: Provide a default instead of magic +- 51f04d6826 [[https://github.com/magit/magit/issues/5042][#5042]] magit-branch-reset: Offer commit at point as history element +- fb1a3c487e [[https://github.com/magit/magit/issues/5051][#5051]] magit-sequencer-abort: Require confirmation +- 4efecc80a6 magit-log-move-to-revision: Default to fixup target if any +- 025c48ed68 magit-section-lineage: Optionally return objects instead of types +- 8a3674b427 completion: Prevent Vertico from sorting completion candidates +- 09961f67a4 [[https://github.com/magit/magit/issues/5097][#5097]] git-commit-turn-on-flyspell: Don't check below cut-line +- 0032ffca8d magit-branch: Add global variable suffixes by default +- 8a3c1ccdda magit-section-cycle: Pivot to tab-next if there is a binding conflict +- 28bcd29db5 [[https://github.com/magit/magit/issues/5107][#5107]] magit--shell-command: Use magit-with-editor +- f49584599c Hide placeholder commands from execute-completing-read +- e37c9ea4de Make discouraged use of git-commit-mode-hook safer and more convenient +- d98e935ed7 [[https://github.com/magit/magit/issues/5134][#5134]] magit-{browse,visit}-thing: Handle raw URL links +- 22fd8f8594 git-commit: Disable auto-filling for summary line +- f3b6864969 magit-insert-heading: Add optional CHILD-COUNT argument +- 6359e5c98f magit-hack-dir-local-variables: New function +- d1e2beb866 magit-file-checkout: Support selecting a directory +- 538cb2f90b [[https://github.com/magit/magit/issues/5176][#5176]] magit-file-section-indent: New variable +- 86509cb09e magit-run-git: Return exit-code +- 1fdb30cc1a [[https://github.com/magit/magit/issues/5188][#5188]] magit-log-select: Place cursor on first non-squash commit +- eb0b81e71d [[https://github.com/magit/magit/issues/5109][#5109]] Remove obsolete advice for Tramp + +** Fixes since v3.3.0 + +- ~magit-status-quick~ wasn't autoloaded. [[https://github.com/magit/magit/issues/4519][#4519]] + +- Magit's version could not be detected if it was installed using Straight. + [[https://github.com/magit/magit/issues/4526][#4526]] + +- Automatic saving of file-visiting buffers was broken inside remote + repositories that are accessed using Tramp. [[https://github.com/magit/magit/issues/4292][#4292]] + +- Worktree commands and listing worktrees in the status buffer were broken + inside remote repositories that are accessed using Tramp. [[https://github.com/magit/magit/issues/4326][#4326]] + +- Due to a regression in v3.3.0 setting the mark did not highlight the current + and only selected section until a second section is selected. 348d9b9861 + +- A diff header added in a new Git release wasn't handled yet. [[https://github.com/magit/magit/issues/4531][#4531]] + +- Fixed calculation of gravatar image size. ecfaa325a3 + +- ~magit-branch-checkout~ refreshed the buffer before all work was done. + a14f847d97 + +- Section highlighting was not always updated when it should have, and sometimes + it was done needlessly. aba0a59611, 41fcb24761, 10b5407131 + +- ~magit-dispatch~ contained a binding that conflicted with that of + ~transient-help~. f85c4efb52 + +- ~magit-diff-wash-submodule~ didn't account for empty commit messages. [[https://github.com/magit/magit/issues/4538][#4538]] + +- Empty face definitions weren't defined properly, resulting in "rogue" faces. + a66b86d511 + +- ~magit-remote-at-point~ could return invalid values on branch sections. + 2039619696 + +- Fixed a regression in ~magit-log-maybe-update-blob-buffer~. [[https://github.com/magit/magit/issues/4552][#4552]] + +- The helper function ~magit-current-blame-chunk~ passed the directory visited by + a Dired buffer to ~git blame~, leading to some commands (e.g., ~magit-checkout~) + erroring when called from a Dired buffer. [[https://github.com/magit/magit/issues/4560][#4560]] + +- ~magit-convert-filename-for-git~ needed yet another tweak on Windows. [[https://github.com/magit/magit/issues/4557][#4557]] + +- For Helm users, calling ~magit-stash-drop~ on the "Stashes" section has been + broken since v3.0.0. [[https://github.com/magit/magit/issues/4571][#4571]] + +- ~magit-list-refs~ failed to list a poorly named ~head~ branch. [[https://github.com/magit/magit/issues/4576][#4576]] + +- ~magit-rebase~ offered arguments that aren't supported by the Git version in + use. 5e70f10566 + +- ~magit-generate-changelog~ wasn't autoloaded. [[https://github.com/magit/magit/issues/4581][#4581]] + +- Failed to specify ~:test~ when calling ~cl-set-difference~ with strings. + d899f0e7a6 + +- ~magit-section-show-child-count~ broke on commits that have no children. [[https://github.com/magit/magit/issues/4598][#4598]] + +- ~magit-fetch-modules~ offered the ~--all~ argument, but that wasn't useful. + dc11ba7b29 + +- ~magit-discard~ didn't properly handle conflicts resulting from a file being + renamed on both sides. [[https://github.com/magit/magit/issues/4225][#4225]] + +- Since v3.0.0, ~magit-pull-from-pushremote~ has failed on non-fast-forward + merges. [[https://github.com/magit/magit/issues/4604][#4604]] + +- ~magit-insert-revision-message~ got tripped up by messages that begin with a + commit hash. [[https://github.com/magit/magit/issues/4602][#4602]] + +- ~git-commit.el~ didn't always use ~magit-git-executable~, instead hard coding + "git", even if Magit is available. 77255776cb + +- ~magit-global-core.notesRef~ and ~magit-global-core.displayRef~ didn't actually + handle global value. 0f96d39834 + +- ~magit-blame--make-highlight-overlay~ put the highlighting on the wrong line. + [[https://github.com/magit/magit/issues/4620][#4620]] + +- A regression from v3.2.0 broke visiting a file when that file has a mode + change and point is on the file or the mode change section. [[https://github.com/magit/magit/issues/4623][#4623]] + +- Module sections used the wrong keymap. 94aca04dc8 + +- In-progress cherry-picks were not always recognized. [[https://github.com/magit/magit/issues/4646][#4646]] + +- Locating remote executables was broken. 4d1d00e6fa + +- The use of external diff tools was not prevented everywhere we need the + ability to feed the output back to ~git apply~. [[https://github.com/magit/magit/issues/4664][#4664]] + +- The revision syntax for matching commit message was not supported. [[https://github.com/magit/magit/issues/4662][#4662]] + +- ~magit-current-blame-chunk~ errored at eob. 437dfe95e9 + +- ~magit-revision-refresh-buffer~ could set ~magit-buffer-revision-hash~ to + something that is not a hash. 2676dddb84 + +- ~magit-tag-release~ failed to create the first release. ea1d09e0a7 + +- 84922c3997 magit-show-commit: Fix handling of current buffer's file +- 71f7d1df1d magit-diff-wash-hunk: Handle one line edge case +- 1b0474b590 [[https://github.com/magit/magit/issues/4693][#4693]] Highlight trailing whitespace on lines using dos eol style +- 4b8eab3af1 [[https://github.com/magit/magit/issues/4697][#4697]] magit-{branch-or,}commit-at-point: Only use blame chunk when blaming +- 9b48dd7e36 [[https://github.com/magit/magit/issues/4702][#4702]] Prefer 'git log --no-walk' to 'git show --no-patch' +- 64cca91341 magit-push: Fix magit-push-implicitly--desc +- 5f5e065e1e magit-list-worktrees: Always include path in returned value +- c1def98185 magit--minibuf-default-add-commit: Fix position of commit +- c92dee94e9 magit-save-repository-buffers: Handle let-bound default-directory +- 9a69e3d479 [[https://github.com/magit/magit/issues/4765][#4765]] magit-blame--make-margin-overlays: Fix beginning of each overlay +- 557ab2c062 magit-diff-wash-diff: Fix headers for "git log -L --no-prefix" +- 8158b484ae magit-list-module-paths: Ensure they are relative to top-level +- 87e68e0a8e [[https://github.com/magit/magit/issues/4803][#4803]] magit-tag-release: Fix case when no default is detected +- a3d3758b26 [[https://github.com/magit/magit/issues/4807][#4807]] magit-file-rename: Fix initial-input for destination +- 2a5815fee1 [[https://github.com/magit/magit/issues/4806][#4806]] git-commit-font-lock-keywords-1: Use more restrictive keyword regexp + +- Commands that use optional third-party Git extensions didn't consider that + extension executables may be installed in Git's exec path instead of a + directory in ~exec-path~. [[https://github.com/magit/magit/issues/4812][#4812]] + +- ~magit-show-commit~ showed the incorrect commit when called on a chunk generated + by ~magit-blame-reverse~. [[https://github.com/magit/magit/issues/4834][#4834]] + +- 2286a63974 [[https://github.com/magit/magit/issues/3624][#3624]] Fix applying changes over Tramp from Windows +- fa0997797b magit-process-filter: Suppress bogus error when aborting emacsclient +- 76fe394953 magit-log-merged: Fix incorrect calculation of distance from tip +- 6d325d90ba Revert "git-commit-setup: Enable mode after setting local variables" +- 467bb21f7d magit-commit-diff-1: Take --allow-empty into account +- 97a95f7007 [[https://github.com/magit/magit/issues/4883][#4883]] magit-revision-fill-summary-line: Use revision buffer's window width +- 8586e49d81 [[https://github.com/magit/magit/issues/4891][#4891]] magit-auto-revert-mode: Leave disabled in one more case +- 5bd6c15089 magit-save-repository-buffers: Guard against disappeared repository +- dec25b407b [[https://github.com/magit/magit/issues/4898][#4898]] magit-log-set-commit-limit: Modify copy of magit-buffer-log-args +- 1d4bf64f33 [[https://github.com/magit/magit/issues/4903][#4903]] magit-insert-remote-branches: Fix Git 2.40 compatibility +- beb3d6cae2 [[https://github.com/magit/magit/issues/4787][#4787]] magit-wash-bisect-log: Ignore '# status:' lines +- dd649baf7c [[https://github.com/magit/magit/issues/4922][#4922]] diff: Fix visiting removed lines of renamed file +- 3224b1765f [[https://github.com/magit/magit/issues/4744][#4744]] Keep cursor from getting stuck in invisible text +- 9c66514b2c [[https://github.com/magit/magit/issues/4940][#4940]] magit-restore-window-configuration: Select buffer +- 031b9fad42 [[https://github.com/magit/magit/issues/4949][#4949]] magit-display-repository-buffer: Fix doing so +- a003d3c11c [[https://github.com/magit/magit/issues/4954][#4954]] magit-clone-internal: correctly get origin value from args +- 8b3acf7473 [[https://github.com/magit/magit/issues/4962][#4962]] Fix killing process if user input is aborted +- 4ca7b95f28 magit-diff-type: Fix in logs when section isn't provided as argument +- 93d30c5459 [[https://github.com/magit/magit/issues/4976][#4976]] magit-cygwin-mount-points: Don't use cygwin hack remotely +- 027bae37ae [[https://github.com/magit/magit/issues/4988][#4988]] git-commit-setup: Fix auto-mode-alist for remote files +- 889ed3111a [[https://github.com/magit/magit/issues/4977][#4977]] Allow un-/staging binary files when whitespace is being ignored +- 7a1d503470 [[https://github.com/magit/magit/issues/5005][#5005]] git-commit-insert-header: Fix determining location +- 18d1b13675 [[https://github.com/magit/magit/issues/5006][#5006]] magit-process-finish: Avoid unnecessary magit-process-buffer call +- 3329bf0f4f magit-list-refs: Exclude all symbolic references +- 139f603cb8 [[https://github.com/magit/magit/issues/5021][#5021]] magit-hunk-section-map: Honor smerge-command-prefix again +- c6a62accc5 [[https://github.com/magit/magit/issues/5029][#5029]] magit-jump-*-pushremote: Restore functionality + +- If applying a patch series with ~git am~ failed, the status buffer incorrectly + repeated already applied patches in the list of remaining patches. [[https://github.com/magit/magit/issues/5024][#5024]] + +- b187753717 magit-insert-section-body: Ensure parent sections get extended + +- ~magit-bisect-run~ is supposed to abort if there are uncommitted + changes or if the revisions are flipped (like ~magit-bisect-start~ + does), but these checks were unintentionally dropped in Magit + v3.1.0. [[https://github.com/magit/magit/issues/5070][#5070]] + +- debb9723d9 Support staging hunks over Tramp again +- c3b7fd7dc4 [[https://github.com/magit/magit/issues/5076][#5076]] magit-status-setup-buffer: Ensure correct position when narrowed +- 8fd3cce75c magit-completing-read: Support using function as COLLECTION +- fc485bae0d [[https://github.com/magit/magit/issues/5092][#5092]] magit-insert-remote-branches: Skip HEAD if not symref +- 36be3d66ed [[https://github.com/magit/magit/issues/5102][#5102]] magit-tag-release: Use magit-run-git-with-editor +- 65ecb9c5fc Only hook up git-commit-setup-font-lock-in-buffer once mode is enabled +- 0e8f25a8d8 [[https://github.com/magit/magit/issues/5094][#5094]] elpa/elpa/magit magit--git-wash: Support commands whose non-zero status isn't an error +- faa308fccd [[https://github.com/magit/magit/issues/5122][#5122]] magit-module-confirm: Never require confirmation with prefix argument +- ea02c8e634 magit-log-buffer-file: Support using the region in blobs again +- ea0f07e549 [[https://github.com/magit/magit/issues/5158][#5158]] magit-section--enable-long-lines-shortcuts: Fix warning +- 9d4192b7b1 [[https://github.com/magit/magit/issues/5116][#5116]] Fix visiting file from buffer created with magit-diff-paths +- ad68015aa1 [[https://github.com/magit/magit/issues/5178][#5178]] magit-confirm: Directly support two rounds of prompt formatting +- f31cf79b27 [[https://github.com/magit/magit/issues/5175][#5175]] magit-parse-git-async: Discard stderr for now + +* Authors + + 899 Jonas Bernoulli + 78 Kyle Meyer + 7 Nacho Barrientos + 5 Basil L. Contovounesios + 4 Andrey Smirnov + 4 Damien Cassou + 4 Park Zhou + 4 Phil Sainty + 4 Stefan Kangas + 3 Daniel Mendler + 2 Aaron L. Zeng + 2 Alex Kreisher + 2 Ben North + 2 Brennan Vincent + 2 Martin Joerg + 2 Nicholas Vollmer + 2 ziggy + 1 Adam Jones + 1 Adam Porter + 1 Allen Li + 1 Andrew Zipperer + 1 Angel de Vicente + 1 Arialdo Martini + 1 Bastian Beranek + 1 Ben Zanin + 1 Brian Leung + 1 Cameron Chaparro + 1 Christian Tietze + 1 Christopher Carlile + 1 Daanturo + 1 Dan Kessler + 1 Daniel Martín + 1 Ellis Kenyo + 1 Eugene Mikhaylov + 1 Eyal Soha + 1 Frédéric Giquel + 1 Greg Steuck + 1 Géza Herman + 1 JD Smith + 1 Jean-Louis Giordano + 1 Jeremy Sowden + 1 Johannes Maier + 1 Jorge Israel Peña + 1 Li Chen + 1 Lin Sun + 1 Lénaïc Huard + 1 Magnar Sveen + 1 Markus Beppler + 1 Matt Beshara + 1 Ola Nilsson + 1 Paul Pogonyshev + 1 Philipp Stephani + 1 Pieter van Oostrum + 1 Pratyush Yadav + 1 Rahul Rameshbabu + 1 Robert Irelan + 1 Roland Marchand + 1 Ron Parker + 1 Sean Allred + 1 Sean Farley + 1 Sean Whitton + 1 Shuguang Sun + 1 StrawberryTea + 1 Ulrich Müller + 1 Vladimir Ivanov + 1 Waqar Hameed + 1 dependabot[bot] + 1 hokomo + 1 shoefone diff --git a/.config/emacs/lisp/magit/docs/htmlxref.cnf b/.config/emacs/lisp/magit/docs/htmlxref.cnf new file mode 100644 index 0000000..cc394c0 --- /dev/null +++ b/.config/emacs/lisp/magit/docs/htmlxref.cnf @@ -0,0 +1,42 @@ +# https://www.gnu.org/software/texinfo/manual/texinfo/html_node/HTML-Xref-Configuration.html + +EMACS = https://www.gnu.org/software/emacs/manual + +auth mono ${EMACS}/html_mono/auth.html +auth node ${EMACS}/html_node/auth/ + +ediff mono ${EMACS}/html_mono/ediff.html +ediff node ${EMACS}/html_node/ediff/ + +elisp mono ${EMACS}/html_mono/elisp.html +elisp node ${EMACS}/html_node/elisp/ + +emacs mono ${EMACS}/html_mono/emacs.html +emacs node ${EMACS}/html_node/emacs/ + + +MAGIT = https://docs.magit.vc + +forge mono ${MAGIT}/forge.html +forge node ${MAGIT}/forge/ + +ghub mono ${MAGIT}/ghub.html +ghub node ${MAGIT}/ghub/ + +magit mono ${MAGIT}/magit.html +magit node ${MAGIT}/magit/ + +transient mono ${MAGIT}/transient.html +transient node ${MAGIT}/transient/ + +with-editor mono ${MAGIT}/with-editor.html +with-editor node ${MAGIT}/with-editor/ + + +MIRROR = https://emacsmirror.net/manual + +borg mono ${MIRROR}/borg.html +borg node ${MIRROR}/borg/ + +epkg mono ${MIRROR}/epkg.html +epkg node ${MIRROR}/epkg/ diff --git a/.config/emacs/lisp/magit/docs/magit-section.org b/.config/emacs/lisp/magit/docs/magit-section.org new file mode 100644 index 0000000..a731113 --- /dev/null +++ b/.config/emacs/lisp/magit/docs/magit-section.org @@ -0,0 +1,309 @@ +#+title: Magit-Section Developer Manual +:PREAMBLE: +#+author: Jonas Bernoulli +#+email: emacs.magit@jonas.bernoulli.dev +#+date: 2015-{{{year}}} + +#+texinfo_dir_category: Emacs +#+texinfo_dir_title: Magit-Section: (magit-section). +#+texinfo_dir_desc: Use Magit sections in your own packages. +#+subtitle: for version 4.5.0 + +#+setupfile: .orgconfig + +This package implements the main user interface of Magit — the +collapsible sections that make up its buffers. This package used +to be distributed as part of Magit but how it can also be used by +other packages that have nothing to do with Magit or Git. + +To learn more about the section abstraction and available commands and +user options see [[info:magit#Sections]]. This manual documents how you +can use sections in your own packages. + +#+texinfo: @noindent +This manual is for Magit-Section version 4.5.0. + +#+texinfo: @insertcopying +:END: +* Introduction + +This package implements the main user interface of Magit — the +collapsible sections that make up its buffers. This package used +to be distributed as part of Magit but how it can also be used by +other packages that have nothing to do with Magit or Git. + +To learn more about the section abstraction and available commands +and user options see [[info:magit#Sections]]. This manual documents +how you can use sections in your own packages. + +When the documentation leaves something unaddressed, then please +consider that Magit uses this library extensively and search its +source for suitable examples before asking me for help. Thanks! + +* Creating Sections + +- Macro: magit-insert-section [name] (type &optional value hide) &rest body :: + + Create a section object of type CLASS, storing VALUE in its + ~value~ slot, and insert the section at point. CLASS is a + subclass of `magit-section' or has the form ~(eval FORM)~, in + which case FORM is evaluated at runtime and should return a + subclass. In other places a sections class is often referred + to as its "type". + + Many commands behave differently depending on the class of the + current section and sections of a certain class can have their + own keymap, which is specified using the `keymap' class slot. + The value of that slot should be a variable whose value is a + keymap. + + For historic reasons Magit and Forge in most cases use symbols + as CLASS that don't actually identify a class and that lack the + appropriate package prefix. This works due to some undocumented + kludges, which are not available to other packages. + + When optional HIDE is non-~nil~ collapse the section body by + default, i.e., when first creating the section, but not when + refreshing the buffer. Else expand it by default. This can be + overwritten using ~magit-section-set-visibility-hook~. When a + section is recreated during a refresh, then the visibility of + predecessor is inherited and HIDE is ignored (but the hook is + still honored). + + BODY is any number of forms that actually insert the section's + heading and body. Optional NAME, if specified, has to be a + symbol, which is then bound to the object of the section being + inserted. + + Before BODY is evaluated the ~start~ of the section object is set + to the value of `point' and after BODY was evaluated its ~end~ is + set to the new value of ~point~; BODY is responsible for moving + ~point~ forward. + + If it turns out inside BODY that the section is empty, then + ~magit-cancel-section~ can be used to abort and remove all traces + of the partially inserted section. This can happen when creating + a section by washing Git's output and Git didn't actually output + anything this time around. + +- Function: magit-insert-heading [child-count] &rest args :: + + Insert the heading for the section currently being inserted. + + This function should only be used inside ~magit-insert-section~. + + When called without any arguments, then just set the ~content~ + slot of the object representing the section being inserted to + a marker at ~point~. The section should only contain a single + line when this function is used like this. + + When called with arguments ARGS, which have to be strings, or + ~nil~, then insert those strings at point. The section should not + contain any text before this happens and afterwards it should + again only contain a single line. If the ~face~ property is set + anywhere inside any of these strings, then insert all of them + unchanged. Otherwise use the `magit-section-heading' face for + all inserted text. + + The ~content~ property of the section object is the end of the + heading (which lasts from ~start~ to ~content~) and the beginning + of the the body (which lasts from ~content~ to ~end~). If the + value of ~content~ is ~nil~, then the section has no heading and + its body cannot be collapsed. If a section does have a heading, + then its height must be exactly one line, including a trailing + newline character. This isn't enforced, you are responsible for + getting it right. The only exception is that this function does + insert a newline character if necessary. + + If provided, optional CHILD-COUNT must evaluate to an integer or + boolean. If ~t~, then the count is determined once the children have been + inserted, using ~magit-insert-child-count~ (which see). For historic + reasons, if the heading ends with ":", the count is substituted for + that, at this time as well. If ~magit-section-show-child-count~ is ~nil~, + no counts are inserted + +- Macro: magit-insert-section-body &rest body :: + + Use BODY to insert the section body, once the section is expanded. + If the section is expanded when it is created, then this is + like ~progn~. Otherwise BODY isn't evaluated until the section + is explicitly expanded. + +- Function: magit-cancel-section :: + + Cancel inserting the section that is currently being inserted. + Remove all traces of that section. + +- Function: magit-wash-sequence function :: + + Repeatedly call FUNCTION until it returns ~nil~ or the end of the + buffer is reached. FUNCTION has to move point forward or return + ~nil~. + +* Core Functions + +- Function: magit-current-section :: + + Return the section at point or where the context menu was invoked. + When using the context menu, return the section that the user + clicked on, provided the current buffer is the buffer in which + the click occurred. Otherwise return the section at point. + +- Function magit-section-at &optional position :: + + Return the section at POSITION, defaulting to point. Default to + point even when the context menu is used. + +- Function: magit-section-ident section :: + + Return an unique identifier for SECTION. The return value has the + form ~((TYPE . VALUE)...)~. + +- Function: magit-section-ident-value value :: + + Return a constant representation of VALUE. + + VALUE is the value of a ~magit-section~ object. If that is an + object itself, then that is not suitable to be used to identify + the section because two objects may represent the same thing but + not be equal. If possible a method should be added for such + objects, which returns a value that is equal. Otherwise the + catch-all method is used, which just returns the argument + itself. + +- Function: magit-get-section ident &optional root :: + + Return the section identified by IDENT. + IDENT has to be a list as returned by ~magit-section-ident~. + If optional ROOT is non-~nil~, then search in that section tree + instead of in the one whose root ~magit-root-section~ is. + +- Function: magit-section-lineage section &optional raw :: + + Return the lineage of SECTION. + If optional RAW is non-~nil~, return a list of section objects, + beginning with SECTION, otherwise return a list of section types. + +- Function: magit-section-content-p section :: + + Return non-~nil~ if SECTION has content or an unused washer function. + +The next two functions are replacements for the Emacs functions that +have the same name except for the ~magit-~ prefix. Like +~magit-current-section~ they do not act on point, the cursors position, +but on the position where the user clicked to invoke the context menu. + +If your package provides a context menu and some of its commands act +on the "thing at point", even if just as a default, then use the +prefixed functions to teach them to instead use the click location +when appropriate. + +- Function magit-point :: + + Return point or the position where the context menu was invoked. + When using the context menu, return the position the user clicked + on, provided the current buffer is the buffer in which the click + occurred. Otherwise return the same value as ~point~. + +- Function magit-thing-at-point thing &optional no-properties :: + + Return the THING at point or where the context menu was invoked. + When using the context menu, return the thing the user clicked + on, provided the current buffer is the buffer in which the click + occurred. Otherwise return the same value as ~thing-at-point~. + For the meaning of THING and NO-PROPERTIES see that function. + +* Matching Functions + +- Function: magit-section-match condition &optional (section (magit-current-section)) :: + + Return ~t~ if SECTION matches CONDITION. + + SECTION defaults to the section at point. If SECTION is not + specified and there also is no section at point, then return + ~nil~. + + CONDITION can take the following forms: + + - ~(CONDITION...)~ matches if any of the CONDITIONs matches. + - ~[CLASS...]~ matches if the section's class is the same + as the first CLASS or a subclass of that; + the section's parent class matches the + second CLASS; and so on. + + - ~[* CLASS...]~ matches sections that match [CLASS...] and + also recursively all their child sections. + - ~CLASS~ matches if the section's class is the same + as CLASS or a subclass of that; regardless + of the classes of the parent sections. + + Each CLASS should be a class symbol, identifying a class that + derives from ~magit-section~. For backward compatibility CLASS + can also be a "type symbol". A section matches such a symbol + if the value of its ~type~ slot is ~eq~. If a type symbol has + an entry in ~magit--section-type-alist~, then a section also + matches that type if its class is a subclass of the class that + corresponds to the type as per that alist. + + Note that it is not necessary to specify the complete section + lineage as printed by ~magit-describe-section-briefly~, unless + of course you want to be that precise. + +- Function: magit-section-value-if condition &optional section :: + + If the section at point matches CONDITION, then return its value. + + If optional SECTION is non-~nil~ then test whether that matches + instead. If there is no section at point and SECTION is ~nil~, + then return ~nil~. If the section does not match, then return + ~nil~. + + See ~magit-section-match~ for the forms CONDITION can take. + +- Macro: magit-section-case &rest clauses :: + + Choose among clauses on the type of the section at point. + + Each clause looks like ~(CONDITION BODY...)~. The type of the + section is compared against each CONDITION; the BODY forms of the + first match are evaluated sequentially and the value of the last + form is returned. Inside BODY the symbol ~it~ is bound to the + section at point. If no clause succeeds or if there is no + section at point, return ~nil~. + + See ~magit-section-match~ for the forms CONDITION can take. + Additionally a CONDITION of ~t~ is allowed in the final clause, and + matches if no other CONDITION match, even if there is no section + at point. + +* Copying +:PROPERTIES: +:COPYING: t +:END: + +#+begin_quote +Copyright (C) 2015-{{{year}}} Jonas Bernoulli + +You can redistribute this document and/or modify it under the terms +of the GNU General Public License as published by the Free Software +Foundation, either version 3 of the License, or (at your option) any +later version. + +This document is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +General Public License for more details. +#+end_quote + +# LocalWords: ARGS CONDITIONs EVAL Git Git's IDENT +# LocalWords: LocalWords MERCHANTABILITY Magit Makefile +# LocalWords: alist eval featurep ident keymap magit ol +# LocalWords: runtime src texinfo utils + +# IMPORTANT: Also update ORG_ARGS and ORG_EVAL in the Makefile. +# Local Variables: +# eval: (require 'magit-base nil t) +# eval: (require 'ol-man nil t) +# indent-tabs-mode: nil +# org-src-preserve-indentation: nil +# End: diff --git a/.config/emacs/lisp/magit/docs/magit.org b/.config/emacs/lisp/magit/docs/magit.org new file mode 100644 index 0000000..62912c2 --- /dev/null +++ b/.config/emacs/lisp/magit/docs/magit.org @@ -0,0 +1,9641 @@ +#+title: Magit User Manual +:PREAMBLE: +#+author: Jonas Bernoulli +#+email: emacs.magit@jonas.bernoulli.dev +#+date: 2015-{{{year}}} + +#+texinfo_dir_category: Emacs +#+texinfo_dir_title: Magit: (magit). +#+texinfo_dir_desc: Using Git from Emacs with Magit. +#+subtitle: for version 4.5.0 + +#+setupfile: .orgconfig + +# Emacs on GNU ELPA build server is too old, so all "man:" links +# will be broken, but this at least allows us to generate the manual. +#+options: broken-links:mark + +Magit is an interface to the version control system Git, implemented +as an Emacs package. Magit aspires to be a complete Git porcelain. +While we cannot (yet) claim that Magit wraps and improves upon each +and every Git command, it is complete enough to allow even experienced +Git users to perform almost all of their daily version control tasks +directly from within Emacs. While many fine Git clients exist, only +Magit and Git itself deserve to be called porcelains. + +#+texinfo: @noindent +This manual is for Magit version 4.5.0. + +#+texinfo: @insertcopying +:END: +* Introduction + +Magit is an interface to the version control system Git, implemented +as an Emacs package. Magit aspires to be a complete Git porcelain. +While we cannot (yet) claim that Magit wraps and improves upon each +and every Git command, it is complete enough to allow even experienced +Git users to perform almost all of their daily version control tasks +directly from within Emacs. While many fine Git clients exist, only +Magit and Git itself deserve to be called porcelains. + +Staging and otherwise applying changes is one of the most important +features in a Git porcelain and here Magit outshines anything else, +including Git itself. Git's own staging interface (~git add --patch~) +is so cumbersome that many users only use it in exceptional cases. +In Magit staging a hunk or even just part of a hunk is as trivial as +staging all changes made to a file. + +The most visible part of Magit's interface is the status buffer, which +displays information about the current repository. Its content is +created by running several Git commands and making their output +actionable. Among other things, it displays information about the +current branch, lists unpulled and unpushed changes and contains +sections displaying the staged and unstaged changes. That might sound +noisy, but, since sections are collapsible, it's not. + +To stage or unstage a change one places the cursor on the change and +then types ~s~ or ~u~. The change can be a file or a hunk, or when the +region is active (i.e., when there is a selection) several files or +hunks, or even just part of a hunk. The change or changes that these +commands - and many others - would act on are highlighted. + +Magit also implements several other "apply variants" in addition to +staging and unstaging. One can discard or reverse a change, or +apply it to the working tree. Git's own porcelain only supports this +for staging and unstaging and you would have to do something like ~git +diff ... | ??? | git apply ...~ to discard, revert, or apply a single +hunk on the command line. In fact that's exactly what Magit does +internally (which is what lead to the term "apply variants"). + +Magit isn't just for Git experts, but it does assume some prior +experience with Git as well as Emacs. That being said, many users +have reported that using Magit was what finally taught them what Git +is capable of and how to use it to its fullest. Other users +wished they had switched to Emacs sooner so that they would have +gotten their hands on Magit earlier. + +While one has to know the basic features of Emacs to be able to make +full use of Magit, acquiring just enough Emacs skills doesn't take +long and is worth it, even for users who prefer other editors. Vim +users are advised to give [[https://github.com/emacs-evil/evil][Evil]], the "Extensible VI Layer for Emacs", +and [[https://github.com/syl20bnr/spacemacs][Spacemacs]], an "Emacs starter-kit focused on Evil" a try. + +Magit provides a consistent and efficient Git porcelain. After a +short learning period, you will be able to perform most of your daily +version control tasks faster than you would on the command line. You +will likely also start using features that seemed too daunting in the +past. + +Magit fully embraces Git. It exposes many advanced features using a +simple but flexible interface instead of only wrapping the trivial +ones like many GUI clients do. Of course Magit supports logging, +cloning, pushing, and other commands that usually don't fail in +spectacular ways; but it also supports tasks that often cannot be +completed in a single step. Magit fully supports tasks such as +merging, rebasing, cherry-picking, reverting, and blaming by not only +providing a command to initiate these tasks but also by displaying +context sensitive information along the way and providing commands +that are useful for resolving conflicts and resuming the sequence +after doing so. + +Magit wraps and in many cases improves upon at least the following Git +porcelain commands: ~add~, ~am~, ~bisect~, ~blame~, ~branch~, ~checkout~, ~cherry~, +~cherry-pick~, ~clean~, ~clone~, ~commit~, ~config~, ~describe~, ~diff~, ~fetch~, +~format-patch~, ~init~, ~log~, ~merge~, ~merge-tree~, ~mv~, ~notes~, ~pull~, ~rebase~, +~reflog~, ~remote~, ~request-pull~, ~reset~, ~revert~, ~rm~, ~show~, ~stash~, +~submodule~, ~subtree~, ~tag~, and ~worktree.~ Many more Magit porcelain +commands are implemented on top of Git plumbing commands. + +* Installation + +Magit can be installed using Emacs' package manager or manually from +its development repository. + +** Installing from Melpa + +Magit is available from Melpa and Melpa-Stable. If you haven't used +Emacs' package manager before, then it is high time you familiarize +yourself with it by reading the documentation in the Emacs manual, see +[[info:emacs#Packages]]. Then add one of the archives to +~package-archives~: + +- To use Melpa: + +#+begin_src emacs-lisp + (require 'package) + (add-to-list 'package-archives + '("melpa" . "https://melpa.org/packages/") t) +#+end_src + +- To use Melpa-Stable: + +#+begin_src emacs-lisp + (require 'package) + (add-to-list 'package-archives + '("melpa-stable" . "https://stable.melpa.org/packages/") t) +#+end_src + +Once you have added your preferred archive, you need to update the +local package list using: + +#+begin_example + M-x package-refresh-contents RET +#+end_example + +Once you have done that, you can install Magit and its dependencies +using: + +#+begin_example + M-x package-install RET magit RET +#+end_example + +Now see [[*Post-Installation Tasks]]. + +** Installing from the Git Repository + +Magit depends on the ~compat~, ~cond-let~, ~llama~, ~seq~ (the built-in version +is enough when using Emacs >= 29.1), ~transient~ and ~with-editor~ libraries +which are available from Melpa and Melpa-Stable. Install them using +~M-x package-install RET RET~. Of course you may also install +them manually from their repository. + +Then clone the Magit repository: + +#+begin_src shell-script + $ git clone https://github.com/magit/magit.git ~/.emacs.d/site-lisp/magit + $ cd ~/.emacs.d/site-lisp/magit +#+end_src + +Then compile the libraries and generate the info manuals: + +#+begin_src shell-script + $ make +#+end_src + +If you haven't installed ~compat~, ~cond-let~, ~llama~, ~seq~ +(only for Emacs 28), ~transient~ and ~with-editor~ from Melpa, or at +~/path/to/magit/../~, then you have to tell ~make~ where to find +them. To do so create the file ~/path/to/magit/config.mk~ with the +following content before running ~make~: + +#+begin_src makefile + LOAD_PATH = -L ~/.emacs.d/site-lisp/magit/lisp + LOAD_PATH += -L ~/.emacs.d/site-lisp/compat + LOAD_PATH += -L ~/.emacs.d/site-lisp/cond-let + LOAD_PATH += -L ~/.emacs.d/site-lisp/llama + LOAD_PATH += -L ~/.emacs.d/site-lisp/seq + LOAD_PATH += -L ~/.emacs.d/site-lisp/transient/lisp + LOAD_PATH += -L ~/.emacs.d/site-lisp/with-editor/lisp +#+end_src + +Finally add this to your init file: + +#+begin_src emacs-lisp + (add-to-list 'load-path "~/.emacs.d/site-lisp/magit/lisp") + (require 'magit) + + (with-eval-after-load 'info + (info-initialize) + (add-to-list 'Info-directory-list "~/.emacs.d/site-lisp/magit/docs/")) +#+end_src + +Of course if you installed the dependencies manually as well, then +you have to tell Emacs about them too, by prefixing the above with: + +#+begin_src emacs-lisp + (add-to-list 'load-path "~/.emacs.d/site-lisp/compat") + (add-to-list 'load-path "~/.emacs.d/site-lisp/cond-let") + (add-to-list 'load-path "~/.emacs.d/site-lisp/llama") + (add-to-list 'load-path "~/.emacs.d/site-lisp/seq") + (add-to-list 'load-path "~/.emacs.d/site-lisp/transient/lisp") + (add-to-list 'load-path "~/.emacs.d/site-lisp/with-editor") +#+end_src + +Note that you have to add the ~lisp~ subdirectory to the ~load-path~, not +the top-level of the repository, and that elements of ~load-path~ should +not end with a slash, while those of ~Info-directory-list~ should. + +Instead of requiring the feature ~magit~, you could load just the +autoload definitions, by loading the file ~magit-autoloads.el~. + +#+begin_src emacs-lisp + (load "/path/to/magit/lisp/magit-autoloads") +#+end_src + +Instead of running Magit directly from the repository by adding that +to the ~load-path~, you might want to instead install it in some other +directory using ~sudo make install~ and setting ~load-path~ accordingly. + +To update Magit use: + +#+begin_src shell-script + $ git pull + $ make +#+end_src + +At times it might be necessary to run ~make clean all~ instead. + +To view all available targets use ~make help~. + +Now see [[*Post-Installation Tasks]]. + +** Post-Installation Tasks + +After installing Magit you should verify that you are indeed using the +Magit, Git, and Emacs releases you think you are using. It's best to +restart Emacs before doing so, to make sure you are not using an +outdated value for ~load-path~. + +#+begin_example + M-x magit-version RET +#+end_example + +should display something like + +#+begin_example + Magit 2.8.0, Git 2.10.2, Emacs 25.1.1, gnu/linux +#+end_example + +Then you might also want to read about options that many users likely +want to customize. See [[*Essential Settings]]. + +To be able to follow cross references to Git manpages found in this +manual, you might also have to manually install the ~gitman~ info manual, +or advice ~Info-follow-nearest-node~ to instead open the actual manpage. +See [[*How to install the gitman info manual?]]. + +If you are completely new to Magit then see [[*Getting Started]]. + +If you run into problems, then please see the [[*FAQ]]. Also see the +[[*Debugging Tools]]. + +And last but not least please consider making a donation, to ensure +that I can keep working on Magit. See https://magit.vc/donate. +for various donation options. + +* Getting Started + +This short tutorial describes the most essential features that many +Magitians use on a daily basis. It only scratches the surface but +should be enough to get you started. + +IMPORTANT: It is safest if you clone some repository just for this +tutorial. Alternatively you can use an existing local repository, but +if you do that, then you should commit all uncommitted changes before +proceeding. + +Type ~C-x g~ to display information about the current Git repository in +a dedicated buffer, called the status buffer. + +Most Magit commands are commonly invoked from the status buffer. It +can be considered the primary interface for interacting with Git using +Magit. Many other Magit buffers may exist at a given time, but they +are often created from this buffer. + +Depending on what state your repository is in, this buffer may contain +sections titled "Staged changes", "Unstaged changes", "Unmerged into +origin/master", "Unpushed to origin/master", and many others. + +Since we are starting from a safe state, which you can easily return +to (by doing a ~git reset --hard PRE-MAGIT-STATE~), there currently are +no staged or unstaged changes. Edit some files and save the changes. +Then go back to the status buffer, while at the same time refreshing +it, by typing ~C-x g~. (When the status buffer, or any Magit buffer for +that matter, is the current buffer, then you can also use just ~g~ to +refresh it). + +Move between sections using ~p~ and ~n~. Note that the bodies of some +sections are hidden. Type ~TAB~ to expand or collapse the section at +point. You can also use ~C-tab~ to cycle the visibility of the current +section and its children. Move to a file section inside the section +named "Unstaged changes" and type ~s~ to stage the changes you have made +to that file. That file now appears under "Staged changes". + +Magit can stage and unstage individual hunks, not just complete files. +Move to the file you have just staged, expand it using ~TAB~, move to +one of the hunks using ~n~, and unstage just that by typing ~u~. Note how +the staging (~s~) and unstaging (~u~) commands operate on the change at +point. Many other commands behave the same way. + +You can also un-/stage just part of a hunk. Inside the body of a hunk +section (move there using ~C-n~), set the mark using ~C-SPC~ and move down +until some added and/or removed lines fall inside the region but not +all of them. Again type ~s~ to stage. + +It is also possible to un-/stage multiple files at once. Move to a +file section, type ~C-SPC~, move to the next file using ~n~, and then ~s~ to +stage both files. Note that both the mark and point have to be on the +headings of sibling sections for this to work. If the region looks +like it does in other buffers, then it doesn't select Magit sections +that can be acted on as a unit. + +And then of course you want to commit your changes. Type ~c~. This +shows the available commit commands and arguments in a buffer at the +bottom of the frame. Each command and argument is prefixed with the +key that invokes/sets it. Do not worry about this for now. We want +to create a "normal" commit, which is done by typing ~c~ again. + +Now two new buffers appear. One is for writing the commit message, +the other shows a diff with the changes that you are about to +commit. Write a message and then type ~C-c C-c~ to actually create +the commit. + +You probably don't want to push the commit you just created because +you just committed some random changes, but if that is not the case +you could push it by typing ~P~ to show all the available push commands +and arguments and then ~p~ to push to a branch with the same name as the +local branch onto the remote configured as the push-remote. (If the +push-remote is not configured yet, then you would first be prompted +for the remote to push to.) + +So far we have mentioned the commit and push menu commands. +These are probably among the menus you will be using the most, but +many others exist. To show a menu that lists all other menus (as well +as the various apply commands and some other essential commands), type +~h~. Try a few. (Such menus are also called "transient prefix +commands" or just "transients".) + +The key bindings in that menu correspond to the bindings in Magit +buffers, including but not limited to the status buffer. So you could +type ~h d~ to bring up the diff menu, but once you remember that "d" +stands for "diff", you would usually do so by just typing ~d~. + +This "prefix of prefixes" is useful even once you have memorized all +the bindings, as it can provide easy access to Magit commands from +non-Magit buffers. So, by default, it is globally bound to ~C-x M-g~. + +A similar menu featuring (for the most part) commands that act on just +the file being visited in the current buffer, is globally bound to ~C-c +M-g~. That binding can also be used in buffers, which do not visit a +file, but then only a subset of the commands is available. + +The global key bindings mentioned in the previous two paragraphs are +quite inconvenient. We recommend using ~C-c g~ and ~C-c f~ instead, but +cannot use those key sequences by default because they are strictly +reserved for bindings added by the user. See [[*Global Bindings]], if you +want to explicitly opt-in to the recommended key bindings. + +Magit also provides context menus and other mouse commands, see [[*Mouse +Support]]. + +It is not necessary that you do so now, but if you stick with Magit, +then it is highly recommended that you read the next section too. + +* Interface Concepts +** Modes and Buffers + +Magit provides several major-modes. For each of these modes there +usually exists only one buffer per repository. Separate modes and +thus buffers exist for commits, diffs, logs, and some other things. + +Besides these special purpose buffers, there also exists an overview +buffer, called the *status buffer*. It's usually from this buffer that +the user invokes Git commands, or creates or visits other buffers. + +In this manual we often speak about "Magit buffers". By that we mean +buffers whose major-modes derive from ~magit-mode~. + +- Key: M-x magit-toggle-buffer-lock :: + + This command locks the current buffer to its value or if the buffer + is already locked, then it unlocks it. + + Locking a buffer to its value prevents it from being reused to + display another value. The name of a locked buffer contains its + value, which allows telling it apart from other locked buffers and + the unlocked buffer. + + Not all Magit buffers can be locked to their values; for example, it + wouldn't make sense to lock a status buffer. + + There can only be a single unlocked buffer using a certain + major-mode per repository. So when a buffer is being unlocked and + another unlocked buffer already exists for that mode and repository, + then the former buffer is instead deleted and the latter is + displayed in its place. + +*** Switching Buffers + +- Function: magit-display-buffer buffer &optional display-function :: + + This function is a wrapper around ~display-buffer~ and is used to + display any Magit buffer. It displays BUFFER in some window and, + unlike ~display-buffer~, also selects that window, provided + ~magit-display-buffer-noselect~ is ~nil~. It also runs the hooks + mentioned below. + + If optional DISPLAY-FUNCTION is non-~nil~, then that is used to + display the buffer. Usually that is ~nil~ and the function specified + by ~magit-display-buffer-function~ is used. + +- Variable: magit-display-buffer-noselect :: + + When this is non-~nil~, then ~magit-display-buffer~ only displays the + buffer but forgoes also selecting the window. This variable should + not be set globally, it is only intended to be let-bound, by code + that automatically updates "the other window". This is used for + example when the revision buffer is updated when you move inside the + log buffer. + +- User Option: magit-display-buffer-function :: + + The function specified here is called by ~magit-display-buffer~ with + one argument, a buffer, to actually display that buffer. This + function should call ~display-buffer~ with that buffer as first and a + list of display actions as second argument. + + Magit provides several functions, listed below, that are suitable + values for this option. If you want to use different rules, then a + good way of doing that is to start with a copy of one of these + functions and then adjust it to your needs. + + Instead of using a wrapper around ~display-buffer~, that function + itself can be used here, in which case the display actions have to + be specified by adding them to ~display-buffer-alist~ instead. + + To learn about display actions, see [[info:elisp#Choosing Window]]. + +- Function: magit-display-buffer-traditional buffer :: + + This function is the current default value of the option + ~magit-display-buffer-function~. Before that option and this function + were added, the behavior was hard-coded in many places all over the + code base but now all the rules are contained in this one function + (except for the "noselect" special case mentioned above). + +- Function: magit-display-buffer-same-window-except-diff-v1 :: + + This function displays most buffers in the currently selected + window. If a buffer's mode derives from ~magit-diff-mode~ or + ~magit-process-mode~, it is displayed in another window. + +- Function: magit-display-buffer-fullframe-status-v1 :: + + This function fills the entire frame when displaying a status + buffer. Otherwise, it behaves like + ~magit-display-buffer-traditional~. + +- Function: magit-display-buffer-fullframe-status-topleft-v1 :: + + This function fills the entire frame when displaying a status + buffer. It behaves like ~magit-display-buffer-fullframe-status-v1~ + except that it displays buffers that derive from ~magit-diff-mode~ + or ~magit-process-mode~ to the top or left of the current buffer + rather than to the bottom or right. As a result, Magit buffers tend + to pop up on the same side as they would if + ~magit-display-buffer-traditional~ were in use. + +- Function: magit-display-buffer-fullcolumn-most-v1 :: + + This function displays most buffers so that they fill the entire + height of the frame. However, the buffer is displayed in another + window if (1) the buffer's mode derives from ~magit-process-mode~, + or (2) the buffer's mode derives from ~magit-diff-mode~, provided + that the mode of the current buffer derives from ~magit-log-mode~ or + ~magit-cherry-mode~. + +- User Option: magit-pre-display-buffer-hook :: + + This hook is run by ~magit-display-buffer~ before displaying the + buffer. + +- Function: magit-save-window-configuration :: + + This function saves the current window configuration. Later when + the buffer is buried, it may be restored by + ~magit-restore-window-configuration~. + +- User Option: magit-post-display-buffer-hook :: + + This hook is run by ~magit-display-buffer~ after displaying the + buffer. + +- Function: magit-maybe-set-dedicated :: + + This function remembers if a new window had to be created to display + the buffer, or whether an existing window was reused. This + information is later used by ~magit-mode-quit-window~, to determine + whether the window should be deleted when its last Magit buffer is + buried. + +*** Naming Buffers + +- User Option: magit-generate-buffer-name-function :: + + The function used to generate the names of Magit buffers. + + Such a function should take the options ~magit-uniquify-buffer-names~ + as well as ~magit-buffer-name-format~ into account. If it doesn't, + then should be clearly stated in the doc-string. And if it supports + %-sequences beyond those mentioned in the doc-string of the option + ~magit-buffer-name-format~, then its own doc-string should describe + the additions. + +- Function: magit-generate-buffer-name-default-function mode :: + + This function returns a buffer name suitable for a buffer whose + major-mode is MODE and which shows information about the repository + in which ~default-directory~ is located. + + This function uses ~magit-buffer-name-format~ and supporting all of + the %-sequences mentioned the documentation of that option. It also + respects the option ~magit-uniquify-buffer-names~. + +- User Option: magit-buffer-name-format :: + + The format string used to name Magit buffers. + + At least the following %-sequences are supported: + + - ~%m~ + + The name of the major-mode, but with the ~-mode~ suffix removed. + + - ~%M~ + + Like ~%m~ but abbreviate ~magit-status-mode~ as ~magit~. + + - ~%v~ + + The value the buffer is locked to, in parentheses, or an empty + string if the buffer is not locked to a value. + + - ~%V~ + + Like ~%v~, but the string is prefixed with a space, unless it is an + empty string. + + - ~%t~ + + The top-level directory of the working tree of the repository, or + if ~magit-uniquify-buffer-names~ is non-~nil~ an abbreviation of that. + + - ~%x~ + + If ~magit-uniquify-buffer-names~ is ~nil~ "*", otherwise the empty + string. Due to limitations of the ~uniquify~ package, buffer names + must end with the path. + + The value should always contain ~%m~ or ~%M~, ~%v~ or ~%V~, and ~%t~. If + ~magit-uniquify-buffer-names~ is non-~nil~, then the value must end with + ~%t~ or ~%t%x~. See issue #2841. + +- User Option: magit-uniquify-buffer-names :: + + This option controls whether the names of Magit buffers are + uniquified. If the names are not being uniquified, then they + contain the full path of the top-level of the working tree of the + corresponding repository. If they are being uniquified, then they + end with the basename of the top-level, or if that would conflict + with the name used for other buffers, then the names of all these + buffers are adjusted until they no longer conflict. + + This is done using the ~uniquify~ package; customize its options to + control how buffer names are uniquified. + +*** Quitting Windows + +- Key: q (magit-mode-bury-buffer) :: + + This command buries or kills the current Magit buffer. The function + specified by option ~magit-bury-buffer-function~ is used to bury the + buffer when called without a prefix argument or to kill it when + called with a single prefix argument. + + When called with two or more prefix arguments then it always kills + all Magit buffers, associated with the current project, including + the current buffer. + +- User Option: magit-bury-buffer-function :: + + The function used to actually bury or kill the current buffer. + + ~magit-mode-bury-buffer~ calls this function with one argument. If + the argument is non-~nil~, then the function has to kill the current + buffer. Otherwise it has to bury it alive. The default value + currently is ~magit-mode-quit-window~. + +- Function: magit-restore-window-configuration kill-buffer :: + + Bury or kill the current buffer using ~quit-window~, which is called + with KILL-BUFFER as first and the selected window as second + argument. + + Then restore the window configuration that existed right before the + current buffer was displayed in the selected frame. Unfortunately + that also means that point gets adjusted in all the buffers, which + are being displayed in the selected frame. + +- Function: magit-mode-quit-window kill-buffer :: + + Bury or kill the current buffer using ~quit-window~, which is called + with KILL-BUFFER as first and the selected window as second + argument. + + Then, if the window was originally created to display a Magit buffer + and the buried buffer was the last remaining Magit buffer that was + ever displayed in the window, then that is deleted. + +*** Automatic Refreshing of Magit Buffers + +After running a command which may change the state of the current +repository, the current Magit buffer and the corresponding status +buffer are refreshed. The status buffer can be automatically refreshed +whenever a buffer is saved to a file inside the respective repository +by adding a hook, like so: + +#+begin_src emacs-lisp + (with-eval-after-load 'magit-mode + (add-hook 'after-save-hook 'magit-after-save-refresh-status t)) +#+end_src + +Automatically refreshing Magit buffers ensures that the displayed +information is up-to-date most of the time but can lead to a +noticeable delay in big repositories. Other Magit buffers are not +refreshed to keep the delay to a minimum and also because doing so can +sometimes be undesirable. + +Buffers can also be refreshed explicitly, which is useful in buffers +that weren't current during the last refresh and after changes were +made to the repository outside of Magit. + +- Key: g (magit-refresh) :: + + This command refreshes the current buffer if its major mode derives + from ~magit-mode~ as well as the corresponding status buffer. + + If the option ~magit-revert-buffers~ calls for it, then it also + reverts all unmodified buffers that visit files being tracked in the + current repository. + +- Key: G (magit-refresh-all) :: + + This command refreshes all Magit buffers belonging to the current + repository and also reverts all unmodified buffers that visit files + being tracked in the current repository. + + The file-visiting buffers are always reverted, even if + ~magit-revert-buffers~ is ~nil~. + +- User Option: magit-refresh-buffer-hook :: + + This hook is run in each Magit buffer that was refreshed during the + current refresh - normally the current buffer and the status buffer. + +- User Option: magit-refresh-status-buffer :: + + When this option is non-~nil~, then the status buffer is automatically + refreshed after running git for side-effects, in addition to the + current Magit buffer, which is always refreshed automatically. + + Only set this to ~nil~ after exhausting all other options to improve + performance. + +- Function: magit-after-save-refresh-status :: + + This function is intended to be added to ~after-save-hook~. After + doing that the corresponding status buffer is refreshed whenever a + buffer is saved to a file inside a repository. + + Note that refreshing a Magit buffer is done by re-creating its + contents from scratch, which can be slow in large repositories. If + you are not satisfied with Magit's performance, then you should + obviously not add this function to that hook. + +*** Automatic Saving of File-Visiting Buffers + +File-visiting buffers are by default saved at certain points in time. +This doesn't guarantee that Magit buffers are always up-to-date, but, +provided one only edits files by editing them in Emacs and uses only +Magit to interact with Git, one can be fairly confident. When in +doubt or after outside changes, type ~g~ (~magit-refresh~) to save and +refresh explicitly. + +- User Option: magit-save-repository-buffers :: + + This option controls whether file-visiting buffers are saved before + certain events. + + If this is non-~nil~ then all modified file-visiting buffers belonging + to the current repository may be saved before running commands, + before creating new Magit buffers, and before explicitly refreshing + such buffers. If this is ~dontask~ then this is done without user + intervention. If it is ~t~ then the user has to confirm each save. + +*** Automatic Reverting of File-Visiting Buffers + +By default Magit automatically reverts buffers that are visiting files +that are being tracked in a Git repository, after they have changed on +disk. When using Magit one often changes files on disk by running +Git, i.e., "outside Emacs", making this a rather important feature. + +For example, if you discard a change in the status buffer, then that +is done by running ~git apply --reverse ...~, and Emacs considers the +file to have "changed on disk". If Magit did not automatically revert +the buffer, then you would have to type ~M-x revert-buffer RET RET~ in +the visiting buffer before you could continue making changes. + +- User Option: magit-auto-revert-mode :: + + When this mode is enabled, then buffers that visit tracked files + are automatically reverted after the visited files change on disk. + +- User Option: global-auto-revert-mode :: + + When this mode is enabled, then any file-visiting buffer is + automatically reverted after the visited file changes on disk. + + If you like buffers that visit tracked files to be automatically + reverted, then you might also like any buffer to be reverted, not + just those visiting tracked files. If that is the case, then enable + this mode /instead of/ ~magit-auto-revert-mode~. + +- User Option: magit-auto-revert-immediately :: + + This option controls whether Magit reverts buffers immediately. + + If this is non-~nil~ and either ~global-auto-revert-mode~ or + ~magit-auto-revert-mode~ is enabled, then Magit immediately reverts + buffers by explicitly calling ~auto-revert-buffers~ after running Git + for side-effects. + + If ~auto-revert-use-notify~ is non-~nil~ (and file notifications are + actually supported), then ~magit-auto-revert-immediately~ does not + have to be non-~nil~, because the reverts happen immediately anyway. + + If ~magit-auto-revert-immediately~ and ~auto-revert-use-notify~ are both + ~nil~, then reverts happen after ~auto-revert-interval~ seconds of user + inactivity. That is not desirable. + +- User Option: auto-revert-use-notify :: + + This option controls whether file notification functions should be + used. Note that this variable unfortunately defaults to ~t~ even on + systems on which file notifications cannot be used. + +- User Option: magit-auto-revert-tracked-only :: + + This option controls whether ~magit-auto-revert-mode~ only reverts + tracked files or all files that are located inside Git repositories, + including untracked files and files located inside Git's control + directory. + +- User Option: auto-revert-mode :: + + The global mode ~magit-auto-revert-mode~ works by turning on this + local mode in the appropriate buffers (but ~global-auto-revert-mode~ + is implemented differently). You can also turn it on or off + manually, which might be necessary if Magit does not notice that a + previously untracked file now is being tracked or vice-versa. + +- User Option: auto-revert-stop-on-user-input :: + + This option controls whether the arrival of user input suspends the + automatic reverts for ~auto-revert-interval~ seconds. + +- User Option: auto-revert-interval :: + + This option controls how many seconds Emacs waits for before + resuming suspended reverts. + +- User Option: auto-revert-buffer-list-filter :: + + This option specifies an additional filter used by + ~auto-revert-buffers~ to determine whether a buffer should be reverted + or not. + + This option is provided by Magit, which also advises + ~auto-revert-buffers~ to respect it. Magit users who do not turn on + the local mode ~auto-revert-mode~ themselves, are best served by + setting the value to ~magit-auto-revert-repository-buffer-p~. + + However the default is ~nil~, so as not to disturb users who do use the + local mode directly. If you experience delays when running Magit + commands, then you should consider using one of the predicates + provided by Magit - especially if you also use Tramp. + + Users who do turn on ~auto-revert-mode~ in buffers in which Magit + doesn't do that for them, should likely not use any filter. Users + who turn on ~global-auto-revert-mode~, do not have to worry about this + option, because it is disregarded if the global mode is enabled. + +- User Option: auto-revert-verbose :: + + This option controls whether Emacs reports when a buffer has been + reverted. + +The options with the ~auto-revert-~ prefix are located in the Custom +group named ~auto-revert~. The other, Magit-specific, options are +located in the ~magit~ group. + +**** Risk of Reverting Automatically +:PROPERTIES: +:TEXINFO-NODE: t +:END: + +For the vast majority of users, automatically reverting file-visiting +buffers after they have changed on disk is harmless. + +If a buffer is modified (i.e., it contains changes that haven't been +saved yet), then Emacs will refuse to automatically revert it. If +you save a previously modified buffer, then that results in what is +seen by Git as an uncommitted change. Git will then refuse to carry +out any commands that would cause these changes to be lost. In other +words, if there is anything that could be lost, then either Git or +Emacs will refuse to discard the changes. + +However, if you use file-visiting buffers as a sort of ad hoc +"staging area", then the automatic reverts could potentially cause +data loss. So far I have heard from only one user who uses such a +workflow. + +An example: You visit some file in a buffer, edit it, and save the +changes. Then, outside of Emacs (or at least not using Magit or by +saving the buffer) you change the file on disk again. At this point +the buffer is the only place where the intermediate version still +exists. You have saved the changes to disk, but that has since been +overwritten. Meanwhile Emacs considers the buffer to be unmodified +(because you have not made any changes to it since you last saved it +to the visited file) and therefore would not object to it being +automatically reverted. At this point an Auto-Revert mode would kick +in. It would check whether the buffer is modified and since that is +not the case it would revert it. The intermediate version would be +lost. (Actually you could still get it back using the ~undo~ command.) + +If your workflow depends on Emacs preserving the intermediate version +in the buffer, then you have to disable all Auto-Revert modes. But +please consider that such a workflow would be dangerous even without +using an Auto-Revert mode, and should therefore be avoided. If Emacs +crashes or if you quit Emacs by mistake, then you would also lose the +buffer content. There would be no autosave file still containing the +intermediate version (because that was deleted when you saved the +buffer) and you would not be asked whether you want to save the buffer +(because it isn't modified). + +** Sections + +Magit buffers are organized into nested sections, which can be +collapsed and expanded, similar to how sections are handled in Org +mode. Each section also has a type, and some sections also have a +value. For each section type there can also be a local keymap, shared +by all sections of that type. + +Taking advantage of the section value and type, many commands operate on +the current section, or when the region is active and selects sections +of the same type, all of the selected sections. Commands that only +make sense for a particular section type (as opposed to just behaving +differently depending on the type) are usually bound in section type +keymaps. + +*** Section Movement + +To move within a section use the usual keys (~C-p~, ~C-n~, ~C-b~, ~C-f~ etc), +whose global bindings are not shadowed. To move to another section use +the following commands. + +The section movement commands described here run the hook +~magit-section-movement-hook~. Note that they explicitly run that hook +and that arbitrary other movement, defined in Emacs and other packages, +do not run that hook. That hook, and hook functions that can be added +to it, or are part of its default value, are described below. + +- Key: p (magit-section-backward) :: + + When not at the beginning of a section, then move to the beginning + of the current section. At the beginning of a section, instead move + to the beginning of the previous visible section. + +- Key: n (magit-section-forward) :: + + Move to the beginning of the next visible section. + +- Key: M-p (magit-section-backward-siblings) :: + + Move to the beginning of the previous sibling section. If there is + no previous sibling section, then move to the parent section + instead. + +- Key: M-n (magit-section-forward-siblings) :: + + Move to the beginning of the next sibling section. If there is no + next sibling section, then move to the parent section instead. + +- Key: ^ (magit-section-up) :: + + Move to the beginning of the parent of the current section. + +The above commands all call the hook ~magit-section-movement-hook~. +Any of the functions listed below can be used as members of this hook. + +You might want to remove some of the functions that Magit adds using +~add-hook~. In doing so you have to make sure you do not attempt to +remove function that haven't even been added yet, for example: + +#+begin_src emacs-lisp + (with-eval-after-load 'magit-diff + (remove-hook 'magit-section-movement-hook + 'magit-hunk-set-window-start)) +#+end_src + +- Variable: magit-section-movement-hook :: + + This hook is run by all of the above section movement commands, + after arriving at the destination. It is *not* run by arbitrary other + movement commands (such as ~next-line~), which are provided by Emacs + or third-party packages. + +- Function: magit-hunk-set-window-start :: + + This hook function ensures that the beginning of the current section + is visible, provided it is a ~hunk~ section. Otherwise, it does + nothing. + + Loading ~magit-diff~ adds this function to the hook. + +- Function: magit-section-set-window-start :: + + This hook function ensures that the beginning of the current section + is visible, regardless of the section's type. If you add this to + ~magit-section-movement-hook~, then you must remove the hunk-only + variant in turn. + +- Function: magit-log-maybe-show-more-commits :: + + This hook function only has an effect in log buffers, and ~point~ is + on the "show more" section. If that is the case, then it doubles + the number of commits that are being shown. + + Loading ~magit-log~ adds this function to the hook. + +- Function: magit-log-maybe-update-revision-buffer :: + + When moving inside a log buffer, then this function updates the + revision buffer, provided it is already being displayed in another + window of the same frame. + + Loading ~magit-log~ adds this function to the hook. + +- Function: magit-log-maybe-update-blob-buffer :: + + When moving inside a log buffer and another window of the same frame + displays a blob buffer, then this function instead displays the blob + buffer for the commit at point in that window. + +- Function: magit-status-maybe-update-revision-buffer :: + + When moving inside a status buffer, then this function updates the + revision buffer, provided it is already being displayed in another + window of the same frame. + +- Function: magit-status-maybe-update-stash-buffer :: + + When moving inside a status buffer, then this function updates the + stash buffer, provided it is already being displayed in another + window of the same frame. + +- Function: magit-status-maybe-update-blob-buffer :: + + When moving inside a status buffer and another window of the same + frame displays a blob buffer, then this function instead displays + the blob buffer for the commit at point in that window. + +- Function: magit-stashes-maybe-update-stash-buffer :: + + When moving inside a buffer listing stashes, then this function + updates the stash buffer, provided it is already being displayed + in another window of the same frame. + +- User Option: magit-update-other-window-delay :: + + Delay before automatically updating the other window. + + When moving around in certain buffers using Magit's own section + movement commands (but not other movement commands), then certain + other buffers, which are being displayed in another window, may + optionally be updated to display information about the section at + point. + + When holding down a key to move by more than just one section, then + that would update that buffer for each section on the way. To + prevent that, updating the revision buffer is delayed, and this + option controls for how long. For optimal experience you might have + to adjust this delay and/or the keyboard repeat rate and delay of + your graphical environment or operating system. + +*** Section Visibility + +Magit provides many commands for changing the visibility of sections, +but all you need to get started are the next two. + +- Key: TAB (magit-section-toggle) :: + + Toggle the visibility of the body of the current section. + +- Key: C-c TAB (magit-section-cycle) :: +- Key: C- (magit-section-cycle) :: + + Cycle the visibility of current section and its children. + + If this command is invoked using ~C-~ and that is globally bound + to ~tab-next~, then this command pivots to behave like that command, + and you must instead use ~C-c TAB~ to cycle section visibility. + + If you would like to keep using ~C-~ to cycle section visibility + but also want to use ~tab-bar-mode~, then you have to prevent that mode + from using this key and instead bind another key to ~tab-next~. Because + ~tab-bar-mode~ does not use a mode map but instead manipulates the + global map, this involves advising ~tab-bar--define-keys~. + +- Key: M- (magit-section-cycle-diffs) :: + + Cycle the visibility of diff-related sections in the current buffer. + +- Key: S- (magit-section-cycle-global) :: + + Cycle the visibility of all sections in the current buffer. + +- Key: 1 (magit-section-show-level-1) :: +- Key: 2 (magit-section-show-level-2) :: +- Key: 3 (magit-section-show-level-3) :: +- Key: 4 (magit-section-show-level-4) :: + + Show sections surrounding the current section up to level N. + +- Key: M-1 (magit-section-show-level-1-all) :: +- Key: M-2 (magit-section-show-level-2-all) :: +- Key: M-3 (magit-section-show-level-3-all) :: +- Key: M-4 (magit-section-show-level-4-all) :: + + Show all sections up to level N. + +Some functions, which are used to implement the above commands, are +also exposed as commands themselves. By default no keys are bound to +these commands, as they are generally perceived to be much less +useful. But your mileage may vary. + +- Command: magit-section-show :: + + Show the body of the current section. + +- Command: magit-section-hide :: + + Hide the body of the current section. + +- Command: magit-section-show-headings :: + + Recursively show headings of children of the current section. Only + show the headings. Previously shown text-only bodies are hidden. + +- Command: magit-section-show-children :: + + Recursively show the bodies of children of the current section. + With a prefix argument show children down to the level of the + current section, and hide deeper children. + +- Command: magit-section-hide-children :: + + Recursively hide the bodies of children of the current section. + +- Command: magit-section-toggle-children :: + + Toggle visibility of bodies of children of the current section. + +When a buffer is first created then some sections are shown expanded +while others are not. This is hard coded. When a buffer is refreshed +then the previous visibility is preserved. The initial visibility of +certain sections can also be overwritten using the hook +~magit-section-set-visibility-hook~. + +- User Option: magit-section-initial-visibility-alist :: + + This options can be used to override the initial visibility of + sections. In the future it will also be used to define the + defaults, but currently a section's default is still hardcoded. + + The value is an alist. Each element maps a section type or lineage + to the initial visibility state for such sections. The state has to + be one of ~show~ or ~hide~, or a function that returns one of these + symbols. A function is called with the section as the only argument. + + Use the command ~magit-describe-section-briefly~ to determine a + section's lineage or type. The vector in the output is the section + lineage and the type is the first element of that vector. Wildcards + can be used, see ~magit-section-match~. + +- User Option: magit-section-cache-visibility :: + + This option controls for which sections the previous visibility + state should be restored if a section disappears and later appears + again. The value is a boolean or a list of section types. If ~t~, + then the visibility of all sections is cached. Otherwise this is + only done for sections whose type matches one of the listed types. + + This requires that the function ~magit-section-cached-visibility~ is + a member of ~magit-section-set-visibility-hook~. + +- Variable: magit-section-set-visibility-hook :: + + This hook is run when first creating a buffer and also when + refreshing an existing buffer, and is used to determine the + visibility of the section currently being inserted. + + Each function is called with one argument, the section being + inserted. It should return ~hide~ or ~show~, or to leave the visibility + undefined ~nil~. If no function decides on the visibility and the + buffer is being refreshed, then the visibility is preserved; or if + the buffer is being created, then the hard coded default is used. + + Usually this should only be used to set the initial visibility but + not during refreshes. If ~magit-insert-section--oldroot~ is non-~nil~, + then the buffer is being refreshed and these functions should + immediately return ~nil~. + +- User Option: magit-section-visibility-indicators :: + + This option controls whether and how to indicate that a section can + be expanded/collapsed. + + If ~nil~, then don't show any indicators. Otherwise the value has to + be a list with two elements. The first controls the indicators used + in graphical frames, the second the indicators in terminal frames. + For graphical frames all of the following forms are valid, while + terminal frames do not have fringes and thus do not support the first + form. + + - ~(EXPANDABLE-BITMAP . COLLAPSIBLE-BITMAP)~ + + Both values have to be variables whose values are fringe + bitmaps. In this case every section that can be expanded + or collapsed gets an indicator in the left fringe. + + To provide extra padding around the indicator, set + ~left-fringe-width~ in ~magit-mode-hook~, e.g.: + + #+BEGIN_SRC emacs-lisp + (add-hook 'magit-mode-hook + (lambda () (setq left-fringe-width 20))) + #+END_SRC + + - ~(EXPANDABLE-CHAR . COLLAPSIBLE-CHAR)~ + + In this case every section that can be expanded or collapsed + gets an indicator in the left margin. + + - ~(STRING . BOOLEAN)~ + + In this case STRING (usually an ellipsis) is shown at the end + of the heading of every collapsed section. Expanded sections + get no indicator. The cdr controls whether the appearance of + these ellipsis take section highlighting into account. Doing + so might potentially have an impact on performance, while not + doing so is kinda ugly. + +*** Section Hooks + +Which sections are inserted into certain buffers is controlled with +hooks. This includes the status and the refs buffers. For other +buffers, e.g., log and diff buffers, this is not possible. The +command ~magit-describe-section~ can be used to see which hook (if any) +was responsible for inserting the section at point. + +For buffers whose sections can be customized by the user, a hook +variable called ~magit-TYPE-sections-hook~ exists. This hook should be +changed using ~magit-add-section-hook~. Avoid using ~add-hooks~ or the +Custom interface. + +The various available section hook variables are described later in +this manual along with the appropriate "section inserter functions". + +- Function: magit-add-section-hook hook function &optional at append local :: + + Add the function FUNCTION to the value of section hook HOOK. + + Add FUNCTION at the beginning of the hook list unless optional + APPEND is non-~nil~, in which case FUNCTION is added at the end. If + FUNCTION already is a member then move it to the new location. + + If optional AT is non-~nil~ and a member of the hook list, then add + FUNCTION next to that instead. Add before or after AT, or replace + AT with FUNCTION depending on APPEND. If APPEND is the symbol + ~replace~, then replace AT with FUNCTION. For any other non-~nil~ value + place FUNCTION right after AT. If ~nil~, then place FUNCTION right + before AT. If FUNCTION already is a member of the list but AT is + not, then leave FUNCTION where ever it already is. + + If optional LOCAL is non-~nil~, then modify the hook's buffer-local + value rather than its global value. This makes the hook local by + copying the default value. That copy is then modified. + + HOOK should be a symbol. If HOOK is void, it is first set to ~nil~. + HOOK's value must not be a single hook function. FUNCTION should + be a function that takes no arguments and inserts one or multiple + sections at point, moving point forward. FUNCTION may choose not + to insert its section(s), when doing so would not make sense. It + should not be abused for other side-effects. + +To remove a function from a section hook, use ~remove-hook~. + +*** Section Types and Values + +Each section has a type, for example ~hunk~, ~file~, and ~commit~. +Instances of certain section types also have a value. The value of a +section of type ~file~, for example, is a file name. + +Users usually do not have to worry about a section's type and value, +but knowing them can be handy at times. + +- Key: H (magit-describe-section) :: + + This command shows information about the section at point in a + separate buffer. + +- Command: magit-describe-section-briefly :: + + This command shows information about the section at point in the + echo area, as ~#~. + +Many commands behave differently depending on the type of the section +at point and/or somehow consume the value of that section. But that +is only one of the reasons why the same key may do something different, +depending on what section is current. + +Additionally for each section type a keymap *might* be defined, named +~magit-TYPE-section-map~. That keymap is used as text property keymap +of all text belonging to any section of the respective type. If such +a map does not exist for a certain type, then you can define it +yourself, and it will automatically be used. + +*** Section Options + +This section describes options that have an effect on more than just a +certain type of sections. As you can see there are not many of those. + +- User Option: magit-section-show-child-count :: + + Whether to append the number of children to section headings. This + only affects sections that could benefit from this information. + +** Transient Commands + +Many Magit commands are implemented as *transient* commands. First the +user invokes a *prefix* command, which causes its *infix* arguments and +*suffix* commands to be displayed in the echo area. The user then +optionally sets some infix arguments and finally invokes one of the +suffix commands. + +This is implemented in the library ~transient~. Earlier Magit releases +used the package ~magit-popup~ and even earlier versions library +~magit-key-mode~. + +Transient is documented in [[info:transient]]. + +- Key: C-x M-g (magit-dispatch) :: +- Key: C-c g (magit-dispatch) :: + + This transient prefix command binds most of Magit's other prefix + commands as suffix commands and displays them in a temporary buffer + until one of them is invoked. Invoking such a sub-prefix causes the + suffixes of that command to be bound and displayed instead of those + of ~magit-dispatch~. + + This command is also, or especially, useful outside Magit buffers, + so Magit by default binds it to ~C-c M-g~ in the global keymap. + ~C-c g~ would be a better binding, but we cannot use that by default, + because that key sequence is reserved for the user. See [[*Global + Bindings]] to learn more default and recommended key bindings. + +** Transient Arguments and Buffer Variables + +The infix arguments of many of Magit's transient prefix commands cease +to have an effect once the ~git~ command that is called with those +arguments has returned. Commands that create a commit are a good +example for this. If the user changes the arguments, then that only +affects the next invocation of a suffix command. If the same +transient prefix command is later invoked again, then the arguments +are initially reset to the default value. This default value can be +set for the current Emacs session or saved permanently, see +[[info:transient#Saving Values]]. It is also possible to cycle through +previously used sets of arguments using ~C-M-p~ and ~C-M-n~, see +[[info:transient#Using History]]. + +However the infix arguments of many other transient commands continue +to have an effect even after the ~git~ command that was called with +those arguments has returned. The most important commands like this +are those that display a diff or log in a dedicated buffer. Their +arguments obviously continue to have an effect for as long as the +respective diff or log is being displayed. Furthermore the used +arguments are stored in buffer-local variables for future reference. + +For commands in the second group it isn't always desirable to reset +their arguments to the global value when the transient prefix command +is invoked again. + +As mentioned above, it is possible to cycle through previously used +sets of arguments while a transient popup is visible. That means that +we could always reset the infix arguments to the default because the +set of arguments that is active in the existing buffer is only a few +~C-M-p~ away. Magit can be configured to behave like that, but because I +expect that most users would not find that very convenient, it is not +the default. + +Also note that it is possible to change the diff and log arguments +used in the current buffer (including the status buffer, which +contains both diff and log sections) using the respective "refresh" +transient prefix commands on ~D~ and ~L~. (~d~ and ~l~ on the other hand are +intended to change *what* diff or log is being displayed. It is +possible to also change *how* the diff or log is being displayed at the +same time, but if you only want to do the latter, then you should use +the refresh variants.) Because these secondary diff and log transient +prefixes are about *changing* the arguments used in the current buffer, +they *always* start out with the set of arguments that are currently in +effect in that buffer. + +Some commands are usually invoked directly even though they can also +be invoked as the suffix of a transient prefix command. Most +prominently ~magit-show-commit~ is usually invoked by typing ~RET~ while +point is on a commit in a log, but it can also be invoked from the +~magit-diff~ transient prefix. + +When such a command is invoked directly, then it is important to reuse +the arguments as specified by the respective buffer-local values, +instead of using the default arguments. Imagine you press ~RET~ in a +log to display the commit at point in a different buffer and then use +~D~ to change how the diff is displayed in that buffer. And then you +press ~RET~ on another commit to show that instead and the diff +arguments are reset to the default. Not cool; so Magit does not do +that by default. + +- User Option: magit-prefix-use-buffer-arguments :: + + This option controls whether the infix arguments initially shown in + certain transient prefix commands are based on the arguments that + are currently in effect in the buffer that their suffixes update. + + The ~magit-diff~ and ~magit-log~ transient prefix commands are affected + by this option. + +- User Option: magit-direct-use-buffer-arguments :: + + This option controls whether certain commands, when invoked directly + (i.e., not as the suffix of a transient prefix command), use the + arguments that are currently active in the buffer that they are + about to update. The alternative is to use the default value for + these arguments, which might change the arguments that are used in + the buffer. + +#+texinfo: @noindent +Valid values for both of the above options are: + + - ~always~: Always use the set of arguments that is currently active + in the respective buffer, provided that buffer exists of course. + - ~selected~ or ~t~: Use the set of arguments from the respective + buffer, but only if it is displayed in a window of the current + frame. This is the default for both variables. + - ~current~: Use the set of arguments from the respective buffer, but + only if it is the current buffer. + - ~never~: Never use the set of arguments from the respective buffer. + +#+texinfo: @noindent +I am afraid it gets more complicated still: + +- The global diff and log arguments are set for each supported mode + individually. The diff arguments for example have different values + in ~magit-diff-mode~, ~magit-revision-mode~, ~magit-merge-preview-mode~ + and ~magit-status-mode~ buffers. Setting or saving the value for one + mode does not change the value for other modes. The history however + is shared. + +- When ~magit-show-commit~ is invoked directly from a log buffer, then + the file filter is picked up from that buffer, not from the revision + buffer or the mode's global diff arguments. + +- Even though they are suffixes of the diff prefix ~magit-show-commit~ + and ~magit-stash-show~ do not use the diff buffer used by the diff + commands, instead they use the dedicated revision and stash buffers. + + At the time you invoke the diff prefix it is unknown to Magit which + of the suffix commands you are going to invoke. While not certain, + more often than not users invoke one of the commands that use the + diff buffer, so the initial infix arguments are those used in that + buffer. However if you invoke one of these commands directly, then + Magit knows that it should use the arguments from the revision resp. + stash buffer. + +- The log prefix also features reflog commands, but these commands do + not use the log arguments. + +- If ~magit-show-refs~ is invoked from a ~magit-refs-mode~ buffer, then it + acts as a refresh prefix and therefore unconditionally uses the + buffer's arguments as initial arguments. If it is invoked elsewhere + with a prefix argument, then it acts as regular prefix and therefore + respects ~magit-prefix-use-buffer-arguments~. If it is invoked + elsewhere without a prefix argument, then it acts as a direct + command and therefore respects ~magit-direct-use-buffer-arguments~. + +** Completion, Confirmation and the Selection +*** Action Confirmation + +By default many actions that could potentially lead to data loss have +to be confirmed. This includes many very common actions, so this can +quickly become annoying. Many of these actions can be undone and if +you have thought about how to undo certain mistakes, then it should +be safe to disable confirmation for the respective actions. + +The option ~magit-no-confirm~ can be used to tell Magit to perform +certain actions without the user having to confirm them. Note that +while this option can only be used to disable confirmation for a +specific set of actions, the next section explains another way of +telling Magit to ask fewer questions. + +- User Option: magit-no-confirm :: + + The value of this option is a list of symbols, representing actions + that do not have to be confirmed by the user before being carried + out. + + By default many potentially dangerous commands ask the user for + confirmation. Each of the below symbols stands for an action which, + when invoked unintentionally or without being fully aware of the + consequences, could lead to tears. In many cases there are several + commands that perform variations of a certain action, so we don't + use the command names but more generic symbols. + + - Applying changes: + + - ~discard~ Discarding one or more changes (i.e., hunks or the + complete diff for a file) loses that change, obviously. + + - ~reverse~ Reverting one or more changes can usually be undone by + reverting the reversion. + + - ~stage-all-changes~, ~unstage-all-changes~ When there are both + staged and unstaged changes, then un-/staging everything would + destroy that distinction. Of course that also applies when + un-/staging a single change, but then less is lost and one does + that so often that having to confirm every time would be + unacceptable. + + - Files: + + - ~delete~ When a file that isn't yet tracked by Git is deleted, + then it is completely lost, not just the last changes. Very + dangerous. + + - ~trash~ Instead of deleting a file it can also be move to the + system trash. Obviously much less dangerous than deleting it. + + Also see option ~magit-delete-by-moving-to-trash~. + + - ~resurrect~ A deleted file can easily be resurrected by "deleting" + the deletion, which is done using the same command that was used + to delete the same file in the first place. + + - ~untrack~ Untracking a file can be undone by tracking it again. + + - ~rename~ Renaming a file can easily be undone. + + - Sequences: + + - ~reset-bisect~ Aborting (known to Git as "resetting") a bisect + operation loses all information collected so far. + + - ~abort-cherry-pick~ Aborting a cherry-pick throws away all + conflict resolutions which have already been carried out by the + user. + + - ~abort-revert~ Aborting a revert throws away all conflict + resolutions which have already been carried out by the user. + + - ~abort-rebase~ Aborting a rebase throws away all already modified + commits, but it's possible to restore those from the reflog. + + - ~abort-merge~ Aborting a merge throws away all conflict + resolutions which have already been carried out by the user. + + - ~merge-dirty~ Merging with a dirty worktree can make it hard to go + back to the state before the merge was initiated. + + - References: + + - ~delete-unmerged-branch~ Once a branch has been deleted, it can + only be restored using low-level recovery tools provided by Git. + And even then the reflog is gone. The user always has to + confirm the deletion of a branch by accepting the default choice + (or selecting another branch), but when a branch has not been + merged yet, also make sure the user is aware of that. + + - ~delete-pr-remote~ When deleting a branch that was created from a + pull-request and if no other branches still exist on that + remote, then ~magit-branch-delete~ offers to delete the remote + as well. This should be safe because it only happens if no + other refs exist in the remotes namespace, and you can recreate + the remote if necessary. + + - ~drop-stashes~ Dropping a stash is dangerous because Git stores + stashes in the reflog. Once a stash is removed, there is no + going back without using low-level recovery tools provided by + Git. When a single stash is dropped, then the user always has + to confirm by accepting the default (or selecting another). + This action only concerns the deletion of multiple stashes at + once. + + - Publishing: + + - ~set-and-push~ When pushing to the upstream or the push-remote + and that isn't actually configured yet, then the user can first + set the target. If s/he confirms the default too quickly, then + s/he might end up pushing to the wrong branch and if the remote + repository is configured to disallow fixing such mistakes, then + that can be quite embarrassing and annoying. + + - Edit published history: + + Without adding these symbols here, you will be warned before + editing commits that have already been pushed to one of the + branches listed in ~magit-published-branches~. + + - ~amend-published~ Affects most commands that amend to "HEAD". + + - ~rebase-published~ Affects commands that perform interactive + rebases. This includes commands from the commit transient that + modify a commit other than "HEAD", namely the various fixup and + squash variants. + + - ~edit-published~ Affects the commands ~magit-edit-line-commit~ and + ~magit-diff-edit-hunk-commit~. These two commands make it quite + easy to accidentally edit a published commit, so you should + think twice before configuring them not to ask for confirmation. + + To disable confirmation completely, add all three symbols here or + set ~magit-published-branches~ to ~nil~. + + - Various: + + - ~stash-apply-3way~ When a stash cannot be applied using ~git stash + apply~, then Magit uses ~git apply~ instead, possibly using the + ~--3way~ argument, which isn't always perfectly safe. See also + ~magit-stash-apply~. + + - ~kill-process~ There seldom is a reason to kill a process. + + - Global settings: + + Instead of adding all of the above symbols to the value of this + option, you can also set it to the atom `t', which has the same + effect as adding all of the above symbols. Doing that most + certainly is a bad idea, especially because other symbols might be + added in the future. So even if you don't want to be asked for + confirmation for any of these actions, you are still better of + adding all of the respective symbols individually. + + When ~magit-wip-before-change-mode~ is enabled, then the following + actions can be undone fairly easily: ~discard~, ~reverse~, + ~stage-all-changes~, and ~unstage-all-changes~. If and only if + this mode is enabled, then ~safe-with-wip~ has the same effect as + adding all of these symbols individually. + +*** Completion and Confirmation + +Many Magit commands ask the user to select from a list of possible +things to act on, while offering the most likely choice as the +default. For many of these commands the default is the thing at +point, provided that it actually is a valid thing to act on. For +many commands that act on a branch, the current branch serves as +the default if there is no branch at point. + +These commands combine asking for confirmation and asking for a target +to act on into a single action. The user can confirm the default +target using ~RET~ or abort using ~C-g~. This is similar to a ~y-or-n-p~ +prompt, but the keys to confirm or abort differ. + +At the same time the user is also given the opportunity to select +another target, which is useful because for some commands and/or in +some situations you might want to select the action before selecting +the target by moving to it. + +However you might find that for some commands you always want to use +the default target, if any, or even that you want the command to act +on the default without requiring any confirmation at all. The option +~magit-dwim-selection~ can be used to configure certain commands to that +effect. + +Note that when the region is active then many commands act on the +things that are selected using a mechanism based on the region, in +many cases after asking for confirmation. This region-based mechanism +is called the "selection" and is described in detail in the next +section. When a selection exists that is valid for the invoked +command, then that command never offers to act on something else, and +whether it asks for confirmation is not controlled by this option. + +Also note that Magit asks for confirmation of certain actions that are +not coupled with completion (or the selection). Such dialogs are also +not affected by this option and are described in the previous section. + +- User Option: magit-dwim-selection :: + +This option can be used to tell certain commands to use the thing +at point instead of asking the user to select a candidate to act +on, with or without confirmation. + +The value has the form ~((COMMAND nil|PROMPT DEFAULT)...)~. + +- COMMAND is the command that should not prompt for a choice. + To have an effect, the command has to use the function + ~magit-completing-read~ or a utility function which in turn uses + that function. + +- If the command uses ~magit-completing-read~ multiple times, then + PROMPT can be used to only affect one of these uses. PROMPT, if + non-~nil~, is a regular expression that is used to match against + the PROMPT argument passed to ~magit-completing-read~. + +- DEFAULT specifies how to use the default. If it is ~t~, then + the DEFAULT argument passed to ~magit-completing-read~ is used + without confirmation. If it is ~ask~, then the user is given + a chance to abort. DEFAULT can also be ~nil~, in which case the + entry has no effect. + +*** The Selection + +If the region is active, then many Magit commands act on the things +that are selected using a mechanism based on the region instead of one +single thing. When the region is not active, then these commands act +on the thing at point or read a single thing to act on. This is +described in the previous section — this section only covers how +multiple things are selected, how that is visualized, and how certain +commands behave when that is the case. + +Magit's mechanism for selecting multiple things, or rather sections +that represent these things, is based on the Emacs region, but the +area that Magit considers to be selected is typically larger than the +region and additional restrictions apply. + +Magit makes a distinction between a region that qualifies as forming a +valid Magit selection and a region that does not. If the region does +not qualify, then it is displayed as it is in other Emacs buffers. If +the region does qualify as a Magit selection, then the selection is +always visualized, while the region itself is only visualized if it +begins and ends on the same line. + +For a region to qualify as a Magit selection, it must begin in the +heading of one section and end in the heading of a sibling section. +Note that if the end of the region is at the very beginning of section +heading (i.e., at the very beginning of a line) then that section is +considered to be *inside* the selection. + +This is not consistent with how the region is normally treated in +Emacs — if the region ends at the beginning of a line, then that line +is outside the region. Due to how Magit visualizes the selection, it +should be obvious that this difference exists. + +Not every command acts on every valid selection. Some commands do not +even consider the location of point, others may act on the section at +point but not support acting on the selection, and even commands that +do support the selection of course only do so if it selects things +that they can act on. + +This is the main reason why the selection must include the section at +point. Even if a selection exists, the invoked command may disregard +it, in which case it may act on the current section only. It is much +safer to only act on the current section but not the other selected +sections than it is to act on the current section *instead* of the +selected sections. The latter would be much more surprising and if +the current section always is part of the selection, then that cannot +happen. + +- Variable: magit-keep-region-overlay :: + + This variable controls whether the region is visualized as usual + even when a valid Magit selection or a hunk-internal region exists. + See the doc-string for more information. + +*** The hunk-internal region + +Somewhat related to the Magit selection described in the previous +section is the hunk-internal region. + +Like the selection, the hunk-internal region is based on the Emacs +region but causes that region to not be visualized as it would in +other Emacs buffers, and includes the line on which the region ends +even if it ends at the very beginning of that line. + +Unlike the selection, which is based on a region that must begin in +the heading of one section and ends in the section of a sibling +section, the hunk-internal region must begin inside the *body* of a +hunk section and end in the body of the *same* section. + +The hunk-internal region is honored by "apply" commands, which can, +among other targets, act on a hunk. If the hunk-internal region is +active, then such commands act only on the marked part of the hunk +instead of on the complete hunk. + +*** Support for Completion Frameworks + +The built-in option ~completing-read-function~ specifies the low-level +function used by ~completing-read~ to ask a user to select from a list +of choices. Its default value is ~completing-read-default~. +Alternative completion frameworks typically activate themselves by +substituting their own implementation. + +Mostly for historic reasons Magit provides a similar option named +~magit-completing-read-function~, which only controls the low-level +function used by ~magit-completing-read~. This option also makes it +possible to use a different completing mechanism for Magit than for +the rest of Emacs, but doing that is not recommend. + +You most likely don't have to customize the magit-specific option to +use an alternative completion framework. For example, if you enable +~ivy-mode~, then Magit will respect that, and if you enable ~helm-mode~, +then you are done too. + +- User Option: magit-completing-read-function :: + + The value of this variable is the low-level function used to perform + completion by code that uses ~magit-completing-read~ (as opposed to + the built-in ~completing-read~). + + The default value, ~magit-builtin-completing-read~, is suitable for + the standard completion mechanism, ~ivy-mode~, and ~helm-mode~ at least. + + The built-in ~completing-read~ and ~completing-read-default~ are *not* + suitable to be used here. ~magit-builtin-completing-read~ performs + some additional work, and any function used in its place has to do + the same. + +- Function: magit-builtin-completing-read prompt choices &optional predicate require-match initial-input hist def :: + + This function performs completion using the built-in ~completing-read~ + and does some additional magit-specific work. + +- Function: magit-completing-read prompt choices &optional predicate require-match initial-input hist def fallback :: + + This is the function that Magit commands use when they need the user + to select a single thing to act on. The arguments have the same + meaning as for ~completing-read~, except for FALLBACK, which is unique + to this function and is described below. + + Instead of asking the user to choose from a list of possible + candidates, this function may just return the default specified by + DEF, with or without requiring user confirmation. Whether that is + the case depends on PROMPT, ~this-command~ and ~magit-dwim-selection~. + See the documentation of the latter for more information. + + If it does read a value in the minibuffer, then this function acts + similar to ~completing-read~, except for the following: + + - COLLECTION must be a list of choices. A function is not + supported. + + - If REQUIRE-MATCH is ~nil~ and the user exits without a choice, then + ~nil~ is returned instead of an empty string. + + - If REQUIRE-MATCH is ~any~, then do not require a match but + do require non-empty input (or non-~nil~ DEFAULT, since that + is substituted for empty input). + + - If REQUIRE-MATCH is non-~nil~ and the users exits without a choice, + an user-error is raised. + + - FALLBACK specifies a secondary default that is only used if the + primary default DEF is ~nil~. The secondary default is not subject + to ~magit-dwim-selection~ — if DEF is ~nil~ but FALLBACK is not, then + this function always asks the user to choose a candidate, just as + if both defaults were ~nil~. + + - ~format-prompt~ is called on PROMPT and DEF (or FALLBACK if + DEF is ~nil~). This appends ": " to the prompt and may also + add the default to the prompt, using the format specified by + ~minibuffer-default-prompt-format~ and depending on + ~magit-completing-read-default-prompt-predicate~. + +*** Additional Completion Options + +- User Option: magit-list-refs-sortby :: + + For many commands that read a ref or refs from the user, the value + of this option can be used to control the order of the refs. Valid + values include any key accepted by the ~--sort~ flag of ~git + for-each-ref~. By default, refs are sorted alphabetically by their + full name (e.g., "refs/heads/master"). + +** Mouse Support + +Double clicking on a section heading toggles the visibility of its +body, if any. Likewise clicking in the left fringe toggles the +visibility of the appropriate section. + +A context menu is provided but has to be enabled explicitly. In Emacs +28 and greater, enable the global mode ~context-menu-mode~. If you use an +older Emacs release, set ~magit-section-show-context-menu-for-emacs<28~. + +** Running Git +*** Viewing Git Output + +Magit runs Git either for side-effects (e.g., when pushing) or to get +some value (e.g., the name of the current branch). + +When Git is run for side-effects, the process output is logged in a +per-repository log buffer, which can be consulted using the +~magit-process-buffer~ command, when things don't go as expected. + +The output/errors for up to ~magit-process-log-max~ Git commands are +retained. + +- Key: $ (magit-process-buffer) :: + + This commands displays the process buffer for the current + repository. + +Inside that buffer, the usual key bindings for navigating and showing +sections are available. There is one additional command. + +- Key: k (magit-process-kill) :: + + This command kills the process represented by the section at point. + +- Key: M-x magit-toggle-git-debug :: + + This command toggles whether additional git errors are reported. + + Magit basically calls git for one of these two reasons: for + side-effects or to do something with its standard output. + + When git is run for side-effects then its output, including error + messages, go into the process buffer which is shown when using ~$~. + + When git's output is consumed in some way, then it would be too + expensive to also insert it into this buffer, but with this command + that can be enabled temporarily. In that case, if git returns with + a non-zero exit status, then at least its standard error is inserted + into this buffer. + + Also note that just because git exits with a non-zero status and + prints an error message, that usually doesn't mean that it is an + error as far as Magit is concerned, which is another reason we + usually hide these error messages. Whether some error message is + relevant in the context of some unexpected behavior has to be judged + on a case by case basis. + +*** Git Process Status + +When a Git process is running for side-effects, Magit displays an +indicator in the mode line, using the ~magit-mode-line-process~ face. + +If the Git process exits successfully, the process indicator is +removed from the mode line immediately. + +In the case of a Git error, the process indicator is not removed, but +is instead highlighted with the ~magit-mode-line-process-error~ face, +and the error details from the process buffer are provided as a +tooltip for mouse users. This error indicator persists in the mode +line until the next magit buffer refresh. + +If you do not wish process errors to be indicated in the mode line, +set ~magit-process-display-mode-line-error~ to ~nil~. + +Process errors are displayed at the top of the status buffer and in +the echo area. In both places a hint is appended, which informs users +that they can see the full output in the process buffer and how to +display that buffer. However, once you are aware of that, you might +want to set ~magit-show-process-buffer-hint~ to ~nil~. + +*** Running Git Manually + +While Magit provides many Emacs commands to interact with Git, it does +not cover everything. In those cases your existing Git knowledge will +come in handy. Magit provides some commands for running arbitrary Git +commands by typing them into the minibuffer, instead of having to +switch to a shell. + +- Key: ! (magit-run) :: + + This transient prefix command binds the following suffix commands + and displays them in a temporary buffer until a suffix is invoked. + +- Key: ! ! (magit-git-command-topdir) :: + + This command reads a command from the user and executes it in the + top-level directory of the current working tree. + + The string "git " is used as initial input when prompting the user + for the command. It can be removed to run another command. + +- Key: : (magit-git-command) :: +- Key: ! p :: + + This command reads a command from the user and executes it in + ~default-directory~. With a prefix argument the command is executed + in the top-level directory of the current working tree instead. + + The string "git " is used as initial input when prompting the user + for the command. It can be removed to run another command. + +- Key: ! s (magit-shell-command-topdir) :: + + This command reads a command from the user and executes it in the + top-level directory of the current working tree. + +- Key: ! S (magit-shell-command) :: + + This command reads a command from the user and executes it in + ~default-directory~. With a prefix argument the command is executed + in the top-level directory of the current working tree instead. + +- User Option: magit-shell-command-verbose-prompt :: + + Whether the prompt, used by the above commands when reading a + shell command, shows the directory in which it will be run. + +These suffix commands start external gui tools. + +- Key: ! k (magit-run-gitk) :: + + This command runs ~gitk~ in the current repository. + +- Key: ! a (magit-run-gitk-all) :: + + This command runs ~gitk --all~ in the current repository. + +- Key: ! b (magit-run-gitk-branches) :: + + This command runs ~gitk --branches~ in the current repository. + +- Key: ! g (magit-run-git-gui) :: + + This command runs ~git gui~ in the current repository. + +- Key: ! m (magit-git-mergetool) :: + + This command runs =git mergetool --gui= in the current repository. + + With a prefix argument this acts as a transient prefix command, + allowing the user to select the mergetool and change some settings. + +*** Git Executable + +When Magit calls Git, then it may do so using the absolute path to the +~git~ executable, or using just its name. + +When running ~git~ locally and the ~system-type~ is ~windows-nt~ (any +Windows version) or ~darwin~ (macOS) then ~magit-git-executable~ is set +to an absolute path when Magit is loaded. + +On Windows it is necessary to use an absolute path because Git comes +with several wrapper scripts for the actual ~git~ binary, which are also +placed on ~$PATH~, and using one of these wrappers instead of the binary +would degrade performance horribly. For some macOS users using just +the name of the executable also performs horribly, so we avoid doing +that on that platform as well. On other platforms, using just the +name seems to work just fine. + +Using an absolute path when running ~git~ on a remote machine over +Tramp, would be problematic to use an absolute path that is suitable +on the local machine, so a separate option is used to control the name +or path that is used on remote machines. + +- User Option: magit-git-executable :: + + The ~git~ executable used by Magit on the local host. This should be + either the absolute path to the executable, or the string "git" to + let Emacs find the executable itself, using the standard mechanism + for doing such things. + +- User Option: magit-remote-git-executable :: + + The ~git~ executable used by Magit on remote machines over Tramp. + Normally this should be just the string "git". Consider customizing + ~tramp-remote-path~ instead of this option. + +If Emacs is unable to find the correct executable, then you can +work around that by explicitly setting the value of one of these two +options. Doing that should be considered a kludge; it is better to +make sure that the order in ~exec-path~ or ~tramp-remote-path~ is correct. + +Note that ~exec-path~ is set based on the value of the ~PATH~ environment +variable that is in effect when Emacs is started. If you set ~PATH~ in +your shell's init files, then that only has an effect on Emacs if you +start it from that shell (because the environment of a process is only +passed to its child processes, not to arbitrary other processes). If +that is not how you start Emacs, then the ~exec-path-from-shell~ package +can help; though honestly I consider that a kludge too. + +The command ~magit-debug-git-executable~ can be useful to find out where +Emacs is searching for ~git~. + +- Key: M-x magit-debug-git-executable :: + + This command displays a buffer with information about + ~magit-git-executable~ and ~magit-remote-git-executable~. + +- Key: M-x magit-version :: + + This command shows the currently used versions of Magit, Git, and + Emacs in the echo area. Non-interactively this just returns the + Magit version. + +*** Global Git Arguments + +- User Option: magit-git-global-arguments :: + + The arguments set here are used every time the git executable is run + as a subprocess. They are placed right after the executable itself + and before the git command - as in ~git HERE... COMMAND REST~. For + valid arguments see [[man:git]] + + Be careful what you add here, especially if you are using Tramp to + connect to servers with ancient Git versions. Never remove anything + that is part of the default value, unless you really know what you + are doing. And think very hard before adding something; it will be + used every time Magit runs Git for any purpose. + +* Inspecting + +The functionality provided by Magit can be roughly divided into three +groups: inspecting existing data, manipulating existing data or adding +new data, and transferring data. Of course that is a rather crude +distinction that often falls short, but it's more useful than no +distinction at all. This section is concerned with inspecting data, +the next two with manipulating and transferring it. Then follows a +section about miscellaneous functionality, which cannot easily be fit +into this distinction. + +Of course other distinctions make sense too, e.g., Git's distinction +between porcelain and plumbing commands, which for the most part is +equivalent to Emacs' distinction between interactive commands and +non-interactive functions. All of the sections mentioned before are +mainly concerned with the porcelain -- Magit's plumbing layer is +described later. + +** Status Buffer + +While other Magit buffers contain, e.g., one particular diff or one +particular log, the status buffer contains the diffs for staged and +unstaged changes, logs for unpushed and unpulled commits, lists of +stashes and untracked files, and information related to the current +branch. + +During certain incomplete operations -- for example when a merge +resulted in a conflict -- additional information is displayed that +helps proceeding with or aborting the operation. + +The command ~magit-status~ displays the status buffer belonging to the +current repository in another window. This command is used so often +that it should be bound globally. We recommend using ~C-x g~: + +#+begin_src emacs-lisp + (global-set-key (kbd "C-x g") 'magit-status) +#+end_src + +- Key: C-x g (magit-status) :: + + When invoked from within an existing Git repository, then this + command shows the status of that repository in a buffer. + + If the current directory isn't located within a Git repository, then + this command prompts for an existing repository or an arbitrary + directory, depending on the option ~magit-repository-directories~, and + the status for the selected repository is shown instead. + + - If that option specifies any existing repositories, then the user + is asked to select one of them. + + - Otherwise the user is asked to select an arbitrary directory using + regular file-name completion. If the selected directory is the + top-level directory of an existing working tree, then the status + buffer for that is shown. + + - Otherwise the user is offered to initialize the selected directory + as a new repository. After creating the repository its status + buffer is shown. + + These fallback behaviors can also be forced using one or more + prefix arguments: + + - With two prefix arguments (or more precisely a numeric prefix + value of 16 or greater) an arbitrary directory is read, which is + then acted on as described above. The same could be accomplished + using the command ~magit-init~. + + - With a single prefix argument an existing repository is read from + the user, or if no repository can be found based on the value of + ~magit-repository-directories~, then the behavior is the same as with + two prefix arguments. + +- User Option: magit-repository-directories :: + + List of directories that are Git repositories or contain Git + repositories. + + Each element has the form ~(DIRECTORY . DEPTH)~. DIRECTORY has to be + a directory or a directory file-name, a string. DEPTH, an integer, + specifies the maximum depth to look for Git repositories. If it is + 0, then only add DIRECTORY itself. + + This option controls which repositories are being listed by + ~magit-list-repositories~. It also affects ~magit-status~ (which see) + in potentially surprising ways (see above). + +- Command: magit-status-quick :: + + This command is an alternative to ~magit-status~ that usually avoids + refreshing the status buffer. + + If the status buffer of the current Git repository exists but isn't + being displayed in the selected frame, then it is displayed without + being refreshed. + + If the status buffer is being displayed in the selected frame, + then this command refreshes it. + + Prefix arguments have the same meaning as for ~magit-status~, + and additionally cause the buffer to be refresh. + + To use this command add this to your init file: + + #+BEGIN_SRC emacs-lisp + (global-set-key (kbd "C-x g") 'magit-status-quick). + #+END_SRC + + If you do that and then for once want to redisplay the buffer and + also immediately refresh it, then type ~C-x g~ followed by ~g~. + + A possible alternative command is ~magit-display-repository-buffer~. + It supports displaying any existing Magit buffer that belongs to the + current repository; not just the status buffer. + +*** Status Sections + +The contents of status buffers is controlled using the hook +~magit-status-sections-hook~. See [[*Section Hooks]] to learn about such +hooks and how to customize them. + +- User Option: magit-status-sections-hook :: + + This hook is run to insert sections into a status buffer. + + The functions described in this section, and the functions + ~magit-insert-status-headers~ and ~magit-insert-untracked-files~, + which are described in subsequent sections, are members of this + hook. + + Some additional functions that can be added to this hook, but are by + default added to another hooks, are listed in [[*References Buffer]]. + +- Function: magit-insert-status-headers :: + + Insert header sections appropriate for ~magit-status-mode~ buffers. + The sections are inserted by running the functions on the hook + ~magit-status-headers-hook~. See [[*Status Header Sections]]. + +- Function: magit-insert-merge-log :: + + Insert section for the on-going merge. Display the heads that are + being merged. If no merge is in progress, do nothing. + +- Function: magit-insert-rebase-sequence :: + + Insert section for the on-going rebase sequence. + If no such sequence is in progress, do nothing. + +- Function: magit-insert-am-sequence :: + + Insert section for the on-going patch applying sequence. + If no such sequence is in progress, do nothing. + +- Function: magit-insert-sequencer-sequence :: + + Insert section for the on-going cherry-pick or revert sequence. + If no such sequence is in progress, do nothing. + +- Function: magit-insert-bisect-output :: + + While bisecting, insert section with output from ~git bisect~. + +- Function: magit-insert-bisect-rest :: + + While bisecting, insert section visualizing the bisect state. + +- Function: magit-insert-bisect-log :: + + While bisecting, insert section logging bisect progress. + +- Function: magit-insert-unstaged-changes :: + + Insert section showing unstaged changes. + +- Function: magit-insert-staged-changes :: + + Insert section showing staged changes. + +- Function: magit-insert-stashes &optional ref heading :: + + Insert the ~stashes~ section showing reflog for "refs/stash". + If optional REF is non-~nil~ show reflog for that instead. + If optional HEADING is non-~nil~ use that as section heading + instead of "Stashes:". + +- Function: magit-insert-unpulled-from-upstream :: + + Insert section showing commits that haven't been pulled from the + upstream branch yet. + +- Function: magit-insert-unpulled-from-pushremote :: + + Insert section showing commits that haven't been pulled from the + push-remote branch yet. + +- Function: magit-insert-unpushed-to-upstream-or-recent :: + + Insert section showing unpushed or other recent commits. + If an upstream is configured for the current branch and it is + behind of the current branch, then show the commits that have + not yet been pushed into the upstream branch. If no upstream is + configured or if the upstream is not behind of the current branch, + then show the last ~magit-log-section-commit-count~ commits. + +- Function: magit-insert-unpushed-to-upstream :: + + Insert section showing commits that haven't been pushed to the + upstream yet. + +- Function: magit-insert-unpushed-to-pushremote :: + + Insert section showing commits that haven't been pushed to the + push-remote yet. + +*** Status File List Sections + +These functions honor the buffer's file filter, which can be set using +~D - -~. + +- Function: magit-insert-untracked-files :: + + This function may insert a list of untracked files. Whether it + actually does so, depends on the option described next. + +- User Option: magit-status-show-untracked-files :: + + This option controls whether the above function inserts a list of + untracked files in the status buffer. + + - If ~nil~, do not list any untracked files. + - If ~t~, list untracked files, but if a directory does not contain any + tracked files, then only list that directory, not the contained + untracked files. + - If ~all~, then list each individual untracked files. This is can be + very slow and is discouraged. + + The corresponding values for the Git variable are "no", "normal" + and "all". + + To disable listing untracked files in a specific repository only, + add the following to ~.dir-locals.el~: + + #+begin_src emacs-lisp + ((magit-status-mode + (magit-status-show-untracked-files . "no"))) + #+end_src + + Alternatively (and mostly for historic reasons), it is possible to + use ~git config~ to set the repository-local value: + + #+begin_src shell-script + git config set --local status.showUntrackedFiles no + #+end_src + + This does *not* override the (if any) local value of this Lisp variable, + but it does override its global value. + + See the last section in the git-status(1) manpage, to speed up the part + of the work Git is responsible for. Turning that list into sections is + also not free, so Magit only lists ~magit-status-file-list-limit~ files. + +- User Option: magit-status-file-list-limit :: + + This option controls many files are listed at most in each section + that lists files in the status buffer. For performance reasons, it + is recommended that you do not increase this limit. + +While the above function is a member of ~magit-status-section-hook~ by +default, the following functions have to be explicitly added by the +user. Because that negatively affects performance, it is recommended +that you don't do that. + +- Function: magit-insert-tracked-files :: + + Insert a list of tracked files. + +- Function: magit-insert-ignored-files :: + + Insert a list of ignored files. + +- Function: magit-insert-skip-worktree-files :: + + Insert a list of skip-worktree files. + +- Function: magit-insert-assume-unchanged-files :: + + Insert a list of files that are assumed to be unchanged. + +*** Status Log Sections + +- Function: magit-insert-unpulled-or-recent-commits :: + + Insert section showing unpulled or recent commits. + If an upstream is configured for the current branch and it is + ahead of the current branch, then show the missing commits. + Otherwise, show the last ~magit-log-section-commit-count~ + commits. + +- Function: magit-insert-recent-commits :: + + Insert section showing the last ~magit-log-section-commit-count~ + commits. + +- User Option: magit-log-section-commit-count :: + + How many recent commits ~magit-insert-recent-commits~ and + ~magit-insert-unpulled-or-recent-commits~ (provided there are no + unpulled commits) show. + +- Function: magit-insert-unpulled-cherries :: + + Insert section showing unpulled commits. + Like ~magit-insert-unpulled-commits~ but prefix each commit + that has not been applied yet (i.e., a commit with a patch-id + not shared with any local commit) with "+", and all others + with "-". + +- Function: magit-insert-unpushed-cherries :: + + Insert section showing unpushed commits. + Like ~magit-insert-unpushed-commits~ but prefix each commit + which has not been applied to upstream yet (i.e., a commit with + a patch-id not shared with any upstream commit) with "+" and + all others with "-". + +*** Status Header Sections + +The contents of status buffers is controlled using the hook +~magit-status-sections-hook~ (see [[*Status Sections]]). + +By default ~magit-insert-status-headers~ is the first member of that +hook variable. + +- Function: magit-insert-status-headers :: + + Insert headers sections appropriate for ~magit-status-mode~ buffers. + The sections are inserted by running the functions on the hook + ~magit-status-headers-hook~. + +- User Option: magit-status-headers-hook :: + + Hook run to insert headers sections into the status buffer. + + This hook is run by ~magit-insert-status-headers~, which in turn has + to be a member of ~magit-status-sections-hook~ to be used at all. + +By default the following functions are members of the above hook: + +- Function: magit-insert-error-header :: + + Insert a header line showing the message about the Git error that + just occurred. + + This function is only aware of the last error that occur when Git + was run for side-effects. If, for example, an error occurs while + generating a diff, then that error won't be inserted. Refreshing + the status buffer causes this section to disappear again. + +- Function: magit-insert-diff-filter-header :: + + Insert a header line showing the effective diff filters. + +- Function: magit-insert-head-branch-header :: + + Insert a header line about the current branch or detached ~HEAD~. + +- Function: magit-insert-upstream-branch-header :: + + Insert a header line about the branch that is usually pulled into + the current branch. + +- Function: magit-insert-push-branch-header :: + + Insert a header line about the branch that the current branch is + usually pushed to. + +- Function: magit-insert-tags-header :: + + Insert a header line about the current and/or next tag, along with + the number of commits between the tag and ~HEAD~. + +The following functions can also be added to the above hook: + +- Function: magit-insert-repo-header :: + + Insert a header line showing the path to the repository top-level. + +- Function: magit-insert-remote-header :: + + Insert a header line about the remote of the current branch. + + If no remote is configured for the current branch, then fall back + showing the "origin" remote, or if that does not exist the first + remote in alphabetic order. + +- Function: magit-insert-user-header :: + + Insert a header line about the current user. + +*** Status Module Sections + +The contents of status buffers is controlled using the hook +~magit-status-sections-hook~ (see [[*Status Sections]]). + +By default ~magit-insert-modules~ is /not/ a member of that hook +variable. + +- Function: magit-insert-modules :: + + Insert submodule sections. + + Hook ~magit-module-sections-hook~ controls which module sections are + inserted, and option ~magit-module-sections-nested~ controls whether + they are wrapped in an additional section. + +- User Option: magit-module-sections-hook :: + + Hook run by ~magit-insert-modules~. + +- User Option: magit-module-sections-nested :: + + This option controls whether ~magit-insert-modules~ wraps inserted + sections in an additional section. + + If this is non-~nil~, then only a single top-level section is inserted. + If it is ~nil~, then all sections listed in ~magit-module-sections-hook~ + become top-level sections. + +- Function: magit-insert-modules-overview :: + + Insert sections for all submodules. For each section insert the + path, the branch, and the output of ~git describe --tags~, + or, failing that, the abbreviated HEAD commit hash. + + Press ~RET~ on such a submodule section to show its own status buffer. + Press ~RET~ on the "Modules" section to display a list of submodules + in a separate buffer. This shows additional information not + displayed in the super-repository's status buffer. + +- Function: magit-insert-modules-unpulled-from-upstream :: + + Insert sections for modules that haven't been pulled from the + upstream yet. These sections can be expanded to show the respective + commits. + +- Function: magit-insert-modules-unpulled-from-pushremote :: + + Insert sections for modules that haven't been pulled from the + push-remote yet. These sections can be expanded to show the + respective commits. + +- Function: magit-insert-modules-unpushed-to-upstream :: + + Insert sections for modules that haven't been pushed to the upstream + yet. These sections can be expanded to show the respective commits. + +- Function: magit-insert-modules-unpushed-to-pushremote :: + + Insert sections for modules that haven't been pushed to the + push-remote yet. These sections can be expanded to show the + respective commits. + +*** Status Options + +- User Option: magit-status-margin :: + + This option specifies whether the margin is initially shown in + Magit-Status mode buffers and how it is formatted. + + The value has the form ~(INIT STYLE WIDTH AUTHOR AUTHOR-WIDTH)~. + + - If INIT is non-~nil~, then the margin is shown initially. + - STYLE controls how to format the author or committer date. It can + be one of ~age~ (to show the age of the commit), ~age-abbreviated~ (to + abbreviate the time unit to a character), or a string (suitable + for ~format-time-string~) to show the actual date. Option + ~magit-log-margin-show-committer-date~ controls which date is being + displayed. + - WIDTH controls the width of the margin. This exists for forward + compatibility and currently the value should not be changed. + - AUTHOR controls whether the name of the author is also shown by + default. + - AUTHOR-WIDTH has to be an integer. When the name of the author + is shown, then this specifies how much space is used to do so. + +Also see the proceeding section for more options concerning status +buffers. + +** Repository List + +- Command: magit-list-repositories :: + + This command displays a list of repositories in a separate buffer. + + The option ~magit-repository-directories~ controls which repositories are + displayed. + +- User Option: magit-repolist-columns :: + + This option controls what columns are displayed by the command + ~magit-list-repositories~ and how they are displayed. + + Each element has the form ~(HEADER WIDTH FORMAT PROPS)~. + + HEADER is the string displayed in the header. WIDTH is the width + of the column. FORMAT is a function that is called with one + argument, the repository identification (usually its basename), + and with ~default-directory~ bound to the toplevel of its working + tree. It has to return a string to be inserted or ~nil~. PROPS is + an alist that supports the keys ~:right-align~, ~:pad-right~ and + ~:sort~. + + The ~:sort~ function has a weird interface described in the + docstring of ~tabulated-list--get-sort~. Alternatively ~<~ and + ~magit-repolist-version<~ can be used as those functions are + automatically replaced with functions that satisfy the interface. + Set ~:sort~ to ~nil~ to inhibit sorting; if unspecified, then the + column is sortable using the default sorter. + + You may wish to display a range of numeric columns using just one + character per column and without any padding between columns, in + which case you should use an appropriate HEADER, set WIDTH to 1, + and set ~:pad-right~ to 9. ~+~ is substituted for numbers higher than 9. + +#+texinfo: @noindent +The following functions can be added to the above option: + +- Function: magit-repolist-column-ident :: + + This function inserts the identification of the repository. Usually + this is just its basename. + +- Function: magit-repolist-column-path :: + + This function inserts the absolute path of the repository. + +- Function: magit-repolist-column-version :: + + This function inserts a description of the repository's ~HEAD~ revision. + +- Function: magit-repolist-column-branch :: + + This function inserts the name of the current branch. + +- Function: magit-repolist-column-upstream :: + + This function inserts the name of the upstream branch of the current + branch. + +- Function: magit-repolist-column-branches :: + + This function inserts the number of branches. + +- Function: magit-repolist-column-stashes :: + + This function inserts the number of stashes. + +- Function: magit-repolist-column-flag :: + + This function inserts a flag as specified by + ~magit-repolist-column-flag-alist~. + + By default this indicates whether there are uncommitted changes. + + - ~N~ if there is at least one untracked file. + - ~U~ if there is at least one unstaged file. + - ~S~ if there is at least one staged file. + + Only the first one of these that applies is shown. + +- Function: magit-repolist-column-flags :: + + This functions insert all flags as specified by + ~magit-repolist-column-flag-alist~. + + This is an alternative to function ~magit-repolist-column-flag~, + which only lists the first one found. + +- Function: magit-repolist-column-unpulled-from-upstream :: + + This function inserts the number of upstream commits not in the + current branch. + +- Function: magit-repolist-column-unpulled-from-pushremote :: + + This function inserts the number of commits in the push branch but + not the current branch. + +- Function: magit-repolist-column-unpushed-to-upstream :: + + This function inserts the number of commits in the current branch + but not its upstream. + +- Function: magit-repolist-column-unpushed-to-pushremote :: + + This function inserts the number of commits in the current branch + but not its push branch. + +#+texinfo: @noindent +The following commands are available in repolist buffers: + +- Key: RET (magit-repolist-status) :: + + This command shows the status for the repository at point. + +- Key: m (magit-repolist-mark) :: + + This command marks the repository at point. + +- Key: u (magit-repolist-unmark) :: + + This command unmarks the repository at point. + +- Key: f (magit-repolist-fetch) :: + + This command fetches all marked repositories. If no repositories + are marked, then it offers to fetch all displayed repositories. + +- Key: 5 (magit-repolist-find-file-other-frame) :: + + This command reads a relative file-name (without completion) and + opens the respective file in each marked repository in a new frame. + If no repositories are marked, then it offers to do this for all + displayed repositories. + +** Logging + +The status buffer contains logs for the unpushed and unpulled commits, +but that obviously isn't enough. The transient prefix command +~magit-log~, on ~l~, features several suffix commands, which show a +specific log in a separate log buffer. + +Like other transient prefix commands, ~magit-log~ also features several +infix arguments that can be changed before invoking one of the suffix +commands. However, in the case of the log transient, these arguments +may be taken from those currently in use in the current repository's +log buffer, depending on the value of ~magit-prefix-use-buffer-arguments~ +(see [[*Transient Arguments and Buffer Variables]]). + +For information about the various arguments, see [[man:git-log]] +The switch ~++order=VALUE~ is converted to one of ~--author-date-order~, +~--date-order~, or ~--topo-order~ before being passed to ~git log~. + +The log transient also features several reflog commands. See [[*Reflog]]. + +- Key: l (magit-log) :: + + This transient prefix command binds the following suffix commands + along with the appropriate infix arguments and displays them in a + temporary buffer until a suffix is invoked. + +- Key: l l (magit-log-current) :: + + Show log for the current branch. When ~HEAD~ is detached or with a + prefix argument, show log for one or more revs read from the + minibuffer. + +- Key: l h (magit-log-head) :: + + Show log for ~HEAD~. + +- Key: l u (magit-log-related) :: + + Show log for the current branch, its upstream and its push target. + When the upstream is a local branch, then also show its own + upstream. When ~HEAD~ is detached, then show log for that, the + previously checked out branch and its upstream and push-target. + +- Key: l o (magit-log-other) :: + + Show log for one or more revs read from the minibuffer. The user + can input any revision or revisions separated by a space, or even + ranges, but only branches, tags, and a representation of the + commit at point are available as completion candidates. + +- Key: l L (magit-log-branches) :: + + Show log for all local branches and ~HEAD~. + +- Key: l b (magit-log-all-branches) :: + + Show log for all local and remote branches and ~HEAD~. + +- Key: l a (magit-log-all) :: + + Show log for all references and ~HEAD~. + +Two additional commands that show the log for the file or blob that is +being visited in the current buffer exists, see [[*Commands for Buffers +Visiting Files]]. The command ~magit-cherry~ also shows a log, see +[[*Cherries]]. + +*** Refreshing Logs + +The transient prefix command ~magit-log-refresh~, on ~L~, can be used to +change the log arguments used in the current buffer, without changing +which log is shown. This works in dedicated log buffers, but also in +the status buffer. + +- Key: L (magit-log-refresh) :: + + This transient prefix command binds the following suffix commands + along with the appropriate infix arguments and displays them in a + temporary buffer until a suffix is invoked. + +- Key: L g (magit-log-refresh) :: + + This suffix command sets the local log arguments for the current + buffer. + +- Key: L s (magit-log-set-default-arguments) :: + + This suffix command sets the default log arguments for buffers of + the same type as that of the current buffer. Other existing buffers + of the same type are not affected because their local values have + already been initialized. + +- Key: L w (magit-log-save-default-arguments) :: + + This suffix command sets the default log arguments for buffers of + the same type as that of the current buffer, and saves the value for + future sessions. Other existing buffers of the same type are not + affected because their local values have already been initialized. + +- Key: L L (magit-toggle-margin) :: + + Show or hide the margin. + +*** Log Buffer + +- Key: L (magit-log-refresh) :: + + This transient prefix command binds the following suffix commands + along with the appropriate infix arguments and displays them in a + temporary buffer until a suffix is invoked. + + See [[*Refreshing Logs]]. + +- Key: q (magit-log-bury-buffer) :: + + Bury the current buffer or the revision buffer in the same frame. + Like ~magit-mode-bury-buffer~ (which see) but with a negative prefix + argument instead bury the revision buffer, provided it is displayed + in the current frame. + +- Key: C-c C-b (magit-go-backward) :: + + Move backward in current buffer's history. + +- Key: C-c C-f (magit-go-forward) :: + + Move forward in current buffer's history. + +- Key: C-c C-n (magit-log-move-to-parent) :: + + Move to a parent of the current commit. By default, this is the + first parent, but a numeric prefix can be used to specify another + parent. + +- Key: j (magit-log-move-to-revision) :: + + Read a revision and move to it in current log buffer. + + If the chosen reference or revision isn't being displayed in + the current log buffer, then inform the user about that and do + nothing else. + + If invoked outside any log buffer, then display the log buffer + of the current repository first; creating it if necessary. + +- Key: SPC (magit-diff-show-or-scroll-up) :: + + Update the commit or diff buffer for the thing at point. + + Either show the commit or stash at point in the appropriate buffer, + or if that buffer is already being displayed in the current frame + and contains information about that commit or stash, then instead + scroll the buffer up. If there is no commit or stash at point, then + prompt for a commit. + +- Key: DEL (magit-diff-show-or-scroll-down) :: + + Update the commit or diff buffer for the thing at point. + + Either show the commit or stash at point in the appropriate buffer, + or if that buffer is already being displayed in the current frame + and contains information about that commit or stash, then instead + scroll the buffer down. If there is no commit or stash at point, + then prompt for a commit. + +- Key: = (magit-log-toggle-commit-limit) :: + + Toggle the number of commits the current log buffer is limited to. + If the number of commits is currently limited, then remove that + limit. Otherwise set it to 256. + +- Key: + (magit-log-double-commit-limit) :: + + Double the number of commits the current log buffer is limited to. + +- Key: - (magit-log-half-commit-limit) :: + + Half the number of commits the current log buffer is limited to. + +- User Option: magit-log-auto-more :: + + Insert more log entries automatically when moving past the last + entry. Only considered when moving past the last entry with + ~magit-goto-*-section~ commands. + +- User Option: magit-log-show-refname-after-summary :: + + Whether to show the refnames after the commit summaries. This is + useful if you use really long branch names. + +- User Option: magit-log-show-color-graph-limit :: + + When showing more commits than specified by this option, then the + ~--color~ argument, if specified, is silently dropped. This is + necessary because the ~ansi-color~ library, which is used to turn + control sequences into faces, is just too slow. + +- User Option: magit-log-show-signatures-limit :: + + When showing more commits than specified by this option, then the + ~--show-signature~ argument, if specified, is silently dropped. This + is necessary because checking the signature of a large number of + commits is just too slow. + +Magit displays references in logs a bit differently from how Git does +it. + +Local branches are blue and remote branches are green. Of course that +depends on the used theme, as do the colors used for other types of +references. The current branch has a box around it, as do remote +branches that are their respective remote's ~HEAD~ branch. + +If a local branch and its push-target point at the same commit, then +their names are combined to preserve space and to make that +relationship visible. For example: + +#+begin_example + origin/feature + [green][blue-] + + instead of + + feature origin/feature + [blue-] [green-------] +#+end_example + +Also note that while the transient features the ~--show-signature~ +argument, that won't actually be used when enabled, because Magit +defaults to use just one line per commit. Instead the commit +colorized to indicate the validity of the signed commit object, +using the faces named ~magit-signature-*~ (which see). + +For a description of ~magit-log-margin~ see [[*Log Margin]]. + +*** Log Margin + +In buffers which show one or more logs, it is possible to show +additional information about each commit in the margin. The options +used to configure the margin are named ~magit-INFIX-margin~, where INFIX +is the same as in the respective major-mode ~magit-INFIX-mode~. In +regular log buffers that would be ~magit-log-margin~. + +- User Option: magit-log-margin :: + + This option specifies whether the margin is initially shown in + Magit-Log mode buffers and how it is formatted. + + The value has the form ~(INIT STYLE WIDTH AUTHOR AUTHOR-WIDTH)~. + + - If INIT is non-~nil~, then the margin is shown initially. + - STYLE controls how to format the author or committer date. It can + be one of ~age~ (to show the age of the commit), ~age-abbreviated~ (to + abbreviate the time unit to a character), or a string (suitable + for ~format-time-string~) to show the actual date. Option + ~magit-log-margin-show-committer-date~ controls which date is being + displayed. + - WIDTH controls the width of the margin. This exists for forward + compatibility and currently the value should not be changed. + - AUTHOR controls whether the name of the author is also shown by + default. + - AUTHOR-WIDTH has to be an integer. When the name of the author + is shown, then this specifies how much space is used to do so. + +You can change the STYLE and AUTHOR-WIDTH of all ~magit-INFIX-margin~ +options to the same values by customizing ~magit-log-margin~ *before* +~magit~ is loaded. If you do that, then the respective values for the +other options will default to what you have set for that variable. +Likewise if you set INIT in ~magit-log-margin~ to ~nil~, then that is used +in the default of all other options. But setting it to ~t~, i.e. +re-enforcing the default for that option, does not carry to other +options. + +- User Option: magit-log-margin-show-committer-date :: + + This option specifies whether to show the committer date in the + margin. This option only controls whether the committer date is + displayed instead of the author date. Whether some date is + displayed in the margin and whether the margin is displayed at all + is controlled by other options. + +- Key: L (magit-margin-settings) :: + + This transient prefix command binds the following suffix commands, + each of which changes the appearance of the margin in some way. + +In some buffers that support the margin, ~L~ is instead bound to +~magit-log-refresh~, but that transient features the same commands, and +then some other unrelated commands. + +- Key: L L (magit-toggle-margin) :: + + This command shows or hides the margin. + +- Key: L l (magit-cycle-margin-style) :: + + This command cycles the style used for the margin. + +- Key: L d (magit-toggle-margin-details) :: + + This command shows or hides details in the margin. + +*** Select from Log + +When the user has to select a recent commit that is reachable from +~HEAD~, using regular completion would be inconvenient (because most +humans cannot remember hashes or "HEAD~5", at least not without double +checking). Instead a log buffer is used to select the commit, which +has the advantage that commits are presented in order and with the +commit message. + +Such selection logs are used when selecting the beginning of a rebase +and when selecting the commit to be squashed into. + +In addition to the key bindings available in all log buffers, the +following additional key bindings are available in selection log +buffers: + +- Key: C-c C-c (magit-log-select-pick) :: + + Select the commit at point and act on it. Call + ~magit-log-select-pick-function~ with the selected commit as + argument. + +- Key: C-c C-k (magit-log-select-quit) :: + + Abort selecting a commit, don't act on any commit. + +- User Option: magit-log-select-margin :: + + This option specifies whether the margin is initially shown in + Magit-Log-Select mode buffers and how it is formatted. + + The value has the form ~(INIT STYLE WIDTH AUTHOR AUTHOR-WIDTH)~. + + - If INIT is non-~nil~, then the margin is shown initially. + - STYLE controls how to format the author or committer date. It can + be one of ~age~ (to show the age of the commit), ~age-abbreviated~ (to + abbreviate the time unit to a character), or a string (suitable + for ~format-time-string~) to show the actual date. Option + ~magit-log-margin-show-committer-date~ controls which date is being + displayed. + - WIDTH controls the width of the margin. This exists for forward + compatibility and currently the value should not be changed. + - AUTHOR controls whether the name of the author is also shown by + default. + - AUTHOR-WIDTH has to be an integer. When the name of the author + is shown, then this specifies how much space is used to do so. + +*** Reflog + +Also see [[man:git-reflog]] + +These reflog commands are available from the log transient. See +[[*Logging]]. + +- Key: l r (magit-reflog-current) :: + + Display the reflog of the current branch. + +- Key: l O (magit-reflog-other) :: + + Display the reflog of a branch or another ref. + +- Key: l H (magit-reflog-head) :: + + Display the ~HEAD~ reflog. + +- User Option: magit-reflog-margin :: + + This option specifies whether the margin is initially shown in + Magit-Reflog mode buffers and how it is formatted. + + The value has the form ~(INIT STYLE WIDTH AUTHOR AUTHOR-WIDTH)~. + + - If INIT is non-~nil~, then the margin is shown initially. + - STYLE controls how to format the author or committer date. It can + be one of ~age~ (to show the age of the commit), ~age-abbreviated~ (to + abbreviate the time unit to a character), or a string (suitable + for ~format-time-string~) to show the actual date. Option + ~magit-log-margin-show-committer-date~ controls which date is being + displayed. + - WIDTH controls the width of the margin. This exists for forward + compatibility and currently the value should not be changed. + - AUTHOR controls whether the name of the author is also shown by + default. + - AUTHOR-WIDTH has to be an integer. When the name of the author + is shown, then this specifies how much space is used to do so. + +*** Cherries + +Cherries are commits that haven't been applied upstream (yet), and are +usually visualized using a log. Each commit is prefixed with ~-~ if it +has an equivalent in the upstream and ~+~ if it does not, i.e., if it is +a cherry. + +The command ~magit-cherry~ shows cherries for a single branch, but the +references buffer (see [[*References Buffer]]) can show cherries for +multiple "upstreams" at once. + +Also see [[man:git-reflog]] + +- Key: Y (magit-cherry) :: + + Show commits that are in a certain branch but that have not been + merged in the upstream branch. + +- User Option: magit-cherry-margin :: + + This option specifies whether the margin is initially shown in + Magit-Cherry mode buffers and how it is formatted. + + The value has the form ~(INIT STYLE WIDTH AUTHOR AUTHOR-WIDTH)~. + + - If INIT is non-~nil~, then the margin is shown initially. + - STYLE controls how to format the author or committer date. It can + be one of ~age~ (to show the age of the commit), ~age-abbreviated~ (to + abbreviate the time unit to a character), or a string (suitable + for ~format-time-string~) to show the actual date. Option + ~magit-log-margin-show-committer-date~ controls which date is being + displayed. + - WIDTH controls the width of the margin. This exists for forward + compatibility and currently the value should not be changed. + - AUTHOR controls whether the name of the author is also shown by + default. + - AUTHOR-WIDTH has to be an integer. When the name of the author + is shown, then this specifies how much space is used to do so. + +** Diffing + +The status buffer contains diffs for the staged and unstaged commits, +but that obviously isn't enough. The transient prefix command +~magit-diff~, on ~d~, features several suffix commands, which show a +specific diff in a separate diff buffer. + +Like other transient prefix commands, ~magit-diff~ also features several +infix arguments that can be changed before invoking one of the suffix +commands. However, in the case of the diff transient, these arguments may +be taken from those currently in use in the current repository's diff +buffer, depending on the value of ~magit-prefix-use-buffer-arguments~ +(see [[*Transient Arguments and Buffer Variables]]). + +Also see [[man:git-diff]] + +- Key: d (magit-diff) :: + + This transient prefix command binds the following suffix commands + along with the appropriate infix arguments and displays them in a + temporary buffer until a suffix is invoked. + +- Key: d d (magit-diff-dwim) :: + + Show changes for the thing at point. + + For example, if point is on a commit, show the changes introduced by + that commit. Likewise if point is on the section titled "Unstaged + changes", then show those changes in a separate buffer. Generally + speaking, compare the thing at point with the most logical, trivial + and (in *any* situation) at least potentially useful other thing it + could be compared to. + + When the region selects commits, then compare the two commits at + either end. There are different ways two commits can be compared. + In the buffer showing the diff, you can control how the comparison, + is done, using "D r" and "D f". + + This function does not always show the changes that you might want + to view in any given situation. You can think of the changes being + shown as the smallest common denominator. There is no AI involved. + If this command never does what you want, then ignore it, and instead + use the commands that allow you to explicitly specify what you need. + +- Key: d r (magit-diff-range) :: + + Show differences between two commits. + + RANGE should be a range (A..B or A...B) but can also be a single + commit. If one side of the range is omitted, then it defaults to + ~HEAD~. If just a commit is given, then changes in the working tree + relative to that commit are shown. + + If the region is active, use the revisions on the first and last + line of the region. With a prefix argument, instead of diffing the + revisions, choose a revision to view changes along, starting at the + common ancestor of both revisions (i.e., use a "..." range). + +- Key: d w (magit-diff-working-tree) :: + + Show changes between the current working tree and the ~HEAD~ commit. + With a prefix argument show changes between the working tree and a + commit read from the minibuffer. + +- Key: d s (magit-diff-staged) :: + + Show changes between the index and the ~HEAD~ commit. With a prefix + argument show changes between the index and a commit read from the + minibuffer. + +- Key: d u (magit-diff-unstaged) :: + + Show changes between the working tree and the index. + +- Key: d p (magit-diff-paths) :: + + Show changes between any two files on disk. + +All of the above suffix commands update the repository's diff buffer. +The diff transient also features two commands which show differences +in another buffer: + +- Key: d c (magit-show-commit) :: + + Show the commit at point. If there is no commit at point or with a + prefix argument, prompt for a commit. + +- Key: d t (magit-stash-show) :: + + Show all diffs of a stash in a buffer. + +Two additional commands that show the diff for the file or blob that +is being visited in the current buffer exists, see [[*Commands for +Buffers Visiting Files]]. + +*** Refreshing Diffs + +The transient prefix command ~magit-diff-refresh~, on ~D~, can be used to +change the diff arguments used in the current buffer, without changing +which diff is shown. This works in dedicated diff buffers, but also +in the status buffer. + +(There is one exception; diff arguments cannot be changed in buffers +created by ~magit-merge-preview~ because the underlying Git command does +not support these arguments.) + +- Key: D (magit-diff-refresh) :: + + This transient prefix command binds the following suffix commands + along with the appropriate infix arguments and displays them in a + temporary buffer until a suffix is invoked. + +- Key: D g (magit-diff-refresh) :: + + This suffix command sets the local diff arguments for the current + buffer. + +- Key: D s (magit-diff-set-default-arguments) :: + + This suffix command sets the default diff arguments for buffers of + the same type as that of the current buffer. Other existing buffers + of the same type are not affected because their local values have + already been initialized. + +- Key: D w (magit-diff-save-default-arguments) :: + + This suffix command sets the default diff arguments for buffers of + the same type as that of the current buffer, and saves the value for + future sessions. Other existing buffers of the same type are not + affected because their local values have already been initialized. + +- Key: D t (magit-diff-toggle-refine-hunk) :: + + This command toggles hunk refinement on or off. + +- Key: D r (magit-diff-switch-range-type) :: + + This command converts the diff range type from "revA..revB" to + "revB...revA", or vice versa. + +- Key: D f (magit-diff-flip-revs) :: + + This command swaps revisions in the diff range from "revA..revB" + to "revB..revA", or vice versa. + +- Key: D F (magit-diff-toggle-file-filter) :: + + This command toggles the file restriction of the diffs in the + current buffer, allowing you to quickly switch between viewing all + the changes in the commit and the restricted subset. As a special + case, when this command is called from a log buffer, it toggles the + file restriction in the repository's revision buffer, which is + useful when you display a revision from a log buffer that is + restricted to a file or files. + +In addition to the above transient, which allows changing any of the +supported arguments, there also exist some commands that change only +a particular argument. + +- Key: - (magit-diff-less-context) :: + + This command decreases the context for diff hunks by COUNT lines. + +- Key: + (magit-diff-more-context) :: + + This command increases the context for diff hunks by COUNT lines. + +- Key: 0 (magit-diff-default-context) :: + + This command resets the context for diff hunks to the default height. + +The following commands quickly change what diff is being displayed +without having to using one of the diff transient. + +- Key: C-c C-d (magit-diff-while-committing) :: + + While committing, this command shows the changes that are about to + be committed. While amending, invoking the command again toggles + between showing just the new changes or all the changes that will be + committed. + + This binding is available in the diff buffer as well as the commit + message buffer. + +- Key: C-c C-b (magit-go-backward) :: + + This command moves backward in current buffer's history. + +- Key: C-c C-f (magit-go-forward) :: + + This command moves forward in current buffer's history. + +*** Commands Available in Diffs + +Some commands are only available if point is inside a diff. + +~magit-diff-visit-file~ and related commands visit the appropriate +version of the file that the diff at point is about. Likewise +~magit-diff-visit-worktree-file~ and related commands visit the worktree +version of the file that the diff at point is about. See [[*Visiting +Files and Blobs from a Diff]] for more information and the key bindings. + +- Key: C-c C-t (magit-diff-trace-definition) :: + + This command shows a log for the definition at point. + +- User Option: magit-log-trace-definition-function :: + + The function specified by this option is used by + ~magit-log-trace-definition~ to determine the function at point. For + major-modes that have special needs, you could set the local value + using the mode's hook. + +- Key: C-c C-e (magit-diff-edit-hunk-commit) :: + + From a hunk, this command edits the respective commit and visits + the file. + + First it visits the file being modified by the hunk at the correct + location using ~magit-diff-visit-file~. This actually visits a blob. + When point is on a diff header, not within an individual hunk, then + this visits the blob the first hunk is about. + + Then it invokes ~magit-edit-line-commit~, which uses an interactive + rebase to make the commit editable, or if that is not possible + because the commit is not reachable from ~HEAD~ by checking out that + commit directly. This also causes the actual worktree file to be + visited. + + Neither the blob nor the file buffer are killed when finishing + the rebase. If that is undesirable, then it might be better to + use ~magit-rebase-edit-commit~ instead of this command. + +- Key: j (magit-jump-to-diffstat-or-diff) :: + + This command jumps to the diffstat or diff. When point is on a file + inside the diffstat section, then jump to the respective diff + section. Otherwise, jump to the diffstat section or a child + thereof. + +The next two commands are not specific to Magit-Diff mode (or and +Magit buffer for that matter), but it might be worth pointing out +that they are available here too. + +- Key: SPC (scroll-up) :: + + This command scrolls text upward. + +- Key: DEL (scroll-down) :: + + This command scrolls text downward. + +*** Diff Options + +- User Option: magit-diff-refine-hunk :: + + Whether to show word-granularity differences within diff hunks. + + - ~nil~ Never show fine differences. + - ~all~ Show fine differences for all displayed diff hunks. + - ~t~ Refine each hunk once it becomes the current section. + Keep the refinement when another section is selected. + Refreshing the buffer removes all refinement. This + variant is only provided for performance reasons. + +- User Option: magit-diff-refine-ignore-whitespace :: + + Whether to ignore whitespace changes in word-granularity + differences. + +- User Option: magit-diff-adjust-tab-width :: + + Whether to adjust the width of tabs in diffs. + + Determining the correct width can be expensive if it requires + opening large and/or many files, so the widths are cached in the + variable ~magit-diff--tab-width-cache~. Set that to ~nil~ to invalidate + the cache. + + - ~nil~ Never adjust tab width. Use `tab-width's value from the Magit + buffer itself instead. + + - ~t~ If the corresponding file-visiting buffer exits, then use + ~tab-width~'s value from that buffer. Doing this is cheap, so this + value is used even if a corresponding cache entry exists. + + - ~always~ If there is no such buffer, then temporarily visit the file + to determine the value. + + - NUMBER Like ~always~, but don't visit files larger than NUMBER + bytes. + +- User Option: magit-diff-paint-whitespace :: + + Specify where to highlight whitespace errors. + + See ~magit-diff-highlight-trailing~, + ~magit-diff-highlight-indentation~. The symbol ~t~ means in all + diffs, ~status~ means only in the status buffer, and ~nil~ means + nowhere. + + - ~nil~ Never highlight whitespace errors. + - ~t~ Highlight whitespace errors everywhere. + - ~uncommitted~ Only highlight whitespace errors in diffs showing + uncommitted changes. For backward compatibility ~status~ is treated + as a synonym. + +- User Option: magit-diff-paint-whitespace-lines :: + + Specify in what kind of lines to highlight whitespace errors. + + - ~t~ Highlight only in added lines. + - ~both~ Highlight in added and removed lines. + - ~all~ Highlight in added, removed and context lines. + +- User Option: magit-diff-highlight-trailing :: + + Whether to highlight whitespace at the end of a line in diffs. Used + only when ~magit-diff-paint-whitespace~ is non-~nil~. + +- User Option: magit-diff-highlight-indentation :: + + This option controls whether to highlight the indentation in case it + used the "wrong" indentation style. Indentation is only highlighted + if ~magit-diff-paint-whitespace~ is also non-~nil~. + + The value is an alist of the form ~((REGEXP . INDENT)...)~. The path + to the current repository is matched against each element in reverse + order. Therefore if a REGEXP matches, then earlier elements are not + tried. + + If the used INDENT is ~tabs~, highlight indentation with tabs. If + INDENT is an integer, highlight indentation with at least that many + spaces. Otherwise, highlight neither. + +- User Option: magit-diff-hide-trailing-cr-characters :: + + Whether to hide ^M characters at the end of a line in diffs. + +- User Option: magit-diff-highlight-hunk-region-functions :: + + This option specifies the functions used to highlight the + hunk-internal region. + + ~magit-diff-highlight-hunk-region-dim-outside~ overlays the outside of + the hunk internal selection with a face that causes the added and + removed lines to have the same background color as context lines. + This function should not be removed from the value of this option. + + ~magit-diff-highlight-hunk-region-using-overlays~ and + ~magit-diff-highlight-hunk-region-using-underline~ emphasize the + region by placing delimiting horizontal lines before and after it. + Both of these functions have glitches which cannot be fixed due to + limitations of Emacs' display engine. For more information see + https://github.com/magit/magit/issues/2758 ff. + + Instead of, or in addition to, using delimiting horizontal lines, + to emphasize the boundaries, you may wish to emphasize the text + itself, using ~magit-diff-highlight-hunk-region-using-face~. + + In terminal frames it's not possible to draw lines as the overlay + and underline variants normally do, so there they fall back to + calling the face function instead. + +- User Option: magit-diff-unmarked-lines-keep-foreground :: + + This option controls whether added and removed lines outside the + hunk-internal region only lose their distinct background color or + also the foreground color. Whether the outside of the region is + dimmed at all depends on ~magit-diff-highlight-hunk-region-functions~. + +- User Option: magit-diff-extra-stat-arguments :: + + This option specifies additional arguments to be used alongside + ~--stat~. + + The value is a list of zero or more arguments or a function that + takes no argument and returns such a list. These arguments are + allowed here: ~--stat-width~, ~--stat-name-width~, + ~--stat-graph-width~ and ~--compact-summary~. Also see [[man:git-diff]] + +- User Option: magit-format-file-function :: + + This function is used to format lines representing a file. It is + used for file headings in diffs, in diffstats and for lists of files + (such as the untracked files). Depending on the caller, it receives + either three or five arguments; the signature has to be ~(kind file + face &optional status orig)~. KIND is one of ~diff~, ~module~, ~stat~ and + ~list~. + +*** Revision Buffer + +- User Option: magit-revision-insert-related-refs :: + + Whether to show related branches in revision buffers. + + - ~nil~ Don't show any related branches. + - ~t~ Show related local branches. + - ~all~ Show related local and remote branches. + - ~mixed~ Show all containing branches and local merged branches. + +- User Option: magit-revision-show-gravatars :: + + Whether to show gravatar images in revision buffers. + + If ~nil~, then don't insert any gravatar images. If ~t~, then insert + both images. If ~author~ or ~committer~, then insert only the + respective image. + + If you have customized the option ~magit-revision-headers-format~ + and want to insert the images then you might also have to specify + where to do so. In that case the value has to be a cons-cell of + two regular expressions. The car specifies where to insert the + author's image. The top half of the image is inserted right + after the matched text, the bottom half on the next line in the + same column. The cdr specifies where to insert the committer's + image, accordingly. Either the car or the cdr may be ~nil~." + +- User Option: magit-revision-use-hash-sections :: + + Whether to turn hashes inside the commit message into sections. + + If non-~nil~, then hashes inside the commit message are turned into + ~commit~ sections. There is a trade off to be made between + performance and reliability: + + - ~slow~ calls git for every word to be absolutely sure. + - ~quick~ skips words less than seven characters long. + - ~quicker~ additionally skips words that don't contain a number. + - ~quickest~ uses all words that are at least seven characters long + and which contain at least one number as well as at least one + letter. + + If ~nil~, then no hashes are turned into sections, but you can still + visit the commit at point using "RET". + +The diffs shown in the revision buffer may be automatically restricted +to a subset of the changed files. If the revision buffer is displayed +from a log buffer, the revision buffer will share the same file +restriction as that log buffer (also see the command +~magit-diff-toggle-file-filter~). + +- User Option: magit-revision-filter-files-on-follow :: + + Whether showing a commit from a log buffer honors the log's file + filter when the log arguments include ~--follow~. + + When this option is ~nil~, displaying a commit from a log ignores the + log's file filter if the log arguments include ~--follow~. Doing so + avoids showing an empty diff in revision buffers for commits before + a rename event. In such cases, the ~--patch~ argument of the log + transient can be used to show the file-restricted diffs inline. + + Set this option to non-~nil~ to keep the log's file restriction even + if ~--follow~ is present in the log arguments. + +If the revision buffer is not displayed from a log buffer, the file +restriction is determined as usual (see [[*Transient Arguments and +Buffer Variables]]). + +** Ediffing + +This section describes how to enter Ediff from Magit buffers. For +information on how to use Ediff itself, see info:ediff. + +- Key: e (magit-ediff-dwim) :: + + Compare, stage, or resolve using Ediff. + + This command tries to guess what file, and what commit or range the + user wants to compare, stage, or resolve using Ediff. It might only + be able to guess either the file, or range/commit, in which case + the user is asked about the other. It might not always guess right, + in which case the appropriate ~magit-ediff-*~ command has to be used + explicitly. If it cannot read the user's mind at all, then it asks + the user for a command to run. + +- Key: E (magit-ediff) :: + + This transient prefix command binds the following suffix commands + and displays them in a temporary buffer until a suffix is invoked. + +- Key: E r (magit-ediff-compare) :: + + Compare two revisions of a file using Ediff. + + If the region is active, use the revisions on the first and last + line of the region. With a prefix argument, instead of diffing the + revisions, choose a revision to view changes along, starting at the + common ancestor of both revisions (i.e., use a "..." range). + +- Key: E m (magit-ediff-resolve-rest) :: + + This command allows you to resolve outstanding conflicts in the file + at point using Ediff. If there is no file at point or if it doesn't + have any unmerged changes, then this command prompts for a file. + + Provided that the value of ~merge.conflictstyle~ is ~diff3~, you can + view the file's merge-base revision using ~/~ in the Ediff control + buffer. + + The A, B and Ancestor buffers are constructed from the conflict + markers in the worktree file. Because you and/or Git may have + already resolved some conflicts, that means that these buffers + may not contain the actual versions from the respective blobs. + +- Key: E M (magit-ediff-resolve-all) :: + + This command allows you to resolve all conflicts in the file at + point using Ediff. If there is no file at point or if it doesn't + have any unmerged changes, then this command prompts for a file. + + Provided that the value of ~merge.conflictstyle~ is ~diff3~, you can + view the file's merge-base revision using ~/~ in the Ediff control + buffer. + + First the file in the worktree is moved aside, appending the suffix + =.ORIG=, so that you could later go back to that version. Then it is + reconstructed from the two sides of the conflict and the merge-base, + if available. + + It would be nice if the worktree file were just used as-is, but + Ediff does not support that. This means that all conflicts, that + Git has already resolved, are restored. On the other hand Ediff + also tries to resolve conflicts, and in many cases Ediff and Git + should produce similar results. + + However if you have already resolved some conflicts manually, then + those changes are discarded (though you can recover them from the + backup file). In such cases ~magit-ediff-resolve-rest~ might be more + suitable. + + The advantage that this command has over ~magit-ediff-resolve-rest~ + is that the A, B and Ancestor buffers correspond to blobs from the + respective commits, allowing you to inspect a side in context and + to use Magit commands in these buffers to do so. Blame and log + commands are particularly useful here. + +- Key: E t (magit-git-mergetool) :: + + This command does not actually use Ediff. While it serves the same + purpose as =magit-ediff-resolve-rest=, it uses =git mergetool --gui= to + resolve conflicts. + + With a prefix argument this acts as a transient prefix command, + allowing the user to select the mergetool and change some settings. + +- Key: E s (magit-ediff-stage) :: + + Stage and unstage changes to a file using Ediff, defaulting to the + file at point. + +- Key: E u (magit-ediff-show-unstaged) :: + + Show unstaged changes to a file using Ediff. + +- Key: E i (magit-ediff-show-staged) :: + + Show staged changes to a file using Ediff. + +- Key: E w (magit-ediff-show-working-tree) :: + + Show changes in a file between ~HEAD~ and working tree using Ediff. + +- Key: E c (magit-ediff-show-commit) :: + + Show changes to a file introduced by a commit using Ediff. + +- Key: E z (magit-ediff-show-stash) :: + + Show changes to a file introduced by a stash using Ediff. + +- User Option: magit-ediff-dwim-resolve-function :: + + This option controls which function ~magit-ediff-dwim~ uses to resolve + conflicts. One of ~magit-ediff-resolve-rest~, ~magit-ediff-resolve-all~ + or ~magit-git-mergetool~; which are all discussed above. + +- User Option: magit-ediff-dwim-show-on-hunks :: + + This option controls what command ~magit-ediff-dwim~ calls when + point is on uncommitted hunks. When ~nil~, always run + ~magit-ediff-stage~. Otherwise, use ~magit-ediff-show-staged~ and + ~magit-ediff-show-unstaged~ to show staged and unstaged changes, + respectively. + +- User Option: magit-ediff-show-stash-with-index :: + + This option controls whether ~magit-ediff-show-stash~ includes a + buffer containing the file's state in the index at the time the + stash was created. This makes it possible to tell which changes in + the stash were staged. + +- User Option: magit-ediff-quit-hook :: + + This hook is run after quitting an Ediff session that was created + using a Magit command. The hook functions are run inside the Ediff + control buffer, and should not change the current buffer. + + This is similar to ~ediff-quit-hook~ but takes the needs of Magit into + account. The regular ~ediff-quit-hook~ is ignored by Ediff sessions + that were created using a Magit command. + +** References Buffer + +- Key: y (magit-show-refs) :: + + This command lists branches and tags in a dedicated buffer. + + However if this command is invoked again from this buffer or if it + is invoked with a prefix argument, then it acts as a transient + prefix command, which binds the following suffix commands and some + infix arguments. + +All of the following suffix commands list exactly the same branches +and tags. The only difference the optional feature that can be +enabled by changing the value of ~magit-refs-show-commit-count~ (see +below). These commands specify a different branch or commit against +which all the other references are compared. + +- Key: y y (magit-show-refs-head) :: + + This command lists branches and tags in a dedicated buffer. Each + reference is being compared with ~HEAD~. + +- Key: y c (magit-show-refs-current) :: + + This command lists branches and tags in a dedicated buffer. Each + reference is being compared with the current branch or ~HEAD~ if it + is detached. + +- Key: y o (magit-show-refs-other) :: + + This command lists branches and tags in a dedicated buffer. Each + reference is being compared with a branch read from the user. + +- Key: y r (magit-refs-set-show-commit-count) :: + + This command changes for which refs the commit count is shown. + +- User Option: magit-refs-show-commit-count :: + + Whether to show commit counts in Magit-Refs mode buffers. + + - ~all~ Show counts for branches and tags. + - ~branch~ Show counts for branches only. + - ~nil~ Never show counts. + + The default is ~nil~ because anything else can be very expensive. + +- User Option: magit-refs-pad-commit-counts :: + + Whether to pad all commit counts on all sides in Magit-Refs mode + buffers. + + If this is ~nil~, then some commit counts are displayed right next to + one of the branches that appear next to the count, without any space + in between. This might look bad if the branch name faces look too + similar to ~magit-dimmed~. + + If this is non-~nil~, then spaces are placed on both sides of all + commit counts. + +- User Option: magit-refs-show-remote-prefix :: + + Whether to show the remote prefix in lists of remote branches. + + Showing the prefix is redundant because the name of the remote is + already shown in the heading preceding the list of its branches. + +- User Option: magit-refs-primary-column-width :: + + Width of the primary column in `magit-refs-mode' buffers. The + primary column is the column that contains the name of the branch + that the current row is about. + + If this is an integer, then the column is that many columns wide. + Otherwise it has to be a cons-cell of two integers. The first + specifies the minimal width, the second the maximal width. In that + case the actual width is determined using the length of the names of + the shown local branches. (Remote branches and tags are not taken + into account when calculating to optimal width.) + +- User Option: magit-refs-focus-column-width :: + + Width of the focus column in `magit-refs-mode' buffers. + + The focus column is the first column, which marks one branch + (usually the current branch) as the focused branch using ~*~ or ~@~. + For each other reference, this column optionally shows how many + commits it is ahead of the focused branch and ~<~, or if it isn't + ahead then the commits it is behind and ~>~, or if it isn't behind + either, then a ~=~. + + This column may also display only ~*~ or ~@~ for the focused branch, in + which case this option is ignored. Use ~L v~ to change the verbosity + of this column. + +- User Option: magit-refs-margin :: + + This option specifies whether the margin is initially shown in + Magit-Refs mode buffers and how it is formatted. + + The value has the form ~(INIT STYLE WIDTH AUTHOR AUTHOR-WIDTH)~. + + - If INIT is non-~nil~, then the margin is shown initially. + - STYLE controls how to format the author or committer date. It can + be one of ~age~ (to show the age of the commit), ~age-abbreviated~ (to + abbreviate the time unit to a character), or a string (suitable + for ~format-time-string~) to show the actual date. Option + ~magit-log-margin-show-committer-date~ controls which date is being + displayed. + - WIDTH controls the width of the margin. This exists for forward + compatibility and currently the value should not be changed. + - AUTHOR controls whether the name of the author is also shown by + default. + - AUTHOR-WIDTH has to be an integer. When the name of the author + is shown, then this specifies how much space is used to do so. + +- User Option: magit-refs-margin-for-tags :: + + This option specifies whether to show information about tags in the + margin. This is disabled by default because it is slow if there are + many tags. + +The following variables control how individual refs are displayed. If +you change one of these variables (especially the "%c" part), then you +should also change the others to keep things aligned. The following +%-sequences are supported: + +- ~%a~ Number of commits this ref has over the one we compare to. +- ~%b~ Number of commits the ref we compare to has over this one. +- ~%c~ Number of commits this ref has over the one we compare to. For + the ref which all other refs are compared this is instead "@", if + it is the current branch, or "#" otherwise. +- ~%C~ For the ref which all other refs are compared this is "@", if it + is the current branch, or "#" otherwise. For all other refs " ". +- ~%h~ Hash of this ref's tip. +- ~%m~ Commit summary of the tip of this ref. +- ~%n~ Name of this ref. +- ~%u~ Upstream of this local branch. +- ~%U~ Upstream of this local branch and additional local vs. upstream + information. + +# new list +- User Option: magit-refs-filter-alist :: + + The purpose of this option is to forgo displaying certain refs + based on their name. If you want to not display any refs of a + certain type, then you should remove the appropriate function + from ~magit-refs-sections-hook~ instead. + + This alist controls which tags and branches are omitted from being + displayed in ~magit-refs-mode~ buffers. If it is ~nil~, then all refs + are displayed (subject to ~magit-refs-sections-hook~). + + All keys are tried in order until one matches. Then its value is + used and subsequent elements are ignored. If the value is non-~nil~, + then the reference is displayed, otherwise it is not. If no element + matches, then the reference is displayed. + + A key can either be a regular expression that the refname has to + match, or a function that takes the refname as only argument and + returns a boolean. A remote branch such as "origin/master" is + displayed as just "master", however for this comparison the + former is used. + +- Key: RET (magit-visit-ref) :: + + This command visits the reference or revision at point in another + buffer. If there is no revision at point or with a prefix argument + then it prompts for a revision. + + This command behaves just like ~magit-show-commit~ as described above, + except if point is on a reference in a ~magit-refs-mode~ buffer, in + which case the behavior may be different, but only if you have + customized the option ~magit-visit-ref-behavior~. + +- User Option: magit-visit-ref-behavior :: + + This option controls how ~magit-visit-ref~ behaves in ~magit-refs-mode~ + buffers. + + By default ~magit-visit-ref~ behaves like ~magit-show-commit~, in all + buffers, including ~magit-refs-mode~ buffers. When the type of the + section at point is ~commit~ then "RET" is bound to ~magit-show-commit~, + and when the type is either ~branch~ or ~tag~ then it is bound to + ~magit-visit-ref~. + + "RET" is one of Magit's most essential keys and at least by default + it should behave consistently across all of Magit, especially + because users quickly learn that it does something very harmless; it + shows more information about the thing at point in another buffer. + + However "RET" used to behave differently in ~magit-refs-mode~ buffers, + doing surprising things, some of which cannot really be described as + "visit this thing". If you've grown accustomed this behavior, you + can restore it by adding one or more of the below symbols to the + value of this option. But keep in mind that by doing so you don't + only introduce inconsistencies, you also lose some functionality and + might have to resort to ~M-x magit-show-commit~ to get it back. + + ~magit-visit-ref~ looks for these symbols in the order in which they + are described here. If the presence of a symbol applies to the + current situation, then the symbols that follow do not affect the + outcome. + + - ~focus-on-ref~ + + With a prefix argument update the buffer to show commit counts + and lists of cherry commits relative to the reference at point + instead of relative to the current buffer or ~HEAD~. + + Instead of adding this symbol, consider pressing "C-u y o RET". + + - ~create-branch~ + + If point is on a remote branch, then create a new local branch + with the same name, use the remote branch as its upstream, and + then check out the local branch. + + Instead of adding this symbol, consider pressing "b c RET RET", + like you would do in other buffers. + + - ~checkout-any~ + + Check out the reference at point. If that reference is a tag + or a remote branch, then this results in a detached ~HEAD~. + + Instead of adding this symbol, consider pressing "b b RET", + like you would do in other buffers. + + - ~checkout-branch~ + + Check out the local branch at point. + + Instead of adding this symbol, consider pressing "b b RET", + like you would do in other buffers. + +*** References Sections + +The contents of references buffers is controlled using the hook +~magit-refs-sections-hook~. See [[*Section Hooks]] to learn about such hooks +and how to customize them. All of the below functions are members of +the default value. Note that it makes much less sense to customize +this hook than it does for the respective hook used for the status +buffer. + +- User Option: magit-refs-sections-hook :: + + Hook run to insert sections into a references buffer. + +- Function: magit-insert-local-branches :: + + Insert sections showing all local branches. + +- Function: magit-insert-remote-branches :: + + Insert sections showing all remote-tracking branches. + +- Function: magit-insert-tags :: + + Insert sections showing all tags. + +** Bisecting + +Also see [[man:git-bisect]] + +- Key: B (magit-bisect) :: + + This transient prefix command binds the following suffix commands + and displays them in a temporary buffer until a suffix is invoked. + +When bisecting is not in progress, then the transient features the +following suffix commands. + +- Key: B B (magit-bisect-start) :: + + Start a bisect session. + + Bisecting a bug means to find the commit that introduced it. + This command starts such a bisect session by asking for a known + good commit and a known bad commit. If you're bisecting a change + that isn't a regression, you can select alternate terms that are + conceptually more fitting than "bad" and "good", but the infix + arguments to do so are disabled by default. + +- Key: B s (magit-bisect-run) :: + + Bisect automatically by running commands after each step. + +When bisecting in progress, then the transient instead features the +following suffix commands. + +- Key: B b (magit-bisect-bad) :: + + Mark the current commit as bad. Use this after you have asserted + that the commit does contain the bug in question. + +- Key: B g (magit-bisect-good) :: + + Mark the current commit as good. Use this after you have asserted + that the commit does not contain the bug in question. + +- Key: B m (magit-bisect-mark) :: + + Mark the current commit with one of the bisect terms. This command + provides an alternative to ~magit-bisect-bad~ and + ~magit-bisect-good~ and is useful when using terms other than "bad" + and "good". This suffix is disabled by default. + +- Key: B k (magit-bisect-skip) :: + + Skip the current commit. Use this if for some reason the current + commit is not a good one to test. This command lets Git choose a + different one. + +- Key: B r (magit-bisect-reset) :: + + After bisecting, cleanup bisection state and return to original + ~HEAD~. + +By default the status buffer shows information about the ongoing +bisect session. + +- User Option: magit-bisect-show-graph :: + + This option controls whether a graph is displayed for the log of + commits that still have to be bisected. + +** Visiting Files and Blobs + +Magit provides several commands that visit a file or blob (the version +of a file that is stored in a certain commit). Actually it provides +several *groups* of such commands and the several *variants* within each +group. + +Also see [[*Commands for Buffers Visiting Files]]. + +*** General-Purpose Visit Commands + +These commands can be used anywhere to open any blob. Currently no +keys are bound to these commands by default, but that is likely to +change. + +- Command: magit-find-file :: + + This command reads a filename and revision from the user and visits + the respective blob in a buffer. The buffer is displayed in the + selected window. + +- Command: magit-find-file-other-window :: + + This command reads a filename and revision from the user and visits + the respective blob in a buffer. The buffer is displayed in another + window. + +- Command: magit-find-file-other-frame :: + + This command reads a filename and revision from the user and visits + the respective blob in a buffer. The buffer is displayed in another + frame. + +*** Visiting Files and Blobs from a Diff + +These commands can only be used when point is inside a diff. +Elsewhere use ~magit-find-file~. + +- Key: RET (magit-diff-visit-file) :: + + This command visits the appropriate version of the file at point. + + Display the buffer in the selected window. With a prefix argument, + OTHER-WINDOW, instead display the buffer in another window. + + In the visited file or blob, go to the location corresponding to the + location in the diff. + + If point is on an added or context line, visit the blob corresponding + to our side (i.e., the new/right side). If point is on a removed line, + visit the blob corresponding to their side (i.e., the old/left side). + + This applies to diffs of staged and unstaged changes as well. For + staged changes the two sides are blobs from the index and the `HEAD' + commit. For unstaged changes the two sides are the actual file in + the worktree and the blob from the index. + + To visit the file in the worktree, regardless of what the current + diff is about, use ~magit-diff-visit-worktree-file~, described next. + +- Key: C- (magit-diff-visit-worktree-file) :: + + This command visits the worktree version of the appropriate file. + The location of point inside the diff determines which file is being + visited. Unlike ~magit-diff-visit-file~ it always visits the "real" + file in the working tree, i.e., the "current version" of the file. + + In the file-visiting buffer this command goes to the line that + corresponds to the line that point is on in the diff. Lines that + were added or removed in the working tree, the index and other + commits in between are automatically accounted for. + + The buffer is displayed in the selected window. With a prefix + argument the buffer is displayed in another window instead. + +Variants of the above two commands exist that instead visit the file +in another window or in another frame. If you prefer such behavior, +then you may want to change the above key bindings, but note that the +above commands also use another window when invoked with a prefix +argument. + +- Command: magit-diff-visit-file-other-window :: +- Command: magit-diff-visit-file-other-frame :: +- Command: magit-diff-visit-worktree-file-other-window :: +- Command: magit-diff-visit-worktree-file-other-frame :: + + These commands behave like the respective commands described above, + except that they display the blob or file in another window or frame. + +- User Option: magit-diff-visit-prefer-worktree :: + + This option controls whether ~magit-diff-visit-file~ always visits the + respective file in the worktree, when invoked anywhere from within a + hunk of staged or unstaged changes. + + By default ~magit-diff-visit-file~ does not do that. Instead it + behaves for staged and unstaged changes as it does for committed + changes, by visiting a blob from the old/left or new/right side, + depending on whether point is on a removed line or not. + + For staged changes the old side is the blob from HEAD and the right + side is the blog from the index. For unstaged changes the left side + is the blob from the index (if there are any changes in the index + for that file, else the blob from HEAD), and the right side is the + file in the worktree. + + Being able to jump to HEAD or the index from a removed line is very + useful, because it allows you to, e.g., use blame to investigate why + some line, which you have already removed, was added in the first + place. + + But if you want to make further changes to already staged changes, + you of course instead need to go to the respective file in the + worktree. The command ~magit-diff-visit-worktree-file~ was created + for that purpose, and it is strongly recommend that you make use of + that command, even if you initially find it inconvenient having to + remember to use ~C-~ instead of ~RET~ in this case. + + While discouraged, you can alternatively set this option to ~t~, + which causes ~magit-diff-visit-file~ itself to go to the file in the + worktree, even when invoked from within a hunk of staged changes. + If you do that, you lose the ability to instantly go to lines you + have already removed. + +- User Option: magit-diff-visit-previous-blob :: + + This option controls whether ~magit-diff-visit-file~ visits the + previous blob when invoked with point on a removed line. + + When this is ~t~ (the default) and point is on a removed line, then + ~magit-diff-visit-file~ visits the blob from the old/left commit, + which still has that line, instead of going to the new/right blob, + which removes that line. + + Setting this to ~nil~, causes ~magit-diff-visit-file~ to always go to + the new/right blob, even when point is on a removed line. This is + very strongly discouraged. Instead place the cursor anywhere else + within the hunk but on a removed line, if you want to visit the new + side. That way you don't lose the ability to visit the old side. + +** Blaming + +Also see [[man:git-blame]] + +To start blaming, invoke the ~magit-file-dispatch~ transient prefix +command. When using the default key bindings, that can be done +by pressing ~C-c M-g~. When using the recommended bindings, this +command is instead bound to ~C-c f~. Also see [[*Global Bindings]]. + +The blaming suffix commands can be invoked directly from the file +dispatch transient. However if you want to set an infix argument, +then you have to enter the blaming sub-prefix first. + +- Key: C-c f B (magit-blame) :: +- Key: C-c f b (magit-blame-addition) :: +- Key: C-c f B b :: +- Key: C-c f r (magit-blame-removal) :: +- Key: C-c f B r :: +- Key: C-c f f (magit-blame-reverse) :: +- Key: C-c f B f :: +- Key: C-c f e (magit-blame-echo) :: +- Key: C-c f B e :: +- Key: C-c f q (magit-blame-quit) :: +- Key: C-c f B q :: + + Each of these commands is documented individually right below, + alongside their default key bindings. The bindings shown above + are the recommended bindings, which you can enable by following + the instructions in [[*Global Bindings]]. + +- Key: C-c M-g B (magit-blame) :: + + This transient prefix command binds the following suffix commands + along with the appropriate infix arguments and displays them in a + temporary buffer until a suffix is invoked. + +Note that not all of the following suffixes are available at all +times. For example if ~magit-blame-mode~ is not enabled, then the +command whose purpose is to turn off that mode would not be of any +use and therefore isn't available. + +- Key: C-c M-g b (magit-blame-addition) :: +- Key: C-c M-g B b :: + + This command augments each line or chunk of lines in the current + file-visiting or blob-visiting buffer with information about what + commits last touched these lines. + + If the buffer visits a revision of that file, then history up to + that revision is considered. Otherwise, the file's full history is + considered, including uncommitted changes. + + If Magit-Blame mode is already turned on in the current buffer then + blaming is done recursively, by visiting REVISION:FILE (using + ~magit-find-file~), where REVISION is a parent of the revision that + added the current line or chunk of lines. + +- Key: C-c M-g r (magit-blame-removal) :: +- Key: C-c M-g B r :: + + This command augments each line or chunk of lines in the current + blob-visiting buffer with information about the revision that + removes it. It cannot be used in file-visiting buffers. + + Like ~magit-blame-addition~, this command can be used recursively. + +- Key: C-c M-g f (magit-blame-reverse) :: +- Key: C-c M-g B f :: + + This command augments each line or chunk of lines in the current + file-visiting or blob-visiting buffer with information about the + last revision in which a line still existed. + + Like ~magit-blame-addition~, this command can be used recursively. + +- Key: C-c M-g e (magit-blame-echo) :: +- Key: C-c M-g B e :: + + This command is like ~magit-blame-addition~ except that it doesn't + turn on ~read-only-mode~ and that it initially uses the visualization + style specified by option ~magit-blame-echo-style~. + +The following key bindings are available when Magit-Blame mode is +enabled and Read-Only mode is not enabled. These commands are also +available in other buffers; here only the behavior is described that +is relevant in file-visiting buffers that are being blamed. + +- Key: C-c M-g q (magit-blame-quit) :: +- Key: C-c M-g B q :: + + This command turns off Magit-Blame mode. If the buffer was created + during a recursive blame, then it also kills the buffer. + +- Key: RET (magit-show-commit) :: + + This command shows the commit that last touched the line at point. + +- Key: SPC (magit-diff-show-or-scroll-up) :: + + This command updates the commit buffer. + + This either shows the commit that last touched the line at point in + the appropriate buffer, or if that buffer is already being displayed + in the current frame and if that buffer contains information about + that commit, then the buffer is scrolled up instead. + +- Key: DEL (magit-diff-show-or-scroll-down) :: + + This command updates the commit buffer. + + This either shows the commit that last touched the line at point in + the appropriate buffer, or if that buffer is already being displayed + in the current frame and if that buffer contains information about + that commit, then the buffer is scrolled down instead. + +The following key bindings are available when both Magit-Blame mode +and Read-Only mode are enabled. + +- Key: b (magit-blame) :: + + See above. + +- Key: n (magit-blame-next-chunk) :: + + This command moves to the next chunk. + +- Key: N (magit-blame-next-chunk-same-commit) :: + + This command moves to the next chunk from the same commit. + +- Key: p (magit-blame-previous-chunk) :: + + This command moves to the previous chunk. + +- Key: P (magit-blame-previous-chunk-same-commit) :: + + This command moves to the previous chunk from the same commit. + +- Key: q (magit-blame-quit) :: + + This command turns off Magit-Blame mode. If the buffer was created + during a recursive blame, then it also kills the buffer. + +- Key: M-w (magit-blame-copy-hash) :: + + This command saves the hash of the current chunk's commit to the + kill ring. + + When the region is active, the command saves the region's content + instead of the hash, like ~kill-ring-save~ would. + +- Key: c (magit-blame-cycle-style) :: + + This command changes how blame information is visualized in the + current buffer by cycling through the styles specified using the + option ~magit-blame-styles~. + +Blaming is also controlled using the following options. + +- User Option: magit-blame-styles :: + + This option defines a list of styles used to visualize blame + information. For now see its doc-string to learn more. + +- User Option: magit-blame-echo-style :: + + This option specifies the blame visualization style used by the + command ~magit-blame-echo~. This must be a symbol that is used as the + identifier for one of the styles defined in ~magit-blame-styles~. + +- User Option: magit-blame-time-format :: + + This option specifies the format string used to display times when + showing blame information. + +- User Option: magit-blame-read-only :: + + This option controls whether blaming a buffer also makes temporarily + read-only. + +- User Option: magit-blame-disable-modes :: + + This option lists incompatible minor-modes that should be disabled + temporarily when a buffer contains blame information. They are + enabled again when the buffer no longer shows blame information. + +- User Option: magit-blame-goto-chunk-hook :: + + This hook is run when moving between chunks. + +* Manipulating +** Creating Repository + +- Key: I (magit-init) :: + + This command initializes a repository and then shows the status + buffer for the new repository. + + If the directory is below an existing repository, then the user has + to confirm that a new one should be created inside. If the + directory is the root of the existing repository, then the user has + to confirm that it should be reinitialized. + +** Cloning Repository + +To clone a remote or local repository use ~C~, which is bound to the +command ~magit-clone~. This command either act as a transient prefix +command, which binds several infix arguments and suffix commands, or +it can invoke ~git clone~ directly, depending on whether a prefix +argument is used and on the value of ~magit-clone-always-transient~. + +- User Option: magit-clone-always-transient :: + + This option controls whether the command ~magit-clone~ always acts as + a transient prefix command, regardless of whether a prefix argument + is used or not. If ~t~, then that command always acts as a transient + prefix. If ~nil~, then a prefix argument has to be used for it to act + as a transient. + +- Key: C (magit-clone) :: + + This command either acts as a transient prefix command as described + above or does the same thing as ~transient-clone-regular~ as described + below. + + If it acts as a transient prefix, then it binds the following suffix + commands and several infix arguments. + +- Key: C C (magit-clone-regular) :: + + This command creates a regular clone of an existing repository. + The repository and the target directory are read from the user. + +- Key: C s (magit-clone-shallow) :: + + This command creates a shallow clone of an existing repository. + The repository and the target directory are read from the user. + By default the depth of the cloned history is a single commit, + but with a prefix argument the depth is read from the user. + +- Key: C > (magit-clone-sparse) :: + + This command creates a clone of an existing repository and + initializes a sparse checkout, avoiding a checkout of the full + working tree. To add more directories, use the + ~magit-sparse-checkout~ transient (see [[*Sparse checkouts]]). + +- Key: C b (magit-clone-bare) :: + + This command creates a bare clone of an existing repository. + The repository and the target directory are read from the user. + +- Key: C m (magit-clone-mirror) :: + + This command creates a mirror of an existing repository. + The repository and the target directory are read from the user. + +The following suffixes are disabled by default. See +[[info:transient#Enabling and Disabling Suffixes]] for how to enable them. + +- Key: C d (magit-clone-shallow-since) :: + + This command creates a shallow clone of an existing repository. + Only commits that were committed after a date are cloned, which + is read from the user. The repository and the target directory + are also read from the user. + +- Key: C e (magit-clone-shallow-exclude) :: + + This command creates a shallow clone of an existing repository. + This reads a branch or tag from the user. Commits that are + reachable from that are not cloned. The repository and the target + directory are also read from the user. + +- User Option: magit-clone-set-remote-head :: + + This option controls whether cloning causes the reference + ~refs/remotes//HEAD~ to be created in the clone. The default + is to delete the reference after running ~git clone~, which insists on + creating it. This is because the reference has not been found to be + particularly useful as it is not automatically updated when the ~HEAD~ + of the remote changes. Setting this option to ~t~ preserves Git's + default behavior of creating the reference. + +- User Option: magit-clone-set-remote.pushDefault :: + + This option controls whether the value of the Git variable + ~remote.pushDefault~ is set after cloning. + + - If ~t~, then it is always set without asking. + - If ~ask~, then the users are asked every time they clone a + repository. + - If ~nil~, then it is never set. + +- User Option: magit-clone-default-directory :: + + This option control the default directory name used when reading the + destination for a cloning operation. + + - If ~nil~ (the default), then the value of ~default-directory~ is used. + - If a directory, then that is used. + - If a function, then that is called with the remote url as the only + argument and the returned value is used. + +- User Option: magit-clone-name-alist :: + + This option maps regular expressions, which match repository names, + to repository urls, making it possible for users to enter short + names instead of urls when cloning repositories. + + Each element has the form ~(REGEXP HOSTNAME USER)~. When the user + enters a name when a cloning command asks for a name or url, then + that is looked up in this list. The first element whose REGEXP + matches is used. + + The format specified by option ~magit-clone-url-format~ is used to + turn the name into an url, using HOSTNAME and the repository name. + If the provided name contains a slash, then that is used. Otherwise + if the name omits the owner of the repository, then the default user + specified in the matched entry is used. + + If USER contains a dot, then it is treated as a Git variable and the + value of that is used as the username. Otherwise it is used as the + username itself. + +- User Option: magit-clone-url-format :: + + The format specified by this option is used when turning repository + names into urls. ~%h~ is the hostname and ~%n~ is the repository + name, including the name of the owner. The value can be a string + (representing a single static format) or an alist with elements + ~(HOSTNAME . FORMAT)~ mapping hostnames to formats. When an alist + is used, the ~t~ key represents the default format. + + Example of a single format string: + + #+BEGIN_SRC emacs-lisp + (setq magit-clone-url-format + "git@%h:%n.git") + #+END_SRC + + Example of by-hostname format strings: + + #+BEGIN_SRC emacs-lisp + (setq magit-clone-url-format + '(("git.example.com" . "git@%h:~%n") + (nil . "git@%h:%n.git"))) + #+END_SRC + +- User Option: magit-post-clone-hook :: + + Hook run after the Git process has successfully finished cloning the + repository. When the hook is called, ~default-directory~ is + let-bound to the directory where the repository has been cloned. + +** Staging and Unstaging + +Like Git, Magit can of course stage and unstage complete files. +Unlike Git, it also allows users to gracefully un-/stage +individual hunks and even just part of a hunk. To stage individual +hunks and parts of hunks using Git directly, one has to use the very +modal and rather clumsy interface of a ~git add --interactive~ session. + +With Magit, on the other hand, one can un-/stage individual hunks by +just moving point into the respective section inside a diff displayed +in the status buffer or a separate diff buffer and typing ~s~ or ~u~. To +operate on just parts of a hunk, mark the changes that should be +un-/staged using the region and then press the same key that would be +used to un-/stage. To stage multiple files or hunks at once use a +region that starts inside the heading of such a section and ends +inside the heading of a sibling section of the same type. + +Besides staging and unstaging, Magit also provides several other +"apply variants" that can also operate on a file, multiple files at +once, a hunk, multiple hunks at once, and on parts of a hunk. These +apply variants are described in the next section. + +You can also use Ediff to stage and unstage. See [[*Ediffing]]. + +- Key: s (magit-stage) :: + + Add the change at point to the staging area. + + With a prefix argument and an untracked file (or files) at point, + stage the file but not its content. This makes it possible to stage + only a subset of the new file's changes. + +- Key: S (magit-stage-modified) :: + + Stage all changes to files modified in the worktree. Stage all new + content of tracked files and remove tracked files that no longer + exist in the working tree from the index also. With a prefix + argument also stage previously untracked (but not ignored) files. + +- Key: u (magit-unstage) :: + + Remove the change at point from the staging area. + + Only staged changes can be unstaged. But by default this command + performs an action that is somewhat similar to unstaging, when it is + called on a committed change: it reverses the change in the index + but not in the working tree. + +- Key: U (magit-unstage-all) :: + + Remove all changes from the staging area. + +- User Option: magit-unstage-committed :: + + This option controls whether ~magit-unstage~ "unstages" committed + changes by reversing them in the index but not the working tree. + The alternative is to raise an error. + +- Key: M-x magit-reverse-in-index :: + + This command reverses the committed change at point in the index but + not the working tree. By default no key is bound directly to this + command, but it is indirectly called when ~u~ (~magit-unstage~) is + pressed on a committed change. + + This allows extracting a change from ~HEAD~, while leaving it in the + working tree, so that it can later be committed using a separate + commit. A typical workflow would be: + + 0. Optionally make sure that there are no uncommitted changes. + 1. Visit the ~HEAD~ commit and navigate to the change that should + not have been included in that commit. + 2. Type ~u~ (~magit-unstage~) to reverse it in the index. + This assumes that ~magit-unstage-committed~ is non-~nil~. + 3. Type ~c e~ to extend ~HEAD~ with the staged changes, + including those that were already staged before. + 4. Optionally stage the remaining changes using ~s~ or ~S~ and then + type ~c c~ to create a new commit. + +- Key: M-x magit-reset-index :: + + Reset the index to some commit. The commit is read from the user + and defaults to the commit at point. If there is no commit at + point, then it defaults to ~HEAD~. + +*** Staging from File-Visiting Buffers + +Fine-grained un-/staging has to be done from the status or a diff +buffer, but it's also possible to un-/stage all changes made to the +file visited in the current buffer right from inside that buffer. + +- Key: M-x magit-stage-file :: + + When invoked inside a file-visiting buffer, then stage all changes + to that file. In a Magit buffer, stage the file at point if any. + Otherwise prompt for a file to be staged. With a prefix argument + always prompt the user for a file, even in a file-visiting buffer or + when there is a file section at point. + +- Key: M-x magit-unstage-file :: + + When invoked inside a file-visiting buffer, then unstage all changes + to that file. In a Magit buffer, unstage the file at point if any. + Otherwise prompt for a file to be unstaged. With a prefix argument + always prompt the user for a file, even in a file-visiting buffer or + when there is a file section at point. + +** Applying + +Magit provides several "apply variants": stage, unstage, discard, +reverse, and "regular apply". At least when operating on a hunk they +are all implemented using ~git apply~, which is why they are called +"apply variants". + +- Stage. Apply a change from the working tree to the index. The change + also remains in the working tree. + +- Unstage. Remove a change from the index. The change remains in the + working tree. + +- Discard. On a staged change, remove it from the working tree and the + index. On an unstaged change, remove it from the working tree only. + +- Reverse. Reverse a change in the working tree. Both committed and + staged changes can be reversed. Unstaged changes cannot be + reversed. Discard them instead. + +- Apply. Apply a change to the working tree. Both committed and staged + changes can be applied. Unstaged changes cannot be applied - as + they already have been applied. + +The previous section described the staging and unstaging commands. +What follows are the commands which implement the remaining apply +variants. + +- Key: a (magit-apply) :: + + Apply the change at point to the working tree. + + With a prefix argument fallback to a 3-way merge. Doing so causes + the change to be applied to the index as well. + +- Key: k (magit-discard) :: + + Remove the change at point from the working tree. + + On a hunk or file with unresolved conflicts prompt which side to + keep (while discarding the other). If point is within the text + of a side, then keep that side without prompting. + +- Key: v (magit-reverse) :: + + Reverse the change at point in the working tree. + + With a prefix argument fallback to a 3-way merge. Doing so causes + the change to be applied to the index as well. + +With a prefix argument all apply variants attempt a 3-way merge when +appropriate (i.e., when ~git apply~ is used internally). + +** Committing + +When the user initiates a commit, Magit calls ~git commit~ without the +~--message~ argument, so Git has to get the message from the user. To +do so, it creates a file such as ~.git/COMMIT_EDITMSG~ and then opens +that file in the editor specified by ~$EDITOR~ (or ~$GIT_EDITOR~). + +Magit arranges for that editor to be the Emacsclient. Once the user +finishes the editing session, the Emacsclient exits and Git creates +the commit, using the file's content as the commit message. + +*** Initiating a Commit + +Also see [[man:git-commit]] + +- Key: c (magit-commit) :: + + This transient prefix command binds the following suffix commands + along with the appropriate infix arguments and displays them in a + temporary buffer until a suffix is invoked. + +**** Creating a new commit + +- Key: c c (magit-commit-create) :: + + Create a new commit. + +**** Editing the last commit + +These commands modify the last (a.k.a., "HEAD") commit. The commit is +modified (a.k.a., replaced) immediately. Similar commands exist for +modifying other (non-HEAD) commits. Those commands are described in +the following two sections. For each command in this section, we +mention the respective non-HEAD commands, to make the relation +explicit. + +The command descriptions below mention the specific arguments they use +when calling ~git commit~. The arguments specified in the menu are +appended to those arguments. + +- Key: c e (magit-commit-extend) :: + + This command amends the staged changes to the last commit, without + editing its commit message. + + This command calls ~git commit --amend --no-edit~. + + With a prefix argument the committer date is not updated; without an + argument it is updated. + + The option ~magit-commit-extend-override-date~ can be used to inverse + the meaning of the prefix argument. Non-interactively, the optional + OVERRIDE-DATE argument controls this behavior, and the option is of + no relevance. + +- Key: c a (magit-commit-amend) :: + + This command amends the staged changes to the last commit, and pops + up a buffer to let the user edit its commit message. + + This command calls ~git commit --amend --edit~. + +- Key: c w (magit-commit-reword) :: + + This command pops up a buffer to let the user edit the message of + the latest commit. The commit tree remains unchanged and staged + changes remain staged. + + This command calls ~git commit --amend --only --edit~. + + With a prefix argument the committer date is not updated; without an + argument it is updated. + + The option ~magit-commit-reword-override-date~ can be used to inverse + the meaning of the prefix argument. Non-interactively, the optional + OVERRIDE-DATE argument controls this behavior, and the option is of + no relevance. + +**** Editing any reachable commit + +These commands create a new commit, which targets an existing commit, +from the staged changes and/or using a new commit message. Any commit +that is reachable from HEAD, including HEAD itself, can be the target. + +The new commit is intended to be eventually squashed into the targeted +commit, but this is *not* done immediately. The squashing is done at a +later time, when you explicitly call ~magit-rebase-autosquash~, or use +~--autosquash~ with another rebase command. + +Some of these commands require that you immediately write a new commit +message, or that you immediately edit an existing message. + +The new commits are called "squash" and "fixup" commits. The +difference is that when a "squash" commit is squashed into its +targeted commit, the user gets a chance to modify the message to be +used for the final commit; while for "fixup" commits the existing +message of the targeted commit is used as-is and the message of the +"fixup" commit is discarded. + +If point is on a reachable commit, then all of these commands target +that commit, without requiring confirmation. If point is on some +reachable commit, but you want to target another commit, use a prefix +argument, to select a commit in a log buffer dedicated to that task. +The meaning of the prefix argument can be inverted by customizing +~magit-commit-squash-confirm~. + +The command descriptions below mention the specific arguments they use +when calling ~git commit~. The arguments specified in the menu are +appended to those arguments. + +The next two commands also exist in "instant" variants, which are +described in the next section. Those variants behave the same as the +variants described here, except that they immediately initiate an +~--autosquash~ rebase. + +- Key: c f (magit-commit-fixup) :: + + This command creates a new fixup commit from the staged changes, + targeting the reachable commit at point, if any. Otherwise the + user is prompted for a commit. + + Use this variant if you want to correct some minor defect in the + targeted commit, which does not require changes to the existing + message of the targeted commit. + + This command calls ~git commit --fixup=COMMIT --no-edit~. + +- Key: c s (magit-commit-squash) :: + + This command creates a new squash commit from the staged changes, + targeting the reachable commit at point, if any. Otherwise the + user is prompted for a commit. + + Use this variant if you want a chance to make changes to the final + commit message, but not until the two commits are being squashed + into the final combined commit. + + This command calls ~git commit --squash=COMMIT --no-edit~. + +- Key: c A (magit-commit-alter) :: + + This command creates a new fixup commit from the staged changes, + targeting the reachable commit at point, if any. Otherwise the + user is prompted for a commit. + + Use this variant if you want to write the final commit message now, + but (as for all variants in this section) do not want to immediately + squash the fixup and targeted commits into a final combined commit. + + This command calls ~git commit --fixup=amend:COMMIT --edit~. + +- Key: c n (magit-commit-augment) :: + + This command creates a new squash commit from the staged changes, + targeting the reachable commit at point, if any. Otherwise the + user is prompted for a commit. + + Use this variant if you want to describe the new changes now, but + want to delay writing the final message, which describes the changes + in the combined commit, until you actually combine the squash and + target commits into the final commit. You can think of the new + message, which you write here, as a "note", to be integrated once + once you write the final commit message. + + This command calls ~git commit --squash=COMMIT --edit~. + +- Key: c W (magit-commit-revise) :: + + This command pops up a buffer containing the commit message of the + reachable commit at point, if any. Otherwise the user is prompted + for a commit to target. + + Use this variant if you want to correct the message of the targeted + commit, but want to delay performing the ~--autosquash~ rebase, which + actually changes that commit. + + This command calls ~git commit --fixup=reword:COMMIT --edit~. + +**** Editing any reachable commit and rebasing immediately + +These commands create a new commit, which targets an existing commit, +from the staged changes. Any commit that is reachable from HEAD, +including HEAD itself, can be the target. + +The new commit is immediately squashed into its target commit, using +an ~--autosquash~ rebase. + +The command descriptions below mention the specific arguments they use +when calling ~git commit~. The arguments specified in the menu are +appended to those arguments when calling ~git commit~. + +- Key: c F (magit-commit-instant-fixup) :: + + This command creates a fixup commit, targeting the reachable commit + at point, if any. Otherwise the user is prompted for a commit. Then + it instantly performs a rebase, to squash the new commit into the + targeted commit. + + The original commit message of the targeted commit is left untouched. + + This command calls ~git commit --fixup=COMMIT --no-edit~ + and then ~git rebase --autosquash MERGE-BASE~. + +- Key: c S (magit-commit-instant-squash) :: + + This command creates a squash commit, targeting the reachable commit + at point, if any. Otherwise the user is prompted for a commit. Then + it instantly performs a rebase, to squash the new commit into the + targeted commit. + + During the rebase phase the user is asked to author the final commit + message, based on the original message of the targeted commit. + + This command calls ~git commit --squash=COMMIT --no-edit~ + and then ~git rebase --autosquash MERGE-BASE~. + +**** Options used by commit commands +***** Used by all or most commit commands + +- User Option: magit-commit-show-diff :: + + Whether the relevant diff is automatically shown when committing. + +- User Option: magit-commit-ask-to-stage :: + + Whether to ask to stage all unstaged changes when committing and + nothing is staged. + +- User Option: magit-post-commit-hook :: + + Hook run after creating a commit without the user editing a message. + + This hook is run by ~magit-refresh~ if ~this-command~ is a member + of ~magit-post-commit-hook-commands~. This only includes commands + named ~magit-commit-*~ that do *not* require that the user edits + the commit message in a buffer. + + Also see ~git-commit-post-finish-hook~. + +- User Option: magit-commit-diff-inhibit-same-window :: + + Whether to inhibit use of same window when showing diff while + committing. + + When writing a commit, then a diff of the changes to be committed + is automatically shown. The idea is that the diff is shown in a + different window of the same frame and for most users that just + works. In other words most users can completely ignore this + option because its value doesn't make a difference for them. + + However for users who configured Emacs to never create a new + window even when the package explicitly tries to do so, then + displaying two new buffers necessarily means that the first is + immediately replaced by the second. In our case the message + buffer is immediately replaced by the diff buffer, which is of + course highly undesirable. + + A workaround is to suppress this user configuration in this + particular case. Users have to explicitly opt-in by toggling + this option. We cannot enable the workaround unconditionally + because that again causes issues for other users: if the frame + is too tiny or the relevant settings too aggressive, then the + diff buffer would end up being displayed in a new frame. + + Also see https://github.com/magit/magit/issues/4132. + +***** Used by all squash and fixup commands + +- User Option: magit-commit-squash-confirm :: + + Whether the commit targeted by squash and fixup has to be confirmed. + When non-~nil~ then the commit at point (if any) is used as default + choice. Otherwise it has to be confirmed. This option only affects + ~magit-commit-squash~ and ~magit-commit-fixup~. The "instant" variants + always require confirmation because making an error while using + those is harder to recover from. + +***** Used by specific commit commands + +- User Option: magit-commit-extend-override-date :: + + Whether using ~magit-commit-extend~ changes the committer date. + +- User Option: magit-commit-reword-override-date :: + + Whether using ~magit-commit-reword~ changes the committer date. + +*** Editing Commit Messages + +After initiating a commit as described in the previous section, two new +buffers appear. One shows the changes that are about to be committed, +while the other is used to write the message. + +Commit messages are edited in an edit session - in the background ~git~ +is waiting for the editor, in our case ~emacsclient~, to save the commit +message in a file (in most cases ~.git/COMMIT_EDITMSG~) and then return. +If the editor returns with a non-zero exit status then ~git~ does not +create the commit. So the most important commands are those for +finishing and aborting the commit. + +- Key: C-c C-c (with-editor-finish) :: + + Finish the current editing session by returning with exit code 0. + Git then creates the commit using the message it finds in the file. + +- Key: C-c C-k (with-editor-cancel) :: + + Cancel the current editing session by returning with exit code 1. + Git then cancels the commit, but leaves the file untouched. + +In addition to being used by ~git commit~, messages may also be stored +in a ring that persists until Emacs is closed. By default the message +is stored at the beginning and the end of an edit session (regardless +of whether the session is finished successfully or was canceled). It +is sometimes useful to bring back messages from that ring. + +- Key: C-c M-s (git-commit-save-message) :: + + Save the current buffer content to the commit message ring. + +- Key: M-p (git-commit-prev-message) :: + + Cycle backward through the commit message ring, after saving the + current message to the ring. With a numeric prefix ARG, go back + ARG comments. + +- Key: M-n (git-commit-next-message) :: + + Cycle forward through the commit message ring, after saving the + current message to the ring. With a numeric prefix ARG, go back + ARG comments. + +By default the diff for the changes that are about to be committed are +automatically shown when invoking the commit. To prevent that, remove +~magit-commit-diff~ from ~server-switch-hook~. + +When amending to an existing commit it may be useful to show either +the changes that are about to be added to that commit or to show those +changes alongside those that have already been committed. + +- Key: C-c C-d (magit-diff-while-committing) :: + + While committing, show the changes that are about to be committed. + While amending, invoking the command again toggles between showing + just the new changes or all the changes that will be committed. + +**** Using the Revision Stack + +- Key: C-c C-w (magit-pop-revision-stack) :: + + This command inserts a representation of a revision into the current + buffer. It can be used inside buffers used to write commit messages + but also in other buffers such as buffers used to edit emails or + ChangeLog files. + + By default this command pops the revision which was last added to + the ~magit-revision-stack~ and inserts it into the current buffer + according to ~magit-pop-revision-stack-format~. Revisions can be put + on the stack using ~magit-copy-section-value~ and + ~magit-copy-buffer-revision~. + + If the stack is empty or with a prefix argument it instead reads a + revision in the minibuffer. By using the minibuffer history this + allows selecting an item which was popped earlier or to insert an + arbitrary reference or revision without first pushing it onto the + stack. + + When reading the revision from the minibuffer, then it might not + be possible to guess the correct repository. When this command + is called inside a repository (e.g., while composing a commit + message), then that repository is used. Otherwise (e.g., while + composing an email) then the repository recorded for the top + element of the stack is used (even though we insert another + revision). If not called inside a repository and with an empty + stack, or with two prefix arguments, then read the repository in + the minibuffer too. + +- User Option: magit-pop-revision-stack-format :: + + This option controls how the command ~magit-pop-revision-stack~ + inserts a revision into the current buffer. + + The entries on the stack have the format ~(HASH TOPLEVEL)~ and this + option has the format ~(POINT-FORMAT EOB-FORMAT INDEX-REGEXP)~, all + of which may be ~nil~ or a string (though either one of EOB-FORMAT + or POINT-FORMAT should be a string, and if INDEX-REGEXP is + non-~nil~, then the two formats should be too). + + First INDEX-REGEXP is used to find the previously inserted entry, + by searching backward from point. The first submatch must match + the index number. That number is incremented by one, and becomes + the index number of the entry to be inserted. If you don't want + to number the inserted revisions, then use ~nil~ for INDEX-REGEXP. + + If INDEX-REGEXP is non-~nil~ then both POINT-FORMAT and EOB-FORMAT + should contain \"%N\", which is replaced with the number that was + determined in the previous step. + + Both formats, if non-~nil~ and after removing %N, are then expanded + using ~git show --format=FORMAT ...~ inside TOPLEVEL. + + The expansion of POINT-FORMAT is inserted at point, and the + expansion of EOB-FORMAT is inserted at the end of the buffer (if the + buffer ends with a comment, then it is inserted right before that). + +**** Commit Pseudo Headers + +Some projects use pseudo headers in commit messages. Magit colorizes +such headers and provides some commands to insert such headers. + +- User Option: git-commit-known-pseudo-headers :: + + A list of Git pseudo headers to be highlighted. + +- Key: C-c C-i (git-commit-insert-pseudo-header) :: + + Insert a commit message pseudo header. + +- Key: C-c C-a (git-commit-ack) :: + + Insert a header acknowledging that you have looked at the commit. + +- Key: C-c C-r (git-commit-review) :: + + Insert a header acknowledging that you have reviewed the commit. + +- Key: C-c C-s (git-commit-signoff) :: + + Insert a header to sign off the commit. + +- Key: C-c C-t (git-commit-test) :: + + Insert a header acknowledging that you have tested the commit. + +- Key: C-c C-o (git-commit-cc) :: + + Insert a header mentioning someone who might be interested. + +- Key: C-c C-p (git-commit-reported) :: + + Insert a header mentioning the person who reported the issue being + fixed by the commit. + +- Key: C-c M-i (git-commit-suggested) :: + + Insert a header mentioning the person who suggested the change. + +**** Commit Mode and Hooks + +~git-commit-mode~ is a minor mode that is only used to establish certain +key bindings. This makes it possible to use an arbitrary major mode +in buffers used to edit commit messages. It is even possible to use +different major modes in different repositories, which is useful when +different projects impose different commit message conventions. + +- User Option: git-commit-major-mode :: + + The value of this option is the major mode used to edit Git commit + messages. + +Because ~git-commit-mode~ is a minor mode, we don't use its mode hook +to setup the buffer, except for the key bindings. All other setup +happens in the function ~git-commit-setup~, which among other things runs +the hook ~git-commit-setup-hook~. + +- User Option: git-commit-setup-hook :: + + Hook run at the end of ~git-commit-setup~. + +#+texinfo: @noindent +The following functions are suitable for this hook: + +- Function: git-commit-save-message :: + + Save the current buffer content to the commit message ring. + +- Function: git-commit-setup-changelog-support :: + + After this function is called, ChangeLog entries are treated as + paragraphs. + +- Function: git-commit-turn-on-auto-fill :: + + Turn on ~auto-fill-mode~. + +- Function: git-commit-turn-on-flyspell :: + + Turn on Flyspell mode. Also prevent comments from being checked and + finally check current non-comment text. + +- Function: git-commit-propertize-diff :: + + Propertize the diff shown inside the commit message buffer. Git + inserts such diffs into the commit message template when the + ~--verbose~ argument is used. ~magit-commit~ by default does not offer + that argument because the diff that is shown in a separate buffer is + more useful. But some users disagree, which is why this function + exists. + +- Function: bug-reference-mode :: + + Hyperlink bug references in the buffer. + +- Function: with-editor-usage-message :: + + Show usage information in the echo area. + +- User Option: git-commit-post-finish-hook :: + + Hook run after the user finished writing a commit message. + + This hook is only run after pressing ~C-c C-c~ in a buffer used to + edit a commit message. If a commit is created without the user + typing a message into a buffer, then this hook is not run. + + This hook is not run until the new commit has been created. If + doing so takes Git longer than one second, then this hook isn't run + at all. For certain commands such as ~magit-rebase-continue~ this + hook is never run because doing so would lead to a race condition. + + This hook is only run if ~magit~ is available. + + Also see ~magit-post-commit-hook~. + +**** Commit Message Conventions + +Git-Commit highlights certain violations of commonly accepted commit +message conventions. Certain violations even cause Git-Commit to ask +you to confirm that you really want to do that. This nagging can of +course be turned off, but the result of doing that usually is that +instead of some code it's now the human who is reviewing your commits +who has to waste some time telling you to fix your commits. + +- User Option: git-commit-summary-max-length :: + + The intended maximal length of the summary line of commit messages. + Characters beyond this column are colorized to indicate that this + preference has been violated. + +- User Option: git-commit-finish-query-functions :: + + List of functions called to query before performing commit. + + The commit message buffer is current while the functions are called. + If any of them returns ~nil~, then the commit is not performed and the + buffer is not killed. The user should then fix the issue and try + again. + + The functions are called with one argument. If it is non-~nil~ then + that indicates that the user used a prefix argument to force + finishing the session despite issues. Functions should usually + honor this wish and return non-~nil~. + + By default the only member is ~git-commit-check-style-conventions~. + +- Function: git-commit-check-style-conventions :: + + This function checks for violations of certain basic style + conventions. For each violation it asks users if they want to + proceed anyway. + +- User Option: git-commit-style-convention-checks :: + + This option controls what conventions the function by the same name + tries to enforce. The value is a list of self-explanatory symbols + identifying certain conventions; ~non-empty-second-line~ and + ~overlong-summary-line~. + +** Branching +*** The Two Remotes + +The upstream branch of some local branch is the branch into which the +commits on that local branch should eventually be merged, usually +something like ~origin/master~. For the ~master~ branch itself the +upstream branch and the branch it is being pushed to, are usually the +same remote branch. But for a feature branch the upstream branch and +the branch it is being pushed to should differ. + +The commits on feature branches too should /eventually/ end up in a +remote branch such as ~origin/master~ or ~origin/maint~. Such a branch +should therefore be used as the upstream. But feature branches +shouldn't be pushed directly to such branches. Instead a feature +branch ~my-feature~ is usually pushed to ~my-fork/my-feature~ or if you +are a contributor ~origin/my-feature~. After the new feature has been +reviewed, the maintainer merges the feature into ~master~. And finally +~master~ (not ~my-feature~ itself) is pushed to ~origin/master~. + +But new features seldom are perfect on the first try, and so feature +branches usually have to be reviewed, improved, and re-pushed several +times. Pushing should therefore be easy to do, and for that reason +many Git users have concluded that it is best to use the remote branch +to which the local feature branch is being pushed as its upstream. + +But luckily Git has long ago gained support for a push-remote which +can be configured separately from the upstream branch, using the +variables ~branch..pushRemote~ and ~remote.pushDefault~. So we no +longer have to choose which of the two remotes should be used as "the +remote". + +Each of the fetching, pulling, and pushing transient commands features +three suffix commands that act on the current branch and some other +branch. Of these, ~p~ is bound to a command which acts on the +push-remote, ~u~ is bound to a command which acts on the upstream, and ~e~ +is bound to a command which acts on any other branch. The status +buffer shows unpushed and unpulled commits for both the push-remote +and the upstream. + +It's fairly simple to configure these two remotes. The values of all +the variables that are related to fetching, pulling, and pushing (as +well as some other branch-related variables) can be inspected and +changed using the command ~magit-branch-configure~, which is available +from many transient prefix commands that deal with branches. It is +also possible to set the push-remote or upstream while pushing (see +[[*Pushing]]). + +*** Branch Commands + +The transient prefix command ~magit-branch~ is used to create and +checkout branches, and to make changes to existing branches. It is +not used to fetch, pull, merge, rebase, or push branches, i.e., this +command deals with branches themselves, not with the commits reachable +from them. Those features are available from separate transient +commands. + +- Key: b (magit-branch) :: + + This transient prefix command binds the following suffix commands + and displays them in a temporary buffer until a suffix is invoked. + + By default it also binds and displays the values of some + branch-related Git variables and allows changing their values. + +- User Option: magit-branch-direct-configure :: + + This option controls whether the transient command ~magit-branch~ can + be used to directly change the values of Git variables. This defaults + to ~t~ (to avoid changing key bindings). When set to ~nil~, then no + variables are displayed by that transient command, and its suffix + command ~magit-branch-configure~ has to be used instead to view and + change branch related variables. + +- Key: b C (magit-branch-configure) :: +- Key: f C :: +- Key: F C :: +- Key: P C :: + + This transient prefix command binds commands that set the value of + branch-related variables and displays them in a temporary buffer + until the transient is exited. + + With a prefix argument, this command always prompts for a branch. + + Without a prefix argument this depends on whether it was invoked as + a suffix of ~magit-branch~ and on the ~magit-branch-direct-configure~ + option. If ~magit-branch~ already displays the variables for the + current branch, then it isn't useful to invoke another transient + that displays them for the same branch. In that case this command + prompts for a branch. + +The variables are described in [[*Branch Git Variables]]. + +- Key: b b (magit-checkout) :: + + Checkout a revision read in the minibuffer and defaulting to the + branch or arbitrary revision at point. If the revision is a local + branch then that becomes the current branch. If it is something + else then ~HEAD~ becomes detached. Checkout fails if the working tree + or the staging area contain changes. + +- Key: b n (magit-branch-create) :: + + Create a new branch. The user is asked for a branch or arbitrary + revision to use as the starting point of the new branch. When a + branch name is provided, then that becomes the upstream branch of + the new branch. The name of the new branch is also read in the + minibuffer. + + Also see option ~magit-branch-prefer-remote-upstream~. + +- Key: b c (magit-branch-and-checkout) :: + + This command creates a new branch like ~magit-branch-create~, but then + also checks it out. + + Also see option ~magit-branch-prefer-remote-upstream~. + +- Key: b l (magit-branch-checkout) :: + + This command checks out an existing or new local branch. It reads a + branch name from the user offering all local branches and a subset + of remote branches as candidates. Remote branches for which a local + branch by the same name exists are omitted from the list of + candidates. The user can also enter a completely new branch name. + + - If the user selects an existing local branch, then that is checked + out. + + - If the user selects a remote branch, then it creates and checks + out a new local branch with the same name, and configures the + selected remote branch as the push target. + + - If the user enters a new branch name, then it creates and checks + that out, after also reading the starting-point from the user. + + In the latter two cases the upstream is also set. Whether it is set + to the chosen starting point or something else depends on the value + of ~magit-branch-adjust-remote-upstream-alist~. + +- Key: b s (magit-branch-spinoff) :: + + This command creates and checks out a new branch starting at and + tracking the current branch. That branch in turn is reset to the + last commit it shares with its upstream. If the current branch has + no upstream or no unpushed commits, then the new branch is created + anyway and the previously current branch is not touched. + + This is useful to create a feature branch after work has already + begun on the old branch (likely but not necessarily "master"). + + If the current branch is a member of the value of option + ~magit-branch-prefer-remote-upstream~ (which see), then the current + branch will be used as the starting point as usual, but the upstream + of the starting-point may be used as the upstream of the new branch, + instead of the starting-point itself. + + If optional FROM is non-~nil~, then the source branch is reset + to ~FROM~~, instead of to the last commit it shares with its + upstream. Interactively, FROM is only ever non-~nil~, if the + region selects some commits, and among those commits, FROM is + the commit that is the fewest commits ahead of the source + branch. + + The commit at the other end of the selection actually does not + matter, all commits between FROM and ~HEAD~ are moved to the new + branch. If FROM is not reachable from ~HEAD~ or is reachable from the + source branch's upstream, then an error is raised. + +- Key: b S (magit-branch-spinout) :: + + This command behaves like ~magit-branch-spinoff~, except that it does + not change the current branch. If there are any uncommitted changes, + then it behaves exactly like ~magit-branch-spinoff~. + +- Key: b x (magit-branch-reset) :: + + This command resets a branch, defaulting to the branch at point, to + the tip of another branch or any other commit. + + When the branch being reset is the current branch, then a hard reset + is performed. If there are any uncommitted changes, then the user + has to confirm the reset because those changes would be lost. + + This is useful when you have started work on a feature branch but + realize it's all crap and want to start over. + + When resetting to another branch and a prefix argument is used, then + the target branch is set as the upstream of the branch that is being + reset. + +- Key: b k (magit-branch-delete) :: + + Delete one or multiple branches. If the region marks multiple + branches, then offer to delete those. Otherwise, prompt for a single + branch to be deleted, defaulting to the branch at point. + + Require confirmation when deleting branches is dangerous in some + way. Option ~magit-no-confirm~ can be customized to not require + confirmation in certain cases. See its docstring to learn why + confirmation is required by default in certain cases or if a + prompt is confusing. + +- Key: b m (magit-branch-rename) :: + + Rename a branch. The branch and the new name are read in the + minibuffer. With prefix argument the branch is renamed even if that + name conflicts with an existing branch. + +- User Option: magit-branch-read-upstream-first :: + + When creating a branch, whether to read the upstream branch before + the name of the branch that is to be created. The default is ~t~, + and I recommend you leave it at that. + +- User Option: magit-branch-prefer-remote-upstream :: + + This option specifies whether remote upstreams are favored over + local upstreams when creating new branches. + + When a new branch is created, then the branch, commit, or stash at + point is suggested as the starting point of the new branch, or if + there is no such revision at point the current branch. In either + case the user may choose another starting point. + + If the chosen starting point is a branch, then it may also be set + as the upstream of the new branch, depending on the value of the + Git variable `branch.autoSetupMerge'. By default this is done + for remote branches, but not for local branches. + + You might prefer to always use some remote branch as upstream. + If the chosen starting point is (1) a local branch, (2) whose + name matches a member of the value of this option, (3) the + upstream of that local branch is a remote branch with the same + name, and (4) that remote branch can be fast-forwarded to the + local branch, then the chosen branch is used as starting point, + but its own upstream is used as the upstream of the new branch. + + Members of this option's value are treated as branch names that + have to match exactly unless they contain a character that makes + them invalid as a branch name. Recommended characters to use + to trigger interpretation as a regexp are "*" and "^". Some + other characters which you might expect to be invalid, actually + are not, e.g., ".+$" are all perfectly valid. More precisely, + if ~git check-ref-format --branch STRING~ exits with a non-zero + status, then treat STRING as a regexp. + + Assuming the chosen branch matches these conditions you would end + up with with e.g.: + + #+BEGIN_SRC text + feature --upstream--> origin/master + #+END_SRC + + instead of + + #+BEGIN_SRC text + feature --upstream--> master --upstream--> origin/master + #+END_SRC + + Which you prefer is a matter of personal preference. If you do + prefer the former, then you should add branches such as ~master~, + ~next~, and ~maint~ to the value of this options. + +- User Option: magit-branch-adjust-remote-upstream-alist :: + + The value of this option is an alist of branches to be used as + the upstream when branching a remote branch. + + When creating a local branch from an ephemeral branch located on a + remote, e.g., a feature or hotfix branch, then that remote branch + should usually not be used as the upstream branch, since the + push-remote already allows accessing it and having both the upstream + and the push-remote reference the same related branch would be + wasteful. Instead a branch like "maint" or "master" should be used + as the upstream. + + This option allows specifying the branch that should be used as the + upstream when branching certain remote branches. The value is an + alist of the form ~((UPSTREAM . RULE)...)~. The first matching + element is used, the following elements are ignored. + + UPSTREAM is the branch to be used as the upstream for branches + specified by RULE. It can be a local or a remote branch. + + RULE can either be a regular expression, matching branches whose + upstream should be the one specified by UPSTREAM. Or it can be a + list of the only branches that should *not* use UPSTREAM; all other + branches will. Matching is done after stripping the remote part of + the name of the branch that is being branched from. + + If you use a finite set of non-ephemeral branches across all your + repositories, then you might use something like: + + #+BEGIN_SRC emacs-lisp + (("origin/master" . ("master" "next" "maint"))) + #+END_SRC + + Or if the names of all your ephemeral branches contain a slash, + at least in some repositories, then a good value could be: + + #+BEGIN_SRC emacs-lisp + (("origin/master" . "/")) + #+END_SRC + + Of course you can also fine-tune: + + #+BEGIN_SRC emacs-lisp + (("origin/maint" . "\\`hotfix/") + ("origin/master" . "\\`feature/")) + #+END_SRC + + UPSTREAM can be a local branch: + + #+BEGIN_SRC emacs-lisp + (("master" . ("master" "next" "maint"))) + #+END_SRC + +Because the main branch is no longer almost always named "master" +you should also account for other common names: + + #+BEGIN_SRC emacs-lisp + (("main" . ("main" "master" "next" "maint")) + ("master" . ("main" "master" "next" "maint"))) + #+END_SRC + +- Command: magit-branch-orphan :: + + This command creates and checks out a new orphan branch with + contents from a given revision. + +- Command: magit-branch-or-checkout :: + + This command is a hybrid between ~magit-checkout~ and + ~magit-branch-and-checkout~ and is intended as a replacement for the + former in ~magit-branch~. + + It first asks the user for an existing branch or revision. If the + user input actually can be resolved as a branch or revision, then it + checks that out, just like ~magit-checkout~ would. + + Otherwise it creates and checks out a new branch using the input as + its name. Before doing so it reads the starting-point for the new + branch. This is similar to what ~magit-branch-and-checkout~ does. + + To use this command instead of ~magit-checkout~ add this to your init + file: + + #+BEGIN_SRC emacs-lisp + (transient-replace-suffix 'magit-branch 'magit-checkout + '("b" "dwim" magit-branch-or-checkout)) + #+END_SRC + +*** Branch Git Variables + +These variables can be set from the transient prefix command +~magit-branch-configure~. By default they can also be set from +~magit-branch~. See [[*Branch Commands]]. + +- Variable: branch.NAME.merge :: + + Together with ~branch.NAME.remote~ this variable defines the upstream + branch of the local branch named NAME. The value of this variable + is the full reference of the upstream /branch/. + +- Variable: branch.NAME.remote :: + + Together with ~branch.NAME.merge~ this variable defines the upstream + branch of the local branch named NAME. The value of this variable + is the name of the upstream /remote/. + +- Variable: branch.NAME.rebase :: + + This variable controls whether pulling into the branch named NAME is + done by rebasing or by merging the fetched branch. + + - When ~true~ then pulling is done by rebasing. + - When ~false~ then pulling is done by merging. + - When undefined then the value of ~pull.rebase~ is used. The default + of that variable is ~false~. + +- Variable: branch.NAME.pushRemote :: + + This variable specifies the remote that the branch named NAME is + usually pushed to. The value has to be the name of an existing + remote. + + It is not possible to specify the name of /branch/ to push the local + branch to. The name of the remote branch is always the same as the + name of the local branch. + + If this variable is undefined but ~remote.pushDefault~ is defined, + then the value of the latter is used. By default ~remote.pushDefault~ + is undefined. + +- Variable: branch.NAME.description :: + + This variable can be used to describe the branch named NAME. That + description is used, e.g., when turning the branch into a series of + patches. + +The following variables specify defaults which are used if the above +branch-specific variables are not set. + +- Variable: pull.rebase :: + + This variable specifies whether pulling is done by rebasing or by + merging. It can be overwritten using ~branch.NAME.rebase~. + + - When ~true~ then pulling is done by rebasing. + - When ~false~ (the default) then pulling is done by merging. + + Since it is never a good idea to merge the upstream branch into a + feature or hotfix branch and most branches are such branches, you + should consider setting this to ~true~, and ~branch.master.rebase~ to + ~false~. + +- Variable: remote.pushDefault :: + + This variable specifies what remote the local branches are usually + pushed to. This can be overwritten per branch using + ~branch.NAME.pushRemote~. + +The following variables are used during the creation of a branch and +control whether the various branch-specific variables are +automatically set at this time. + +- Variable: branch.autoSetupMerge :: + + This variable specifies under what circumstances creating a branch + NAME should result in the variables ~branch.NAME.merge~ and + ~branch.NAME.remote~ being set according to the starting point used to + create the branch. If the starting point isn't a branch, then these + variables are never set. + + - When ~always~ then the variables are set regardless of whether the + starting point is a local or a remote branch. + - When ~true~ (the default) then the variables are set when the starting + point is a remote branch, but not when it is a local branch. + - When ~false~ then the variables are never set. + +- Variable: branch.autoSetupRebase :: + + This variable specifies whether creating a branch NAME should result + in the variable ~branch.NAME.rebase~ being set to ~true~. + + - When ~always~ then the variable is set regardless of whether the + starting point is a local or a remote branch. + - When ~local~ then the variable are set when the starting point is a + local branch, but not when it is a remote branch. + - When ~remote~ then the variable are set when the starting point is a + remote branch, but not when it is a local branch. + - When ~never~ (the default) then the variable is never set. + +Note that the respective commands always change the repository-local +values. If you want to change the global value, which is used when +the local value is undefined, then you have to do so on the command +line, e.g.: + +#+begin_src shell-script + git config --global remote.autoSetupMerge always +#+end_src + +For more information about these variables you should also see +man:git-config Also see [[man:git-branch]], [[man:git-checkout]] and [[*Pushing]]. + +- User Option: magit-prefer-remote-upstream :: + + This option controls whether commands that read a branch from the + user and then set it as the upstream branch, offer a local or a + remote branch as default completion candidate, when they have the + choice. + + This affects all commands that use ~magit-read-upstream-branch~ or + ~magit-read-starting-point~, which includes all commands that change + the upstream and many which create new branches. + +*** Auxiliary Branch Commands + +These commands are not available from the transient ~magit-branch~ by +default. + +- Command: magit-branch-shelve :: + + This command shelves a branch. This is done by deleting the branch, + and creating a new reference "refs/shelved/BRANCH-NAME" pointing at + the same commit as the branch pointed at. If the deleted branch had + a reflog, then that is preserved as the reflog of the new reference. + + This is useful if you want to move a branch out of sight, but are + not ready to completely discard it yet. + +- Command: magit-branch-unshelve :: + + This command unshelves a branch that was previously shelved using + ~magit-branch-shelve~. This is done by deleting the reference + "refs/shelved/BRANCH-NAME" and creating a branch "BRANCH-NAME" + pointing at the same commit as the deleted reference pointed at. + If the deleted reference had a reflog, then that is restored as + the reflog of the branch. + +** Merging + +Also see [[man:git-merge]] For information on how to resolve +merge conflicts see the next section. + +- Key: m (magit-merge) :: + + This transient prefix command binds the following suffix commands + along with the appropriate infix arguments and displays them in a + temporary buffer until a suffix is invoked. + +When no merge is in progress, then the transient features the +following suffix commands. + +- Key: m m (magit-merge-plain) :: + + This command merges another branch or an arbitrary revision into the + current branch. The branch or revision to be merged is read in the + minibuffer and defaults to the branch at point. + + Unless there are conflicts or a prefix argument is used, then the + resulting merge commit uses a generic commit message, and the user + does not get a chance to inspect or change it before the commit is + created. With a prefix argument this does not actually create the + merge commit, which makes it possible to inspect how conflicts were + resolved and to adjust the commit message. + +- Key: m e (magit-merge-editmsg) :: + + This command merges another branch or an arbitrary revision into the + current branch and opens a commit message buffer, so that the user + can make adjustments. The commit is not actually created until the + user finishes with ~C-c C-c~. + +- Key: m n (magit-merge-nocommit) :: + + This command merges another branch or an arbitrary revision into the + current branch, but does not actually create the merge commit. The + user can then further adjust the merge, even when automatic conflict + resolution succeeded and/or adjust the commit message. + +- Key: m a (magit-merge-absorb) :: + + This command merges another local branch into the current branch and + then removes the former. + + Before the source branch is merged, it is first force pushed to its + push-remote, provided the respective remote branch already exists. + This ensures that the respective pull-request (if any) won't get + stuck on some obsolete version of the commits that are being merged. + Finally, if ~magit-branch-pull-request~ was used to create the merged + branch, then the respective remote branch is also removed. + +- Key: m d (magit-merge-dissolve) :: + + This command merges the current branch into another local branch and + then removes the former. The latter becomes the new current branch. + + Before the source branch is merged, it is first force pushed to its + push-remote, provided the respective remote branch already exists. + This ensures that the respective pull-request (if any) won't get + stuck on some obsolete version of the commits that are being merged. + Finally, if ~magit-branch-pull-request~ was used to create the merged + branch, then the respective remote branch is also removed. + +- Key: m s (magit-merge-squash) :: + + This command squashes the changes introduced by another branch or an + arbitrary revision into the current branch. This only applies the + changes made by the squashed commits. No information is preserved + that would allow creating an actual merge commit. Instead of this + command you should probably use a command from the apply transient. + +- Key: m p (magit-merge-preview) :: + + This command shows a preview of merging another branch or an + arbitrary revision into the current branch. + + Note that commands, that normally change how a diff is displayed, do + not work in buffers created by this command, because the underlying + Git command does not support diff arguments. + +When a merge is in progress, then the transient instead features the +following suffix commands. + +- Key: m m (magit-merge) :: + + After the user resolved conflicts, this command proceeds with the + merge. If some conflicts weren't resolved, then this command fails. + +- Key: m a (magit-merge-abort) :: + + This command aborts the current merge operation. + +** Resolving Conflicts + +When merging branches (or otherwise combining or changing history) +conflicts can occur. If you edited two completely different parts of +the same file in two branches and then merge one of these branches +into the other, then Git can resolve that on its own, but if you edit +the same area of a file, then a human is required to decide how the +two versions, or "sides of the conflict", are to be combined into one. + +Here we can only provide a brief introduction to the subject and point +you toward some tools that can help. If you are new to this, then +please also consult Git's own documentation as well as other +resources. + +If a file has conflicts and Git cannot resolve them by itself, then it +puts both versions into the affected file along with special markers +whose purpose is to denote the boundaries of the unresolved part of +the file and between the different versions. These boundary lines +begin with the strings consisting of seven times the same character, +one of ~<~, ~|~, ~=~ and ~>~, and are followed by information about the source +of the respective versions, e.g.: + +#+begin_example + <<<<<<< HEAD + Take the blue pill. + ======= + Take the red pill. + >>>>>>> feature +#+end_example + +In this case you have chosen to take the red pill on one branch and on +another you picked the blue pill. Now that you are merging these two +diverging branches, Git cannot possibly know which pill you want to +take. + +To resolve that conflict you have to create a version of the affected +area of the file by keeping only one of the sides, possibly by editing +it in order to bring in the changes from the other side, remove the +other versions as well as the markers, and then stage the result. A +possible resolution might be: + +#+begin_example + Take both pills. +#+end_example + +Often it is useful to see not only the two sides of the conflict but +also the "original" version from before the same area of the file was +modified twice on different branches. Instruct Git to insert that +version as well by running this command once: + +#+begin_src shell-script + git config --global merge.conflictStyle diff3 +#+end_src + +The above conflict might then have looked like this: + +#+begin_example + <<<<<<< HEAD + Take the blue pill. + ||||||| merged common ancestors + Take either the blue or the red pill, but not both. + ======= + Take the red pill. + >>>>>>> feature +#+end_example + +If that were the case, then the above conflict resolution would not +have been correct, which demonstrates why seeing the original version +alongside the conflicting versions can be useful. + +You can perform the conflict resolution completely by hand, but Emacs +also provides some packages that help in the process: Smerge, Ediff +(info:ediff), and Emerge (info:emacs#Emerge). Magit does not provide +its own tools for conflict resolution, but it does make using Smerge +and Ediff more convenient. (Ediff supersedes Emerge, so you probably +don't want to use the latter anyway.) + +In the Magit status buffer, files with unresolved conflicts are listed +in the "Unstaged changes" and/or "Staged changes" sections. They are +prefixed with the word "unmerged", which in this context essentially +is a synonym for "unresolved". + +Pressing ~RET~ while point is on such a file section shows a buffer +visiting that file, turns on ~smerge-mode~ in that buffer, and places +point inside the first area with conflicts. You should then resolve +that conflict using regular edit commands and/or Smerge commands. + +Unfortunately Smerge does not have a manual, but you can get a list of +commands and binding ~C-c ^ C-h~ and press ~RET~ while point is on a +command name to read its documentation. + +Normally you would edit one version and then tell Smerge to keep only +that version. Use ~C-c ^ m~ (~smerge-keep-mine~) to keep the ~HEAD~ +version or ~C-c ^ o~ (~smerge-keep-other~) to keep the version that +follows "|||||||". Then use ~C-c ^ n~ to move to the next conflicting +area in the same file. Once you are done resolving conflicts, return +to the Magit status buffer. The file should now be shown as +"modified", no longer as "unmerged", because Smerge automatically +stages the file when you save the buffer after resolving the last +conflict. + +Magit now wraps the mentioned Smerge commands, allowing you to use +these key bindings without having to go to the file-visiting buffer. +Additionally ~k~ (~magit-discard~) on a hunk with unresolved conflicts +asks which side to keep or, if point is on a side, then it keeps it +without prompting. Similarly ~k~ on a unresolved file ask which side +to keep. + +Alternatively you could use Ediff, which uses separate buffers for the +different versions of the file. To resolve conflicts in a file using +Ediff press ~e~ while point is on such a file in the status buffer. + +Ediff can be used for other purposes as well. For more information on +how to enter Ediff from Magit, see [[*Ediffing]]. Explaining how to use +Ediff is beyond the scope of this manual, instead see info:ediff. + +If you are unsure whether you should Smerge or Ediff, then use the +former. It is much easier to understand and use, and except for +truly complex conflicts, the latter is usually overkill. + +** Rebasing + +Also see [[man:git-rebase]] For information on how to resolve +conflicts that occur during rebases see the preceding section. + +- Key: r (magit-rebase) :: + + This transient prefix command binds the following suffix commands + along with the appropriate infix arguments and displays them in a + temporary buffer until a suffix is invoked. + +When no rebase is in progress, then the transient features the +following suffix commands. + +Using one of these commands /starts/ a rebase sequence. Git might then +stop somewhere along the way, either because you told it to do so, or +because applying a commit failed due to a conflict. When that +happens, then the status buffer shows information about the rebase +sequence which is in progress in a section similar to a log section. +See [[*Information About In-Progress Rebase]]. + +For information about the upstream and the push-remote, see [[*The Two +Remotes]]. + +- Key: r p (magit-rebase-onto-pushremote) :: + + This command rebases the current branch onto its push-remote. + + With a prefix argument or when the push-remote is either not + configured or unusable, then let the user first configure the + push-remote. + +- Key: r u (magit-rebase-onto-upstream) :: + + This command rebases the current branch onto its upstream branch. + + With a prefix argument or when the upstream is either not + configured or unusable, then let the user first configure + the upstream. + +- Key: r e (magit-rebase-branch) :: + + This command rebases the current branch onto a branch read in the + minibuffer. All commits that are reachable from head but not from + the selected branch TARGET are being rebased. + +- Key: r s (magit-rebase-subset) :: + + This command starts a non-interactive rebase sequence to transfer + commits from START to ~HEAD~ onto NEWBASE. START has to be selected + from a list of recent commits. + +By default Magit uses the ~--autostash~ argument, which causes +uncommitted changes to be stored in a stash before the rebase begins. +These changes are restored after the rebase completes and if possible +the stash is removed. If the stash does not apply cleanly, then the +stash is not removed. In case something goes wrong when resolving +the conflicts, this allows you to start over. + +Even though one of the actions is dedicated to interactive rebases, +the transient also features the infix argument ~--interactive~. This +can be used to turn one of the other, non-interactive rebase variants +into an interactive rebase. + +For example if you want to clean up a feature branch and at the same +time rebase it onto ~master~, then you could use ~r-iu~. But we recommend +that you instead do that in two steps. First use ~ri~ to cleanup the +feature branch, and then in a second step ~ru~ to rebase it onto ~master~. +That way if things turn out to be more complicated than you thought +and/or you make a mistake and have to start over, then you only have +to redo half the work. + +Explicitly enabling ~--interactive~ won't have an effect on the +following commands as they always use that argument anyway, even if it +is not enabled in the transient. + +- Key: r i (magit-rebase-interactive) :: + + This command starts an interactive rebase sequence. + +- Key: r f (magit-rebase-autosquash) :: + + This command combines squash and fixup commits with their intended + targets. + + By default only commits that are not reachable from the upstream + branch are potentially squashed into. If no upstream is configured + or with a prefix argument, the user is prompted for the first commit + to potentially squash into. + +- Key: r m (magit-rebase-edit-commit) :: + + This command starts an interactive rebase sequence that lets the + user edit a single older commit. + +- Key: r w (magit-rebase-reword-commit) :: + + This command starts an interactive rebase sequence that lets the + user reword a single older commit. + +- Key: r k (magit-rebase-remove-commit) :: + + This command removes a single older commit using rebase. + +When a rebase is in progress, then the transient instead features +the following suffix commands. + +- Key: r r (magit-rebase-continue) :: + + This command restart the current rebasing operation. + + In some cases this pops up a commit message buffer for you do edit. + With a prefix argument the old message is reused as-is. + +- Key: r s (magit-rebase-skip) :: + + This command skips the current commit and restarts the current + rebase operation. + +- Key: r e (magit-rebase-edit) :: + + This command lets the user edit the todo list of the current rebase + operation. + +- Key: r a (magit-rebase-abort) :: + + This command aborts the current rebase operation, restoring the + original branch. + +*** Editing Rebase Sequences + +- Key: C-c C-c (with-editor-finish) :: + + Finish the current editing session by returning with exit code 0. + Git then uses the rebase instructions it finds in the file. + +- Key: C-c C-k (with-editor-cancel) :: + + Cancel the current editing session by returning with exit code 1. + Git then forgoes starting the rebase sequence. + +- Key: RET (git-rebase-show-commit) :: + + Show the commit on the current line in another buffer and select + that buffer. + +- Key: SPC (git-rebase-show-or-scroll-up) :: + + Show the commit on the current line in another buffer without + selecting that buffer. If the revision buffer is already visible in + another window of the current frame, then instead scroll that window + up. + +- Key: DEL (git-rebase-show-or-scroll-down) :: + + Show the commit on the current line in another buffer without + selecting that buffer. If the revision buffer is already visible in + another window of the current frame, then instead scroll that window + down. + +- Key: p (git-rebase-backward-line) :: + + Move to previous line. + +- Key: n (forward-line) :: + + Move to next line. + +- Key: M-p (git-rebase-move-line-up) :: + + Move the current commit (or command) up. + +- Key: M-n (git-rebase-move-line-down) :: + + Move the current commit (or command) down. + +- Key: r (git-rebase-reword) :: + + Edit message of commit on current line. + +- Key: e (git-rebase-edit) :: + + Stop at the commit on the current line. + +- Key: s (git-rebase-squash) :: + + This command folds the commit on the current line into the previous + commit, giving the user a change to manually merge the two messages. + +- Key: S (git-rebase-squish) :: + + This command folds the commit on the current line into the previous + commit, discarding the message of the previous commit but giving the + user a change to edit the final message, based on the message of the + current commit. + + This action's indicator, shown in the list of commits, is ~fixup -c~ + (with a lower-case c). + +- Key: f (git-rebase-fixup) :: + + This command folds the commit on the current line into the previous + commit, using only the message of the previous commit as-is and + discarding the message of the current commit. + +- Key: F (git-rebase-alter) :: + + This command folds the commit on the current into the previous + commit, discarding the message of the previous commit and instead + using the message of the current commit as-is. + + This is like ~git-rebase-alter~, except that it uses the other + message. This is also like ~git-rebase-squish~, except that it lets + the user edit the message. + + This action's indicator, shown in the list of commits, is ~fixup -C~ + (with a upper-case C). + +- Key: k (git-rebase-kill-line) :: + + Comment the current action line, or if it is already commented, then + uncomment it. + +- Key: c (git-rebase-pick) :: + + Use commit on current line. + +- Key: x (git-rebase-exec) :: + + Insert a shell command to be run after the proceeding commit. + + If there already is such a command on the current line, then edit + that instead. With a prefix argument insert a new command even when + there already is one on the current line. With empty input remove + the command on the current line, if any. + +- Key: b (git-rebase-break) :: + + Insert a break action before the current line, instructing Git to + return control to the user. + +- Key: y (git-rebase-insert) :: + + Read an arbitrary commit and insert it below current line. + +- Key: C-x u (git-rebase-undo) :: + + Undo some previous changes. Like ~undo~ but works in read-only + buffers. + +- User Option: git-rebase-auto-advance :: + + Whether to move to next line after changing a line. + +- User Option: git-rebase-show-instructions :: + + Whether to show usage instructions inside the rebase buffer. + +- User Option: git-rebase-confirm-cancel :: + + Whether confirmation is required to cancel. + +When a rebase is performed with the ~--rebase-merges~ option, the +sequence will include a few other types of actions and the following +commands become relevant. + +- Key: l (git-rebase-label) :: + + This commands inserts a label action or edits the one at point. + +- Key: t (git-rebase-reset) :: + + This command inserts a reset action or edits the one at point. The + prompt will offer the labels that are currently present in the + buffer. + +- Key: MM (git-rebase-merge) :: + + The command inserts a merge action or edits the one at point. The + prompt will offer the labels that are currently present in the + buffer. Specifying a message to reuse via ~-c~ or ~-C~ is not + supported; an editor will always be invoked for the merge. + +- Key: Mt (git-rebase-merge-toggle-editmsg) :: + + This command toggles between the ~-C~ and ~-c~ options of the merge + action at point. These options both specify a commit whose message + should be reused. The lower-case variant instructs Git to invoke + the editor when creating the merge, allowing the user to edit the + message. + +*** Information About In-Progress Rebase + +While a rebase sequence is in progress, the status buffer features a +section that lists the commits that have already been applied as well +as the commits that still have to be applied. + +The commits are split in two halves. When rebase stops at a commit, +either because the user has to deal with a conflict or because s/he +explicitly requested that rebase stops at that commit, then point is +placed on the commit that separates the two groups, i.e., on ~HEAD~. +The commits above it have not been applied yet, while the ~HEAD~ and the +commits below it have already been applied. In between these two +groups of applied and yet-to-be applied commits, there sometimes is a +commit which has been dropped. + +Each commit is prefixed with a word and these words are additionally +shown in different colors to indicate the status of the commits. + +The following colors are used: + +- Commits that use the same foreground color as the ~default~ face have + not been applied yet. + +- Yellow commits have some special relationship to the commit rebase + stopped at. This is used for the words "join", "goal", "same" and + "work" (see below). + +- Gray commits have already been applied. + +- The blue commit is the ~HEAD~ commit. + +- The green commit is the commit the rebase sequence stopped at. If + this is the same commit as ~HEAD~ (e.g., because you haven't done + anything yet after rebase stopped at the commit, then this commit is + shown in blue, not green). There can only be a green *and* a blue + commit at the same time, if you create one or more new commits after + rebase stops at a commit. + +- Red commits have been dropped. They are shown for reference only, + e.g., to make it easier to diff. + +Of course these colors are subject to the color-theme in use. + +The following words are used: + +- Commits prefixed with ~pick~, ~reword~, ~edit~, ~squash~, and ~fixup~ have not + been applied yet. These words have the same meaning here as they do + in the buffer used to edit the rebase sequence. See [[*Editing Rebase + Sequences]]. When the ~--rebase-merges~ option was specified, + ~reset~, ~label~, and ~merge~ lines may also be present. + +- Commits prefixed with ~done~ and ~onto~ have already been applied. + It is possible for such a commit to be the ~HEAD~, in which case it + is blue. Otherwise it is grey. + + - The commit prefixed with ~onto~ is the commit on top of which all + the other commits are being re-applied. This commit itself did + not have to be re-applied, it is the commit rebase did rewind to + before starting to re-apply other commits. + + - Commits prefixed with ~done~ have already been re-applied. This + includes commits that have been re-applied but also new commits + that you have created during the rebase. + +- All other commits, those not prefixed with any of the above words, + are in some way related to the commit at which rebase stopped. + + To determine whether a commit is related to the stopped-at commit + their hashes, trees and patch-ids [fn:patch-id] are being compared. + The commit message is not used for this purpose. + + Generally speaking commits that are related to the stopped-at commit + can have any of the used colors, though not all color/word + combinations are possible. + + Words used for stopped-at commits are: + + - When a commit is prefixed with ~void~, then that indicates that + Magit knows for sure that all the changes in that commit have been + applied using several new commits. This commit is no longer + reachable from ~HEAD~, and it also isn't one of the commits that + will be applied when resuming the session. + + - When a commit is prefixed with ~join~, then that indicates that the + rebase sequence stopped at that commit due to a conflict - you now + have to join (merge) the changes with what has already been + applied. In a sense this is the commit rebase stopped at, but + while its effect is already in the index and in the worktree (with + conflict markers), the commit itself has not actually been applied + yet (it isn't the ~HEAD~). So it is shown in yellow, like the other + commits that still have to be applied. + + - When a commit is prefixed with ~stop~ or a /blue/ or /green/ ~same~, then + that indicates that rebase stopped at this commit, that it is + still applied or has been applied again, and that at least its + patch-id is unchanged. + + - When a commit is prefixed with ~stop~, then that indicates that + rebase stopped at that commit because you requested that + earlier, and its patch-id is unchanged. It might even still be + the exact same commit. + + - When a commit is prefixed with a /blue/ or /green/ ~same~, then that + indicates that while its tree or hash changed, its patch-id did + not. If it is blue, then it is the ~HEAD~ commit (as always for + blue). When it is green, then it no longer is ~HEAD~ because + other commit have been created since (but before continuing the + rebase). + + - When a commit is prefixed with ~goal~, a /yellow/ ~same,~ or ~work~, then + that indicates that rebase applied that commit but that you then + reset ~HEAD~ to an earlier commit (likely to split it up into + multiple commits), and that there are some uncommitted changes + remaining which likely (but not necessarily) originate from that + commit. + + - When a commit is prefixed with ~goal~, then that indicates that it + is still possible to create a new commit with the exact same + tree (the "goal") without manually editing any files, by + committing the index, or by staging all changes and then + committing that. This is the case when the original tree still + exists in the index or worktree in untainted form. + + - When a commit is prefixed with a yellow ~same~, then that + indicates that it is no longer possible to create a commit with + the exact same tree, but that it is still possible to create a + commit with the same patch-id. This would be the case if you + created a new commit with other changes, but the changes from + the original commit still exist in the index or working tree in + untainted form. + + - When a commit is prefixed with ~work~, then that indicates that + you reset ~HEAD~ to an earlier commit, and that there are some + staged and/or unstaged changes (likely, but not necessarily) + originating from that commit. However it is no longer possible + to create a new commit with the same tree or at least the same + patch-id because you have already made other changes. + + - When a commit is prefixed with ~poof~ or ~gone~, then that indicates + that rebase applied that commit but that you then reset ~HEAD~ to an + earlier commit (likely to split it up into multiple commits), and + that there are no uncommitted changes. + + - When a commit is prefixed with ~poof~, then that indicates that it + is no longer reachable from ~HEAD~, but that it has been replaced + with one or more commits, which together have the exact same + effect. + + - When a commit is prefixed with ~gone~, then that indicates that it + is no longer reachable from ~HEAD~ and that we also cannot + determine whether its changes are still in effect in one or more + new commits. They might be, but if so, then there must also be + other changes which makes it impossible to know for sure. + +Do not worry if you do not fully understand the above. That's okay, +you will acquire a good enough understanding through practice. + +For other sequence operations such as cherry-picking, a similar section +is displayed, but they lack some of the features described above, due +to limitations in the git commands used to implement them. Most +importantly these sequences only support "picking" a commit but not +other actions such as "rewording", and they do not keep track of the +commits which have already been applied. + +[fn:patch-id] The patch-id is a hash of the /changes/ introduced by a +commit. It differs from the hash of the commit itself, which is a +hash of the result of applying that change (i.e., the resulting trees +and blobs) as well as author and committer information, the commit +message, and the hashes of the parents of the commit. The patch-id +hash on the other hand is created only from the added and removed +lines, even line numbers and whitespace changes are ignored when +calculating this hash. The patch-ids of two commits can be used to +answer the question "Do these commits make the same change?". + +** Cherry Picking + +Also see [[man:git-cherry-pick]] + +- Key: A (magit-cherry-pick) :: + + This transient prefix command binds the following suffix commands + along with the appropriate infix arguments and displays them in a + temporary buffer until a suffix is invoked. + +When no cherry-pick or revert is in progress, then the transient +features the following suffix commands. + +- Key: A A (magit-cherry-copy) :: + + This command copies COMMITS from another branch onto the current + branch. If the region selects multiple commits, then those are + copied, without prompting. Otherwise the user is prompted for a + commit or range, defaulting to the commit at point. + +- Key: A a (magit-cherry-apply) :: + + This command applies the changes in COMMITS from another branch onto + the current branch. If the region selects multiple commits, then + those are used, without prompting. Otherwise the user is prompted + for a commit or range, defaulting to the commit at point. + + This command also has a top-level binding, which can be invoked + without using the transient by typing ~a~ at the top-level. + +The following commands not only apply some commits to some branch, but +also remove them from some other branch. The removal is performed +using either ~git-update-ref~ or if necessary ~git-rebase~. Both applying +commits as well as removing them using ~git-rebase~ can lead to +conflicts. If that happens, then these commands abort and you not +only have to resolve the conflicts but also finish the process the +same way you would have to if these commands didn't exist at all. + +- Key: A h (magit-cherry-harvest) :: + + This command moves the selected COMMITS that must be located on + another BRANCH onto the current branch instead, removing them from + the former. When this command succeeds, then the same branch is + current as before. + + Applying the commits on the current branch or removing them from the + other branch can lead to conflicts. When that happens, then this + command stops and you have to resolve the conflicts and then finish + the process manually. + +- Key: A d (magit-cherry-donate) :: + + This command moves the selected COMMITS from the current branch onto + another existing BRANCH, removing them from the former. When this + command succeeds, then the same branch is current as before. ~HEAD~ + is allowed to be detached initially. + + Applying the commits on the other branch or removing them from the + current branch can lead to conflicts. When that happens, then this + command stops and you have to resolve the conflicts and then finish + the process manually. + +- Key: A n (magit-cherry-spinout) :: + + This command moves the selected COMMITS from the current branch onto + a new branch BRANCH, removing them from the former. When this + command succeeds, then the same branch is current as before. + + Applying the commits on the other branch or removing them from the + current branch can lead to conflicts. When that happens, then this + command stops and you have to resolve the conflicts and then finish + the process manually. + +- Key: A s (magit-cherry-spinoff) :: + + This command moves the selected COMMITS from the current branch onto + a new branch BRANCH, removing them from the former. When this + command succeeds, then the new branch is checked out. + + Applying the commits on the other branch or removing them from the + current branch can lead to conflicts. When that happens, then this + command stops and you have to resolve the conflicts and then finish + the process manually. + +When a cherry-pick or revert is in progress, then the transient +instead features the following suffix commands. + +- Key: A A (magit-sequence-continue) :: + + Resume the current cherry-pick or revert sequence. + +- Key: A s (magit-sequence-skip) :: + + Skip the stopped at commit during a cherry-pick or revert sequence. + +- Key: A a (magit-sequence-abort) :: + + Abort the current cherry-pick or revert sequence. This discards all + changes made since the sequence started. + +*** Reverting + +- Key: V (magit-revert) :: + + This transient prefix command binds the following suffix commands + along with the appropriate infix arguments and displays them in a + temporary buffer until a suffix is invoked. + +When no cherry-pick or revert is in progress, then the transient +features the following suffix commands. + +- Key: V V (magit-revert-and-commit) :: + + Revert a commit by creating a new commit. Prompt for a commit, + defaulting to the commit at point. If the region selects multiple + commits, then revert all of them, without prompting. + +- Key: V v (magit-revert-no-commit) :: + + Revert a commit by applying it in reverse to the working tree. + Prompt for a commit, defaulting to the commit at point. If the + region selects multiple commits, then revert all of them, without + prompting. + +When a cherry-pick or revert is in progress, then the transient +instead features the following suffix commands. + +- Key: V V (magit-sequence-continue) :: + + Resume the current cherry-pick or revert sequence. + +- Key: V s (magit-sequence-skip) :: + + Skip the stopped at commit during a cherry-pick or revert sequence. + +- Key: V a (magit-sequence-abort) :: + + Abort the current cherry-pick or revert sequence. This discards all + changes made since the sequence started. + +** Resetting + +Also see [[man:git-reset]] + +- Key: x (magit-reset-quickly) :: + + Reset the ~HEAD~ and index to some commit read from the user and + defaulting to the commit at point, and possibly also reset the + working tree. With a prefix argument reset the working tree + otherwise don't. + +- Key: X m (magit-reset-mixed) :: + + Reset the ~HEAD~ and index to some commit read from the user and + defaulting to the commit at point. The working tree is kept as-is. + +- Key: X s (magit-reset-soft) :: + + Reset the ~HEAD~ to some commit read from the user and defaulting + to the commit at point. The index and the working tree are kept + as-is. + +- Key: X h (magit-reset-hard) :: + + Reset the ~HEAD~, index, and working tree to some commit read from the + user and defaulting to the commit at point. + +- Key: X k (magit-reset-keep) :: + + Reset the ~HEAD~, index, and working tree to some commit read from the + user and defaulting to the commit at point. Uncommitted changes are + kept as-is. + +- Key: X i (magit-reset-index) :: + + Reset the index to some commit read from the user and defaulting to + the commit at point. Keep the ~HEAD~ and working tree as-is, so if + the commit refers to the ~HEAD~, then this effectively unstages all + changes. + +- Key: X w (magit-reset-worktree) :: + + Reset the working tree to some commit read from the user and + defaulting to the commit at point. Keep the ~HEAD~ and index as-is. + +- Key: X f (magit-file-checkout) :: + + Update file in the working tree and index to the contents from a + revision. Both the revision and file are read from the user. + +** Stashing + +Also see [[man:git-stash]] + +- Key: z (magit-stash) :: + + This transient prefix command binds the following suffix commands + along with the appropriate infix arguments and displays them in a + temporary buffer until a suffix is invoked. + +- Key: z z (magit-stash-both) :: + + Create a stash of the index and working tree. Untracked files are + included according to infix arguments. One prefix argument is + equivalent to ~--include-untracked~ while two prefix arguments are + equivalent to ~--all~. + +- Key: z i (magit-stash-index) :: + + Create a stash of the index only. Unstaged and untracked changes + are not stashed. + +- Key: z w (magit-stash-worktree) :: + + Create a stash of unstaged changes in the working tree. Untracked + files are included according to infix arguments. One prefix + argument is equivalent to ~--include-untracked~ while two prefix + arguments are equivalent to ~--all~. + +- Key: z x (magit-stash-keep-index) :: + + Create a stash of the index and working tree, keeping index intact. + Untracked files are included according to infix arguments. One + prefix argument is equivalent to ~--include-untracked~ while two + prefix arguments are equivalent to ~--all~. + +- Key: z Z (magit-snapshot-both) :: + + Create a snapshot of the index and working tree. Untracked files + are included according to infix arguments. One prefix argument is + equivalent to ~--include-untracked~ while two prefix arguments are + equivalent to ~--all~. + +- Key: z I (magit-snapshot-index) :: + + Create a snapshot of the index only. Unstaged and untracked changes + are not stashed. + +- Key: z W (magit-snapshot-worktree) :: + + Create a snapshot of unstaged changes in the working tree. + Untracked files are included according to infix arguments. One + prefix argument is equivalent to ~--include-untracked~ while two + prefix arguments are equivalent to ~--all~-. + +- Key: z a (magit-stash-apply) :: + + Apply a stash to the working tree. + + When using a Git release before v2.38.0, simply run ~git stash apply~ + or with a prefix argument ~git stash apply --index~. + + When using Git v2.38.0 or later, behave more intelligently: + + First try ~git stash apply --index~, which tries to preserve the + index stored in the stash, if any. This may fail because applying + the stash could result in conflicts and those have to be stored in + the index, making it impossible to also store the stash's index + there. + + If ~git stash~ fails, then potentially fall back to using ~git apply~. + If the stash does not touch any unstaged files, then pass ~--3way~ to + that command. Otherwise ask the user whether to use that argument + or ~--reject~. Customize ~magit-no-confirm~ if you want to fall back + to using ~--3way~, without being prompted. + +- Key: z p (magit-stash-pop) :: + + Apply a stash to the working tree. On complete success (if the + stash can be applied without any conflicts, and while preserving + the stash's index) then remove the stash from stash list. + + When using a Git release before v2.38.0, simply run ~git stash pop~ + or with a prefix argument ~git stash pop --index~. + + When using Git v2.38.0 or later, behave more intelligently: + + First try ~git stash pop --index~, which tries to preserve the index + stored in the stash, if any. This may fail because applying the + stash could result in conflicts and those have to be stored in the + index, making it impossible to also store the stash's index there. + + If ~git stash~ fails, then potentially fall back to using ~git apply~. + If the stash does not touch any unstaged files, then pass ~--3way~ to + that command. Otherwise ask the user whether to use that argument + or ~--reject~. Customize ~magit-no-confirm~ if you want to fall back + to using ~--3way~, without being prompted. + +- Key: z k (magit-stash-drop) :: + + Remove a stash from the stash list. When the region is active, offer + to drop all contained stashes. + +- Key: z v (magit-stash-show) :: + + Show all diffs of a stash in a buffer. + +- Key: z b (magit-stash-branch) :: + + Create and checkout a new branch from an existing stash. The new + branch starts at the commit that was current when the stash was + created. + +- Key: z B (magit-stash-branch-here) :: + + Create and checkout a new branch from an existing stash. Use the + current branch or ~HEAD~ as the starting-point of the new branch. + Then apply the stash, dropping it if it applies cleanly. + +- Key: z f (magit-stash-format-patch) :: + + Create a patch from STASH. + +- Key: k (magit-stash-clear) :: + + Remove all stashes saved in REF's reflog by deleting REF. + +- Key: z l (magit-stash-list) :: + + List all stashes in a buffer. + +- User Option: magit-stashes-margin :: + + This option specifies whether the margin is initially shown in + stashes buffers and how it is formatted. + + The value has the form ~(INIT STYLE WIDTH AUTHOR AUTHOR-WIDTH)~. + + - If INIT is non-~nil~, then the margin is shown initially. + - STYLE controls how to format the author or committer date. It can + be one of ~age~ (to show the age of the commit), ~age-abbreviated~ (to + abbreviate the time unit to a character), or a string (suitable + for ~format-time-string~) to show the actual date. Option + ~magit-log-margin-show-committer-date~ controls which date is being + displayed. + - WIDTH controls the width of the margin. This exists for forward + compatibility and currently the value should not be changed. + - AUTHOR controls whether the name of the author is also shown by + default. + - AUTHOR-WIDTH has to be an integer. When the name of the author + is shown, then this specifies how much space is used to do so. + +* Transferring +** Remotes +*** Remote Commands + +The transient prefix command ~magit-remote~ is used to add remotes and +to make changes to existing remotes. This command only deals with +remotes themselves, not with branches or the transfer of commits. +Those features are available from separate transient commands. + +Also see [[man:git-remote]] + +- Key: M (magit-remote) :: + + This transient prefix command binds the following suffix commands + and displays them in a temporary buffer until a suffix is invoked. + + By default it also binds and displays the values of some + remote-related Git variables and allows changing their values. + +- User Option: magit-remote-direct-configure :: + + This option controls whether remote-related Git variables are + accessible directly from the transient ~magit-remote~. + + If ~t~ (the default) and a local branch is checked out, then + ~magit-remote~ features the variables for the upstream remote of that + branch, or if ~HEAD~ is detached, for ~origin~, provided that exists. + + If ~nil~, then ~magit-remote-configure~ has to be used to do so. + +- Key: M C (magit-remote-configure) :: + + This transient prefix command binds commands that set the value of + remote-related variables and displays them in a temporary buffer + until the transient is exited. + + With a prefix argument, this command always prompts for a remote. + + Without a prefix argument this depends on whether it was invoked as + a suffix of ~magit-remote~ and on the ~magit-remote-direct-configure~ + option. If ~magit-remote~ already displays the variables for the + upstream, then it does not make sense to invoke another transient + that displays them for the same remote. In that case this command + prompts for a remote. + +The variables are described in [[*Remote Git Variables]]. + +- Key: M a (magit-remote-add) :: + + This command add a remote and fetches it. The remote name and url + are read in the minibuffer. + +- Key: M r (magit-remote-rename) :: + + This command renames a remote. Both the old and the new names are + read in the minibuffer. + +- Key: M u (magit-remote-set-url) :: + + This command changes the url of a remote. Both the remote and the + new url are read in the minibuffer. + +- Key: M k (magit-remote-remove) :: + + This command deletes a remote, read in the minibuffer. + +- Key: M p (magit-remote-prune) :: + + This command removes stale remote-tracking branches for a remote + read in the minibuffer. + +- Key: M P (magit-remote-prune-refspecs) :: + + This command removes stale refspecs for a remote read in the + minibuffer. + + A refspec is stale if there no longer exists at least one branch + on the remote that would be fetched due to that refspec. A stale + refspec is problematic because its existence causes Git to refuse + to fetch according to the remaining non-stale refspecs. + + If only stale refspecs remain, then this command offers to either + delete the remote or to replace the stale refspecs with the default + refspec ("+refs/heads/*:refs/remotes/REMOTE/*"). + + This command also removes the remote-tracking branches that were + created due to the now stale refspecs. Other stale branches are + not removed. + +- User Option: magit-remote-add-set-remote.pushDefault :: + + This option controls whether the user is asked whether they want to + set ~remote.pushDefault~ after adding a remote. + + If ~ask~, then users is always ask. If ~ask-if-unset~, then the user is + only if the variable isn't set already. If ~nil~, then the user isn't + asked and the variable isn't set. If the value is a string, then + the variable is set without the user being asked, provided that the + name of the added remote is equal to that string and the variable + isn't already set. + +*** Remote Git Variables + +These variables can be set from the transient prefix command +~magit-remote-configure~. By default they can also be set from +~magit-remote~. See [[*Remote Commands]]. + +- Variable: remote.NAME.url :: + + This variable specifies the url of the remote named NAME. It can + have multiple values. + +- Variable: remote.NAME.fetch :: + + The refspec used when fetching from the remote named NAME. It can + have multiple values. + +- Variable: remote.NAME.pushurl :: + + This variable specifies the url used for pushing to the remote + named NAME. If it is not specified, then ~remote.NAME.url~ is used + instead. It can have multiple values. + +- Variable: remote.NAME.push :: + + The refspec used when pushing to the remote named NAME. It can + have multiple values. + +- Variable: remote.NAME.tagOpts :: + + This variable specifies what tags are fetched by default. If the + value is ~--no-tags~ then no tags are fetched. If the value is + ~--tags~, then all tags are fetched. If this variable has no value, + then only tags are fetched that are reachable from fetched branches. + +** Fetching + +Also see [[man:git-fetch]] For information about the upstream and the +push-remote, see [[*The Two Remotes]]. + +- Key: f (magit-fetch) :: + + This transient prefix command binds the following suffix commands + along with the appropriate infix arguments and displays them in a + temporary buffer until a suffix is invoked. + +- Key: f p (magit-fetch-from-pushremote) :: + + This command fetches from the current push-remote. + + With a prefix argument or when the push-remote is either not + configured or unusable, then let the user first configure the + push-remote. + +- Key: f u (magit-fetch-from-upstream) :: + + This command fetch from the upstream of the current branch. + + If the upstream is configured for the current branch and names + an existing remote, then use that. Otherwise try to use another + remote: If only a single remote is configured, then use that. + Otherwise if a remote named "origin" exists, then use that. + + If no remote can be determined, then this command is not available + from the ~magit-fetch~ transient prefix and invoking it directly + results in an error. + +- Key: f e (magit-fetch-other) :: + + This command fetch from a repository read from the minibuffer. + +- Key: f o (magit-fetch-branch) :: + + This command fetches a branch from a remote, both of which are read + from the minibuffer. + +- Key: f r (magit-fetch-refspec) :: + + This command fetches from a remote using an explicit refspec, both + of which are read from the minibuffer. + +- Key: f a (magit-fetch-all) :: + + This command fetches from all remotes. + +- Key: f m (magit-fetch-modules) :: + + This command fetches all submodules. With a prefix argument, it + acts as a transient prefix command, allowing the caller to set + options. + +- User Option: magit-pull-or-fetch :: + + By default fetch and pull commands are available from separate + transient prefix command. Setting this to ~t~ adds some (but not all) + of the above suffix commands to the ~magit-pull~ transient. + + If you do that, then you might also want to change the key binding + for these prefix commands, e.g.: + + #+BEGIN_SRC emacs-lisp + (setq magit-pull-or-fetch t) + (define-key magit-mode-map "f" 'magit-pull) ; was magit-fetch + (define-key magit-mode-map "F" nil) ; was magit-pull + #+END_SRC + +** Pulling + +Also see [[man:git-pull]] For information about the upstream and the +push-remote, see [[*The Two Remotes]]. + +- Key: F (magit-pull) :: + + This transient prefix command binds the following suffix commands + and displays them in a temporary buffer until a suffix is invoked. + +- Key: F p (magit-pull-from-pushremote) :: + + This command pulls from the push-remote of the current branch. + + With a prefix argument or when the push-remote is either not + configured or unusable, then let the user first configure the + push-remote. + +- Key: F u (magit-pull-from-upstream) :: + + This command pulls from the upstream of the current branch. + + With a prefix argument or when the upstream is either not + configured or unusable, then let the user first configure + the upstream. + +- Key: F e (magit-pull-branch) :: + + This command pulls from a branch read in the minibuffer. + +** Pushing + +Also see [[man:git-push]] For information about the upstream and the +push-remote, see [[*The Two Remotes]]. + +- Key: P (magit-push) :: + + This transient prefix command binds the following suffix commands + along with the appropriate infix arguments and displays them in a + temporary buffer until a suffix is invoked. + +- Key: P p (magit-push-current-to-pushremote) :: + + This command pushes the current branch to its push-remote. + + With a prefix argument or when the push-remote is either not + configured or unusable, then let the user first configure the + push-remote. + +- Key: P u (magit-push-current-to-upstream) :: + + This command pushes the current branch to its upstream branch. + + With a prefix argument or when the upstream is either not + configured or unusable, then let the user first configure + the upstream. + +- Key: P e (magit-push-current) :: + + This command pushes the current branch to a branch read in the + minibuffer. + +- Key: P o (magit-push-other) :: + + This command pushes an arbitrary branch or commit somewhere. Both + the source and the target are read in the minibuffer. + +- Key: P r (magit-push-refspecs) :: + + This command pushes one or multiple refspecs to a remote, both of + which are read in the minibuffer. + + To use multiple refspecs, separate them with commas. Completion is + only available for the part before the colon, or when no colon is + used. + +- Key: P m (magit-push-matching) :: + + This command pushes all matching branches to another repository. + + If only one remote exists, then push to that. Otherwise prompt for + a remote, offering the remote configured for the current branch as + default. + +- Key: P t (magit-push-tags) :: + + This command pushes all tags to another repository. + + If only one remote exists, then push to that. Otherwise prompt for + a remote, offering the remote configured for the current branch as + default. + +- Key: P T (magit-push-tag) :: + + This command pushes a tag to another repository. + +One of the infix arguments, ~--force-with-lease~, deserves a word of +caution. It is passed without a value, which means "permit a force +push as long as the remote-tracking branches match their counterparts +on the remote end". If you've set up a tool to do automatic fetches +(Magit itself does not provide such functionality), using +~--force-with-lease~ can be dangerous because you don't actually +control or know the state of the remote-tracking refs. In that case, +you should consider setting ~push.useForceIfIncludes~ to ~true~ +(available since Git 2.30). + +Two more push commands exist, which by default are not available from +the push transient. See their doc-strings for instructions on how to +add them to the transient. + +- Command: magit-push-implicitly args :: + + This command pushes somewhere without using an explicit refspec. + + This command simply runs ~git push -v [ARGS]~. ARGS are the infix + arguments. No explicit refspec arguments are used. Instead the + behavior depends on at least these Git variables: ~push.default~, + ~remote.pushDefault~, ~branch..pushRemote~, + ~branch..remote~, ~branch..merge~, and + ~remote..push~. + + If you add this suffix to a transient prefix without explicitly + specifying the description, then an attempt is made to predict + what this command will do. For example: + + #+BEGIN_SRC emacs-lisp + (transient-insert-suffix 'magit-push \"p\" + '(\"i\" magit-push-implicitly))" + #+END_SRC + +- Command: magit-push-to-remote remote args :: + + This command pushes to the remote REMOTE without using an explicit + refspec. The remote is read in the minibuffer. + + This command simply runs ~git push -v [ARGS] REMOTE~. ARGS are the + infix arguments. No refspec arguments are used. Instead the + behavior depends on at least these Git variables: ~push.default~, + ~remote.pushDefault~, ~branch..pushRemote~, + ~branch..remote~, ~branch..merge~, and + ~remote..push~. + +** Plain Patches + +- Key: W (magit-patch) :: + + This transient prefix command binds the following suffix commands + along with the appropriate infix arguments and displays them in a + temporary buffer until a suffix is invoked. + +- Key: W c (magit-patch-create) :: + + This command creates patches for a set commits. If the region marks + several commits, then it creates patches for all of them. Otherwise + it functions as a transient prefix command, which features several + infix arguments and binds itself as a suffix command. When this + command is invoked as a suffix of itself, then it creates a patch + using the specified infix arguments. + +- Key: w a (magit-patch-apply) :: + + This command applies a patch. This is a transient prefix command, + which features several infix arguments and binds itself as a suffix + command. When this command is invoked as a suffix of itself, then + it applies a patch using the specified infix arguments. + +- Key: W s (magit-patch-save) :: + + This command creates a patch from the current diff. + + Inside ~magit-diff-mode~ or ~magit-revision-mode~ buffers, ~C-x C-w~ is + also bound to this command. + +It is also possible to save a plain patch file by using ~C-x C-w~ inside +a ~magit-diff-mode~ or ~magit-revision-mode~ buffer. + +** Maildir Patches + +Also see [[man:git-am]] and [[man:git-apply]] + +- Key: w (magit-am) :: + + This transient prefix command binds the following suffix commands + along with the appropriate infix arguments and displays them in a + temporary buffer until a suffix is invoked. + +- Key: w w (magit-am-apply-patches) :: + + This command applies one or more patches. If the region marks + files, then those are applied as patches. Otherwise this command + reads a file-name in the minibuffer, defaulting to the file at + point. + +- Key: w m (magit-am-apply-maildir) :: + + This command applies patches from a maildir. + +- Key: w a (magit-patch-apply) :: + + This command applies a plain patch. For a longer description see + [[*Plain Patches]]. This command is only available from the ~magit-am~ + transient for historic reasons. + +When an "am" operation is in progress, then the transient instead +features the following suffix commands. + +- Key: w w (magit-am-continue) :: + + This command resumes the current patch applying sequence. + +- Key: w s (magit-am-skip) :: + + This command skips the stopped at patch during a patch applying + sequence. + +- Key: w a (magit-am-abort) :: + + This command aborts the current patch applying sequence. This + discards all changes made since the sequence started. + +* Miscellaneous +** Tagging + +Also see [[man:git-tag]] + +- Key: t (magit-tag) :: + + This transient prefix command binds the following suffix commands + along with the appropriate infix arguments and displays them in a + temporary buffer until a suffix is invoked. + +- Key: t t (magit-tag-create) :: + + This command creates a new tag with the given NAME at REV. With a + prefix argument it creates an annotated tag. + +- Key: t r (magit-tag-release) :: + + This commands creates a release tag. It assumes that release tags + match ~magit-release-tag-regexp~. + + First it prompts for the name of the new tag using the highest + existing tag as initial input and leaving it to the user to + increment the desired part of the version string. If you use + unconventional release tags or version numbers (e.g., + ~v1.2.3-custom.1~), you can set the ~magit-release-tag-regexp~ and + ~magit-tag-version-regexp-alist~ variables. + + If ~--annotate~ is enabled then it prompts for the message of the + new tag. The proposed tag message is based on the message of the + highest tag, provided that that contains the corresponding version + string and substituting the new version string for that. Otherwise + it proposes something like "Foo-Bar 1.2.3", given, for example, a + TAG "v1.2.3" and a repository located at something like + "/path/to/foo-bar". + +- Key: t k (magit-tag-delete) :: + + This command deletes one or more tags. If the region marks multiple + tags (and nothing else), then it offers to delete those. Otherwise, + it prompts for a single tag to be deleted, defaulting to the tag at + point. + +- Key: t p (magit-tag-prune) :: + + This command offers to delete tags missing locally from REMOTE, and + vice versa. + +** Notes + +Also see [[man:git-notes]] + +- Key: T (magit-notes) :: + + This transient prefix command binds the following suffix commands + along with the appropriate infix arguments and displays them in a + temporary buffer until a suffix is invoked. + +- Key: T T (magit-notes-edit) :: + + Edit the note attached to a commit, defaulting to the commit at + point. + + By default use the value of Git variable ~core.notesRef~ or + "refs/notes/commits" if that is undefined. + +- Key: T r (magit-notes-remove) :: + + Remove the note attached to a commit, defaulting to the commit at + point. + + By default use the value of Git variable ~core.notesRef~ or + "refs/notes/commits" if that is undefined. + +- Key: T p (magit-notes-prune) :: + + Remove notes about unreachable commits. + +It is possible to merge one note ref into another. That may result in +conflicts which have to resolved in the temporary worktree +".git/NOTES_MERGE_WORKTREE". + +- Key: T m (magit-notes-merge) :: + + Merge the notes of a ref read from the user into the current notes + ref. The current notes ref is the value of Git variable + ~core.notesRef~ or "refs/notes/commits" if that is undefined. + +When a notes merge is in progress then the transient features the +following suffix commands, instead of those listed above. + +- Key: T c (magit-notes-merge-commit) :: + + Commit the current notes ref merge, after manually resolving + conflicts. + +- Key: T a (magit-notes-merge-abort) :: + + Abort the current notes ref merge. + +The following variables control what notes reference ~magit-notes-*~, +~git notes~ and ~git show~ act on and display. Both the local and global +values are displayed and can be modified. + +- Variable: core.notesRef :: + + This variable specifies the notes ref that is displayed by default + and which commands act on by default. + +- Variable: notes.displayRef :: + + This variable specifies additional notes ref to be displayed in + addition to the ref specified by ~core.notesRef~. It can have + multiple values and may end with ~*~ to display all refs in the + ~refs/notes/~ namespace (or ~**~ if some names contain slashes). + +** Submodules + +Also see [[man:git-submodule]] + +*** Listing Submodules + +The command ~magit-list-submodules~ displays a list of the current +repository's submodules in a separate buffer. It's also possible to +display information about submodules directly in the status buffer of +the super-repository by adding ~magit-insert-modules~ to the hook +~magit-status-sections-hook~ as described in [[*Status Module Sections]]. + +- Command: magit-list-submodules :: + + This command displays a list of the current repository's populated + submodules in a separate buffer. + + It can be invoked by pressing ~RET~ on the section titled "Modules". + +- User Option: magit-submodule-list-columns :: + + This option controls what columns are displayed by the command + ~magit-list-submodules~ and how they are displayed. + + Each element has the form ~(HEADER WIDTH FORMAT PROPS)~. + + HEADER is the string displayed in the header. WIDTH is the width + of the column. FORMAT is a function that is called with one + argument, the repository identification (usually its basename), + and with ~default-directory~ bound to the toplevel of its working + tree. It has to return a string to be inserted or ~nil~. PROPS is + an alist that supports the keys ~:right-align~, ~:pad-right~ and + ~:sort~. + + The ~:sort~ function has a weird interface described in the + docstring of ~tabulated-list--get-sort~. Alternatively ~<~ and + ~magit-repolist-version<~ can be used as those functions are + automatically replaced with functions that satisfy the interface. + Set ~:sort~ to ~nil~ to inhibit sorting; if unspecified, then the + column is sortable using the default sorter. + + You may wish to display a range of numeric columns using just one + character per column and without any padding between columns, in + which case you should use an appropriate HEADER, set WIDTH to 1, + and set ~:pad-right~ to 9. ~+~ is substituted for numbers higher than 9. + +*** Submodule Transient + +- Key: o (magit-submodule) :: + + This transient prefix command binds the following suffix commands + along with the appropriate infix arguments and displays them in a + temporary buffer until a suffix is invoked. + +Some of the below commands default to act on the modules that are +selected using the region. For brevity their description talk about +"the selected modules", but if no modules are selected, then they act +on the current module instead, or if point isn't on a module, then the +read a single module to act on. With a prefix argument these commands +ignore the selection and the current module and instead act on all +suitable modules. + +- Key: o a (magit-submodule-add) :: + + This commands adds the repository at URL as a module. Optional PATH + is the path to the module relative to the root of the super-project. + If it is ~nil~ then the path is determined based on URL. + +- Key: o r (magit-submodule-register) :: + + This command registers the selected modules by copying their urls + from ".gitmodules" to "$GIT_DIR/config". These values can then be + edited before running ~magit-submodule-populate~. If you don't need + to edit any urls, then use the latter directly. + +- Key: o p (magit-submodule-populate) :: + + This command creates the working directory or directories of the + selected modules, checking out the recorded commits. + +- Key: o u (magit-submodule-update) :: + + This command updates the selected modules checking out the recorded + commits. + +- Key: o s (magit-submodule-synchronize) :: + + This command synchronizes the urls of the selected modules, copying + the values from ".gitmodules" to the ".git/config" of the + super-project as well those of the modules. + +- Key: o d (magit-submodule-unpopulate) :: + + This command removes the working directory of the selected modules. + +- Key: o l (magit-list-submodules) :: + + This command displays a list of the current repository's modules. + +- Key: o f (magit-fetch-modules) :: + + This command fetches all populated modules. With a prefix argument, + it acts as a transient prefix command, allowing the caller to set + options. + + Also fetch the super-repository, because ~git fetch~ does not + support not doing that. + +** Subtree + +Also see [[man:git-subtree]] + +- Key: O (magit-subtree) :: + + This transient prefix command binds the two sub-transients; one for + importing a subtree and one for exporting a subtree. + +- Key: O i (magit-subtree-import) :: + + This transient prefix command binds the following suffix commands + along with the appropriate infix arguments and displays them in a + temporary buffer until a suffix is invoked. + + The suffixes of this command import subtrees. + + If the ~--prefix~ argument is set, then the suffix commands use that + prefix without prompting the user. If it is unset, then they read + the prefix in the minibuffer. + +- Key: O i a (magit-subtree-add) :: + + This command adds COMMIT from REPOSITORY as a new subtree at PREFIX. + +- Key: O i c (magit-subtree-add-commit) :: + + This command add COMMIT as a new subtree at PREFIX. + +- Key: O i m (magit-subtree-merge) :: + + This command merges COMMIT into the PREFIX subtree. + +- Key: O i f (magit-subtree-pull) :: + + This command pulls COMMIT from REPOSITORY into the PREFIX subtree. + +- Key: O e (magit-subtree-export) :: + + This transient prefix command binds the following suffix commands + along with the appropriate infix arguments and displays them in a + temporary buffer until a suffix is invoked. + + The suffixes of this command export subtrees. + + If the ~--prefix~ argument is set, then the suffix commands use that + prefix without prompting the user. If it is unset, then they read + the prefix in the minibuffer. + +- Key: O e p (magit-subtree-push) :: + + This command extract the history of the subtree PREFIX and pushes it + to REF on REPOSITORY. + +- Key: O e s (magit-subtree-split) :: + + This command extracts the history of the subtree PREFIX. + +** Worktree + +Also see [[man:git-worktree]] + +- Key: Z (magit-worktree) :: + + This transient prefix command binds the following suffix commands + and displays them in a temporary buffer until a suffix is invoked. + +- Key: Z b (magit-worktree-checkout) :: + + Checkout BRANCH in a new worktree at PATH. + +- Key: Z c (magit-worktree-branch) :: + + Create a new BRANCH and check it out in a new worktree at PATH. + +- Key: Z m (magit-worktree-move) :: + + Move an existing worktree to a new PATH. + +- Key: Z k (magit-worktree-delete) :: + + Delete a worktree, defaulting to the worktree at point. + The primary worktree cannot be deleted. + +- Key: Z g (magit-worktree-status) :: + + Show the status for the worktree at point. + + If there is no worktree at point, then read one in the minibuffer. + If the worktree at point is the one whose status is already being + displayed in the current buffer, then show it in Dired instead. + +If you want the status buffer to list worktrees, add the function +~magit-insert-worktrees~ to ~magit-status-sections-hook~ as described +in [[*Status Sections]]. If there is only one worktree, this function +inserts nothing. + +** Sparse checkouts + +Sparse checkouts provide a way to restrict the working tree to a +subset of directories. See [[man:git-sparse-checkout]] + +*Warning*: Git introduced the ~git sparse-checkout~ command in version +2.25 and still advertises it as experimental and subject to change. +Magit's interface should be considered the same. In particular, if +Git introduces a backward incompatible change, Magit's sparse checkout +functionality may be updated in a way that requires a more recent Git +version. + +- Key: > (magit-sparse-checkout) :: + + This transient prefix command binds the following suffix commands + and displays them in a temporary buffer until a suffix is invoked. + +- Key: > e (magit-sparse-checkout-enable) :: + + This command initializes a sparse checkout that includes only the + files in the top-level directory. + + Note that ~magit-sparse-checkout-set~ and + ~magit-sparse-checkout-add~ automatically initialize a sparse + checkout if necessary. However, you may want to call + ~magit-sparse-checkout-enable~ explicitly to re-initialize a sparse + checkout after calling ~magit-sparse-checkout-disable~, to pass + additional arguments to ~git sparse-checkout init~, or to execute + the initialization asynchronously. + +- Key: > s (magit-sparse-checkout-set) :: + + This command takes a list of directories and configures the sparse + checkout to include only files in those subdirectories. Any + previously included directories are excluded unless they are in the + provided list of directories. + +- Key: > a (magit-sparse-checkout-add) :: + + This command is like ~magit-sparse-checkout-set~, but instead adds + the specified list of directories to the set of directories that is + already included in the sparse checkout. + +- Key: > r (magit-sparse-checkout-reapply) :: + + This command applies the currently configured sparse checkout + patterns to the working tree. This is useful to call if excluded + files have been checked out after operations such as merging or + rebasing. + +- Key: > d (magit-sparse-checkout-disable) :: + + This command restores the full checkout. To return to the previous + sparse checkout, call ~magit-sparse-checkout-enable~. + +A sparse checkout can also be initiated when cloning a repository by +using the ~magit-clone-sparse~ command in the ~magit-clone~ transient +(see [[*Cloning Repository]]). + +If you want the status buffer to indicate when a sparse checkout is +enabled, add the function ~magit-sparse-checkout-insert-header~ to +~magit-status-headers-hook~. + +** Bundle + +Also see [[man:git-bundle]] + +- Command: magit-bundle :: + + This transient prefix command binds several suffix commands for + running ~git bundle~ subcommands and displays them in a temporary + buffer until a suffix is invoked. + +** Common Commands + +- Command: magit-switch-to-repository-buffer :: ++ Command: magit-switch-to-repository-buffer-other-window :: ++ Command: magit-switch-to-repository-buffer-other-frame :: ++ Command: magit-display-repository-buffer :: + + These commands read any existing Magit buffer that belongs to the + current repository from the user and then switch to the selected + buffer (without refreshing it). + + The last variant uses ~magit-display-buffer~ to do so and thus + respects ~magit-display-buffer-function~. + +These are some of the commands that can be used in all buffers whose +major-modes derive from ~magit-mode~. There are other common commands +beside the ones below, but these didn't fit well anywhere else. + +- Key: C-w (magit-copy-section-value) :: + + This command saves the value of the current section to the + ~kill-ring~, and, provided that the current section is a commit, + branch, or tag section, it also pushes the (referenced) revision to + the ~magit-revision-stack~. + + When the current section is a branch or a tag, and a prefix argument + is used, then it saves the revision at its tip to the ~kill-ring~ + instead of the reference name. + + When the region is active, this command saves that to the + ~kill-ring~, like ~kill-ring-save~ would, instead of behaving as + described above. If a prefix argument is used and the region is + within a hunk, then it strips the diff marker column and keeps + only either the added or removed lines, depending on the sign of + the prefix argument. + +- Key: M-w (magit-copy-buffer-revision) :: + + This command saves the revision being displayed in the current buffer + to the ~kill-ring~ and also pushes it to the ~magit-revision-stack~. It + is mainly intended for use in ~magit-revision-mode~ buffers, the only + buffers where it is always unambiguous exactly which revision should + be saved. + + Most other Magit buffers usually show more than one revision, in + some way or another, so this command has to select one of them, and + that choice might not always be the one you think would have been + the best pick. + +Outside of Magit ~M-w~ and ~C-w~ are usually bound to ~kill-ring-save~ and +~kill-region~, and these commands would also be useful in Magit buffers. +Therefore when the region is active, then both of these commands +behave like ~kill-ring-save~ instead of as described above. + +** Wip Modes + +Git keeps *committed* changes around long enough for users to recover +changes they have accidentally deleted. It does so by not garbage +collecting any committed but no longer referenced objects for a +certain period of time, by default 30 days. + +But Git does *not* keep track of *uncommitted* changes in the working tree +and not even the index (the staging area). Because Magit makes it so +convenient to modify uncommitted changes, it also makes it easy to +shoot yourself in the foot in the process. + +For that reason Magit provides a global mode that saves *tracked* files +to work-in-progress references after or before certain actions. (At +present untracked files are never saved and for technical reasons +nothing is saved before the first commit has been created). + +Two separate work-in-progress references are used to track the state +of the index and of the working tree: ~refs/wip/index/~ and +~refs/wip/wtree/~, where ~~ is the full ref of the +current branch, e.g., ~refs/heads/master~. When the ~HEAD~ is detached +then ~HEAD~ is used in place of ~~. + +Checking out another branch (or detaching ~HEAD~) causes the use of +different wip refs for subsequent changes. + +- User Option: magit-wip-mode :: + + When this mode is enabled, then uncommitted changes are committed + to dedicated work-in-progress refs whenever appropriate (i.e., when + dataloss would be a possibility otherwise). + + Setting this variable directly does not take effect; either use the + Custom interface to do so or call the respective mode function. + +To view the log for a branch and its wip refs use the commands +~magit-wip-log~ and ~magit-wip-log-current~. You should use ~--graph~ when +using these commands. + +- Command: magit-wip-log :: + + This command shows the log for a branch and its wip refs. + With a negative prefix argument only the worktree wip ref is shown. + + The absolute numeric value of the prefix argument controls how many + "branches" of each wip ref are shown. This is only relevant if the + value of ~magit-wip-merge-branch~ is ~nil~. + +- Command: magit-wip-log-current :: + + This command shows the log for the current branch and its wip refs. + With a negative prefix argument only the worktree wip ref is shown. + + The absolute numeric value of the prefix argument controls how many + "branches" of each wip ref are shown. This is only relevant if the + value of ~magit-wip-merge-branch~ is ~nil~. + +- Key: X w (magit-reset-worktree) :: + + This command resets the working tree to some commit read from the + user and defaulting to the commit at point, while keeping the ~HEAD~ + and index as-is. + + This can be used to restore files to the state committed to a wip + ref. Note that this will discard any unstaged changes that might + have existed before invoking this command (but of course only after + committing that to the working tree wip ref). + +Note that even if you enable ~magit-wip-mode~ this won't give you +perfect protection. The most likely scenario for losing changes +despite the use of ~magit-wip-mode~ is making a change outside Emacs and +then destroying it also outside Emacs. In some such a scenario, +Magit, being an Emacs package, didn't get the opportunity to keep you +from shooting yourself in the foot. + +When you are unsure whether Magit did commit a change to the wip refs, +then you can explicitly request that all changes to all tracked files +are being committed. + +- Key: M-x magit-wip-commit :: + + This command commits all changes to all tracked files to the index + and working tree work-in-progress refs. Like the modes described above, + it does not commit untracked files, but it does check all tracked + files for changes. Use this command when you suspect that the modes + might have overlooked a change made outside Emacs/Magit. + +- User Option: magit-wip-namespace :: + + The namespace used for work-in-progress refs. It has to end with + a slash. The wip refs are named ~index/~ and + ~wtree/~. When snapshots are created while + the ~HEAD~ is detached then ~HEAD~ is used in place of ~~. + +- User Option: magit-wip-mode-lighter :: + + Mode-line lighter for ~magit-wip--mode~. + +*** Wip Graph + +- User Option: magit-wip-merge-branch :: + + This option controls whether the current branch is merged into the + wip refs after a new commit was created on the branch. + + If non-~nil~ and the current branch has new commits, then it is + merged into the wip ref before creating a new wip commit. This + makes it easier to inspect wip history and the wip commits are + never garbage collected. + + If ~nil~ and the current branch has new commits, then the wip ref + is reset to the tip of the branch before creating a new wip + commit. With this setting wip commits are eventually garbage + collected. + + If ~immediately~, then use ~git-commit-post-finish-hook~ to + create the merge commit. This is discouraged because it can + lead to a race condition, e.g., during rebases. + +When ~magit-wip-merge-branch~ is ~t~, then the history looks like this: + +#+begin_example + ,*--*--*--*--*--* refs/wip/index/refs/heads/master + / / / +A-----B-----C refs/heads/master +#+end_example + +When ~magit-wip-merge-branch~ is ~nil~, then creating a commit on the real +branch and then making a change causes the wip refs to be recreated to +fork from the new commit. But the old commits on the wip refs are not +lost. They are still available from the reflog. To make it easier to +see when the fork point of a wip ref was changed, an additional commit +with the message "restart autosaving" is created on it (~xxO~ commits +below are such boundary commits). + +Starting with + +#+begin_example + BI0---BI1 refs/wip/index/refs/heads/master + / +A---B refs/heads/master + \ + BW0---BW1 refs/wip/wtree/refs/heads/master +#+end_example + +and committing the staged changes and editing and saving a file would +result in + +#+begin_example + BI0---BI1 refs/wip/index/refs/heads/master + / +A---B---C refs/heads/master + \ \ + \ CW0---CW1 refs/wip/wtree/refs/heads/master + \ + BW0---BW1 refs/wip/wtree/refs/heads/master@{2} +#+end_example + +The fork-point of the index wip ref is not changed until some change +is being staged. Likewise just checking out a branch or creating a +commit does not change the fork-point of the working tree wip ref. The +fork-points are not adjusted until there actually is a change that +should be committed to the respective wip ref. + +** Commands for Buffers Visiting Files + +By default Magit defines a few global key bindings. These bindings +are a compromise between providing no bindings at all and providing +the better bindings I would have liked to use instead. Magit cannot +provide the set of recommended bindings by default because those key +sequences are strictly reserved for bindings added by the user. +Also see [[*Global Bindings]] and [[info:elisp#Key Binding Conventions]]. + +To use the recommended bindings, add this to your init file and +restart Emacs. + +#+begin_src emacs-lisp + (setq magit-define-global-key-bindings 'recommended) +#+end_src + +If you don't want Magit to add any bindings to the global keymap at +all, add this to your init file and restart Emacs. + +#+begin_src emacs-lisp + (setq magit-define-global-key-bindings nil) +#+end_src + +- Key: C-c f (magit-file-dispatch) :: +- Key: C-c f s (magit-stage-file) :: +- Key: C-c f s (magit-stage-buffer-file) :: +- Key: C-c f u (magit-unstage-file) :: +- Key: C-c f u (magit-unstage-buffer-file) :: +- Key: C-c f , x (magit-file-untrack) :: +- Key: C-c f , r (magit-file-rename) :: +- Key: C-c f , k (magit-file-delete) :: +- Key: C-c f , c (magit-file-checkout) :: +- Key: C-c f D (magit-diff) :: +- Key: C-c f d (magit-diff-buffer-file) :: +- Key: C-c f L (magit-log) :: +- Key: C-c f l (magit-log-buffer-file) :: +- Key: C-c f t (magit-log-trace-definition) :: +- Key: C-c f M (magit-log-merged) :: +- Key: C-c f B (magit-blame) :: +- Key: C-c f b (magit-blame-additions) :: +- Key: C-c f r (magit-blame-removal) :: +- Key: C-c f f (magit-blame-reverse) :: +- Key: C-c f m (magit-blame-echo) :: +- Key: C-c f q (magit-blame-quit) :: +- Key: C-c f p (magit-blob-previous) :: +- Key: C-c f n (magit-blob-next) :: +- Key: C-c f v (magit-find-file) :: +- Key: C-c f V (magit-blob-visit-file) :: +- Key: C-c f g (magit-status-here) :: +- Key: C-c f G (magit-display-repository-buffer) :: +- Key: C-c f c (magit-commit) :: +- Key: C-c f e (magit-edit-line-commit) :: + + Each of these commands is documented individually right below, + alongside their default key bindings. The bindings shown above + are the recommended bindings, which you can enable by following + the instructions further up. + +- Key: C-c M-g (magit-file-dispatch) :: + + This transient prefix command binds the following suffix commands + and displays them in a temporary buffer until a suffix is invoked. + +- Key: C-c M-g s (magit-stage-file) :: +- Key: C-c M-g s (magit-stage-buffer-file) :: + + Stage all changes to the file being visited in the current buffer. + When not visiting a file, then the first command is used, which + prompts for a file. + +- Key: C-c M-g u (magit-unstage-file) :: +- Key: C-c M-g u (magit-unstage-buffer-file) :: + + Unstage all changes to the file being visited in the current buffer. + When not visiting a file, then the first command is used, which + prompts for a file. + +- Key: C-c M-g , x (magit-file-untrack) :: + + This command untracks a file read from the user, defaulting to the + visited file. + +- Key: C-c M-g , r (magit-file-rename) :: + + This command renames a file read from the user, defaulting to the + visited file. + +- Key: C-c M-g , k (magit-file-delete) :: + + This command deletes a file read from the user, defaulting to the + visited file. + +- Key: C-c M-g , c (magit-file-checkout) :: + + This command updates a file in the working tree and index to the + contents from a revision. Both the revision and file are read + from the user. + +- Key: C-c M-g D (magit-diff) :: + + This transient prefix command binds several diff suffix commands and + infix arguments and displays them in a temporary buffer until a + suffix is invoked. See [[*Diffing]]. + + This is the same command that ~d~ is bound to in Magit buffers. + If this command is invoked from a file-visiting buffer, then the + initial value of the option (~--~) that limits the diff to certain + file(s) is set to the visited file. + +- Key: C-c M-g d (magit-diff-buffer-file) :: + + This command shows the diff for the file of blob that the current + buffer visits. + +- User Option: magit-diff-buffer-file-locked :: + + This option controls whether ~magit-diff-buffer-file~ uses a dedicated + buffer. See [[*Modes and Buffers]]. + +- Key: C-c M-g L (magit-log) :: + + This transient prefix command binds several log suffix commands and + infix arguments and displays them in a temporary buffer until a + suffix is invoked. See [[*Logging]]. + + This is the same command that ~l~ is bound to in Magit buffers. + If this command is invoked from a file-visiting buffer, then the + initial value of the option (~--~) that limits the log to certain + file(s) is set to the visited file. + +- Key: C-c M-g l (magit-log-buffer-file) :: + + This command shows the log for the file of blob that the current + buffer visits. Renames are followed when a prefix argument is used + or when ~--follow~ is an active log argument. When the region is + active, the log is restricted to the selected line range. + +- User Option: magit-log-buffer-file-locked :: + + This option controls whether ~magit-log-buffer-file~ uses a dedicated + buffer. See [[*Modes and Buffers]]. + +- Key: C-c M-g t (magit-log-trace-definition) :: + + This command shows the log for the definition at point. + +- Key: C-c M-g M (magit-log-merged) :: + + This command reads a commit and a branch in shows a log concerning + the merge of the former into the latter. This shows multiple commits + even in case of a fast-forward merge. + +- Key: C-c M-g B (magit-blame) :: + + This transient prefix command binds all blaming suffix commands + along with the appropriate infix arguments and displays them in a + temporary buffer until a suffix is invoked. + + For more information about this and the following commands also see + [[*Blaming]]. + + In addition to the ~magit-blame~ sub-transient, the dispatch transient + also binds several blaming suffix commands directly. See [[*Blaming]] + for information about those commands and bindings. + +- Key: C-c M-g p (magit-blob-previous) :: + + This command visits the previous blob which modified the current + file. + +- Key: C-c M-g n (magit-blob-next) :: + + This command visits the next blob which modified the current file. + +- Key: C-c M-g v (magit-find-file) :: + + This command reads a revision and file and visits the respective + blob. + +- Key: C-c M-g V (magit-blob-visit-file) :: + + This command visits the file from the working tree, corresponding + to the current blob. When visiting a blob or the version from the + index, then it goes to the same location in the respective file in + the working tree. + +- Key: C-c M-g g (magit-status-here) :: + + This command displays the status of the current repository in a + buffer, like ~magit-status~ does. Additionally it tries to go to + the position in that buffer, which corresponds to the position + in the current file-visiting buffer (if any). + + Before doing so, save all file-visiting buffers belonging to the + current repository without prompting. + +- Key: C-c M-g G (magit-display-repository-buffer) :: + + This command reads and displays a Magit buffer belonging to the + current repository, without refreshing it. + +- Key: C-c M-g c (magit-commit) :: + + This transient prefix command binds the following suffix commands + along with the appropriate infix arguments and displays them in a + temporary buffer until a suffix is invoked. See [[*Initiating a + Commit]]. + +- Key: C-c M-g e (magit-edit-line-commit) :: + + This command makes the commit editable that added the current line. + + With a prefix argument it makes the commit editable that removes the + line, if any. The commit is determined using ~git blame~ and made + editable using ~git rebase --interactive~ if it is reachable from + ~HEAD~, or by checking out the commit (or a branch that points at it) + otherwise. + +** Minor Mode for Buffers Visiting Blobs + +The ~magit-blob-mode~ enables certain Magit features in blob-visiting +buffers. Such buffers can be created using ~magit-find-file~ and some +of the commands mentioned below, which also take care of turning on +this minor mode. Currently this mode only establishes a few key +bindings, but this might be extended. + +- Key: p (magit-blob-previous) :: + + This command visits the previous blob that modified the current + file. + +- Key: n (magit-blob-next) :: + + This command visit the next blob that modified the current file. + +- Key: q (magit-bury-or-kill-buffer) :: + + This command buries the current buffer, if that is being displayed + in multiple windows and/or when a prefix argument is used. If + neither is the case, it instead kills the current buffer. + +You might want to bind ~u~ to another command. Suitable commands +include ~bury-buffer~, ~magit-bury-buffer~ and ~magit-kill-this-buffer~. + +* Customizing + +Both Git and Emacs are highly customizable. Magit is both a Git +porcelain as well as an Emacs package, so it makes sense to customize +it using both Git variables as well as Emacs options. However this +flexibility doesn't come without problems, including but not limited +to the following. + +- Some Git variables automatically have an effect in Magit without + requiring any explicit support. Sometimes that is desirable - in + other cases, it breaks Magit. + + When a certain Git setting breaks Magit but you want to keep using + that setting on the command line, then that can be accomplished by + overriding the value for Magit only by appending something like + ~("-c" "some.variable=compatible-value")~ to + ~magit-git-global-arguments~. + +- Certain settings like ~fetch.prune=true~ are respected by Magit + commands (because they simply call the respective Git command) but + their value is not reflected in the respective transient buffers. + In this case the ~--prune~ argument in ~magit-fetch~ might be active or + inactive, but that doesn't keep the Git variable from being honored + by the suffix commands anyway. So pruning might happen despite the + ~--prune~ arguments being displayed in a way that seems to indicate + that no pruning will happen. + +I intend to address these and similar issues in a future release. + +** Per-Repository Configuration + +Magit can be configured on a per-repository level using both Git +variables as well as Emacs options. + +To set a Git variable for one repository only, simply set it in +~/path/to/repo/.git/config~ instead of ~$HOME/.gitconfig~ or +~/etc/gitconfig~. See [[man:git-config]] + +Similarly, Emacs options can be set for one repository only by editing +~/path/to/repo/.dir-locals.el~. See [[info:emacs#Directory Variables]]. +For example to disable automatic refreshes of file-visiting buffers in +just one huge repository use this: + +- ~/path/to/huge/repo/.dir-locals.el~ + + #+BEGIN_SRC emacs-lisp + ((nil . ((magit-refresh-buffers . nil)))) + #+END_SRC + +It might only be costly to insert certain information into Magit +buffers for repositories that are exceptionally large, in which case +you can disable the respective section inserters just for that +repository: + +- ~/path/to/tag/invested/repo/.dir-locals.el~ + + #+BEGIN_SRC emacs-lisp + ((magit-status-mode + . ((eval . (magit-disable-section-inserter 'magit-insert-tags-header))))) + #+END_SRC + +# new list +- Function: magit-disable-section-inserter fn :: + + This function disables the section inserter FN in the current + repository. It is only intended for use in ~.dir-locals.el~ and + ~.dir-locals-2.el~. + +If you want to apply the same settings to several, but not all, +repositories then keeping the repository-local config files in sync +would quickly become annoying. To avoid that you can create config +files for certain classes of repositories (e.g., "huge repositories") +and then include those files in the per-repository config files. +For example: + +- ~/path/to/huge/repo/.git/config~ + + #+BEGIN_SRC conf + [include] + path = /path/to/huge-gitconfig + #+END_SRC + +- ~/path/to/huge-gitconfig~ + + #+BEGIN_SRC conf + [status] + showUntrackedFiles = no + #+END_SRC + +- ~$HOME/.emacs.d/init.el~ + + #+BEGIN_SRC emacs-lisp + (dir-locals-set-class-variables 'huge-git-repository + '((nil . ((magit-refresh-buffers . nil))))) + + (dir-locals-set-directory-class + "/path/to/huge/repo/" 'huge-git-repository) + #+END_SRC + +** Essential Settings + +The next three sections list and discuss several variables that many +users might want to customize, for safety and/or performance reasons. + +*** Safety + +This section discusses various variables that you might want to +change (or *not* change) for safety reasons. + +Git keeps *committed* changes around long enough for users to recover +changes they have accidentally been deleted. It does not do the same +for *uncommitted* changes in the working tree and not even the index +(the staging area). Because Magit makes it so easy to modify +uncommitted changes, it also makes it easy to shoot yourself in the +foot in the process. For that reason Magit provides three global +modes that save *tracked* files to work-in-progress references after or +before certain actions. See [[*Wip Modes]]. + +These modes are not enabled by default because of performance +concerns. Instead a lot of potentially destructive commands require +confirmation every time they are used. In many cases this can be +disabled by adding a symbol to ~magit-no-confirm~ (see [[*Completion and +Confirmation]]). If you enable the various wip modes then you should +add ~safe-with-wip~ to this list. + +Similarly it isn't necessary to require confirmation before moving a +file to the system trash - if you trashed a file by mistake then you +can recover it from there. Option ~magit-delete-by-moving-to-trash~ +controls whether the system trash is used, which is the case by default. +Nevertheless, ~trash~ isn't a member of ~magit-no-confirm~ - you +might want to change that. + +By default buffers visiting files are automatically reverted when the +visited file changes on disk. This isn't as risky as it might seem, +but to make an informed decision you should see [[*Risk of Reverting +Automatically]]. + +*** Performance + +After Magit has run ~git~ for side-effects, it also refreshes the +current Magit buffer and the respective status buffer. This is +necessary because otherwise outdated information might be displayed +without the user noticing. Magit buffers are updated by recreating +their content from scratch, which makes updating simpler and less +error-prone, but also more costly. Keeping it simple and just +re-creating everything from scratch is an old design decision and +departing from that will require major refactoring. + +Meanwhile you can tell Magit to only automatically refresh the current +Magit buffer, but not the status buffer. If you do that, then the +status buffer is only refreshed automatically if it is the +current buffer. + +#+begin_src emacs-lisp + (setq magit-refresh-status-buffer nil) +#+end_src + +You should also check whether any third-party packages have added +anything to ~magit-refresh-buffer-hook~, ~magit-pre-refresh-hook~, and +~magit-post-refresh-hook~. If so, then check whether those additions +impact performance significantly. + +Magit can be told to refresh buffers verbosely using ~M-x +magit-toggle-verbose-refresh~. Enabling this helps figuring out which +sections are bottlenecks. Each line printed to the ~*Messages*~ buffer +contains a section name, the number of seconds it took to show this +section, and from 0 to 2 exclamation marks: the more exclamation marks +the slower the section is. + +Magit also reverts buffers for visited files located inside the +current repository when the visited file changes on disk. That is +implemented on top of ~auto-revert-mode~ from the built-in library +~autorevert~. To figure out whether that impacts performance, check +whether performance is significantly worse, when many buffers exist +and/or when some buffers visit files using TRAMP. If so, then this +should help. + +#+begin_src emacs-lisp + (setq auto-revert-buffer-list-filter + 'magit-auto-revert-repository-buffer-p) +#+end_src + +For alternative approaches see [[*Automatic Reverting of File-Visiting +Buffers]]. + +If you have enabled any features that are disabled by default, then +you should check whether they impact performance significantly. It's +likely that they were not enabled by default because it is known that +they reduce performance at least in large repositories. + +If performance is only slow inside certain unusually large +repositories, then you might want to disable certain features on a +per-repository or per-repository-class basis only. See +[[*Per-Repository Configuration]]. For example it takes a long time to +determine the next and current tag in repository with exceptional +numbers of tags. It would therefore be a good idea to disable +~magit-insert-tags-headers~, as explained at the mentioned node. + +**** Log Performance +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +When showing logs, Magit limits the number of commits initially shown +in the hope that this avoids unnecessary work. When ~--graph~ is +used, then this unfortunately does not have the desired effect for +large histories. Junio, Git's maintainer, said on the Git mailing +list (https://www.spinics.net/lists/git/msg232230.html): "~--graph~ wants +to compute the whole history and the max-count only affects the output +phase after ~--graph~ does its computation". + +In other words, it's not that Git is slow at outputting the +differences, or that Magit is slow at parsing the output - the problem +is that Git first goes outside and has a smoke. + +We actually work around this issue by limiting the number of commits +not only by using ~-~ but by also using a range. But unfortunately +that's not always possible. + +When more than a few thousand commits are shown, then the use of +~--graph~ can slow things down. + +Using ~--color --graph~ is even slower. Magit uses code that is part of +Emacs to turn control characters into faces. That code is pretty slow +and this is quite noticeable when showing a log with many branches and +merges. For that reason ~--color~ is not enabled by default anymore. +Consider leaving it at that. + +**** Diff Performance +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +If diffs are slow, then consider turning off some optional diff +features by setting all or some of the following variables to ~nil~: +~magit-diff-highlight-indentation~, ~magit-diff-highlight-trailing~, +~magit-diff-paint-whitespace~, ~magit-diff-highlight-hunk-body~, and +~magit-diff-refine-hunk~. + +When showing a commit instead of some arbitrary diff, then some +additional information is displayed. Calculating this information +can be quite expensive given certain circumstances. If looking at +a commit using ~magit-revision-mode~ takes considerably more time than +looking at the same commit in ~magit-diff-mode~, then consider setting +~magit-revision-insert-related-refs~ to ~nil~. + +When you are often confronted with diffs that contain deleted files, +then you might want to enable the ~--irreversible-delete~ argument. If +you do that then diffs still show that a file was deleted but without +also showing the complete deleted content of the file. This argument +is not available by default, see [[info:transient#Enabling and Disabling +Suffixes]]. Once you have done that you should enable it and save that +setting, see [[info:transient#Saving Values]]. You should do this in both +the diff (~d~) and the diff refresh (~D~) transient popups. + +**** Refs Buffer Performance +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +When refreshing the "references buffer" is slow, then that's usually +because several hundred refs are being displayed. The best way to +address that is to display fewer refs, obviously. + +If you are not, or only mildly, interested in seeing the list of tags, +then start by not displaying them: + +#+begin_src emacs-lisp + (remove-hook 'magit-refs-sections-hook 'magit-insert-tags) +#+end_src + +Then you should also make sure that the listed remote branches +actually all exist. You can do so by pruning branches which no longer +exist using ~f-pa~. + +**** Committing Performance +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +When you initiate a commit, then Magit by default automatically shows +a diff of the changes you are about to commit. For large commits this +can take a long time, which is especially distracting when you are +committing large amounts of generated data which you don't actually +intend to inspect before committing. This behavior can be turned off +using: + +#+begin_src emacs-lisp + (remove-hook 'server-switch-hook 'magit-commit-diff) + (remove-hook 'with-editor-filter-visit-hook 'magit-commit-diff) +#+end_src + +Then you can type ~C-c C-d~ to show the diff when you actually want to +see it, but only then. Alternatively you can leave the hook alone and +just type ~C-g~ in those cases when it takes too long to generate the +diff. If you do that, then you will end up with a broken diff buffer, +but doing it this way has the advantage that you usually get to see +the diff, which is useful because it increases the odds that you spot +potential issues. + +**** Microsoft Windows Performance + +In order to update the status buffer, ~git~ has to be run a few dozen +times. That is problematic on Microsoft Windows, because that +operating system is exceptionally slow at starting processes. Sadly +this is an issue that can only be fixed by Microsoft itself, and they +don't appear to be particularly interested in doing so. + +Beside the subprocess issue, there are also other Windows-specific +performance issues. Some of these have workarounds. The +maintainers of "Git for Windows" try to improve performance on Windows. +Always use the latest release in order to benefit from the latest +performance tweaks. Magit too tries to work around some +Windows-specific issues. + +According to some sources, setting the following Git variables can also +help. + +#+begin_src shell-script + git config --global core.preloadindex true # default since v2.1 + git config --global core.fscache true # default since v2.8 + git config --global gc.auto 256 +#+end_src + +You should also check whether an anti-virus program is affecting +performance. + +**** MacOS Performance + +Before Emacs 26.1 child processes were created using ~fork~ on macOS. +That needlessly copied GUI resources, which is expensive. The result +was that forking took about 30 times as long on Darwin than on Linux, +and because Magit starts many ~git~ processes that made quite a +difference. + +So make sure that you are using at least Emacs 26.1, in which case the +faster ~vfork~ will be used. (The creation of child processes still +takes about twice as long on Darwin compared to Linux.) See [fn:mac1] +for more information. + +Additionally, ~git~ installed from a package manager like ~brew~ or ~nix~ +seems to be slower than the native executable. Profile the ~git~ +executable you're running against the one at ~/usr/bin/git~, and if +you notice a notable difference try using the latter as +~magit-git-executable~. + +[fn:mac1] https://lists.gnu.org/archive/html/bug-gnu-emacs/2017-04/msg00201.html + +*** Global Bindings + +- User Option: magit-define-global-key-bindings :: + + This option controls which set of Magit key bindings, if any, may + be added to the global keymap, even before Magit is first used in + the current Emacs session. + + - If the value is ~nil~, no bindings are added. + + - If ~default~, maybe add: + + | ~C-x g~ | ~magit-status~ | + | ~C-x M-g~ | ~magit-dispatch~ | + | ~C-c M-g~ | ~magit-file-dispatch~ | + + - If ~recommended~, maybe add: + + | ~C-x g~ | ~magit-status~ | + | ~C-c g~ | ~magit-dispatch~ | + | ~C-c f~ | ~magit-file-dispatch~ | + + These bindings are strongly recommended, but we cannot use + them by default, because the ~C-c ~ namespace is + strictly reserved for bindings added by the user (see + [[info:elisp#Key Binding Conventions]]). + + The bindings in the chosen set may be added when + ~after-init-hook~ is run. Each binding is added if, and only + if, at that time no other key is bound to the same command, + and no other command is bound to the same key. In other words + we try to avoid adding bindings that are unnecessary, as well + as bindings that conflict with other bindings. + + Adding these bindings is delayed until ~after-init-hook~ is + run to allow users to set the variable anywhere in their init + file (without having to make sure to do so before ~magit~ is + loaded or autoloaded) and to increase the likelihood that all + the potentially conflicting user bindings have already been + added. + + To set this variable use either ~setq~ or the Custom interface. + Do not use the function ~customize-set-variable~ because doing + that would cause Magit to be loaded immediately, when that form + is evaluated (this differs from ~custom-set-variables~, which + doesn't load the libraries that define the customized variables). + + Setting this variable has no effect if ~after-init-hook~ has + already been run. + +* Plumbing + +The following sections describe how to use several of Magit's core +abstractions to extend Magit itself or implement a separate extension. + +A few of the low-level features used by Magit have been factored out +into separate libraries/packages, so that they can be used by other +packages, without having to depend on Magit. See [[info:with-editor]] for +information about ~with-editor~. ~transient~ doesn't have a manual yet. + +If you are trying to find an unused key that you can bind to a +command provided by your own Magit extension, then checkout +https://github.com/magit/magit/wiki/Plugin-Dispatch-Key-Registry. + +** Calling Git + +Magit provides many specialized functions for calling Git. All of +these functions are defined in either ~magit-git.el~ or ~magit-process.el~ +and have one of the prefixes ~magit-run-~, ~magit-call-~, ~magit-start-~, +or ~magit-git-~ (which is also used for other things). + +All of these functions accept an indefinite number of arguments, which +are strings that specify command line arguments for Git (or in some +cases an arbitrary executable). These arguments are flattened before +being passed on to the executable; so instead of strings they can also +be lists of strings and arguments that are ~nil~ are silently dropped. +Some of these functions also require a single mandatory argument +before these command line arguments. + +Roughly speaking, these functions run Git either to get some value or +for side-effects. The functions that return a value are useful to +collect the information necessary to populate a Magit buffer, while +the others are used to implement Magit commands. + +The functions in the value-only group always run synchronously, and +they never trigger a refresh. The function in the side-effect group +can be further divided into subgroups depending on whether they run +Git synchronously or asynchronously, and depending on whether they +trigger a refresh when the executable has finished. + +*** Getting a Value from Git + +These functions run Git in order to get a value, an exit +status, or output. Of course you could also use them to run Git +commands that have side-effects, but that should be avoided. + +- Function: magit-git-exit-code &rest args :: + + Executes git with ARGS and returns its exit code. + +- Function: magit-git-success &rest args :: + + Executes git with ARGS and returns ~t~ if the exit code is ~0~, ~nil~ + otherwise. + +- Function: magit-git-failure &rest args :: + + Executes git with ARGS and returns ~t~ if the exit code is ~1~, ~nil~ + otherwise. + +- Function: magit-git-true &rest args :: + + Executes git with ARGS and returns ~t~ if the first line printed by + git is the string "true", ~nil~ otherwise. + +- Function: magit-git-false &rest args :: + + Executes git with ARGS and returns ~t~ if the first line printed by + git is the string "false", ~nil~ otherwise. + +- Function: magit-git-insert &rest args :: + + Executes git with ARGS and inserts its output at point. + +- Function: magit-git-string &rest args :: + + Executes git with ARGS and returns the first line of its output. If + there is no output or if it begins with a newline character, then + this returns ~nil~. + +- Function: magit-git-lines &rest args :: + + Executes git with ARGS and returns its output as a list of lines. + Empty lines anywhere in the output are omitted. + +- Function: magit-git-items &rest args :: + + Executes git with ARGS and returns its null-separated output as a + list. Empty items anywhere in the output are omitted. + + If the value of option ~magit-git-debug~ is non-~nil~ and git exits with + a non-zero exit status, then warn about that in the echo area and + add a section containing git's standard error in the current + repository's process buffer. + +- Function: magit-process-git destination &rest args :: + + Calls Git synchronously in a separate process, returning its exit + code. DESTINATION specifies how to handle the output, like for + ~call-process~, except that file handlers are supported. Enables + Cygwin's "noglob" option during the call and ensures unix eol + conversion. + +- Function: magit-process-file process &optional infile buffer display &rest args :: + + Processes files synchronously in a separate process. Identical to + ~process-file~ but temporarily enables Cygwin's "noglob" option during + the call and ensures unix eol conversion. + +If an error occurs when using one of the above functions, then that +is usually due to a bug, i.e., using an argument which is not +actually supported. Such errors are usually not reported, but when +they occur we need to be able to debug them. + +- User Option: magit-git-debug :: + + Whether to report errors that occur when using ~magit-git-insert~, + ~magit-git-string~, ~magit-git-lines~, or ~magit-git-items~. This does + not actually raise an error. Instead a message is shown in the echo + area, and git's standard error is insert into a new section in the + current repository's process buffer. + +- Function: magit-git-str &rest args :: + + This is a variant of ~magit-git-string~ that ignores the option + ~magit-git-debug~. It is mainly intended to be used while handling + errors in functions that do respect that option. Using such a + function while handing an error could cause yet another error and + therefore lead to an infinite recursion. You probably won't ever + need to use this function. + +*** Calling Git for Effect + +These functions are used to run git to produce some effect. Most +Magit commands that actually run git do so by using such a function. + +Because we do not need to consume git's output when using these +functions, their output is instead logged into a per-repository +buffer, which can be shown using ~$~ from a Magit buffer or ~M-x +magit-process~ elsewhere. + +These functions can have an effect in two distinct ways. Firstly, +running git may change something, i.e., create or push a new commit. +Secondly, that change may require that Magit buffers are refreshed to +reflect the changed state of the repository. But refreshing isn't +always desirable, so only some of these functions do perform such a +refresh after git has returned. + +Sometimes it is useful to run git asynchronously. For example, when +the user has just initiated a push, then there is no reason to make +her wait until that has completed. In other cases it makes sense to +wait for git to complete before letting the user do something else. +For example after staging a change it is useful to wait until after +the refresh because that also automatically moves to the next change. + +The synchronous functions return the exit code, while the asynchronous +functions return the process object. + +- Function: magit-call-git &rest args :: + + Calls git synchronously with ARGS. + +- Function: magit-call-process program &rest args :: + + Calls PROGRAM synchronously with ARGS. + +- Function: magit-run-git &rest args :: + + Calls git synchronously with ARGS and then refreshes. + +- Function: magit-run-git-with-input &rest args :: + + Calls git synchronously with ARGS and sends it the content of the + current buffer on standard input. + + If the current buffer's ~default-directory~ is on a remote + filesystem, this function actually runs git asynchronously. But + then it waits for the process to return, so the function itself is + synchronous. + +- Function: magit-git &rest args :: + + Calls git synchronously with ARGS for side-effects only. This + function does not refresh the buffer. + +- Function: magit-git-wash washer &rest args :: + + Execute Git with ARGS, inserting washed output at point. Actually + first insert the raw output at point. If there is no output call + ~magit-cancel-section~. Otherwise temporarily narrow the buffer to + the inserted text, move to its beginning, and then call function + WASHER with ARGS as its sole argument. + +And now for the asynchronous variants. + +- Function: magit-run-git-async &rest args :: + + Start Git, prepare for refresh, and return the process object. + ARGS is flattened and then used as arguments to Git. + + Display the command line arguments in the echo area. + + After Git returns some buffers are refreshed: the buffer that was + current when this function was called (if it is a Magit buffer and + still alive), as well as the respective Magit status buffer. + Unmodified buffers visiting files that are tracked in the current + repository are reverted if ~magit-revert-buffers~ is non-~nil~. + +- Function: magit-run-git-with-editor &rest args :: + + Export GIT_EDITOR and start Git. Also prepare for refresh and + return the process object. ARGS is flattened and then used as + arguments to Git. + + Display the command line arguments in the echo area. + + After Git returns some buffers are refreshed: the buffer that was + current when this function was called (if it is a Magit buffer and + still alive), as well as the respective Magit status buffer. + +- Function: magit-start-git input &rest args :: + + Start Git, prepare for refresh, and return the process object. + + If INPUT is non-~nil~, it has to be a buffer or the name of an + existing buffer. The buffer content becomes the processes + standard input. + + Option ~magit-git-executable~ specifies the Git executable and option + ~magit-git-global-arguments~ specifies constant arguments. The + remaining arguments ARGS specify arguments to Git. They are + flattened before use. + + After Git returns, some buffers are refreshed: the buffer that was + current when this function was called (if it is a Magit buffer and + still alive), as well as the respective Magit status buffer. + Unmodified buffers visiting files that are tracked in the current + repository are reverted if ~magit-revert-buffers~ is non-~nil~. + +- Function: magit-start-process &rest args :: + + Start PROGRAM, prepare for refresh, and return the process object. + + If optional argument INPUT is non-~nil~, it has to be a buffer or + the name of an existing buffer. The buffer content becomes the + processes standard input. + + The process is started using ~start-file-process~ and then setup to + use the sentinel ~magit-process-sentinel~ and the filter + ~magit-process-filter~. Information required by these functions is + stored in the process object. When this function returns the + process has not started to run yet so it is possible to override the + sentinel and filter. + + After the process returns, ~magit-process-sentinel~ refreshes the + buffer that was current when ~magit-start-process~ was called (if it + is a Magit buffer and still alive), as well as the respective Magit + status buffer. Unmodified buffers visiting files that are tracked + in the current repository are reverted if ~magit-revert-buffers~ is + non-~nil~. + +- Variable: magit-this-process :: + + The child process which is about to start. This can be used to + change the filter and sentinel. + +- Variable: magit-process-raise-error :: + + When this is non-~nil~, then ~magit-process-sentinel~ raises an error if + git exits with a non-zero exit status. For debugging purposes. + +** Section Plumbing +*** Creating Sections + +- Macro: magit-insert-section &rest args :: + + Insert a section at point. + + TYPE is the section type, a symbol. Many commands that act on the + current section behave differently depending on that type. Also if + a variable ~magit-TYPE-section-map~ exists, then use that as the + text-property ~keymap~ of all text belonging to the section (but this + may be overwritten in subsections). TYPE can also have the form + ~(eval FORM)~ in which case FORM is evaluated at runtime. + + Optional VALUE is the value of the section, usually a string that is + required when acting on the section. + + When optional HIDE is non-~nil~ collapse the section body by default, + i.e., when first creating the section, but not when refreshing the + buffer. Otherwise, expand it by default. This can be overwritten using + ~magit-section-set-visibility-hook~. When a section is recreated + during a refresh, then the visibility of predecessor is inherited + and HIDE is ignored (but the hook is still honored). + + BODY is any number of forms that actually insert the section's + heading and body. Optional NAME, if specified, has to be a symbol, + which is then bound to the struct of the section being inserted. + + Before BODY is evaluated the ~start~ of the section object is set to + the value of ~point~ and after BODY was evaluated its ~end~ is set to + the new value of ~point~; BODY is responsible for moving ~point~ + forward. + + If it turns out inside BODY that the section is empty, then + ~magit-cancel-section~ can be used to abort and remove all traces of + the partially inserted section. This can happen when creating a + section by washing Git's output and Git didn't actually output + anything this time around. + +- Function: magit-insert-heading &rest args :: + + Insert the heading for the section currently being inserted. + + This function should only be used inside ~magit-insert-section~. + + When called without any arguments, then just set the ~content~ slot of + the object representing the section being inserted to a marker at + ~point~. The section should only contain a single line when this + function is used like this. + + When called with arguments ARGS, which have to be strings, then + insert those strings at point. The section should not contain any + text before this happens and afterwards it should again only contain + a single line. If the ~face~ property is set anywhere inside any of + these strings, then insert all of them unchanged. Otherwise use the + ~magit-section-heading~ face for all inserted text. + + The ~content~ property of the section struct is the end of the heading + (which lasts from ~start~ to ~content~) and the beginning of the body + (which lasts from ~content~ to ~end~). If the value of ~content~ is ~nil~, + then the section has no heading and its body cannot be collapsed. + If a section does have a heading then its height must be exactly one + line, including a trailing newline character. This isn't enforced; + you are responsible for getting it right. The only exception is + that this function does insert a newline character if necessary. + +- Function: magit-cancel-section :: + + Cancel the section currently being inserted. This exits the + innermost call to ~magit-insert-section~ and removes all traces of + what has already happened inside that call. + +- Function: magit-define-section-jumper sym title &optional value :: + + Define an interactive function to go to section SYM. TITLE is the + displayed title of the section. + +*** Section Selection + +- Function: magit-current-section :: + + Return the section at point. + +- Function: magit-region-sections &optional condition multiple :: + + Return a list of the selected sections. + + When the region is active and constitutes a valid section + selection, then return a list of all selected sections. This is + the case when the region begins in the heading of a section and + ends in the heading of the same section or in that of a sibling + section. If optional MULTIPLE is non-~nil~, then the region cannot + begin and end in the same section. + + When the selection is not valid, then return ~nil~. In this case, + most commands that can act on the selected sections will instead + act on the section at point. + + When the region looks like it would in any other buffer then + the selection is invalid. When the selection is valid then the + region uses the ~magit-section-highlight~ face. This does not + apply to diffs where things get a bit more complicated, but even + here if the region looks like it usually does, then that's not + a valid selection as far as this function is concerned. + + If optional CONDITION is non-~nil~, then the selection not only + has to be valid; all selected sections additionally have to match + CONDITION, or ~nil~ is returned. See ~magit-section-match~ for the + forms CONDITION can take. + +- Function: magit-region-values &optional condition multiple :: + + Return a list of the values of the selected sections. + + Return the values that themselves would be returned by + ~magit-region-sections~ (which see). + +*** Matching Sections + +- Key: M-x magit-describe-section-briefly :: + + Show information about the section at point. This command is + intended for debugging purposes. + +- Function: magit-section-ident section :: + + Return an unique identifier for SECTION. The return value has the + form ~((TYPE . VALUE)...)~. + +- Function: magit-get-section ident &optional root :: + + Return the section identified by IDENT. IDENT has to be a list as + returned by ~magit-section-ident~. + +- Function: magit-section-match condition &optional section :: + + Return ~t~ if SECTION matches CONDITION. + SECTION defaults to the section at point. If SECTION is not + specified and there also is no section at point, then return + ~nil~. + + CONDITION can take the following forms: + - ~(CONDITION...)~ + + matches if any of the CONDITIONs matches. + + - ~[CLASS...]~ + + matches if the section's class is the same + as the first CLASS or a subclass of that; + the section's parent class matches the + second CLASS; and so on. + + - ~[* CLASS...]~ + + matches sections that match ~[CLASS...]~ and + also recursively all their child sections. + + - ~CLASS~ + + matches if the section's class is the same + as CLASS or a subclass of that; regardless + of the classes of the parent sections. + + Each CLASS should be a class symbol, identifying a class that + derives from ~magit-section~. For backward compatibility CLASS + can also be a "type symbol". A section matches such a symbol + if the value of its ~type~ slot is ~eq~. If a type symbol has + an entry in ~magit--section-type-alist~, then a section also + matches that type if its class is a subclass of the class that + corresponds to the type as per that alist. + + Note that it is not necessary to specify the complete section + lineage as printed by ~magit-describe-section-briefly~, unless + of course you want to be that precise. + +- Function: magit-section-value-if condition &optional section :: + + If the section at point matches CONDITION, then return its value. + + If optional SECTION is non-~nil~ then test whether that matches + instead. If there is no section at point and SECTION is ~nil~, + then return ~nil~. If the section does not match, then return + ~nil~. + + See ~magit-section-match~ for the forms CONDITION can take. + +- Function: magit-section-case &rest clauses :: + + Choose among clauses on the type of the section at point. + + Each clause looks like (CONDITION BODY...). The type of the + section is compared against each CONDITION; the BODY forms of the + first match are evaluated sequentially and the value of the last + form is returned. Inside BODY the symbol ~it~ is bound to the + section at point. If no clause succeeds or if there is no + section at point return ~nil~. + + See ~magit-section-match~ for the forms CONDITION can take. + Additionally a CONDITION of ~t~ is allowed in the final clause and + matches if no other CONDITION match, even if there is no section at + point. + +- Variable: magit-root-section :: + + The root section in the current buffer. All other sections are + descendants of this section. The value of this variable is set by + ~magit-insert-section~ and you should never modify it. + +For diff related sections a few additional tools exist. + +- Function: magit-diff-type &optional section :: + + Return the diff type of SECTION. + + The returned type is one of the symbols ~staged~, ~unstaged~, ~committed~, + or ~undefined~. This type serves a similar purpose as the general + type common to all sections (which is stored in the ~type~ slot of the + corresponding ~magit-section~ struct) but takes additional information + into account. When the SECTION isn't related to diffs and the + buffer containing it also isn't a diff-only buffer, then return ~nil~. + + Currently the type can also be one of ~tracked~ and ~untracked~, but + these values are not handled explicitly in every place they should + be. A possible fix could be to just return ~nil~ here. + + The section has to be a ~diff~ or ~hunk~ section, or a section whose + children are of type ~diff~. If optional SECTION is ~nil~, return the + diff type for the current section. In buffers whose major mode is + ~magit-diff-mode~ SECTION is ignored and the type is determined using + other means. In ~magit-revision-mode~ buffers the type is always + ~committed~. + +- Function: magit-diff-scope &optional section strict :: + + Return the diff scope of SECTION or the selected section(s). + + A diff's "scope" describes what part of a diff is selected, it is a + symbol, one of ~region~, ~hunk~, ~hunks~, ~file~, ~files~, or ~list~. Do not + confuse this with the diff "type", as returned by ~magit-diff-type~. + + If optional SECTION is non-~nil~, then return the scope of that, + ignoring the sections selected by the region. Otherwise return the + scope of the current section, or if the region is active and selects + a valid group of diff related sections, the type of these sections, + i.e., ~hunks~ or ~files~. If SECTION (or if the current section that + is ~nil~) is a ~hunk~ section and the region starts and ends inside + the body of a that section, then the type is ~region~. + + If optional STRICT is non-~nil~ then return ~nil~ if the diff type of + the section at point is ~untracked~ or the section at point is not + actually a ~diff~ but a ~diffstat~ section. + +** Refreshing Buffers + +All commands that create a new Magit buffer or change what is being +displayed in an existing buffer do so by calling ~magit-mode-setup~. +Among other things, that function sets the buffer local values of +~default-directory~ (to the top-level of the repository), +~magit-refresh-function~, and ~magit-refresh-args~. + +Buffers are refreshed by calling the function that is the local value +of ~magit-refresh-function~ (a function named ~magit-*-refresh-buffer~, +where ~*~ may be something like ~diff~) with the value of +~magit-refresh-args~ as arguments. + +- Macro: magit-mode-setup buffer switch-func mode refresh-func &optional refresh-args :: + + This function displays and selects BUFFER, turns on MODE, and + refreshes a first time. + + This function displays and optionally selects BUFFER by calling + ~magit-mode-display-buffer~ with BUFFER, MODE and SWITCH-FUNC as + arguments. Then it sets the local value of ~magit-refresh-function~ + to REFRESH-FUNC and that of ~magit-refresh-args~ to REFRESH-ARGS. + Finally it creates the buffer content by calling REFRESH-FUNC with + REFRESH-ARGS as arguments. + + All arguments are evaluated before switching to BUFFER. + +- Function: magit-mode-display-buffer buffer mode &optional switch-function :: + + This function display BUFFER in some window and select it. BUFFER + may be a buffer or a string, the name of a buffer. The buffer is + returned. + + Unless BUFFER is already displayed in the selected frame, store the + previous window configuration as a buffer local value, so that it + can later be restored by ~magit-mode-bury-buffer~. + + The buffer is displayed and selected using SWITCH-FUNCTION. If that + is ~nil~ then ~pop-to-buffer~ is used if the current buffer's major mode + derives from ~magit-mode~. Otherwise ~switch-to-buffer~ is used. + +- Variable: magit-refresh-function :: + + The value of this buffer-local variable is the function used to + refresh the current buffer. It is called with ~magit-refresh-args~ as + arguments. + +- Variable: magit-refresh-args :: + + The list of arguments used by ~magit-refresh-function~ to refresh the + current buffer. ~magit-refresh-function~ is called with these + arguments. + + The value is usually set using ~magit-mode-setup~, but in some cases + it's also useful to provide commands that can change the value. For + example, the ~magit-diff-refresh~ transient can be used to change any + of the arguments used to display the diff, without having to specify + again which differences should be shown, but ~magit-diff-more-context~, + ~magit-diff-less-context~ and ~magit-diff-default-context~ change just + the ~-U~ argument. In both case this is done by changing the value + of this variable and then calling this ~magit-refresh-function~. + +** Conventions + +Also see [[*Completion and Confirmation]]. + +*** Theming Faces + +The default theme uses blue for local branches, green for remote +branches, and goldenrod (brownish yellow) for tags. When creating a +new theme, you should probably follow that example. If your theme +already uses other colors, then stick to that. + +In older releases these reference faces used to have a background +color and a box around them. The basic default faces no longer do so, +to make Magit buffers much less noisy, and you should follow that +example at least with regards to boxes. (Boxes were used in the past +to work around a conflict between the highlighting overlay and text +property backgrounds. That's no longer necessary because highlighting no +longer causes other background colors to disappear.) Alternatively +you can keep the background color and/or box, but then have to take +special care to adjust ~magit-branch-current~ accordingly. By default +it looks mostly like ~magit-branch-local~, but with a box (by default +the former is the only face that uses a box, exactly so that it sticks +out). If the former also uses a box, then you have to make sure that +it differs in some other way from the latter. + +The most difficult faces to theme are those related to diffs, +headings, highlighting, and the region. There are faces that fall +into all four groups - expect to spend some time getting this right. + +The ~region~ face in the default theme, in both the light and dark +variants, as well as in many other themes, distributed with Emacs or +by third-parties, is very ugly. It is common to use a background +color that really sticks out, which is ugly but if that were the only +problem then it would be acceptable. Unfortunately many themes also +set the foreground color, which ensures that all text within the +region is readable. Without doing that there might be cases where +some foreground color is too close to the region background color to +still be readable. But it also means that text within the region +loses all syntax highlighting. + +I consider the work that went into getting the ~region~ face right to be +a good indicator for the general quality of a theme. My +recommendation for the ~region~ face is this: use a background color +slightly different from the background color of the ~default~ face, and +do not set the foreground color at all. So for a light theme you +might use a light (possibly tinted) gray as the background color of +~default~ and a somewhat darker gray for the background of ~region~. +That should usually be enough to not collide with the foreground color +of any other face. But if some other faces also set a light gray as +background color, then you should also make sure it doesn't collide +with those (in some cases it might be acceptable though). + +Magit only uses the ~region~ face when the region is "invalid" by its +own definition. In a Magit buffer the region is used to either select +multiple sibling sections, so that commands which support it act on +all of these sections instead of just the current section, or to +select lines within a single hunk section. In all other cases, the +section is considered invalid and Magit won't act on it. But such +invalid sections happen, either because the user has not moved point +enough yet to make it valid or because she wants to use a non-magit +command to act on the region, e.g., ~kill-region~. + +So using the regular ~region~ face for invalid sections is a feature. It +tells the user that Magit won't be able to act on it. It's acceptable +if that face looks a bit odd and even (but less so) if it collides +with the background colors of section headings and other things that +have a background color. + +Magit highlights the current section. If a section has subsections, +then all of them are highlighted. This is done using faces that have +"highlight" in their names. For most sections, ~magit-section-highlight~ +is used for both the body and the heading. Like the ~region~ face, it +should only set the background color to something similar to that of +~default~. The highlight background color must be different from both +the ~region~ background color and the ~default~ background color. + +For diff related sections Magit uses various faces to +highlight different parts of the selected section(s). Note that hunk +headings, unlike all other section headings, by default have a +background color, because it is useful to have very visible separators +between hunks. That face ~magit-diff-hunk-heading~, should be different +from both ~magit-diff-hunk-heading-highlight~ and +~magit-section-highlight~, as well as from ~magit-diff-context~ and +~magit-diff-context-highlight~. By default we do that by changing the +foreground color. Changing the background color would lead to +complications, and there are already enough we cannot get around. +(Also note that it is generally a good idea for section headings to +always be bold, but only for sections that have subsections). + +When there is a valid region selecting diff-related sibling sections, +i.e., multiple files or hunks, then the bodies of all these sections +use the respective highlight faces, but additionally the headings +instead use one of the faces ~magit-diff-file-heading-selection~ or +~magit-diff-hunk-heading-selection~. These faces have to be different +from the regular highlight variants to provide explicit visual +indication that the region is active. + +When theming diff related faces, start by setting the option +~magit-diff-refine-hunk~ to ~all~. You might personally prefer to only +refine the current hunk or not use hunk refinement at all, but some of +the users of your theme want all hunks to be refined, so you have to +cater to that. + +(Also turn on ~magit-diff-highlight-indentation~, +~magit-diff-highlight-trailing~, and ~magit-diff-paint-whitespace~; and +insert some whitespace errors into the code you use for testing.) + +For added lines you have to adjust three faces: +~magit-diff-added~, ~magit-diff-added-highlight~, and +~diff-refined-added~. Make sure that the latter works well with both +of the former, as well as ~smerge-other~ and ~diff-added~. Then do the +same for the removed lines, context lines, lines added by us, and +lines added by them. Also make sure the respective added, removed, +and context faces use approximately the same saturation for both the +highlighted and unhighlighted variants. Also make sure the file and +diff headings work nicely with context lines (e.g., make them look +different). Line faces should set both the foreground and the +background color. For example, for added lines use two different +greens. + +It's best if the foreground color of both the highlighted and the +unhighlighted variants are the same, so you will need to have to find +a color that works well on the highlight and unhighlighted background, +the refine background, and the highlight context background. When +there is an hunk internal region, then the added- and removed-lines +background color is used only within that region. Outside the region +the highlighted context background color is used. This makes it +easier to see what is being staged. With an hunk internal region the +hunk heading is shown using ~magit-diff-hunk-heading-selection~, and so +are the thin lines that are added around the lines that fall within +the region. The background color of that has to be distinct enough +from the various other involved background colors. + +Nobody said this would be easy. If your theme restricts itself to a +certain set of colors, then you should make an exception here. +Otherwise it would be impossible to make the diffs look good in each +and every variation. Actually you might want to just stick to the +default definitions for these faces. You have been warned. Also +please note that if you do not get this right, this will in some cases +look to users like bugs in Magit - so please do it right or not at +all. + +* FAQ +:PROPERTIES: +:APPENDIX: t +:END: + +The next two nodes lists frequently asked questions. For a list of +frequently *and recently* asked questions, i.e., questions that haven't +made it into the manual yet, see +https://github.com/magit/magit/wiki/FAQ. + +Please also see [[*Debugging Tools]]. + +** FAQ - How to ...? +*** How to pronounce Magit? + +Either ~mu[m's] git~ or ~magi{c => t}~ is fine. + +The slogan is "It's Magit! The magical Git client", so it makes sense +to pronounce Magit like magic, while taking into account that C and T +do not sound the same. + +The German "Magie" is not pronounced the same as the English "magic", +so if you speak German, then you can use the above rationale to justify +using the former pronunciation; ~Mag{ie => it}~. + +You can also choose to use the former pronunciation just because you +like it better. + +Also see https://magit.vc/assets/videos/magic.mp4. +Also see https://emacs.stackexchange.com/questions/13696. + +*** How to show git's output? + +To show the output of recently run git commands, press ~$~ (or, if that +isn't available, use ~M-x magit-process-buffer~). This shows a buffer +containing a section per git invocation; as always press ~TAB~ to expand +or collapse them. + +By default, git's output is only inserted into the process buffer if +it is run for side-effects. When the output is consumed in some way, +also inserting it into the process buffer would be too expensive. +For debugging purposes, it's possible to do so anyway, using ~M-x +magit-toggle-git-debug~. + +*** How to install the gitman info manual? + +Git's manpages can be exported as an info manual called ~gitman~. +Magit's own info manual links to nodes in that manual instead of the +actual manpages, simply because Info doesn't support linking to +manpages. + +Unfortunately some distributions do not install the ~gitman~ manual by +default and you would have to install a separate documentation package +to get it. + +Magit patches info, adding the ability to visit links to the ~gitman~ +info manual, by instead viewing the respective manpage. If you prefer +that approach, then set the value of ~magit-view-git-manual-method~ to +one of the supported Emacs packages ~man~ or ~woman~, e.g.: + +#+begin_src emacs-lisp + (setq magit-view-git-manual-method 'man) +#+end_src + +*** How to show diffs for gpg-encrypted files? + +Git supports showing diffs for encrypted files, but has to be told to +do so. Since Magit just uses Git to get the diffs, configuring Git +also affects the diffs displayed inside Magit. + +#+begin_src shell-script + git config --global diff.gpg.textconv "gpg --no-tty --decrypt" + echo "*.gpg filter=gpg diff=gpg" > .gitattributes +#+end_src + +*** How does branching and pushing work? + +Please see [[*Branching]] and https://emacsair.me/2016/01/18/magit-2.4 + +*** Should I disable VC? + +If you don't use VC (the built-in version control interface) then +you might be tempted to disable it, not least because we used to +recommend that you do that. + +We no longer recommend that you disable VC. Doing so would break +useful third-party packages (such as ~diff-hl~), which depend on VC +being enabled. + +If you choose to disable VC anyway, then you can do so by changing +the value of ~vc-handled-backends~. + +** FAQ - Issues and Errors +*** Magit is slow + +See [[*Performance]] and [[*I changed several thousand files at once and +now Magit is unusable]]. + +*** I changed several thousand files at once and now Magit is unusable + +Magit is currently not expected to work well under such conditions. +It sure would be nice if it did. Reaching satisfactory performance +under such conditions will require some heavy refactoring. This is no +small task but I hope to eventually find the time to make it happen. + +But for now we recommend you use the command line to complete this one +commit. Also see [[*Performance]]. + +*** I am having problems committing + +That likely means that Magit is having problems finding an appropriate +~emacsclient~ executable. See [[info:with-editor#Configuring With-Editor]] +and [[info:with-editor#Debugging]]. + +*** I am using MS Windows and cannot push with Magit + +It's almost certain that Magit is only incidental to this issue. It +is much more likely that this is a configuration issue, even if you +can push on the command line. + +Detailed setup instructions can be found at +https://github.com/magit/magit/wiki/Pushing-with-Magit-from-Windows. + +*** I am using macOS and SOMETHING works in shell, but not in Magit + +This usually occurs because Emacs doesn't have the same environment +variables as your shell. Try installing and configuring +https://github.com/purcell/exec-path-from-shell. By default it +synchronizes ~$PATH~, which helps Magit find the same ~git~ as the one you +are using on the shell. + +If SOMETHING is "passphrase caching with gpg-agent for commit and/or +tag signing", then you'll also need to synchronize ~$GPG_AGENT_INFO~. + +*** Expanding a file to show the diff causes it to disappear + +This is probably caused by a customization of a ~diff.*~ Git variable. +You probably set that variable for a reason, and should therefore only +undo that setting in Magit by customizing ~magit-git-global-arguments~. + +*** Point is wrong in the ~COMMIT_EDITMSG~ buffer + +Neither Magit nor ~git-commit.el~ fiddle with point in the buffer used +to write commit messages, so something else must be doing it. + +You have probably globally enabled a mode, which restores point in +file-visiting buffers. It might be a bit surprising, but when you +write a commit message, then you are actually editing a file. + +So you have to figure out which package is doing it. ~saveplace~, +~pointback~, and ~session~ are likely candidates. These snippets might +help: + +#+begin_src emacs-lisp + (setq session-name-disable-regexp "\\(?:\\`'\\.git/[A-Z_]+\\'\\)") + + (with-eval-after-load 'pointback + (lambda () + (when (or git-commit-mode git-rebase-mode) + (pointback-mode -1)))) +#+end_src + +*** The mode-line information isn't always up-to-date + +Magit is not responsible for the version control information that is +being displayed in the mode-line and looks something like ~Git-master~. +The built-in "Version Control" package, also known as "VC", updates +that information, and can be told to do so more often: + +#+begin_src emacs-lisp + (setq auto-revert-check-vc-info t) +#+end_src + +But doing so isn't good for performance. For more (overly optimistic) +information see [[info:emacs#VC Mode Line]]. + +If you don't really care about seeing this information in the +mode-line, but just don't want to see /incorrect/ information, +then consider simply not displaying it in the mode-line: + +#+begin_src emacs-lisp + (setq-default mode-line-format + (delete '(vc-mode vc-mode) mode-line-format)) +#+end_src + +*** A branch and tag sharing the same name breaks SOMETHING + +Or more generally, ambiguous refnames break SOMETHING. + +Magit assumes that refs are named non-ambiguously across the +"refs/heads/", "refs/tags/", and "refs/remotes/" namespaces (i.e., all +the names remain unique when those prefixes are stripped). We +consider ambiguous refnames unsupported and recommend that you use a +non-ambiguous naming scheme. However, if you do work with a +repository that has ambiguous refnames, please report any issues you +encounter, so that we can investigate whether there is a simple fix. + +*** My Git hooks work on the command-line but not inside Magit + +When Magit calls ~git~ it adds a few global arguments including +~--literal-pathspecs~ and the ~git~ process started by Magit then passes +that setting on to other ~git~ process it starts itself. It does so by +setting the environment variable ~GIT_LITERAL_PATHSPECS~, not by calling +subprocesses with the ~--literal-pathspecs~ argument. You can therefore +override this setting in hook scripts using ~unset +GIT_LITERAL_PATHSPECS~. + +*** ~git-commit-mode~ isn't used when committing from the command-line + +The reason for this is that ~git-commit.el~ has not been loaded yet +and/or that the server has not been started yet. These things have +always already been taken care of when you commit from Magit because +in order to do so, Magit has to be loaded and doing that involves +loading ~git-commit~ and starting the server. + +If you want to commit from the command-line, then you have to take +care of these things yourself. Your ~init.el~ file should contain: + +#+begin_src emacs-lisp + (require 'git-commit) + (server-mode) +#+end_src + +Instead of `(require 'git-commit)` you may also use: + +#+begin_src emacs-lisp + (load "/path/to/magit-autoloads.el") +#+end_src + +You might want to do that because loading ~git-commit~ causes large +parts of Magit to be loaded. + +There are also some variations of ~(server-mode)~ that you might want to +try. Personally I use: + +#+begin_src emacs-lisp + (use-package server + :config (or (server-running-p) (server-mode))) +#+end_src + +Now you can use: + +#+begin_src shell-script + $ emacs& + $ EDITOR=emacsclient git commit +#+end_src + +However you cannot use: + +#+begin_src shell-script + $ killall emacs + $ EDITOR="emacsclient --alternate-editor emacs" git commit +#+end_src + +This will actually end up using ~emacs~, not ~emacsclient~. If you do +this, then you can still edit the commit message but ~git-commit-mode~ +won't be used and you have to exit ~emacs~ to finish the process. + +Tautology ahead. If you want to be able to use ~emacsclient~ to connect +to a running ~emacs~ instance, even though no ~emacs~ instance is running, +then you cannot use ~emacsclient~ directly. + +Instead you have to create a script that does something like this: + +Try to use ~emacsclient~ (without using ~--alternate-editor~). If that +succeeds, do nothing else. Otherwise start ~emacs &~ (and ~init.el~ must +call ~server-start~) and try to use ~emacsclient~ again. + +*** Point ends up inside invisible text when jumping to a file-visiting buffer + +This can happen when you type ~RET~ on a hunk to visit the respective +file at the respective position. One solution to this problem is to +use ~global-reveal-mode~. It makes sure that text around point is +always visible. If that is too drastic for your taste, then you may +instead use ~magit-diff-visit-file-hook~ to reveal the text, possibly +using ~reveal-post-command~ or for Org buffers ~org-reveal~. + +*** I am no longer able to save popup defaults + +Magit used to use Magit-Popup to implement the transient popup menus. +Now it used Transient instead, which is Magit-Popup's successor. + +In the older Magit-Popup menus, it was possible to save user settings +(e.g., setting the gpg signing key for commits) by using ~C-c C-c~ in +the popup buffer. This would dismiss the popup, but save the settings +as the defaults for future popups. + +When switching to Transient menus, this functionality is now available +via ~C-x C-s~ instead; the ~C-x~ prefix has other options as well when +using Transient, which will be displayed when it is typed. See +https://docs.magit.vc/transient/Saving-Values.html#Saving-Values for +more details. + +* Debugging Tools + +Magit and its dependencies provide a few debugging tools, and we +appreciate it very much if you use those tools before reporting an +issue. Please include all relevant output when reporting an +issue. + +- Key: M-x magit-version :: + + This command shows the currently used versions of Magit, Git, and + Emacs in the echo area. Non-interactively this just returns the + Magit version. + +- Key: M-x magit-emacs-Q-command :: + + This command shows a debugging shell command in the echo area and + adds it to the kill ring. Paste that command into a shell and run + it. + + This shell command starts ~emacs~ with only ~magit~ and its + dependencies loaded. Neither your configuration nor other installed + packages are loaded. This makes it easier to determine whether some + issue lays with Magit or something else. + + If you run Magit from its Git repository, then you should be able to + use ~make emacs-Q~ instead of the output of this command. + +- Key: M-x magit-toggle-git-debug :: + + This command toggles whether additional git errors are reported. + + Magit basically calls git for one of these two reasons: for + side-effects or to do something with its standard output. + + When git is run for side-effects then its output, including error + messages, go into the process buffer which is shown when using ~$~. + + When git's output is consumed in some way, then it would be too + expensive to also insert it into this buffer, but with this command + that can be enabled temporarily. In that case, if git returns with + a non-zero exit status, then at least its standard error is inserted + into this buffer. + + Also note that just because git exits with a non-zero status and + prints an error message, that usually doesn't mean that it is an + error as far as Magit is concerned, which is another reason we + usually hide these error messages. Whether some error message is + relevant in the context of some unexpected behavior has to be judged + on a case by case basis. + +- Key: M-x magit-toggle-verbose-refresh :: + + This command toggles whether Magit refreshes buffers verbosely. + Enabling this helps figuring out which sections are bottlenecks. + The additional output can be found in the ~*Messages*~ buffer. + +- Key: M-x magit-toggle-subprocess-record :: + + This command toggles whether subprocess invocations are recorded. + + When enabled, all subprocesses started by ~magit-process-file~ are + logged into the buffer specified by ~magit-process-record-buffer-name~ + using the format ~magit-process-record-entry-format~. This is for + debugging purposes. + + This is in addition to and distinct from the default logging done by + default, and additional logging enabled with ~magit-toggle-git-debug~. + +- Key: M-x magit-debug-git-executable :: + + This command displays a buffer containing information about the + available and used ~git~ executable(s), and can be useful when + investigating ~exec-path~ issues. + + Also see [[*Git Executable]]. + +- Key: M-x magit-profile-refresh-buffer :: + + This command profiles refreshing the current Magit buffer and then + displays the results. + +- Key: M-x magit-toggle-profiling :: + + This command starts profiling Magit and Forge, or if profiling is + already in progress, it instead stops that and displays the results. + +- Key: M-x with-editor-debug :: + + This command displays a buffer containing information about the + available and used ~emacsclient~ executable(s), and can be useful + when investigating why Magit (or rather ~with-editor~) cannot find + an appropriate ~emacsclient~ executable. + + Also see [[info:with-editor#Debugging]]. + +#+texinfo: @noindent +Please also see [[*FAQ]]. + +* Keystroke Index +:PROPERTIES: +:APPENDIX: t +:INDEX: ky +:COOKIE_DATA: recursive +:END: +* Function and Command Index +:PROPERTIES: +:APPENDIX: t +:INDEX: fn +:END: +* Variable Index +:PROPERTIES: +:APPENDIX: t +:INDEX: vr +:END: + +* Copying +:PROPERTIES: +:COPYING: t +:END: + +#+begin_quote +Copyright (C) 2015-{{{year}}} Jonas Bernoulli + +You can redistribute this document and/or modify it under the terms +of the GNU General Public License as published by the Free Software +Foundation, either version 3 of the License, or (at your option) any +later version. + +This document is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +General Public License for more details. +#+end_quote + +# LocalWords: ARG ARGS CONDITIONs ChangeLog DNS Dired Ediff Ediffing +# LocalWords: Elpa Emacsclient FUNC Flyspell Git Git's Gitk HOOK's +# LocalWords: IDENT Junio LocalWords Magit Magit's Magitian Magitians +# LocalWords: Melpa Propertize REF REF's RET Reflog SPC SYM Spacemacs +# LocalWords: Submodules TODO TYPEs Theming Unpulled Unpushed Unstaged +# LocalWords: Untracked WORKTREE Wip ack args async autoloads autosaving +# LocalWords: autosquash backport basename branchref builtin +# LocalWords: cdr changelog committer config customizable diff's diffstat +# LocalWords: dwim ediff ediffing editmsg emacsclient filename fixup +# LocalWords: flyspell func git's gitk gitman gitmodule gitmodules goto +# LocalWords: gpg gui ident init inserter inserters keymap keymaps +# LocalWords: logfile magit maildir manpage manpages minibuffer multi mv +# LocalWords: namespace newbase nocommit notesRef posix prev +# LocalWords: propertize rebase rebased rebasing reflog repo signoff str +# LocalWords: struct subcommand submodule submodule's submodules subprocess +# LocalWords: sym texinfo theming todo topdir un unhighlighted unpulled +# LocalWords: unpushed unstage unstaged unstages unstaging untracked url +# LocalWords: versa whitespace wip workflow worktree wtree +# LocalWords: backported macOS + +# IMPORTANT: Also update ORG_ARGS and ORG_EVAL in the Makefile. +# Local Variables: +# eval: (require 'magit-base nil t) +# eval: (require 'ol-man nil t) +# indent-tabs-mode: nil +# org-src-preserve-indentation: nil +# End: -- cgit v1.2.3