Extend paragraph about remote branches

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

diff --git a/pep-git.txt b/pep-git.txt
index a9b4d9ea3b37911fbdc6431541bc7a419946637c..d13193422d307f9068e66001c1d433e75995b6b0 100644 (file)
--- a/pep-git.txt
+++ b/pep-git.txt
@@ -3,7 +3,7 @@ Title: Collecting information about git
 Version: $Revision$
 Last-Modified: $Date$
 Author: Oleg Broytman <phd@phdru.name>
 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
 Type: Informational
 Content-Type: text/x-rst
 Created: 01-Jun-2015


@@ -45,13 +45,13 @@ Git Tutorial: `part 1
 `Git workflows
 <https://www.kernel.org/pub/software/scm/git/docs/gitworkflows.html>`_.
 
 `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.
 
 `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
 `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


@@ -85,9 +85,11 @@ MacOS X: use git installed with `XCode
 <http://sourceforge.net/projects/git-osx-installer/files/>`_ or
 install git with `Homebrew <http://brew.sh/>`_: ``brew install git``.
 
 <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
 ---------------------
 
 Initial configuration
 ---------------------


@@ -115,10 +117,15 @@ done something like that::
     $ cd python
     $ git branch v1 origin/v1
 
     $ 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 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.
 
 The last command creates a new local branch v1 and sets
 remotes/origin/v1 as its upstream remote 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 clone -b v1 http://git.python.org/python.git
     $ cd python


@@ -142,8 +149,8 @@ Labels, on the other hand, can be created, moved, renamed and deleted
 freely.
 
 
 freely.
 
 

-Remote repository and remote branches
-=====================================
+Remote repositories and remote branches
+=======================================

 
 Another example of slightly misleading terminology. Remote
 repositories are really remote, you access them via network (well, a
 
 Another example of slightly misleading terminology. Remote
 repositories are really remote, you access them via network (well, a


@@ -166,9 +173,10 @@ To see local and remote branches (and tags) pointing to commits::
 
 You never do your own development on remote branches. You create a
 local branch that has a remote branch as upstream and do development
 
 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.
+on that local branch. On push git pushes commits to the remote repo
+and updates remote branches, on pull git fetches commits from the
+remote repo, updates remote branches and fast-forwards, merges or
+rebases local branches.

 
 When you do an initial clone like this::
 
 
 When you do an initial clone like this::
 


@@ -216,15 +224,15 @@ is equivalent to
 ::
 
     $ git fetch REMOTE BRANCH
 ::
 
     $ 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::
 
 
 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 merge v1
 
 If you have not yet pushed commits on ``v1``, though, the scenario has


@@ -373,11 +381,24 @@ or shared repository.
 Undo
 ====
 
 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``).
+
+TODO: describe undo strategies: git reset, git reflog, git revert.
+"Commit early, commit often".

 
 How to undo a merge
 
 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?
 
 
 Merge or rebase?


@@ -386,11 +407,11 @@ 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
 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
 
 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


@@ -403,31 +424,36 @@ and configure rebase for existing branches::
 
     $ git config branch.NAME.rebase true
 
 
     $ 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
 --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
         ...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 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::
 
     $ 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
 
 The topic branch is deleted to avoid cluttering branch namespace with
 small topic branches. Information on what issue was fixed or what


@@ -437,10 +463,10 @@ feature was implemented should be in the commit messages.
 Null-merges
 ===========
 
 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"::
 
 "null-merge"::
 

-    $ git merge -s ours v1 # null-merge v1 into v2
+    $ git merge -s ours v1  # null-merge v1 into v2

 
 
 ReReRe
 
 
 ReReRe


@@ -478,6 +504,7 @@ Database maintenance
 ====================
 
 TODO: dangling objects, git gc, git repack.
 ====================
 
 TODO: dangling objects, git gc, git repack.

+https://gcc.gnu.org/ml/gcc/2007-12/msg00165.html

 
 
 Tips and tricks
 
 
 Tips and tricks


@@ -485,7 +512,10 @@ Tips and tricks
 
 TODO: sticky options; example: git grep -O.
 
 
 TODO: sticky options; example: git grep -O.
 

+TODO: tricky options; example: git log -p3.
+

 TODO: bash/zsh completion, bash/zsh prompt.
 TODO: bash/zsh completion, bash/zsh prompt.

+https://git.kernel.org/cgit/git/git.git/tree/contrib/completion

 
 
 git on server
 
 
 git on server


@@ -493,6 +523,11 @@ git on server
 
 TODO: anonymous access; git over ssh; gitolite; gitweb; cgit; gitlab.
 
 
 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
 =====================
 
 From Mercurial to git
 =====================