Describe staging area

diff --git a/pep-git.txt b/pep-git.txt
index 9dd4b0ca9647fd5e9bb34dee9095be5774e27a7f..552901ea2f49487d84ea16af94a3864c9afa9e8d 100644 (file)
--- a/pep-git.txt
+++ b/pep-git.txt
@@ -637,8 +637,31 @@ Advanced topics
 Staging area
 ------------
 
-Staging area aka index is a distinguishing feature of git. See
-`WhatIsTheIndex
+Staging area aka index aka cache is a distinguishing feature of git.
+Staging area is where git collects patches before committing them.
+Separation between collecting patches and commit phases provides a
+very useful feature of git: one can review collected patches before
+commit and even edit them - remove some hunks, add new hunks and
+review again.
+
+To add files to the index use ``git add``. Collecting patches before
+committing means you need to do that for every change, not only to add
+new (untracked) files. To simplify committing in case you just want to
+commit everything without reviewing run ``git commit --all`` (or just
+``-a``) - the command adds every changed tracked file to the index and
+then commit.
+
+To add hunks of patches to the index use ``git add --patch`` (or just
+``-p``). To remove collected files from the index use ``git reset HEAD
+-- $FILE...`` To add/inspect/remove collected hunks use ``git add
+--interactive`` (``-i``).
+
+To see the diff between the index and the last commit (i.e., collected
+patches) use ``git diff --cached``. To see the diff between the
+working tree and the index (i.e., uncollected patches) use just ``git
+diff``.
+
+See `WhatIsTheIndex
 <https://git.wiki.kernel.org/index.php/WhatIsTheIndex>`_ and
 `IndexCommandQuickref
 <https://git.wiki.kernel.org/index.php/IndexCommandQuickref>`_ in Git