42
It will be useful to have a git repository to experiment with as you
43
read this manual.
44
45
-The best way to get one is by using the gitlink:git-clone[1] command to
45
+The best way to get one is by using the linkgit:git-clone[1] command to
46
download a copy of an existing repository. If you don't already have a
47
project in mind, here are some interesting examples:
48
79
80
A single git repository can track development on multiple branches. It
81
does this by keeping a list of <<def_head,heads>> which reference the
82
-latest commit on each branch; the gitlink:git-branch[1] command shows
82
+latest commit on each branch; the linkgit:git-branch[1] command shows
83
you the list of branch heads:
84
85
------------------------------------------------
93
94
Most projects also use <<def_tag,tags>>. Tags, like heads, are
95
references into the project's history, and can be listed using the
96
-gitlink:git-tag[1] command:
96
+linkgit:git-tag[1] command:
97
98
------------------------------------------------
99
$ git tag -l
113
while heads are expected to advance as development progresses.
114
115
Create a new branch head pointing to one of these versions and check it
116
-out using gitlink:git-checkout[1]:
116
+out using linkgit:git-checkout[1]:
117
118
------------------------------------------------
119
$ git checkout -b new v2.6.13
120
------------------------------------------------
121
122
The working directory then reflects the contents that the project had
123
-when it was tagged v2.6.13, and gitlink:git-branch[1] shows two
123
+when it was tagged v2.6.13, and linkgit:git-branch[1] shows two
124
branches, with an asterisk marking the currently checked-out branch:
125
126
------------------------------------------------
146
------------------------------
147
148
Every change in the history of a project is represented by a commit.
149
-The gitlink:git-show[1] command shows the most recent commit on the
149
+The linkgit:git-show[1] command shows the most recent commit on the
150
current branch:
151
152
------------------------------------------------
208
each parent representing the most recent commit on one of the lines
209
of development leading to that point.
210
211
-The best way to see how this works is using the gitlink:gitk[1]
211
+The best way to see how this works is using the linkgit:gitk[1]
212
command; running gitk now on a git repository and looking for merge
213
commits will help understand how the git organizes history.
214
335
of the HEAD in the repository that you cloned from. That repository
336
may also have had other branches, though, and your local repository
337
keeps branches which track each of those remote branches, which you
338
-can view using the "-r" option to gitlink:git-branch[1]:
338
+can view using the "-r" option to linkgit:git-branch[1]:
339
340
------------------------------------------------
341
$ git branch -r
378
(Newly created refs are actually stored in the .git/refs directory,
379
under the path given by their name. However, for efficiency reasons
380
they may also be packed together in a single file; see
381
-gitlink:git-pack-refs[1]).
381
+linkgit:git-pack-refs[1]).
382
383
As another useful shortcut, the "HEAD" of a repository can be referred
384
to just using the name of that repository. So, for example, "origin"
387
For the complete list of paths which git checks for references, and
388
the order it uses to decide which to choose when there are multiple
389
references with the same shorthand name, see the "SPECIFYING
390
-REVISIONS" section of gitlink:git-rev-parse[1].
390
+REVISIONS" section of linkgit:git-rev-parse[1].
391
392
[[Updating-a-repository-with-git-fetch]]
393
Updating a repository with git fetch
407
-----------------------------------------
408
409
You can also track branches from repositories other than the one you
410
-cloned from, using gitlink:git-remote[1]:
410
+cloned from, using linkgit:git-remote[1]:
411
412
-------------------------------------------------
413
$ git remote add linux-nfs git://linux-nfs.org/pub/nfs-2.6.git
443
This is what causes git to track the remote's branches; you may modify
444
or delete these configuration options by editing .git/config with a
445
text editor. (See the "CONFIGURATION FILE" section of
446
-gitlink:git-config[1] for details.)
446
+linkgit:git-config[1] for details.)
447
448
[[exploring-git-history]]
449
Exploring git history
468
"master" crashes. Sometimes the best way to find the cause of such a
469
regression is to perform a brute-force search through the project's
470
history to find the particular commit that caused the problem. The
471
-gitlink:git-bisect[1] command can help you do this:
471
+linkgit:git-bisect[1] command can help you do this:
472
473
-------------------------------------------------
474
$ git bisect start
497
498
After about 13 tests (in this case), it will output the commit id of
499
the guilty commit. You can then examine the commit with
500
-gitlink:git-show[1], find out who wrote it, and mail them your bug
500
+linkgit:git-show[1], find out who wrote it, and mail them your bug
501
report with the commit id. Finally, run
502
503
-------------------------------------------------
543
- HEAD: refers to the head of the current branch
544
545
There are many more; see the "SPECIFYING REVISIONS" section of the
546
-gitlink:git-rev-parse[1] man page for the complete list of ways to
546
+linkgit:git-rev-parse[1] man page for the complete list of ways to
547
name revisions. Some examples:
548
549
-------------------------------------------------
584
which refers to the other branch that we're merging in to the current
585
branch.
586
587
-The gitlink:git-rev-parse[1] command is a low-level command that is
587
+The linkgit:git-rev-parse[1] command is a low-level command that is
588
occasionally useful for translating some name for a commit to the object
589
name for that commit:
590
608
609
This creates a "lightweight" tag. If you would also like to include a
610
comment with the tag, and possibly sign it cryptographically, then you
611
-should create a tag object instead; see the gitlink:git-tag[1] man page
611
+should create a tag object instead; see the linkgit:git-tag[1] man page
612
for details.
613
614
[[browsing-revisions]]
615
Browsing revisions
616
------------------
617
618
-The gitlink:git-log[1] command can show lists of commits. On its
618
+The linkgit:git-log[1] command can show lists of commits. On its
619
own, it shows all commits reachable from the parent commit; but you
620
can also make more specific requests:
621
645
$ git log -p
646
-------------------------------------------------
647
648
-See the "--pretty" option in the gitlink:git-log[1] man page for more
648
+See the "--pretty" option in the linkgit:git-log[1] man page for more
649
display options.
650
651
Note that git log starts with the most recent commit and works
658
----------------
659
660
You can generate diffs between any two versions using
661
-gitlink:git-diff[1]:
661
+linkgit:git-diff[1]:
662
663
-------------------------------------------------
664
$ git diff master..test
673
-------------------------------------------------
674
675
Sometimes what you want instead is a set of patches; for this you can
676
-use gitlink:git-format-patch[1]:
676
+use linkgit:git-format-patch[1]:
677
678
-------------------------------------------------
679
$ git format-patch master..test
714
-------------------------------------------------
715
716
Alternatively, you may often see this sort of thing done with the
717
-lower-level command gitlink:git-rev-list[1], which just lists the SHA1's
717
+lower-level command linkgit:git-rev-list[1], which just lists the SHA1's
718
of all the given commits:
719
720
-------------------------------------------------
772
$ gitk e05db0fd..
773
-------------------------------------------------
774
775
-Or you can use gitlink:git-name-rev[1], which will give the commit a
775
+Or you can use linkgit:git-name-rev[1], which will give the commit a
776
name based on any tag it finds pointing to one of the commit's
777
descendants:
778
781
e05db0fd tags/v1.5.0-rc1^0~23
782
-------------------------------------------------
783
784
-The gitlink:git-describe[1] command does the opposite, naming the
784
+The linkgit:git-describe[1] command does the opposite, naming the
785
revision using a tag on which the given commit is based:
786
787
-------------------------------------------------
793
given commit.
794
795
If you just want to verify whether a given tagged version contains a
796
-given commit, you could use gitlink:git-merge-base[1]:
796
+given commit, you could use linkgit:git-merge-base[1]:
797
798
-------------------------------------------------
799
$ git merge-base e05db0fd v1.5.0-rc1
814
will produce empty output if and only if v1.5.0-rc1 includes e05db0fd,
815
because it outputs only commits that are not reachable from v1.5.0-rc1.
816
817
-As yet another alternative, the gitlink:git-show-branch[1] command lists
817
+As yet another alternative, the linkgit:git-show-branch[1] command lists
818
the commits reachable from its arguments with a display on the left-hand
819
side that indicates which arguments that commit is reachable from. So,
820
you can run something like
847
head named "master" but not from any other head in your repository.
848
849
We can list all the heads in this repository with
850
-gitlink:git-show-ref[1]:
850
+linkgit:git-show-ref[1]:
851
852
-------------------------------------------------
853
$ git show-ref --heads
884
$ gitk $( git show-ref --heads ) --not $( git show-ref --tags )
885
-------------------------------------------------
886
887
-(See gitlink:git-rev-parse[1] for explanations of commit-selecting
887
+(See linkgit:git-rev-parse[1] for explanations of commit-selecting
888
syntax such as `--not`.)
889
890
[[making-a-release]]
891
Creating a changelog and tarball for a software release
892
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
893
894
-The gitlink:git-archive[1] command can create a tar or zip archive from
894
+The linkgit:git-archive[1] command can create a tar or zip archive from
895
any version of a project; for example:
896
897
-------------------------------------------------
944
-------------------------------------------------
945
946
Figuring out why this works is left as an exercise to the (advanced)
947
-student. The gitlink:git-log[1], gitlink:git-diff-tree[1], and
948
-gitlink:git-hash-object[1] man pages may prove helpful.
947
+student. The linkgit:git-log[1], linkgit:git-diff-tree[1], and
948
+linkgit:git-hash-object[1] man pages may prove helpful.
949
950
[[Developing-with-git]]
951
Developing with git
965
email = you@yourdomain.example.com
966
------------------------------------------------
967
968
-(See the "CONFIGURATION FILE" section of gitlink:git-config[1] for
968
+(See the "CONFIGURATION FILE" section of linkgit:git-config[1] for
969
details on the configuration file.)
970
971
1088
$ git status # a brief per-file summary of the above.
1089
-------------------------------------------------
1090
1091
-You can also use gitlink:git-gui[1] to create commits, view changes in
1091
+You can also use linkgit:git-gui[1] to create commits, view changes in
1092
the index and the working tree files, and individually select diff hunks
1093
for inclusion in the index (by right-clicking on the diff hunk and
1094
choosing "Stage Hunk For Commit").
1131
*.[oa]
1132
-------------------------------------------------
1133
1134
-See gitlink:gitignore[5] for a detailed explanation of the syntax. You can
1134
+See linkgit:gitignore[5] for a detailed explanation of the syntax. You can
1135
also place .gitignore files in other directories in your working tree, and they
1136
will apply to those directories and their subdirectories. The `.gitignore`
1137
files can be added to your repository like any other files (just run `git add
1144
them in a file in your repository named .git/info/exclude, or in any file
1145
specified by the `core.excludesfile` configuration variable. Some git
1146
commands can also take exclude patterns directly on the command line.
1147
-See gitlink:gitignore[5] for the details.
1147
+See linkgit:gitignore[5] for the details.
1148
1149
[[how-to-merge]]
1150
How to merge
1151
------------
1152
1153
You can rejoin two diverging branches of development using
1154
-gitlink:git-merge[1]:
1154
+linkgit:git-merge[1]:
1155
1156
-------------------------------------------------
1157
$ git merge branchname
1188
information you need to help resolve the merge.
1189
1190
Files with conflicts are marked specially in the index, so until you
1191
-resolve the problem and update the index, gitlink:git-commit[1] will
1191
+resolve the problem and update the index, linkgit:git-commit[1] will
1192
fail:
1193
1194
-------------------------------------------------
1196
file.txt: needs merge
1197
-------------------------------------------------
1198
1199
-Also, gitlink:git-status[1] will list those files as "unmerged", and the
1199
+Also, linkgit:git-status[1] will list those files as "unmerged", and the
1200
files with conflicts will have conflict markers added, like this:
1201
1202
-------------------------------------------------
1227
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1228
1229
All of the changes that git was able to merge automatically are
1230
-already added to the index file, so gitlink:git-diff[1] shows only
1230
+already added to the index file, so linkgit:git-diff[1] shows only
1231
the conflicts. It uses an unusual syntax:
1232
1233
-------------------------------------------------
1262
1263
Since the stage 2 and stage 3 versions have already been updated with
1264
nonconflicting changes, the only remaining differences between them are
1265
-the important ones; thus gitlink:git-diff[1] can use the information in
1265
+the important ones; thus linkgit:git-diff[1] can use the information in
1266
the index to show only those conflicts.
1267
1268
The diff above shows the differences between the working-tree version of
1271
column is used for differences between the first parent and the working
1272
directory copy, and the second for differences between the second parent
1273
and the working directory copy. (See the "COMBINED DIFF FORMAT" section
1274
-of gitlink:git-diff-files[1] for a details of the format.)
1274
+of linkgit:git-diff-files[1] for a details of the format.)
1275
1276
After resolving the conflict in the obvious way (but before updating the
1277
index), the diff will look like:
1304
$ git diff --theirs file.txt # same as the above.
1305
-------------------------------------------------
1306
1307
-The gitlink:git-log[1] and gitk[1] commands also provide special help
1307
+The linkgit:git-log[1] and gitk[1] commands also provide special help
1308
for merges:
1309
1310
-------------------------------------------------
1315
These will display all commits which exist only on HEAD or on
1316
MERGE_HEAD, and which touch an unmerged file.
1317
1318
-You may also use gitlink:git-mergetool[1], which lets you merge the
1318
+You may also use linkgit:git-mergetool[1], which lets you merge the
1319
unmerged files using external tools such as emacs or kdiff3.
1320
1321
Each time you resolve the conflicts in a file and update the index:
1394
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1395
1396
Creating a new commit that reverts an earlier change is very easy;
1397
-just pass the gitlink:git-revert[1] command a reference to the bad
1397
+just pass the linkgit:git-revert[1] command a reference to the bad
1398
commit; for example, to revert the most recent commit:
1399
1400
-------------------------------------------------
1437
changes, giving you a chance to edit the old commit message first.
1438
1439
Again, you should never do this to a commit that may already have
1440
-been merged into another branch; use gitlink:git-revert[1] instead in
1440
+been merged into another branch; use linkgit:git-revert[1] instead in
1441
that case.
1442
1443
It is also possible to replace commits further back in the history, but
1450
1451
In the process of undoing a previous bad change, you may find it
1452
useful to check out an older version of a particular file using
1453
-gitlink:git-checkout[1]. We've used git checkout before to switch
1453
+linkgit:git-checkout[1]. We've used git checkout before to switch
1454
branches, but it has quite different behavior if it is given a path
1455
name: the command
1456
1463
1464
If you just want to look at an old version of the file, without
1465
modifying the working directory, you can do that with
1466
-gitlink:git-show[1]:
1466
+linkgit:git-show[1]:
1467
1468
-------------------------------------------------
1469
$ git show HEAD^:path/to/file
1477
1478
While you are in the middle of working on something complicated, you
1479
find an unrelated but obvious and trivial bug. You would like to fix it
1480
-before continuing. You can use gitlink:git-stash[1] to save the current
1480
+before continuing. You can use linkgit:git-stash[1] to save the current
1481
state of your work, and after fixing the bug (or, optionally after doing
1482
so on a different branch and then coming back), unstash the
1483
work-in-progress changes.
1511
information from taking up too much space on disk or in memory.
1512
1513
This compression is not performed automatically. Therefore you
1514
-should occasionally run gitlink:git-gc[1]:
1514
+should occasionally run linkgit:git-gc[1]:
1515
1516
-------------------------------------------------
1517
$ git gc
1529
Checking the repository for corruption
1530
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1531
1532
-The gitlink:git-fsck[1] command runs a number of self-consistency checks
1532
+The linkgit:git-fsck[1] command runs a number of self-consistency checks
1533
on the repository, and reports on any problems. This may take some
1534
time. The most common warning by far is about "dangling" objects:
1535
1549
Dangling objects are not a problem. At worst they may take up a little
1550
extra disk space. They can sometimes provide a last-resort method for
1551
recovering lost work--see <<dangling-objects>> for details. However, if
1552
-you wish, you can remove them with gitlink:git-prune[1] or the `--prune`
1553
-option to gitlink:git-gc[1]:
1552
+you wish, you can remove them with linkgit:git-prune[1] or the `--prune`
1553
+option to linkgit:git-gc[1]:
1554
1555
-------------------------------------------------
1556
$ git gc --prune
1560
git-gc when run without any options), it is not safe to prune while
1561
other git operations are in progress in the same repository.
1562
1563
-If gitlink:git-fsck[1] complains about sha1 mismatches or missing
1563
+If linkgit:git-fsck[1] complains about sha1 mismatches or missing
1564
objects, you may have a much more serious problem; your best option is
1565
probably restoring from backups. See
1566
<<recovering-from-repository-corruption>> for a detailed discussion.
1573
Reflogs
1574
^^^^^^^
1575
1576
-Say you modify a branch with `gitlink:git-reset[1] --hard`, and then
1576
+Say you modify a branch with `linkgit:git-reset[1] --hard`, and then
1577
realize that the branch was the only reference you had to that point in
1578
history.
1579
1608
you've checked out.
1609
1610
The reflogs are kept by default for 30 days, after which they may be
1611
-pruned. See gitlink:git-reflog[1] and gitlink:git-gc[1] to learn
1611
+pruned. See linkgit:git-reflog[1] and linkgit:git-gc[1] to learn
1612
how to control this pruning, and see the "SPECIFYING REVISIONS"
1613
-section of gitlink:git-rev-parse[1] for details.
1613
+section of linkgit:git-rev-parse[1] for details.
1614
1615
Note that the reflog history is very different from normal git history.
1616
While normal history is shared by every repository that works on the
1675
into your own work.
1676
1677
We have already seen <<Updating-a-repository-with-git-fetch,how to
1678
-keep remote tracking branches up to date>> with gitlink:git-fetch[1],
1678
+keep remote tracking branches up to date>> with linkgit:git-fetch[1],
1679
and how to merge two branches. So you can merge in changes from the
1680
original repository's master branch with:
1681
1684
$ git merge origin/master
1685
-------------------------------------------------
1686
1687
-However, the gitlink:git-pull[1] command provides a way to do this in
1687
+However, the linkgit:git-pull[1] command provides a way to do this in
1688
one step:
1689
1690
-------------------------------------------------
1702
More generally, a branch that is created from a remote branch will pull
1703
by default from that branch. See the descriptions of the
1704
branch.<name>.remote and branch.<name>.merge options in
1705
-gitlink:git-config[1], and the discussion of the `--track` option in
1706
-gitlink:git-checkout[1], to learn how to control these defaults.
1705
+linkgit:git-config[1], and the discussion of the `--track` option in
1706
+linkgit:git-checkout[1], to learn how to control these defaults.
1707
1708
In addition to saving you keystrokes, "git pull" also helps you by
1709
producing a default commit message documenting the branch and
1731
If you just have a few changes, the simplest way to submit them may
1732
just be to send them as patches in email:
1733
1734
-First, use gitlink:git-format-patch[1]; for example:
1734
+First, use linkgit:git-format-patch[1]; for example:
1735
1736
-------------------------------------------------
1737
$ git format-patch origin
1742
1743
You can then import these into your mail client and send them by
1744
hand. However, if you have a lot to send at once, you may prefer to
1745
-use the gitlink:git-send-email[1] script to automate the process.
1745
+use the linkgit:git-send-email[1] script to automate the process.
1746
Consult the mailing list for your project first to determine how they
1747
prefer such patches be handled.
1748
1750
Importing patches to a project
1751
------------------------------
1752
1753
-Git also provides a tool called gitlink:git-am[1] (am stands for
1753
+Git also provides a tool called linkgit:git-am[1] (am stands for
1754
"apply mailbox"), for importing such an emailed series of patches.
1755
Just save all of the patch-containing messages, in order, into a
1756
single mailbox file, say "patches.mbox", then run
1785
1786
Another way to submit changes to a project is to tell the maintainer
1787
of that project to pull the changes from your repository using
1788
-gitlink:git-pull[1]. In the section "<<getting-updates-with-git-pull,
1788
+linkgit:git-pull[1]. In the section "<<getting-updates-with-git-pull,
1789
Getting updates with git pull>>" we described this as a way to get
1790
updates from the "main" repository, but it works just as well in the
1791
other direction.
1866
"<<pushing-changes-to-a-public-repository,Pushing changes to a public
1867
repository>>", below.
1868
1869
-Otherwise, all you need to do is start gitlink:git-daemon[1]; it will
1869
+Otherwise, all you need to do is start linkgit:git-daemon[1]; it will
1870
listen on port 9418. By default, it will allow access to any directory
1871
that looks like a git directory and contains the magic file
1872
git-daemon-export-ok. Passing some directory paths as git-daemon
1873
arguments will further restrict the exports to those paths.
1874
1875
You can also run git-daemon as an inetd service; see the
1876
-gitlink:git-daemon[1] man page for details. (See especially the
1876
+linkgit:git-daemon[1] man page for details. (See especially the
1877
examples section.)
1878
1879
[[exporting-via-http]]
1895
-------------------------------------------------
1896
1897
(For an explanation of the last two lines, see
1898
-gitlink:git-update-server-info[1], and the documentation
1898
+linkgit:git-update-server-info[1], and the documentation
1899
link:hooks.html[Hooks used by git].)
1900
1901
Advertise the URL of proj.git. Anybody else should then be able to
1920
access, which you will need to update the public repository with the
1921
latest changes created in your private repository.
1922
1923
-The simplest way to do this is using gitlink:git-push[1] and ssh; to
1923
+The simplest way to do this is using linkgit:git-push[1] and ssh; to
1924
update the remote branch named "master" with the latest state of your
1925
branch named "master", run
1926
1961
-------------------------------------------------
1962
1963
See the explanations of the remote.<name>.url, branch.<name>.remote,
1964
-and remote.<name>.push options in gitlink:git-config[1] for
1964
+and remote.<name>.push options in linkgit:git-config[1] for
1965
details.
1966
1967
[[forcing-push]]
2083
-------------------------------------------------
2084
2085
Linus's tree will be stored in the remote branch named origin/master,
2086
-and can be updated using gitlink:git-fetch[1]; you can track other
2087
-public trees using gitlink:git-remote[1] to set up a "remote" and
2088
-gitlink:git-fetch[1] to keep them up-to-date; see
2086
+and can be updated using linkgit:git-fetch[1]; you can track other
2087
+public trees using linkgit:git-remote[1] to set up a "remote" and
2088
+linkgit:git-fetch[1] to keep them up-to-date; see
2089
<<repositories-and-branches>>.
2090
2091
Now create the branches in which you are going to work; these start out
2092
at the current tip of origin/master branch, and should be set up (using
2093
-the --track option to gitlink:git-branch[1]) to merge changes in from
2093
+the --track option to linkgit:git-branch[1]) to merge changes in from
2094
Linus by default.
2095
2096
-------------------------------------------------
2098
$ git branch --track release origin/master
2099
-------------------------------------------------
2100
2101
-These can be easily kept up to date using gitlink:git-pull[1].
2101
+These can be easily kept up to date using linkgit:git-pull[1].
2102
2103
-------------------------------------------------
2104
$ git checkout test && git pull
2113
will become part of the permanent history when you ask Linus to pull
2114
from the release branch.
2115
2116
-A few configuration variables (see gitlink:git-config[1]) can
2116
+A few configuration variables (see linkgit:git-config[1]) can
2117
make it easy to push both branches to your public tree. (See
2118
<<setting-up-a-public-repository>>.)
2119
2127
-------------------------------------------------
2128
2129
Then you can push both the test and release trees using
2130
-gitlink:git-push[1]:
2130
+linkgit:git-push[1]:
2131
2132
-------------------------------------------------
2133
$ git push mytree
2440
2441
However, if you prefer to keep the history in mywork a simple series of
2442
commits without any merges, you may instead choose to use
2443
-gitlink:git-rebase[1]:
2443
+linkgit:git-rebase[1]:
2444
2445
-------------------------------------------------
2446
$ git checkout mywork
2491
which will replace the old commit by a new commit incorporating your
2492
changes, giving you a chance to edit the old commit message first.
2493
2494
-You can also use a combination of this and gitlink:git-rebase[1] to
2494
+You can also use a combination of this and linkgit:git-rebase[1] to
2495
replace a commit further back in your history and recreate the
2496
intervening changes on top of it. First, tag the problematic commit
2497
with
2529
Reordering or selecting from a patch series
2530
-------------------------------------------
2531
2532
-Given one existing commit, the gitlink:git-cherry-pick[1] command
2532
+Given one existing commit, the linkgit:git-cherry-pick[1] command
2533
allows you to apply the change introduced by that commit and create a
2534
new commit that records it. So, for example, if "mywork" points to a
2535
series of patches on top of "origin", you might do something like:
2542
and browse through the list of patches in the mywork branch using gitk,
2543
applying them (possibly in a different order) to mywork-new using
2544
cherry-pick, and possibly modifying them as you go using `commit --amend`.
2545
-The gitlink:git-gui[1] command may also help as it allows you to
2545
+The linkgit:git-gui[1] command may also help as it allows you to
2546
individually select diff hunks for inclusion in the index (by
2547
right-clicking on the diff hunk and choosing "Stage Hunk for Commit").
2548
2555
-------------------------------------------------
2556
2557
Then modify, reorder, or eliminate patches as preferred before applying
2558
-them again with gitlink:git-am[1].
2558
+them again with linkgit:git-am[1].
2559
2560
[[patch-series-tools]]
2561
Other tools
2618
Why bisecting merge commits can be harder than bisecting linear history
2619
-----------------------------------------------------------------------
2620
2621
-The gitlink:git-bisect[1] command correctly handles history that
2621
+The linkgit:git-bisect[1] command correctly handles history that
2622
includes merge commits. However, when the commit that it finds is a
2623
merge commit, the user may need to work harder than usual to figure out
2624
why that commit introduced a problem.
2651
on the lower line of development have not been converted to the new
2652
semantics introduced on the upper line of development. So if all
2653
you know is that D is bad, that Z is good, and that
2654
-gitlink:git-bisect[1] identifies C as the culprit, how will you
2654
+linkgit:git-bisect[1] identifies C as the culprit, how will you
2655
figure out that the problem is due to this change in semantics?
2656
2657
When the result of a git-bisect is a non-merge commit, you should
2688
Fetching individual branches
2689
----------------------------
2690
2691
-Instead of using gitlink:git-remote[1], you can also choose just
2691
+Instead of using linkgit:git-remote[1], you can also choose just
2692
to update one branch at a time, and to store it locally under an
2693
arbitrary name:
2694
2779
We saw above that "origin" is just a shortcut to refer to the
2780
repository that you originally cloned from. This information is
2781
stored in git configuration variables, which you can see using
2782
-gitlink:git-config[1]:
2782
+linkgit:git-config[1]:
2783
2784
-------------------------------------------------
2785
$ git config -l
2832
2833
Also note that all of the above configuration can be performed by
2834
directly editing the file .git/config instead of using
2835
-gitlink:git-config[1].
2835
+linkgit:git-config[1].
2836
2837
-See gitlink:git-config[1] for more details on the configuration
2837
+See linkgit:git-config[1] for more details on the configuration
2838
options mentioned above.
2839
2840
2900
2901
The "commit" object links a physical state of a tree with a description
2902
of how we got there and why. Use the --pretty=raw option to
2903
-gitlink:git-show[1] or gitlink:git-log[1] to examine your favorite
2903
+linkgit:git-show[1] or linkgit:git-log[1] to examine your favorite
2904
commit:
2905
2906
------------------------------------------------
2941
its parents. In particular, git does not attempt to record file renames
2942
explicitly, though it can identify cases where the existence of the same
2943
file data at changing paths suggests a rename. (See, for example, the
2944
--M option to gitlink:git-diff[1]).
2944
+-M option to linkgit:git-diff[1]).
2945
2946
-A commit is usually created by gitlink:git-commit[1], which creates a
2946
+A commit is usually created by linkgit:git-commit[1], which creates a
2947
commit whose parent is normally the current HEAD, and whose tree is
2948
taken from the content currently stored in the index.
2949
2951
Tree Object
2952
~~~~~~~~~~~
2953
2954
-The ever-versatile gitlink:git-show[1] command can also be used to
2955
-examine tree objects, but gitlink:git-ls-tree[1] will give you more
2954
+The ever-versatile linkgit:git-show[1] command can also be used to
2955
+examine tree objects, but linkgit:git-ls-tree[1] will give you more
2956
details:
2957
2958
------------------------------------------------
2991
Blob Object
2992
~~~~~~~~~~~
2993
2994
-You can use gitlink:git-show[1] to examine the contents of a blob; take,
2994
+You can use linkgit:git-show[1] to examine the contents of a blob; take,
2995
for example, the blob in the entry for "COPYING" from the tree above:
2996
2997
------------------------------------------------
3013
renaming a file does not change the object that file is associated with.
3014
3015
Note that any tree or blob object can be examined using
3016
-gitlink:git-show[1] with the <revision>:<path> syntax. This can
3016
+linkgit:git-show[1] with the <revision>:<path> syntax. This can
3017
sometimes be useful for browsing the contents of a tree that is not
3018
currently checked out.
3019
3053
3054
A tag object contains an object, object type, tag name, the name of the
3055
person ("tagger") who created the tag, and a message, which may contain
3056
-a signature, as can be seen using the gitlink:git-cat-file[1]:
3056
+a signature, as can be seen using the linkgit:git-cat-file[1]:
3057
3058
------------------------------------------------
3059
$ git cat-file tag v1.5.0
3072
-----END PGP SIGNATURE-----
3073
------------------------------------------------
3074
3075
-See the gitlink:git-tag[1] command to learn how to create and verify tag
3076
-objects. (Note that gitlink:git-tag[1] can also be used to create
3075
+See the linkgit:git-tag[1] command to learn how to create and verify tag
3076
+objects. (Note that linkgit:git-tag[1] can also be used to create
3077
"lightweight tags", which are not tag objects at all, but just simple
3078
references whose names begin with "refs/tags/").
3079
3135
Although the object files are gone, any commands that refer to those
3136
objects will work exactly as they did before.
3137
3138
-The gitlink:git-gc[1] command performs packing, pruning, and more for
3138
+The linkgit:git-gc[1] command performs packing, pruning, and more for
3139
you, so is normally the only high-level command you need.
3140
3141
[[dangling-objects]]
3142
Dangling objects
3143
~~~~~~~~~~~~~~~~
3144
3145
-The gitlink:git-fsck[1] command will sometimes complain about dangling
3145
+The linkgit:git-fsck[1] command will sometimes complain about dangling
3146
objects. They are not a problem.
3147
3148
The most common cause of dangling objects is that you've rebased a
3246
especially commits is *much* harder).
3247
3248
Before starting, verify that there is corruption, and figure out where
3249
-it is with gitlink:git-fsck[1]; this may be time-consuming.
3249
+it is with linkgit:git-fsck[1]; this may be time-consuming.
3250
3251
Assume the output looks like this:
3252
3264
points to it. If you could find just one copy of that missing blob
3265
object, possibly in some other repository, you could move it into
3266
.git/objects/4b/9458b3... and be done. Suppose you can't. You can
3267
-still examine the tree that pointed to it with gitlink:git-ls-tree[1],
3267
+still examine the tree that pointed to it with linkgit:git-ls-tree[1],
3268
which might output something like:
3269
3270
------------------------------------------------
3282
say it's in "somedirectory". If you're lucky the missing copy might be
3283
the same as the copy you have checked out in your working tree at
3284
"somedirectory/myfile"; you can test whether that's right with
3285
-gitlink:git-hash-object[1]:
3285
+linkgit:git-hash-object[1]:
3286
3287
------------------------------------------------
3288
$ git hash-object -w somedirectory/myfile
3352
3353
The index is a binary file (generally kept in .git/index) containing a
3354
sorted list of path names, each with permissions and the SHA1 of a blob
3355
-object; gitlink:git-ls-files[1] can show you the contents of the index:
3355
+object; linkgit:git-ls-files[1] can show you the contents of the index:
3356
3357
-------------------------------------------------
3358
$ git ls-files --stage
3374
1. The index contains all the information necessary to generate a single
3375
(uniquely determined) tree object.
3376
+
3377
-For example, running gitlink:git-commit[1] generates this tree object
3377
+For example, running linkgit:git-commit[1] generates this tree object
3378
from the index, stores it in the object database, and uses it as the
3379
tree object associated with the new commit.
3380
3395
+
3396
We saw in <<conflict-resolution>> that during a merge the index can
3397
store multiple versions of a single file (called "stages"). The third
3398
-column in the gitlink:git-ls-files[1] output above is the stage
3398
+column in the linkgit:git-ls-files[1] output above is the stage
3399
number, and will take on values other than 0 for files with merge
3400
conflicts.
3401
3444
Partial checkouts of the superproject are possible: you can tell Git to
3445
clone none, some or all of the submodules.
3446
3447
-The gitlink:git-submodule[1] command is available since Git 1.5.3. Users
3447
+The linkgit:git-submodule[1] command is available since Git 1.5.3. Users
3448
with Git 1.5.2 can look up the submodule commits in the repository and
3449
manually check them out; earlier versions won't recognize the submodules at
3450
all.
3492
3493
- It clones the submodule under the current directory and by default checks out
3494
the master branch.
3495
-- It adds the submodule's clone path to the gitlink:gitmodules[5] file and
3495
+- It adds the submodule's clone path to the linkgit:gitmodules[5] file and
3496
adds this file to the index, ready to be committed.
3497
- It adds the submodule's current commit ID to the index, ready to be
3498
committed.
3653
Object access and manipulation
3654
------------------------------
3655
3656
-The gitlink:git-cat-file[1] command can show the contents of any object,
3657
-though the higher-level gitlink:git-show[1] is usually more useful.
3656
+The linkgit:git-cat-file[1] command can show the contents of any object,
3657
+though the higher-level linkgit:git-show[1] is usually more useful.
3658
3659
-The gitlink:git-commit-tree[1] command allows constructing commits with
3659
+The linkgit:git-commit-tree[1] command allows constructing commits with
3660
arbitrary parents and trees.
3661
3662
-A tree can be created with gitlink:git-write-tree[1] and its data can be
3663
-accessed by gitlink:git-ls-tree[1]. Two trees can be compared with
3664
-gitlink:git-diff-tree[1].
3662
+A tree can be created with linkgit:git-write-tree[1] and its data can be
3663
+accessed by linkgit:git-ls-tree[1]. Two trees can be compared with
3664
+linkgit:git-diff-tree[1].
3665
3666
-A tag is created with gitlink:git-mktag[1], and the signature can be
3667
-verified by gitlink:git-verify-tag[1], though it is normally simpler to
3668
-use gitlink:git-tag[1] for both.
3666
+A tag is created with linkgit:git-mktag[1], and the signature can be
3667
+verified by linkgit:git-verify-tag[1], though it is normally simpler to
3668
+use linkgit:git-tag[1] for both.
3669
3670
[[the-workflow]]
3671
The Workflow
3672
------------
3673
3674
-High-level operations such as gitlink:git-commit[1],
3675
-gitlink:git-checkout[1] and gitlink:git-reset[1] work by moving data
3674
+High-level operations such as linkgit:git-commit[1],
3675
+linkgit:git-checkout[1] and linkgit:git-reset[1] work by moving data
3676
between the working tree, the index, and the object database. Git
3677
provides low-level operations which perform each of these steps
3678
individually.
3687
working directory -> index
3688
~~~~~~~~~~~~~~~~~~~~~~~~~~
3689
3690
-The gitlink:git-update-index[1] command updates the index with
3690
+The linkgit:git-update-index[1] command updates the index with
3691
information from the working directory. You generally update the
3692
index information by just specifying the filename you want to update,
3693
like so:
3717
it will only update the fields that are used to quickly test whether
3718
an object still matches its old backing store object.
3719
3720
-The previously introduced gitlink:git-add[1] is just a wrapper for
3721
-gitlink:git-update-index[1].
3720
+The previously introduced linkgit:git-add[1] is just a wrapper for
3721
+linkgit:git-update-index[1].
3722
3723
[[index-to-object-database]]
3724
index -> object database
3865
3866
You can examine the data represented in the object database and the
3867
index with various helper tools. For every object, you can use
3868
-gitlink:git-cat-file[1] to examine details about the
3868
+linkgit:git-cat-file[1] to examine details about the
3869
object:
3870
3871
-------------------------------------------------
4528
- howto's
4529
- some of technical/?
4530
- hooks
4531
-- list of commands in gitlink:git[1]
4531
+- list of commands in linkgit:git[1]
4532
4533
Scan email archives for other stuff left out
4534