user-manual: add section ID's
Any section lacking an id gets an annoying warning when you build the manual. More seriously, the table of contents then generates volatile id's which change with every build, with the effect that we get URL's that change all the time. The ID's are manually generated and sometimes inconsistent, but that's OK. XXX: what to do about the preface? Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
J. Bruce Fields committed
Apr 18, 2007 at 00:46 UTC
e34caace588612e9bc492aa9188390de42546aad
1 file changed
+82
-2
Documentation/user-manual.txt
+82
-2
@@ -23,12 +23,14 @@ pages. For a command such as "git clone", just use
23
$ man git-clone
24
------------------------------------------------
25
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
@@ -50,6 +52,7 @@ $ git clone git://example.com/pub/project.git
52
$ cd project
53
-----------------------------------------------
54
55
+[[managing-branches]]
56
Managing branches
57
-----------------
58
@@ -112,6 +115,7 @@ $ git branch -r # list all remote branches
115
-----------------------------------------------
116
117
118
+[[exploring-history]]
119
Exploring history
120
-----------------
121
@@ -147,6 +151,7 @@ $ git bisect bad # if this revision is bad.
151
# repeat until done.
152
-----------------------------------------------
153
154
+[[making-changes]]
155
Making changes
156
--------------
157
@@ -177,6 +182,7 @@ $ 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
@@ -187,6 +193,7 @@ $ git pull git://example.com/project.git master
193
$ git pull . test # equivalent to git merge test
194
-----------------------------------------------
195
196
+[[sharing-your-changes]]
197
Sharing your changes
198
--------------------
199
@@ -232,6 +239,7 @@ $ git remote add example ssh://example.com/project.git
239
$ git push example test
240
-----------------------------------------------
241
242
+[[repository-maintenance]]
243
Repository maintenance
244
----------------------
245
@@ -247,9 +255,11 @@ Recompress, remove unused cruft:
255
$ git gc
256
-----------------------------------------------
257
258
+[[repositories-and-branches]]
259
Repositories and Branches
260
=========================
261
262
+[[how-to-get-a-git-repository]]
263
How to get a git repository
264
---------------------------
265
@@ -280,6 +290,7 @@ contains all the information about the history of the project.
290
In most of the following, examples will be taken from one of the two
291
repositories above.
292
293
+[[how-to-check-out]]
294
How to check out a different version of a project
295
-------------------------------------------------
296
@@ -352,6 +363,7 @@ particular point in history, then resetting that branch may leave you
363
with no way to find the history it used to point to; so use this command
364
carefully.
365
366
+[[understanding-commits]]
367
Understanding History: Commits
368
------------------------------
369
@@ -407,6 +419,7 @@ In fact, in <<git-internals>> we shall see that everything stored in git
419
history, including file data and directory contents, is stored in an object
420
with a name that is a hash of its contents.
421
422
+[[understanding-reachability]]
423
Understanding history: commits, parents, and reachability
424
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
425
@@ -431,6 +444,7 @@ if commit X is an ancestor of commit Y. Equivalently, you could say
444
that Y is a descendent of X, or that there is a chain of parents
445
leading from commit Y to commit X.
446
447
+[[history-diagrams]]
448
Understanding history: History diagrams
449
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
450
@@ -450,6 +464,7 @@ lines drawn with - / and \. Time goes left to right:
464
If we need to talk about a particular commit, the character "o" may
465
be replaced with another letter or number.
466
467
+[[what-is-a-branch]]
468
Understanding history: What is a branch?
469
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
470
@@ -463,6 +478,7 @@ the line of three commits leading up to that point as all being part of
478
However, when no confusion will result, we often just use the term
479
"branch" both for branches and for branch heads.
480
481
+[[manipulating-branches]]
482
Manipulating branches
483
---------------------
484
@@ -538,6 +554,7 @@ This is an easy way to check out a particular version without having to
554
make up a name for the new branch. You can still create a new branch
555
(or tag) for this version later if you decide to.
556
557
+[[examining-remote-branches]]
558
Examining branches from a remote repository
559
-------------------------------------------
560
@@ -611,6 +628,7 @@ remote-tracking branches to the latest version found in her
628
repository. It will not touch any of your own branches--not even the
629
"master" branch that was created for you on clone.
630
631
+[[fetching-branches]]
632
Fetching branches from other repositories
633
-----------------------------------------
634
@@ -653,6 +671,7 @@ or delete these configuration options by editing .git/config with a
671
text editor. (See the "CONFIGURATION FILE" section of
672
gitlink:git-config[1] for details.)
673
674
+[[exploring-git-history]]
675
Exploring git history
676
=====================
677
@@ -667,6 +686,7 @@ history of a project.
686
We start with one specialized tool that is useful for finding the
687
commit that introduced a bug into a project.
688
689
+[[using-bisect]]
690
How to use bisect to find a regression
691
--------------------------------------
692
@@ -734,6 +754,7 @@ $ git reset --hard fb47ddb2db...
754
then test, run "bisect good" or "bisect bad" as appropriate, and
755
continue.
756
757
+[[naming-commits]]
758
Naming commits
759
--------------
760
@@ -798,6 +819,7 @@ $ git rev-parse origin
819
e05db0fd4f31dde7005f075a84f96b360d05984b
820
-------------------------------------------------
821
822
+[[creating-tags]]
823
Creating tags
824
-------------
825
@@ -815,6 +837,7 @@ share with others, and possibly sign cryptographically, then you
837
should create a tag object instead; see the gitlink:git-tag[1] man
838
page for details.
839
840
+[[browsing-revisions]]
841
Browsing revisions
842
------------------
843
@@ -856,6 +879,7 @@ backwards through the parents; however, since git history can contain
879
multiple independent lines of development, the particular order that
880
commits are listed in may be somewhat arbitrary.
881
882
+[[generating-diffs]]
883
Generating diffs
884
----------------
885
@@ -877,6 +901,7 @@ but not from master. Note that if master also has commits which are
901
not reachable from test, then the combined result of these patches
902
will not be the same as the diff produced by the git-diff example.
903
904
+[[viewing-old-file-versions]]
905
Viewing old file versions
906
-------------------------
907
@@ -892,9 +917,11 @@ $ git show v2.5:fs/locks.c
917
Before the colon may be anything that names a commit, and after it
918
may be any path to a file tracked by git.
919
920
+[[history-examples]]
921
Examples
922
--------
923
924
+[[checking-for-equal-branches]]
925
Check whether two branches point at the same history
926
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
927
@@ -927,6 +954,7 @@ $ git log origin...master
954
955
will return no commits when the two branches are equal.
956
957
+[[finding-tagged-descendants]]
958
Find first tagged version including a given fix
959
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
960
@@ -1012,9 +1040,11 @@ Which shows that e05db0fd is reachable from itself, from v1.5.0-rc1, and
1040
from v1.5.0-rc2, but not from v1.5.0-rc0.
1041
1042
1043
+[[Developing-with-git]]
1044
Developing with git
1045
===================
1046
1047
+[[telling-git-your-name]]
1048
Telling git your name
1049
---------------------
1050
@@ -1033,6 +1063,7 @@ EOF
1063
details on the configuration file.)
1064
1065
1066
+[[creating-a-new-repository]]
1067
Creating a new repository
1068
-------------------------
1069
@@ -1149,6 +1180,7 @@ $ git diff # difference between the index file and your
1180
$ git status # a brief per-file summary of the above.
1181
-------------------------------------------------
1182
1183
+[[creating-good-commit-messages]]
1184
Creating good commit messages
1185
-----------------------------
1186
@@ -1159,6 +1191,7 @@ description. Tools that turn commits into email, for example, use
1191
the first line on the Subject line and the rest of the commit in the
1192
body.
1193
1194
+[[how-to-merge]]
1195
How to merge
1196
------------
1197
@@ -1236,6 +1269,7 @@ your own if desired.
1269
The above is all you need to know to resolve a simple merge. But git
1270
also provides more information to help resolve conflicts:
1271
1272
+[[conflict-resolution]]
1273
Getting conflict-resolution help during a merge
1274
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1275
@@ -1359,6 +1393,7 @@ throw away a commit you have already committed if that commit may
1393
itself have been merged into another branch, as doing so may confuse
1394
further merges.
1395
1396
+[[fast-forwards]]
1397
Fast-forward merges
1398
-------------------
1399
@@ -1374,6 +1409,7 @@ already contained in the other--then git just performs a
1409
moved forward to point at the head of the merged-in branch, without
1410
any new commits being created.
1411
1412
+[[fixing-mistakes]]
1413
Fixing mistakes
1414
---------------
1415
@@ -1398,6 +1434,7 @@ fundamentally different ways to fix the problem:
1434
change, and cannot correctly perform repeated merges from
1435
a branch that has had its history changed.
1436
1437
+[[reverting-a-commit]]
1438
Fixing a mistake with a new commit
1439
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1440
@@ -1452,6 +1489,7 @@ It is also possible to edit commits further back in the history, but
1489
this is an advanced topic to be left for
1490
<<cleaning-up-history,another chapter>>.
1491
1492
+[[checkout-of-path]]
1493
Checking out an old version of a file
1494
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1495
@@ -1478,6 +1516,7 @@ $ git show HEAD^:path/to/file
1516
1517
which will display the given version of the file.
1518
1519
+[[ensuring-good-performance]]
1520
Ensuring good performance
1521
-------------------------
1522
@@ -1494,9 +1533,12 @@ $ git gc
1533
to recompress the archive. This can be very time-consuming, so
1534
you may prefer to run git-gc when you are not doing other work.
1535
1536
+
1537
+[[ensuring-reliability]]
1538
Ensuring reliability
1539
--------------------
1540
1541
+[[checking-for-corruption]]
1542
Checking the repository for corruption
1543
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1544
@@ -1532,9 +1574,11 @@ other git operations are in progress in the same repository.
1574
For more about dangling objects, see <<dangling-objects>>.
1575
1576
1577
+[[recovering-lost-changes]]
1578
Recovering lost changes
1579
~~~~~~~~~~~~~~~~~~~~~~~
1580
1581
+[[reflogs]]
1582
Reflogs
1583
^^^^^^^
1584
@@ -1582,6 +1626,7 @@ While normal history is shared by every repository that works on the
1626
same project, the reflog history is not shared: it tells you only about
1627
how the branches in your local repository have changed over time.
1628
1629
+[[dangling-objects]]
1630
Examining dangling objects
1631
^^^^^^^^^^^^^^^^^^^^^^^^^^
1632
@@ -1623,6 +1668,7 @@ $ git branch recovered-branch 7281251ddd
1668
------------------------------------------------
1669
1670
1671
+[[sharing-development]]
1672
Sharing development with others
1673
===============================
1674
@@ -1682,6 +1728,7 @@ $ git merge branch
1728
1729
are roughly equivalent. The former is actually very commonly used.
1730
1731
+[[submitting-patches]]
1732
Submitting patches to a project
1733
-------------------------------
1734
@@ -1703,6 +1750,7 @@ use the gitlink:git-send-email[1] script to automate the process.
1750
Consult the mailing list for your project first to determine how they
1751
prefer such patches be handled.
1752
1753
+[[importing-patches]]
1754
Importing patches to a project
1755
------------------------------
1756
@@ -1898,6 +1946,7 @@ See the explanations of the remote.<name>.url, branch.<name>.remote,
1946
and remote.<name>.push options in gitlink:git-config[1] for
1947
details.
1948
1949
+[[setting-up-a-shared-repository]]
1950
Setting up a shared repository
1951
------------------------------
1952
@@ -1907,6 +1956,7 @@ all push to and pull from a single shared repository. See
1956
link:cvs-migration.txt[git for CVS users] for instructions on how to
1957
set this up.
1958
1959
+[[setting-up-gitweb]]
1960
Allow web browsing of a repository
1961
----------------------------------
1962
@@ -1914,6 +1964,7 @@ The gitweb cgi script provides users an easy way to browse your
1964
project's files and history without having to install git; see the file
1965
gitweb/INSTALL in the git source tree for instructions on setting it up.
1966
1967
+[[sharing-development-examples]]
1968
Examples
1969
--------
1970
@@ -1931,6 +1982,7 @@ cause git's merge machinery (for example) to do the wrong thing.
1982
However, there is a situation in which it can be useful to violate this
1983
assumption.
1984
1985
+[[patch-series]]
1986
Creating the perfect patch series
1987
---------------------------------
1988
@@ -1963,6 +2015,7 @@ We will introduce some tools that can help you do this, explain how to
2015
use them, and then explain some of the problems that can arise because
2016
you are rewriting history.
2017
2018
+[[using-git-rebase]]
2019
Keeping a patch series up to date using git-rebase
2020
--------------------------------------------------
2021
@@ -2044,6 +2097,7 @@ return mywork to the state it had before you started the rebase:
2097
$ git rebase --abort
2098
-------------------------------------------------
2099
2100
+[[modifying-one-commit]]
2101
Modifying a single commit
2102
-------------------------
2103
@@ -2089,6 +2143,7 @@ Note that the immutable nature of git history means that you haven't really
2143
"modified" existing commits; instead, you have replaced the old commits with
2144
new commits having new object names.
2145
2146
+[[reordering-patch-series]]
2147
Reordering or selecting from a patch series
2148
-------------------------------------------
2149
@@ -2118,6 +2173,7 @@ $ git reset --hard origin
2173
Then modify, reorder, or eliminate patches as preferred before applying
2174
them again with gitlink:git-am[1].
2175
2176
+[[patch-series-tools]]
2177
Other tools
2178
-----------
2179
@@ -2125,6 +2181,7 @@ There are numerous other tools, such as stgit, which exist for the
2181
purpose of maintaining a patch series. These are outside of the scope of
2182
this manual.
2183
2184
+[[problems-with-rewriting-history]]
2185
Problems with rewriting history
2186
-------------------------------
2187
@@ -2173,9 +2230,11 @@ branches into their own work.
2230
For true distributed development that supports proper merging,
2231
published branches should never be rewritten.
2232
2233
+[[advanced-branch-management]]
2234
Advanced branch management
2235
==========================
2236
2237
+[[fetching-individual-branches]]
2238
Fetching individual branches
2239
----------------------------
2240
@@ -2204,7 +2263,7 @@ already have a branch named example-master, it will attempt to
2263
"fast-forward" to the commit given by example.com's master branch. So
2264
next we explain what a fast-forward is:
2265
2207
-[[fast-forwards]]
2266
+[[fast-forwards-2]]
2267
Understanding git history: fast-forwards
2268
----------------------------------------
2269
@@ -2242,6 +2301,7 @@ situation above this may mean losing the commits labeled "a" and "b",
2301
unless you've already created a reference of your own pointing to
2302
them.
2303
2304
+[[forcing-fetch]]
2305
Forcing git fetch to do non-fast-forward updates
2306
------------------------------------------------
2307
@@ -2256,6 +2316,7 @@ Note the addition of the "+" sign. Be aware that commits that the
2316
old version of example/master pointed at may be lost, as we saw in
2317
the previous section.
2318
2319
+[[remote-branch-configuration]]
2320
Configuring remote branches
2321
---------------------------
2322
@@ -2329,6 +2390,7 @@ Git internals
2390
Git depends on two fundamental abstractions: the "object database", and
2391
the "current directory cache" aka "index".
2392
2393
+[[the-object-database]]
2394
The Object Database
2395
-------------------
2396
@@ -2398,6 +2460,7 @@ to just verifying their superficial consistency through the hash).
2460
2461
The object types in some more detail:
2462
2463
+[[blob-object]]
2464
Blob Object
2465
-----------
2466
@@ -2419,6 +2482,7 @@ file is associated with in any way.
2482
A blob is typically created when gitlink:git-update-index[1]
2483
is run, and its data can be accessed by gitlink:git-cat-file[1].
2484
2485
+[[tree-object]]
2486
Tree Object
2487
-----------
2488
@@ -2460,6 +2524,7 @@ A tree is created with gitlink:git-write-tree[1] and
2524
its data can be accessed by gitlink:git-ls-tree[1].
2525
Two trees can be compared with gitlink:git-diff-tree[1].
2526
2527
+[[commit-object]]
2528
Commit Object
2529
-------------
2530
@@ -2486,6 +2551,7 @@ file manager.
2551
A commit is created with gitlink:git-commit-tree[1] and
2552
its data can be accessed by gitlink:git-cat-file[1].
2553
2554
+[[trust]]
2555
Trust
2556
-----
2557
@@ -2515,6 +2581,7 @@ like GPG/PGP.
2581
2582
To assist in this, git also provides the tag object...
2583
2584
+[[tag-object]]
2585
Tag Object
2586
----------
2587
@@ -2537,6 +2604,7 @@ and the signature can be verified by
2604
gitlink:git-verify-tag[1].
2605
2606
2607
+[[the-index]]
2608
The "index" aka "Current Directory Cache"
2609
-----------------------------------------
2610
@@ -2591,6 +2659,7 @@ been written back to the backing store.
2659
2660
2661
2662
+[[the-workflow]]
2663
The Workflow
2664
------------
2665
@@ -2600,6 +2669,7 @@ index), but most operations move data to and from the index file. Either
2669
from the database or from the working directory. Thus there are four
2670
main combinations:
2671
2672
+[[working-directory-to-index]]
2673
working directory -> index
2674
~~~~~~~~~~~~~~~~~~~~~~~~~~
2675
@@ -2633,6 +2703,7 @@ stat information. It will 'not' update the object status itself, and
2703
it will only update the fields that are used to quickly test whether
2704
an object still matches its old backing store object.
2705
2706
+[[index-to-object-database]]
2707
index -> object database
2708
~~~~~~~~~~~~~~~~~~~~~~~~
2709
@@ -2648,6 +2719,7 @@ and it will return the name of the resulting top-level tree. You can
2719
use that tree to re-generate the index at any time by going in the
2720
other direction:
2721
2722
+[[object-database-to-index]]
2723
object database -> index
2724
~~~~~~~~~~~~~~~~~~~~~~~~
2725
@@ -2664,6 +2736,7 @@ and your index file will now be equivalent to the tree that you saved
2736
earlier. However, that is only your 'index' file: your working
2737
directory contents have not been modified.
2738
2739
+[[index-to-working-directory]]
2740
index -> working directory
2741
~~~~~~~~~~~~~~~~~~~~~~~~~~
2742
@@ -2693,6 +2766,7 @@ need to use the "-f" flag ('before' the "-a" flag or the filename) to
2766
Finally, there are a few odds and ends which are not purely moving
2767
from one representation to the other:
2768
2769
+[[tying-it-all-together]]
2770
Tying it all together
2771
~~~~~~~~~~~~~~~~~~~~~
2772
@@ -2768,6 +2842,7 @@ various pieces fit together.
2842
------------
2843
2844
2845
+[[examining-the-data]]
2846
Examining the data
2847
------------------
2848
@@ -2803,6 +2878,7 @@ $ git-cat-file commit HEAD
2878
2879
to see what the top commit was.
2880
2881
+[[merging-multiple-trees]]
2882
Merging multiple trees
2883
----------------------
2884
@@ -2854,6 +2930,7 @@ index file, and you can just write the result out with
2930
`git-write-tree`.
2931
2932
2933
+[[merging-multiple-trees-2]]
2934
Merging multiple trees, continued
2935
---------------------------------
2936
@@ -2924,6 +3001,7 @@ $ git-merge-index git-merge-one-file hello.c
3001
3002
and that is what higher level `git merge -s resolve` is implemented with.
3003
3004
+[[pack-files]]
3005
How git stores objects efficiently: pack files
3006
----------------------------------------------
3007
@@ -2984,7 +3062,7 @@ objects will work exactly as they did before.
3062
The gitlink:git-gc[1] command performs packing, pruning, and more for
3063
you, so is normally the only high-level command you need.
3064
2987
-[[dangling-objects]]
3065
+[[dangling-objects-2]]
3066
Dangling objects
3067
----------------
3068
@@ -3065,8 +3143,10 @@ confusing and scary messages, but it won't actually do anything bad. In
3143
contrast, running "git prune" while somebody is actively changing the
3144
repository is a *BAD* idea).
3145
3146
+[[glossary]]
3147
include::glossary.txt[]
3148
3149
+[[todo]]
3150
Notes and todo list for this manual
3151
===================================
3152