diff options
| -rw-r--r-- | Documentation/blame-options.txt | 67 | ||||
| -rw-r--r-- | Documentation/git-am.txt | 25 | ||||
| -rw-r--r-- | Documentation/git-annotate.txt | 15 | ||||
| -rw-r--r-- | Documentation/git-apply.txt | 13 | ||||
| -rw-r--r-- | Documentation/git-applymbox.txt | 14 | ||||
| -rw-r--r-- | Documentation/git-blame.txt | 64 | ||||
| -rw-r--r-- | Documentation/git-checkout.txt | 21 | ||||
| -rw-r--r-- | Documentation/git-lost-found.txt | 23 | ||||
| -rw-r--r-- | Documentation/user-manual.txt | 103 | ||||
| -rw-r--r-- | builtin-blame.c | 6 | ||||
| -rw-r--r-- | templates/hooks--update | 8 |
11 files changed, 222 insertions, 137 deletions
diff --git a/Documentation/blame-options.txt b/Documentation/blame-options.txt new file mode 100644 index 0000000000..331f161c77 --- /dev/null +++ b/Documentation/blame-options.txt @@ -0,0 +1,67 @@ +-b:: + Show blank SHA-1 for boundary commits. This can also + be controlled via the `blame.blankboundary` config option. + +--root:: + Do not treat root commits as boundaries. This can also be + controlled via the `blame.showroot` config option. + +--show-stats:: + Include additional statistics at the end of blame output. + +-L n,m:: + Annotate only the specified line range (lines count from 1). + +-l:: + Show long rev (Default: off). + +-t:: + Show raw timestamp (Default: off). + +-S <revs-file>:: + Use revs from revs-file instead of calling gitlink:git-rev-list[1]. + +-p, --porcelain:: + Show in a format designed for machine consumption. + +--incremental:: + Show the result incrementally in a format designed for + machine consumption. + +--contents <file>:: + When <rev> is not specified, the command annotates the + changes starting backwards from the working tree copy. + This flag makes the command pretend as if the working + tree copy has the contents of he named file (specify + `-` to make the command read from the standard input). + +-M|<num>|:: + Detect moving lines in the file as well. When a commit + moves a block of lines in a file (e.g. the original file + has A and then B, and the commit changes it to B and + then A), traditional 'blame' algorithm typically blames + the lines that were moved up (i.e. B) to the parent and + assigns blame to the lines that were moved down (i.e. A) + to the child commit. With this option, both groups of lines + are blamed on the parent. + + <num> is optional but it is the lower bound on the number of + alphanumeric characters that git must detect as moving + within a file for it to associate those lines with the parent + commit. + +-C|<num>|:: + In addition to `-M`, detect lines copied from other + files that were modified in the same commit. This is + useful when you reorganize your program and move code + around across files. When this option is given twice, + the command looks for copies from all other files in the + parent for the commit that creates the file in addition. + + <num> is optional but it is the lower bound on the number of + alphanumeric characters that git must detect as moving + between files for it to associate those lines with the parent + commit. + +-h, --help:: + Show help message. diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt index 148ce40568..f0405a35e9 100644 --- a/Documentation/git-am.txt +++ b/Documentation/git-am.txt @@ -26,18 +26,18 @@ OPTIONS The list of mailbox files to read patches from. If you do not supply this argument, reads from the standard input. ---signoff:: +-s, --signoff:: Add `Signed-off-by:` line to the commit message, using the committer identity of yourself. ---dotest=<dir>:: +-d=<dir>, --dotest=<dir>:: Instead of `.dotest` directory, use <dir> as a working area to store extracted patches. ---keep:: +-k, --keep:: Pass `-k` flag to `git-mailinfo` (see gitlink:git-mailinfo[1]). ---utf8:: +-u, --utf8:: Pass `-u` flag to `git-mailinfo` (see gitlink:git-mailinfo[1]). The proposed commit log message taken from the e-mail are re-coded into UTF-8 encoding (configuration variable @@ -48,14 +48,14 @@ This was optional in prior versions of git, but now it is the default. You could use `--no-utf8` to override this. --no-utf8:: - Do not pass `-u` flag to `git-mailinfo` (see + Pass `-n` flag to `git-mailinfo` (see gitlink:git-mailinfo[1]). ---binary:: +-b, --binary:: Pass `--allow-binary-replacement` flag to `git-apply` (see gitlink:git-apply[1]). ---3way:: +-3, --3way:: When the patch does not apply cleanly, fall back on 3-way merge, if the patch records the identity of blobs it is supposed to apply to, and we have those blobs @@ -73,10 +73,10 @@ default. You could use `--no-utf8` to override this. These flags are passed to the `git-apply` program that applies the patch. ---interactive:: +-i, --interactive:: Run interactively, just like git-applymbox. ---resolved:: +-r, --resolved:: After a patch failure (e.g. attempting to apply conflicting patch), the user has applied it by hand and the index file stores the result of the application. @@ -84,6 +84,13 @@ default. You could use `--no-utf8` to override this. extracted from the e-mail message and the current index file, and continue. +--resolvemsg=<msg>:: + When a patch failure occurs, <msg> will be printed + to the screen before exiting. This overrides the + standard message informing you to use `--resolved` + or `--skip` to handle the failure. This is solely + for internal use between `git-rebase` and `git-am`. + DISCUSSION ---------- diff --git a/Documentation/git-annotate.txt b/Documentation/git-annotate.txt index 7baf73111b..02dc4740d0 100644 --- a/Documentation/git-annotate.txt +++ b/Documentation/git-annotate.txt @@ -16,20 +16,7 @@ which introduced the line. Optionally annotate from a given revision. OPTIONS ------- --l, --long:: - Show long rev (Defaults off). - --t, --time:: - Show raw timestamp (Defaults off). - --r, --rename:: - Follow renames (Defaults on). - --S, --rev-file <revs-file>:: - Use revs from revs-file instead of calling git-rev-list. - --h, --help:: - Show help message. +include::blame-options.txt[] SEE ALSO -------- diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt index 065ba1bf24..3bd2c995da 100644 --- a/Documentation/git-apply.txt +++ b/Documentation/git-apply.txt @@ -9,11 +9,12 @@ git-apply - Apply a patch on a git index file and a working tree SYNOPSIS -------- [verse] -'git-apply' [--stat] [--numstat] [--summary] [--check] [--index] [--apply] - [--no-add] [--index-info] [--allow-binary-replacement | --binary] - [-R | --reverse] [--reject] [-z] [-pNUM] [-CNUM] [--inaccurate-eof] - [--whitespace=<nowarn|warn|error|error-all|strip>] [--exclude=PATH] - [--cached] [--verbose] [<patch>...] +'git-apply' [--stat] [--numstat] [--summary] [--check] [--index] + [--apply] [--no-add] [--index-info] [-R | --reverse] + [--allow-binary-replacement | --binary] [--reject] [-z] + [-pNUM] [-CNUM] [--inaccurate-eof] [--cached] + [--whitespace=<nowarn|warn|error|error-all|strip>] + [--exclude=PATH] [--verbose] [<patch>...] DESCRIPTION ----------- @@ -158,7 +159,7 @@ discouraged. correctly. This option adds support for applying such patches by working around this bug. ---verbose:: +-v, --verbose:: Report progress to stderr. By default, only a message about the current patch being applied will be printed. This option will cause additional information to be reported. diff --git a/Documentation/git-applymbox.txt b/Documentation/git-applymbox.txt index 95dc65a583..3bc92d8cf1 100644 --- a/Documentation/git-applymbox.txt +++ b/Documentation/git-applymbox.txt @@ -42,14 +42,20 @@ OPTIONS and the current tree. -u:: - The commit log message, author name and author email are - taken from the e-mail, and after minimally decoding MIME - transfer encoding, re-coded in UTF-8 by transliterating - them. This used to be optional but now it is the default. + Pass `-u` flag to `git-mailinfo` (see gitlink:git-mailinfo[1]). + The proposed commit log message taken from the e-mail + are re-coded into UTF-8 encoding (configuration variable + `i18n.commitencoding` can be used to specify project's + preferred encoding if it is not UTF-8). This used to be + optional but now it is the default. + Note that the patch is always used as-is without charset conversion, even with this flag. +-n:: + Pass `-n` flag to `git-mailinfo` (see + gitlink:git-mailinfo[1]). + -c .dotest/<num>:: When the patch contained in an e-mail does not cleanly apply, the command exits with an error message. The diff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt index 5c9888d014..8f9439a6dd 100644 --- a/Documentation/git-blame.txt +++ b/Documentation/git-blame.txt @@ -8,8 +8,9 @@ git-blame - Show what revision and author last modified each line of a file SYNOPSIS -------- [verse] -'git-blame' [-c] [-l] [-t] [-f] [-n] [-p] [--incremental] [-L n,m] [-S <revs-file>] - [-M] [-C] [-C] [--since=<date>] [<rev> | --contents <file>] [--] <file> +'git-blame' [-c] [-l] [-t] [-f] [-n] [-p] [--incremental] [-L n,m] + [-S <revs-file>] [-M] [-C] [-C] [--since=<date>] + [<rev> | --contents <file>] [--] <file> DESCRIPTION ----------- @@ -37,20 +38,19 @@ ea4c7f9bf69e781dd0cd88d2bccb2bf5cc15c9a7 git-blame: Make the output OPTIONS ------- --c, --compatibility:: - Use the same output mode as gitlink:git-annotate[1] (Default: off). - --L n,m:: - Annotate only the specified line range (lines count from 1). - --l, --long:: - Show long rev (Default: off). +include::blame-options.txt[] --t, --time:: - Show raw timestamp (Default: off). +-c:: + Use the same output mode as gitlink:git-annotate[1] (Default: off). --S, --rev-file <revs-file>:: - Use revs from revs-file instead of calling gitlink:git-rev-list[1]. +--score-debug:: + Include debugging information related to the movement of + lines between files (see `-C`) and lines moved within a + file (see `-M`). The first number listed is the score. + This is the number of alphanumeric characters detected + to be moved between or within files. This must be above + a certain threshold for git-blame to consider those lines + of code to have been moved. -f, --show-name:: Show filename in the original commit. By default @@ -60,42 +60,6 @@ OPTIONS -n, --show-number:: Show line number in the original commit (Default: off). --p, --porcelain:: - Show in a format designed for machine consumption. - ---incremental:: - Show the result incrementally in a format designed for - machine consumption. - ---contents <file>:: - When <rev> is not specified, the command annotates the - changes starting backwards from the working tree copy. - This flag makes the command pretend as if the working - tree copy has the contents of he named file (specify - `-` to make the command read from the standard input). - --M:: - Detect moving lines in the file as well. When a commit - moves a block of lines in a file (e.g. the original file - has A and then B, and the commit changes it to B and - then A), traditional 'blame' algorithm typically blames - the lines that were moved up (i.e. B) to the parent and - assigns blame to the lines that were moved down (i.e. A) - to the child commit. With this option, both groups of - lines are blamed on the parent. - --C:: - In addition to `-M`, detect lines copied from other - files that were modified in the same commit. This is - useful when you reorganize your program and move code - around across files. When this option is given twice, - the command looks for copies from all other files in the - parent for the commit that creates the file in addition. - --h, --help:: - Show help message. - - THE PORCELAIN FORMAT -------------------- diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index f5b2d5017b..4f2e847dc3 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -23,9 +23,9 @@ options, which will be passed to `git branch`. When <paths> are given, this command does *not* switch branches. It updates the named paths in the working tree from -the index file (i.e. it runs `git-checkout-index -f -u`), or a -named commit. In -this case, `-f` and `-b` options are meaningless and giving +the index file (i.e. it runs `git-checkout-index -f -u`), or +from a named commit. In +this case, the `-f` and `-b` options are meaningless and giving either of them results in an error. <tree-ish> argument can be used to specify a specific tree-ish (i.e. commit, tag or tree) to update the index for the given paths before updating the @@ -38,7 +38,8 @@ OPTIONS Quiet, supress feedback messages. -f:: - Force a re-read of everything. + Proceed even if the index or the working tree differs + from HEAD. This is used to throw away local changes. -b:: Create a new branch named <new_branch> and start it at @@ -48,13 +49,17 @@ OPTIONS --track:: When -b is given and a branch is created off a remote branch, - setup so that git-pull will automatically retrieve data from - the remote branch. + set up configuration so that git-pull will automatically + retrieve data from the remote branch. Set the + branch.autosetupmerge configuration variable to true if you + want git-checkout and git-branch to always behave as if + '--track' were given. --no-track:: When -b is given and a branch is created off a remote branch, - force that git-pull will automatically retrieve data from - the remote branch independent of the configuration settings. + set up configuration so that git-pull will not retrieve data + from the remote branch, ignoring the branch.autosetupmerge + configuration variable. -l:: Create the new branch's ref log. This activates recording of diff --git a/Documentation/git-lost-found.txt b/Documentation/git-lost-found.txt index f52a9d7f68..e48607f008 100644 --- a/Documentation/git-lost-found.txt +++ b/Documentation/git-lost-found.txt @@ -12,23 +12,22 @@ SYNOPSIS DESCRIPTION ----------- Finds dangling commits and tags from the object database, and -creates refs to them in .git/lost-found/ directory. Commits and -tags that dereference to commits go to .git/lost-found/commit -and others are stored in .git/lost-found/other directory. +creates refs to them in the .git/lost-found/ directory. Commits and +tags that dereference to commits are stored in .git/lost-found/commit, +and other objects are stored in .git/lost-found/other. OUTPUT ------ -One line description from the commit and tag found along with -their object name are printed on the standard output. - +Prints to standard output the object names and one-line descriptions +of any commits or tags found. EXAMPLE ------- -Suppose you run 'git tag -f' and mistyped the tag to overwrite. +Suppose you run 'git tag -f' and mistype the tag to overwrite. The ref to your tag is overwritten, but until you run 'git -prune', it is still there. +prune', the tag itself is still there. ------------ $ git lost-found @@ -36,15 +35,15 @@ $ git lost-found ... ------------ -Also you can use gitk to browse how they relate to each other -and existing (probably old) tags. +Also you can use gitk to browse how any tags found relate to each +other. ------------ $ gitk $(cd .git/lost-found/commit && echo ??*) ------------ -After making sure that it is the object you are looking for, you -can reconnect it to your regular .git/refs hierarchy. +After making sure you know which the object is the tag you are looking +for, you can reconnect it to your regular .git/refs hierarchy. ------------ $ git cat-file -t 1ef2b196 diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index d43d2377ec..9c4c41df5a 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -298,9 +298,9 @@ $ git branch * master ------------------------------------------------ -A freshly cloned repository contains a single branch head, named -"master", and working directory is initialized to the state of -the project referred to by "master". +A freshly cloned repository contains a single branch head, by default +named "master", with the working directory initialized to the state of +the project referred to by that branch head. Most projects also use <<def_tag,tags>>. Tags, like heads, are references into the project's history, and can be listed using the @@ -495,8 +495,49 @@ git checkout -b <new> <start-point>:: create a new branch <new> referencing <start-point>, and check it out. -It is also useful to know that the special symbol "HEAD" can always -be used to refer to the current branch. +The special symbol "HEAD" can always be used to refer to the current +branch. In fact, git uses a file named "HEAD" in the .git directory to +remember which branch is current: + +------------------------------------------------ +$ cat .git/HEAD +ref: refs/heads/master +------------------------------------------------ + +[[detached-head]] +Examining an old version without creating a new branch +------------------------------------------------------ + +The git-checkout command normally expects a branch head, but will also +accept an arbitrary commit; for example, you can check out the commit +referenced by a tag: + +------------------------------------------------ +$ git checkout v2.6.17 +Note: moving to "v2.6.17" which isn't a local branch +If you want to create a new branch from this checkout, you may do so +(now or later) by using -b with the checkout command again. Example: + git checkout -b <new_branch_name> +HEAD is now at 427abfa... Linux v2.6.17 +------------------------------------------------ + +The HEAD then refers to the SHA1 of the commit instead of to a branch, +and git branch shows that you are no longer on a branch: + +------------------------------------------------ +$ cat .git/HEAD +427abfa28afedffadfca9dd8b067eb6d36bac53f +git branch +* (no branch) + master +------------------------------------------------ + +In this case we say that the HEAD is "detached". + +This can be an easy way to check out a particular version without having +to make up a name for a new branch. However, keep in mind that when you +switch away from the (for example, by checking out something else), you +can lose track of what the HEAD used to point to. Examining branches from a remote repository ------------------------------------------- @@ -2015,22 +2056,22 @@ $ 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: +Then check out that commit, edit it, and rebase the rest of the series +on top of it (note that we could check out the commit on a temporary +branch, but instead we're using a <<detached-head,detached head>>): ------------------------------------------------- -$ git checkout -b TMP bad +$ git checkout bad $ # make changes here and update the index $ git commit --amend -$ git rebase --onto TMP bad mywork +$ git rebase --onto HEAD 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 +When you're done, you'll be left with mywork checked out, with the top +patches on mywork reapplied on top of your modified commit. You can then clean up with ------------------------------------------------- -$ git branch -d TMP $ git tag -d bad ------------------------------------------------- @@ -2275,8 +2316,8 @@ options mentioned above. Git internals ============= -There are two object abstractions: the "object database", and the -"current directory cache" aka "index". +Git depends on two fundamental abstractions: the "object database", and +the "current directory cache" aka "index". The Object Database ------------------- @@ -2291,22 +2332,23 @@ All objects have a statically determined "type" aka "tag", which is determined at object creation time, and which identifies the format of the object (i.e. how it is used, and how it can refer to other objects). There are currently four different object types: "blob", -"tree", "commit" and "tag". +"tree", "commit", and "tag". -A "blob" object cannot refer to any other object, and is, like the type -implies, a pure storage object containing some user data. It is used to -actually store the file data, i.e. a blob object is associated with some -particular version of some file. +A <<def_blob_object,"blob" object>> cannot refer to any other object, +and is, as the name implies, a pure storage object containing some +user data. It is used to actually store the file data, i.e. a blob +object is associated with some particular version of some file. -A "tree" object is an object that ties one or more "blob" objects into a -directory structure. In addition, a tree object can refer to other tree -objects, thus creating a directory hierarchy. +A <<def_tree_object,"tree" object>> is an object that ties one or more +"blob" objects into a directory structure. In addition, a tree object +can refer to other tree objects, thus creating a directory hierarchy. -A "commit" object ties such directory hierarchies together into -a DAG of revisions - each "commit" is associated with exactly one tree -(the directory hierarchy at the time of the commit). In addition, a -"commit" refers to one or more "parent" commit objects that describe the -history of how we arrived at that directory hierarchy. +A <<def_commit_object,"commit" object>> ties such directory hierarchies +together into a <<def_DAG,directed acyclic graph>> of revisions - each +"commit" is associated with exactly one tree (the directory hierarchy at +the time of the commit). In addition, a "commit" refers to one or more +"parent" commit objects that describe the history of how we arrived at +that directory hierarchy. As a special case, a commit object with no parents is called the "root" object, and is the point of an initial project commit. Each project @@ -2316,9 +2358,10 @@ has two or more separate roots as its ultimate parents, that's probably just going to confuse people. So aim for the notion of "one root object per project", even if git itself does not enforce that. -A "tag" object symbolically identifies and can be used to sign other -objects. It contains the identifier and type of another object, a -symbolic name (of course!) and, optionally, a signature. +A <<def_tag_object,"tag" object>> symbolically identifies and can be +used to sign other objects. It contains the identifier and type of +another object, a symbolic name (of course!) and, optionally, a +signature. Regardless of object type, all objects share the following characteristics: they are all deflated with zlib, and have a header diff --git a/builtin-blame.c b/builtin-blame.c index bc86bda6c4..8919b028e6 100644 --- a/builtin-blame.c +++ b/builtin-blame.c @@ -19,11 +19,11 @@ static char blame_usage[] = "git-blame [-c] [-l] [-t] [-f] [-n] [-p] [-L n,m] [-S <revs-file>] [-M] [-C] [-C] [--contents <filename>] [--incremental] [commit] [--] file\n" -" -c, --compatibility Use the same output mode as git-annotate (Default: off)\n" +" -c Use the same output mode as git-annotate (Default: off)\n" " -b Show blank SHA-1 for boundary commits (Default: off)\n" -" -l, --long Show long commit SHA1 (Default: off)\n" +" -l Show long commit SHA1 (Default: off)\n" " --root Do not treat root commits as boundaries (Default: off)\n" -" -t, --time Show raw timestamp (Default: off)\n" +" -t Show raw timestamp (Default: off)\n" " -f, --show-name Show original filename (Default: auto)\n" " -n, --show-number Show original linenumber (Default: off)\n" " -p, --porcelain Show in a format designed for machine consumption\n" diff --git a/templates/hooks--update b/templates/hooks--update index 0ff03309e6..9d3795c6d0 100644 --- a/templates/hooks--update +++ b/templates/hooks--update @@ -34,13 +34,19 @@ fi allowunannotated=$(git-repo-config --bool hooks.allowunannotated) # check for no description +projectdesc=$(sed -e '1p' "$GIT_DIR/description") if [ -z "$projectdesc" -o "$projectdesc" = "Unnamed repository; edit this file to name it for gitweb" ]; then echo "*** Project description file hasn't been set" >&2 exit 1 fi # --- Check types -newrev_type=$(git-cat-file -t $newrev) +# if $newrev is 0000...0000, it's a commit to delete a branch +if [ -z "${newrev##0*}" ]; then + newrev_type=commit +else + newrev_type=$(git-cat-file -t $newrev) +fi case "$refname","$newrev_type" in refs/tags/*,commit) |