user-manual: add "quick start" as chapter 1
Add a "quick start" guide, modelled after Mercurial's, as the first chapter. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
J. Bruce Fields committed
Jan 20, 2007 at 21:41 UTC
ef89f701a0c214fa2967e921f8d3891e25cf3125
1 file changed
+200
-2
Documentation/user-manual.txt
+200
-2
@@ -4,11 +4,14 @@ _________________
4
This manual is designed to be readable by someone with basic unix
5
commandline skills, but no previous knowledge of git.
6
7
-Chapters 1 and 2 explain how to fetch and study a project using
7
+Chapter 1 gives a brief overview of git commands, without any
8
+explanation; you can skip to chapter 2 on a first reading.
9
+
10
+Chapters 2 and 3 explain how to fetch and study a project using
11
git--the tools you'd need to build and test a particular version of a
12
software project, to search for regressions, and so on.
13
11
-Chapter 3 explains how to do development with git, and chapter 4 how
14
+Chapter 4 explains how to do development with git, and chapter 5 how
15
to share that development with others.
16
17
Further chapters cover more specialized topics.
@@ -20,6 +23,201 @@ pages. For a command such as "git clone", just use
23
$ man git-clone
24
------------------------------------------------
25
26
+Git Quick Start
27
+===============
28
+
29
+This is a quick summary of the major commands; the following chapters
30
+will explain how these work in more detail.
31
+
32
+Creating a new repository
33
+-------------------------
34
+
35
+From a tarball:
36
+
37
+-----------------------------------------------
38
+$ tar xzf project.tar.gz
39
+$ cd project
40
+$ git init
41
+Initialized empty Git repository in .git/
42
+$ git add .
43
+$ git commit
44
+-----------------------------------------------
45
+
46
+From a remote repository:
47
+
48
+-----------------------------------------------
49
+$ git clone git://example.com/pub/project.git
50
+$ cd project
51
+-----------------------------------------------
52
+
53
+Managing branches
54
+-----------------
55
+
56
+-----------------------------------------------
57
+$ git branch # list all branches in this repo
58
+$ git checkout test # switch working directory to branch "test"
59
+$ git branch new # create branch "new" starting at current HEAD
60
+$ git branch -d new # delete branch "new"
61
+-----------------------------------------------
62
+
63
+Instead of basing new branch on current HEAD (the default), use:
64
+
65
+-----------------------------------------------
66
+$ git branch new test # branch named "test"
67
+$ git branch new v2.6.15 # tag named v2.6.15
68
+$ git branch new HEAD^ # commit before the most recent
69
+$ git branch new HEAD^^ # commit before that
70
+$ git branch new test~10 # ten commits before tip of branch "test"
71
+-----------------------------------------------
72
+
73
+Create and switch to a new branch at the same time:
74
+
75
+-----------------------------------------------
76
+$ git checkout -b new v2.6.15
77
+-----------------------------------------------
78
+
79
+Update and examine branches from the repository you cloned from:
80
+
81
+-----------------------------------------------
82
+$ git fetch # update
83
+$ git branch -r # list
84
+ origin/master
85
+ origin/next
86
+ ...
87
+$ git branch checkout -b masterwork origin/master
88
+-----------------------------------------------
89
+
90
+Fetch a branch from a different repository, and give it a new
91
+name in your repository:
92
+
93
+-----------------------------------------------
94
+$ git fetch git://example.com/project.git theirbranch:mybranch
95
+$ git fetch git://example.com/project.git v2.6.15:mybranch
96
+-----------------------------------------------
97
+
98
+Keep a list of repositories you work with regularly:
99
+
100
+-----------------------------------------------
101
+$ git remote add example git://example.com/project.git
102
+$ git remote # list remote repositories
103
+example
104
+origin
105
+$ git remote show example # get details
106
+* remote example
107
+ URL: git://example.com/project.git
108
+ Tracked remote branches
109
+ master next ...
110
+$ git fetch example # update branches from example
111
+$ git branch -r # list all remote branches
112
+-----------------------------------------------
113
+
114
+
115
+Exploring history
116
+-----------------
117
+
118
+-----------------------------------------------
119
+$ gitk # visualize and browse history
120
+$ git log # list all commits
121
+$ git log src/ # ...modifying src/
122
+$ git log v2.6.15..v2.6.16 # ...in v2.6.16, not in v2.6.15
123
+$ git log master..test # ...in branch test, not in branch master
124
+$ git log test..master # ...in branch master, but not in test
125
+$ git log test...master # ...in one branch, not in both
126
+$ git log -S'foo()' # ...where difference contain "foo()"
127
+$ git log --since="2 weeks ago"
128
+$ git log -p # show patches as well
129
+$ git show # most recent commit
130
+$ git diff v2.6.15..v2.6.16 # diff between two tagged versions
131
+$ git diff v2.6.15..HEAD # diff with current head
132
+$ git grep "foo()" # search working directory for "foo()"
133
+$ git grep v2.6.15 "foo()" # search old tree for "foo()"
134
+$ git show v2.6.15:a.txt # look at old version of a.txt
135
+-----------------------------------------------
136
+
137
+Searching for regressions:
138
+
139
+-----------------------------------------------
140
+$ git bisect start
141
+$ git bisect bad # current version is bad
142
+$ git bisect good v2.6.13-rc2 # last known good revision
143
+Bisecting: 675 revisions left to test after this
144
+ # test here, then:
145
+$ git bisect good # if this revision is good, or
146
+$ git bisect bad # if this revision is bad.
147
+ # repeat until done.
148
+-----------------------------------------------
149
+
150
+Making changes
151
+--------------
152
+
153
+Make sure git knows who to blame:
154
+
155
+------------------------------------------------
156
+$ cat >~/.gitconfig <<\EOF
157
+[user]
158
+name = Your Name Comes Here
159
+email = you@yourdomain.example.com
160
+EOF
161
+------------------------------------------------
162
+
163
+Select file contents to include in the next commit, then make the
164
+commit:
165
+
166
+-----------------------------------------------
167
+$ git add a.txt # updated file
168
+$ git add b.txt # new file
169
+$ git rm c.txt # old file
170
+$ git commit
171
+-----------------------------------------------
172
+
173
+Or, prepare and create the commit in one step:
174
+
175
+-----------------------------------------------
176
+$ git commit d.txt # use latest content of d.txt
177
+$ git commit -a # use latest content of all tracked files
178
+-----------------------------------------------
179
+
180
+Merging
181
+-------
182
+
183
+-----------------------------------------------
184
+$ git merge test # merge branch "test" into the current branch
185
+$ git pull git://example.com/project.git master
186
+ # fetch and merge in remote branch
187
+$ git pull . test # equivalent to git merge test
188
+-----------------------------------------------
189
+
190
+Sharing development
191
+-------------------
192
+
193
+Importing or exporting patches:
194
+
195
+-----------------------------------------------
196
+$ git format-patch origin..HEAD # format a patch for each commit
197
+ # in HEAD but not in origin
198
+$ git-am mbox # import patches from the mailbox "mbox"
199
+-----------------------------------------------
200
+
201
+Fetch a branch from a different git repository:
202
+
203
+-----------------------------------------------
204
+$ git fetch git://example.com/project.git theirbranch:mybranch
205
+-----------------------------------------------
206
+
207
+Fetch a branch in a different git repository, then merge into the
208
+current branch:
209
+
210
+-----------------------------------------------
211
+$ git pull git://example.com/project.git theirbranch
212
+-----------------------------------------------
213
+
214
+Store the fetched branch into a local branch before merging into the
215
+current branch:
216
+
217
+-----------------------------------------------
218
+$ git pull git://example.com/project.git theirbranch:mybranch
219
+-----------------------------------------------
220
+
221
Repositories and Branches
222
=========================
223