diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/Makefile | 5 | ||||
| -rw-r--r-- | Documentation/RelNotes-1.5.0.3.txt | 25 | ||||
| -rw-r--r-- | Documentation/RelNotes-1.5.1.txt | 12 | ||||
| -rw-r--r-- | Documentation/SubmittingPatches | 27 | ||||
| -rw-r--r-- | Documentation/config.txt | 7 | ||||
| -rw-r--r-- | Documentation/cvs-migration.txt | 2 | ||||
| -rw-r--r-- | Documentation/git-archimport.txt | 19 | ||||
| -rw-r--r-- | Documentation/git-diff.txt | 2 | ||||
| -rw-r--r-- | Documentation/git-fast-import.txt | 13 | ||||
| -rw-r--r-- | Documentation/git-fetch-pack.txt | 5 | ||||
| -rw-r--r-- | Documentation/git-format-patch.txt | 6 | ||||
| -rw-r--r-- | Documentation/git-receive-pack.txt | 149 | ||||
| -rw-r--r-- | Documentation/git-update-index.txt | 5 | ||||
| -rw-r--r-- | Documentation/git-upload-pack.txt | 9 | ||||
| -rw-r--r-- | Documentation/git.txt | 12 | ||||
| -rw-r--r-- | Documentation/glossary.txt | 9 | ||||
| -rw-r--r-- | Documentation/user-manual.txt | 174 |
17 files changed, 379 insertions, 102 deletions
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 $< | \ 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/Documentation/RelNotes-1.5.1.txt b/Documentation/RelNotes-1.5.1.txt index aa371be1da..f374e1c2c7 100644 --- a/Documentation/RelNotes-1.5.1.txt +++ b/Documentation/RelNotes-1.5.1.txt @@ -22,6 +22,9 @@ Updates since v1.5.0 - "git diff --no-index pathA pathB" can be used as diff replacement with git specific enhancements. + - "git diff --pretty=format:<string>" to allow more flexible + custom log output. + - "git name-rev" learned --refs=<pattern>, to limit the tags used for naming the given revisions only to the ones matching the given pattern. @@ -36,6 +39,10 @@ Updates since v1.5.0 - "git bundle" can help sneaker-netting your changes between repositories. + - A new configuration "core.symlinks" can be used to disable + symlinks on filesystems that do not support them; they are + checked out as regular files instead. + * Updated behaviour of existing commands. @@ -89,6 +96,9 @@ Updates since v1.5.0 - "git status" in a read-only repository got a bit saner. + - "git fetch" (hence "git clone" and "git pull") are less + noisy when the output does not go to tty. + * Hooks - The sample update hook to show how to send out notification @@ -98,7 +108,7 @@ Updates since v1.5.0 -- exec >/var/tmp/1 -O=v1.5.0.2-259-g16d5315 +O=v1.5.0.3-268-g3ddad98 echo O=`git describe master` git shortlog --no-merges $O..master ^maint diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 285781d9db..131bcff9b2 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -1,3 +1,30 @@ +Checklist (and a short version for the impatient): + + - make commits of logical units + - check for unnecessary whitespace with "git diff --check" + before committing + - do not check in commented out code or unneeded files + - provide a meaningful commit message + - the first line of the commit message should be a short + description and should skip the full stop + - if you want your work included in git.git, add a + "Signed-off-by: Your Name <your@email.com>" line to the + commit message (or just use the option "-s" when + committing) to confirm that you agree to the Developer's + Certificate of Origin + - do not PGP sign your patch + - use "git format-patch -M" to create the patch + - do not attach your patch, but read in the mail + body, unless you cannot teach your mailer to + leave the formatting of the patch alone. + - be careful doing cut & paste into your mailer, not to + corrupt whitespaces. + - provide additional information (which is unsuitable for + the commit message) between the "---" and the diffstat + - send the patch to the list _and_ the maintainer + +Long version: + I started reading over the SubmittingPatches document for Linux kernel, primarily because I wanted to have a document similar to it for the core GIT to make sure people understand what they are diff --git a/Documentation/config.txt b/Documentation/config.txt index d20902bc33..5408dd67d3 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -117,6 +117,13 @@ core.fileMode:: the working copy are ignored; useful on broken filesystems like FAT. See gitlink:git-update-index[1]. True by default. +core.symlinks:: + If false, symbolic links are checked out as small plain files that + contain the link text. gitlink:git-update-index[1] and + gitlink:git-add[1] will not change the recorded type to regular + file. Useful on filesystems like FAT that do not support + symbolic links. True by default. + core.gitProxy:: A "proxy command" to execute (as 'command host port') instead of establishing direct connection to the remote server when 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 <destination> +$ git cvsimport -C <destination> <module> ------------------------------------------- This puts a git archive of the named CVS module in the directory diff --git a/Documentation/git-archimport.txt b/Documentation/git-archimport.txt index 5a13187a87..82cb41d279 100644 --- a/Documentation/git-archimport.txt +++ b/Documentation/git-archimport.txt @@ -10,7 +10,7 @@ SYNOPSIS -------- [verse] 'git-archimport' [-h] [-v] [-o] [-a] [-f] [-T] [-D depth] [-t tempdir] - <archive/branch> [ <archive/branch> ] + <archive/branch>[:<git-branch>] ... DESCRIPTION ----------- @@ -39,6 +39,19 @@ directory. To follow the development of a project that uses Arch, rerun `git-archimport` with the same parameters as the initial import to perform incremental imports. +While git-archimport will try to create sensible branch names for the +archives that it imports, it is also possible to specify git branch names +manually. To do so, write a git branch name after each <archive/branch> +parameter, separated by a colon. This way, you can shorten the Arch +branch names and convert Arch jargon to git jargon, for example mapping a +"PROJECT--devo--VERSION" branch to "master". + +Associating multiple Arch branches to one git branch is possible; the +result will make the most sense only if no commits are made to the first +branch, after the second branch is created. Still, this is useful to +convert Arch repositories that had been rotated periodically. + + MERGES ------ Patch merge data from Arch is used to mark merges in git as well. git @@ -73,7 +86,9 @@ OPTIONS Use this for compatibility with old-style branch names used by earlier versions of git-archimport. Old-style branch names were category--branch, whereas new-style branch names are - archive,category--branch--version. + archive,category--branch--version. In both cases, names given + on the command-line will override the automatically-generated + ones. -D <depth>:: Follow merge ancestry and attempt to import trees that have been diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt index 12a531d1e9..044cee9b42 100644 --- a/Documentation/git-diff.txt +++ b/Documentation/git-diff.txt @@ -8,7 +8,7 @@ git-diff - Show changes between commits, commit and working tree, etc SYNOPSIS -------- -'git-diff' [ --diff-options ] <commit>{0,2} [--] [<path>...] +'git-diff' [<common diff options>] <commit>{0,2} [--] [<path>...] DESCRIPTION ----------- diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt index 77a14bb076..7e3d2b1a96 100644 --- a/Documentation/git-fast-import.txt +++ b/Documentation/git-fast-import.txt @@ -62,7 +62,18 @@ OPTIONS Dumps the internal marks table to <file> when complete. Marks are written one per line as `:markid SHA-1`. Frontends can use this file to validate imports after they - have been completed. + have been completed, or to save the marks table across + incremental runs. As <file> is only opened and truncated + at checkpoint (or completion) the same path can also be + safely given to \--import-marks. + +--import-marks=<file>:: + Before processing any input, load the marks specified in + <file>. The input file must exist, must be readable, and + must use the same format as produced by \--export-marks. + Multiple options may be supplied to import more than one + set of marks. If a mark is defined to different values, + the last file wins. --export-pack-edges=<file>:: After creating a packfile, print a line of data to diff --git a/Documentation/git-fetch-pack.txt b/Documentation/git-fetch-pack.txt index 105d76b0ba..a99a5b321f 100644 --- a/Documentation/git-fetch-pack.txt +++ b/Documentation/git-fetch-pack.txt @@ -8,7 +8,7 @@ git-fetch-pack - Receive missing objects from another repository SYNOPSIS -------- -'git-fetch-pack' [--all] [--quiet|-q] [--keep|-k] [--thin] [--upload-pack=<git-upload-pack>] [--depth=<n>] [-v] [<host>:]<directory> [<refs>...] +'git-fetch-pack' [--all] [--quiet|-q] [--keep|-k] [--thin] [--upload-pack=<git-upload-pack>] [--depth=<n>] [--no-progress] [-v] [<host>:]<directory> [<refs>...] DESCRIPTION ----------- @@ -63,6 +63,9 @@ OPTIONS \--depth=<n>:: Limit fetching to ancestor-chains not longer than n. +\--no-progress:: + Do not show the progress. + \-v:: Run verbosely. diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index 59f34b9f0d..84eabebe0b 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -9,8 +9,8 @@ git-format-patch - Prepare patches for e-mail submission SYNOPSIS -------- [verse] -'git-format-patch' [-n | -k] [-o <dir> | --stdout] [--attach] [--thread] - [-s | --signoff] [--diff-options] [--start-number <n>] +'git-format-patch' [<common diff options>] [-n | -k] [-o <dir> | --stdout] + [--attach] [--thread] [-s | --signoff] [--start-number <n>] [--in-reply-to=Message-Id] [--suffix=.<sfx>] [--ignore-if-in-upstream] <since>[..<until>] @@ -46,6 +46,8 @@ reference. OPTIONS ------- +include::diff-options.txt[] + -o|--output-directory <dir>:: Use <dir> to store the resulting files, instead of the current working directory. diff --git a/Documentation/git-receive-pack.txt b/Documentation/git-receive-pack.txt index 10e8c46c4c..3cf55111cc 100644 --- a/Documentation/git-receive-pack.txt +++ b/Documentation/git-receive-pack.txt @@ -25,61 +25,126 @@ The command allows for creation and fast forwarding of sha1 refs local end receive-pack runs, but to the user who is sitting at the send-pack end, it is updating the remote. Confused?) -Before each ref is updated, if $GIT_DIR/hooks/update file exists -and executable, it is called with three parameters: +There are other real-world examples of using update and +post-update hooks found in the Documentation/howto directory. - $GIT_DIR/hooks/update refname sha1-old sha1-new +git-receive-pack honours the receive.denyNonFastForwards config +option, which tells it if updates to a ref should be denied if they +are not fast-forwards. + +OPTIONS +------- +<directory>:: + The repository to sync into. + +pre-receive Hook +---------------- +Before any ref is updated, if $GIT_DIR/hooks/pre-receive file exists +and is executable, it will be invoked once, with three parameters +per ref to be updated: + + $GIT_DIR/hooks/pre-receive (refname sha1-old sha1-new)+ + +The refname parameter is relative to $GIT_DIR; e.g. for the master +head this is "refs/heads/master". The two sha1 arguments after +each refname are the object names for the refname before and after +the update. Refs to be created will have sha1-old equal to 0{40}, +while refs to be deleted will have sha1-new equal to 0{40}, otherwise +sha1-old and sha1-new should be valid objects in the repository. + +This hook is called before any refname is updated and before any +fast-forward checks are performed. + +If the pre-receive hook exits with a non-zero exit status no updates +will be performed, and the update, post-receive and post-update +hooks will not be invoked either. This can be useful to quickly +bail out if the update is not to be supported. -The refname parameter is relative to $GIT_DIR; e.g. for the -master head this is "refs/heads/master". Two sha1 are the -object names for the refname before and after the update. Note -that the hook is called before the refname is updated, so either -sha1-old is 0{40} (meaning there is no such ref yet), or it -should match what is recorded in refname. +update Hook +----------- +Before each ref is updated, if $GIT_DIR/hooks/update file exists +and is executable, it is invoked once per ref, with three parameters: -The hook should exit with non-zero status if it wants to -disallow updating the named ref. Otherwise it should exit with -zero. + $GIT_DIR/hooks/update refname sha1-old sha1-new -Using this hook, it is easy to generate mails on updates to -the local repository. This example script sends a mail with -the commits pushed to the repository: +The refname parameter is relative to $GIT_DIR; e.g. for the master +head this is "refs/heads/master". The two sha1 arguments are +the object names for the refname before and after the update. +Note that the hook is called before the refname is updated, +so either sha1-old is 0{40} (meaning there is no such ref yet), +or it should match what is recorded in refname. + +The hook should exit with non-zero status if it wants to disallow +updating the named ref. Otherwise it should exit with zero. + +Successful execution (a zero exit status) of this hook does not +ensure the ref will actully be updated, it is only a prerequisite. +As such it is not a good idea to send notices (e.g. email) from +this hook. Consider using the post-receive hook instead. + +post-receive Hook +----------------- +After all refs were updated (or attempted to be updated), if any +ref update was successful, and if $GIT_DIR/hooks/post-receive +file exists and is executable, it will be invoke once with three +parameters for each successfully updated ref: + + $GIT_DIR/hooks/post-receive (refname sha1-old sha1-new)+ + +The refname parameter is relative to $GIT_DIR; e.g. for the master +head this is "refs/heads/master". The two sha1 arguments after +each refname are the object names for the refname before and after +the update. Refs that were created will have sha1-old equal to +0{40}, while refs that were deleted will have sha1-new equal to +0{40}, otherwise sha1-old and sha1-new should be valid objects in +the repository. + +Using this hook, it is easy to generate mails describing the updates +to the repository. This example script sends one mail message per +ref listing the commits pushed to the repository: #!/bin/sh # mail out commit update information. - if expr "$2" : '0*$' >/dev/null - then - echo "Created a new ref, with the following commits:" - git-rev-list --pretty "$2" - else - echo "New commits:" - git-rev-list --pretty "$3" "^$2" - fi | - mail -s "Changes to ref $1" commit-list@mydomain + while test $# -gt 0 + do + if expr "$2" : '0*$' >/dev/null + then + echo "Created a new ref, with the following commits:" + git-rev-list --pretty "$2" + else + echo "New commits:" + git-rev-list --pretty "$3" "^$2" + fi | + mail -s "Changes to ref $1" commit-list@mydomain + shift; shift; shift; # discard this ref's args + done exit 0 -Another hook $GIT_DIR/hooks/post-update, if exists and -executable, is called with the list of refs that have been -updated. This can be used to implement repository wide cleanup -task if needed. The exit code from this hook invocation is -ignored; the only thing left for git-receive-pack to do at that -point is to exit itself anyway. This hook can be used, for -example, to run "git-update-server-info" if the repository is -packed and is served via a dumb transport. +The exit code from this hook invocation is ignored, however a +non-zero exit code will generate an error message. - #!/bin/sh - exec git-update-server-info +Note that it is possible for refname to not have sha1-new when this +hook runs. This can easily occur if another user modifies the ref +after it was updated by receive-pack, but before the hook was able +to evaluate it. It is recommended that hooks rely on sha1-new +rather than the current value of refname. -There are other real-world examples of using update and -post-update hooks found in the Documentation/howto directory. +post-update Hook +---------------- +After all other processing, if at least one ref was updated, and +if $GIT_DIR/hooks/post-update file exists and is executable, then +post-update will called with the list of refs that have been updated. +This can be used to implement any repository wide cleanup tasks. -git-receive-pack honours the receive.denyNonFastforwards flag, which -tells it if updates to a ref should be denied if they are not fast-forwards. +The exit code from this hook invocation is ignored; the only thing +left for git-receive-pack to do at that point is to exit itself +anyway. -OPTIONS -------- -<directory>:: - The repository to sync into. +This hook can be used, for example, to run "git-update-server-info" +if the repository is packed and is served via a dumb transport. + + #!/bin/sh + exec git-update-server-info SEE ALSO diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt index b161c8b32b..cd5e014d48 100644 --- a/Documentation/git-update-index.txt +++ b/Documentation/git-update-index.txt @@ -295,6 +295,11 @@ in the index and the file mode on the filesystem if they differ only on executable bit. On such an unfortunate filesystem, you may need to use `git-update-index --chmod=`. +Quite similarly, if `core.symlinks` configuration variable is set +to 'false' (see gitlink:git-config[1]), symbolic links are checked out +as plain files, and this command does not modify a recorded file mode +from symbolic link to regular file. + The command looks at `core.ignorestat` configuration variable. See 'Using "assume unchanged" bit' section above. diff --git a/Documentation/git-upload-pack.txt b/Documentation/git-upload-pack.txt index 9da062d5c9..fd6519299a 100644 --- a/Documentation/git-upload-pack.txt +++ b/Documentation/git-upload-pack.txt @@ -8,7 +8,7 @@ git-upload-pack - Send objects packed back to git-fetch-pack SYNOPSIS -------- -'git-upload-pack' <directory> +'git-upload-pack' [--strict] [--timeout=<n>] <directory> DESCRIPTION ----------- @@ -23,6 +23,13 @@ repository. For push operations, see 'git-send-pack'. OPTIONS ------- + +\--strict:: + Do not try <directory>/.git/ if <directory> is no git directory. + +\--timeout=<n>:: + Interrupt transfer after <n> seconds of inactivity. + <directory>:: The repository to sync from. diff --git a/Documentation/git.txt b/Documentation/git.txt index 9a74747989..e875e8318d 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -35,14 +35,14 @@ ifdef::stalenotes[] You are reading the documentation for the latest version of git. Documentation for older releases are available here: -* link:v1.5.0.2/git.html[documentation for release 1.5.0.2] +* link:v1.5.0.3/git.html[documentation for release 1.5.0.3] + +* link:v1.5.0.3/RelNotes-1.5.0.3.txt[release notes for 1.5.0.3] * link:v1.5.0.2/RelNotes-1.5.0.2.txt[release notes for 1.5.0.2] * link:v1.5.0.1/RelNotes-1.5.0.1.txt[release notes for 1.5.0.1] -* link:v1.5.0/git.html[documentation for release 1.5.0] - * link:v1.5.0/RelNotes-1.5.0.txt[release notes for 1.5.0] * link:v1.4.4.4/git.html[documentation for release 1.4.4.4] @@ -241,6 +241,12 @@ Identifier Terminology operate on a <tree> object but automatically dereferences <commit> and <tag> objects that point at a <tree>. +<commit-ish>:: + Indicates a commit or tag object name. A + command that takes a <commit-ish> argument ultimately wants to + operate on a <commit> object but automatically dereferences + <tag> objects that point at a <commit>. + <type>:: Indicates that an object type is required. Currently one of: `blob`, `tree`, `commit`, or `tag`. 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. diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index 34e965104b..ffd673ec33 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 <<git-internals>> 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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1163,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 @@ -1195,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 @@ -1220,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 @@ -1255,7 +1317,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 @@ -1328,6 +1390,7 @@ with the changes to be reverted, then you will be asked to fix conflicts manually, just as in the case of <<resolving-a-merge, resolving a merge>>. +[[fixing-a-mistake-by-editing-history]] Fixing a mistake by editing history ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1930,6 +1993,51 @@ return mywork to the state it had before you started the rebase: $ git rebase --abort ------------------------------------------------- +Modifying a single commit +------------------------- + +We saw in <<fixing-a-mistake-by-editing-history>> 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 ------------------------------------------- @@ -2155,6 +2263,7 @@ See gitlink:git-config[1] for more details on the configuration options mentioned above. +[[git-internals]] Git internals ============= @@ -2936,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? |