Documentation/devel/git-starting.itexi

   1 @c -*- coding: us-ascii; mode: texinfo; -*-
   2 @node Starting with git
   3 @chapter Starting with git
   4
   5 @menu
   6 * Getting the source code::
   7 * Updating the source code::
   8 * Sharing your changes::
   9 * Other interesting Git commands::
  10 * Git on Windows::
  11 @end menu
  12
  13
  14 @node Getting the source code
  15 @section Getting the source code
  16
  17 The source code is kept in a git respository.
  18
  19 @warning{These instructions assume that you are using the
  20 command-line version of git 1.5 or higher.}
  21
  22
  23 @menu
  24 * Main source code::
  25 * Website source code::
  26 * Documentation translations source code::
  27 * Other branches::
  28 * Git user configuration::
  29 @end menu
  30
  31 @node Main source code
  32 @subsection Main source code
  33
  34 To get the main source code and documentation,
  35
  36 FIXME: test this!!!
  37
  38 @example
  39 mkdir lilypond; cd lilypond
  40 git init-db
  41 git remote add -f -t master -m master origin git://git.sv.gnu.org/lilypond.git/
  42 git checkout -b master origin/master
  43 @end example
  44
  45
  46 @node Website source code
  47 @subsection Website source code
  48
  49 To get the website (including translations),
  50
  51 @example
  52 mkdir lilyweb ; cd lilyweb
  53 git init-db
  54 git remote add -f -t web -m web origin git://git.sv.gnu.org/lilypond.git/
  55 git checkout -b web origin/web
  56 @end example
  57
  58
  59 @node Documentation translations source code
  60 @subsection Documentation translations source code
  61
  62 To translate the documentation (@emph{not} the website),
  63
  64 FIXME: change
  65
  66 @example
  67 mkdir lilytranslate ; cd lilytranslate
  68 git init-db
  69 git remote add -f -t web -m web origin git://git.sv.gnu.org/lilypond.git/
  70 git checkout -b web origin/web
  71 @end example
  72
  73
  74 @menu
  75 * Other branches::
  76 * Git user configuration::
  77 @end menu
  78
  79 @node Other branches
  80 @subsection Other branches
  81
  82 Most contributors will never need to touch the other branches.  If
  83 you wish to do so, you will need more familiarity with git.
  84
  85 @itemize
  86
  87 @item @code{gub}:
  88 This stores the Grand Unified Binary, our cross-platform building
  89 tool.
  90
  91 @example
  92 FIXME: insert new gub addy
  93 @end example
  94
  95 @item @code{dev/XYZ}:
  96 These branches are for individual developers.  They store code
  97 which is not yet stable enough to be added to the @code{master}
  98 branch.
  99
 100 @item @code{stable/XYZ}:
 101 The branches are kept for archival reasons.
 102
 103 @end itemize
 104
 105
 106 @node Git user configuration
 107 @subsection Git user configuration
 108
 109 To configure git to automatically use your name and email address
 110 for patches,
 111
 112 @example
 113 git config --global user.name "MYNAME"
 114 git config --global user.email myemail@@example.net
 115 @end example
 116
 117
 118 @node Updating the source code
 119 @section Updating the source code
 120
 121 @menu
 122 * Importance of updating::
 123 * Update command::
 124 * Resolving conflicts::
 125 * Technical notes::
 126 @end menu
 127
 128 @node Importance of updating
 129 @subsection Importance of updating
 130
 131 In a large project like LilyPond, contributors sometimes edit the
 132 same file at the same time.  As long as everybody updates their
 133 version of the file with the most recent changes (@qq{pull}ing),
 134 there are generally no problems with this multiple-person editing.
 135 However, serious problems can arise if you do not pull before
 136 attempting commit.
 137
 138 @node Update command
 139 @subsection Updating command
 140
 141 Whenever you are asked to pull, it means you should update your
 142 local copy of the repository with the changes made by others on
 143 the remote @code{git.sv.gnu.org} repository:
 144
 145 @example
 146 git pull origin
 147 @end example
 148
 149 @node Resolving conflicts
 150 @subsection Resolving conflicts
 151
 152 Occasionally an update may result in conflicts -- this happens
 153 when you and somebody else hae modified the same part of the same
 154 file and git cannot figure out how to merge the two versions
 155 together.  When this happens, you must manually merge the two
 156 versions.
 157
 158 @example
 159 TODO
 160 @end example
 161
 162
 163 @node Technical notes
 164 @subsection Technical notes
 165
 166 Let's explain a bit of Git vocabulary.  The @code{git pull
 167 origin} command is just a shortcut for this command:
 168
 169 @example
 170 git pull git://git.sv.gnu.org/lilypond.git/ MY-BRANCH:origin/MY-BRANCH
 171 @end example
 172
 173 A commit is a set of changes made to the sources; it also includes the
 174 committish of the parent commit, the name and e-mail of the author
 175 (the person who wrote the changes), the name and e-mail of the
 176 committer (the person who brings these changes into the git
 177 repository), and a commit message.
 178
 179 A committish is the SHA1 checksum of a commit, a number made of 40
 180 hexadecimal digits, which acts as the internal unique identifier for
 181 this commit.  To refer to a particular revision, don't use vague
 182 references like the (approximative) date, simply copy'n'paste the
 183 committish.
 184
 185 A branch is a tree (in the mathematical or computer science sense) of
 186 commits, and the topmost commit of this branch is called a head.
 187
 188 The "git fetch" command above has created a branch called origin/web
 189 in your local Git repository.  As this branch is a copy of the remote
 190 branch web from git.sv.gnu.org LilyPond repository, it is
 191 called a `remote branch', and is meant to track the changes on the
 192 branch from git.sv.gnu.org: it will be updated every time you run 'git
 193 pull' or 'git fetch' with this branch reference as argument, e.g.
 194 by using .git/remotes/web remote file when running 'git fetch web'.
 195
 196 The 'git checkout' command above has created a branch named 'web'.  At
 197 the beginning, this branch is identical to 'origin/web', but it will
 198 differ as soon as you make changes, e.g. adding newly translated
 199 pages.  Whenever you pull, you merge the changes from origin/web and
 200 your web branch since the last pulling.  If you do not have push
 201 (i.e. "write") access on git.sv.gnu.org, your web branch will always
 202 differ from origin/web.  In this case, remember that other people
 203 working like you on the remote web branch of
 204 git://git.sv.gnu.org/lilypond.git/ know nothing about your own web
 205 branch: this means that whenever you use a committish or make a patch,
 206 others expect you to take the lastest commit of origin/web branch as a
 207 reference.
 208
 209 This README tries to explain most of Git commands needed for
 210 translating the web site.  However, you are invited to read
 211 further documentation to make git more familiar to you; for
 212 instance, take a look at @uref{http://git.or.cz/gitwiki/},
 213 especially GitDocumentation and GitGlossary; a good alternative to
 214 reading the wiki is reading the first two chapters of Git User's
 215 Manual at
 216 @uref{http://www.kernel.org/pub/software/scm/git/docs/user-manual.html}
 217
 218
 219
 220
 221 @node Sharing your changes
 222 @section Sharing your changes
 223
 224
 225 @menu
 226 * Producing a patch::
 227 * Committing directly::
 228 @end menu
 229
 230 @node Producing a patch
 231 @subsection Producing a patch
 232
 233 Once you have finished editing your files, checked that your
 234 changes meet the @ref{Code style} and/or @ref{Documentation
 235 policy}, and checked that the entire thing compiles, you may
 236
 237 @example
 238 git commit -a
 239 git-format-patch HEAD
 240 @end example
 241
 242 Send an email to @email{lilypond-devel@@gnu.org} with the diff as
 243 an attachment.
 244
 245
 246 @node Committing directly
 247 @subsection Committing directly
 248
 249 Most contributors do not have permission to commit directly.  If
 250 you do, edit @file{.git/config} to contain
 251
 252 @example
 253 FIXME?
 254 @end example
 255
 256 You may then @code{git push}.
 257
 258
 259 @node Other interesting Git commands
 260 @section Other interesting Git commands
 261
 262 The commands above don't only bring you the latest version of the
 263 sources, but also the full history of revisions (revisons, also
 264 called commits, are changes made to the sources), stored in the
 265 .git directory.  You can browse this history with
 266
 267 @example
 268 git log     # only shows the logs (author, committish and commit message)
 269 git log -p  # also shows diffs
 270 gitk        # shows history graphically
 271 @end example
 272
 273
 274
 275
 276 @node Git on Windows
 277 @section Git on Windows
 278
 279
 280