user-manual: move quick-start to an appendix
The quick start interrupts the flow of the manual a bit. Move it to "appendix A" but add a reference to it in the preface. Also rename the todo chapter to "appendix B", and revise the preface a little. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
J. Bruce Fields committed
May 12, 2007 at 22:55 UTC
2624d9a5aa4a98fbfb91b330b297488365af4701
1 file changed
+245
-239
Documentation/user-manual.txt
+245
-239
@@ -4,15 +4,13 @@ ______________________________________________
4
This manual is designed to be readable by someone with basic unix
5
command-line skills, but no previous knowledge of git.
6
7
-Chapter 1 gives a brief overview of git commands, without any
8
-explanation; you may prefer to skip to chapter 2 on a first reading.
7
+<<repositories-and-branches>> and <<exploring-git-history>> explain how
8
+to fetch and study a project using git--read these chapters to learn how
9
+to build and test a particular version of a software project, search for
10
+regressions, and so on.
11
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
-
14
-Chapter 4 explains how to do development with git, and chapter 5 how
15
-to share that development with others.
12
+People needing to do actual development will also want to read
13
+<<Developing-with-git>> and <<sharing-development>>.
14
15
Further chapters cover more specialized topics.
16
@@ -23,237 +21,12 @@ pages. For a command such as "git clone", just use
21
$ man git-clone
22
------------------------------------------------
23
26
-[[git-quick-start]]
27
-Git Quick Start
28
-===============
29
-
30
-This is a quick summary of the major commands; the following chapters
31
-will explain how these work in more detail.
32
-
33
-[[quick-creating-a-new-repository]]
34
-Creating a new repository
35
--------------------------
36
-
37
-From a tarball:
38
-
39
------------------------------------------------
40
-$ tar xzf project.tar.gz
41
-$ cd project
42
-$ git init
43
-Initialized empty Git repository in .git/
44
-$ git add .
45
-$ git commit
46
------------------------------------------------
47
-
48
-From a remote repository:
49
-
50
------------------------------------------------
51
-$ git clone git://example.com/pub/project.git
52
-$ cd project
53
------------------------------------------------
54
-
55
-[[managing-branches]]
56
-Managing branches
57
------------------
58
-
59
------------------------------------------------
60
-$ git branch # list all local branches in this repo
61
-$ git checkout test # switch working directory to branch "test"
62
-$ git branch new # create branch "new" starting at current HEAD
63
-$ git branch -d new # delete branch "new"
64
------------------------------------------------
65
-
66
-Instead of basing new branch on current HEAD (the default), use:
67
-
68
------------------------------------------------
69
-$ git branch new test # branch named "test"
70
-$ git branch new v2.6.15 # tag named v2.6.15
71
-$ git branch new HEAD^ # commit before the most recent
72
-$ git branch new HEAD^^ # commit before that
73
-$ git branch new test~10 # ten commits before tip of branch "test"
74
------------------------------------------------
75
-
76
-Create and switch to a new branch at the same time:
77
-
78
------------------------------------------------
79
-$ git checkout -b new v2.6.15
80
------------------------------------------------
81
-
82
-Update and examine branches from the repository you cloned from:
83
-
84
------------------------------------------------
85
-$ git fetch # update
86
-$ git branch -r # list
87
- origin/master
88
- origin/next
89
- ...
90
-$ git checkout -b masterwork origin/master
91
------------------------------------------------
92
-
93
-Fetch a branch from a different repository, and give it a new
94
-name in your repository:
95
-
96
------------------------------------------------
97
-$ git fetch git://example.com/project.git theirbranch:mybranch
98
-$ git fetch git://example.com/project.git v2.6.15:mybranch
99
------------------------------------------------
100
-
101
-Keep a list of repositories you work with regularly:
102
-
103
------------------------------------------------
104
-$ git remote add example git://example.com/project.git
105
-$ git remote # list remote repositories
106
-example
107
-origin
108
-$ git remote show example # get details
109
-* remote example
110
- URL: git://example.com/project.git
111
- Tracked remote branches
112
- master next ...
113
-$ git fetch example # update branches from example
114
-$ git branch -r # list all remote branches
115
------------------------------------------------
116
-
117
-
118
-[[exploring-history]]
119
-Exploring history
120
------------------
121
-
122
------------------------------------------------
123
-$ gitk # visualize and browse history
124
-$ git log # list all commits
125
-$ git log src/ # ...modifying src/
126
-$ git log v2.6.15..v2.6.16 # ...in v2.6.16, not in v2.6.15
127
-$ git log master..test # ...in branch test, not in branch master
128
-$ git log test..master # ...in branch master, but not in test
129
-$ git log test...master # ...in one branch, not in both
130
-$ git log -S'foo()' # ...where difference contain "foo()"
131
-$ git log --since="2 weeks ago"
132
-$ git log -p # show patches as well
133
-$ git show # most recent commit
134
-$ git diff v2.6.15..v2.6.16 # diff between two tagged versions
135
-$ git diff v2.6.15..HEAD # diff with current head
136
-$ git grep "foo()" # search working directory for "foo()"
137
-$ git grep v2.6.15 "foo()" # search old tree for "foo()"
138
-$ git show v2.6.15:a.txt # look at old version of a.txt
139
------------------------------------------------
140
-
141
-Search for regressions:
142
-
143
------------------------------------------------
144
-$ git bisect start
145
-$ git bisect bad # current version is bad
146
-$ git bisect good v2.6.13-rc2 # last known good revision
147
-Bisecting: 675 revisions left to test after this
148
- # test here, then:
149
-$ git bisect good # if this revision is good, or
150
-$ git bisect bad # if this revision is bad.
151
- # repeat until done.
152
------------------------------------------------
153
-
154
-[[making-changes]]
155
-Making changes
156
---------------
157
-
158
-Make sure git knows who to blame:
159
-
160
-------------------------------------------------
161
-$ cat >>~/.gitconfig <<\EOF
162
-[user]
163
- name = Your Name Comes Here
164
- email = you@yourdomain.example.com
165
-EOF
166
-------------------------------------------------
167
-
168
-Select file contents to include in the next commit, then make the
169
-commit:
170
-
171
------------------------------------------------
172
-$ git add a.txt # updated file
173
-$ git add b.txt # new file
174
-$ git rm c.txt # old file
175
-$ git commit
176
------------------------------------------------
24
+See also <<git-quick-start>> for a brief overview of git commands,
25
+without any explanation.
26
178
-Or, prepare and create the commit in one step:
27
+Also, see <<todo>> for ways that you can help make this manual more
28
+complete.
29
180
------------------------------------------------
181
-$ git commit d.txt # use latest content only of d.txt
182
-$ git commit -a # use latest content of all tracked files
183
------------------------------------------------
184
-
185
-[[merging]]
186
-Merging
187
--------
188
-
189
------------------------------------------------
190
-$ git merge test # merge branch "test" into the current branch
191
-$ git pull git://example.com/project.git master
192
- # fetch and merge in remote branch
193
-$ git pull . test # equivalent to git merge test
194
------------------------------------------------
195
-
196
-[[sharing-your-changes]]
197
-Sharing your changes
198
---------------------
199
-
200
-Importing or exporting patches:
201
-
202
------------------------------------------------
203
-$ git format-patch origin..HEAD # format a patch for each commit
204
- # in HEAD but not in origin
205
-$ git am mbox # import patches from the mailbox "mbox"
206
------------------------------------------------
207
-
208
-Fetch a branch in a different git repository, then merge into the
209
-current branch:
210
-
211
------------------------------------------------
212
-$ git pull git://example.com/project.git theirbranch
213
------------------------------------------------
214
-
215
-Store the fetched branch into a local branch before merging into the
216
-current branch:
217
-
218
------------------------------------------------
219
-$ git pull git://example.com/project.git theirbranch:mybranch
220
------------------------------------------------
221
-
222
-After creating commits on a local branch, update the remote
223
-branch with your commits:
224
-
225
------------------------------------------------
226
-$ git push ssh://example.com/project.git mybranch:theirbranch
227
------------------------------------------------
228
-
229
-When remote and local branch are both named "test":
230
-
231
------------------------------------------------
232
-$ git push ssh://example.com/project.git test
233
------------------------------------------------
234
-
235
-Shortcut version for a frequently used remote repository:
236
-
237
------------------------------------------------
238
-$ git remote add example ssh://example.com/project.git
239
-$ git push example test
240
------------------------------------------------
241
-
242
-[[repository-maintenance]]
243
-Repository maintenance
244
-----------------------
245
-
246
-Check for corruption:
247
-
248
------------------------------------------------
249
-$ git fsck
250
------------------------------------------------
251
-
252
-Recompress, remove unused cruft:
253
-
254
------------------------------------------------
255
-$ git gc
256
------------------------------------------------
30
31
[[repositories-and-branches]]
32
Repositories and Branches
@@ -3372,9 +3145,242 @@ itself!
3145
[[glossary]]
3146
include::glossary.txt[]
3147
3148
+[[git-quick-start]]
3149
+Appendix A: Git Quick Start
3150
+===========================
3151
+
3152
+This is a quick summary of the major commands; the following chapters
3153
+will explain how these work in more detail.
3154
+
3155
+[[quick-creating-a-new-repository]]
3156
+Creating a new repository
3157
+-------------------------
3158
+
3159
+From a tarball:
3160
+
3161
+-----------------------------------------------
3162
+$ tar xzf project.tar.gz
3163
+$ cd project
3164
+$ git init
3165
+Initialized empty Git repository in .git/
3166
+$ git add .
3167
+$ git commit
3168
+-----------------------------------------------
3169
+
3170
+From a remote repository:
3171
+
3172
+-----------------------------------------------
3173
+$ git clone git://example.com/pub/project.git
3174
+$ cd project
3175
+-----------------------------------------------
3176
+
3177
+[[managing-branches]]
3178
+Managing branches
3179
+-----------------
3180
+
3181
+-----------------------------------------------
3182
+$ git branch # list all local branches in this repo
3183
+$ git checkout test # switch working directory to branch "test"
3184
+$ git branch new # create branch "new" starting at current HEAD
3185
+$ git branch -d new # delete branch "new"
3186
+-----------------------------------------------
3187
+
3188
+Instead of basing new branch on current HEAD (the default), use:
3189
+
3190
+-----------------------------------------------
3191
+$ git branch new test # branch named "test"
3192
+$ git branch new v2.6.15 # tag named v2.6.15
3193
+$ git branch new HEAD^ # commit before the most recent
3194
+$ git branch new HEAD^^ # commit before that
3195
+$ git branch new test~10 # ten commits before tip of branch "test"
3196
+-----------------------------------------------
3197
+
3198
+Create and switch to a new branch at the same time:
3199
+
3200
+-----------------------------------------------
3201
+$ git checkout -b new v2.6.15
3202
+-----------------------------------------------
3203
+
3204
+Update and examine branches from the repository you cloned from:
3205
+
3206
+-----------------------------------------------
3207
+$ git fetch # update
3208
+$ git branch -r # list
3209
+ origin/master
3210
+ origin/next
3211
+ ...
3212
+$ git checkout -b masterwork origin/master
3213
+-----------------------------------------------
3214
+
3215
+Fetch a branch from a different repository, and give it a new
3216
+name in your repository:
3217
+
3218
+-----------------------------------------------
3219
+$ git fetch git://example.com/project.git theirbranch:mybranch
3220
+$ git fetch git://example.com/project.git v2.6.15:mybranch
3221
+-----------------------------------------------
3222
+
3223
+Keep a list of repositories you work with regularly:
3224
+
3225
+-----------------------------------------------
3226
+$ git remote add example git://example.com/project.git
3227
+$ git remote # list remote repositories
3228
+example
3229
+origin
3230
+$ git remote show example # get details
3231
+* remote example
3232
+ URL: git://example.com/project.git
3233
+ Tracked remote branches
3234
+ master next ...
3235
+$ git fetch example # update branches from example
3236
+$ git branch -r # list all remote branches
3237
+-----------------------------------------------
3238
+
3239
+
3240
+[[exploring-history]]
3241
+Exploring history
3242
+-----------------
3243
+
3244
+-----------------------------------------------
3245
+$ gitk # visualize and browse history
3246
+$ git log # list all commits
3247
+$ git log src/ # ...modifying src/
3248
+$ git log v2.6.15..v2.6.16 # ...in v2.6.16, not in v2.6.15
3249
+$ git log master..test # ...in branch test, not in branch master
3250
+$ git log test..master # ...in branch master, but not in test
3251
+$ git log test...master # ...in one branch, not in both
3252
+$ git log -S'foo()' # ...where difference contain "foo()"
3253
+$ git log --since="2 weeks ago"
3254
+$ git log -p # show patches as well
3255
+$ git show # most recent commit
3256
+$ git diff v2.6.15..v2.6.16 # diff between two tagged versions
3257
+$ git diff v2.6.15..HEAD # diff with current head
3258
+$ git grep "foo()" # search working directory for "foo()"
3259
+$ git grep v2.6.15 "foo()" # search old tree for "foo()"
3260
+$ git show v2.6.15:a.txt # look at old version of a.txt
3261
+-----------------------------------------------
3262
+
3263
+Search for regressions:
3264
+
3265
+-----------------------------------------------
3266
+$ git bisect start
3267
+$ git bisect bad # current version is bad
3268
+$ git bisect good v2.6.13-rc2 # last known good revision
3269
+Bisecting: 675 revisions left to test after this
3270
+ # test here, then:
3271
+$ git bisect good # if this revision is good, or
3272
+$ git bisect bad # if this revision is bad.
3273
+ # repeat until done.
3274
+-----------------------------------------------
3275
+
3276
+[[making-changes]]
3277
+Making changes
3278
+--------------
3279
+
3280
+Make sure git knows who to blame:
3281
+
3282
+------------------------------------------------
3283
+$ cat >>~/.gitconfig <<\EOF
3284
+[user]
3285
+ name = Your Name Comes Here
3286
+ email = you@yourdomain.example.com
3287
+EOF
3288
+------------------------------------------------
3289
+
3290
+Select file contents to include in the next commit, then make the
3291
+commit:
3292
+
3293
+-----------------------------------------------
3294
+$ git add a.txt # updated file
3295
+$ git add b.txt # new file
3296
+$ git rm c.txt # old file
3297
+$ git commit
3298
+-----------------------------------------------
3299
+
3300
+Or, prepare and create the commit in one step:
3301
+
3302
+-----------------------------------------------
3303
+$ git commit d.txt # use latest content only of d.txt
3304
+$ git commit -a # use latest content of all tracked files
3305
+-----------------------------------------------
3306
+
3307
+[[merging]]
3308
+Merging
3309
+-------
3310
+
3311
+-----------------------------------------------
3312
+$ git merge test # merge branch "test" into the current branch
3313
+$ git pull git://example.com/project.git master
3314
+ # fetch and merge in remote branch
3315
+$ git pull . test # equivalent to git merge test
3316
+-----------------------------------------------
3317
+
3318
+[[sharing-your-changes]]
3319
+Sharing your changes
3320
+--------------------
3321
+
3322
+Importing or exporting patches:
3323
+
3324
+-----------------------------------------------
3325
+$ git format-patch origin..HEAD # format a patch for each commit
3326
+ # in HEAD but not in origin
3327
+$ git am mbox # import patches from the mailbox "mbox"
3328
+-----------------------------------------------
3329
+
3330
+Fetch a branch in a different git repository, then merge into the
3331
+current branch:
3332
+
3333
+-----------------------------------------------
3334
+$ git pull git://example.com/project.git theirbranch
3335
+-----------------------------------------------
3336
+
3337
+Store the fetched branch into a local branch before merging into the
3338
+current branch:
3339
+
3340
+-----------------------------------------------
3341
+$ git pull git://example.com/project.git theirbranch:mybranch
3342
+-----------------------------------------------
3343
+
3344
+After creating commits on a local branch, update the remote
3345
+branch with your commits:
3346
+
3347
+-----------------------------------------------
3348
+$ git push ssh://example.com/project.git mybranch:theirbranch
3349
+-----------------------------------------------
3350
+
3351
+When remote and local branch are both named "test":
3352
+
3353
+-----------------------------------------------
3354
+$ git push ssh://example.com/project.git test
3355
+-----------------------------------------------
3356
+
3357
+Shortcut version for a frequently used remote repository:
3358
+
3359
+-----------------------------------------------
3360
+$ git remote add example ssh://example.com/project.git
3361
+$ git push example test
3362
+-----------------------------------------------
3363
+
3364
+[[repository-maintenance]]
3365
+Repository maintenance
3366
+----------------------
3367
+
3368
+Check for corruption:
3369
+
3370
+-----------------------------------------------
3371
+$ git fsck
3372
+-----------------------------------------------
3373
+
3374
+Recompress, remove unused cruft:
3375
+
3376
+-----------------------------------------------
3377
+$ git gc
3378
+-----------------------------------------------
3379
+
3380
+
3381
[[todo]]
3376
-Notes and todo list for this manual
3377
-===================================
3382
+Appendix B: Notes and todo list for this manual
3383
+===============================================
3384
3385
This is a work in progress.
3386