@matheusbsbs / matheus-bagliano / commits / e34caace58
Fork 0

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