From: Linus Torvalds Date: Wed, 22 Jun 2005 21:05:02 +0000 (-0700) Subject: Do a cross-project merge of Paul Mackerras' gitk visualizer X-Git-Tag: v0.99~205 X-Git-Url: https://git.lorimer.id.au/gitweb.git/diff_plain/5569bf9bbedd63a00780fc5c110e0cfab3aa97b9?hp=6c20ff3423e39f9982436953b6b9103f3f8447f8 Do a cross-project merge of Paul Mackerras' gitk visualizer gitk is really quite incredibly cool, and is great for visualizing what is going on in a git repository. It's especially useful when you are looking at what has changed since a particular version, since it gracefully handles partial trees (and this also avoids the expense of looking at _all_ changes in a big project). For example, to see what changed in a merge after a "git pull", do gitk ORIG_HEAD.. to see only the new things. Or you can simply do "gitk v2.6.12.." to see what has changed since the v2.6.12 tag etc. This merge itself is pretty interesting too, since it shows off a feature of git itself that is incredibly cool: you can merge a _separate_ git project into another git project. Not only does this keep all the history of the original project, it also makes it possible to continue to merge with the original project and the union of the two projects. I don't think anybody else can do that. --- diff --git a/COPYING b/COPYING new file mode 100644 index 0000000000..6ff87c4664 --- /dev/null +++ b/COPYING @@ -0,0 +1,361 @@ + + Note that the only valid version of the GPL as far as this project + is concerned is _this_ particular version of the license (ie v2, not + v2.2 or v3.x or whatever), unless explicitly otherwise stated. + + HOWEVER, in order to allow a migration to GPLv3 if that seems like + a good idea, I also ask that people involved with the project make + their preferences known. In particular, if you trust me to make that + decision, you might note so in your copyright message, ie something + like + + This file is licensed under the GPL v2, or a later version + at the discretion of Linus. + + might avoid issues. But we can also just decide to synchronize and + contact all copyright holders on record if/when the occasion arises. + + Linus Torvalds + +---------------------------------------- + + GNU GENERAL PUBLIC LICENSE + Version 2, June 1991 + + Copyright (C) 1989, 1991 Free Software Foundation, Inc. + 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + Preamble + + The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +License is intended to guarantee your freedom to share and change free +software--to make sure the software is free for all its users. This +General Public License applies to most of the Free Software +Foundation's software and to any other program whose authors commit to +using it. (Some other Free Software Foundation software is covered by +the GNU Library General Public License instead.) You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish), that you receive source code or can get it +if you want it, that you can change the software or use pieces of it +in new free programs; and that you know you can do these things. + + To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must give the recipients all the rights that +you have. You must make sure that they, too, receive or can get the +source code. And you must show them these terms so they know their +rights. + + We protect your rights with two steps: (1) copyright the software, and +(2) offer you this license which gives you legal permission to copy, +distribute and/or modify the software. + + Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, we +want its recipients to know that what they have is not the original, so +that any problems introduced by others will not reflect on the original +authors' reputations. + + Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that redistributors of a free +program will individually obtain patent licenses, in effect making the +program proprietary. To prevent this, we have made it clear that any +patent must be licensed for everyone's free use or not licensed at all. + + The precise terms and conditions for copying, distribution and +modification follow. + + GNU GENERAL PUBLIC LICENSE + TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + + 0. This License applies to any program or other work which contains +a notice placed by the copyright holder saying it may be distributed +under the terms of this General Public License. The "Program", below, +refers to any such program or work, and a "work based on the Program" +means either the Program or any derivative work under copyright law: +that is to say, a work containing the Program or a portion of it, +either verbatim or with modifications and/or translated into another +language. (Hereinafter, translation is included without limitation in +the term "modification".) Each licensee is addressed as "you". + +Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running the Program is not restricted, and the output from the Program +is covered only if its contents constitute a work based on the +Program (independent of having been made by running the Program). +Whether that is true depends on what the Program does. + + 1. You may copy and distribute verbatim copies of the Program's +source code as you receive it, in any medium, provided that you +conspicuously and appropriately publish on each copy an appropriate +copyright notice and disclaimer of warranty; keep intact all the +notices that refer to this License and to the absence of any warranty; +and give any other recipients of the Program a copy of this License +along with the Program. + +You may charge a fee for the physical act of transferring a copy, and +you may at your option offer warranty protection in exchange for a fee. + + 2. You may modify your copy or copies of the Program or any portion +of it, thus forming a work based on the Program, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: + + a) You must cause the modified files to carry prominent notices + stating that you changed the files and the date of any change. + + b) You must cause any work that you distribute or publish, that in + whole or in part contains or is derived from the Program or any + part thereof, to be licensed as a whole at no charge to all third + parties under the terms of this License. + + c) If the modified program normally reads commands interactively + when run, you must cause it, when started running for such + interactive use in the most ordinary way, to print or display an + announcement including an appropriate copyright notice and a + notice that there is no warranty (or else, saying that you provide + a warranty) and that users may redistribute the program under + these conditions, and telling the user how to view a copy of this + License. (Exception: if the Program itself is interactive but + does not normally print such an announcement, your work based on + the Program is not required to print an announcement.) + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Program, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Program, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote it. + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Program. + +In addition, mere aggregation of another work not based on the Program +with the Program (or with a work based on the Program) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + + 3. You may copy and distribute the Program (or a work based on it, +under Section 2) in object code or executable form under the terms of +Sections 1 and 2 above provided that you also do one of the following: + + a) Accompany it with the complete corresponding machine-readable + source code, which must be distributed under the terms of Sections + 1 and 2 above on a medium customarily used for software interchange; or, + + b) Accompany it with a written offer, valid for at least three + years, to give any third party, for a charge no more than your + cost of physically performing source distribution, a complete + machine-readable copy of the corresponding source code, to be + distributed under the terms of Sections 1 and 2 above on a medium + customarily used for software interchange; or, + + c) Accompany it with the information you received as to the offer + to distribute corresponding source code. (This alternative is + allowed only for noncommercial distribution and only if you + received the program in object code or executable form with such + an offer, in accord with Subsection b above.) + +The source code for a work means the preferred form of the work for +making modifications to it. For an executable work, complete source +code means all the source code for all modules it contains, plus any +associated interface definition files, plus the scripts used to +control compilation and installation of the executable. However, as a +special exception, the source code distributed need not include +anything that is normally distributed (in either source or binary +form) with the major components (compiler, kernel, and so on) of the +operating system on which the executable runs, unless that component +itself accompanies the executable. + +If distribution of executable or object code is made by offering +access to copy from a designated place, then offering equivalent +access to copy the source code from the same place counts as +distribution of the source code, even though third parties are not +compelled to copy the source along with the object code. + + 4. You may not copy, modify, sublicense, or distribute the Program +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense or distribute the Program is +void, and will automatically terminate your rights under this License. +However, parties who have received copies, or rights, from you under +this License will not have their licenses terminated so long as such +parties remain in full compliance. + + 5. You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Program or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Program (or any work based on the +Program), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Program or works based on it. + + 6. Each time you redistribute the Program (or any work based on the +Program), the recipient automatically receives a license from the +original licensor to copy, distribute or modify the Program subject to +these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties to +this License. + + 7. If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Program at all. For example, if a patent +license would not permit royalty-free redistribution of the Program by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Program. + +If any portion of this section is held invalid or unenforceable under +any particular circumstance, the balance of the section is intended to +apply and the section as a whole is intended to apply in other +circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system, which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + +This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + + 8. If the distribution and/or use of the Program is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Program under this License +may add an explicit geographical distribution limitation excluding +those countries, so that distribution is permitted only in or among +countries not thus excluded. In such case, this License incorporates +the limitation as if written in the body of this License. + + 9. The Free Software Foundation may publish revised and/or new versions +of the General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies a version number of this License which applies to it and "any +later version", you have the option of following the terms and conditions +either of that version or of any later version published by the Free +Software Foundation. If the Program does not specify a version number of +this License, you may choose any version ever published by the Free Software +Foundation. + + 10. If you wish to incorporate parts of the Program into other free +programs whose distribution conditions are different, write to the author +to ask for permission. For software which is copyrighted by the Free +Software Foundation, write to the Free Software Foundation; we sometimes +make exceptions for this. Our decision will be guided by the two goals +of preserving the free status of all derivatives of our free software and +of promoting the sharing and reuse of software generally. + + NO WARRANTY + + 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY +FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN +OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES +PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED +OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS +TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE +PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, +REPAIR OR CORRECTION. + + 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR +REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING +OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED +TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY +YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER +PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE +POSSIBILITY OF SUCH DAMAGES. + + END OF TERMS AND CONDITIONS + + How to Apply These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +convey the exclusion of warranty; and each file should have at least +the "copyright" line and a pointer to where the full notice is found. + + + Copyright (C) + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + + +Also add information on how to contact you by electronic and paper mail. + +If the program is interactive, make it output a short notice like this +when it starts in an interactive mode: + + Gnomovision version 69, Copyright (C) year name of author + Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type `show c' for details. + +The hypothetical commands `show w' and `show c' should show the appropriate +parts of the General Public License. Of course, the commands you use may +be called something other than `show w' and `show c'; they could even be +mouse-clicks or menu items--whatever suits your program. + +You should also get your employer (if you work as a programmer) or your +school, if any, to sign a "copyright disclaimer" for the program, if +necessary. Here is a sample; alter the names: + + Yoyodyne, Inc., hereby disclaims all copyright interest in the program + `Gnomovision' (which makes passes at compilers) written by James Hacker. + + , 1 April 1989 + Ty Coon, President of Vice + +This General Public License does not permit incorporating your program into +proprietary programs. If your program is a subroutine library, you may +consider it more useful to permit linking proprietary applications with the +library. If this is what you want to do, use the GNU Library General +Public License instead of this License. diff --git a/Documentation/Makefile b/Documentation/Makefile new file mode 100644 index 0000000000..e3844f213b --- /dev/null +++ b/Documentation/Makefile @@ -0,0 +1,41 @@ +MAN1_TXT=$(wildcard git-*.txt) +MAN7_TXT=git.txt + +DOC_HTML=$(patsubst %.txt,%.html,$(MAN1_TXT) $(MAN7_TXT)) + +DOC_MAN1=$(patsubst %.txt,%.1,$(MAN1_TXT)) +DOC_MAN7=$(patsubst %.txt,%.7,$(MAN7_TXT)) + +# +# Please note that there is a minor bug in asciidoc. +# The version after 6.0.3 _will_ include the patch found here: +# http://marc.theaimsgroup.com/?l=git&m=111558757202243&w=2 +# +# Until that version is released you may have to apply the patch +# yourself - yes, all 6 characters of it! +# + +all: html man + +html: $(DOC_HTML) + + +man: man1 man7 +man1: $(DOC_MAN1) +man7: $(DOC_MAN7) + +# 'include' dependencies +git-diff-%.txt: diff-format.txt + touch $@ + +clean: + rm -f *.xml *.html *.1 *.7 + +%.html : %.txt + asciidoc -b css-embedded -d manpage $< + +%.1 %.7 : %.xml + xmlto man $< + +%.xml : %.txt + asciidoc -b docbook -d manpage $< diff --git a/Documentation/cvs-migration.txt b/Documentation/cvs-migration.txt new file mode 100644 index 0000000000..4e2c452034 --- /dev/null +++ b/Documentation/cvs-migration.txt @@ -0,0 +1,212 @@ +Git for CVS users +================= + +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 +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, +however, may be a bit _too_ different (read: "good") for your taste, and +does a lot of things differently. + +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 +track that, since git never tracks things on the level of an individual +file, only on the whole project level. + +The good news is that most people don't do that, and in fact most sane +people think it's a bug in CVS that makes it tag (and check in changes) +one file at a time. So most projects you'll ever see will use CVS +_as_if_ it was sane. In which case you'll find it very easy indeed to +move over to Git. + +First off: this is not a git tutorial. See Documentation/tutorial.txt +for how git actually works. This is more of a random collection of +gotcha's 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 +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 +just keep in mind that with git, every checked out working tree will +have a full revision control history of its own. + + +Importing a CVS archive +----------------------- + +Ok, you have an old project, and you want to at least give git a chance +to see how it performs. The first thing you want to do (after you've +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 +will need the help of a program called "cvsps": + + http://www.cobite.com/cvsps/ + +which is not actually related to git at all, but which makes CVS usage +look almost sane (ie you almost certainly want to have it even if you +decide to stay with CVS). However, git will want at _least_ version 2.1 +of cvsps (available at the address above), and in fact will currently +refuse to work with anything else. + +Once you've gotten (and installed) cvsps, you may or may not want to get +any more familiar with it, but make sure it is in your path. After that, +the magic command line is + + git cvsimport + +which will do exactly what you'd think it does: it will create a git +archive of the named CVS module. The new archive will be created in a +subdirectory named . + +It can take some time to actually do the conversion for a large archive +since it involves checking out from CVS every revision of every file, +and the conversion script can be reasonably chatty, but on some not very +scientific tests it averaged about eight revisions per second, so a +medium-sized project should not take more than a couple of minutes. For +larger projects or remote repositories, the process may take longer. + + +Emulating CVS behaviour +----------------------- + + +FIXME! Talk about setting up several repositories, and pulling and +pushing between them. Talk about merging, and branches. Some of this +needs to be in the tutorial too. + + + +CVS annotate +------------ + +So, something has gone wrong, and you don't know whom to blame, and +you're an ex-CVS user and used to do "cvs annotate" to see who caused +the breakage. You're looking for the "git annotate", and it's just +claiming not to find such a script. You're annoyed. + +Yes, that's right. Core git doesn't do "annotate", although it's +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 +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"). + +The "git-whatchanged" script is a truly trivial script that can give you +a good overview of what has changed in a file or a directory (or an +arbitrary list of files or directories). The "pickaxe" support is an +additional layer that can be used to further specify exactly what you're +looking for, if you already know the specific area that changed. + +Let's step back a bit and think about the reason why you would +want to do "cvs annotate a-file.c" to begin with. + +You would use "cvs annotate" on a file when you have trouble +with a function (or even a single "if" statement in a function) +that happens to be defined in the file, which does not do what +you want it to do. And you would want to find out why it was +written that way, because you are about to modify it to suit +your needs, and at the same time you do not want to break its +current callers. For that, you are trying to find out why the +original author did things that way in the original context. + +Many times, it may be enough to see the commit log messages of +commits that touch the file in question, possibly along with the +patches themselves, like this: + + $ git-whatchanged -p a-file.c + +This will show log messages and patches for each commit that +touches a-file. + +This, however, may not be very useful when this file has many +modifications that are not related to the piece of code you are +interested in. You would see many log messages and patches that +do not have anything to do with the piece of code you are +interested in. As an example, assuming that you have this piece +code that you are interested in in the HEAD version: + + if (frotz) { + nitfol(); + } + +you would use git-rev-list and git-diff-tree like this: + + $ git-rev-list HEAD | + git-diff-tree --stdin -v -p -S'if (frotz) { + nitfol(); + }' + +We have already talked about the "--stdin" form of git-diff-tree +command that reads the list of commits and compares each commit +with its parents. The git-whatchanged command internally runs +the equivalent of the above command, and can be used like this: + + $ git-whatchanged -p -S'if (frotz) { + nitfol(); + }' + +When the -S option is used, git-diff-tree command outputs +differences between two commits only if one tree has the +specified string in a file and the corresponding file in the +other tree does not. The above example looks for a commit that +has the "if" statement in it in a file, but its parent commit +does not have it in the same shape in the corresponding file (or +the other way around, where the parent has it and the commit +does not), and the differences between them are shown, along +with the commit message (thanks to the -v flag). It does not +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 +a situation. For that, you can give the -C flag to +git-diff-tree, like this: + + $ git-whatchanged -p -C -S'if (frotz) { + nitfol(); + }' + +When the -C flag is used, file renames and copies are followed. +So if the "if" statement in question happens to be in "a-file.c" +in the current HEAD commit, even if the file was originally +called "o-file.c" and then renamed in an earlier commit, or if +the file was created by copying an existing "o-file.c" in an +earlier commit, you will not lose track. If the "if" statement +did not change across such rename or copy, then the commit that +does rename or copy would not show in the output, and if the +"if" statement was modified while the file was still called +"o-file.c", it would find the commit that changed the statement +when it was in "o-file.c". + +[ BTW, the current versions of "git-diff-tree -C" is not eager + enough to find copies, and it will miss the fact that a-file.c + was created by copying o-file.c unless o-file.c was somehow + changed in the same commit.] + +You can use the --pickaxe-all flag in addition to the -S flag. +This causes the differences from all the files contained in +those two commits, not just the differences between the files +that contain this changed "if" statement: + + $ git-whatchanged -p -C -S'if (frotz) { + nitfol(); + }' --pickaxe-all + +[ Side note. This option is called "--pickaxe-all" because -S + option is internally called "pickaxe", a tool for software + archaeologists.] diff --git a/Documentation/diff-format.txt b/Documentation/diff-format.txt new file mode 100644 index 0000000000..d6ce035419 --- /dev/null +++ b/Documentation/diff-format.txt @@ -0,0 +1,135 @@ +The output format from "git-diff-cache", "git-diff-tree" and +"git-diff-files" is very similar. + +These commands all compare two sets of things; what are +compared are different: + +git-diff-cache :: + compares the and the files on the filesystem. + +git-diff-cache --cached :: + compares the and the cache. + +git-diff-tree [-r] [...]:: + compares the trees named by the two arguments. + +git-diff-files [...]:: + compares the cache and the files on the filesystem. + + +An output line is formatted this way: + +in-place edit :100644 100644 bcd1234... 0123456... M file0 +copy-edit :100644 100644 abcd123... 1234567... C68 file1 file2 +rename-edit :100644 100644 abcd123... 1234567... R86 file1 file3 +create :000000 100644 0000000... 1234567... N file4 +delete :100644 000000 1234567... 0000000... D file5 +unmerged :000000 000000 0000000... 0000000... U file6 + +That is, from the left to the right: + + (1) a colon. + (2) mode for "src"; 000000 if creation or unmerged. + (3) a space. + (4) mode for "dst"; 000000 if deletion or unmerged. + (5) a space. + (6) sha1 for "src"; 0{40} if creation or unmerged. + (7) a space. + (8) sha1 for "dst"; 0{40} if creation, unmerged or "look at work tree". + (9) a space. + (10) status, followed by optional "score" number. + (11) a tab or a NUL when '-z' option is used. + (12) path for "src" + (13) a tab or a NUL when '-z' option is used; only exists for C or R. + (14) path for "dst"; only exists for C or R. + (15) an LF or a NUL when '-z' option is used, to terminate the record. + + is shown as all 0's if new is a file on the filesystem +and it is out of sync with the cache. Example: + + :100644 100644 5be4a4...... 000000...... M file.c + +Generating patches with -p +-------------------------- + +When "git-diff-cache", "git-diff-tree", or "git-diff-files" are run +with a '-p' option, they do not produce the output described above; +instead they produce a patch file. + +The patch generation can be customized at two levels. This +customization also applies to "git-diff-helper". + +1. When the environment variable 'GIT_EXTERNAL_DIFF' is not set, + these commands internally invoke "diff" like this: + + diff -L a/ -L a/ -pu ++ +For added files, `/dev/null` is used for . For removed +files, `/dev/null` is used for ++ +The "diff" formatting options can be customized via the +environment variable 'GIT_DIFF_OPTS'. For example, if you +prefer context diff: + + GIT_DIFF_OPTS=-c git-diff-cache -p $(cat .git/HEAD) + + +2. When the environment variable 'GIT_EXTERNAL_DIFF' is set, the + program named by it is called, instead of the diff invocation + described above. ++ +For a path that is added, removed, or modified, +'GIT_EXTERNAL_DIFF' is called with 7 parameters: + + path old-file old-hex old-mode new-file new-hex new-mode ++ +where: + + -file:: are files GIT_EXTERNAL_DIFF can use to read the + contents of , + -hex:: are the 40-hexdigit SHA1 hashes, + -mode:: are the octal representation of the file modes. + ++ +The file parameters can point at the user's working file +(e.g. `new-file` in "git-diff-files"), `/dev/null` (e.g. `old-file` +when a new file is added), or a temporary file (e.g. `old-file` in the +cache). 'GIT_EXTERNAL_DIFF' should not worry about unlinking the +temporary file --- it is removed when 'GIT_EXTERNAL_DIFF' exits. + +For a path that is unmerged, 'GIT_EXTERNAL_DIFF' is called with 1 +parameter, . + + +Git specific extention to diff format +------------------------------------- + +What -p option produces is slightly different from the +traditional diff format. + + (1) It is preceeded with a "git diff" header, that looks like + this: + + diff --git a/file1 b/file2 + + The a/ and b/ filenames are the same unless rename/copy is + involved. Especially, even for a creation or a deletion, + /dev/null is _not_ used in place of a/ or b/ filename. + + When rename/copy is involved, file1 and file2 shows the + name of the source file of the rename/copy and the name of + the file that rename/copy produces, respectively. + + (2) It is followed by extended header lines that are one or + more of: + + old mode + new mode + deleted file mode + new file mode + copy from + copy to + rename from + rename to + similarity index + dissimilarity index diff --git a/Documentation/diffcore.txt b/Documentation/diffcore.txt new file mode 100644 index 0000000000..6c474d1c0c --- /dev/null +++ b/Documentation/diffcore.txt @@ -0,0 +1,248 @@ +Tweaking diff output +==================== +June 2005 + + +Introduction +------------ + +The diff commands git-diff-cache, 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 chain of operation +---------------------- + +The git-diff-* family works by first comparing two sets of +files: + + - git-diff-cache compares contents of a "tree" object and the + working directory (when --cached flag is not used) or a + "tree" object and the index file (when --cached flag is + used); + + - git-diff-files compares contents of the index file and the + working directory; + + - git-diff-tree compares contents of two "tree" objects. + +In all of these cases, the commands themselves compare +corresponding paths in the two sets of files. The result of +comparison is passed from these commands to what is internally +called "diffcore", in a format similar to what is output when +the -p option is not used. E.g. + + in-place edit :100644 100644 bcd1234... 0123456... M file0 + create :000000 100644 0000000... 1234567... N file4 + delete :100644 000000 1234567... 0000000... D file5 + unmerged :000000 000000 0000000... 0000000... U file6 + +The diffcore mechanism is fed a list of such comparison results +(each of which is called "filepair", although at this point each +of them talks about a single file), and transforms such a list +into another list. There are currently 6 such transformations: + + - diffcore-pathspec + - diffcore-break + - diffcore-rename + - diffcore-merge-broken + - diffcore-pickaxe + - diffcore-order + +These are applied in sequence. The set of filepairs git-diff-* +commands find are used as the input to diffcore-pathspec, and +the output from diffcore-pathspec is used as the input to the +next transformation. The final result is then passed to the +output routine and generates either diff-raw format (see Output +format sections of the manual for git-diff-* commands) or +diff-patch format. + + +diffcore-pathspec +----------------- + +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. + +Implementation note. For performance reasons, git-diff-tree +uses the pathname parameters on the command line to cull set of +filepairs it feeds the diffcore mechanism itself, and does not +use diffcore-pathspec, but the end result is the same. + + +diffcore-break +-------------- + +The second transformation in the chain is diffcore-break, and is +controlled by the -B option to the git-diff-* commands. This is +used to detect a filepair that represents "complete rewrite" and +break such filepair into two filepairs that represent delete and +create. E.g. If the input contained this filepair: + + :100644 100644 bcd1234... 0123456... M file0 + +and if it detects that the file "file0" is completely rewritten, +it changes it to: + + :100644 000000 bcd1234... 0000000... D file0 + :000000 100644 0000000... 0123456... N file0 + +For the purpose of breaking a filepair, diffcore-break examines +the extent of changes between the contents of the files before +and after modification (i.e. the contents that have "bcd1234..." +and "0123456..." as their SHA1 content ID, in the above +example). The amount of deletion of original contents and +insertion of new material are added together, and if it exceeds +the "break score", the filepair is broken into two. The break +score defaults to 50% of the size of the smaller of the original +and the result (i.e. if the edit shrinks the file, the size of +the result is used; if the edit lengthens the file, the size of +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 +--------------- + +This transformation is used to detect renames and copies, and is +controlled by the -M option (to detect renames) and the -C option +(to detect copies as well) to the git-diff-* commands. If the +input contained these filepairs: + + :100644 000000 0123456... 0000000... D fileX + :000000 100644 0000000... 0123456... N file0 + +and the contents of the deleted file fileX is similar enough to +the contents of the created file file0, then rename detection +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 +created file file0: + + :100644 100644 0123456... 1234567... M fileY + :000000 100644 0000000... 0123456... N file0 + +the original contents of fileY and the resulting contents of +file0 are compared, and if they are similar enough, they are +changed to: + + :100644 100644 0123456... 1234567... M fileY + :100644 100644 0123456... 0123456... 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 +8/10 = 80%). + +Note. When the "-C" option is used with --find-copies-harder +option, git-diff-* commands feed unmodified filepairs to +diffcore mechanism as well as modified ones. This lets the copy +detector consider unmodified files as copy source candidates at +the expense of making it slower. Without --find-copies-harder, +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 +--------------------- + +This transformation is used to merge filepairs broken by +diffcore-break, and were not transformed into rename/copy by +diffcore-rename, back into a single modification. This always +runs when diffcore-break is used. + +For the purpose of merging broken filepairs back, it uses a +different "extent of changes" computation from the ones used by +diffcore-break and diffcore-rename. It counts only the deletion +from the original, and does not count insertion. If you removed +only 10 lines from a 100-line document, even if you added 910 +new lines to make a new 1000-line document, you did not do a +complete rewrite. diffcore-break breaks such a case in order to +help diffcore-rename to consider such filepairs as candidate of +rename/copy detection, but if filepairs broken that way were not +matched with other filepairs to create rename/copy, then this +transformation merges them back into the original +"modification". + +The "extent of changes" parameter can be tweaked from the +default 80% (that is, unless more than 80% of the original +material is deleted, the broken pairs are merged back into a +single modification) by giving a second number to -B option, +like these: + + -B50/60 (give 50% "break score" to diffcore-break, use + 60% for diffcore-merge-broken). + -B/60 (the same as above, since diffcore-break defautls to + 50%). + +Note that earlier implementation left a broken pair as a separate +creation and deletion patches. This was unnecessary hack and +the latest implementation always merges all the broken pairs +back into modifications, but the resulting patch output is +formatted differently to still let the reviewing easier for such +a complete rewrite by showing the entire contents of old version +prefixed with '-', followed by the entire contents of new +version prefixed with '+'. + + +diffcore-pickaxe +---------------- + +This transformation is used to find filepairs that represent +changes that touch a specified string, and is controlled by the +-S option and the --pickaxe-all option to the git-diff-* +commands. + +When diffcore-pickaxe is in use, it checks if there are +filepairs whose "original" side has the specified string and +whose "result" side does not. Such a filepair represents "the +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 +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 +make reviewing of the changes in the context of the whole +changeset easier. + + +diffcore-order +-------------- + +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 +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 +should look like this: + + README + Makefile + Documentation + *.h + *.c + t + diff --git a/Documentation/git-apply-patch-script.txt b/Documentation/git-apply-patch-script.txt new file mode 100644 index 0000000000..a6f860d424 --- /dev/null +++ b/Documentation/git-apply-patch-script.txt @@ -0,0 +1,32 @@ +git-apply-patch-script(1) +========================= +v0.1, May 2005 + +NAME +---- +git-apply-patch-script - Sample script to apply the diffs from git-diff-* + + +SYNOPSIS +-------- +'git-apply-patch-script' + +DESCRIPTION +----------- +This is a sample script to be used via the 'GIT_EXTERNAL_DIFF' +environment variable to apply the differences that the "git-diff-*" +family of commands report to the current work tree. + + +Author +------ +Written by Linus Torvalds + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list . + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt new file mode 100644 index 0000000000..81eb155af6 --- /dev/null +++ b/Documentation/git-apply.txt @@ -0,0 +1,72 @@ +git-apply(1) +============ +v0.1, June 2005 + +NAME +---- +git-apply - Apply patch on a GIT index file and a work tree + + +SYNOPSIS +-------- +'git-apply' [--no-merge] [--stat] [--summary] [--check] +[--index] [--show-files] [-] [...] + +DESCRIPTION +----------- +Reads supplied diff output and applies it on a GIT index file +and a work tree. + +OPTIONS +------- +...:: + The files to read patch from. + +-:: + Instead of reading from a file, read from standard input. + +--no-merge:: + The default mode of operation is the merge behaviour + which is not quite implemented yet. This flag + explicitly tells the program not to use the merge + behaviour. + +--stat:: + Instead of applying the patch, output diffstat for the + input. + +--summary:: + Instead of applying the patch, output a condensed + summary of information obtained from git diff extended + headers, such as creations, renames and mode changes. + +--check:: + Instead of applying the patch, see if the patch is + applicable to the current work tree and/or the index + file and detects errors. + +--index:: + When --check is in effect, or when applying the patch + (which is the default when none of the options that + disables it is in effect), make sure the patch is + applicable to what the current index file records. If + the file to be patched in the work tree is not + up-to-date, it is flagged as an error. This flag also + causes the index file to be updated. + +--show-files:: + Show summary of files that are affected by the patch. + + +Author +------ +Written by Linus Torvalds + +Documentation +-------------- +Documentation by Junio C Hamano + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt new file mode 100644 index 0000000000..48fb37769c --- /dev/null +++ b/Documentation/git-cat-file.txt @@ -0,0 +1,55 @@ +git-cat-file(1) +=============== +v0.1, May 2005 + +NAME +---- +git-cat-file - Provide content or type information for repository objects + + +SYNOPSIS +-------- +'git-cat-file' (-t | ) + +DESCRIPTION +----------- +Provides content or type of objects in the repository. The type +is required if '-t' is not being used to find the object type. + +OPTIONS +------- +:: + The sha1 identifier of the object. + +-t:: + Instead of the content, show the object type identified by + . + +:: + Typically this matches the real type of but asking + for a type that can trivially dereferenced from the given + is also permitted. An example is to ask for a + "tree" with being a commit object that contains it, + or to ask for a "blob" with being a tag object that + points at it. + +OUTPUT +------ +If '-t' is specified, one of the . + +Otherwise the raw (though uncompressed) contents of the will +be returned. + + +Author +------ +Written by Linus Torvalds + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list . + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-check-files.txt b/Documentation/git-check-files.txt new file mode 100644 index 0000000000..6146098022 --- /dev/null +++ b/Documentation/git-check-files.txt @@ -0,0 +1,50 @@ +git-check-files(1) +================== +v0.1, May 2005 + +NAME +---- +git-check-files - Verify a list of files are up-to-date + + + +SYNOPSIS +-------- +'git-check-files' ... + +DESCRIPTION +----------- +Check that a list of files are up-to-date between the filesystem and +the cache. Used to verify a patch target before doing a patch. + +Files that do not exist on the filesystem are considered up-to-date +(whether or not they are in the cache). + +Emits an error message on failure: + +preparing to update existing file not in cache:: + exists but is not in the cache + +preparing to update file not uptodate in cache:: + on disk is not up-to-date with the cache + +Exits with a status code indicating success if all files are +up-to-date. + +See Also +-------- +link:git-update-cache.html[git-update-cache] + + +Author +------ +Written by Linus Torvalds + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list . + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-checkout-cache.txt b/Documentation/git-checkout-cache.txt new file mode 100644 index 0000000000..321a00c251 --- /dev/null +++ b/Documentation/git-checkout-cache.txt @@ -0,0 +1,106 @@ +git-checkout-cache(1) +===================== +v0.1, May 2005 + +NAME +---- +git-checkout-cache - Copy files from the cache to the working directory + + +SYNOPSIS +-------- +'git-checkout-cache' [-u] [-q] [-a] [-f] [-n] [--prefix=] + [--] ... + +DESCRIPTION +----------- +Will copy all files listed from the cache to the working directory +(not overwriting existing files). + +OPTIONS +------- +-u:: + update stat information for the checked out entries in + the cache file. + +-q:: + be quiet if files exist or are not in the cache + +-f:: + forces overwrite of existing files + +-a:: + checks out all files in the cache (will then continue to + process listed files). + +-n:: + Don't checkout new files, only refresh files already checked + out. + +--prefix=:: + When creating files, prepend (usually a directory + including a trailing /) + +--:: + Do not interpret any more arguments as options. + +Note that the order of the flags matters: + + git-checkout-cache -a -f file.c + +will first check out all files listed in the cache (but not overwrite +any old ones), and then force-checkout `file.c` a second time (ie that +one *will* overwrite any old contents with the same filename). + +Also, just doing "git-checkout-cache" does nothing. You probably meant +"git-checkout-cache -a". And if you want to force it, you want +"git-checkout-cache -f -a". + +Intuitiveness is not the goal here. Repeatability is. The reason for +the "no arguments means no work" thing is that from scripts you are +supposed to be able to do things like: + + find . -name '*.h' -print0 | xargs -0 git-checkout-cache -f -- + +which will force all existing `*.h` files to be replaced with their +cached copies. If an empty command line implied "all", then this would +force-refresh everything in the cache, which was not the point. + +To update and refresh only the files already checked out: + + git-checkout-cache -n -f -a && git-update-cache --ignore-missing --refresh + +Oh, and the "--" is just a good idea when you know the rest will be +filenames. Just so that you wouldn't have a filename of "-a" causing +problems (not possible in the above example, but get used to it in +scripting!). + +The prefix ability basically makes it trivial to use +git-checkout-cache as an "export as tree" function. Just read the +desired tree into the index, and do a + + git-checkout-cache --prefix=git-export-dir/ -a + +and git-checkout-cache will "export" the cache into the specified +directory. + +NOTE The final "/" is important. The exported name is literally just +prefixed with the specified string, so you can also do something like + + git-checkout-cache --prefix=.merged- Makefile + +to check out the currently cached copy of `Makefile` into the file +`.merged-Makefile` + +Author +------ +Written by Linus Torvalds + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list . + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt new file mode 100644 index 0000000000..c0dc1f46c5 --- /dev/null +++ b/Documentation/git-commit-tree.txt @@ -0,0 +1,88 @@ +git-commit-tree(1) +================== +v0.1, May 2005 + +NAME +---- +git-commit-tree - Creates a new commit object + + +SYNOPSIS +-------- +'git-commit-tree' [-p ]\ < changelog + +DESCRIPTION +----------- +Creates a new commit object based on the provided tree object and +emits the new commit object id on stdout. If no parent is given then +it is considered to be an initial tree. + +A commit object usually has 1 parent (a commit after a change) or up +to 16 parents. More than one parent represents a merge of branches +that led to them. + +While a tree represents a particular directory state of a working +directory, a commit represents that state in "time", and explains how +to get there. + +Normally a commit would identify a new "HEAD" state, and while git +doesn't care where you save the note about that state, in practice we +tend to just write the result to the file `.git/HEAD`, so that we can +always see what the last committed state was. + +OPTIONS +------- +:: + An existing tree object + +-p :: + Each '-p' indicates a the id of a parent commit object. + + +Commit Information +------------------ + +A commit encapsulates: + +- all parent object ids +- author name, email and date +- committer name and email and the commit time. + +If not provided, "git-commit-tree" uses your name, hostname and domain to +provide author and committer info. This can be overridden using the +following environment variables. + + GIT_AUTHOR_NAME + GIT_AUTHOR_EMAIL + GIT_AUTHOR_DATE + GIT_COMMITTER_NAME + GIT_COMMITTER_EMAIL + +(nb <,> and '\n's are stripped) + +A commit comment is read from stdin (max 999 chars). If a changelog +entry is not provided via '<' redirection, "git-commit-tree" will just wait +for one to be entered and terminated with ^D + +Diagnostics +----------- +You don't exist. Go away!:: + The passwd(5) gecos field couldn't be read + +See Also +-------- +link:git-write-tree.html[git-write-tree] + + +Author +------ +Written by Linus Torvalds + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list . + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-convert-cache.txt b/Documentation/git-convert-cache.txt new file mode 100644 index 0000000000..66d7fe7855 --- /dev/null +++ b/Documentation/git-convert-cache.txt @@ -0,0 +1,30 @@ +git-convert-cache(1) +==================== +v0.1, May 2005 + +NAME +---- +git-convert-cache - Converts old-style GIT repository + + +SYNOPSIS +-------- +'git-convert-cache' + +DESCRIPTION +----------- +Converts old-style GIT repository to the latest format + + +Author +------ +Written by Linus Torvalds + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list . + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-diff-cache.txt b/Documentation/git-diff-cache.txt new file mode 100644 index 0000000000..f6dd7037d5 --- /dev/null +++ b/Documentation/git-diff-cache.txt @@ -0,0 +1,176 @@ +git-diff-cache(1) +================= +v0.1, May 2005 + +NAME +---- +git-diff-cache - Compares content and mode of blobs between the cache and repository + + +SYNOPSIS +-------- +'git-diff-cache' [-p] [-r] [-z] [-m] [--cached] [-R] [-B] [-M] [-C] [--find-copies-harder] [-O] [-S] [--pickaxe-all] [...] + +DESCRIPTION +----------- +Compares the content and mode of the blobs found via a tree +object with the content of the current cache and, optionally +ignoring the stat state of the file on disk. When paths are +specified, compares only those named paths. Otherwise all +entries in the cache are compared. + +OPTIONS +------- +:: + The id of a tree object to diff against. + +-p:: + Generate patch (see section on generating patches) + +-r:: + This flag does not mean anything. It is there only to match + "git-diff-tree". Unlike "git-diff-tree", "git-diff-cache" + always looks at all the subdirectories. + +-z:: + \0 line termination on output + +-B:: + Break complete rewrite changes into pairs of delete and create. + +-M:: + Detect renames. + +-C:: + Detect copies as well as renames. + +--find-copies-harder:: + By default, -C option finds copies only if the original + file of the copy was modified in the same changeset for + performance reasons. This flag makes the command + inspect unmodified files as candidates for the source of + copy. This is a very expensive operation for large + projects, so use it with caution. + +-S:: + Look for differences that contains the change in . + +--pickaxe-all:: + When -S finds a change, show all the changes in that + changeset, not just the files that contains the change + in . + +-O:: + Output the patch in the order specified in the + , which has one shell glob pattern per line. + +-R:: + Swap two inputs; that is, show differences from cache or + on-disk file to tree contents. + +--cached:: + do not consider the on-disk file at all + +-m:: + By default, files recorded in the index but not checked + out are reported as deleted. This flag makes + "git-diff-cache" say that all non-checked-out files are up + to date. + +Output format +------------- +include::diff-format.txt[] + +Operating Modes +--------------- +You can choose whether you want to trust the index file entirely +(using the '--cached' flag) or ask the diff logic to show any files +that don't match the stat state as being "tentatively changed". Both +of these operations are very useful indeed. + +Cached Mode +----------- +If '--cached' is specified, it allows you to ask: + + show me the differences between HEAD and the current index + contents (the ones I'd write with a "git-write-tree") + +For example, let's say that you have worked on your index file, and are +ready to commit. You want to see eactly *what* you are going to commit is +without having to write a new tree object and compare it that way, and to +do that, you just do + + git-diff-cache --cached $(cat .git/HEAD) + +Example: let's say I had renamed `commit.c` to `git-commit.c`, and I had +done an "git-update-cache" to make that effective in the index file. +"git-diff-files" wouldn't show anything at all, since the index file +matches my working directory. But doing a "git-diff-cache" does: + + torvalds@ppc970:~/git> git-diff-cache --cached $(cat .git/HEAD) + -100644 blob 4161aecc6700a2eb579e842af0b7f22b98443f74 commit.c + +100644 blob 4161aecc6700a2eb579e842af0b7f22b98443f74 git-commit.c + +You can trivially see that the above is a rename. + +In fact, "git-diff-cache --cached" *should* always be entirely equivalent to +actually doing a "git-write-tree" and comparing that. Except this one is much +nicer for the case where you just want to check where you are. + +So doing a "git-diff-cache --cached" is basically very useful when you are +asking yourself "what have I already marked for being committed, and +what's the difference to a previous tree". + +Non-cached Mode +--------------- +The "non-cached" mode takes a different approach, and is potentially +the more useful of the two in that what it does can't be emulated with +a "git-write-tree" + "git-diff-tree". Thus that's the default mode. +The non-cached version asks the question: + + show me the differences between HEAD and the currently checked out + tree - index contents _and_ files that aren't up-to-date + +which is obviously a very useful question too, since that tells you what +you *could* commit. Again, the output matches the "git-diff-tree -r" +output to a tee, but with a twist. + +The twist is that if some file doesn't match the cache, we don't have +a backing store thing for it, and we use the magic "all-zero" sha1 to +show that. So let's say that you have edited `kernel/sched.c`, but +have not actually done a "git-update-cache" on it yet - there is no +"object" associated with the new state, and you get: + + torvalds@ppc970:~/v2.6/linux> git-diff-cache $(cat .git/HEAD ) + *100644->100664 blob 7476bb......->000000...... kernel/sched.c + +ie it shows that the tree has changed, and that `kernel/sched.c` has is +not up-to-date and may contain new stuff. The all-zero sha1 means that to +get the real diff, you need to look at the object in the working directory +directly rather than do an object-to-object diff. + +NOTE! As with other commands of this type, "git-diff-cache" does not +actually look at the contents of the file at all. So maybe +`kernel/sched.c` hasn't actually changed, and it's just that you +touched it. In either case, it's a note that you need to +"git-upate-cache" it to make the cache be in sync. + +NOTE 2! You can have a mixture of files show up as "has been updated" +and "is still dirty in the working directory" together. You can always +tell which file is in which state, since the "has been updated" ones +show a valid sha1, and the "not in sync with the index" ones will +always have the special all-zero sha1. + + +Author +------ +Written by Linus Torvalds + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list . + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-diff-files.txt b/Documentation/git-diff-files.txt new file mode 100644 index 0000000000..32e9a1e760 --- /dev/null +++ b/Documentation/git-diff-files.txt @@ -0,0 +1,84 @@ +git-diff-files(1) +================= +v0.1, May 2005 + +NAME +---- +git-diff-files - Compares files in the working tree and the cache + + +SYNOPSIS +-------- +'git-diff-files' [-p] [-q] [-r] [-z] [-R] [-B] [-M] [-C] [--find-copies-harder] [-O] [-S] [--pickaxe-all] [...] + +DESCRIPTION +----------- +Compares the files in the working tree and the cache. When paths +are specified, compares only those named paths. Otherwise all +entries in the cache are compared. The output format is the +same as "git-diff-cache" and "git-diff-tree". + +OPTIONS +------- +-p:: + generate patch (see section on generating patches). + +-q:: + Remain silent even on nonexisting files + +-R:: + Swap two inputs; that is, show differences from on-disk files + to cache contents. + +-B:: + Break complete rewrite changes into pairs of delete and create. + +-M:: + Detect renames. + +-C:: + Detect copies as well as renames. + +--find-copies-harder:: + By default, -C option finds copies only if the original + file of the copy was modified in the same changeset for + performance reasons. This flag makes the command + inspect unmodified files as candidates for the source of + copy. This is a very expensive operation for large + projects, so use it with caution. + +-S:: + Look for differences that contains the change in . + +--pickaxe-all:: + When -S finds a change, show all the changes in that + changeset, not just the files that contains the change + in . + +-O:: + Output the patch in the order specified in the + , which has one shell glob pattern per line. + +-r:: + This flag does not mean anything. It is there only to match + git-diff-tree. Unlike git-diff-tree, git-diff-files always looks + at all the subdirectories. + + +Output format +------------- +include::diff-format.txt[] + + +Author +------ +Written by Linus Torvalds + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list . + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-diff-helper.txt b/Documentation/git-diff-helper.txt new file mode 100644 index 0000000000..d826deb42e --- /dev/null +++ b/Documentation/git-diff-helper.txt @@ -0,0 +1,53 @@ +git-diff-helper(1) +================== +v0.1, May 2005 + +NAME +---- +git-diff-helper - Generates patch format output for git-diff-* + + +SYNOPSIS +-------- +'git-diff-helper' [-z] [-S] [-O] + +DESCRIPTION +----------- +Reads output from "git-diff-cache", "git-diff-tree" and "git-diff-files" and +generates patch format output. + +OPTIONS +------- +-z:: + \0 line termination on input + +-S:: + Look for differences that contains the change in . + +--pickaxe-all:: + When -S finds a change, show all the changes in that + changeset, not just the files that contains the change + in . + +-O:: + Output the patch in the order specified in the + , which has one shell glob pattern per line. + +See Also +-------- +The section on generating patches in link:git-diff-cache.html[git-diff-cache] + + +Author +------ +Written by Junio C Hamano + + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list . + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-diff-stages.txt b/Documentation/git-diff-stages.txt new file mode 100644 index 0000000000..e7e59c8491 --- /dev/null +++ b/Documentation/git-diff-stages.txt @@ -0,0 +1,83 @@ +git-diff-stages(1) +================== +v0.1, June 2005 + +NAME +---- +git-diff-stages - Compares content and mode of blobs between stages in an unmerged index file. + + +SYNOPSIS +-------- +'git-diff-stages' [-p] [-r] [-z] [-R] [-B] [-M] [-C] [--find-copies-harder] [-O] [-S] [--pickaxe-all] [...] + +DESCRIPTION +----------- +Compares the content and mode of the blobs in two stages in an +unmerged index file. + +OPTIONS +------- +,:: + The stage number to be compared. + +-p:: + Generate patch (see section on generating patches) + +-r:: + This flag does not mean anything. It is there only to match + "git-diff-tree". Unlike "git-diff-tree", "git-diff-stages" + always looks at all the subdirectories. + +-z:: + \0 line termination on output + +-B:: + Break complete rewrite changes into pairs of delete and create. + +-M:: + Detect renames. + +-C:: + Detect copies as well as renames. + +--find-copies-harder:: + By default, -C option finds copies only if the original + file of the copy was modified in the same changeset for + performance reasons. This flag makes the command + inspect unmodified files as candidates for the source of + copy. This is a very expensive operation for large + projects, so use it with caution. + +-S:: + Look for differences that contains the change in . + +--pickaxe-all:: + When -S finds a change, show all the changes in that + changeset, not just the files that contains the change + in . + +-O:: + Output the patch in the order specified in the + , which has one shell glob pattern per line. + +-R:: + Swap two inputs; that is, show differences from to + . + +Output format +------------- +include::diff-format.txt[] + + +Author +------ +Written by Junio C Hamano + +Documentation +-------------- +Documentation by Junio C Hamano. + +GIT +--- +Part of the link:git.html[git] suite diff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt new file mode 100644 index 0000000000..ab0ba4fb17 --- /dev/null +++ b/Documentation/git-diff-tree.txt @@ -0,0 +1,170 @@ +git-diff-tree(1) +================ +v0.1, May 2005 + +NAME +---- +git-diff-tree - Compares the content and mode of blobs found via two tree objects + + +SYNOPSIS +-------- +'git-diff-tree' [-p] [-r] [-z] [--stdin] [-m] [-s] [-v] [-t] [-R] [-B] [-M] [-C] [--find-copies-harder] [-O] [-S] [--pickaxe-all] [...] + +DESCRIPTION +----------- +Compares the content and mode of the blobs found via two tree objects. + +Note that "git-diff-tree" can use the tree encapsulated in a commit object. + +OPTIONS +------- +:: + The id of a tree object. + +...:: + If provided, the results are limited to a subset of files + matching one of these prefix strings. + ie file matches `/^||.../` + Note that this parameter does not provide any wildcard or regexp + features. + +-p:: + generate patch (see section on generating patches). For + git-diff-tree, this flag implies '-r' as well. + +-B:: + Break complete rewrite changes into pairs of delete and create. + +-M:: + Detect renames. + +-C:: + Detect copies as well as renames. + +--find-copies-harder:: + By default, -C option finds copies only if the original + file of the copy was modified in the same changeset for + performance reasons. This flag makes the command + inspect unmodified files as candidates for the source of + copy. This is a very expensive operation for large + projects, so use it with caution. + +-R:: + Swap two input trees. + +-S:: + Look for differences that contains the change in . + +--pickaxe-all:: + When -S finds a change, show all the changes in that + changeset, not just the files that contains the change + in . + +-O:: + Output the patch in the order specified in the + , which has one shell glob pattern per line. + +-r:: + recurse + +-t:: + show tree entry itself as well as subtrees. Implies -r. + +-z:: + \0 line termination on output + +--root:: + When '--root' is specified the initial commit will be showed as a big + creation event. This is equivalent to a diff against the NULL tree. + +--stdin:: + When '--stdin' is specified, the command does not take + arguments from the command line. Instead, it + reads either one or a pair of + separated with a single space from its standard input. ++ +When a single commit is given on one line of such input, it compares +the commit with its parents. The following flags further affects its +behaviour. This does not apply to the case where two +separated with a single space are given. + +-m:: + By default, "git-diff-tree --stdin" does not show + differences for merge commits. With this flag, it shows + differences to that commit from all of its parents. + +-s:: + By default, "git-diff-tree --stdin" shows differences, + either in machine-readable form (without '-p') or in patch + form (with '-p'). This output can be supressed. It is + only useful with '-v' flag. + +-v:: + This flag causes "git-diff-tree --stdin" to also show + the commit message before the differences. + +--pretty[=(raw|medium|short)]:: + This is used to control "pretty printing" format of the + commit message. Without "=