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 Put your real name and preferred email.
  95
  96
  97 Examples in this PEP
  98 ====================
  99
 100 Examples of git commands in this PEP use the following approach. It is
 101 supposed that you, the user, works with a local repository named
 102 ``python`` that has an upstream remote repo named ``origin``. Your
 103 local repo has two branches ``v1`` and ``v2``. For most examples the
 104 currently checked out branch is ``v2``. That is, it's assumed you did
 105 something like that::
 106
 107     $ git clone -b v1 http://git.python.org/python.git
 108     $ cd python
 109     $ git fetch origin v2:v2
 110     $ git checkout -b v2
 111
 112
 113 Remote repository and remote branches
 114 =====================================
 115
 116 Git terminology can be a bit misleading. Take, for example, terms
 117 "remote repository" and "remote branches". A remote repository is
 118 really remote, you access it via network (well, a remote repository
 119 can be on your local disk, but it's still remote because it's not the
 120 current repo).
 121
 122 Remote branches, on the other hand, are pointers to commits in your
 123 local repository. They are there for git to remember what branches and
 124 commits have been pushed from and pulled to what remote repos (you can
 125 pull from and push to many remotes).
 126
 127 To see the status of remote branches::
 128
 129     $ git branch -rv
 130
 131 To see local and remote branches (and tags) pointing to commits run::
 132
 133     $ git log --decorate
 134
 135 You never do your own development on remote branches. You create a
 136 local branch that has a remote branch as an upstream and do
 137 development on that local branch. On push git updates remote branches,
 138 and on pull git updates remote branches and fast-forwards, merges or
 139 rebases local branches.
 140
 141 When you do an initial clone like this::
 142
 143     $ git clone -b v1 http://git.python.org/python.git
 144
 145 git clones remote repository ``http://git.python.org/python.git`` to
 146 directory ``python``, creates remote branches and checks out branch
 147 ``v1`` into the working directory.
 148
 149
 150 Commit editing and caveats
 151 ==========================
 152
 153 A warning not to edit published (pushed) commits also appears in
 154 documentation but it's also repeated here as it's very important.
 155
 156 It is possible to recover from forced push but it's PITA for the
 157 entire team. Please avoid it.
 158
 159 To see what commits have not been published yet compare the head of the
 160 branch with its upstream remote branch::
 161
 162     $ git log origin/v2..
 163     $ git log origin/v1..v1
 164
 165 For every branch that has an upstream remote branch git maintains an
 166 alias @{upstream} (short version @{u}), so the commands above can be
 167 given as::
 168
 169     $ git log @{u}..
 170     $ git log v1@{u}..v1
 171
 172 To see the status of all branches::
 173
 174     $ git branch -avv
 175
 176 To compare the status of local branches with a remote repo::
 177
 178     $ git remote show origin
 179
 180 Read `how to recover from upstream rebase
 181 <https://git-scm.com/docs/git-rebase#_recovering_from_upstream_rebase>`_.
 182 It is in ``git help rebase``.
 183
 184 On the other hand don't be too afraid about commit editing. You can
 185 safely edit, remove, reorder, combine and split commits that hasn't
 186 been pushed yet. You can even push commits to your own (backup) repo,
 187 edit them later and force-push edited commits to replace what has
 188 already been pushed. Not a problem until commits are in a public
 189 repository.
 190
 191
 192 References
 193 ==========
 194
 195 .. []
 196
 197
 198 Copyright
 199 =========
 200
 201 This document has been placed in the public domain.
 202
 203
 204 \f
 205 ..
 206    Local Variables:
 207    mode: indented-text
 208    indent-tabs-mode: nil
 209    sentence-end-double-space: t
 210    fill-column: 70
 211    coding: utf-8
 212    End:
 213    vim: set fenc=us-ascii tw=70 :