diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/RelNotes-1.5.1.txt | 12 | ||||
| -rw-r--r-- | Documentation/SubmittingPatches | 27 | ||||
| -rw-r--r-- | Documentation/git-archimport.txt | 19 | ||||
| -rw-r--r-- | Documentation/git-commit.txt | 9 | ||||
| -rw-r--r-- | Documentation/git-config.txt | 8 | ||||
| -rw-r--r-- | Documentation/git-diff.txt | 2 | ||||
| -rw-r--r-- | Documentation/git-fast-import.txt | 19 | ||||
| -rw-r--r-- | Documentation/git-format-patch.txt | 4 | ||||
| -rw-r--r-- | Documentation/git-receive-pack.txt | 149 | ||||
| -rw-r--r-- | Documentation/git.txt | 12 | ||||
| -rwxr-xr-x | Documentation/install-webdoc.sh | 2 | ||||
| -rw-r--r-- | Documentation/sort_glossary.pl | 2 | ||||
| -rw-r--r-- | Documentation/user-manual.txt | 45 |
13 files changed, 234 insertions, 76 deletions
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/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-commit.txt b/Documentation/git-commit.txt index 2187eee416..53a7bb0895 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -8,8 +8,9 @@ git-commit - Record changes to the repository SYNOPSIS -------- [verse] -'git-commit' [-a] [-s] [-v] [(-c | -C) <commit> | -F <file> | -m <msg> | - --amend] [--no-verify] [-e] [--author <author>] +'git-commit' [-a | --interactive] [-s] [-v] + [(-c | -C) <commit> | -F <file> | -m <msg> | --amend] + [--no-verify] [-e] [--author <author>] [--] [[-i | -o ]<file>...] DESCRIPTION @@ -35,6 +36,10 @@ methods: before, and to automatically "rm" files that have been removed from the working tree, and perform the actual commit. +5. by using the --interactive switch with the 'commit' command to decide one + by one which files should be part of the commit, before finalizing the + operation. Currently, this is done by invoking `git-add --interactive`. + The gitlink:git-status[1] command can be used to obtain a summary of what is included by any of the above for the next commit by giving the same set of parameters you would give to diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt index 6624484fe1..68de5881bd 100644 --- a/Documentation/git-config.txt +++ b/Documentation/git-config.txt @@ -16,6 +16,8 @@ SYNOPSIS 'git-config' [--global] [type] --get-all name [value_regex] 'git-config' [--global] [type] --unset name [value_regex] 'git-config' [--global] [type] --unset-all name [value_regex] +'git-config' [--global] [type] --rename-section old_name new_name +'git-config' [--global] [type] --remove-section name 'git-config' [--global] -l | --list DESCRIPTION @@ -74,6 +76,12 @@ OPTIONS --global:: Use global ~/.gitconfig file rather than the repository .git/config. +--remove-section:: + Remove the given section from the configuration file. + +--rename-section:: + Rename the given section to a new name. + --unset:: Remove the line matching the key from config file. 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..eaba6fd4c1 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 @@ -451,7 +462,7 @@ in octal. Git only supports the following modes: In both formats `<path>` is the complete path of the file to be added (if not already existing) or modified (if already existing). -A `<path>` string must use UNIX-style directory seperators (forward +A `<path>` string must use UNIX-style directory separators (forward slash `/`), may contain any byte other than `LF`, and must not start with double quote (`"`). @@ -461,8 +472,8 @@ quoting should be used, e.g. `"path/with\n and \" in it"`. The value of `<path>` must be in canoncial form. That is it must not: * contain an empty directory component (e.g. `foo//bar` is invalid), -* end with a directory seperator (e.g. `foo/` is invalid), -* start with a directory seperator (e.g. `/foo` is invalid), +* end with a directory separator (e.g. `foo/` is invalid), +* start with a directory separator (e.g. `/foo` is invalid), * contain the special component `.` or `..` (e.g. `foo/./bar` and `foo/../bar` are invalid). diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index dfdb65290f..111d7c60bf 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -11,7 +11,7 @@ SYNOPSIS [verse] 'git-format-patch' [-n | -k] [-o <dir> | --stdout] [--thread] [--attach[=<boundary>] | --inline[=<boundary>]] - [-s | --signoff] [--diff-options] [--start-number <n>] + [-s | --signoff] [<common diff options>] [--start-number <n>] [--in-reply-to=Message-Id] [--suffix=.<sfx>] [--ignore-if-in-upstream] <since>[..<until>] @@ -47,6 +47,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.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/install-webdoc.sh b/Documentation/install-webdoc.sh index b3981936e3..cd3a18eb7f 100755 --- a/Documentation/install-webdoc.sh +++ b/Documentation/install-webdoc.sh @@ -2,7 +2,7 @@ T="$1" -for h in *.html *.txt howto/*.txt howto/*.html RelNotes-*.txt +for h in *.html *.txt howto/*.txt howto/*.html RelNotes-*.txt *.css do if test -f "$T/$h" && diff -u -I'Last updated [0-9][0-9]-[A-Z][a-z][a-z]-' "$T/$h" "$h" diff --git a/Documentation/sort_glossary.pl b/Documentation/sort_glossary.pl index e0bc552a64..05dc7b2c7b 100644 --- a/Documentation/sort_glossary.pl +++ b/Documentation/sort_glossary.pl @@ -48,7 +48,7 @@ This list is sorted alphabetically: '; @keys=sort {uc($a) cmp uc($b)} keys %terms; -$pattern='(\b(?<!link:git-)'.join('\b|\b(?<!link:git-)',reverse @keys).'\b)'; +$pattern='(\b(?<!link:git-)'.join('\b|\b(?<!-)',reverse @keys).'\b)'; foreach $key (@keys) { $terms{$key}=~s/$pattern/sprintf "<<ref_".no_spaces($1).",$1>>";/eg; print '[[ref_'.no_spaces($key).']]'.$key."::\n" diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index ffd673ec33..d7b227e647 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -437,11 +437,14 @@ We will sometimes represent git history using diagrams like the one below. Commits are shown as "o", and the links between them with lines drawn with - / and \. Time goes left to right: + +................................................ o--o--o <-- Branch A / o--o--o <-- master \ o--o--o <-- Branch B +................................................ If we need to talk about a particular commit, the character "o" may be replaced with another letter or number. @@ -601,8 +604,8 @@ a new stanza: $ cat .git/config ... [remote "linux-nfs"] - url = git://linux-nfs.org/~bfields/git.git - fetch = +refs/heads/*:refs/remotes/linux-nfs-read/* + url = git://linux-nfs.org/pub/nfs-2.6.git + fetch = +refs/heads/*:refs/remotes/linux-nfs/* ... ------------------------------------------------- @@ -1133,17 +1136,9 @@ modified in two different ways in the remote branch and the local branch--then you are warned; the output may look something like this: ------------------------------------------------- -$ git pull . next -Trying really trivial in-index merge... -fatal: Merge requires file-level merging -Nope. -Merging HEAD with 77976da35a11db4580b80ae27e8d65caf5208086 -Merging: -15e2162 world -77976da goodbye -found 1 common ancestor(s): -d122ed4 initial -Auto-merging file.txt +$ git merge next + 100% (4/4) done +Auto-merged file.txt CONFLICT (content): Merge conflict in file.txt Automatic merge failed; fix conflicts and then commit the result. ------------------------------------------------- @@ -1439,7 +1434,7 @@ modifying the working directory, you can do that with gitlink:git-show[1]: ------------------------------------------------- -$ git show HEAD^ path/to/file +$ git show HEAD^:path/to/file ------------------------------------------------- which will display the given version of the file. @@ -1936,25 +1931,29 @@ $ git commit You have performed no merges into mywork, so it is just a simple linear sequence of patches on top of "origin": - +................................................ o--o--o <-- origin \ o--o--o <-- mywork +................................................ Some more interesting work has been done in the upstream project, and "origin" has advanced: +................................................ o--o--O--o--o--o <-- origin \ a--b--c <-- mywork +................................................ At this point, you could use "pull" to merge your changes back in; the result would create a new merge commit, like this: - +................................................ o--o--O--o--o--o <-- origin \ \ a--b--c--m <-- mywork +................................................ However, if you prefer to keep the history in mywork a simple series of commits without any merges, you may instead choose to use @@ -1971,9 +1970,11 @@ point at the latest version of origin, then apply each of the saved patches to the new mywork. The result will look like: +................................................ o--o--O--o--o--o <-- origin \ a'--b'--c' <-- mywork +................................................ In the process, it may discover conflicts. In that case it will stop and allow you to fix the conflicts; after fixing conflicts, use "git @@ -2081,24 +2082,30 @@ The primary problem with rewriting the history of a branch has to do with merging. Suppose somebody fetches your branch and merges it into their branch, with a result something like this: +................................................ o--o--O--o--o--o <-- origin \ \ t--t--t--m <-- their branch: +................................................ Then suppose you modify the last three commits: +................................................ o--o--o <-- new head of origin / o--o--O--o--o--o <-- old head of origin +................................................ If we examined all this history together in one repository, it will look like: +................................................ o--o--o <-- new head of origin / o--o--O--o--o--o <-- old head of origin \ \ t--t--t--m <-- their branch: +................................................ Git has no way of knowing that the new head is an updated version of the old head; it treats this situation exactly the same as it would if @@ -2159,9 +2166,11 @@ commit. Git calls this process a "fast forward". A fast forward looks something like this: +................................................ o--o--o--o <-- old head of the branch \ o--o--o <-- new head of the branch +................................................ In some cases it is possible that the new head will *not* actually be @@ -2169,11 +2178,11 @@ a descendant of the old head. For example, the developer may have realized she made a serious mistake, and decided to backtrack, resulting in a situation like: +................................................ o--o--o--o--a--b <-- old head of the branch \ o--o--o <-- new head of the branch - - +................................................ In this case, "git fetch" will fail, and print out a warning. |