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

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.