Version: $Revision$
Last-Modified: $Date$
Author: Oleg Broytman <phd@phdru.name>
-Status: Active
+Status: Draft
Type: Informational
Content-Type: text/x-rst
Created: 01-Jun-2015
`Git workflows
<https://www.kernel.org/pub/software/scm/git/docs/gitworkflows.html>`_.
+Advanced documentation
+----------------------
+
`Git Magic
<http://www-cs-students.stanford.edu/~blynn/gitmagic/index.html>`_,
also with a number of translations.
-Advanced documentation
-----------------------
-
`Pro Git <https://git-scm.com/book>`_. The Book about git. Buy it at
Amazon or download in PDF, mobi, or ePub form. Has translations to
many different languages. Download Russian translation from `GArik
<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 sleek and
-powerful Git GUI written in Python and GPL licensed. Linux, Windows,
-MacOS X.
+`git-cola <https://git-cola.github.io/index.html>`_ 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.
Initial configuration
---------------------
$ cd python
$ git branch v1 origin/v1
+The first command clones remote repository into local directory
+`python``, creates a new local branch v2, sets remotes/origin/v2 as
+its upstream remote-tracking branch and checks it out into the working
+directory.
+
The last command creates a new local branch v1 and sets
-remotes/origin/v1 as its upstream remote branch.
+remotes/origin/v1 as its upstream remote-tracking branch.
-The same result can achieved with commands::
+The same result can be achieved with commands::
$ git clone -b v1 http://git.python.org/python.git
$ cd python
$ git checkout --track origin/v2
-The last command creates a new local branch v2, sets
-remotes/origin/v2 as its upstream remote branch and checks it out into
-the working directory.
+The last command creates a new local branch v2, sets remotes/origin/v2
+as its upstream remote-tracking branch and checks it out into the
+working directory.
Branches and branches
freely.
-Remote repository and remote branches
-=====================================
-
-Another example of slightly misleading terminology. Remote
-repositories are really remote, you access them via network (well, a
-remote repository can be on your local disk, but it's still remote
-because it's not the current repo).
+Remote repositories and remote branches
+=======================================
-Remote branches, on the other hand, are branches (pointers to commits)
-in your local repository. They are there for you to remember what
-branches and commits have been pulled from and pushed to what remote
-repos (you can pull from and push to many remotes). Remote branches
-live under ``remotes/REMOTE`` namespaces, e.g. ``remotes/origin/v2``.
+Remote-tracking branches are branches (pointers to commits) in your
+local repository. They are there for you to remember what branches and
+commits have been pulled from and pushed to what remote repos (you can
+pull from and push to many remotes). Remote-tracking branches live
+under ``remotes/REMOTE`` namespaces, e.g. ``remotes/origin/v2``.
-To see the status of remote branches run::
+To see the status of remote-tracking branches run::
$ git branch -rv
-To see local and remote branches (and tags) pointing to commits::
+To see local and remote-tracking branches (and tags) pointing to
+commits::
$ git log --decorate
-You never do your own development on remote branches. You create a
-local branch that has a remote branch as upstream and do development
-on that local branch. On push git updates remote branches, and on pull
-git updates remote branches and fast-forwards, merges or rebases local
-branches.
+You never do your own development on remote-tracking branches. You
+create a local branch that has a remote branch as upstream and do
+development on that local branch. On push git pushes commits to the
+remote repo and updates remote-tracking branches, on pull git fetches
+commits from the remote repo, updates remote-tracking branches and
+fast-forwards, merges or rebases local branches.
When you do an initial clone like this::
$ git clone -b v1 http://git.python.org/python.git
git clones remote repository ``http://git.python.org/python.git`` to
-directory ``python``, creates remote branches, creates a local branch
-``v1``, configure it to track upstream remotes/origin/v1 branch and
-checks out ``v1`` into the working directory.
+directory ``python``, creates remote-tracking branches, creates a
+local branch ``v1``, configure it to track upstream remotes/origin/v1
+branch and checks out ``v1`` into the working directory.
-Updating local and remote branches
-----------------------------------
+Updating local and remote-tracking branches
+-------------------------------------------
There is a major difference between
The second command fetches commits from the named BRANCH in the REMOTE
repository that are not in your repository and updates both the local
-branch BRANCH and its upstream remote branch. But it refuses to update
-branches in case of non-fast-forward. And it refuses to update the
-current branch.
+branch BRANCH and its upstream remote-tracking branch. But it refuses
+to update branches in case of non-fast-forward. And it refuses to
+update the current branch.
The first command is used internally by ``git pull``.
::
$ git fetch REMOTE BRANCH
- $ git merge FETCH_HEAD # FETCH_HEAD is a literal here
+ $ git merge FETCH_HEAD # FETCH_HEAD is a literal here
Certainly, BRANCH in that case should be your current branch. If you
want to merge a different branch into your current branch first update
that non-current branch and then merge::
- $ git fetch origin v1:v1 # Update v1
- $ git pull --rebase origin v2 # Update the current branch v2 using
- # rebase instead of merge
+ $ git fetch origin v1:v1 # Update v1
+ $ git pull --rebase origin v2 # Update the current branch v2 using
+ # rebase instead of merge
$ git merge v1
If you have not yet pushed commits on ``v1``, though, the scenario has
$ git push origin v1:v1 v2:v2
-Git pushes commits to the remote repo and updates remote branches. Git
-refuses to push commits that aren't fast-forwardable. You can
-force-push anyway, but please remember - you can force-push to your
-own repositories but don't force-push to public or shared repos. If
-you find git refuses to push commits that aren't fast-forwardable,
+Git pushes commits to the remote repo and updates remote-tracking
+branches. Git refuses to push commits that aren't fast-forwardable.
+You can force-push anyway, but please remember - you can force-push to
+your own repositories but don't force-push to public or shared repos.
+If you find git refuses to push commits that aren't fast-forwardable,
better fetch and merge commits from the remote repo (or rebase your
commits on top of the fetched commits), then push. Only force-push if
you know what you do and why you do it. See the section `Commit
entire team. Please avoid it.
To see what commits have not been published yet compare the head of the
-branch with its upstream remote branch::
+branch with its upstream remote-tracking branch::
$ git log origin/v2..
$ git log origin/v1..v1
-For every branch that has an upstream remote branch git maintains an
-alias @{upstream} (short version @{u}), so the commands above can be
-given as::
+For every branch that has an upstream remote-tracking branch git
+maintains an alias @{upstream} (short version @{u}), so the commands
+above can be given as::
$ git log @{u}..
$ git log v1@{u}..v1
Undo
====
-TODO: describe undo strategies: git reset, git revert, git checkout,
-git reflog. "Commit early, commit often".
+Whatever you do, don't panic. Almost anything in git can be undone.
+``git checkout``, for example, can be used to restore the content of
+file(s) to that one of a commit. Like this::
+
+ git checkout HEAD~ README
+
+The commands restores the contente of README file to the last but one
+commit in the current branch. By default a commit ID is simple HEAD;
+i.e. ``git checkout README`` restores README to the latest commit.
+
+(Do not use ``git checkout`` to view a content of a file in a commit,
+use ``git cat-file -p``; e.g. ``git cat-file -p HEAD~:path/to/README``).
+
+``git reset`` moves the head of the current branch. The head can be
+moved to point to any commit but it's often used to remove a commit or
+a few (preferably, non-pushed ones) from the top of the branch - that
+is, to move the branch backward in order to undo a few non-pushed
+commits.
+
+``git reset`` has three modes of operation - soft, hard and mixed.
+Default is mixed. ProGit `explains
+<https://git-scm.com/book/en/Git-Tools-Reset-Demystified>`_ the
+difference very clearly. Bare repositories don't have indices or
+working trees so in a bare repo only soft reset is possible.
+
+Mixed mode reset with a path or paths can be used to unstage changes -
+that is, to remove changes added with ``git add`` for committing. See
+`The Book <https://git-scm.com/book/en/v2/Git-Basics-Undoing-Things>`_
+for details about unstaging and other undo tricks.
+
+TODO: describe undo strategies: git reflog, git revert.
+"Commit early, commit often".
How to undo a merge
-https://kernel.org/pub/software/scm/git/docs/howto/revert-a-faulty-merge.html
+https://www.kernel.org/pub/software/scm/git/docs/howto/revert-a-faulty-merge.html
Merge or rebase?
Internet is full of heated discussions on the topic: "merge or
rebase?" Most of them are meaningless. When a DVCS is being used in a
big team with a big and complex project with many branches there is
-simply no way to avoid merges. So the question diminished to "whether
-to use rebase, and if yes - when to use rebase?" Considering that it
-is very much recommended not to rebase published commits the question
-diminished even further: "whether to use rebase on non-pushed
-commits?"
+simply no way to avoid merges. So the question's diminished to
+"whether to use rebase, and if yes - when to use rebase?" Considering
+that it is very much recommended not to rebase published commits the
+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::
- $ git config branch.autosetuprebase true
+ $ git config branch.autosetuprebase always
and configure rebase for existing branches::
$ git config branch.NAME.rebase true
-After that ``git pull origin v2`` will be equivalent to ``git pull
+For example::
+
+ $ git config branch.v1.rebase true
+ $ git config branch.v2.rebase true
+
+After that ``git pull origin v2`` becomes equivalent to ``git pull
--rebase origin v2``.
In case when merge is preferred it is recommended to create new
commits in a separate feature or topic branch while using rebase to
update the mainline branch. When the topic branch is ready merge it
-into mainline. To avoid a tedious task of resolving conflicts you can
-merge the topic branch to the mainline from time to time and switch
-back to the topic branch to continue working on it. The entire
-workflow would be something like::
+into mainline. To avoid a tedious task of resolving large number of
+conflicts at once you can merge the topic branch to the mainline from
+time to time and switch back to the topic branch to continue working
+on it. The entire workflow would be something like::
- $ git checkout -b issue-42 # create and switch to a new branch
+ $ git checkout -b issue-42 # create a new issue branch and switch to it
...edit/test/commit...
$ git checkout v2
- $ git pull --rebase origin v2 # update v2 from the upstream
+ $ git pull --rebase origin v2 # update v2 from the upstream
$ git merge issue-42
- $ git branch -d issue-42 # delete the topic branch
+ $ git branch -d issue-42 # delete the topic branch
$ git push origin v2
When the topic branch is deleted only the label is removed, commits
are stayed in the database, they are now merged into v2::
- --o--o--o--o--o--o-M-<v2 - it is the mainline branch
- \ /
- --*--*--* - it is the topic branch, now unnamed
+ o--o--o--o--o--M--< v2 - the mainline branch
+ \ /
+ --*--*--* - the topic branch, now unnamed
The topic branch is deleted to avoid cluttering branch namespace with
small topic branches. Information on what issue was fixed or what
Null-merges
===========
-Git has a builtin strategy for what Python core developers call
+Git has a builtin merge strategy for what Python core developers call
"null-merge"::
- $ git merge -s ours v1 # null-merge v1 into v2
+ $ git merge -s ours v1 # null-merge v1 into v2
ReReRe
====================
TODO: dangling objects, git gc, git repack.
+https://gcc.gnu.org/ml/gcc/2007-12/msg00165.html
Tips and tricks
TODO: sticky options; example: git grep -O.
+TODO: tricky options; example: git log -p3.
+
TODO: bash/zsh completion, bash/zsh prompt.
+https://git.kernel.org/cgit/git/git.git/tree/contrib/completion
git on server
TODO: anonymous access; git over ssh; gitolite; gitweb; cgit; gitlab.
+http://gitolite.com/gitolite/index.html
+
+https://git.kernel.org/cgit/git/git.git/tree/gitweb
+
+http://git.zx2c4.com/cgit/
From Mercurial to git
=====================
projects / git-wiki.git / blobdiff