`Git Wiki <https://git.wiki.kernel.org/index.php/Main_Page>`_.
+`Git Buch <http://gitbu.ch/index.html>`_ (German).
+
Offline documentation
---------------------
<https://git-scm.com/download/linux>`_.
Microsoft Windows: download `git-for-windows
-<https://github.com/git-for-windows/git/releases>`_ or `msysGit
-<https://github.com/msysgit/msysgit/releases>`_.
+<https://github.com/git-for-windows/git/releases>`_.
MacOS X: use git installed with `XCode
-<https://developer.apple.com/xcode/downloads/>`_ or download from
-`MacPorts <https://www.macports.org/ports.php?by=name&substr=git>`_ or
+<https://developer.apple.com/xcode/>`_ or download from `MacPorts
+<https://www.macports.org/ports.php?by=name&substr=git>`_ or
`git-osx-installer
<http://sourceforge.net/projects/git-osx-installer/files/>`_ or
install git with `Homebrew <http://brew.sh/>`_: ``brew install git``.
-`git-cola <https://git-cola.github.io/index.html>`_ is a Git GUI
-written in Python and GPL licensed. Linux, Windows, MacOS X.
+`git-cola <https://git-cola.github.io/index.html>`_ (`repository
+<https://github.com/git-cola/git-cola>`__) is a Git GUI written in
+Python and GPL licensed. Linux, Windows, MacOS X.
`TortoiseGit <https://tortoisegit.org/>`_ is a Windows Shell Interface
to Git based on TortoiseSVN; open source.
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
::
<https://git-scm.com/docs/git-rebase#_recovering_from_upstream_rebase>`_.
It is in ``git help rebase``.
-On the other hand don't be too afraid about commit editing. You can
+On the other hand, don't be too afraid about commit editing. You can
safely edit, reorder, remove, combine and split commits that haven't
been pushed yet. You can even push commits to your own (backup) repo,
edit them later and force-push edited commits to replace what have
original commit but preserve two commits created in the current branch
do something like::
- $ git branch save-master # create a new branch saving master
- $ git reflog # find the original place of master
+ $ git branch save-master # create a new branch saving master
+ $ git reflog # find the original place of master
$ git reset $COMMIT_ID
$ git cherry-pick save-master~ save-master
- $ git branch -D save-master # remove temporary branch
+ $ git branch -D save-master # remove temporary branch
git revert: revert a commit
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
a program; default program for ``-O`` is a pager (usually ``less``),
but you can use your editor::
- $ git grep -Ovim # but not -O vim
+ $ git grep -Ovim # but not -O vim
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
-<http://gogs.io/>`_ is written in Go; there is a fork `Gitea
-<http://gitea.io/>`_.
+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://gitbucket.github.io/gitbucket-news/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.
To start converting your Mercurial habits to git see the page
`Mercurial for Git users
-<https://mercurial.selenic.com/wiki/GitConcepts>`_ at Mercurial wiki.
+<https://www.mercurial-scm.org/wiki/GitConcepts>`_ at Mercurial wiki.
At the second half of the page there is a table that lists
corresponding Mercurial and git commands. Should work perfectly in
both directions.