Add Kallithea, pagure, gogs and gitea

[git-wiki.git] / pep-git.txt

diff --git a/pep-git.txt b/pep-git.txt
index 9dd4b0ca9647fd5e9bb34dee9095be5774e27a7f..4684b1e739eb1859be92dda50b52e1aa382b5098 100644 (file)
--- a/pep-git.txt
+++ b/pep-git.txt
@@ -72,7 +72,8 @@ Quick start
 Download and installation
 -------------------------
 
-Unix users: download and install using your package manager.
+Unix users: `download and install using your package manager
+<https://git-scm.com/download/linux>`_.
 
 Microsoft Windows: download `git-for-windows
 <https://github.com/git-for-windows/git/releases>`_ or `msysGit
@@ -637,8 +638,33 @@ 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 commit a file or files regardless of patches collected
+in the index run ``git commit [--only|-o] -- $FILE...``.
+
+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``. To see the diff between the working tree and the last commit
+(i.e., both collected and uncollected patches) run ``git diff HEAD``.
+
+See `WhatIsTheIndex
 <https://git.wiki.kernel.org/index.php/WhatIsTheIndex>`_ and
 `IndexCommandQuickref
 <https://git.wiki.kernel.org/index.php/IndexCommandQuickref>`_ in Git
@@ -654,11 +680,38 @@ https://git-scm.com/book/en/Git-Tools-Rerere
 Database maintenance
 ====================
 
-TODO: dangling objects, git gc, git repack.
-
-https://gcc.gnu.org/ml/gcc/2007-12/msg00165.html
-
-http://vcscompare.blogspot.ru/2008/06/git-repack-parameters.html
+Git object database and other files/directories under ``.git`` require
+periodic maintenance and cleanup. For example, commit editing left
+unreferenced objects (dangling objects, in git terminology) and these
+objects should be pruned to avoid collecting cruft in the DB. The
+command ``git gc`` is used for maintenance. Git automatically runs
+``git gc --auto`` as a part of some commands to do quick maintenance.
+Users are recommended to run ``git gc --aggressive`` from time to
+time; ``git help gc`` recommends to run it  every few hundred
+changesets; for more intensive projects it should be something like
+once a week and less frequently (biweekly or monthly) for lesser
+active projects.
+
+``git gc --aggressive`` not only removes dangling objects, it also
+repacks object database into indexed and better optimized pack(s); it
+also packs symbolic references (branches and tags). Another way to do
+it is to run ``git repack``.
+
+There is a well-known `message
+<https://gcc.gnu.org/ml/gcc/2007-12/msg00165.html>`_ from Linus
+Torvalds regarding "stupidity" of ``git gc --aggressive``. The message
+can safely be ignored now. It is old and outdated, ``git gc
+--aggressive`` became much better since that time.
+
+For those who still prefer ``git repack`` over ``git gc --aggressive``
+the recommended parameters are ``git repack -a -d -f --depth=20
+--window=250``. See `this detailed experiment
+<http://vcscompare.blogspot.ru/2008/06/git-repack-parameters.html>`_
+for explanation on the effects of these parameters.
+
+From time to time run ``git fsck [--strict]`` to verify integrity of
+the database. ``git fsck`` could report dangling objects; that's not
+an error, just a reminder to perform regular maintenance.
 
 
 Tips and tricks
@@ -675,7 +728,8 @@ https://git.kernel.org/cgit/git/git.git/tree/contrib/completion
 git on server
 =============
 
-TODO: anonymous access; git over ssh; gitolite; gitweb; cgit; gitlab.
+TODO: anonymous access (``git daemon``); git over ssh; gitolite;
+gitweb; cgit; Kallithea; pagure; gogs and gitea; gitlab.
 
 http://gitolite.com/gitolite/index.html
 
@@ -683,6 +737,15 @@ https://git.kernel.org/cgit/git/git.git/tree/gitweb
 
 http://git.zx2c4.com/cgit/
 
+https://kallithea-scm.org/
+
+https://pagure.io/
+
+http://gogs.io/ and http://gitea.io/
+
+https://about.gitlab.com/
+
+
 From Mercurial to git
 =====================