From: Junio C Hamano Date: Thu, 18 Aug 2005 04:09:15 +0000 (-0700) Subject: Merge with gitk X-Git-Tag: v0.99.5~14^2~2 X-Git-Url: https://git.octo.it/?a=commitdiff_plain;h=379955c696a417f0fb6118f2fd91dbffd2816ad1;hp=f6075ebadb1fce2bd75f2dd68b8aeae40a69158a;p=git.git Merge with gitk --- diff --git a/COPYING b/COPYING new file mode 100644 index 00000000..6ff87c46 --- /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 00000000..33657849 --- /dev/null +++ b/Documentation/Makefile @@ -0,0 +1,56 @@ +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)) + +prefix=$(HOME) +bin=$(prefix)/bin +mandir=$(prefix)/man +man1=$(mandir)/man1 +man7=$(mandir)/man7 +# DESTDIR= + +INSTALL=install + +# +# 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) + +install: + $(INSTALL) -m755 -d $(DESTDIR)/$(man1) $(DESTDIR)/$(man7) + $(INSTALL) $(DOC_MAN1) $(DESTDIR)/$(man1) + $(INSTALL) $(DOC_MAN7) $(DESTDIR)/$(man7) + +# 'include' dependencies +git-diff-%.txt: diff-format.txt diff-options.txt + touch $@ + +clean: + rm -f *.xml *.html *.1 *.7 + +%.html : %.txt + asciidoc -b xhtml11 -d manpage $< + +%.1 %.7 : %.xml + xmlto man $< + +%.xml : %.txt + asciidoc -b docbook -d manpage $< + diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches new file mode 100644 index 00000000..6121e902 --- /dev/null +++ b/Documentation/SubmittingPatches @@ -0,0 +1,130 @@ +I started reading over the SubmittingPatches document for Linux +kernel, primarily because I wanted to have a document similar to +it for the core GIT to make sure people understand what they are +doing when they write "Signed-off-by" line. + +But the patch submission requirements are a lot more relaxed +here, because the core GIT is thousand times smaller ;-). So +here is only the relevant bits. + + +(1) Make separate commits for logically separate changes. + +Unless your patch is really trivial, you should not be sending +out a patch that was generated between your working tree and +your commit head. Instead, always make a commit with complete +commit message and generate a series of patches from your +repository. It is a good discipline. + +Describe the technical detail of the change(s). + +If your description starts to get long, that's a sign that you +probably need to split up your commit to finer grained pieces. + + +(2) Generate your patch using git/cogito out of your commits. + +git diff tools generate unidiff which is the preferred format. +You do not have to be afraid to use -M option to "git diff" or +"git format-patch", if your patch involves file renames. The +receiving end can handle them just fine. + +Please make sure your patch does not include any extra files +which do not belong in a patch submission. Make sure to review +your patch after generating it, to ensure accuracy. Before +sending out, please make sure it cleanly applies to the "master" +branch head. + + +(3) Sending your patches. + +People on the git mailing list needs to be able to read and +comment on the changes you are submitting. It is important for +a developer to be able to "quote" your changes, using standard +e-mail tools, so that they may comment on specific portions of +your code. For this reason, all patches should be submitting +e-mail "inline". WARNING: Be wary of your MUAs word-wrap +corrupting your patch. Do not cut-n-paste your patch. + +It is common convention to prefix your subject line with +[PATCH]. This lets people easily distinguish patches from other +e-mail discussions. + +"git format-patch" command follows the best current practice to +format the body of an e-mail message. At the beginning of the +patch should come your commit message, ending with the +Signed-off-by: lines, and a line that consists of three dashes, +followed by the diffstat information and the patch itself. If +you are forwarding a patch from somebody else, optionally, at +the beginning of the e-mail message just before the commit +message starts, you can put a "From: " line to name that person. + +You often want to add additional explanation about the patch, +other than the commit message itself. Place such "cover letter" +material between the three dash lines and the diffstat. + +Do not attach the patch as a MIME attachment, compressed or not. +Do not let your e-mail client send quoted-printable. Many +popular e-mail applications will not always transmit a MIME +attachment as plain text, making it impossible to comment on +your code. A MIME attachment also takes a bit more time to +process. This does not decrease the likelihood of your +MIME-attached change being accepted, but it makes it more likely +that it will be postponed. + +Exception: If your mailer is mangling patches then someone may ask +you to re-send them using MIME. + +Note that your maintainer does not subscribe to the git mailing +list (he reads it via mail-to-news gateway). If your patch is +for discussion first, send it "To:" the mailing list, and +optoinally "cc:" him. If it is trivially correct or after list +discussion reached consensus, send it "To:" the maintainer and +optionally "cc:" the list. + + +(6) Sign your work + +To improve tracking of who did what, we've borrowed the +"sign-off" procedure from the Linux kernel project on patches +that are being emailed around. Although core GIT is a lot +smaller project it is a good discipline to follow it. + +The sign-off is a simple line at the end of the explanation for +the patch, which certifies that you wrote it or otherwise have +the right to pass it on as a open-source patch. The rules are +pretty simple: if you can certify the below: + + Developer's Certificate of Origin 1.1 + + By making a contribution to this project, I certify that: + + (a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + + (b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + + (c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + + (d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. + +then you just add a line saying + + Signed-off-by: Random J Developer + +Some people also put extra tags at the end. They'll just be ignored for +now, but you can do this to mark internal company procedures or just +point out some special detail about the sign-off. diff --git a/Documentation/cvs-migration.txt b/Documentation/cvs-migration.txt new file mode 100644 index 00000000..8db1409e --- /dev/null +++ b/Documentation/cvs-migration.txt @@ -0,0 +1,246 @@ +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 -v -d -C + +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 the +subdirectory named ; it'll be created if it doesn't exist. +Default is the local directory. + +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 is reasonably chatty unless you omit the '-v' +option, but on some not very scientific tests it averaged about twenty +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. + +After the (initial) import is done, the CVS archive's current head +revision will be checked out -- thus, you can start adding your own +changes right away. + +The import is incremental, i.e. if you call it again next month it'll +fetch any CVS updates that have been happening in the meantime. The +cut-off is date-based, so don't change the branches that were imported +from CVS. + +You can merge those updates (or, in fact, a different CVS branch) into +your main branch: + + git resolve HEAD origin "merge with current CVS HEAD" + +The HEAD revision from CVS is named "origin", not "HEAD", because git +already uses "HEAD". (If you don't like 'origin', use cvsimport's +'-o' option to change it.) + + +Emulating CVS behaviour +----------------------- + + +So, by now you are convinced you absolutely want to work with git, but +at the same time you absolutely have to have a central repository. +Step back and think again. Okay, you still need a single central +repository? There are several ways to go about that: + +1. Designate a person responsible to pull all branches. Make the +repository of this person public, and make every team member +pull regularly from it. + +2. Set up a public repository with read/write access for every team +member. Use "git pull/push" as you used "cvs update/commit". Be +sure that your repository is up to date before pushing, just +like you used to do with "cvs commit"; your push will fail if +what you are pushing is not up to date. + +3. Make the repository of every team member public. It is the +responsibility of each single member to pull from every other +team member. + + +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 +of 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 a 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 00000000..9298d79e --- /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 b/ -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 extension 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/diff-options.txt b/Documentation/diff-options.txt new file mode 100644 index 00000000..b28496e5 --- /dev/null +++ b/Documentation/diff-options.txt @@ -0,0 +1,53 @@ +-p:: + Generate patch (see section on generating patches) + +-u:: + Synonym for "-p". + +-r:: + Look recursively in subdirectories; this flag does not + mean anything to commands other than "git-diff-tree"; + other diff commands always look at all the subdirectories. + +-z:: + \0 line termination on output + +--name-only:: + Show only names of changed files. + +--name-only-z:: + Same as --name-only, but terminate lines with NUL. + +-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. + diff --git a/Documentation/diffcore.txt b/Documentation/diffcore.txt new file mode 100644 index 00000000..6c474d1c --- /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 00000000..808d3cdc --- /dev/null +++ b/Documentation/git-apply-patch-script.txt @@ -0,0 +1,32 @@ +git-apply-patch-script(1) +========================= +v0.99.4, 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 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-apply.txt b/Documentation/git-apply.txt new file mode 100644 index 00000000..391d6f5c --- /dev/null +++ b/Documentation/git-apply.txt @@ -0,0 +1,76 @@ +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] [--apply] [...] + +DESCRIPTION +----------- +Reads supplied diff output and applies it on a GIT index file +and a work tree. + +OPTIONS +------- +...:: + The files to read patch from. '-' can be used to read + from the standard input. + +--no-merge:: + The default mode of operation is the merge behaviour + which is not 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. Turns off "apply". + +--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. + Turns off "apply". + +--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. Turns off "apply". + +--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. + +--apply:: + If you use any of the options marked ``Turns off + "apply"'' above, git-apply reads and outputs the + information you asked without actually applying the + patch. Give this flag after those flags to also apply + 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 00000000..2131a299 --- /dev/null +++ b/Documentation/git-cat-file.txt @@ -0,0 +1,61 @@ +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 | -s | ) + +DESCRIPTION +----------- +Provides content or type of objects in the repository. The type +is required unless '-t' is used to find the object type, +or '-s' is used to find the object size. + +OPTIONS +------- +:: + The sha1 identifier of the object. + +-t:: + Instead of the content, show the object type identified by + . + +-s:: + Instead of the content, show the object size 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 . If '-s' is specified, +the size of the in bytes. + +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-checkout-cache.txt b/Documentation/git-checkout-cache.txt new file mode 100644 index 00000000..321a00c2 --- /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-clone-pack.txt b/Documentation/git-clone-pack.txt new file mode 100644 index 00000000..0dc89a90 --- /dev/null +++ b/Documentation/git-clone-pack.txt @@ -0,0 +1,65 @@ +git-clone-pack(1) +================= +v0.1, July 2005 + +NAME +---- +git-clone-pack - Clones a repository by receiving packed objects. + + +SYNOPSIS +-------- +'git-clone-pack' [-q] [--exec=] [:] [...] + +DESCRIPTION +----------- +Clones a repository into the current repository by invoking +'git-upload-pack', possibly on the remote host via ssh, in +the named repository, and invoking 'git-unpack-objects' locally +to receive the pack. + +OPTIONS +------- +-q:: + Pass '-q' flag to 'git-unpack-objects'; this makes the + cloning process less verbose. + +--exec=:: + Use this to specify the path to 'git-upload-pack' on the + remote side, if is not found on your $PATH. + Installations of sshd ignores the user's environment + setup scripts for login shells (e.g. .bash_profile) and + your privately installed GIT may not be found on the system + default $PATH. Another workaround suggested is to set + up your $PATH in ".bashrc", but this flag is for people + who do not want to pay the overhead for non-interactive + shells by having a lean .bashrc file (they set most of + the things up in .bash_profile). + +:: + A remote host that houses the repository. When this + part is specified, 'git-upload-pack' is invoked via + ssh. + +:: + The repository to sync from. + +...:: + The heads to update. This is relative to $GIT_DIR + (e.g. "HEAD", "refs/heads/master"). When unspecified, + all heads are updated to match the remote repository. + + +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-clone-script.txt b/Documentation/git-clone-script.txt new file mode 100644 index 00000000..afb25bd8 --- /dev/null +++ b/Documentation/git-clone-script.txt @@ -0,0 +1,60 @@ +git-clone-script(1) +=================== +v0.1, July 2005 + +NAME +---- +git-clone-script - Clones a repository. + + +SYNOPSIS +-------- +'git clone' [-l] [-u ] [-q] + +DESCRIPTION +----------- +Clones a repository into a newly created directory. + +OPTIONS +------- +-l:: + When the repository to clone from is on a local machine, + this flag bypasses normal "git aware" transport + mechanism and clones the repository by making a copy of + HEAD and everything under objects and refs directories. + The files under .git/objects/ directory are hardlinked + to save space when possible. + +-q:: + Operate quietly. This flag is passed to "rsync" and + "git-clone-pack" commands when given. + +-u :: + When given, and the repository to clone from is handled + by 'git-clone-pack', '--exec=' is passed to + the command to specify non-default path for the command + run on the other end. + +:: + The (possibly remote) repository to clone from. It can + be an "rsync://host/dir" URL, an "http://host/dir" URL, + or [:]/dir notation that is used by 'git-clone-pack'. + Currently http transport is not supported. + +:: + The name of a new directory to be cloned into. It is an + error to specify an existing directory. + +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-commit-script.txt b/Documentation/git-commit-script.txt new file mode 100644 index 00000000..cf6b5c3d --- /dev/null +++ b/Documentation/git-commit-script.txt @@ -0,0 +1,62 @@ +git-commit-script(1) +==================== +v0.99.4, Aug 2005 + +NAME +---- +git-commit-script - Record your changes + +SYNOPSIS +-------- +'git commit' [-a] [-s] [-v] [(-c | -C) | -F | -m ] ... + +DESCRIPTION +----------- +Updates the index file for given paths, or all modified files if +'-a' is specified, and makes a commit object. The command +VISUAL and EDITOR environment variables to edit the commit log +message. + +OPTIONS +------- +-a:: + Update all paths in the index file. + +-c or -C :: + Take existing commit object, and reuse the log message + and the authorship information (including the timestamp) + when creating the commit. With '-C', the editor is not + invoked; with '-c' the user can further edit the commit + message. + +-F :: + Take the commit message from the given file. Use '-' to + read the message from the standard input. + +-m :: + Use the given as the commit message. + +-s:: + Add Signed-off-by line at the end of the commit message. + +-v:: + Look for suspicious lines the commit introduces, and + abort committing if there is one. The definition of + 'suspicious lines' is currently the lines that has + trailing whitespaces, and the lines whose indentation + has a SP character immediately followed by a TAB + character. + +...:: + Update specified paths in the index file. + + +Author +------ +Written by Linus Torvalds and +Junio C Hamano + + +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 00000000..55366688 --- /dev/null +++ b/Documentation/git-commit-tree.txt @@ -0,0 +1,92 @@ +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 +Your parents must have hated you!:: + The password(5) gecos field is longer than a giant static buffer. +Your sysadmin must hate you!:: + The password(5) name field is longer than a giant static buffer. + +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 00000000..66d7fe78 --- /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-cvsimport-script.txt b/Documentation/git-cvsimport-script.txt new file mode 100644 index 00000000..d01a15d8 --- /dev/null +++ b/Documentation/git-cvsimport-script.txt @@ -0,0 +1,106 @@ +git-cvsimport-script(1) +======================= +v0.1, July 2005 + +NAME +---- +git-cvsimport-script - Import a CVS repository into git + + +SYNOPSIS +-------- +'git-cvsimport-script' [ -o ] [ -h ] [ -v ] + [ -d ] [ -p ] + [ -C ] [ -i ] [ -k ] + [ -s ] [ -m ] [ -M regex ] [ ] + + +DESCRIPTION +----------- +Imports a CVS repository into git. It will either create a new +repository, or incrementally import into an existing one. + +Splitting the CVS log into patch sets is done by 'cvsps'. +At least version 2.1 is required. + +OPTIONS +------- +-d :: + The root of the CVS archive. May be local (a simple path) or remote; + currently, only the :local:, :ext: and :pserver: access methods + are supported. + +-C :: + The GIT repository to import to. If the directory doesn't + exist, it will be created. Default is the current directory. + +-i:: + Import-only: don't perform a checkout after importing. This option + ensures the working directory and cache remain untouched and will + not create them if they do not exist. + +-k:: + Kill keywords: will extract files with -kk from the CVS archive + to avoid noisy changesets. Highly recommended, but off by default + to preserve compatibility with early imported trees. + +-o :: + The 'HEAD' branch from CVS is imported to the 'origin' branch within + the git repository, as 'HEAD' already has a special meaning for git. + Use this option if you want to import into a different branch. + + Use '-o master' for continuing an import that was initially done by + the old cvs2git tool. + +-p :: + Additional options for cvsps. + The options '-u' and '-A' are implicit and should not be used here. + + If you need to pass multiple options, separate them with a comma. + +-m:: + Attempt to detect merges based on the commit message. This option + will enable default regexes that try to capture the name source + branch name from the commit message. + +-M :: + Attempt to detect merges based on the commit message with a custom + regex. It can be used with -m to also see the default regexes. + You must escape forward slashes. + +-v:: + Verbosity: let 'cvsimport' report what it is doing. + +:: + The CVS module you want to import. Relative to . + +-h:: + Print a short usage message and exit. + +-z :: + Pass the timestamp fuzz factor to cvsps. + +-s :: + Substitute the character "/" in branch names with + +OUTPUT +------ +If '-v' is specified, the script reports what it is doing. + +Otherwise, success is indicated the Unix way, i.e. by simply exiting with +a zero exit status. + + +Author +------ +Written by Matthias Urlichs , with help from +various participants of the git-list . + +Documentation +-------------- +Documentation by Matthias Urlichs . + +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 00000000..a353d126 --- /dev/null +++ b/Documentation/git-diff-cache.txt @@ -0,0 +1,134 @@ +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' [-m] [--cached] [] [...] + +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 +------- +include::diff-options.txt[] + +:: + The id of a tree object to diff against. + +--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 cache + contents (the ones I'd write with a "git-write-tree") + +For example, let's say that you have worked on your working directory, updated +some files in the cache 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 00000000..3e1244f8 --- /dev/null +++ b/Documentation/git-diff-files.txt @@ -0,0 +1,44 @@ +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' [-q] [] [...] + +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 +------- +include::diff-options.txt[] + +-q:: + Remain silent even on nonexisting files + +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 00000000..d826deb4 --- /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 00000000..2084c704 --- /dev/null +++ b/Documentation/git-diff-stages.txt @@ -0,0 +1,41 @@ +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' [] [...] + +DESCRIPTION +----------- +Compares the content and mode of the blobs in two stages in an +unmerged index file. + +OPTIONS +------- +include::diff-options.txt[] + +,:: + The stage number to be compared. + +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 00000000..5ccf0ba1 --- /dev/null +++ b/Documentation/git-diff-tree.txt @@ -0,0 +1,130 @@ +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' [--stdin] [-m] [-s] [-v] [--pretty] [-t] [] [...] + +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 +------- +include::diff-options.txt[] + +:: + 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. + +-t:: + show tree entry itself as well as subtrees. Implies -r. + +--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 "=