X-Git-Url: https://git.cworth.org/git?a=blobdiff_plain;f=tour.mdwn;h=53f8f2ca8cc7e7fcec82c06c5a05a9eb1508c00c;hb=6c295b78cc0207247daba5594f62b6ead3dd94e8;hp=c511fab051c9e5d75d23316a5835dc749cfbcce9;hpb=5aef61cdf52d974653657dbeb41079555e4a868b;p=hgbook-git diff --git a/tour.mdwn b/tour.mdwn index c511fab..53f8f2c 100644 --- a/tour.mdwn +++ b/tour.mdwn @@ -39,13 +39,13 @@ or and can be [browsed online](http://git.cworth.org/git/hgbook-git) -### 2.1 Installing git on your system +### 2.1 Installing git on your system Prebuilt binary packages of git are available for many popular operating systems. These make it easy to start using git on your computer immediately. -#### 2.1.1 Linux +#### 2.1.1 Linux Because each Linux distribution has its own packaging tools, policies, and rate of development, it’s difficult to give a comprehensive set of @@ -80,7 +80,7 @@ with git, meaning GNU Interactive Tools). apt-get install git-core -#### 2.1.2 Mac OS X +#### 2.1.2 Mac OS X A git-core package is available through [macports](http://macports.org). Once macports is enabled, the command @@ -88,7 +88,7 @@ to install git is: port install git-core -#### 2.1.3 Windows +#### 2.1.3 Windows Git has long been available as part of cygwin, and works reasonably well in that environment. Some people find cygwin a particularly @@ -102,7 +102,7 @@ port of git, and WinGit, a package for installing just git itself without the development environment, (still in Alpha as of September 2007). -### 2.2 Getting started +### 2.2 Getting started To begin, we’ll use the “git version” command to find out whether git is actually installed properly. Versions 1.5 and newer of git are much @@ -113,7 +113,7 @@ upgrade. $ git version git version 1.5.3.2 -#### 2.2.1 Built-in help +#### 2.2.1 Built-in help Git provides a built-in help system. This is invaluable for those times when you find yourself stuck trying to remember how to run a @@ -135,7 +135,7 @@ present and just call out to "man git-"?] available for git-? And perhaps alos provide a "git -v help" similar to "hg -v help" for more?] -### 2.3 Working with a repository +### 2.3 Working with a repository In git, everything happens inside a repository. The repository for a project contains all of the files that “belong to” that project, @@ -146,13 +146,18 @@ a directory tree in your filesystem that git treats as special. You can rename or delete a repository any time you like, using either the command line or your file browser. -#### 2.3.1 Making a local copy of a repository +#### 2.3.1 Creating a local copy of a remote repository -Copying a repository is just a little bit special. While you could use -a normal file copying command to make a copy of a repository, it’s -best to use a built-in command that git provides. This command -is called “git clone”, because it creates an identical copy of an -existing repository. +As suggested, a repository can be copied through normal file-copying +commands. But git also provides a "git clone" tool for copying a +repository. This provides a means of copying a repository over the +network, and is also useful with a local repository since it is much +more efficient than creating a normal copy, (creating a local clones +is blazingly fast). + +We've assembled a simple repository that will be used in the examples +throughout this chapter. Go ahead and clone this repository now so +that you will be able to follow along: $ git clone git://cworth.org/git/hello Initialized empty Git repository in /tmp/hello/.git/ @@ -205,7 +210,7 @@ What this means for now is that we’re free to experiment with our repository, safe in the knowledge that it’s a private “sandbox” that won’t affect anyone else. -#### 2.3.2 What’s in a repository? +#### 2.3.2 What’s in a repository? When we take a more detailed look inside a repository, we can see that it contains a directory named .git. This is where git keeps all @@ -226,7 +231,7 @@ distinction is that the repository contains the history of your project, while the working directory contains a snapshot of your project at a particular point in history. -### 2.4 A tour through history +### 2.4 A tour through history One of the first things we might want to do with a new, unfamiliar repository is understand its history. The “git log” command gives us a @@ -289,7 +294,7 @@ The fields in a record of output from “git log” are as follows. The default output printed by “git log” is purely a summary; it is missing a lot of detail. -#### 2.4.1 Commits, revisions, and talking to other people +#### 2.4.1 Commits, revisions, and talking to other people As English is a notoriously sloppy language, and computer science has a hallowed history of terminological confusion (why use one term when @@ -339,9 +344,9 @@ in the current branch, "HEAD~", refers to the previous commit, and Another useful syntax is .. which can be used to specify a range of commits. So "origin..master" specifies everything that has been -committed to master since it derived from origin. +committed to master since it diverged from origin. -#### 2.4.3 Viewing specific revisions +#### 2.4.3 Viewing specific revisions You can use "git log" to explore the range syntax just introduced. For example, to see a list of the most recent 3 revisions you can use @@ -371,7 +376,7 @@ case): Besides filtering by commit identifiers, git allows you to easily filter the log output according to which files (or directories) are -modified by listing them after "--" wihch is necessary to distinguish +modified by listing them after "--" which is necessary to distinguish commit names from file names: $ git log -- Makefile @@ -392,10 +397,14 @@ created: $ git log --since="2 weeks ago" --until="yesterday" + [XXX: By default, "git log" displays author dates as "Date" + but then uses commit dates when given a --since option. That + seems like broken defaults to me. Why the inconsistency?] + Another useful option is -n or --max-count which, unsurprisingly, limits the maximum number of commits to be displayed. -#### 2.4.5 More detailed information +#### 2.4.5 More detailed information While the default information printed by “git log” is useful if you already know what you’re looking for, you may need to see more details @@ -480,7 +489,7 @@ same output: return 0; } -### 2.5 All about command options +### 2.5 All about command options Let’s take a brief break from exploring git commands to discuss a pattern in the way that they work; you may find this useful to keep @@ -511,7 +520,7 @@ systems. Many commands that print output of some kind can be made more quiet by passing the -q or --quiet options. -### 2.6 Making and reviewing changes +### 2.6 Making and reviewing changes Now that we have a grasp of viewing history in git, let’s take a look at making some changes and examining them. @@ -601,7 +610,7 @@ this, we use the “git diff” command. return 0; } -### 2.7 Recording changes in a new commit +### 2.7 Recording changes in a new commit We can modify files, build and test our changes, and use “git status” and “git diff” to review our changes, until we’re satisfied with what @@ -611,7 +620,7 @@ record our work in a new commit. The “git commit” command lets us create a new changeset; we’ll usually refer to this as “making a commit” or “committing”. -#### 2.7.1 Setting up a username +#### 2.7.1 Setting up a username When you try to run “git commit” for the first time, it might not do exactly what you want. Git records your name and address with each @@ -709,7 +718,7 @@ requirement that the email address actually be valid, and perhaps it's useful to be reminded which machine was used to create particular commits. -#### 2.7.2 Writing a commit message +#### 2.7.2 Writing a commit message When we commit a change, git drops us into a text editor to enter a message that will describe the modifications we’ve made in @@ -719,12 +728,18 @@ after we’ve finished committing. $ git commit -a -Note: The -a on the command-line instructs git to commit all changes -to tracked files. Without this, "git commit" will only commit changes -that have been previously staged for committing with "git add -file". The most common usage is to commit with "git commit -a" and -only use "git add file; git commit" when there is a need to commit -only some subset of changes that have been made. +Note: The -a on the command-line instructs git to commit the new +content of *all* tracked files that have been modified. This is a +convenience over explicitly listing filenames to be committed on the +"git commit" command line. It is useful to use "git commit " +when there is a need to commit only some subset of the files that have +been modified. + +If new files need to be committed for the first time, just use "git +add " before "git commit -a". If a file needs to be removed, +just remove it as normal before committing and "git commit -a" will +notice that---it does not need to be explicitly told about the +removal. The editor that the “git commit” command drops us into will contain an empty line, followed by a number of lines starting with “#”. @@ -743,7 +758,7 @@ git ignores the lines that start with “#”; it uses them only to tell us which files it’s recording changes to. Modifying or deleting these lines has no effect. -#### 2.7.3 Writing a good commit message +#### 2.7.3 Writing a good commit message A good commit message will generally have a single line that summarizes the commit, a blank line, and then one or more pargraphs @@ -774,14 +789,14 @@ My personal preference is for short, but informative, commit messages that tell me something that I can’t figure out with a quick glance at the output of “git log -p". -#### 2.7.4 Aborting a commit +#### 2.7.4 Aborting a commit If you decide that you don’t want to commit while in the middle of editing a commit message, simply exit from your editor without saving the file that it’s editing. This will cause nothing to happen to either the repository or the working directory. -#### 2.7.5 Admiring our new handiwork +#### 2.7.5 Admiring our new handiwork Once we’ve finished the commit, we can use the “git show” command to display the commit we just created. As discussed previously, this @@ -905,14 +920,14 @@ the --amend example to not teach bad habits like I did above. [Note: All this bad-habit stuff was introduced by me, and was not present in Bryan's original chapter. -Carl] -### 2.8 Sharing changes +### 2.8 Sharing changes We mentioned earlier that repositories in git are self-contained. This means that the commit we just created exists only in our my-hello repository. Let’s look at a few ways that we can propagate this change into other repositories. -#### 2.8.1 Pulling changes from another repository +#### 2.8.1 Pulling changes from another repository To get started, let’s clone our original hello repository, which does not contain the change we just committed. We’ll call our temporary @@ -1026,21 +1041,21 @@ seems a little intimidating, understand that it's because things are not presented in the most natural "git way", (and I'm a little too tired to fix it tonight).] -#### 2.8.2 Checking out previous revisions +Note: Mercurial users who are reading this might wonder if there's a +need for the equivalent of "hg update" after doing a "git pull". And +the answer is no. Unlike mercurial, "git pull" and "git merge" will +automatically update the workind-directory files as necessary. -If any users of mercurial are reading this, they might wonder if -there's a need for the equivalent of "hg update" after doing a "git -pull". And the answer is no. Unlike mercurial, "git pull" and "git -merge" will automatically update the workind-directory files as -necessary. +#### 2.8.2 Checking out previous revisions -But there's another function provided by "hg update" which is to -update the working-directory files to a particular revision. In git, -this functionality is provided by the "git checkout" command. To -checkout a particular branch, tag, or an arbitrary revions, simply -give the appropriate name to the "git checkout" command. For example, -to examine the files as they existed before the original typo -introduction, we could do: +It's often useful to examine the working-tree state of some specific +revision other than the tip of some branch. For example, maybe you +would like to build a particular tagged version, or maybe you'd like +to test the behavior of the code before a particular change was +introduced. To do this, use "git checkout" and pass it the name of any +revision, (with a branch name, a tag name, or any other commit +identifier). For example, to examine our project before the original +typo was introduced: $ git checkout 0a633bf5 Note: moving to "0a633bf5" which isn't a local branch @@ -1055,6 +1070,10 @@ history, but if we actually wanted to use this revision as the basis for new commits, we would first have to create a new branch name as it describes. +If we were to use "git checkout" with a branch name, then that would +change the current branch, (meaning that any new commits would advance +that branch pointer). + For now, let's return back to the tip of the master branch by just checking it out again: @@ -1062,7 +1081,7 @@ checking it out again: Previous HEAD position was 0a633bf... Create a makefile Switched to branch "master" -#### 2.8.3 Pushing changes to another repository +#### 2.8.3 Pushing changes to another repository Git lets us push changes to another repository, from the repository we’re currently visiting. As with previous examples, above, we’ll @@ -1110,7 +1129,7 @@ repository already has those changes? Nothing too exciting. $ git push ../hello-push Everything up-to-date -#### 2.8.4 Sharing changes over a network +#### 2.8.4 Sharing changes over a network The commands we have covered in the previous few sections are not limited to working with local repositories. Each works in exactly the @@ -1122,7 +1141,7 @@ Open Publication License Version 1.0, 8 June 1999 -### D.1 Requirements on both unmodified and modified versions +### D.1 Requirements on both unmodified and modified versions The Open Publication works may be reproduced and distributed in whole or in part, in any medium physical or electronic, provided that the @@ -1151,12 +1170,12 @@ outer surfaces of the book the original publisher’s name shall be as large as the title of the work and cited as possessive with respect to the title. -### D.2 Copyright +### D.2 Copyright The copyright to each Open Publication is owned by its author(s) or designee. -### D.3 Scope of license +### D.3 Scope of license The following license terms apply to all Open Publication works, unless otherwise explicitly stated in the document. @@ -1176,7 +1195,7 @@ without warranty of any kind, express or implied, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose or a warranty of non-infringement. -### D.4 Requirements on modified works +### D.4 Requirements on modified works All modified versions of documents covered by this license, including translations, anthologies, compilations and partial documents, must @@ -1193,7 +1212,7 @@ meet the following requirements: assert or imply endorsement of the resulting document without the original author’s (or authors’) permission. -### D.5 Good-practice recommendations +### D.5 Good-practice recommendations In addition to the requirements of this license, it is requested from and strongly recommended of redistributors that: @@ -1212,7 +1231,7 @@ and strongly recommended of redistributors that: CD-ROM expression of an Open Publication-licensed work to its author(s). -### D.6 License options +### D.6 License options The author(s) and/or publisher of an Open Publication-licensed document may elect certain options by appending language to the