Rename Documentation/ to docs/

1 files changed, 438 insertions, 0 deletions

diff --git a/docs/RelNotes/2.90.0.org b/docs/RelNotes/2.90.0.org
new file mode 100644
index 0000000..671e0bc
--- /dev/null
+++ b/docs/RelNotes/2.90.0.org
@@ -0,0 +1,438 @@
+* It's Magit!  A Git Porcelain inside Emacs
+
+Magit is a text-based Git user interface that puts an unmatched focus
+on streamlining workflows. Commands are invoked using short mnemonic
+key sequences that take the cursor’s position in the highly actionable
+interface into account to provide context-sensitive behavior.
+
+With Magit you can do nearly everything that you can do when using Git
+on the command-line, but at greater speed and while taking advantage
+of advanced features that previously seemed too daunting to use on a
+daily basis. Many users will find that by using Magit they can become
+more effective Git user.
+
+For more information about Magit, see https://magit.vc.
+
+* 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