1 files changed, 31 insertions, 0 deletions
diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi
index b93009ad216..ddde5b22e6b 100644
--- a/doc/emacs/custom.texi
+++ b/doc/emacs/custom.texi
@@ -2209,6 +2209,7 @@ Manual}.
 * Terminal Init::       Each terminal type can have an init file.
 * Find Init::           How Emacs finds the init file.
 * Init Non-ASCII::      Using non-@acronym{ASCII} characters in an init file.
+* Early Init File::     Another init file, which is read early on.
 @end menu
 
 @node Init Syntax
@@ -2609,3 +2610,33 @@ instance:
 
 @noindent
 Type @kbd{C-q}, followed by the key you want to bind, to insert @var{char}.
+
+@node Early Init File
+@subsection The Early Init File
+@cindex early init file
+
+  Most customizations for Emacs should be put in the normal init file,
+@file{.emacs} or @file{~/.emacs.d/init.el}.  However, it is sometimes desirable
+to have customizations that take effect during Emacs startup earlier than the
+normal init file is processed.  Such customizations can be put in the early
+init file, @file{~/.emacs.d/early-init.el}.  This file is loaded before the
+package system and GUI is initialized, so in it you can customize variables
+that affect frame appearance as well as the package initialization process,
+such as @code{package-enable-at-startup}, @code{package-load-list}, and
+@code{package-user-dir}.  Note that variables like @code{package-archives}
+which only affect the installation of new packages, and not the process of
+making already-installed packages available, may be customized in the regular
+init file.  @xref{Package Installation}.
+
+  We do not recommend that you move into @file{early-init.el}
+customizations that can be left in the normal init files.  That is
+because the early init file is read before the GUI is initialized, so
+customizations related to GUI features will not work reliably in
+@file{early-init.el}.  By contrast, the normal init files are read
+after the GUI is initialized.  If you must have customizations in the
+early init file that rely on GUI features, make them run off hooks
+provided by the Emacs startup, such as @code{window-setup-hook} or
+@code{tty-setup-hook}.  @xref{Hooks}.
+
+  For more information on the early init file, @pxref{Init File,,,
+elisp, The Emacs Lisp Reference Manual}.