Unix users: download and install using your package manager.
Microsoft Windows: download `git-for-windows
-<https://git-for-windows.github.io/>`_.
+<https://github.com/git-for-windows/git/releases>`_.
MacOS X: use git installed with `XCode
<https://developer.apple.com/xcode/downloads/>`_ or download
This simple code is often appears in documentation, but it is
important so let repeat it here. Git marks every commit with author
-and commiter names/emails, so configure your real name and preferred
+and committer names/emails, so configure your real name and preferred
email::
$ git config --global user.name "User Name"
supposed that you, the user, works with a local repository named
``python`` that has an upstream remote repo named ``origin``. Your
local repo has two branches ``v1`` and ``v2``. For most examples the
-currently checked out branch is ``v2``. That is, it's assumed you did
-something like that::
+currently checked out branch is ``v2``. That is, it's assumed you have
+done something like that::
$ git clone -b v1 http://git.python.org/python.git
$ cd python
$ git log --decorate
You never do your own development on remote branches. You create a
-local branch that has a remote branch as an 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.
+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.
When you do an initial clone like this::
directory ``python``, creates remote branches and checks out branch
``v1`` into the working directory.
+Updating local and remote branches
+----------------------------------
+
+There is a major difference between
+
+::
+
+ $ git fetch REMOTE BRANCH
+
+and
+
+::
+
+ $ 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 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 first command is used internally by ``git pull``.
+
+::
+
+ $ git pull REMOTE BRANCH
+
+is equivalent to
+
+::
+
+ $ git fetch REMOTE BRANCH
+ $ 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 merge v1
+
+It is possible to configure git to make it fetch/pull a few branches
+or all branches at once, so you can simply run
+
+::
+
+ $ git pull origin
+
+or even
+
+::
+
+ $ git pull
+
+Push
+''''
+
+Pushing is a bit simpler. There is only one command ``push``. When you
+run
+
+::
+
+ $ git push origin v1 v2
+
+git guesses (knowing upstream remote branches) that you really want
+
+::
+
+ $ 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,
+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
+editing and caveats`_ below.
+
+It is possible to configure git to make it push a few branches or all
+branches at once, so you can simply run
+
+::
+
+ $ git push origin
+
+or even
+
+::
+
+ $ git push
+
+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
+repositories git prefers pull-based workflow.
+
+Tags
+''''
+
+Git automatically fetches tags that point to commits being fetched
+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 NAME1 tag NAME2...
+
+For example::
+
+ $ git fetch origin tag 1.4.2 tag 2.1.7
+
+Git doesn't automatically pushes tags. That allows you to have private
+tags (lightweight tags are also private for a repo, they cannot be
+pushed). To push tag(s) list them explicitly::
+
+ $ git push origin tag 1.4.2
+ $ git push origin v1 v2 tag 2.1.7
+
Commit editing and caveats
==========================
A warning not to edit published (pushed) commits also appears in
-documentation but it's also repeated here as it's very important.
+documentation but it's repeated here anyway as it's very important.
It is possible to recover from forced push but it's PITA for the
entire team. Please avoid it.
been pushed yet. You can even push commits to your own (backup) repo,
edit them later and force-push edited commits to replace what has
already been pushed. Not a problem until commits are in a public
-repository.
+or shared repository.
Undo
Wiki.
-Advanced configuration
-======================
-
-Line endings
-------------
-
-Git has builtin mechanisms to handle line endings.
-
-TODO: describe crlf configuration and .gitattributes.
+Merge or rebase?
+================
Null-merges
$ git merge -s ours v1 # null-merge v1 into v2
+ReReRe
+======
+
+https://git-scm.com/book/en/Git-Tools-Rerere
+
+
+Advanced configuration
+======================
+
+Line endings
+------------
+
+Git has builtin mechanisms to handle line endings.
+
+TODO: describe crlf configuration and .gitattributes.
+
+
Database maintenance
====================
projects / git-wiki.git / blobdiff