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