diff options
Diffstat (limited to 'Documentation')
41 files changed, 468 insertions, 125 deletions
diff --git a/Documentation/RelNotes-1.5.5.1.txt b/Documentation/RelNotes-1.5.5.1.txt new file mode 100644 index 0000000000..7de419708f --- /dev/null +++ b/Documentation/RelNotes-1.5.5.1.txt @@ -0,0 +1,44 @@ +GIT v1.5.5.1 Release Notes +========================== + +Fixes since v1.5.5 +------------------ + + * "git archive --prefix=$path/" mishandled gitattributes. + + * "git fetch -v" that fetches into FETCH_HEAD did not report the summary + the same way as done for updating the tracking refs. + + * "git svn" misbehaved when the configuration file customized the "git + log" output format using format.pretty. + + * "git submodule status" leaked an unnecessary error message. + + * "git log --date-order --topo-order" did not override the earlier + date-order with topo-order as expected. + + * "git bisect good $this" did not check the validity of the revision + given properly. + + * "url.<there>.insteadOf" did not work correctly. + + * "git clean" ran inside subdirectory behaved as if the directory was + explicitly specified for removal by the end user from the top level. + + * "git bisect" from a detached head leaked an unnecessary error message. + + * "git bisect good $a $b" when $a is Ok but $b is bogus should have + atomically failed before marking $a as good. + + * "git fmt-merge-msg" did not clean up leading empty lines from commit + log messages like "git log" family does. + + * "git am" recorded a commit with empty Subject: line without + complaining. + + * when given a commit log message whose first paragraph consists of + multiple lines, "git rebase" squashed it into a single line. + + * "git remote add $bogus_name $url" did not complain properly. + +Also comes with various documentation updates. diff --git a/Documentation/RelNotes-1.5.5.txt b/Documentation/RelNotes-1.5.5.txt index b299e8792c..2932212488 100644 --- a/Documentation/RelNotes-1.5.5.txt +++ b/Documentation/RelNotes-1.5.5.txt @@ -6,7 +6,7 @@ Updates since v1.5.4 (subsystems) - * Comes with git-gui 0.9.3. + * Comes with git-gui 0.10.1 (portability) @@ -166,8 +166,8 @@ Updates since v1.5.4 symmetric difference between the HEAD version and the work tree version of the submodule commits. - * Various "git cvsimport", "git cvsexportcommit", "git svn" and - "git p4" improvements. + * Various "git cvsimport", "git cvsexportcommit", "git cvsserver", + "git svn" and "git p4" improvements. (internal) @@ -205,9 +205,3 @@ this release, unless otherwise noted. * "git imap-send" without setting imap.host did not error out but segfaulted. - ---- -exec >/var/tmp/1 -O=v1.5.5-rc1-21-g319a36a -echo O=`git describe refs/heads/master` -git shortlog --no-merges $O..refs/heads/master ^refs/heads/maint diff --git a/Documentation/RelNotes-1.5.6.txt b/Documentation/RelNotes-1.5.6.txt new file mode 100644 index 0000000000..f3256fb82c --- /dev/null +++ b/Documentation/RelNotes-1.5.6.txt @@ -0,0 +1,59 @@ +GIT v1.5.6 Release Notes +======================== + +Updates since v1.5.5 +-------------------- + +(subsystems) + + +(portability) + + +(performance) + +* "git rebase --onto $there $from $branch" used to switch to the tip of + $branch only to immediately reset back to $from, smudging work tree + files unnecessarily. This has been optimized. + +(usability, bells and whistles) + +* "git add -p" (and the "patch" subcommand of "git add -i") can choose to + apply (or not apply) mode changes independently from contents changes. + +* "git bisect help" gives longer and more helpful usage information. + +* "git diff/log --dirstat" output is consistent between binary and textual + changes. + +* "git gc --auto" honors a new pre-aut-gc hook to temporarily disable it. + +* "git log --pretty=tformat:<custom format>" gives a LF after each entry, + instead of giving a LF between each pair of entries which is how + "git log --pretty=format:<custom format>" works. + +* "git send-email" now can send out messages outside a git repository. + +* "git status" can optionally include output from "git submodule + summary". + +* "gitweb" can read from a system-wide configuration file. + +(internal) + +* "git unpack-objects" and "git receive-pack" is now more strict about + detecting breakage in the objects they receive over the wire. + + +Fixes since v1.5.5 +------------------ + +All of the fixes in v1.5.5 maintenance series are included in +this release, unless otherwise noted. + + +-- +exec >/var/tmp/1 +O=v1.5.5-56-g5f0734f +echo O=`git describe refs/heads/master` +git shortlog --no-merges $O..refs/heads/master ^refs/heads/maint diff --git a/Documentation/config.txt b/Documentation/config.txt index 3017d640cf..00f089fee4 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -234,7 +234,13 @@ core.worktree:: used in combination with repositories found automatically in a .git directory (i.e. $GIT_DIR is not set). This can be overridden by the GIT_WORK_TREE environment - variable and the '--work-tree' command line option. + variable and the '--work-tree' command line option. It can be + a absolute path or relative path to the directory specified by + --git-dir or GIT_DIR. + Note: If --git-dir or GIT_DIR are specified but none of + --work-tree, GIT_WORK_TREE and core.worktree is specified, + the current working directory is regarded as the top directory + of your working tree. core.logAllRefUpdates:: Enable the reflog. Updates to a ref <ref> is logged to the file @@ -261,7 +267,12 @@ core.sharedRepository:: group-writable). When 'all' (or 'world' or 'everybody'), the repository will be readable by all users, additionally to being group-shareable. When 'umask' (or 'false'), git will use permissions - reported by umask(2). See linkgit:git-init[1]. False by default. + reported by umask(2). When '0xxx', where '0xxx' is an octal number, + files in the repository will have this mode value. '0xxx' will override + user's umask value, and thus, users with a safe umask (0077) can use + this option. Examples: '0660' is equivalent to 'group'. '0640' is a + repository that is group-readable but not group-writable. + See linkgit:git-init[1]. False by default. core.warnAmbiguousRefs:: If true, git will warn you if the ref name you passed it is ambiguous @@ -661,6 +672,13 @@ gitcvs.dbuser, gitcvs.dbpass:: 'gitcvs.dbuser' supports variable substitution (see linkgit:git-cvsserver[1] for details). +gitcvs.dbTableNamePrefix:: + Database table name prefix. Prepended to the names of any + database tables used, allowing a single database to be used + for several repositories. Supports variable substitution (see + linkgit:git-cvsserver[1] for details). Any non-alphabetic + characters will be replaced with underscores. + All gitcvs variables except for 'gitcvs.allbinary' can also be specified as 'gitcvs.<access_method>.<varname>' (where 'access_method' is one of "ext" and "pserver") to make them apply only for the given @@ -903,6 +921,10 @@ remote.<name>.push:: The default set of "refspec" for linkgit:git-push[1]. See linkgit:git-push[1]. +remote.<name>.mirror:: + If true, pushing to this remote will automatically behave + as if the `\--mirror` option was given on the command line. + remote.<name>.skipDefaultUpdate:: If true, this remote will be skipped by default when updating using the update subcommand of linkgit:git-remote[1]. @@ -984,6 +1006,12 @@ imap:: The configuration variables in the 'imap' section are described in linkgit:git-imap-send[1]. +receive.fsckObjects:: + If it is set to true, git-receive-pack will check all received + objects. It will abort in the case of a malformed object or a + broken link. The result of an abort are only dangling objects. + Defaults to false. + receive.unpackLimit:: If the number of objects received in a push is below this limit then the objects will be unpacked into loose object diff --git a/Documentation/core-tutorial.txt b/Documentation/core-tutorial.txt index aa40dfd36a..5a5531222d 100644 --- a/Documentation/core-tutorial.txt +++ b/Documentation/core-tutorial.txt @@ -535,18 +535,18 @@ with the associated patches use the more complex (and much more powerful) ---------------- -$ git-whatchanged -p --root +$ git-whatchanged -p ---------------- and you will see exactly what has changed in the repository over its short history. [NOTE] -The `\--root` flag is a flag to `git-diff-tree` to tell it to -show the initial aka 'root' commit too. Normally you'd probably not -want to see the initial import diff, but since the tutorial project -was started from scratch and is so small, we use it to make the result -a bit more interesting. +When using the above two commands, the initial commit will be shown. +If this is a problem because it is huge, you can hide it by setting +the log.showroot configuration variable to false. Having this, you +can still show it for each command just adding the `\--root` option, +which is a flag for `git-diff-tree` accepted by both commands. With that, you should now be having some inkling of what git does, and can explore on your own. diff --git a/Documentation/cvs-migration.txt b/Documentation/cvs-migration.txt index ea98900228..00f2e36b2e 100644 --- a/Documentation/cvs-migration.txt +++ b/Documentation/cvs-migration.txt @@ -8,7 +8,8 @@ designating a single shared repository which people can synchronize with; this document explains how to do that. Some basic familiarity with git is required. This -link:tutorial.html[tutorial introduction to git] should be sufficient. +link:tutorial.html[tutorial introduction to git] and the +link:glossary.html[git glossary] should be sufficient. Developing against a shared repository -------------------------------------- diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index 8dc5b001c4..13234fa280 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -58,6 +58,14 @@ endif::git-format-patch[] number of modified files, as well as number of added and deleted lines. +--dirstat[=limit]:: + Output only the sub-directories that are impacted by a diff, + and to what degree they are impacted. You can override the + default cut-off in percent (3) by "--dirstat=limit". If you + want to enable "cumulative" directory statistics, you can use + the "--cumulative" flag, which adds up percentages recursively + even when they have been already reported for a sub-directory. + --summary:: Output a condensed summary of extended header information such as creations, renames and mode changes. @@ -75,7 +83,8 @@ endif::git-format-patch[] Show only names of changed files. --name-status:: - Show only names and status of changed files. + Show only names and status of changed files. See the description + of the `--diff-filter` option on what the status letters mean. --color:: Show colored diff. diff --git a/Documentation/everyday.txt b/Documentation/everyday.txt index fdbd15a181..e598cdda45 100644 --- a/Documentation/everyday.txt +++ b/Documentation/everyday.txt @@ -48,14 +48,12 @@ $ git gc <3> repository health reasonably well. <2> check how many loose objects there are and how much disk space is wasted by not repacking. -<3> repacks the local repository and performs other housekeeping tasks. Running -without `--prune` is a safe operation even while other ones are in progress. +<3> repacks the local repository and performs other housekeeping tasks. Repack a small project into single pack.:: + ------------ $ git gc <1> -$ git gc --prune ------------ + <1> pack all the objects reachable from the refs into one pack, @@ -182,7 +180,7 @@ $ git pull <3> $ git log -p ORIG_HEAD.. arch/i386 include/asm-i386 <4> $ git pull git://git.kernel.org/pub/.../jgarzik/libata-dev.git ALL <5> $ git reset --hard ORIG_HEAD <6> -$ git gc --prune <7> +$ git gc <7> $ git fetch --tags <8> ------------ + diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt index c751a17d07..35e67a06e4 100644 --- a/Documentation/git-add.txt +++ b/Documentation/git-add.txt @@ -226,6 +226,12 @@ diff:: This lets you review what will be committed (i.e. between HEAD and index). +Bugs +---- +The interactive mode does not work with files whose names contain +characters that need C-quoting. `core.quotepath` configuration can be +used to work this limitation around to some degree, but backslash, +double-quote and control characters will still have problems. See Also -------- diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt index 96585ae8d9..698ffde7ce 100644 --- a/Documentation/git-bisect.txt +++ b/Documentation/git-bisect.txt @@ -15,6 +15,7 @@ DESCRIPTION The command takes various subcommands, and different options depending on the subcommand: + git bisect help git bisect start [<bad> [<good>...]] [--] [<paths>...] git bisect bad [<rev>] git bisect good [<rev>...] @@ -29,6 +30,12 @@ This command uses 'git-rev-list --bisect' option to help drive the binary search process to find which change introduced a bug, given an old "good" commit object name and a later "bad" commit object name. +Getting help +~~~~~~~~~~~~ + +Use "git bisect" to get a short usage description, and "git bisect +help" or "git bisect -h" to get a long usage description. + Basic bisect commands: start, bad, good ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index 6f07a17a2c..c824d88742 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -8,7 +8,7 @@ git-branch - List, create, or delete branches SYNOPSIS -------- [verse] -'git-branch' [--color | --no-color] [-r | -a] +'git-branch' [--color | --no-color] [-r | -a] [--merged | --no-merged] [-v [--abbrev=<length> | --no-abbrev]] [--contains <commit>] 'git-branch' [--track | --no-track] [-l] [-f] <branchname> [<start-point>] @@ -24,6 +24,8 @@ and option `-a` shows both. With `--contains <commit>`, shows only the branches that contains the named commit (in other words, the branches whose tip commits are descendant of the named commit). +With `--merged`, only branches merged into HEAD will be listed, and +with `--no-merged` only branches not merged into HEAD will be listed. In its second form, a new branch named <branchname> will be created. It will start out with a head equal to the one given as <start-point>. @@ -118,6 +120,15 @@ OPTIONS --no-track:: Ignore the branch.autosetupmerge configuration variable. +--contains <commit>:: + Only list branches which contain the specified commit. + +--merged:: + Only list branches which are fully contained by HEAD. + +--no-merged:: + Do not list branches which are fully contained by HEAD. + <branchname>:: The name of the branch to create or delete. The new branch name must pass all checks defined by @@ -175,6 +186,18 @@ If you are creating a branch that you want to immediately checkout, it's easier to use the git checkout command with its `-b` option to create a branch and check it out with a single command. +The options `--contains`, `--merged` and `--no-merged` serves three related +but different purposes: + +- `--contains <commit>` is used to find all branches which will need + special attention if <commit> were to be rebased or amended, since those + branches contain the specified <commit>. + +- `--merged` is used to find all branches which can be safely deleted, + since those branches are fully contained by HEAD. + +- `--no-merged` is used to find branches which are candidates for merging + into HEAD, since those branches are not fully contained by HEAD. Author ------ diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index e11cddbfc9..a644173e15 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -47,7 +47,7 @@ OPTIONS by linkgit:git-check-ref-format[1]. Some of these checks may restrict the characters allowed in a branch name. ---track:: +-t, --track:: When creating a new branch, set up configuration so that git-pull will automatically retrieve data from the start point, which must be a branch. Use this if you always pull from the same upstream branch diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index 975824301a..9b564420c5 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -65,10 +65,13 @@ OPTIONS + *NOTE*: this is a possibly dangerous operation; do *not* use it unless you understand what it does. If you clone your -repository using this option, then delete branches in the -source repository and then run linkgit:git-gc[1] using the -'--prune' option in the source repository, it may remove -objects which are referenced by the cloned repository. +repository using this option and then delete branches (or use any +other git command that makes any existing commit unreferenced) in the +source repository, some objects may become unreferenced (or dangling). +These objects may be removed by normal git operations (such as git-commit[1]) +which automatically call git-gc[1]. If these objects are removed and +were referenced by the cloned repository, then the cloned repository +will become corrupt. @@ -79,6 +82,8 @@ objects which are referenced by the cloned repository. an already existing repository as an alternate will require fewer objects to be copied from the repository being cloned, reducing network and local storage costs. ++ +*NOTE*: see NOTE to --shared option. --quiet:: -q:: diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index b4ae61ff46..4bb51cc06e 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -139,6 +139,17 @@ but can be used to amend a merge commit. as well. This is usually not what you want unless you are concluding a conflicted merge. +-o|--only:: + Make a commit only from the paths specified on the + command line, disregarding any contents that have been + staged so far. This is the default mode of operation of + 'git commit' if any paths are given on the command line, + in which case this option can be omitted. + If this option is specified together with '--amend', then + no paths need be specified, which can be used to amend + the last commit without committing changes that have + already been staged. + -u|--untracked-files:: Show all untracked files, also those in uninteresting directories, in the "Untracked files:" section of commit diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt index fa161718dd..5de5d051b7 100644 --- a/Documentation/git-config.txt +++ b/Documentation/git-config.txt @@ -144,6 +144,8 @@ See also <<FILES>>. "auto". If `stdout-is-tty` is missing, then checks the standard output of the command itself, and exits with status 0 if color is to be used, or exits with status 1 otherwise. + When the color setting for `name` is undefined, the command uses + `color.ui` as fallback. --get-color name default:: diff --git a/Documentation/git-cvsserver.txt b/Documentation/git-cvsserver.txt index d3e99931d7..b1106714b2 100644 --- a/Documentation/git-cvsserver.txt +++ b/Documentation/git-cvsserver.txt @@ -110,7 +110,9 @@ cvs -d ":ext;CVS_SERVER=git-cvsserver:user@server/path/repo.git" co <HEAD_name> ------ This has the advantage that it will be saved in your 'CVS/Root' files and you don't need to worry about always setting the correct environment -variable. +variable. SSH users restricted to git-shell don't need to override the default +with CVS_SERVER (and shouldn't) as git-shell understands `cvs` to mean +git-cvsserver and pretends that the other end runs the real cvs better. -- 2. For each repo that you want accessible from CVS you need to edit config in the repo and add the following section. @@ -141,25 +143,29 @@ allowing access over SSH. enabled=1 ------ -- -3. On the client machine you need to set the following variables. - CVSROOT should be set as per normal, but the directory should point at the - appropriate git repo. For example: +3. If you didn't specify the CVSROOT/CVS_SERVER directly in the checkout command, + automatically saving it in your 'CVS/Root' files, then you need to set them + explicitly in your environment. CVSROOT should be set as per normal, but the + directory should point at the appropriate git repo. As above, for SSH clients + _not_ restricted to git-shell, CVS_SERVER should be set to git-cvsserver. + -- -For SSH access, CVS_SERVER should be set to git-cvsserver - -Example: - ------ export CVSROOT=:ext:user@server:/var/git/project.git export CVS_SERVER=git-cvsserver ------ -- -4. For SSH clients that will make commits, make sure their .bashrc file - sets the GIT_AUTHOR and GIT_COMMITTER variables. +4. For SSH clients that will make commits, make sure their server-side + .ssh/environment files (or .bashrc, etc., according to their specific shell) + export appropriate values for GIT_AUTHOR_NAME, GIT_AUTHOR_EMAIL, + GIT_COMMITTER_NAME, and GIT_COMMITTER_EMAIL. For SSH clients whose login + shell is bash, .bashrc may be a reasonable alternative. 5. Clients should now be able to check out the project. Use the CVS 'module' - name to indicate what GIT 'head' you want to check out. Example: + name to indicate what GIT 'head' you want to check out. This also sets the + name of your newly checked-out directory, unless you tell it otherwise with + `-d <dir_name>`. For example, this checks out 'master' branch to the + `project-master` directory: + ------ cvs co -d project-master master @@ -227,6 +233,11 @@ gitcvs.dbpass:: Database password. Only useful if setting `dbdriver`, since SQLite has no concept of database passwords. +gitcvs.dbTableNamePrefix:: + Database table name prefix. Supports variable substitution + (see below). Any non-alphabetic characters will be replaced + with underscores. + All variables can also be set per access method, see <<configaccessmethod,above>>. Variable substitution diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt index 9d11b418bb..8d80f0d074 100644 --- a/Documentation/git-filter-branch.txt +++ b/Documentation/git-filter-branch.txt @@ -249,12 +249,12 @@ committed a merge between P1 and P2, it will be propagated properly and all children of the merge will become merge commits with P1,P2 as their parents instead of the merge commit. -You can rewrite the commit log messages using `--message-filter`. For +You can rewrite the commit log messages using `--msg-filter`. For example, `git-svn-id` strings in a repository created by `git-svn` can be removed this way: ------------------------------------------------------- -git filter-branch --message-filter ' +git filter-branch --msg-filter ' sed -e "/^git-svn-id:/d" ' ------------------------------------------------------- diff --git a/Documentation/git-fsck.txt b/Documentation/git-fsck.txt index f16cb98612..4cc26fb744 100644 --- a/Documentation/git-fsck.txt +++ b/Documentation/git-fsck.txt @@ -22,7 +22,8 @@ OPTIONS An object to treat as the head of an unreachability trace. + If no objects are given, git-fsck defaults to using the -index file and all SHA1 references in .git/refs/* as heads. +index file, all SHA1 references in .git/refs/*, and all reflogs (unless +--no-reflogs is given) as heads. --unreachable:: Print out objects that exist but that aren't readable from any diff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt index d424a4ecbe..b6b5ce1519 100644 --- a/Documentation/git-gc.txt +++ b/Documentation/git-gc.txt @@ -104,6 +104,21 @@ The optional configuration variable 'gc.pruneExpire' controls how old the unreferenced loose objects have to be before they are pruned. The default is "2 weeks ago". + +Notes +----- + +git-gc tries very hard to be safe about the garbage it collects. In +particular, it will keep not only objects referenced by your current set +of branches and tags, but also objects referenced by the index, remote +tracking branches, refs saved by linkgit:git-filter-branch[1] in +refs/original/, or reflogs (which may references commits in branches +that were later amended or rewound). + +If you are expecting some objects to be collected and they aren't, check +all of those locations and decide whether it makes sense in your case to +remove those references. + See Also -------- linkgit:git-prune[1] diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt index 62914da97b..b17ae8485c 100644 --- a/Documentation/git-init.txt +++ b/Documentation/git-init.txt @@ -31,7 +31,7 @@ structure, some suggested "exclude patterns", and copies of non-executing "hook" files. The suggested patterns and hook files are all modifiable and extensible. ---shared[={false|true|umask|group|all|world|everybody}]:: +--shared[={false|true|umask|group|all|world|everybody|0xxx}]:: Specify that the git repository is to be shared amongst several users. This allows users belonging to the same group to push into that @@ -52,6 +52,12 @@ is given: - 'all' (or 'world' or 'everybody'): Same as 'group', but make the repository readable by all users. + - '0xxx': '0xxx' is an octal number and each file will have mode '0xxx' + Any option except 'umask' can be set using this option. '0xxx' will + override users umask(2) value, and thus, users with a safe umask (0077) + can use this option. '0640' will create a repository which is group-readable + but not writable. '0660' is equivalent to 'group'. + By default, the configuration flag receive.denyNonFastForwards is enabled in shared repositories, so that you cannot force a non fast-forwarding push into it. diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt index eed0a94c6e..3a1be08186 100644 --- a/Documentation/git-pack-objects.txt +++ b/Documentation/git-pack-objects.txt @@ -22,8 +22,9 @@ archive with specified base-name, or to the standard output. A packed archive is an efficient way to transfer set of objects between two repositories, and also is an archival format which is efficient to access. The packed archive format (.pack) is -designed to be unpackable without having anything else, but for -random access, accompanied with the pack index file (.idx). +designed to be self contained so that it can be unpacked without +any further information, but for fast, random access to the objects +in the pack, a pack index file (.idx) will be generated. Placing both in the pack/ subdirectory of $GIT_OBJECT_DIRECTORY (or any of the directories on $GIT_ALTERNATE_OBJECT_DIRECTORIES) diff --git a/Documentation/git-prune.txt b/Documentation/git-prune.txt index f151cff5d9..f92bb8cfa0 100644 --- a/Documentation/git-prune.txt +++ b/Documentation/git-prune.txt @@ -13,6 +13,9 @@ SYNOPSIS DESCRIPTION ----------- +NOTE: In most cases, users should run linkgit:git-gc[1], which calls +git-prune. See the section "NOTES", below. + This runs `git-fsck --unreachable` using all the refs available in `$GIT_DIR/refs`, optionally with additional set of objects specified on the command line, and prunes all @@ -50,6 +53,23 @@ borrows from your repository via its $ git prune $(cd ../another && $(git-rev-parse --all)) ------------ +Notes +----- + +In most cases, users will not need to call git-prune directly, but +should instead call linkgit:git-gc[1], which handles pruning along with +many other housekeeping tasks. + +For a description of which objects are considered for pruning, see +git-fsck's --unreachable option. + +See Also +-------- + +linkgit:git-fsck[1], +linkgit:git-gc[1], +linkgit:git-reflog[1] + Author ------ Written by Linus Torvalds <torvalds@osdl.org> diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index 3128170bcd..f06d94e318 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -35,14 +35,15 @@ OPTIONS by the source ref, followed by a colon `:`, followed by the destination ref. + -The <src> side can be an -arbitrary "SHA1 expression" that can be used as an -argument to `git-cat-file -t`. E.g. `master~4` (push -four parents before the current master head). +The <src> side represents the source branch (or arbitrary +"SHA1 expression", such as `master~4` (four parents before the +tip of `master` branch); see linkgit:git-rev-parse[1]) that you +want to push. The <dst> side represents the destination location. + The local ref that matches <src> is used -to fast forward the remote ref that matches <dst>. If -the optional plus `+` is used, the remote ref is updated +to fast forward the remote ref that matches <dst> (or, if no <dst> was +specified, the same ref that <src> referred to locally). If +the optional leading plus `+` is used, the remote ref is updated even if it does not result in a fast forward update. + Note: If no explicit refspec is found, (that is neither @@ -69,7 +70,9 @@ the remote repository. be mirrored to the remote repository. Newly created local refs will be pushed to the remote end, locally updated refs will be force updated on the remote end, and deleted refs - will be removed from the remote end. + will be removed from the remote end. This is the default + if the configuration option `remote.<remote>.mirror` is + set. \--dry-run:: Do everything except actually send the updates. @@ -165,7 +168,8 @@ git push origin master:: Find a ref that matches `master` in the source repository (most likely, it would find `refs/heads/master`), and update the same ref (e.g. `refs/heads/master`) in `origin` repository - with it. + with it. If `master` did not exist remotely, it would be + created. git push origin :experimental:: Find a ref that matches `experimental` in the `origin` repository @@ -179,9 +183,10 @@ git push origin master:satellite/master:: git push origin master:refs/heads/experimental:: Create the branch `experimental` in the `origin` repository - by copying the current `master` branch. This form is usually - needed to create a new branch in the remote repository as - there is no `experimental` branch to match. + by copying the current `master` branch. This form is only + needed to create a new branch or tag in the remote repository when + the local name and the remote name are different; otherwise, + the ref name on its own will work. Author ------ diff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt index 2cbd1f764b..b20e851973 100644 --- a/Documentation/git-remote.txt +++ b/Documentation/git-remote.txt @@ -47,9 +47,11 @@ With `-m <master>` option, `$GIT_DIR/remotes/<name>/HEAD` is set up to point at remote's `<master>` branch instead of whatever branch the `HEAD` at the remote repository actually points at. + -In mirror mode, enabled with `--mirror`, the refs will not be stored +In mirror mode, enabled with `\--mirror`, the refs will not be stored in the 'refs/remotes/' namespace, but in 'refs/heads/'. This option -only makes sense in bare repositories. +only makes sense in bare repositories. If a remote uses mirror +mode, furthermore, `git push` will always behave as if `\--mirror` +was passed. 'rm':: diff --git a/Documentation/git-request-pull.txt b/Documentation/git-request-pull.txt index 270df9b185..9a14c04e39 100644 --- a/Documentation/git-request-pull.txt +++ b/Documentation/git-request-pull.txt @@ -24,7 +24,7 @@ OPTIONS URL to include in the summary. <end>:: - Commit to send at; defaults to HEAD. + Commit to end at; defaults to HEAD. Author ------ diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index 6513c2efe1..110e7ba71f 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -52,6 +52,11 @@ OPTIONS The parameter given must be usable as a single, valid object name. Otherwise barf and abort. +-q, --quiet:: + Only meaningful in `--verify` mode. Do not output an error + message if the first argument is not a valid object name; + instead exit with non-zero status silently. + --sq:: Usually the output is made one line per flag and parameter. This option makes output a single line, diff --git a/Documentation/git-rm.txt b/Documentation/git-rm.txt index dc36c662ae..9c81b72dbe 100644 --- a/Documentation/git-rm.txt +++ b/Documentation/git-rm.txt @@ -11,28 +11,37 @@ SYNOPSIS DESCRIPTION ----------- -Remove files from the working tree and from the index. The -files have to be identical to the tip of the branch, and no -updates to its contents must have been placed in the staging -area (aka index). When --cached is given, the staged content has to -match either the tip of the branch *or* the file on disk. +Remove files from the index, or from the working tree and the index. +`git rm` will not remove a file from just your working directory. +(There is no option to remove a file only from the work tree +and yet keep it in the index; use `/bin/rm` if you want to do that.) +The files being removed have to be identical to the tip of the branch, +and no updates to their contents can be staged in the index, +though that default behavior can be overridden with the `-f` option. +When '--cached' is given, the staged content has to +match either the tip of the branch or the file on disk, +allowing the file to be removed from just the index. OPTIONS ------- <file>...:: Files to remove. Fileglobs (e.g. `*.c`) can be given to - remove all matching files. Also a leading directory name - (e.g. `dir` to add `dir/file1` and `dir/file2`) can be - given to remove all files in the directory, recursively, - but this requires `-r` option to be given for safety. + remove all matching files. If you want git to expand + file glob characters, you may need to shell-escape them. + A leading directory name + (e.g. `dir` to remove `dir/file1` and `dir/file2`) can be + given to remove all files in the directory, and recursively + all sub-directories, + but this requires the `-r` option to be explicitly given. -f:: Override the up-to-date check. -n, \--dry-run:: - Don't actually remove the file(s), just show if they exist in - the index. + Don't actually remove any file(s). Instead, just show + if they exist in the index and would otherwise be removed + by the command. -r:: Allow recursive removal when a leading directory name is @@ -44,9 +53,9 @@ OPTIONS for command-line options). \--cached:: - This option can be used to tell the command to remove - the paths only from the index, leaving working tree - files. + Use this option to unstage and remove paths only from the index. + Working tree files, whether modified or not, will be + left alone. \--ignore-unmatch:: Exit with a zero status even if no files matched. @@ -59,11 +68,15 @@ OPTIONS DISCUSSION ---------- -The list of <file> given to the command can be exact pathnames, -file glob patterns, or leading directory name. The command -removes only the paths that is known to git. Giving the name of +The <file> list given to the command can be exact pathnames, +file glob patterns, or leading directory names. The command +removes only the paths that are known to git. Giving the name of a file that you have not told git about does not remove that file. +File globbing matches across directory boundaries. Thus, given +two directories `d` and `d2`, there is a difference between +using `git rm \'d\*\'` and `git rm \'d/\*\'`, as the former will +also remove all of directory `d2`. EXAMPLES -------- @@ -72,11 +85,10 @@ git-rm Documentation/\\*.txt:: `Documentation` directory and any of its subdirectories. + Note that the asterisk `\*` is quoted from the shell in this -example; this lets the command include the files from -subdirectories of `Documentation/` directory. +example; this lets git, and not the shell, expand the pathnames +of files and subdirectories under the `Documentation/` directory. git-rm -f git-*.sh:: - Remove all git-*.sh scripts that are in the index. Because this example lets the shell expand the asterisk (i.e. you are listing the files explicitly), it does not remove `subdir/git-foo.sh`. diff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt index c7752575d8..d7cb4c0468 100644 --- a/Documentation/git-shortlog.txt +++ b/Documentation/git-shortlog.txt @@ -8,8 +8,8 @@ git-shortlog - Summarize 'git log' output SYNOPSIS -------- [verse] -git-log --pretty=short | 'git-shortlog' [-h] [-n] [-s] [-e] -git-shortlog [-n|--numbered] [-s|--summary] [-e|--email] [<committish>...] +git-log --pretty=short | 'git-shortlog' [-h] [-n] [-s] [-e] [-w] +git-shortlog [-n|--numbered] [-s|--summary] [-e|--email] [-w[<width>[,<indent1>[,<indent2>]]]] [<committish>...] DESCRIPTION ----------- @@ -35,6 +35,12 @@ OPTIONS -e, \--email:: Show the email address of each author. +-w[<width>[,<indent1>[,<indent2>]]]:: + Linewrap the output by wrapping each line at `width`. The first + line of each entry is indented by `indent1` spaces, and the second + and subsequent lines are indented by `indent2` spaces. `width`, + `indent1`, and `indent2` default to 76, 6 and 9 respectively. + FILES ----- diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt index 3ea269aa7a..ea4376a17f 100644 --- a/Documentation/git-status.txt +++ b/Documentation/git-status.txt @@ -52,6 +52,11 @@ If the config variable `status.relativePaths` is set to false, then all paths shown are relative to the repository root, not to the current directory. +If `status.submodulesummary` is set to a non zero number or true (identical +to -1 or an unlimited number), the submodule summary will be enabled and a +summary of commits for modified submodules will be shown (see --summary-limit +option of linkgit:git-submodule[1]). + See Also -------- linkgit:gitignore[5] diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 41f9f63566..6ffd896fbc 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -70,7 +70,7 @@ OPTIONS -n, --summary-limit:: This option is only valid for the summary command. Limit the summary size (number of commits shown in total). - Giving 0 will disable the summary; a negative number means unlimted + Giving 0 will disable the summary; a negative number means unlimited (the default). This limit only applies to modified submodules. The size is always limited to 1 for added/deleted/typechanged submodules. diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt index bec9accc89..f4ba1056f0 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -188,6 +188,12 @@ All arguments are passed directly to `git blame'. commit. All merging is assumed to have taken place independently of git-svn functions. +'create-ignore':: + + Recursively finds the svn:ignore property on directories and + creates matching .gitignore files. The resulting files are staged to + be committed, but are not committed. + 'show-ignore':: Recursively finds and lists the svn:ignore property on directories. The output is suitable for appending to diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt index c22fb71176..9712392f79 100644 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@ -11,7 +11,7 @@ SYNOPSIS [verse] 'git-tag' [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>] <name> [<head>] 'git-tag' -d <name>... -'git-tag' [-n [<num>]] -l [<pattern>] +'git-tag' [-n[<num>]] -l [<pattern>] 'git-tag' -v <name>... DESCRIPTION @@ -57,7 +57,7 @@ OPTIONS -v:: Verify the gpg signature of the given tag names. --n <num>:: +-n<num>:: <num> specifies how many lines from the annotation, if any, are printed when using -l. The default is not to print any annotation lines. @@ -233,14 +233,14 @@ the tag object affects, for example, the ordering of tags in the gitweb interface. To set the date used in future tag objects, set the environment -variable GIT_AUTHOR_DATE to one or more of the date and time. The +variable GIT_COMMITTER_DATE to one or more of the date and time. The date and time can be specified in a number of ways; the most common is "YYYY-MM-DD HH:MM". An example follows. ------------ -$ GIT_AUTHOR_DATE="2006-10-02 10:31" git tag -s v1.0.1 +$ GIT_COMMITTER_DATE="2006-10-02 10:31" git tag -s v1.0.1 ------------ diff --git a/Documentation/git-unpack-objects.txt b/Documentation/git-unpack-objects.txt index b79be3fd4c..50947c50df 100644 --- a/Documentation/git-unpack-objects.txt +++ b/Documentation/git-unpack-objects.txt @@ -8,7 +8,7 @@ git-unpack-objects - Unpack objects from a packed archive SYNOPSIS -------- -'git-unpack-objects' [-n] [-q] [-r] <pack-file +'git-unpack-objects' [-n] [-q] [-r] [--strict] <pack-file DESCRIPTION @@ -40,6 +40,9 @@ OPTIONS and make the best effort to recover as many objects as possible. +--strict:: + Don't write objects with broken content or links. + Author ------ diff --git a/Documentation/git.txt b/Documentation/git.txt index aaf3189936..6f445b1e3b 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -43,6 +43,14 @@ unreleased) version of git, that is available from 'master' branch of the `git.git` repository. Documentation for older releases are available here: +* link:v1.5.5/git.html[documentation for release 1.5.5] + +* release notes for + link:RelNotes-1.5.5.1.txt[1.5.5.1], + link:RelNotes-1.5.5.txt[1.5.5]. + +* link:v1.5.5.1/git.html[documentation for release 1.5.5.1] + * link:v1.5.4.5/git.html[documentation for release 1.5.4.5] * release notes for @@ -135,7 +143,8 @@ help ...'. --git-dir=<path>:: Set the path to the repository. This can also be controlled by - setting the GIT_DIR environment variable. + setting the GIT_DIR environment variable. It can be an absolute + path or relative path to current working directory. --work-tree=<path>:: Set the path to the working tree. The value will not be @@ -143,7 +152,12 @@ help ...'. a .git directory (i.e. $GIT_DIR is not set). This can also be controlled by setting the GIT_WORK_TREE environment variable and the core.worktree configuration - variable. + variable. It can be an absolute path or relative path to + the directory specified by --git-dir or GIT_DIR. + Note: If --git-dir or GIT_DIR are specified but none of + --work-tree, GIT_WORK_TREE and core.worktree is specified, + the current working directory is regarded as the top directory + of your working tree. --bare:: Treat the repository as a bare repository. If GIT_DIR diff --git a/Documentation/gitk.txt b/Documentation/gitk.txt index 29edafceda..50d12da89f 100644 --- a/Documentation/gitk.txt +++ b/Documentation/gitk.txt @@ -41,6 +41,12 @@ frequently used options. Show all branches. +--merge:: + + After an attempt to merge stops with conflicts, show the commits on + the history between two branches (i.e. the HEAD and the MERGE_HEAD) + that modify the conflicted files. + <revs>:: Limit the revisions to show. This can be either a single revision @@ -74,6 +80,11 @@ gitk --max-count=100 --all \-- Makefile:: Show at most 100 changes made to the file 'Makefile'. Instead of only looking for changes in the current branch look in all branches. +Files +----- +Gitk creates the .gitk file in your $HOME directory to store preferences +such as display options, font, and colors. + See Also -------- 'qgit(1)':: diff --git a/Documentation/hooks.txt b/Documentation/hooks.txt index 76b8d77460..d89cc22261 100644 --- a/Documentation/hooks.txt +++ b/Documentation/hooks.txt @@ -28,10 +28,11 @@ The default 'applypatch-msg' hook, when enabled, runs the pre-applypatch -------------- -This hook is invoked by `git-am`. It takes no parameter, -and is invoked after the patch is applied, but before a commit -is made. Exiting with non-zero status causes the working tree -after application of the patch not committed. +This hook is invoked by `git-am`. It takes no parameter, and is +invoked after the patch is applied, but before a commit is made. + +If it exits with non-zero status, then the working tree will not be +committed after applying the patch. It can be used to inspect the current working tree and refuse to make a commit if it does not pass certain test. @@ -136,7 +137,8 @@ post-merge This hook is invoked by `git-merge`, which happens when a `git pull` is done on a local repository. The hook takes a single parameter, a status flag specifying whether or not the merge being done was a squash merge. -This hook cannot affect the outcome of `git-merge`. +This hook cannot affect the outcome of `git-merge` and is not executed, +if the merge failed due to conflicts. This hook can be used in conjunction with a corresponding pre-commit hook to save and restore any form of metadata associated with the working tree @@ -276,3 +278,10 @@ probably enable this hook. Both standard output and standard error output are forwarded to `git-send-pack` on the other end, so you can simply `echo` messages for the user. + +pre-auto-gc +----------- + +This hook is invoked by `git-gc --auto`. It takes no parameter, and +exiting with non-zero status from this script causes the `git-gc --auto` +to abort. diff --git a/Documentation/howto/setup-git-server-over-http.txt b/Documentation/howto/setup-git-server-over-http.txt index 8eadc20494..b7d09c1ec6 100644 --- a/Documentation/howto/setup-git-server-over-http.txt +++ b/Documentation/howto/setup-git-server-over-http.txt @@ -1,5 +1,5 @@ From: Rutger Nijlunsing <rutger@nospam.com> -Subject: Setting up a git repository which can be pushed into and pulled from over HTTP. +Subject: Setting up a git repository which can be pushed into and pulled from over HTTP(S). Date: Thu, 10 Aug 2006 22:00:26 +0200 Since Apache is one of those packages people like to compile @@ -40,9 +40,13 @@ What's needed: - have permissions to chown a directory -- have git installed at the server _and_ client +- have git installed on the client, and -In effect, this probably means you're going to be root. +- either have git installed on the server or have a webdav client on + the client. + +In effect, this means you're going to be root, or that you're using a +preconfigured WebDAV server. Step 1: setup a bare GIT repository @@ -50,9 +54,9 @@ Step 1: setup a bare GIT repository At the time of writing, git-http-push cannot remotely create a GIT repository. So we have to do that at the server side with git. Another -option would be to generate an empty repository at the client and copy -it to the server with WebDAV. But then you're probably the first to -try that out :) +option is to generate an empty bare repository at the client and copy +it to the server with a WebDAV client (which is the only option if Git +is not installed on the server). Create the directory under the DocumentRoot of the directories served by Apache. As an example we take /usr/local/apache2, but try "grep @@ -169,7 +173,9 @@ On Debian: Most tests should pass. -A command line tool to test WebDAV is cadaver. +A command line tool to test WebDAV is cadaver. If you prefer GUIs, for +example, konqueror can open WebDAV URLs as "webdav://..." or +"webdavs://...". If you're into Windows, from XP onwards Internet Explorer supports WebDAV. For this, do Internet Explorer -> Open Location -> @@ -179,8 +185,9 @@ http://<servername>/my-new-repo.git [x] Open as webfolder -> login . Step 3: setup the client ------------------------ -Make sure that you have HTTP support, i.e. your git was built with curl. -The easiest way to check is to look for the executable 'git-http-push'. +Make sure that you have HTTP support, i.e. your git was built with +curl (version more recent than 7.10). The command 'git http-push' with +no argument should display a usage message. Then, add the following to your $HOME/.netrc (you can do without, but will be asked to input your password a _lot_ of times): @@ -197,10 +204,10 @@ instead of the server name. To check whether all is OK, do: - curl --netrc --location -v http://<username>@<servername>/my-new-repo.git/ - -...this should give a directory listing in HTML of /var/www/my-new-repo.git . + curl --netrc --location -v http://<username>@<servername>/my-new-repo.git/HEAD +...this should give something like 'ref: refs/heads/master', which is +the content of the file HEAD on the server. Now, add the remote in your existing repository which contains the project you want to export: @@ -225,6 +232,15 @@ want to export) to repository called 'upload', which we previously defined with git-config. +Using a proxy: +-------------- + +If you have to access the WebDAV server from behind an HTTP(S) proxy, +set the variable 'all_proxy' to 'http://proxy-host.com:port', or +'http://login-on-proxy:passwd-on-proxy@proxy-host.com:port'. See 'man +curl' for details. + + Troubleshooting: ---------------- @@ -248,9 +264,14 @@ Reading /usr/local/apache2/logs/error_log is often helpful. On Debian: Read /var/log/apache2/error.log instead. +If you access HTTPS locations, git may fail verifying the SSL +certificate (this is return code 60). Setting http.sslVerify=false can +help diagnosing the problem, but removes security checks. + Debian References: http://www.debian-administration.org/articles/285 Authors Johannes Schindelin <Johannes.Schindelin@gmx.de> Rutger Nijlunsing <git@wingding.demon.nl> + Matthieu Moy <Matthieu.Moy@imag.fr> diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt index 0193c3ce58..e8bea3e18e 100644 --- a/Documentation/pretty-formats.txt +++ b/Documentation/pretty-formats.txt @@ -123,3 +123,4 @@ The placeholders are: - '%Creset': reset color - '%m': left, right or boundary mark - '%n': newline +- '%x00': print a byte from a hex code diff --git a/Documentation/repository-layout.txt b/Documentation/repository-layout.txt index 6939130094..bbaed2e129 100644 --- a/Documentation/repository-layout.txt +++ b/Documentation/repository-layout.txt @@ -3,7 +3,10 @@ git repository layout You may find these things in your git repository (`.git` directory for a repository associated with your working tree, or -`'project'.git` directory for a public 'bare' repository). +`'project'.git` directory for a public 'bare' repository. It is +also possible to have a working tree where `.git` is a plain +ascii file containing `gitdir: <path>`, i.e. the path to the +real git repository). objects:: Object store associated with this repository. Usually diff --git a/Documentation/technical/pack-format.txt b/Documentation/technical/pack-format.txt index aa87756a55..1803e64e46 100644 --- a/Documentation/technical/pack-format.txt +++ b/Documentation/technical/pack-format.txt @@ -103,10 +103,24 @@ Pack file entry: <+ packed object data: If it is not DELTA, then deflated bytes (the size above is the size before compression). - If it is DELTA, then + If it is REF_DELTA, then 20-byte base object name SHA1 (the size above is the size of the delta data that follows). delta data, deflated. + If it is OFS_DELTA, then + n-byte offset (see below) interpreted as a negative + offset from the type-byte of the header of the + ofs-delta entry (the size above is the size of + the delta data that follows). + delta data, deflated. + + offset encoding: + n bytes with MSB set in all but the last one. + The offset is then the number constructed by + concatenating the lower 7 bit of each byte, and + for n >= 2 adding 2^7 + 2^14 + ... + 2^(7*(n-1)) + to the result. + = Version 2 pack-*.idx files support packs larger than 4 GiB, and diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index 565aeb9804..86b91a53e5 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -1548,22 +1548,7 @@ dangling tree b24c2473f1fd3d91352a624795be026d64c8841f Dangling objects are not a problem. At worst they may take up a little extra disk space. They can sometimes provide a last-resort method for -recovering lost work--see <<dangling-objects>> for details. However, if -you wish, you can remove them with linkgit:git-prune[1] or the `--prune` -option to linkgit:git-gc[1]: - -------------------------------------------------- -$ git gc --prune -------------------------------------------------- - -This may be time-consuming. Unlike most other git operations (including -git-gc when run without any options), it is not safe to prune while -other git operations are in progress in the same repository. - -If linkgit:git-fsck[1] complains about sha1 mismatches or missing -objects, you may have a much more serious problem; your best option is -probably restoring from backups. See -<<recovering-from-repository-corruption>> for a detailed discussion. +recovering lost work--see <<dangling-objects>> for details. [[recovering-lost-changes]] Recovering lost changes |