Documentation: reorder development section, todo's
Update todo's. Split out "sharing development" section into a separate chapter, reorder. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
J. Bruce Fields committed
Jan 8, 2007 at 23:42 UTC
b684f830cc071c99ede9861c84e3b1e54549f6c7
1 file changed
+123
-120
Documentation/user-manual.txt
+123
-120
@@ -1024,6 +1024,109 @@ already contained in the other--then git just performs a
1024
moved forward to point at the head of the merged-in branch, without
1025
any new commits being created.
1026
1027
+Fixing mistakes
1028
+---------------
1029
+
1030
+If you've messed up the working tree, but haven't yet committed your
1031
+mistake, you can return the entire working tree to the last committed
1032
+state with
1033
+
1034
+-------------------------------------------------
1035
+$ git reset --hard HEAD
1036
+-------------------------------------------------
1037
+
1038
+If you make a commit that you later wish you hadn't, there are two
1039
+fundamentally different ways to fix the problem:
1040
+
1041
+ 1. You can create a new commit that undoes whatever was done
1042
+ by the previous commit. This is the correct thing if your
1043
+ mistake has already been made public.
1044
+
1045
+ 2. You can go back and modify the old commit. You should
1046
+ never do this if you have already made the history public;
1047
+ git does not normally expect the "history" of a project to
1048
+ change, and cannot correctly perform repeated merges from
1049
+ a branch that has had its history changed.
1050
+
1051
+Fixing a mistake with a new commit
1052
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1053
+
1054
+Creating a new commit that reverts an earlier change is very easy;
1055
+just pass the gitlink:git-revert[1] command a reference to the bad
1056
+commit; for example, to revert the most recent commit:
1057
+
1058
+-------------------------------------------------
1059
+$ git revert HEAD
1060
+-------------------------------------------------
1061
+
1062
+This will create a new commit which undoes the change in HEAD. You
1063
+will be given a chance to edit the commit message for the new commit.
1064
+
1065
+You can also revert an earlier change, for example, the next-to-last:
1066
+
1067
+-------------------------------------------------
1068
+$ git revert HEAD^
1069
+-------------------------------------------------
1070
+
1071
+In this case git will attempt to undo the old change while leaving
1072
+intact any changes made since then. If more recent changes overlap
1073
+with the changes to be reverted, then you will be asked to fix
1074
+conflicts manually, just as in the case of <<resolving-a-merge,
1075
+resolving a merge>>.
1076
+
1077
+Fixing a mistake by editing history
1078
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1079
+
1080
+If the problematic commit is the most recent commit, and you have not
1081
+yet made that commit public, then you may just
1082
+<<undoing-a-merge,destroy it using git-reset>>.
1083
+
1084
+Alternatively, you
1085
+can edit the working directory and update the index to fix your
1086
+mistake, just as if you were going to <<how-to-make-a-commit,create a
1087
+new commit>>, then run
1088
+
1089
+-------------------------------------------------
1090
+$ git commit --amend
1091
+-------------------------------------------------
1092
+
1093
+which will replace the old commit by a new commit incorporating your
1094
+changes, giving you a chance to edit the old commit message first.
1095
+
1096
+Again, you should never do this to a commit that may already have
1097
+been merged into another branch; use gitlink:git-revert[1] instead in
1098
+that case.
1099
+
1100
+It is also possible to edit commits further back in the history, but
1101
+this is an advanced topic to be left for
1102
+<<cleaning-up-history,another chapter>>.
1103
+
1104
+Checking out an old version of a file
1105
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1106
+
1107
+In the process of undoing a previous bad change, you may find it
1108
+useful to check out an older version of a particular file using
1109
+gitlink:git-checkout[1]. We've used git checkout before to switch
1110
+branches, but it has quite different behavior if it is given a path
1111
+name: the command
1112
+
1113
+-------------------------------------------------
1114
+$ git checkout HEAD^ path/to/file
1115
+-------------------------------------------------
1116
+
1117
+replaces path/to/file by the contents it had in the commit HEAD^, and
1118
+also updates the index to match. It does not change branches.
1119
+
1120
+If you just want to look at an old version of the file, without
1121
+modifying the working directory, you can do that with
1122
+gitlink:git-show[1]:
1123
+
1124
+-------------------------------------------------
1125
+$ git show HEAD^ path/to/file
1126
+-------------------------------------------------
1127
+
1128
+which will display the given version of the file.
1129
+
1130
Ensuring good performance
1131
-------------------------
1132
@@ -1043,11 +1146,11 @@ you should not modify the repository while it is working, so you
1146
should run it while you are not working.
1147
1148
Sharing development with others
1046
--------------------------------
1149
+===============================
1150
1151
[[getting-updates-with-git-pull]]
1152
Getting updates with git pull
1050
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1153
+-----------------------------
1154
1155
After you clone a repository and make a few changes of your own, you
1156
may wish to check the original repository for updates and merge them
@@ -1102,7 +1205,7 @@ $ git merge branch
1205
are roughly equivalent. The former is actually very commonly used.
1206
1207
Submitting patches to a project
1105
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1208
+-------------------------------
1209
1210
If you just have a few changes, the simplest way to submit them may
1211
just be to send them as patches in email:
@@ -1123,7 +1226,7 @@ Consult the mailing list for your project first to determine how they
1226
prefer such patches be handled.
1227
1228
Importing patches to a project
1126
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1229
+------------------------------
1230
1231
Git also provides a tool called gitlink:git-am[1] (am stands for
1232
"apply mailbox"), for importing such an emailed series of patches.
@@ -1153,7 +1256,7 @@ taken from the message containing each patch.
1256
1257
[[setting-up-a-public-repository]]
1258
Setting up a public repository
1156
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1259
+------------------------------
1260
1261
Another way to submit changes to a project is to simply tell the
1262
maintainer of that project to pull from your repository, exactly as
@@ -1219,7 +1322,7 @@ created public repository:
1322
1323
[[exporting-via-http]]
1324
Exporting a git repository via http
1222
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1325
+-----------------------------------
1326
1327
The git protocol gives better performance and reliability, but on a
1328
host with a web server set up, http exports may be simpler to set up.
@@ -1253,7 +1356,7 @@ allows pushing over http.)
1356
1357
[[exporting-via-git]]
1358
Exporting a git repository via the git protocol
1256
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1359
+-----------------------------------------------
1360
1361
This is the preferred method.
1362
@@ -1262,7 +1365,7 @@ instructions. (See especially the examples section.)
1365
1366
[[pushing-changes-to-a-public-repository]]
1367
Pushing changes to a public repository
1265
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1368
+--------------------------------------
1369
1370
Note that the two techniques outline above (exporting via
1371
<<exporting-via-http,http>> or <<exporting-via-git,git>>) allow other
@@ -1315,7 +1418,7 @@ and remote.<name>.push options in gitlink:git-repo-config[1] for
1418
details.
1419
1420
Setting up a shared repository
1318
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1421
+------------------------------
1422
1423
Another way to collaborate is by using a model similar to that
1424
commonly used in CVS, where several developers with special rights
@@ -1323,108 +1426,16 @@ all push to and pull from a single shared repository. See
1426
link:cvs-migration.txt[git for CVS users] for instructions on how to
1427
set this up.
1428
1326
-Fixing mistakes
1327
----------------
1328
-
1329
-If you've messed up the working tree, but haven't yet committed your
1330
-mistake, you can return the entire working tree to the last committed
1331
-state with
1332
-
1333
--------------------------------------------------
1334
-$ git reset --hard HEAD
1335
--------------------------------------------------
1336
-
1337
-If you make a commit that you later wish you hadn't, there are two
1338
-fundamentally different ways to fix the problem:
1339
-
1340
- 1. You can create a new commit that undoes whatever was done
1341
- by the previous commit. This is the correct thing if your
1342
- mistake has already been made public.
1343
-
1344
- 2. You can go back and modify the old commit. You should
1345
- never do this if you have already made the history public;
1346
- git does not normally expect the "history" of a project to
1347
- change, and cannot correctly perform repeated merges from
1348
- a branch that has had its history changed.
1349
-
1350
-Fixing a mistake with a new commit
1351
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1352
-
1353
-Creating a new commit that reverts an earlier change is very easy;
1354
-just pass the gitlink:git-revert[1] command a reference to the bad
1355
-commit; for example, to revert the most recent commit:
1356
-
1357
--------------------------------------------------
1358
-$ git revert HEAD
1359
--------------------------------------------------
1360
-
1361
-This will create a new commit which undoes the change in HEAD. You
1362
-will be given a chance to edit the commit message for the new commit.
1363
-
1364
-You can also revert an earlier change, for example, the next-to-last:
1365
-
1366
--------------------------------------------------
1367
-$ git revert HEAD^
1368
--------------------------------------------------
1369
-
1370
-In this case git will attempt to undo the old change while leaving
1371
-intact any changes made since then. If more recent changes overlap
1372
-with the changes to be reverted, then you will be asked to fix
1373
-conflicts manually, just as in the case of <<resolving-a-merge,
1374
-resolving a merge>>.
1375
-
1376
-Fixing a mistake by editing history
1377
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1429
+Allow web browsing of a repository
1430
+----------------------------------
1431
1379
-If the problematic commit is the most recent commit, and you have not
1380
-yet made that commit public, then you may just
1381
-<<undoing-a-merge,destroy it using git-reset>>.
1432
+TODO: Brief setup-instructions for gitweb
1433
1383
-Alternatively, you
1384
-can edit the working directory and update the index to fix your
1385
-mistake, just as if you were going to <<how-to-make-a-commit,create a
1386
-new commit>>, then run
1434
+Examples
1435
+--------
1436
1388
--------------------------------------------------
1389
-$ git commit --amend
1390
--------------------------------------------------
1437
+TODO: topic branches, typical roles as in everyday.txt, ?
1438
1392
-which will replace the old commit by a new commit incorporating your
1393
-changes, giving you a chance to edit the old commit message first.
1394
-
1395
-Again, you should never do this to a commit that may already have
1396
-been merged into another branch; use gitlink:git-revert[1] instead in
1397
-that case.
1398
-
1399
-It is also possible to edit commits further back in the history, but
1400
-this is an advanced topic to be left for
1401
-<<cleaning-up-history,another chapter>>.
1402
-
1403
-Checking out an old version of a file
1404
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1405
-
1406
-In the process of undoing a previous bad change, you may find it
1407
-useful to check out an older version of a particular file using
1408
-gitlink:git-checkout[1]. We've used git checkout before to switch
1409
-branches, but it has quite different behavior if it is given a path
1410
-name: the command
1411
-
1412
--------------------------------------------------
1413
-$ git checkout HEAD^ path/to/file
1414
--------------------------------------------------
1415
-
1416
-replaces path/to/file by the contents it had in the commit HEAD^, and
1417
-also updates the index to match. It does not change branches.
1418
-
1419
-If you just want to look at an old version of the file, without
1420
-modifying the working directory, you can do that with
1421
-gitlink:git-show[1]:
1422
-
1423
--------------------------------------------------
1424
-$ git show HEAD^ path/to/file
1425
--------------------------------------------------
1426
-
1427
-which will display the given version of the file.
1439
1440
Working with other version control systems
1441
==========================================
@@ -1623,10 +1634,8 @@ Scan email archives for other stuff left out
1634
Scan man pages to see if any assume more background than this manual
1635
provides.
1636
1626
-Mention of gitweb.
1627
-
1628
-Update git fetch discussion to use "git remote" setup. That will
1629
-make things simpler. Maybe wait till git remote is done.
1637
+Update git fetch discussion to use "git remote", move most of branch
1638
+discussion till later.
1639
1640
Can also simplify beginning by suggesting disconnected head instead
1641
of temporary branch creation.
@@ -1636,18 +1645,12 @@ section: diff -1, -2, -3, --ours, --theirs :1:/path notation. The
1645
"git ls-files --unmerged --stage" thing is sorta useful too, actually. And
1646
note gitk --merge. Also what's easiest way to see common merge base?
1647
1639
-Add more good examples. Entire sections of just cookbook examples might be a
1640
-good idea; maybe make an "advanced examples" section a standard end-of-chapter
1641
-section?
1648
+Add more good examples. Entire sections of just cookbook examples might
1649
+be a good idea; maybe make an "advanced examples" section a standard
1650
+end-of-chapter section?
1651
1652
Include cross-references to the glossary, where appropriate.
1653
1645
-Update for detached-head.
1646
-
1647
-Update for git-remote. Even if the command isn't there yet, I think we should
1648
-probably just document the repository configuration necessary to set it up, as
1649
-the default way to keep a repository up-to-date.
1650
-
1654
To document:
1655
reflogs, git reflog expire
1656
shallow clones?? See draft 1.5.0 release notes for some documentation.