pep-git.txt

   1 PEP: XXX
   2 Title: Collecting information about git
   3 Version: $Revision$
   4 Last-Modified: $Date$
   5 Author: Oleg Broytman <phd@phdru.name>
   6 Status: Active
   7 Type: Informational
   8 Content-Type: text/x-rst
   9 Created: 01-Jun-2015
  10 Post-History:
  11
  12 Abstract
  13 ========
  14
  15 This Informational PEP collects information about git. There is, of
  16 course, a lot of documentation for git, so the PEP concentrates on
  17 more complex issues, topics and scenarios.
  18
  19 The plan is to extend the PEP in the future collecting information
  20 about equivalence of Mercurial and git scenarios to help migrating
  21 Python development from Mercurial to git.
  22
  23 The author of the PEP doesn't currently plan to write a Process PEP on
  24 migration from Mercurial to git.
  25
  26
  27 Documentation
  28 =============
  29
  30 Git is accompanied with a lot of documentation, both online and
  31 offline.
  32
  33 Documentation for starters
  34 --------------------------
  35
  36 Git Tutorial: `part 1
  37 <https://www.kernel.org/pub/software/scm/git/docs/gittutorial.html>`_,
  38 `part 2
  39 <https://www.kernel.org/pub/software/scm/git/docs/gittutorial-2.html>`_.
  40
  41 `Git User's manual
  42 <https://www.kernel.org/pub/software/scm/git/docs/user-manual.html>`_.
  43 `Everyday GIT With 20 Commands Or So
  44 <https://www.kernel.org/pub/software/scm/git/docs/everyday.html>`_.
  45 `Git workflows
  46 <https://www.kernel.org/pub/software/scm/git/docs/gitworkflows.html>`_.
  47
  48 `Git Magic
  49 <http://www-cs-students.stanford.edu/~blynn/gitmagic/index.html>`_,
  50 also with a number of translations.
  51
  52 Advanced documentation
  53 ----------------------
  54
  55 `Pro Git <https://git-scm.com/book>`_. The Book about git. Buy it at
  56 Amazon or download in PDF, mobi, or ePub form. Has translations to
  57 many different languages. Download Russian translation from `GArik
  58 <https://github.com/GArik/progit/wiki>`_.
  59
  60 `Git Wiki <https://git.wiki.kernel.org/index.php/Main_Page>`_.
  61
  62 Offline documentation
  63 ---------------------
  64
  65 Git has builtin help: run ``git help TOPIC``. For example, run
  66 ``git help git`` or ``git help help``.
  67
  68
  69 Quick start
  70 ===========
  71
  72 Download and installation
  73 -------------------------
  74
  75 Unix users: download and install using your package manager.
  76
  77 Microsoft Windows: download `git-for-windows
  78 <https://git-for-windows.github.io/>`_.
  79
  80 MacOS X: use git installed with `XCode
  81 <https://developer.apple.com/xcode/downloads/>`_ or download
  82 `git-osx-installer
  83 <http://sourceforge.net/projects/git-osx-installer/files/>`_.
  84
  85 Initial configuration
  86 ---------------------
  87
  88 This simple code is often appears in documentation, but it is
  89 important so let repeat it here::
  90
  91     $ git config --global user.name "User Name"
  92     $ git config --global user.email user.name@example.org
  93
  94
  95 Examples in this PEP
  96 ====================
  97
  98 Examples of git commands in this PEP use the following approach. It is
  99 supposed that you, the user, works with a local repository named
 100 ``python`` that has an upstream remote repo named ``origin``. Your
 101 local repo has two branches ``v1`` and ``v2``. Usually the currently
 102 checked out branch is ``v2``.
 103
 104
 105 Commit editing and caveats
 106 ==========================
 107
 108 A warning not to edit published (pushed) commits also appears in
 109 documentation but it's also repeated here as it's very important.
 110
 111 It is possible to recover from forced push but it's PITA for the
 112 entire team. Please avoid it.
 113
 114 To see what commits have not been published yet see the head of the
 115 remote branch::
 116
 117     $ git log origin/v2..
 118
 119 For every branch that has an upstream remote branch git maintains an
 120 alias @{upstream} (short version @{u})::
 121
 122     $ git log @{u}..
 123     $ git log v1@{u}..v1
 124
 125 To see the status of all branches::
 126
 127     $ git branch -avv
 128
 129 Read `how to recover from upstream rebase
 130 <https://git-scm.com/docs/git-rebase#_recovering_from_upstream_rebase>`_.
 131 It is in ``git help rebase``.
 132
 133 On the other hand don't be too afraid about commit editing. You can
 134 safely edit commits that hasn't been pushed yet. You can even push
 135 commits to your own (backup) repo, edit them later and force-push
 136 edited commits to replace what has already been pushed.
 137
 138
 139 References
 140 ==========
 141
 142 .. []
 143
 144
 145 Copyright
 146 =========
 147
 148 This document has been placed in the public domain.
 149
 150
 151 \f
 152 ..
 153    Local Variables:
 154    mode: indented-text
 155    indent-tabs-mode: nil
 156    sentence-end-double-space: t
 157    fill-column: 70
 158    coding: utf-8
 159    End:
 160    vim: set fenc=us-ascii tw=70 :