Commit c2ee9270 authored by Jonas Bernoulli's avatar Jonas Bernoulli

add and extend library commentaries

parent ca2cafa8
......@@ -32,37 +32,82 @@
;;; Commentary:
;; Support for editing Git commit messages.
;;;; Formatting
;; Highlight the formatting of git commit messages and indicate errors according
;; to the guidelines for commit messages (see
;; http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html).
;; This package assists the user in writing good Git commit messages.
;; While Git allows for the message to be provided on the command
;; line, it is preferable to tell Git to create the commit without
;; actually passing it a message. Git then invokes the `$GIT_EDITOR'
;; (or if that is undefined `$EDITOR') asking the user to provide the
;; message by editing the file ".git/COMMIT_MSG" (or another file in
;; that directory, e.g. ".git/MERGE_MSG" for merge commits).
;; When `global-git-commit-mode' is enabled, which it is by default,
;; then opening such a file causes the features described below, to
;; be enabled in that buffer. Normally this would be done using a
;; major-mode but to allow the use of any major-mode, as the user sees
;; fit, it is done here by running a setup function, which among other
;; things turns on the preferred major-mode, by default `text-mode'.
;; Git waits for the `$EDITOR' to finish and then either creates the
;; commit using the contents of the file as commit message, or, if the
;; editor process exited with a non-zero exit status, aborts without
;; creating a commit. Unfortunately Emacsclient (which is what Emacs
;; users should be using as `$EDITOR' or at least as `$GIT_EDITOR')
;; does not differentiate between "successfully" editing a file and
;; aborting; not out of the box that is.
;; By making use of the `with-editor' package this package provides
;; both ways of finish an editing session. In either case the file
;; is saved, but Emacseditor's exit code differs.
;;
;; Highlight the first line (aka "summary") specially if it exceeds 50
;; characters (configurable using `git-commit-summary-max-length').
;; C-c C-c Finish the editing session successfully by returning
;; with exit code 0. Git then creates the commit using
;; the message it finds in the file.
;;
;; Enable `auto-fill-mode' and set the `fill-column' to 72 according to the
;; aforementioned guidelines (configurable using `git-commit-fill-column').
;;;; Headers
;; Provide commands to insert standard headers into commit messages.
;; C-c C-k Aborts the edit editing session by returning with exit
;; code 1. Git then aborts the commit.
;; Aborting the commit does not cause the message to be lost, but
;; relying solely on the file not being tampered with is risky. This
;; package additionally stores all aborted messages for the duration
;; of the current session (i.e. until you close Emacs). To get back
;; an aborted message use M-p and M-n while editing a message.
;;
;; - C-c C-s inserts Signed-off-by (`git-commit-signoff').
;; - C-C C-a inserts Acked-by (`git-commit-ack').
;; - C-c C-t inserts Tested-by (`git-commit-test').
;; - C-c C-r inserts Reviewed-by (`git-commit-review').
;; - C-c C-o inserts Cc (`git-commit-cc').
;; - C-c C-p inserts Reported-by (`git-commit-reported').
;;;; Committing
;; M-p Replace the buffer contents with the previous message
;; from the message ring. Of course only after storing
;; the current content there too.
;;
;; M-n Replace the buffer contents with the next message from
;; the message ring, after storing the current content.
;; C-c C-c finishes a commit.
;; Some support for pseudo headers as used in some projects is
;; provided by these commands:
;;
;; C-c C-s Insert a Signed-off-by header.
;; C-C C-a Insert a Acked-by header.
;; C-c C-t Insert a Tested-by header.
;; C-c C-r Insert a Reviewed-by header.
;; C-c C-o Insert a Cc header.
;; C-c C-p Insert a Reported-by header.
;; C-c M-s Insert a Suggested-by header.
;; When Git requests a commit message from the user, it does so by
;; having her edit a file which initially contains some comments,
;; instructing her what to do, and providing useful information, such
;; as which files were modified. These comments, even when left
;; intact by the user, do not become part of the commit message. This
;; package ensures these comments are propertizes as such and further
;; prettifies them by using different faces for various parts, such as
;; files.
;; Finally this package highlights style errors, like lines that are
;; to long, or when the second line is not empty. It may even nag you
;; when you attempt to finish the commit without having fixed these
;; issues. Some people like that nagging, I don't, so you'll have to
;; enable it. Which brings me to the last point. Like any
;; respectable Emacs package, this one too is highly customizable:
;;
;; Check a buffer for stylistic errors before committing, and ask for
;; confirmation before committing with style errors.
;; M-x customize-group RET git-commit RET
;;; Code:
;;;; Dependencies
......
;;; git-rebase.el --- Major mode for editing git rebase files
;;; git-rebase.el --- Major mode for editing Git rebase files
;; Copyright (C) 2010-2015 The Magit Project Developers
;;
......@@ -29,9 +29,38 @@
;;; Commentary:
;; Allows the editing of a git rebase file (which you might get when
;; using 'git rebase -i' or hitting 'E' in Magit). Assumes editing is
;; happening in a server.
;; This package assists the user in editing the list of commits to be
;; rewritten during an interactive rebase.
;; When the user initiates an interactive rebase, e.g. using "e e" in
;; a Magit buffer or on the command line using "git rebase -i REV",
;; Git invokes the `$GIT_SEQUENCE_EDITOR' (or if that is undefined
;; `$GIT_EDITOR' or even `$EDITOR') letting the user rearrange, drop,
;; reword, edit, and squash commits.
;; This package provides the major-mode `git-rebase-mode' which makes
;; doing so much more fun, by making the buffer more colorful and
;; providing the following commands:
;;
;; C-c C-c Tell Git to make it happen.
;; C-c C-k Tell Git that you changed your mind, i.e. abort.
;;
;; M-p Move the commit at point up.
;; M-n Move the commit at point down.
;;
;; k Drop the commit at point.
;; p Don't drop the commit at point.
;; r Change the message of the commit at point.
;; e Edit the commit at point.
;; s Squash the commit at point, into the one above.
;; f Like "s" but don't also edit the commit message.
;; x Add a script to be run with the commit at point
;; being checked out.
;;
;; RET Show the commit at point in another buffer.
;; C-/ Undo last change.
;; You should probably also read the `git-rebase' manpage.
;;; Code:
......
......@@ -22,6 +22,13 @@
;; You should have received a copy of the GNU General Public License
;; along with Magit. If not, see http://www.gnu.org/licenses.
;;; Commentary:
;; This library implements commands for applying Git diffs or parts
;; of such a diff. The supported "apply variants" are apply, stage,
;; unstage, discard, and reverse - more than Git itself knows about,
;; at least at the porcelain level.
;;; Code:
(require 'magit-core)
......
......@@ -22,6 +22,23 @@
;; You should have received a copy of the GNU General Public License
;; along with Magit. If not, see http://www.gnu.org/licenses.
;;; Commentary:
;; This library implements support for creating stashes that serve
;; as backups. When `magit-backup-mode' is enabled, then many Magit
;; command that may lose data, try to mitigate the risk by first
;; saving a stash to `magit-backup-ref'.
;; Note that "many" is not the same as "all" and that "Magit" is not
;; the same as "any way in which one can interact with a repository".
;; Generally speaking only changes which can be saved by creating a
;; stash, are being saved by creating a stash - which is exactly the
;; sort of tautology you would in the description of any backup tool.
;; You might also be interested in `magit-wip-save-mode', which is
;; defined elsewhere, and which covers one of the many cases where
;; using `magit-backup-mode' would not have saved you.
;;; Code:
(require 'magit)
......
......@@ -22,6 +22,12 @@
;; You should have received a copy of the GNU General Public License
;; along with Magit. If not, see http://www.gnu.org/licenses.
;;; Commentary:
;; This library implements commands for creating Git commits. These
;; commands just initiate the commit, support for writing the commit
;; messages is implemented in `git-commit.el'.
;;; Code:
(require 'magit)
......
......@@ -22,6 +22,13 @@
;; You should have received a copy of the GNU General Public License
;; along with Magit. If not, see http://www.gnu.org/licenses.
;;; Commentary:
;; This library requires several other libraries, so that yet other
;; libraries can just require this one, instead of having to require
;; all the other ones. In other words this separates the low-level
;; stuff from the rest. It also defines some Custom groups.
;;; Code:
(require 'magit-utils)
......
......@@ -22,6 +22,11 @@
;; You should have received a copy of the GNU General Public License
;; along with Magit. If not, see http://www.gnu.org/licenses.
;;; Commentary:
;; This library implements support for looking at Git diffs and
;; commits.
;;; Code:
(require 'git-commit)
......
......@@ -22,6 +22,10 @@
;; You should have received a copy of the GNU General Public License
;; along with Magit. If not, see http://www.gnu.org/licenses.
;;; Commentary:
;; This library implements wrappers for various Git plumbing commands.
;;; Code:
(require 'cl-lib)
......
......@@ -22,6 +22,12 @@
;; You should have received a copy of the GNU General Public License
;; along with Magit. If not, see http://www.gnu.org/licenses.
;;; Commentary:
;; This library implements support for looking at Git logs, including
;; special logs like reflogs and cherry-logs, as well as for selecting
;; a commit from a log.
;;; Code:
(require 'magit-core)
......
......@@ -22,6 +22,12 @@
;; You should have received a copy of the GNU General Public License
;; along with Magit. If not, see http://www.gnu.org/licenses.
;;; Commentary:
;; This library implements the abstract major-mode `magit-mode' from
;; which almost all other Magit major-modes derive. The code in here
;; is mostly concerned with creating and refreshing Magit buffers.
;;; Code:
(require 'cl-lib)
......
......@@ -22,6 +22,14 @@
;; You should have received a copy of the GNU General Public License
;; along with Magit. If not, see http://www.gnu.org/licenses.
;;; Commentary:
;; This library implements the tools used to run Git for side-effects.
;; Note that the functions used to run Git and then consume its
;; output, are defined in `magit-git.el'. There's a bit of overlap
;; though.
;;; Code:
(require 'cl-lib)
......
......@@ -22,6 +22,12 @@
;; You should have received a copy of the GNU General Public License
;; along with Magit. If not, see http://www.gnu.org/licenses.
;;; Commentary:
;; This library implements support for interacting with remote
;; repositories. Commands for cloning, fetching, pulling, and
;; pushing are defined here.
;;; Code:
(require 'magit)
......
......@@ -22,6 +22,12 @@
;; You should have received a copy of the GNU General Public License
;; along with Magit. If not, see http://www.gnu.org/licenses.
;;; Commentary:
;; This library implements "sections" as used in all Magit buffers.
;; If you have used Magit before then you probably know what that
;; means, otherwise think "read-only Org-Mode for Git", kinda.
;;; Code:
(require 'cl-lib)
......
......@@ -25,6 +25,22 @@
;; You should have received a copy of the GNU General Public License
;; along with Magit. If not, see http://www.gnu.org/licenses.
;;; Commentary:
;; This library defines several utility functions used by several
;; other libraries which cannot depend on one another (because
;; circular dependencies are not good). Luckily most (all) of these
;; functions have very little (nothing) to do with Git, so we not only
;; have to do this, it even makes sense.
;; Unfortunately there are also some options which are used by several
;; libraries which cannot depend on one another, they are defined here
;; too.
;; And finally, some users insist on using ancient Emacsen, making
;; backward compatibility definitions necessary. They too are placed
;; here.
;;; Code:
(require 'cl-lib)
......
......@@ -22,6 +22,12 @@
;; You should have received a copy of the GNU General Public License
;; along with Magit. If not, see http://www.gnu.org/licenses.
;;; Commentary:
;; This library implements a global minor-mode which saves changes to
;; dedicated work-in-progress refs, whenever the user saves a buffer
;; which visits a file tracked by Git.
;;; Code:
(require 'magit-core)
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment