From 0bc25a78428a7dc3a3acf00eb9637424419c3afd Mon Sep 17 00:00:00 2001 From: "J. Bruce Fields" Date: Tue, 6 Feb 2007 02:51:26 -0500 Subject: [PATCH 1/8] Documentation: mention module option to git-cvsimport The git-cvsimport argument that specifies a cvs module to import should probably be included in the default example. Signed-off-by: "J. Bruce Fields" Signed-off-by: Junio C Hamano --- Documentation/cvs-migration.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/cvs-migration.txt b/Documentation/cvs-migration.txt index 764cc560b4..3b6b494162 100644 --- a/Documentation/cvs-migration.txt +++ b/Documentation/cvs-migration.txt @@ -109,7 +109,7 @@ sure it is in your path. Then cd to a checked out CVS working directory of the project you are interested in and run gitlink:git-cvsimport[1]: ------------------------------------------- -$ git cvsimport -C +$ git cvsimport -C ------------------------------------------- This puts a git archive of the named CVS module in the directory From 1c73bb0ef7bf6632d1aa5d6760bba7ea4e336fe9 Mon Sep 17 00:00:00 2001 From: "J. Bruce Fields" Date: Mon, 19 Feb 2007 18:46:09 -0500 Subject: [PATCH 2/8] user-manual: reset to ORIG_HEAD not HEAD to undo merge As Linus pointed out recently on the mailing list, git reset --hard HEAD^ doesn't undo a merge in the case where the merge did a fast-forward. So the rcommendation here is a little dangerous. Signed-off-by: "J. Bruce Fields" Signed-off-by: Junio C Hamano --- Documentation/user-manual.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index 7b6dc22e7b..e37a1234fa 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -1255,7 +1255,7 @@ $ git reset --hard HEAD Or, if you've already commited the merge that you want to throw away, ------------------------------------------------- -$ git reset --hard HEAD^ +$ git reset --hard ORIG_HEAD ------------------------------------------------- However, this last command can be dangerous in some cases--never From 1c95c565c2472a07be8316f2658e7100e62bf94d Mon Sep 17 00:00:00 2001 From: "J. Bruce Fields" Date: Sat, 3 Mar 2007 13:33:48 -0500 Subject: [PATCH 3/8] user-manual: ensure generated manual references stylesheet The generated user manual is rather hard to read thanks to the lack of the css that's supposed to be included from docbook-xsl.css. I'm totally ignorant of the toolchain; grubbing through xmlto and related scripts, the easiest way I could find to ensure that the generated html links to the stylesheet is by calling xsltproc directly. Maybe there's some better way. Signed-off-by: "J. Bruce Fields" Signed-off-by: Junio C Hamano --- Documentation/Makefile | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/Documentation/Makefile b/Documentation/Makefile index b6d1d8824f..7c1c9e1918 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -105,8 +105,11 @@ clean: user-manual.xml: user-manual.txt user-manual.conf $(ASCIIDOC) -b docbook -d book $< +XSLT = http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl +XSLTOPTS = --nonet --xinclude --stringparam html.stylesheet docbook-xsl.css + user-manual.html: user-manual.xml - xmlto html-nochunks $< + xsltproc $(XSLTOPTS) -o $@ $(XSLT) $< glossary.html : glossary.txt sort_glossary.pl cat $< | \ From 3512193034cbc5207a955d6c4c8506f028d48f2d Mon Sep 17 00:00:00 2001 From: "J. Bruce Fields" Date: Sat, 3 Mar 2007 14:04:42 -0500 Subject: [PATCH 4/8] user-manual: insert earlier of mention content-addressable architecture The content-addressable design is too important not to be worth at least a brief mention a little earlier on. Signed-off-by: "J. Bruce Fields" Signed-off-by: Junio C Hamano --- Documentation/user-manual.txt | 24 +++++++++++++++--------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index e37a1234fa..5625df2a5a 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -391,15 +391,20 @@ index 8be626f..d7aac9d 100644 As you can see, a commit shows who made the latest change, what they did, and why. -Every commit has a 40-hexdigit id, sometimes called the "object name" -or the "SHA1 id", shown on the first line of the "git show" output. -You can usually refer to a commit by a shorter name, such as a tag or a -branch name, but this longer name can also be useful. Most -importantly, it is a globally unique name for this commit: so if you -tell somebody else the object name (for example in email), then you are -guaranteed that name will refer to the same commit in their repository -that it does in yours (assuming their repository has that commit at -all). +Every commit has a 40-hexdigit id, sometimes called the "object name" or the +"SHA1 id", shown on the first line of the "git show" output. You can usually +refer to a commit by a shorter name, such as a tag or a branch name, but this +longer name can also be useful. Most importantly, it is a globally unique +name for this commit: so if you tell somebody else the object name (for +example in email), then you are guaranteed that name will refer to the same +commit in their repository that it does in yours (assuming their repository +has that commit at all). Since the object name is computed as a hash over the +contents of the commit, you are guaranteed that the commit can never change +without its name also changing. + +In fact, in <> we shall see that everything stored in git +history, including file data and directory contents, is stored in an object +with a name that is a hash of its contents. Understanding history: commits, parents, and reachability ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -2155,6 +2160,7 @@ See gitlink:git-config[1] for more details on the configuration options mentioned above. +[[git-internals]] Git internals ============= From 365aa199196c8665e978ec7092323167621a69ea Mon Sep 17 00:00:00 2001 From: "J. Bruce Fields" Date: Sat, 3 Mar 2007 14:30:32 -0500 Subject: [PATCH 5/8] user-manual: how to replace commits older than most recent "Modifying" an old commit by checking it out, --amend'ing it, then rebasing on top of it, is a slightly cumbersome technique, but I've found it useful frequently enough to make it seem worth documenting. Signed-off-by: "J. Bruce Fields" Signed-off-by: Junio C Hamano --- Documentation/user-manual.txt | 46 +++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index 5625df2a5a..b80300e374 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -1333,6 +1333,7 @@ with the changes to be reverted, then you will be asked to fix conflicts manually, just as in the case of <>. +[[fixing-a-mistake-by-editing-history]] Fixing a mistake by editing history ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1935,6 +1936,51 @@ return mywork to the state it had before you started the rebase: $ git rebase --abort ------------------------------------------------- +Modifying a single commit +------------------------- + +We saw in <> that you can replace the +most recent commit using + +------------------------------------------------- +$ git commit --amend +------------------------------------------------- + +which will replace the old commit by a new commit incorporating your +changes, giving you a chance to edit the old commit message first. + +You can also use a combination of this and gitlink:git-rebase[1] to edit +commits further back in your history. First, tag the problematic commit with + +------------------------------------------------- +$ git tag bad mywork~5 +------------------------------------------------- + +(Either gitk or git-log may be useful for finding the commit.) + +Then check out a new branch at that commit, edit it, and rebase the rest of +the series on top of it: + +------------------------------------------------- +$ git checkout -b TMP bad +$ # make changes here and update the index +$ git commit --amend +$ git rebase --onto TMP bad mywork +------------------------------------------------- + +When you're done, you'll be left with mywork checked out, with the top patches +on mywork reapplied on top of the modified commit you created in TMP. You can +then clean up with + +------------------------------------------------- +$ git branch -d TMP +$ git tag -d bad +------------------------------------------------- + +Note that the immutable nature of git history means that you haven't really +"modified" existing commits; instead, you have replaced the old commits with +new commits having new object names. + Reordering or selecting from a patch series ------------------------------------------- From ef561ac7380cae589549237c804ad88e8dd449ef Mon Sep 17 00:00:00 2001 From: "J. Bruce Fields" Date: Sat, 3 Mar 2007 15:34:27 -0500 Subject: [PATCH 6/8] user-manual: more detailed merge discussion Add more details on conflict, including brief discussion of file stages. Signed-off-by: "J. Bruce Fields" Signed-off-by: Junio C Hamano --- Documentation/user-manual.txt | 102 +++++++++++++++++++++++++--------- 1 file changed, 77 insertions(+), 25 deletions(-) diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index b80300e374..a5e7b536f2 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -1168,18 +1168,46 @@ the working tree in a special state that gives you all the information you need to help resolve the merge. Files with conflicts are marked specially in the index, so until you -resolve the problem and update the index, git commit will fail: +resolve the problem and update the index, gitlink:git-commit[1] will +fail: ------------------------------------------------- $ git commit file.txt: needs merge ------------------------------------------------- -Also, git status will list those files as "unmerged". +Also, gitlink:git-status[1] will list those files as "unmerged", and the +files with conflicts will have conflict markers added, like this: + +------------------------------------------------- +<<<<<<< HEAD:file.txt +Hello world +======= +Goodbye +>>>>>>> 77976da35a11db4580b80ae27e8d65caf5208086:file.txt +------------------------------------------------- + +All you need to do is edit the files to resolve the conflicts, and then + +------------------------------------------------- +$ git add file.txt +$ git commit +------------------------------------------------- + +Note that the commit message will already be filled in for you with +some information about the merge. Normally you can just use this +default message unchanged, but you may add additional commentary of +your own if desired. + +The above is all you need to know to resolve a simple merge. But git +also provides more information to help resolve conflicts: + +Getting conflict-resolution help during a merge +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ All of the changes that git was able to merge automatically are already added to the index file, so gitlink:git-diff[1] shows only -the conflicts. Also, it uses a somewhat unusual syntax: +the conflicts. It uses an unusual syntax: ------------------------------------------------- $ git diff @@ -1200,14 +1228,32 @@ conflict will have two parents instead of the usual one: one parent will be HEAD, the tip of the current branch; the other will be the tip of the other branch, which is stored temporarily in MERGE_HEAD. -The diff above shows the differences between the working-tree version -of file.txt and two previous versions: one version from HEAD, and one -from MERGE_HEAD. So instead of preceding each line by a single "+" -or "-", it now uses two columns: the first column is used for -differences between the first parent and the working directory copy, -and the second for differences between the second parent and the -working directory copy. Thus after resolving the conflict in the -obvious way, the diff will look like: +During the merge, the index holds three versions of each file. Each of +these three "file stages" represents a different version of the file: + +------------------------------------------------- +$ git show :1:file.txt # the file in a common ancestor of both branches +$ git show :2:file.txt # the version from HEAD, but including any + # nonconflicting changes from MERGE_HEAD +$ git show :3:file.txt # the version from MERGE_HEAD, but including any + # nonconflicting changes from HEAD. +------------------------------------------------- + +Since the stage 2 and stage 3 versions have already been updated with +nonconflicting changes, the only remaining differences between them are +the important ones; thus gitlink:git-diff[1] can use the information in +the index to show only those conflicts. + +The diff above shows the differences between the working-tree version of +file.txt and the stage 2 and stage 3 versions. So instead of preceding +each line by a single "+" or "-", it now uses two columns: the first +column is used for differences between the first parent and the working +directory copy, and the second for differences between the second parent +and the working directory copy. (See the "COMBINED DIFF FORMAT" section +of gitlink:git-diff-files[1] for a details of the format.) + +After resolving the conflict in the obvious way (but before updating the +index), the diff will look like: ------------------------------------------------- $ git diff @@ -1225,26 +1271,37 @@ This shows that our resolved version deleted "Hello world" from the first parent, deleted "Goodbye" from the second parent, and added "Goodbye world", which was previously absent from both. -The gitlink:git-log[1] command also provides special help for merges: +Some special diff options allow diffing the working directory against +any of these stages: + +------------------------------------------------- +$ git diff -1 file.txt # diff against stage 1 +$ git diff --base file.txt # same as the above +$ git diff -2 file.txt # diff against stage 2 +$ git diff --ours file.txt # same as the above +$ git diff -3 file.txt # diff against stage 3 +$ git diff --theirs file.txt # same as the above. +------------------------------------------------- + +The gitlink:git-log[1] and gitk[1] commands also provide special help +for merges: ------------------------------------------------- $ git log --merge +$ gitk --merge ------------------------------------------------- -This will list all commits which exist only on HEAD or on MERGE_HEAD, -and which touch an unmerged file. +These will display all commits which exist only on HEAD or on +MERGE_HEAD, and which touch an unmerged file. -We can now add the resolved version to the index and commit: +Each time you resolve the conflicts in a file and update the index: ------------------------------------------------- $ git add file.txt -$ git commit ------------------------------------------------- -Note that the commit message will already be filled in for you with -some information about the merge. Normally you can just use this -default message unchanged, but you may add additional commentary of -your own if desired. +the different stages of that file will be "collapsed", after which +git-diff will (by default) no longer show diffs for that file. [[undoing-a-merge]] undoing a merge @@ -2988,11 +3045,6 @@ provides. Simplify beginning by suggesting disconnected head instead of temporary branch creation? -Explain how to refer to file stages in the "how to resolve a merge" -section: diff -1, -2, -3, --ours, --theirs :1:/path notation. The -"git ls-files --unmerged --stage" thing is sorta useful too, -actually. And note gitk --merge. - Add more good examples. Entire sections of just cookbook examples might be a good idea; maybe make an "advanced examples" section a standard end-of-chapter section? From 2aa54fa872adf37fb3e062dbcafefa30506eed49 Mon Sep 17 00:00:00 2001 From: Yasushi SHOJI Date: Mon, 5 Mar 2007 03:07:43 +0900 Subject: [PATCH 7/8] glossary: Add definitions for dangling and unreachable objects Define "dangling" and "unreachable" objects. Modified from original text proposed by Yasushi Shoji. Signed-off-by: "J. Bruce Fields" Signed-off-by: Junio C Hamano --- Documentation/glossary.txt | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/Documentation/glossary.txt b/Documentation/glossary.txt index d20eb6270c..9f446241e2 100644 --- a/Documentation/glossary.txt +++ b/Documentation/glossary.txt @@ -73,6 +73,11 @@ DAG:: objects is acyclic (there is no chain which begins and ends with the same object). +dangling object:: + An unreachable object which is not reachable even from other + unreachable objects; a dangling object has no references to it + from any reference or object in the repository. + dircache:: You are *waaaaay* behind. @@ -350,6 +355,10 @@ tag:: unmerged index:: An index which contains unmerged index entries. +unreachable object:: + An object which is not reachable from a branch, tag, or any + other reference. + working tree:: The set of files and directories currently being worked on, i.e. you can work in your working tree without using git at all. From 7193db3685b71be3e93aaac785bdc554d91d2167 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Sun, 4 Mar 2007 17:20:38 -0800 Subject: [PATCH 8/8] GIT 1.5.0.3 Signed-off-by: Junio C Hamano --- Documentation/RelNotes-1.5.0.3.txt | 25 ++++++++++++++----------- GIT-VERSION-GEN | 2 +- 2 files changed, 15 insertions(+), 12 deletions(-) diff --git a/Documentation/RelNotes-1.5.0.3.txt b/Documentation/RelNotes-1.5.0.3.txt index 90b49cf27d..cd500f96bf 100644 --- a/Documentation/RelNotes-1.5.0.3.txt +++ b/Documentation/RelNotes-1.5.0.3.txt @@ -1,4 +1,4 @@ -GIT v1.5.0.2 Release Notes +GIT v1.5.0.3 Release Notes ========================== Fixes since v1.5.0.2 @@ -15,6 +15,10 @@ Fixes since v1.5.0.2 path. Earlier it started in the middle of the path, and incorrectly. + - 'git-merge' did not exit with non-zero status when the + working tree was dirty and cannot fast forward. It does + now. + - 'cvsexportcommit' does not lose yet-to-be-used message file. - int-vs-size_t typefix when running combined diff on files @@ -38,18 +42,17 @@ Fixes since v1.5.0.2 - 'git index-pack' did not protect itself from getting a short read out of pread(2). + - 'git http-push' had a few buffer overruns. + + - Build dependency fixes to rebuild fetch.o when other headers + change. + * Documentation updates - - options to 'git remote add' were described insufficiently. + - user-manual updates. + - Options to 'git remote add' were described insufficiently. ---- -exec >/var/tmp/1 -O=v1.5.0.2 -O=v1.5.0.2-16-gdb554bf -echo O=`git describe maint` -git shortlog --no-merges $O..maint + - Configuration format.suffix was not documented. -# Local Variables: -# mode: text -# End: + - Other formatting and spelling fixes. diff --git a/GIT-VERSION-GEN b/GIT-VERSION-GEN index 32a9422336..05f935972c 100755 --- a/GIT-VERSION-GEN +++ b/GIT-VERSION-GEN @@ -1,7 +1,7 @@ #!/bin/sh GVF=GIT-VERSION-FILE -DEF_VER=v1.5.0.2.GIT +DEF_VER=v1.5.0.3.GIT LF=' '