Documentation/tutorial.txt

   1 A tutorial introduction to git
   2 ==============================
   3
   4 This tutorial explains how to import a new project into git, make
   5 changes to it, and share changes with other developers.
   6
   7 First, note that you can get documentation for a command such as "git
   8 diff" with:
   9
  10 ------------------------------------------------
  11 $ man git-diff
  12 ------------------------------------------------
  13
  14 Importing a new project
  15 -----------------------
  16
  17 Assume you have a tarball project.tar.gz with your initial work.  You
  18 can place it under git revision control as follows.
  19
  20 ------------------------------------------------
  21 $ tar xzf project.tar.gz
  22 $ cd project
  23 $ git init-db
  24 ------------------------------------------------
  25
  26 Git will reply
  27
  28 ------------------------------------------------
  29 defaulting to local storage area
  30 ------------------------------------------------
  31
  32 You've now initialized the working directory--you may notice a new
  33 directory created, named ".git".  Tell git that you want it to track
  34 every file under the current directory with
  35
  36 ------------------------------------------------
  37 $ git add .
  38 ------------------------------------------------
  39
  40 Finally,
  41
  42 ------------------------------------------------
  43 $ git commit -a
  44 ------------------------------------------------
  45
  46 will prompt you for a commit message, then record the current state
  47 of all the files to the repository.
  48
  49 Try modifying some files, then run
  50
  51 ------------------------------------------------
  52 $ git diff
  53 ------------------------------------------------
  54
  55 to review your changes.  When you're done,
  56
  57 ------------------------------------------------
  58 $ git commit -a
  59 ------------------------------------------------
  60
  61 will again prompt your for a message describing the change, and then
  62 record the new versions of the modified files.
  63
  64 A note on commit messages: Though not required, it's a good idea to
  65 begin the commit message with a single short (less than 50 character)
  66 line summarizing the change, followed by a blank line and then a more
  67 thorough description.  Tools that turn commits into email, for
  68 example, use the first line on the Subject line and the rest of the
  69 commit in the body.
  70
  71 To add a new file, first create the file, then
  72
  73 ------------------------------------------------
  74 $ git add path/to/new/file
  75 ------------------------------------------------
  76
  77 then commit as usual.  No special command is required when removing a
  78 file; just remove it, then commit.
  79
  80 At any point you can view the history of your changes using
  81
  82 ------------------------------------------------
  83 $ git whatchanged
  84 ------------------------------------------------
  85
  86 If you also want to see complete diffs at each step, use
  87
  88 ------------------------------------------------
  89 $ git whatchanged -p
  90 ------------------------------------------------
  91
  92 Managing branches
  93 -----------------
  94
  95 A single git repository can maintain multiple branches of
  96 development.  To create a new branch named "experimental", use
  97
  98 ------------------------------------------------
  99 $ git branch experimental
 100 ------------------------------------------------
 101
 102 If you now run
 103
 104 ------------------------------------------------
 105 $ git branch
 106 ------------------------------------------------
 107
 108 you'll get a list of all existing branches:
 109
 110 ------------------------------------------------
 111   experimental
 112 * master
 113 ------------------------------------------------
 114
 115 The "experimental" branch is the one you just created, and the
 116 "master" branch is a default branch that was created for you
 117 automatically.  The asterisk marks the branch you are currently on;
 118 type
 119
 120 ------------------------------------------------
 121 $ git checkout experimental
 122 ------------------------------------------------
 123
 124 to switch to the experimental branch.  Now edit a file, commit the
 125 change, and switch back to the master branch:
 126
 127 ------------------------------------------------
 128 (edit file)
 129 $ git commit -a
 130 $ git checkout master
 131 ------------------------------------------------
 132
 133 Check that the change you made is no longer visible, since it was
 134 made on the experimental branch and you're back on the master branch.
 135
 136 You can make a different change on the master branch:
 137
 138 ------------------------------------------------
 139 (edit file)
 140 $ git commit -a
 141 ------------------------------------------------
 142
 143 at this point the two branches have diverged, with different changes
 144 made in each.  To merge the changes made in the two branches, run
 145
 146 ------------------------------------------------
 147 $ git pull . experimental
 148 ------------------------------------------------
 149
 150 If the changes don't conflict, you're done.  If there are conflicts,
 151 markers will be left in the problematic files showing the conflict;
 152
 153 ------------------------------------------------
 154 $ git diff
 155 ------------------------------------------------
 156
 157 will show this.  Once you've edited the files to resolve the
 158 conflicts,
 159
 160 ------------------------------------------------
 161 $ git commit -a
 162 ------------------------------------------------
 163
 164 will commit the result of the merge. Finally,
 165
 166 ------------------------------------------------
 167 $ gitk
 168 ------------------------------------------------
 169
 170 will show a nice graphical representation of the resulting history.
 171
 172 If you develop on a branch crazy-idea, then regret it, you can always
 173 delete the branch with
 174
 175 -------------------------------------
 176 $ git branch -D crazy-idea
 177 -------------------------------------
 178
 179 Branches are cheap and easy, so this is a good way to try something
 180 out.
 181
 182 Using git for collaboration
 183 ---------------------------
 184
 185 Suppose that Alice has started a new project with a git repository in
 186 /home/alice/project, and that Bob, who has a home directory on the
 187 same machine, wants to contribute.
 188
 189 Bob begins with:
 190
 191 ------------------------------------------------
 192 $ git clone /home/alice/project myrepo
 193 ------------------------------------------------
 194
 195 This creates a new directory "myrepo" containing a clone of Alice's
 196 repository.  The clone is on an equal footing with the original
 197 project, posessing its own copy of the original project's history.
 198
 199 Bob then makes some changes and commits them:
 200
 201 ------------------------------------------------
 202 (edit files)
 203 $ git commit -a
 204 (repeat as necessary)
 205 ------------------------------------------------
 206
 207 When he's ready, he tells Alice to pull changes from the repository
 208 at /home/bob/myrepo.  She does this with:
 209
 210 ------------------------------------------------
 211 $ cd /home/alice/project
 212 $ git pull /home/bob/myrepo
 213 ------------------------------------------------
 214
 215 This actually pulls changes from the branch in Bob's repository named
 216 "master".  Alice could request a different branch by adding the name
 217 of the branch to the end of the git pull command line.
 218
 219 This merges Bob's changes into her repository; "git whatchanged" will
 220 now show the new commits.  If Alice has made her own changes in the
 221 meantime, then Bob's changes will be merged in, and she will need to
 222 manually fix any conflicts.
 223
 224 A more cautious Alice might wish to examine Bob's changes before
 225 pulling them.  She can do this by creating a temporary branch just
 226 for the purpose of studying Bob's changes:
 227
 228 -------------------------------------
 229 $ git fetch /home/bob/myrepo master:bob-incoming
 230 -------------------------------------
 231
 232 which fetches the changes from Bob's master branch into a new branch
 233 named bob-incoming.  (Unlike git pull, git fetch just fetches a copy
 234 of Bob's line of development without doing any merging).  Then
 235
 236 -------------------------------------
 237 $ git whatchanged -p master..bob-incoming
 238 -------------------------------------
 239
 240 shows a list of all the changes that Bob made since he branched from
 241 Alice's master branch.
 242
 243 After examing those changes, and possibly fixing things, Alice can
 244 pull the changes into her master branch:
 245
 246 -------------------------------------
 247 $ git checkout master
 248 $ git pull . bob-incoming
 249 -------------------------------------
 250
 251 The last command is a pull from the "bob-incoming" branch in Alice's
 252 own repository.
 253
 254 Later, Bob can update his repo with Alice's latest changes using
 255
 256 -------------------------------------
 257 $ git pull
 258 -------------------------------------
 259
 260 Note that he doesn't need to give the path to Alice's repository;
 261 when Bob cloned Alice's repository, git stored the location of her
 262 repository in the file .git/remotes/origin, and that location is used
 263 as the default for pulls.
 264
 265 Bob may also notice a branch in his repository that he didn't create:
 266
 267 -------------------------------------
 268 $ git branch
 269 * master
 270   origin
 271 -------------------------------------
 272
 273 The "origin" branch, which was created automatically by "git clone",
 274 is a pristine copy of Alice's master branch; Bob should never commit
 275 to it.
 276
 277 If Bob later decides to work from a different host, he can still
 278 perform clones and pulls using the ssh protocol:
 279
 280 -------------------------------------
 281 $ git clone alice.org:/home/alice/project myrepo
 282 -------------------------------------
 283
 284 Alternatively, git has a native protocol, or can use rsync or http;
 285 see gitlink:git-pull[1] for details.
 286
 287 Git can also be used in a CVS-like mode, with a central repository
 288 that various users push changes to; see gitlink:git-push[1] and
 289 link:cvs-migration.html[git for CVS users].
 290
 291 Keeping track of history
 292 ------------------------
 293
 294 Git history is represented as a series of interrelated commits.  The
 295 most recent commit in the currently checked-out branch can always be
 296 referred to as HEAD, and the "parent" of any commit can always be
 297 referred to by appending a caret, "^", to the end of the name of the
 298 commit.  So, for example,
 299
 300 -------------------------------------
 301 git diff HEAD^ HEAD
 302 -------------------------------------
 303
 304 shows the difference between the most-recently checked-in state of
 305 the tree and the previous state, and
 306
 307 -------------------------------------
 308 git diff HEAD^^ HEAD^
 309 -------------------------------------
 310
 311 shows the difference between that previous state and the state two
 312 commits ago.  Also, HEAD~5 can be used as a shorthand for HEAD{caret}{caret}{caret}{caret}{caret},
 313 and more generally HEAD~n can refer to the nth previous commit.
 314 Commits representing merges have more than one parent, and you can
 315 specify which parent to follow in that case; see
 316 gitlink:git-rev-parse[1].
 317
 318 The name of a branch can also be used to refer to the most recent
 319 commit on that branch; so you can also say things like
 320
 321 -------------------------------------
 322 git diff HEAD experimental
 323 -------------------------------------
 324
 325 to see the difference between the most-recently committed tree in
 326 the current branch and the most-recently committed tree in the
 327 experimental branch.
 328
 329 But you may find it more useful to see the list of commits made in
 330 the experimental branch but not in the current branch, and
 331
 332 -------------------------------------
 333 git whatchanged HEAD..experimental
 334 -------------------------------------
 335
 336 will do that, just as
 337
 338 -------------------------------------
 339 git whatchanged experimental..HEAD
 340 -------------------------------------
 341
 342 will show the list of commits made on the HEAD but not included in
 343 experimental.
 344
 345 You can also give commits convenient names of your own: after running
 346
 347 -------------------------------------
 348 $ git-tag v2.5 HEAD^^
 349 -------------------------------------
 350
 351 you can refer to HEAD^^ by the name "v2.5".  If you intend to share
 352 this name with other people (for example, to identify a release
 353 version), you should create a "tag" object, and perhaps sign it; see
 354 gitlink:git-tag[1] for details.
 355
 356 You can revisit the old state of a tree, and make further
 357 modifications if you wish, using git branch: the command
 358
 359 -------------------------------------
 360 $ git branch stable-release v2.5
 361 -------------------------------------
 362
 363 will create a new branch named "stable-release" starting from the
 364 commit which you tagged with the name v2.5.
 365
 366 You can reset the state of any branch to an earlier commit at any
 367 time with
 368
 369 -------------------------------------
 370 $ git reset --hard v2.5
 371 -------------------------------------
 372
 373 This will remove all later commits from this branch and reset the
 374 working tree to the state it had when the given commit was made.  If
 375 this branch is the only branch containing the later commits, those
 376 later changes will be lost.  Don't use "git reset" on a
 377 publicly-visible branch that other developers pull from, as git will
 378 be confused by history that disappears in this way.
 379
 380 Next Steps
 381 ----------
 382
 383 Some good commands to explore next:
 384
 385   * gitlink:git-diff[1]: This flexible command does much more than
 386     we've seen in the few examples above.
 387
 388   * gitlink:git-format-patch[1], gitlink:git-am[1]: These convert
 389     series of git commits into emailed patches, and vice versa,
 390     useful for projects such as the linux kernel which rely heavily
 391     on emailed patches.
 392
 393   * gitlink:git-bisect[1]: When there is a regression in your
 394     project, one way to track down the bug is by searching through
 395     the history to find the exact commit that's to blame.  Git bisect
 396     can help you perform a binary search for that commit.  It is
 397     smart enough to perform a close-to-optimal search even in the
 398     case of complex non-linear history with lots of merged branches.
 399
 400 Other good starting points include link:everyday.html[Everday GIT
 401 with 20 Commands Or So] and link:cvs-migration.html[git for CVS
 402 users].  Also, link:core-tutorial.html[A short git tutorial] gives an
 403 introduction to lower-level git commands for advanced users and
 404 developers.