diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/RelNotes-1.5.3.7.txt | 45 | ||||
| -rw-r--r-- | Documentation/RelNotes-1.5.4.txt | 95 | ||||
| -rwxr-xr-x | Documentation/cmd-list.perl | 2 | ||||
| -rw-r--r-- | Documentation/git-branch.txt | 21 | ||||
| -rw-r--r-- | Documentation/git-peek-remote.txt | 3 | ||||
| -rw-r--r-- | Documentation/git-push.txt | 8 | ||||
| -rw-r--r-- | Documentation/git-tag.txt | 4 | ||||
| -rw-r--r-- | Documentation/git.txt | 1 | ||||
| -rw-r--r-- | Documentation/user-manual.txt | 227 |
9 files changed, 364 insertions, 42 deletions
diff --git a/Documentation/RelNotes-1.5.3.7.txt b/Documentation/RelNotes-1.5.3.7.txt new file mode 100644 index 0000000000..2f690616c8 --- /dev/null +++ b/Documentation/RelNotes-1.5.3.7.txt @@ -0,0 +1,45 @@ +GIT v1.5.3.7 Release Notes +========================== + +Fixes since v1.5.3.6 +-------------------- + + * git-send-email added 8-bit contents to the payload without + marking it as 8-bit in a CTE header. + + * "git-bundle create a.bndl HEAD" dereferenced the symref and + did not record the ref as 'HEAD'; this prevented a bundle + from being used as a normal source of git-clone. + + * The code to reject nonsense command line of the form + "git-commit -a paths..." and "git-commit --interactive + paths..." were broken. + + * Adding a signature that is not ASCII-only to an original + commit that is ASCII-only would make the result non-ASCII. + "git-format-patch -s" did not mark such a message correctly + with MIME encoding header. + + * git-add sometimes did not mark the resulting index entry + stat-clean. This affected only cases when adding the + contents with the same length as the previously staged + contents, and the previous staging made the index entry + "racily clean". + + * git-commit did not honor GIT_INDEX_FILE the user had in the + environment. + + * When checking out a revision, git-checkout did not report where the + updated HEAD is if you happened to have a file called HEAD in the + work tree. + + * "git-rev-list --objects" mishandled a tree that points at a + submodule. + + * "git cvsimport" was not ready for packed refs that "git gc" can + produce and gave incorrect results. + + * Many scripted Porcelains were confused when you happened to have a + file called "HEAD" in your work tree. + +Also it contains updates to the user manual and documentation. diff --git a/Documentation/RelNotes-1.5.4.txt b/Documentation/RelNotes-1.5.4.txt index a4a2a7f429..192766f868 100644 --- a/Documentation/RelNotes-1.5.4.txt +++ b/Documentation/RelNotes-1.5.4.txt @@ -1,20 +1,70 @@ GIT v1.5.4 Release Notes ======================== +Deprecation notices +------------------- + + * Next feature release of git (this change is scheduled for v1.5.5 but + it could slip) will by default install dashed form of commands + (e.g. "git-commit") outside of users' normal $PATH, and will install + only selected commands ("git" itself, and "gitk") in $PATH. This + implies: + + - Using dashed form of git commands (e.g. "git-commit") from the + command line has been informally deprecated since early 2006, but + now it officially is, and will be removed in the future. Use + dashless form (e.g. "git commit") instead. + + - Using dashed from from your scripts, without first prepending the + return value from "git --exec-path" to the scripts' PATH, has been + informally deprecated since early 2006, but now it officially is. + + - Use of dashed form with "PATH=$(git --exec-path):$PATH; export + PATH" early in your script is not deprecated with this change. + + Users are strongly encouraged to adjust their habits and scripts now + to prepare for this. + + * The post-receive hook was introduced in March 2007 to supersede + post-update hook, primarily to overcome the command line length + limitation of the latter. Use of post-update hook will be deprecated + in future versions of git, perhaps in v1.5.5. + + Updates since v1.5.3 -------------------- * Comes with much improved gitk. + * Comes with git-gui 0.9.0 with i18n. + + * git-lost-found was deprecated in favor of git-fsck's --lost-found + option. + + * git-peek-remote is deprecated, as git-ls-remote was written in C and + works for all transports. + + * git-cherry-pick made a misguided attempt to repeat the original + command line in the generated log message, when told to cherry-pick a + commit by naming a tag that points at it. It does not anymore. + * "progress display" from many commands are a lot nicer to the eye. Transfer commands show throughput data. + * many commands that pay attention to per-directory .gitignore now do + so lazily, which makes the usual case go much faster. + * git-reset is now built-in and its output can be squelched with -q. * git-send-email can optionally talk over ssmtp and use SMTP-AUTH. * git-rebase learned --whitespace option. + * In git-rebase, when you decide not to replay a particular change + after the command stopped with a conflict, you can say "git-rebase + --skip" without first running "git reset --hard", as the command now + runs it for you. + * git-remote knows --mirror mode. * git-merge can call the "post-merge" hook. @@ -37,11 +87,20 @@ Updates since v1.5.3 variable used to mean "do not require", but we now use the safer default). + * git-clean has been rewritten in C. + * git-push has been rewritten in C. * git-push learned --dry-run option to show what would happen if a push is run. + * git-push does not update a tracking ref on the pushing side when the + remote refused to update the corresponding ref. + + * git-push learned --mirror option. This is to push the local refs + one-to-one to the remote, and deletes refs from the remote that do + not exist anymore in the repository on the pushing side. + * git-remote learned "rm" subcommand. * git-rebase --interactive mode can now work on detached HEAD. @@ -54,9 +113,6 @@ Updates since v1.5.3 * Various Perforce importer updates. - * git-lost-found was deprecated in favor of git-fsck's --lost-found - option. - * "git log" learned --early-output option to help interactive GUI implementations. @@ -86,14 +142,41 @@ Updates since v1.5.3 to allow checking out a path outside the current directory without cd'ing up. + * "git send-email --dry-run" shows full headers for easier + diagnosis. + + * "git merge-ours" is built-in. + + * "git svn" learned "info" and "show-externals" subcommands. + + * calling "git svn" from a subdirectory failed read settings from the + .git/config. + + * "git svn" learned --use-log-author option, which picks up more + descriptive name from From: and Signed-off-by: lines in the commit + message. + + * "git status" from a subdirectory now shows relative paths + which makes copy-and-pasting for git-checkout/git-add/git-rm + easier. + + * "git checkout" from and to detached HEAD leaves a bit more + information in the reflog. + * Output processing for '--pretty=format:<user format>' has been optimized. - * Rename detection diff family, while detecting exact matches, - has been greatly optimized. + * Rename detection of diff family, while detecting exact matches, has + been greatly optimized. + + * Rename detection of diff family tries to make more naturally looking + pairing. Earlier if more than one identical rename sources were + found in the preimage, they were picked pretty much at random. * Example update and post-receive hooks have been improved. + * A corrupt ref at the remote site can be removed via "git push". + * In addition there are quite a few internal clean-ups. Notably - many fork/exec have been replaced with run-command API, @@ -119,6 +202,6 @@ this release, unless otherwise noted. -- exec >/var/tmp/1 -O=v1.5.3.6-727-g5d3d1ca +O=v1.5.3.7-948-gb52e985 echo O=`git describe refs/heads/master` git shortlog --no-merges $O..refs/heads/master ^refs/heads/maint diff --git a/Documentation/cmd-list.perl b/Documentation/cmd-list.perl index 57a790df63..b709551726 100755 --- a/Documentation/cmd-list.perl +++ b/Documentation/cmd-list.perl @@ -151,7 +151,7 @@ git-pack-redundant plumbinginterrogators git-pack-refs ancillarymanipulators git-parse-remote synchelpers git-patch-id purehelpers -git-peek-remote purehelpers +git-peek-remote purehelpers deprecated git-prune ancillarymanipulators git-prune-packed plumbingmanipulators git-pull mainporcelain diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index 16303ef555..d3f21c7975 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -49,17 +49,22 @@ to happen. With a `-d` or `-D` option, `<branchname>` will be deleted. You may specify more than one branch for deletion. If the branch currently -has a reflog then the reflog will also be deleted. Use -r together with -d -to delete remote-tracking branches. +has a reflog then the reflog will also be deleted. + +Use -r together with -d to delete remote-tracking branches. Note, that it +only makes sense to delete remote-tracking branches if they no longer exist +in remote repository or if gitlink:git-fetch[1] was configured not to fetch +them again. See also 'prune' subcommand of gitlink:git-remote[1] for way to +clean up all obsolete remote-tracking branches. OPTIONS ------- -d:: - Delete a branch. The branch must be fully merged. + Delete a branch. The branch must be fully merged in HEAD. -D:: - Delete a branch irrespective of its index status. + Delete a branch irrespective of its merged status. -l:: Create the branch's reflog. This activates recording of @@ -157,9 +162,11 @@ $ git branch -d -r origin/todo origin/html origin/man <1> $ git branch -D test <2> ------------ + -<1> Delete remote-tracking branches "todo", "html", "man" -<2> Delete "test" branch even if the "master" branch does not have all -commits from test branch. +<1> Delete remote-tracking branches "todo", "html", "man". Next 'fetch' or +'pull' will create them again unless you configure them not to. See +gitlink:git-fetch[1]. +<2> Delete "test" branch even if the "master" branch (or whichever branch is +currently checked out) does not have all commits from test branch. Notes diff --git a/Documentation/git-peek-remote.txt b/Documentation/git-peek-remote.txt index abc171266a..38a5325af7 100644 --- a/Documentation/git-peek-remote.txt +++ b/Documentation/git-peek-remote.txt @@ -12,8 +12,7 @@ SYNOPSIS DESCRIPTION ----------- -Lists the references the remote repository has, and optionally -stores them in the local repository under the same name. +This command is deprecated; use `git-ls-remote` instead. OPTIONS ------- diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index 4a68aaba34..b8003c63c7 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -63,6 +63,14 @@ the remote repository. Instead of naming each ref to push, specifies that all refs under `$GIT_DIR/refs/heads/` be pushed. +\--mirror:: + Instead of naming each ref to push, specifies that all + refs under `$GIT_DIR/refs/heads/` and `$GIT_DIR/refs/tags/` + 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. + \--dry-run:: Do everything except actually send the updates. diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt index 10d3e3fa95..784ec6d4c2 100644 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@ -65,7 +65,9 @@ OPTIONS Typing "git tag" without arguments, also lists all tags. -m <msg>:: - Use the given tag message (instead of prompting) + Use the given tag message (instead of prompting). + If multiple `-m` options are given, there values are + concatenated as separate paragraphs. -F <file>:: Take the tag message from the given file. Use '-' to diff --git a/Documentation/git.txt b/Documentation/git.txt index 546020100a..9ff4659d8c 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -46,6 +46,7 @@ Documentation for older releases are available here: * link:v1.5.3/git.html[documentation for release 1.5.3] * release notes for + link:RelNotes-1.5.3.7.txt[1.5.3.7], link:RelNotes-1.5.3.6.txt[1.5.3.6], link:RelNotes-1.5.3.5.txt[1.5.3.5], link:RelNotes-1.5.3.4.txt[1.5.3.4], diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index 3661879f1a..93a47b439b 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -56,11 +56,12 @@ $ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git The initial clone may be time-consuming for a large project, but you will only need to clone once. -The clone command creates a new directory named after the project -("git" or "linux-2.6" in the examples above). After you cd into this +The clone command creates a new directory named after the project ("git" +or "linux-2.6" in the examples above). After you cd into this directory, you will see that it contains a copy of the project files, -together with a special top-level directory named ".git", which -contains all the information about the history of the project. +called the <<def_working_tree,working tree>>, together with a special +top-level directory named ".git", which contains all the information +about the history of the project. [[how-to-check-out]] How to check out a different version of a project @@ -71,8 +72,13 @@ of files. It stores the history as a compressed collection of interrelated snapshots of the project's contents. In git each such version is called a <<def_commit,commit>>. -A single git repository may contain multiple branches. It keeps track -of them by keeping a list of <<def_head,heads>> which reference the +Those snapshots aren't necessarily all arranged in a single line from +oldest to newest; instead, work may simultaneously proceed along +parallel lines of development, called <def_branch,branches>>, which may +merge and diverge. + +A single git repository can track development on multiple branches. It +does this by keeping a list of <<def_head,heads>> which reference the latest commit on each branch; the gitlink:git-branch[1] command shows you the list of branch heads: @@ -1410,8 +1416,8 @@ with the changes to be reverted, then you will be asked to fix conflicts manually, just as in the case of <<resolving-a-merge, resolving a merge>>. -[[fixing-a-mistake-by-editing-history]] -Fixing a mistake by editing history +[[fixing-a-mistake-by-rewriting-history]] +Fixing a mistake by rewriting history ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If the problematic commit is the most recent commit, and you have not @@ -1434,7 +1440,7 @@ Again, you should never do this to a commit that may already have been merged into another branch; use gitlink:git-revert[1] instead in that case. -It is also possible to edit commits further back in the history, but +It is also possible to replace commits further back in the history, but this is an advanced topic to be left for <<cleaning-up-history,another chapter>>. @@ -1554,6 +1560,11 @@ 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 gitlink: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-changes]] Recovering lost changes ~~~~~~~~~~~~~~~~~~~~~~~ @@ -1923,15 +1934,9 @@ or just $ git push ssh://yourserver.com/~you/proj.git master ------------------------------------------------- -As with git-fetch, git-push will complain if this does not result in -a <<fast-forwards,fast forward>>. Normally this is a sign of -something wrong. However, if you are sure you know what you're -doing, you may force git-push to perform the update anyway by -preceding the branch name by a plus sign: - -------------------------------------------------- -$ git push ssh://yourserver.com/~you/proj.git +master -------------------------------------------------- +As with git-fetch, git-push will complain if this does not result in a +<<fast-forwards,fast forward>>; see the following section for details on +handling this case. Note that the target of a "push" is normally a <<def_bare_repository,bare>> repository. You can also push to a @@ -1959,6 +1964,52 @@ See the explanations of the remote.<name>.url, branch.<name>.remote, and remote.<name>.push options in gitlink:git-config[1] for details. +[[forcing-push]] +What to do when a push fails +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If a push would not result in a <<fast-forwards,fast forward>> of the +remote branch, then it will fail with an error like: + +------------------------------------------------- +error: remote 'refs/heads/master' is not an ancestor of + local 'refs/heads/master'. + Maybe you are not up-to-date and need to pull first? +error: failed to push to 'ssh://yourserver.com/~you/proj.git' +------------------------------------------------- + +This can happen, for example, if you: + + - use `git reset --hard` to remove already-published commits, or + - use `git commit --amend` to replace already-published commits + (as in <<fixing-a-mistake-by-rewriting-history>>), or + - use `git rebase` to rebase any already-published commits (as + in <<using-git-rebase>>). + +You may force git-push to perform the update anyway by preceding the +branch name with a plus sign: + +------------------------------------------------- +$ git push ssh://yourserver.com/~you/proj.git +master +------------------------------------------------- + +Normally whenever a branch head in a public repository is modified, it +is modified to point to a descendent of the commit that it pointed to +before. By forcing a push in this situation, you break that convention. +(See <<problems-with-rewriting-history>>.) + +Nevertheless, this is a common practice for people that need a simple +way to publish a work-in-progress patch series, and it is an acceptable +compromise as long as you warn other developers that this is how you +intend to manage the branch. + +It's also possible for a push to fail in this way when other people have +the right to push to the same repository. In that case, the correct +solution is to retry the push after first updating your work by either a +pull or a fetch followed by a rebase; see the +<<setting-up-a-shared-repository,next section>> and +link:cvs-migration.html[git for CVS users] for more. + [[setting-up-a-shared-repository]] Setting up a shared repository ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -2426,11 +2477,11 @@ return mywork to the state it had before you started the rebase: $ git rebase --abort ------------------------------------------------- -[[modifying-one-commit]] -Modifying a single commit +[[rewriting-one-commit]] +Rewriting a single commit ------------------------- -We saw in <<fixing-a-mistake-by-editing-history>> that you can replace the +We saw in <<fixing-a-mistake-by-rewriting-history>> that you can replace the most recent commit using ------------------------------------------------- @@ -2440,8 +2491,10 @@ $ git commit --amend which will replace the old commit by a new commit incorporating your changes, giving you a chance to edit the old commit message first. -You can also use a combination of this and gitlink:git-rebase[1] to edit -commits further back in your history. First, tag the problematic commit with +You can also use a combination of this and gitlink:git-rebase[1] to +replace a commit further back in your history and recreate the +intervening changes on top of it. First, tag the problematic commit +with ------------------------------------------------- $ git tag bad mywork~5 @@ -3172,6 +3225,127 @@ confusing and scary messages, but it won't actually do anything bad. In contrast, running "git prune" while somebody is actively changing the repository is a *BAD* idea). +[[recovering-from-repository-corruption]] +Recovering from repository corruption +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +By design, git treats data trusted to it with caution. However, even in +the absence of bugs in git itself, it is still possible that hardware or +operating system errors could corrupt data. + +The first defense against such problems is backups. You can back up a +git directory using clone, or just using cp, tar, or any other backup +mechanism. + +As a last resort, you can search for the corrupted objects and attempt +to replace them by hand. Back up your repository before attempting this +in case you corrupt things even more in the process. + +We'll assume that the problem is a single missing or corrupted blob, +which is sometimes a solveable problem. (Recovering missing trees and +especially commits is *much* harder). + +Before starting, verify that there is corruption, and figure out where +it is with gitlink:git-fsck[1]; this may be time-consuming. + +Assume the output looks like this: + +------------------------------------------------ +$ git-fsck --full +broken link from tree 2d9263c6d23595e7cb2a21e5ebbb53655278dff8 + to blob 4b9458b3786228369c63936db65827de3cc06200 +missing blob 4b9458b3786228369c63936db65827de3cc06200 +------------------------------------------------ + +(Typically there will be some "dangling object" messages too, but they +aren't interesting.) + +Now you know that blob 4b9458b3 is missing, and that the tree 2d9263c6 +points to it. If you could find just one copy of that missing blob +object, possibly in some other repository, you could move it into +.git/objects/4b/9458b3... and be done. Suppose you can't. You can +still examine the tree that pointed to it with gitlink:git-ls-tree[1], +which might output something like: + +------------------------------------------------ +$ git ls-tree 2d9263c6d23595e7cb2a21e5ebbb53655278dff8 +100644 blob 8d14531846b95bfa3564b58ccfb7913a034323b8 .gitignore +100644 blob ebf9bf84da0aab5ed944264a5db2a65fe3a3e883 .mailmap +100644 blob ca442d313d86dc67e0a2e5d584b465bd382cbf5c COPYING +... +100644 blob 4b9458b3786228369c63936db65827de3cc06200 myfile +... +------------------------------------------------ + +So now you know that the missing blob was the data for a file named +"myfile". And chances are you can also identify the directory--let's +say it's in "somedirectory". If you're lucky the missing copy might be +the same as the copy you have checked out in your working tree at +"somedirectory/myfile"; you can test whether that's right with +gitlink:git-hash-object[1]: + +------------------------------------------------ +$ git hash-object -w somedirectory/myfile +------------------------------------------------ + +which will create and store a blob object with the contents of +somedirectory/myfile, and output the sha1 of that object. if you're +extremely lucky it might be 4b9458b3786228369c63936db65827de3cc06200, in +which case you've guessed right, and the corruption is fixed! + +Otherwise, you need more information. How do you tell which version of +the file has been lost? + +The easiest way to do this is with: + +------------------------------------------------ +$ git log --raw --all --full-history -- somedirectory/myfile +------------------------------------------------ + +Because you're asking for raw output, you'll now get something like + +------------------------------------------------ +commit abc +Author: +Date: +... +:100644 100644 4b9458b... newsha... M somedirectory/myfile + + +commit xyz +Author: +Date: + +... +:100644 100644 oldsha... 4b9458b... M somedirectory/myfile +------------------------------------------------ + +This tells you that the immediately preceding version of the file was +"newsha", and that the immediately following version was "oldsha". +You also know the commit messages that went with the change from oldsha +to 4b9458b and with the change from 4b9458b to newsha. + +If you've been committing small enough changes, you may now have a good +shot at reconstructing the contents of the in-between state 4b9458b. + +If you can do that, you can now recreate the missing object with + +------------------------------------------------ +$ git hash-object -w <recreated-file> +------------------------------------------------ + +and your repository is good again! + +(Btw, you could have ignored the fsck, and started with doing a + +------------------------------------------------ +$ git log --raw --all +------------------------------------------------ + +and just looked for the sha of the missing object (4b9458b..) in that +whole thing. It's up to you - git does *have* a lot of information, it is +just missing one particular blob version. + [[the-index]] The index ----------- @@ -3533,7 +3707,7 @@ should use the `--remove` and `--add` flags respectively. NOTE! A `--remove` flag does 'not' mean that subsequent filenames will necessarily be removed: if the files still exist in your directory structure, the index will be updated with their new status, not -removed. The only thing `--remove` means is that update-cache will be +removed. The only thing `--remove` means is that update-index will be considering a removed file to be a valid thing, and if the file really does not exist any more, it will update the index accordingly. @@ -4382,4 +4556,7 @@ Write a chapter on using plumbing and writing scripts. Alternates, clone -reference, etc. -git unpack-objects -r for recovery +More on recovery from repository corruption. See: + http://marc.theaimsgroup.com/?l=git&m=117263864820799&w=2 + http://marc.theaimsgroup.com/?l=git&m=117147855503798&w=2 + http://marc.theaimsgroup.com/?l=git&m=117147855503798&w=2 |