PEP: XXX
-Title: git
+Title: Collecting information about git
Version: $Revision$
Last-Modified: $Date$
Author: Oleg Broytman <phd@phdru.name>
Abstract
========
+This Informational PEP collects information about git. There is, of
+course, a lot of documentation for git, so the PEP concentrates on
+more complex issues, topics and scenarios.
+
+The plan is to extend the PEP in the future collecting information
+about equivalence of Mercurial and git scenarios to help migrating
+Python development from Mercurial to git.
+
+The author of the PEP doesn't currently plan to write a Process PEP on
+migration from Mercurial to git.
+
+
+Documentation
+=============
+
+Git is accompanied with a lot of documentation, both online and
+offline.
+
+Documentation for starters
+--------------------------
+
+Git Tutorial: `part 1
+<https://www.kernel.org/pub/software/scm/git/docs/gittutorial.html>`_,
+`part 2
+<https://www.kernel.org/pub/software/scm/git/docs/gittutorial-2.html>`_.
+
+`Git User's manual
+<https://www.kernel.org/pub/software/scm/git/docs/user-manual.html>`_.
+`Everyday GIT With 20 Commands Or So
+<https://www.kernel.org/pub/software/scm/git/docs/everyday.html>`_.
+`Git workflows
+<https://www.kernel.org/pub/software/scm/git/docs/gitworkflows.html>`_.
+
+`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
+<https://github.com/GArik/progit/wiki>`_.
+
+`Git Wiki <https://git.wiki.kernel.org/index.php/Main_Page>`_.
+
+Offline documentation
+---------------------
+
+Git has builtin help: run ``git help TOPIC``. For example, run
+``git help git`` or ``git help help``.
+
+
+Quick start
+===========
+
+Download and installation
+-------------------------
+
+Unix users: download and install using your package manager.
+
+Microsoft Windows: download `git-for-windows
+<https://git-for-windows.github.io/>`_.
+
+MacOS X: use git installed with `XCode
+<https://developer.apple.com/xcode/downloads/>`_ or download
+`git-osx-installer
+<http://sourceforge.net/projects/git-osx-installer/files/>`_.
+
+Initial configuration
+---------------------
+
+This simple code is often appears in documentation, but it is
+important so let repeat it here::
+
+ $ git config --global user.name "User Name"
+ $ git config --global user.email user.name@example.org
+
+Put your real name and preferred email.
+
+
+Examples in this PEP
+====================
+
+Examples of git commands in this PEP use the following approach. It is
+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::
+
+ $ git clone -b v1 http://git.python.org/python.git
+ $ cd python
+ $ git fetch origin v2:v2
+ $ git checkout -b v2
+
+
+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 chain of
+commits (possible 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. Chains of commits
+are unnamed and are usually only lengthening. Labels, on the other
+hand, can be created, moved, renamed and deleted freely.
+
+
+Remote repository and remote branches
+=====================================
+
+Another example of misleading terminology. A remote repository is
+really remote, you access it 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 branches, on the other hand, are branches (pointers to commits)
+in your local repository. They are there for git 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).
+
+To see the status of remote branches::
+
+ $ git branch -rv
+
+To see local and remote branches (and tags) pointing to commits run::
+
+ $ 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.
+
+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 and checks out branch
+``v1`` into the working directory.
+
+
+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.
+
+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::
+
+ $ 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::
+
+ $ git log @{u}..
+ $ git log v1@{u}..v1
+
+To see the status of all branches::
+
+ $ git branch -avv
+
+To compare the status of local branches with a remote repo::
+
+ $ git remote show origin
+
+Read `how to recover from upstream rebase
+<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
+safely edit, remove, reorder, combine and split commits that hasn'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 has
+already been pushed. Not a problem until commits are in a public
+repository.
+
+
+Undo
+====
+
+TODO: describe undo strategies: git reset, git revert, git checkout,
+git reflog. "Commit early, commit often".
+
+How to undo a merge
+https://kernel.org/pub/software/scm/git/docs/howto/revert-a-faulty-merge.html
+
+
+Advanced topics
+===============
+
+Staging area
+------------
+
+Staging area aka index is a distinguishing feature of git. See
+`WhatIsTheIndex
+<https://git.wiki.kernel.org/index.php/WhatIsTheIndex>`_ and
+`IndexCommandQuickref
+<https://git.wiki.kernel.org/index.php/IndexCommandQuickref>`_ in Git
+Wiki.
+
+
+Advanced configuration
+======================
+
+Line endings
+------------
+
+Git has builtin mechanisms to handle line endings.
+
+TODO: describe crlf configuration and .gitattributes.
+
+
+Null-merges
+===========
+
+Git has a builtin strategy for what Python core developers call
+"null-merge"::
+
+ $ git merge -s ours v1 # null-merge v1 into v2
+
+
+Database maintenance
+====================
+
+TODO: dangling objects, git gc, git repack.
+
+
+From Mercurial to git
+=====================
+
+Mercurial for Git users https://mercurial.selenic.com/wiki/GitConcepts
+
+https://github.com/felipec/git-remote-hg
+
+https://hg-git.github.io/
+
References
==========
+.. []
+
Copyright
=========
projects / git-wiki.git / blobdiff