`Git Wiki <https://git.wiki.kernel.org/index.php/Main_Page>`_.
+`Git Buch <http://gitbu.ch/index.html>`_ (German).
+
Offline documentation
---------------------
to track upstream remotes/origin/v1 branch and checks out ``v1`` into
the working directory.
+Some commands, like ``git status --branch`` and ``git branch --verbose``,
+report the difference between local and remote branches.
+Please remember they only do comparison with remote-tracking branches
+in your local repository, and the state of those remote-tracking
+branches can be outdated. To update remote-tracking branches you
+either fetch and merge (or rebase) commits from the remote repository
+or update remote-tracking branches without updating local branches.
+
Updating local and remote-tracking branches
-------------------------------------------
+To update remote-tracking branches without updating local branches run
+``git remote update [$REMOTE...]``. For example::
+
+ $ git remote update
+ $ git remote update origin
+
+
+Fetch and pull
+''''''''''''''
+
There is a major difference between
::
question's diminished even further: "whether to use rebase on
non-pushed commits?"
-That small question is for the team to decide. The author of the PEP
-recommends to use rebase when pulling, i.e. always do ``git pull
---rebase`` or even configure automatic setup of rebase for every new
-branch::
+That small question is for the team to decide. To preserve the beauty
+of linear history it's recommended to use rebase when pulling, i.e. do
+``git pull --rebase`` or even configure automatic setup of rebase for
+every new branch::
$ git config branch.autosetuprebase always
small topic branches. Information on what issue was fixed or what
feature was implemented should be in the commit messages.
+But even that small amount of rebasing could be too big in case of
+long-lived merged branches. Imagine you're doing work in both ``v1``
+and ``master`` branches, regularly merging ``v1`` into ``master``.
+After some time you will have a lot of merge and non-merge commits in
+``master``. Then you want to push your finished work to a shared
+repository and find someone has pushed a few commits to ``v1``. Now
+you have a choice of two equally bad alternatives: either you fetch
+and rebase ``v1`` and then have to recreate all you work in ``master``
+(reset ``master`` to the origin, merge ``v1`` and cherry-pick all
+non-merge commits from the old master); or merge the new ``v1`` and
+loose the beauty of linear history.
+
Null-merges
===========
$ git check-attr -a -- \*.py
+Useful assets
+-------------
+
+`GitAlias <http://gitalias.com/>`_ (`repository
+<https://github.com/GitAlias/gitalias>`_) is a big collection of
+aliases. A careful selection of aliases for frequently used commands
+could save you a lot of keystrokes!
+
+`GitIgnore <https://www.gitignore.io/>`_ and
+https://github.com/github/gitignore are collections of ``.gitignore``
+files for all kinds of IDEs and programming languages. Python
+included!
+
+`pre-commit <http://pre-commit.com/>`_ (`repositories
+<https://github.com/pre-commit>`_) is a framework for managing and
+maintaining multi-language pre-commit hooks. The framework is written
+in Python and has a lot of plugins for many programming languages.
+
+
Advanced topics
===============
Wiki.
+Root
+----
+
+Git switches to the root (top-level directory of the project where
+``.git`` subdirectory exists) before running any command. Git
+remembers though the directory that was current before the switch.
+Some programs take into account the current directory. E.g., ``git
+status`` shows file paths of changed and unknown files relative to the
+current directory; ``git grep`` searches below the current directory;
+``git apply`` applies only those hunks from the patch that touch files
+below the current directory.
+
+But most commands run from the root and ignore the current directory.
+Imagine, for example, that you have two work trees, one for the branch
+``v1`` and the other for ``master``. If you want to merge ``v1`` from
+a subdirectory inside the second work tree you must write commands as
+if you're in the top-level dir. Let take two work trees,
+``project-v1`` and ``project``, for example::
+
+ $ cd project/subdirectory
+ $ git fetch ../project-v1 v1:v1
+ $ git merge v1
+
+Please note the path in ``git fetch ../project-v1 v1:v1`` is
+``../project-v1`` and not ``../../project-v1`` despite the fact that
+we run the commands from a subdirectory, not from the root.
+
+
ReReRe
-======
+------
Rerere is a mechanism that helps to resolve repeated merge conflicts.
The most frequent source of recurring merge conflicts are topic
$ git config rerere.autoupdate true
You don't need to turn rerere on globally - you don't want rerere in
-bare repositories or single-branche repositories; you only need rerere
+bare repositories or single-branch repositories; you only need rerere
in repos where you often perform merges and resolve merge conflicts.
See `Rerere <https://git-scm.com/book/en/Git-Tools-Rerere>`_ in The
Database maintenance
-====================
+--------------------
Git object database and other files/directories under ``.git`` require
periodic maintenance and cleanup. For example, commit editing left
BTW, if git is instructed to use ``less`` as the pager (i.e., if pager
is not configured in git at all it uses ``less`` by default, or if it
gets ``less`` from GIT_PAGER or PAGER environment variables, or if it
-was configured with ``git config --global core.pager less``, or
+was configured with ``git config [--global] core.pager less``, or
``less`` is used in the command ``git grep -Oless``) ``git grep``
passes ``+/$pattern`` option to ``less`` which is quite convenient.
Unfortunately, ``git grep`` doesn't pass the pattern if the pager is
not exactly ``less``, even if it's ``less`` with parameters (something
-like ``git config --global core.pager less -FRSXgimq``); fortunately,
+like ``git config [--global] core.pager less -FRSXgimq``); fortunately,
``git grep -Oless`` always passes the pattern.
<https://git.kernel.org/cgit/git/git.git/tree/gitweb>`_ or `cgit
<http://git.zx2c4.com/cgit/about/>`_. Both are CGI scripts (written in
Perl and C). In addition to web interface both provide read-only dumb
-http access for git (http(s):// URLs).
+http access for git (http(s):// URLs). `Klaus
+<https://pypi.python.org/pypi/klaus>`_ is a small and simple WSGI web
+server that implements both web interface and git smart HTTP
+transport; supports Python 2 and Python 3, performs syntax
+highlighting.
There are also more advanced web-based development environments that
include ability to manage users, groups and projects; private,
and communication. Among these environments are `Kallithea
<https://kallithea-scm.org/>`_ and `pagure <https://pagure.io/>`_,
both are written in Python; pagure was written by Fedora developers
-and is being used to develop some Fedora projects. `Gogs
-<https://gogs.io/>`_ is written in Go; there is a fork `Gitea
-<http://gitea.io/>`_. `GitBucket
-<https://takezoe.github.io/gitbucket/about/>`_ is written in Scala.
+and is being used to develop some Fedora projects. `GitPrep
+<http://gitprep.yukikimoto.com/>`_ is yet another Github clone,
+written in Perl. `Gogs <https://gogs.io/>`_ is written in Go.
+`GitBucket <https://takezoe.github.io/gitbucket/about/>`_ is written
+in Scala.
And last but not least, `Gitlab <https://about.gitlab.com/>`_. It's
perhaps the most advanced web-based development environment for git.