diff options
Diffstat (limited to 'Documentation')
90 files changed, 1003 insertions, 261 deletions
diff --git a/Documentation/Makefile b/Documentation/Makefile index bb21d6af44..3cfa360a9e 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -17,14 +17,14 @@ DOC_HTML += $(patsubst %,%.html,$(ARTICLES) $(SP_ARTICLES)) DOC_MAN1=$(patsubst %.txt,%.1,$(MAN1_TXT)) DOC_MAN7=$(patsubst %.txt,%.7,$(MAN7_TXT)) -prefix=$(HOME) +prefix?=$(HOME) bin=$(prefix)/bin mandir=$(prefix)/man man1=$(mandir)/man1 man7=$(mandir)/man7 # DESTDIR= -INSTALL=install +INSTALL?=install # # Please note that there is a minor bug in asciidoc. diff --git a/Documentation/cvs-migration.txt b/Documentation/cvs-migration.txt index 4361278dab..57436f0078 100644 --- a/Documentation/cvs-migration.txt +++ b/Documentation/cvs-migration.txt @@ -1,6 +1,5 @@ -Git for CVS users +git for CVS users ================= -v0.99.5, Aug 2005 Ok, so you're a CVS user. That's ok, it's a treatable condition, and the first step to recovery is admitting you have a problem. The fact that @@ -8,7 +7,7 @@ you are reading this file means that you may be well on that path already. The thing about CVS is that it absolutely sucks as a source control -manager, and you'll thus be happy with almost anything else. Git, +manager, and you'll thus be happy with almost anything else. git, however, may be a bit 'too' different (read: "good") for your taste, and does a lot of things differently. @@ -16,7 +15,7 @@ One particular suckage of CVS is very hard to work around: CVS is basically a tool for tracking 'file' history, while git is a tool for tracking 'project' history. This sometimes causes problems if you are used to doing very strange things in CVS, in particular if you're doing -things like making branches of just a subset of the project. Git can't +things like making branches of just a subset of the project. git can't track that, since git never tracks things on the level of an individual file, only on the whole project level. @@ -33,7 +32,7 @@ and notes on converting from CVS to git. Second: CVS has the notion of a "repository" as opposed to the thing that you're actually working in (your working directory, or your -"checked out tree"). Git does not have that notion at all, and all git +"checked out tree"). git does not have that notion at all, and all git working directories 'are' the repositories. However, you can easily emulate the CVS model by having one special "global repository", which people can synchronize with. See details later, but in the meantime @@ -50,7 +49,7 @@ gone through the git tutorial, and generally familiarized yourself with how to commit stuff etc in git) is to create a git'ified version of your CVS archive. -Happily, that's very easy indeed. Git will do it for you, although git +Happily, that's very easy indeed. git will do it for you, although git will need the help of a program called "cvsps": http://www.cobite.com/cvsps/ @@ -136,7 +135,7 @@ technically possible, and there are at least two specialized scripts out there that can be used to get equivalent information (see the git mailing list archives for details). -Git has a couple of alternatives, though, that you may find sufficient +git has a couple of alternatives, though, that you may find sufficient or even superior depending on your use. One is called "git-whatchanged" (for obvious reasons) and the other one is called "pickaxe" ("a tool for the software archeologist"). @@ -209,7 +208,7 @@ show anything for commits that do not touch this "if" statement. Also, in the original context, the same statement might have appeared at first in a different file and later the file was renamed to "a-file.c". CVS annotate would not help you to go -back across such a rename, but GIT would still help you in such +back across such a rename, but git would still help you in such a situation. For that, you can give the -C flag to git-diff-tree, like this: diff --git a/Documentation/diff-format.txt b/Documentation/diff-format.txt index dacd8fb534..d1d0d2d3dc 100644 --- a/Documentation/diff-format.txt +++ b/Documentation/diff-format.txt @@ -55,6 +55,11 @@ Example: :100644 100644 5be4a4...... 000000...... M file.c ------------------------------------------------ +When `-z` option is not used, TAB, LF, and backslash characters +in pathnames are represented as `\t`, `\n`, and `\\`, +respectively. + + Generating patches with -p -------------------------- @@ -106,7 +111,7 @@ For a path that is unmerged, 'GIT_EXTERNAL_DIFF' is called with 1 parameter, <path>. -Git specific extension to diff format +git specific extension to diff format ------------------------------------- What -p option produces is slightly different from the @@ -137,3 +142,7 @@ the file that rename/copy produces, respectively. rename to <path> similarity index <number> dissimilarity index <number> + index <hash>..<hash> <mode> + +3. TAB, LF, and backslash characters in pathnames are + represented as `\t`, `\n`, and `\\`, respectively. diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index 06500d04b7..32005b03f3 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -4,10 +4,6 @@ -u:: Synonym for "-p". --r:: - Look recursively in subdirectories; only used by "git-diff-tree"; - other diff commands always work recursively. - -z:: \0 line termination on output diff --git a/Documentation/diffcore.txt b/Documentation/diffcore.txt index 9d20a4ff19..cb4e562004 100644 --- a/Documentation/diffcore.txt +++ b/Documentation/diffcore.txt @@ -6,13 +6,12 @@ June 2005 Introduction ------------ -The diff commands git-diff-index, git-diff-files, and -git-diff-tree can be told to manipulate differences they find -in unconventional ways before showing diff(1) output. The -manipulation is collectively called "diffcore transformation". -This short note describes what they are and how to use them to -produce diff outputs that are easier to understand than the -conventional kind. +The diff commands git-diff-index, git-diff-files, git-diff-tree, and +git-diff-stages can be told to manipulate differences they find in +unconventional ways before showing diff(1) output. The manipulation +is collectively called "diffcore transformation". This short note +describes what they are and how to use them to produce diff outputs +that are easier to understand than the conventional kind. The chain of operation @@ -29,7 +28,10 @@ files: - git-diff-files compares contents of the index file and the working directory; - - git-diff-tree compares contents of two "tree" objects. + - git-diff-tree compares contents of two "tree" objects; + + - git-diff-stages compares contents of blobs at two stages in an + unmerged index file. In all of these cases, the commands themselves compare corresponding paths in the two sets of files. The result of @@ -65,14 +67,23 @@ format sections of the manual for git-diff-\* commands) or diff-patch format. -diffcore-pathspec ------------------ +diffcore-pathspec: For Ignoring Files Outside Our Consideration +--------------------------------------------------------------- The first transformation in the chain is diffcore-pathspec, and is controlled by giving the pathname parameters to the git-diff-* commands on the command line. The pathspec is used to limit the world diff operates in. It removes the filepairs -outside the specified set of pathnames. +outside the specified set of pathnames. E.g. If the input set +of filepairs included: + +------------------------------------------------ +:100644 100644 bcd1234... 0123456... M junkfile +------------------------------------------------ + +but the command invocation was "git-diff-files myfile", then the +junkfile entry would be removed from the list because only "myfile" +is under consideration. Implementation note. For performance reasons, git-diff-tree uses the pathname parameters on the command line to cull set of @@ -80,8 +91,8 @@ filepairs it feeds the diffcore mechanism itself, and does not use diffcore-pathspec, but the end result is the same. -diffcore-break --------------- +diffcore-break: For Splitting Up "Complete Rewrites" +---------------------------------------------------- The second transformation in the chain is diffcore-break, and is controlled by the -B option to the git-diff-* commands. This is @@ -115,8 +126,8 @@ the original is used), and can be customized by giving a number after "-B" option (e.g. "-B75" to tell it to use 75%). -diffcore-rename ---------------- +diffcore-rename: For Detection Renames and Copies +------------------------------------------------- This transformation is used to detect renames and copies, and is controlled by the -M option (to detect renames) and the -C option @@ -136,16 +147,16 @@ merges these filepairs and creates: :100644 100644 0123456... 0123456... R100 fileX file0 ------------------------------------------------ -When the "-C" option is used, the original contents of modified -files and contents of unchanged files are considered as -candidates of the source files in rename/copy operation, in -addition to the deleted files. If the input were like these -filepairs, that talk about a modified file fileY and a newly +When the "-C" option is used, the original contents of modified files, +and deleted files (and also unmodified files, if the +"\--find-copies-harder" option is used) are considered as candidates +of the source files in rename/copy operation. If the input were like +these filepairs, that talk about a modified file fileY and a newly created file file0: ------------------------------------------------ :100644 100644 0123456... 1234567... M fileY -:000000 100644 0000000... 0123456... A file0 +:000000 100644 0000000... bcd3456... A file0 ------------------------------------------------ the original contents of fileY and the resulting contents of @@ -154,14 +165,14 @@ changed to: ------------------------------------------------ :100644 100644 0123456... 1234567... M fileY -:100644 100644 0123456... 0123456... C100 fileY file0 +:100644 100644 0123456... bcd3456... C100 fileY file0 ------------------------------------------------ In both rename and copy detection, the same "extent of changes" algorithm used in diffcore-break is used to determine if two files are "similar enough", and can be customized to use -similarity score different from the default 50% by giving a -number after "-M" or "-C" option (e.g. "-M8" to tell it to use +a similarity score different from the default of 50% by giving a +number after the "-M" or "-C" option (e.g. "-M8" to tell it to use 8/10 = 80%). Note. When the "-C" option is used with `\--find-copies-harder` @@ -173,8 +184,8 @@ git-diff-\* commands can detect copies only if the file that was copied happened to have been modified in the same changeset. -diffcore-merge-broken ---------------------- +diffcore-merge-broken: For Putting "Complete Rewrites" Back Together +-------------------------------------------------------------------- This transformation is used to merge filepairs broken by diffcore-break, and not transformed into rename/copy by @@ -215,8 +226,8 @@ prefixed with '-', followed by the entire contents of new version prefixed with '+'. -diffcore-pickaxe ----------------- +diffcore-pickaxe: For Detecting Addition/Deletion of Specified String +--------------------------------------------------------------------- This transformation is used to find filepairs that represent changes that touch a specified string, and is controlled by the @@ -230,7 +241,7 @@ string appeared in this changeset". It also checks for the opposite case that loses the specified string. When `\--pickaxe-all` is not in effect, diffcore-pickaxe leaves -only such filepairs that touches the specified string in its +only such filepairs that touch the specified string in its output. When `\--pickaxe-all` is used, diffcore-pickaxe leaves all filepairs intact if there is such a filepair, or makes the output empty otherwise. The latter behaviour is designed to @@ -238,19 +249,19 @@ make reviewing of the changes in the context of the whole changeset easier. -diffcore-order --------------- +diffcore-order: For Sorting the Output Based on Filenames +--------------------------------------------------------- This is used to reorder the filepairs according to the user's (or project's) taste, and is controlled by the -O option to the git-diff-* commands. -This takes a text file each of whose line is a shell glob +This takes a text file each of whose lines is a shell glob pattern. Filepairs that match a glob pattern on an earlier line in the file are output before ones that match a later line, and filepairs that do not match any glob pattern are output last. -As an example, typical orderfile for the core GIT probably +As an example, a typical orderfile for the core git probably would look like this: ------------------------------------------------ diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt index 4a03b4cfc6..32300297d6 100644 --- a/Documentation/git-add.txt +++ b/Documentation/git-add.txt @@ -7,7 +7,7 @@ git-add - Add files to the cache. SYNOPSIS -------- -'git-add' <file>... +'git-add' [-n] [-v] <file>... DESCRIPTION ----------- @@ -19,6 +19,13 @@ OPTIONS <file>...:: Files to add to the cache. +-n:: + Don't actually add the file(s), just show if they exist |