@matheusbsbs / matheus-bagliano / commits / 2624d9a5aa
Fork 0

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