X-Git-Url: https://git.phdru.name/?a=blobdiff_plain;ds=sidebyside;f=pep-git.txt;h=402dac8907b5731166e4ae04ba822737a5d08808;hb=d97d98eb25a34050380fa73f58752c2e2af5c207;hp=4cbedf62b90518b76f02adb2565cde2c7395e5df;hpb=ab8f276ae1a7c24ba145764144be8f87870282ac;p=git-wiki.git
diff --git a/pep-git.txt b/pep-git.txt
index 4cbedf6..402dac8 100644
--- a/pep-git.txt
+++ b/pep-git.txt
@@ -62,7 +62,7 @@ many different languages. Download Russian translation from `GArik
Offline documentation
---------------------
-Git has builtin help: run ``git help TOPIC``. For example, run
+Git has builtin help: run ``git help $TOPIC``. For example, run
``git help git`` or ``git help help``.
@@ -85,9 +85,8 @@ MacOS X: use git installed with `XCode
`_ or
install git with `Homebrew `_: ``brew install git``.
-`git-cola `_ is a sleek and
-powerful Git GUI written in Python and GPL licensed. Linux, Windows,
-MacOS X.
+`git-cola `_ is a Git GUI
+written in Python and GPL licensed. Linux, Windows, MacOS X.
`TortoiseGit `_ is a Windows Shell Interface
to Git based on TortoiseSVN; open source.
@@ -120,11 +119,11 @@ done something like that::
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
+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 be achieved with commands::
@@ -132,9 +131,9 @@ The same result can be achieved with commands::
$ 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
@@ -143,90 +142,87 @@ Branches and branches
Git terminology can be a bit misleading. Take, for example, the term
"branch". In git it has two meanings. A branch is a directed line of
commits (possibly with merges). And a branch is a label or a pointer
-assigned to a line of commits. It is important to differentiate when
-you talk about commits and when about their labels. Lines of commits
-are by itself unnamed and are usually only lengthening and merging.
+assigned to a line of commits. It is important to distinguish when you
+talk about commits and when about their labels. Lines of commits are
+by itself unnamed and are usually only lengthening and merging.
Labels, on the other hand, can be created, moved, renamed and deleted
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
-remote repository can be on your local disk, but it's still remote
-because it's not the current repo).
+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``.
-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``.
-
-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
::
- $ git fetch REMOTE BRANCH
+ $ git fetch $REMOTE $BRANCH
and
::
- $ git fetch REMOTE BRANCH:BRANCH
+ $ git fetch $REMOTE $BRANCH:$BRANCH
-The first command fetches commits from the named BRANCH in the REMOTE
-repository that are not in your repository and leaves the id (the
-hash) of the head commit in file .git/FETCH_HEAD. But it doesn't
-update any branch (doesn't move any pointer).
+The first command fetches commits from the named $BRANCH in the
+$REMOTE repository that are not in your repository and leaves the id
+(the hash) of the head commit in file .git/FETCH_HEAD and updates
+remote-tracking branch.
-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.
+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-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 pull REMOTE BRANCH
+ $ git pull $REMOTE $BRANCH
is equivalent to
::
- $ git fetch REMOTE BRANCH
- $ git merge FETCH_HEAD # FETCH_HEAD is a literal here
+ $ git fetch $REMOTE $BRANCH
+ $ git merge FETCH_HEAD
-Certainly, BRANCH in that case should be your current branch. If you
+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::
@@ -262,6 +258,10 @@ or even
$ git pull
+Default remote repository for fetching/pulling is origin. Default set
+of references to fetch is calculated using matching algorithm: git
+fetches all branches having the same name on both ends.
+
Push
''''
@@ -272,17 +272,16 @@ run
$ git push origin v1 v2
-git guesses (knowing upstream remote branches) that you really want
-
-::
+git pushes local v1 to remote v1 and local v2 to remote v2. The same
+as::
$ 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
@@ -301,6 +300,21 @@ or even
$ git push
+Default remote repository for pushing is origin. Default set
+of references to push in git before 2.0 is calculated using matching
+algorithm: git pushes all branches having the same name on both ends.
+Default set of references to push in git 2.0+ is calculated using
+simple algorithm: git pushes the current branch back to its
+@{upstream}.
+
+To configure git before 2.0 to the new behaviour run::
+
+$ git config push.default simple
+
+To configure git 2.0+ to the old behaviour run::
+
+$ git config push.default matching
+
Git refuses to push a branch if it's the current branch in the remote
non-bare repository: git refuses to update remote working directory.
You really should push only to bare repositories. For non-bare
@@ -320,7 +334,7 @@ during fetch/pull. To fetch all tags (and commits they point to) run
``git fetch --tags origin``. To fetch some specific tags fetch them
explicitly::
- $ git fetch origin tag TAG1 tag TAG2...
+ $ git fetch origin tag $TAG1 tag $TAG2...
For example::
@@ -333,7 +347,8 @@ pushed). To push tags list them explicitly::
$ git push origin tag 1.4.2
$ git push origin v1 v2 tag 2.1.7
-Don't move tags with ``git tag -f`` after they have been published.
+Don't move tags with ``git tag -f`` or remove tags with ``git tag -d``
+after they have been published.
Commit editing and caveats
@@ -346,14 +361,14 @@ It is possible to recover from forced push but it's PITA for the
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
@@ -382,24 +397,60 @@ Undo
====
Whatever you do, don't panic. Almost anything in git can be undone.
+
+git checkout: restore file's content
+------------------------------------
+
``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;
+The commands restores the contents of README file to the last but one
+commit in the current branch. By default the commit ID is simply 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 revert,
-git reflog. "Commit early, commit often".
+git reset: remove (non-pushed) commits
+--------------------------------------
+
+``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
+`_ the
+difference very clearly. Bare repositories don't have indices or
+working trees so in a bare repo only soft reset is possible.
+
+Unstaging
+'''''''''
+
+Mixed mode reset with a path or paths can be used to unstage changes -
+that is, to remove from index changes added with ``git add`` for
+committing. See `The Book
+`_ for details
+about unstaging and other undo tricks.
+
+git reflog: reference log
+-------------------------
+
+git revert: revert a commit
+---------------------------
How to undo a merge
https://www.kernel.org/pub/software/scm/git/docs/howto/revert-a-faulty-merge.html
+One thing that cannot be undone
+-------------------------------
+
+"Commit early, commit often".
+
Merge or rebase?
================
@@ -418,11 +469,11 @@ 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
+ $ git config branch.$NAME.rebase true
For example::
@@ -463,7 +514,7 @@ feature was implemented should be in the commit messages.
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
@@ -504,8 +555,11 @@ 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
+
Tips and tricks
===============