diff options
Diffstat (limited to 'Documentation')
115 files changed, 10494 insertions, 0 deletions
diff --git a/Documentation/.gitignore b/Documentation/.gitignore new file mode 100644 index 0000000000..dad52b80d3 --- /dev/null +++ b/Documentation/.gitignore @@ -0,0 +1,5 @@ +*.xml +*.html +*.1 +*.7 +howto-index.txt diff --git a/Documentation/Makefile b/Documentation/Makefile new file mode 100644 index 0000000000..aecae676de --- /dev/null +++ b/Documentation/Makefile @@ -0,0 +1,93 @@ +MAN1_TXT=$(wildcard git-*.txt) gitk.txt +MAN7_TXT=git.txt + +DOC_HTML=$(patsubst %.txt,%.html,$(MAN1_TXT) $(MAN7_TXT)) + +ARTICLES = tutorial +ARTICLES += cvs-migration +ARTICLES += diffcore +ARTICLES += howto-index +ARTICLES += repository-layout +ARTICLES += hooks +# with their own formatting rules. +SP_ARTICLES = glossary howto/revert-branch-rebase + +DOC_HTML += $(patsubst %,%.html,$(ARTICLES) $(SP_ARTICLES)) + +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: man + $(INSTALL) -d -m755 $(DESTDIR)/$(man1) $(DESTDIR)/$(man7) + $(INSTALL) $(DOC_MAN1) $(DESTDIR)/$(man1) + $(INSTALL) $(DOC_MAN7) $(DESTDIR)/$(man7) + +# 'include' dependencies +$(patsubst %.txt,%.1,$(wildcard git-diff-*.txt)): \ + diff-format.txt diff-options.txt +$(patsubst %,%.1,git-fetch git-pull git-push): pull-fetch-param.txt +git.7: ../README + +clean: + rm -f *.xml *.html *.1 *.7 howto-index.txt howto/*.html + +%.html : %.txt + asciidoc -b xhtml11 -d manpage -f asciidoc.conf $< + +%.1 %.7 : %.xml + xmlto man $< + +%.xml : %.txt + asciidoc -b docbook -d manpage -f asciidoc.conf $< + +git.html: git.txt ../README + +glossary.html : glossary.txt sort_glossary.pl + cat $< | \ + perl sort_glossary.pl | \ + asciidoc -b xhtml11 - > glossary.html + +howto-index.txt: howto-index.sh $(wildcard howto/*.txt) + rm -f $@+ $@ + sh ./howto-index.sh $(wildcard howto/*.txt) >$@+ + mv $@+ $@ + +$(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt + asciidoc -b xhtml11 $*.txt + +WEBDOC_DEST = /pub/software/scm/git/docs + +$(patsubst %.txt,%.html,$(wildcard howto/*.txt)): %.html : %.txt + rm -f $@+ $@ + sed -e '1,/^$$/d' $? | asciidoc -b xhtml11 - >$@+ + mv $@+ $@ + +install-webdoc : html + sh ./install-webdoc.sh $(WEBDOC_DEST) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches new file mode 100644 index 0000000000..9ccb8f72ed --- /dev/null +++ b/Documentation/SubmittingPatches @@ -0,0 +1,298 @@ +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, that is OK. + +Do not PGP sign your patch, at least for now. Most likely, your +maintainer or other people on the list would not have your PGP +key and would not bother obtaining it anyway. Your patch is not +judged by who you are; a good patch from an unknown origin has a +far better chance of being accepted than a patch from a known, +respected origin that is done poorly or does incorrect things. + +If you really really really really want to do a PGP signed +patch, format it as "multipart/signed", not a text/plain message +that starts with '-----BEGIN PGP SIGNED MESSAGE-----'. That is +not a text/plain, it's something else. + +Note that your maintainer does not necessarily read everything +on the git mailing list. If your patch is for discussion first, +send it "To:" the mailing list, and optionally "cc:" him. If it +is trivially correct or after the list reached a 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 <random@developer.example.org> + +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. + + +------------------------------------------------ +MUA specific hints + +Some of patches I receive or pick up from the list share common +patterns of breakage. Please make sure your MUA is set up +properly not to corrupt whitespaces. Here are two common ones +I have seen: + +* Empty context lines that do not have _any_ whitespace. + +* Non empty context lines that have one extra whitespace at the + beginning. + +One test you could do yourself if your MUA is set up correctly is: + +* Send the patch to yourself, exactly the way you would, except + To: and Cc: lines, which would not contain the list and + maintainer address. + +* Save that patch to a file in UNIX mailbox format. Call it say + a.patch. + +* Try to apply to the tip of the "master" branch from the + git.git public repository: + + $ git fetch http://kernel.org/pub/scm/git/git.git master:test-apply + $ git checkout test-apply + $ git reset --hard + $ git applymbox a.patch + +If it does not apply correctly, there can be various reasons. + +* Your patch itself does not apply cleanly. That is _bad_ but + does not have much to do with your MUA. Please rebase the + patch appropriately. + +* Your MUA corrupted your patch; applymbox would complain that + the patch does not apply. Look at .dotest/ subdirectory and + see what 'patch' file contains and check for the common + corruption patterns mentioned above. + +* While you are at it, check what are in 'info' and + 'final-commit' files as well. If what is in 'final-commit' is + not exactly what you would want to see in the commit log + message, it is very likely that your maintainer would end up + hand editing the log message when he applies your patch. + Things like "Hi, this is my first patch.\n", if you really + want to put in the patch e-mail, should come after the + three-dash line that signals the end of the commit message. + + +Pine +---- + +(Johannes Schindelin) + +I don't know how many people still use pine, but for those poor +souls it may be good to mention that the quell-flowed-text is +needed for recent versions. + +... the "no-strip-whitespace-before-send" option, too. AFAIK it +was introduced in 4.60. + +(Linus Torvalds) + +And 4.58 needs at least this. + +--- +diff-tree 8326dd8350be64ac7fc805f6563a1d61ad10d32c (from e886a61f76edf5410573e92e38ce22974f9c40f1) +Author: Linus Torvalds <torvalds@g5.osdl.org> +Date: Mon Aug 15 17:23:51 2005 -0700 + + Fix pine whitespace-corruption bug + + There's no excuse for unconditionally removing whitespace from + the pico buffers on close. + +diff --git a/pico/pico.c b/pico/pico.c +--- a/pico/pico.c ++++ b/pico/pico.c +@@ -219,7 +219,9 @@ PICO *pm; + switch(pico_all_done){ /* prepare for/handle final events */ + case COMP_EXIT : /* already confirmed */ + packheader(); ++#if 0 + stripwhitespace(); ++#endif + c |= COMP_EXIT; + break; + + +(Daniel Barkalow) + +> A patch to SubmittingPatches, MUA specific help section for +> users of Pine 4.63 would be very much appreciated. + +Ah, it looks like a recent version changed the default behavior to do the +right thing, and inverted the sense of the configuration option. (Either +that or Gentoo did it.) So you need to set the +"no-strip-whitespace-before-send" option, unless the option you have is +"strip-whitespace-before-send", in which case you should avoid checking +it. + + +Thunderbird +----------- + +(A Large Angry SCM) + +Here are some hints on how to successfully submit patches inline using +Thunderbird. + +This recipe appears to work with the current [*1*] Thunderbird from Suse. + +The following Thunderbird extensions are needed: + AboutConfig 0.5 + http://aboutconfig.mozdev.org/ + External Editor 0.5.4 + http://extensionroom.mozdev.org/more-info/exteditor + +1) Prepare the patch as a text file using your method of choice. + +2) Before opening a compose window, use Edit->Account Settings to +uncheck the "Compose messages in HTML format" setting in the +"Composition & Addressing" panel of the account to be used to send the +patch. [*2*] + +3) In the main Thunderbird window, _before_ you open the compose window +for the patch, use Tools->about:config to set the following to the +indicated values: + mailnews.send_plaintext_flowed => false + mailnews.wraplength => 0 + +4) Open a compose window and click the external editor icon. + +5) In the external editor window, read in the patch file and exit the +editor normally. + +6) Back in the compose window: Add whatever other text you wish to the +message, complete the addressing and subject fields, and press send. + +7) Optionally, undo the about:config/account settings changes made in +steps 2 & 3. + + +[Footnotes] +*1* Version 1.0 (20041207) from the MozillaThunderbird-1.0-5 rpm of Suse +9.3 professional updates. + +*2* It may be possible to do this with about:config and the following +settings but I haven't tried, yet. + mail.html_compose => false + mail.identity.default.compose_html => false + mail.identity.id?.compose_html => false + diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf new file mode 100644 index 0000000000..baefb2f0da --- /dev/null +++ b/Documentation/asciidoc.conf @@ -0,0 +1,21 @@ +## gitlink: macro +# +# Usage: gitlink:command[manpage-section] +# +# Note, {0} is the manpage section, while {target} is the command. +# +# Show GIT link as: <command>(<section>); if section is defined, else just show +# the command. + +ifdef::backend-docbook[] +[gitlink-inlinemacro] +{0%{target}} +{0#<citerefentry>} +{0#<refentrytitle>{target}</refentrytitle><manvolnum>{0}</manvolnum>} +{0#</citerefentry>} +endif::backend-docbook[] + +ifdef::backend-xhtml11[] +[gitlink-inlinemacro] +<a href="{target}.html">{target}{0?({0})}</a> +endif::backend-xhtml11[] diff --git a/Documentation/cvs-migration.txt b/Documentation/cvs-migration.txt new file mode 100644 index 0000000000..390a72392b --- /dev/null +++ b/Documentation/cvs-migration.txt @@ -0,0 +1,248 @@ +Git for CVS users +================= +v0.99.5, Aug 2005 + +Ok, so you're a CVS user. That's ok, it's a treatable condition, and the +first step to recovery is admitting you have a problem. The fact that +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 +link:tutorial.html[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 <cvsroot> -C <destination> <module> + +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 <destination>; 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 0000000000..6e9fa8cdb7 --- /dev/null +++ b/Documentation/diff-format.txt @@ -0,0 +1,140 @@ +The output format from "git-diff-index", "git-diff-tree" and +"git-diff-files" are very similar. + +These commands all compare two sets of things; what are +compared are different: + +git-diff-index <tree-ish>:: + compares the <tree-ish> and the files on the filesystem. + +git-diff-index --cached <tree-ish>:: + compares the <tree-ish> and the cache. + +git-diff-tree [-r] <tree-ish-1> <tree-ish-2> [<pattern>...]:: + compares the trees named by the two arguments. + +git-diff-files [<pattern>...]:: + 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... A file4 +delete :100644 000000 1234567... 0000000... D file5 +unmerged :000000 000000 0000000... 0000000... U file6 +------------------------------------------------ + +That is, from the left to the right: + +. a colon. +. mode for "src"; 000000 if creation or unmerged. +. a space. +. mode for "dst"; 000000 if deletion or unmerged. +. a space. +. sha1 for "src"; 0\{40\} if creation or unmerged. +. a space. +. sha1 for "dst"; 0\{40\} if creation, unmerged or "look at work tree". +. a space. +. status, followed by optional "score" number. +. a tab or a NUL when '-z' option is used. +. path for "src" +. a tab or a NUL when '-z' option is used; only exists for C or R. +. path for "dst"; only exists for C or R. +. an LF or a NUL when '-z' option is used, to terminate the record. + +<sha1> 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-index", "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. + +1. When the environment variable 'GIT_EXTERNAL_DIFF' is not set, + these commands internally invoke "diff" like this: + + diff -L a/<path> -L b/<path> -pu <old> <new> ++ +For added files, `/dev/null` is used for <old>. For removed +files, `/dev/null` is used for <new> ++ +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-index -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: + + <old|new>-file:: are files GIT_EXTERNAL_DIFF can use to read the + contents of <old|ne>, + <old|new>-hex:: are the 40-hexdigit SHA1 hashes, + <old|new>-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, <path>. + + +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/` filenames. ++ +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 <mode> + new mode <mode> + deleted file mode <mode> + new file mode <mode> + copy from <path> + copy to <path> + rename from <path> + rename to <path> + similarity index <number> + dissimilarity index <number> diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt new file mode 100644 index 0000000000..613a60d601 --- /dev/null +++ b/Documentation/diff-options.txt @@ -0,0 +1,62 @@ +-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-status:: + Show only names and status of changed files. + +-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. + +-l<num>:: + -M and -C options require O(n^2) processing time where n + in the number of potential rename/copy targets. This + option prevents rename/copy detection from running if + the number of rename/copy targets exceed the specified + number. + +-S<string>:: + Look for differences that contains the change in <string>. + +--pickaxe-all:: + When -S finds a change, show all the changes in that + changeset, not just the files that contains the change + in <string>. + +-O<orderfile>:: + Output the patch in the order specified in the + <orderfile>, 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. + +For more detailed explanation on these common options, see also +link:diffcore.html[diffcore documentation]. diff --git a/Documentation/diffcore.txt b/Documentation/diffcore.txt new file mode 100644 index 0000000000..1908b92f38 --- /dev/null +++ b/Documentation/diffcore.txt @@ -0,0 +1,264 @@ +Tweaking diff output +==================== +June 2005 + + +Introduction +------------ + +The diff commands git-diff-index, git-diff-files, and +git-diff-tree can be told to manipulate differences they find +in unconventional ways before showing diff(1) output. The +manipulation is collectively called "diffcore transformation". +This short note describes what they are and how to use them to +produce diff outputs that are easier to understand than the +conventional kind. + + +The chain of operation +---------------------- + +The git-diff-* family works by first comparing two sets of +files: + + - git-diff-index 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... A 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... A 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... A 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... A 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 defaults 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 +would look like this: + +------------------------------------------------ + README + Makefile + Documentation + *.h + *.c + t +------------------------------------------------ + diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt new file mode 100644 index 0000000000..ae1ea762f5 --- /dev/null +++ b/Documentation/git-add.txt @@ -0,0 +1,33 @@ +git-add(1) +========== + +NAME +---- +git-add - Add files to the cache. + +SYNOPSIS +-------- +'git-add' <file>... + +DESCRIPTION +----------- +A simple wrapper to git-update-index to add files to the cache for people used +to do "cvs add". + +OPTIONS +------- +<file>...:: + Files to add to the cache. + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt new file mode 100644 index 0000000000..4f7e1195de --- /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] [<patch>...] + +DESCRIPTION +----------- +Reads supplied diff output and applies it on a GIT index file +and a work tree. + +OPTIONS +------- +<patch>...:: + 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 <torvalds@osdl.org> + +Documentation +-------------- +Documentation by Junio C Hamano + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-applymbox.txt b/Documentation/git-applymbox.txt new file mode 100644 index 0000000000..5022643ad1 --- /dev/null +++ b/Documentation/git-applymbox.txt @@ -0,0 +1,84 @@ +git-applymbox(1) +================ + +NAME +---- +git-applymbox - Apply a series of patches in a mailbox + + +SYNOPSIS +-------- +'git-applymbox' [-u] [-k] [-q] ( -c .dotest/<num> | <mbox> ) [ <signoff> ] + +DESCRIPTION +----------- +Splits mail messages in a mailbox into commit log message, +authorship information and patches, and applies them to the +current branch. + + +OPTIONS +------- +-q:: + Apply patches interactively. The user will be given + opportunity to edit the log message and the patch before + attempting to apply patch in each e-mail message. + +-k:: + Usually the program 'cleans up' the Subject: header line + to extract the title line for the commit log message, + among which (1) remove 'Re:' or 're:', (2) leading + whitespaces, (3) '[' up to ']', typically '[PATCH]', and + then prepends "[PATCH] ". This flag forbids this + munging, and is most useful when used to read back 'git + format-patch --mbox' output. + +-u:: + By default, the commit log message, author name and + author email are taken from the e-mail without any + charset conversion, after minimally decoding MIME + transfer encoding. This flag causes the resulting + commit to be encoded in utf-8 by transliterating them. + Note that the patch is always used as is without charset + conversion, even with this flag. + +-c .dotest/<num>:: + When the patch contained in an e-mail does not cleanly + apply, the command exits with an error message. The + patch and extracted message are found in .dotest/, and + you could re-run 'git applymbox' with '-c .dotest/<num>' + flag to restart the process after inspecting and fixing + them. + +<mbox>:: + The name of the file that contains the e-mail messages + with patches. This file should be in the UNIX mailbox + format. See 'SubmittingPatches' document to learn about + the formatting convention for e-mail submission. + +<signoff>:: + The name of the file that contains your "Signed-off-by" + line. See 'SubmittingPatches' document to learn what + "Signed-off-by" line means. You can also just say + 'yes', 'true', 'me', or 'please' to use an automatically + generated "Signed-off-by" line based on your committer + identity. + + +SEE ALSO +-------- +gitlink:git-applypatch[1]. + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-applypatch.txt b/Documentation/git-applypatch.txt new file mode 100644 index 0000000000..4046360217 --- /dev/null +++ b/Documentation/git-applypatch.txt @@ -0,0 +1,50 @@ +git-applypatch(1) +================= + +NAME +---- +git-applypatch - Apply one patch extracted from an e-mail. + + +SYNOPSIS +-------- +'git-applypatch' <msg> <patch> <info> [<signoff>] + +DESCRIPTION +----------- +Takes three files <msg>, <patch>, and <info> prepared from an +e-mail message by 'git-mailinfo', and creates a commit. It is +usually not necessary to use this command directly. + +This command can run `applypatch-msg`, `pre-applypatch`, and +`post-applypatch` hooks. See link:hooks.html[hooks] for more +information. + + +OPTIONS +------- +<msg>:: + Commit log message (sans the first line, which comes + from e-mail Subject stored in <info>). + +<patch>:: + The patch to apply. + +<info>: + Author and subject information extracted from e-mail, + used on "author" line and as the first line of the + commit log message. + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-archimport.txt b/Documentation/git-archimport.txt new file mode 100644 index 0000000000..6054731741 --- /dev/null +++ b/Documentation/git-archimport.txt @@ -0,0 +1,82 @@ +git-archimport(1) +================= + +NAME +---- +git-archimport - Import an Arch repository into GIT + + +SYNOPSIS +-------- +`git-archimport` [ -h ] [ -v ] [ -T ] [ -t tempdir ] + <archive/branch> [ <archive/branch> ] + +DESCRIPTION +----------- +Imports a project from one or more Arch repositories. It will follow branches +and repositories within the namespaces defined by the <archive/branch> +parameters suppplied. If it cannot find the remote branch a merge comes from +it will just import it as a regular commit. If it can find it, it will mark it +as a merge whenever possible (see discussion below). + +The script expects you to provide the key roots where it can start the import +from an 'initial import' or 'tag' type of Arch commit. It will follow and import +new branches within the provided roots. + +It expects to be dealing with one project only. If it sees +branches that have different roots, it will refuse to run. In that case, edit your +<archive/branch> parameters to define clearly the scope of the import. + +`git-archimport` uses `tla` extensively in the background to access the Arch repository. +Make sure you have a recent version of `tla` available in the path. `tla` must +know about the repositories you pass to `git-archimport`. + +For the initial import `git-archimport` expects to find itself in an empty +directory. To follow the development of a project that uses Arch, rerun +`git-archimport` with the same parameters as the initial import to perform incremental imports. + +MERGES +------ +Patch merge data from Arch is used to mark merges in GIT as well. GIT +does not care much about tracking patches, and only considers a merge when a +branch incorporates all the commits since the point they forked. The end result +is that GIT will have a good idea of how far branches have diverged. So the +import process does lose some patch-trading metadata. + +Fortunately, when you try and merge branches imported from Arch, +GIT will find a good merge base, and it has a good chance of identifying +patches that have been traded out-of-sequence between the branches. + +OPTIONS +------- + +-h:: + Display usage. + +-v:: + Verbose output. + +-T:: + Many tags. Will create a tag for every commit, reflecting the commit + name in the Arch repository. + +-t <tmpdir>:: + Override the default tempdir. + + +<archive/branch>:: + Archive/branch identifier in a format that `tla log` understands. + + +Author +------ +Written by Martin Langhoff <martin@catalyst.net.nz>. + +Documentation +-------------- +Documentation by Junio C Hamano, Martin Langhoff and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt new file mode 100644 index 0000000000..b124b0751c --- /dev/null +++ b/Documentation/git-bisect.txt @@ -0,0 +1,100 @@ +git-bisect(1) +============= + +NAME +---- +git-bisect - Find the change that introduced a bug + + +SYNOPSIS +-------- +'git bisect' start +'git bisect' bad <rev> +'git bisect' good <rev> +'git bisect' reset [<branch>] +'git bisect' visualize +'git bisect' replay <logfile> +'git bisect' log + +DESCRIPTION +----------- +This command uses 'git-rev-list --bisect' option to help drive +the binary search process to find which change introduced a bug, +given an old "good" commit object name and a later "bad" commit +object name. + +The way you use it is: + +------------------------------------------------ +git bisect start +git bisect bad # Current version is bad +git bisect good v2.6.13-rc2 # v2.6.13-rc2 was the last version + # tested that was good +------------------------------------------------ + +When you give at least one bad and one good versions, it will +bisect the revision tree and say something like: + +------------------------------------------------ +Bisecting: 675 revisions left to test after this +------------------------------------------------ + +and check out the state in the middle. Now, compile that kernel, and boot +it. Now, let's say that this booted kernel works fine, then just do + +------------------------------------------------ +git bisect good # this one is good +------------------------------------------------ + +which will now say + +------------------------------------------------ +Bisecting: 337 revisions left to test after this +------------------------------------------------ + +and you continue along, compiling that one, testing it, and depending on +whether it is good or bad, you say "git bisect good" or "git bisect bad", +and ask for the next bisection. + +Until you have no more left, and you'll have been left with the first bad +kernel rev in "refs/bisect/bad". + +Oh, and then after you want to reset to the original head, do a + +------------------------------------------------ +git bisect reset +------------------------------------------------ + +to get back to the master branch, instead of being in one of the bisection +branches ("git bisect start" will do that for you too, actually: it will +reset the bisection state, and before it does that it checks that you're +not using some old bisection branch). + +During the bisection process, you can say + + git bisect visualize + +to see the currently remaining suspects in `gitk`. + +The good/bad you told the command is logged, and `git bisect +log` shows what you have done so far. You can truncate its +output somewhere and save it in a file, and run + + git bisect replay that-file + +if you find later you made a mistake telling good/bad about a +revision. + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt new file mode 100644 index 0000000000..a2a0cfb7be --- /dev/null +++ b/Documentation/git-branch.txt @@ -0,0 +1,39 @@ +git-branch(1) +============= + +NAME +---- +git-branch - Create a new branch. + +SYNOPSIS +-------- +'git-branch' [<branchname> [start-point]] + +DESCRIPTION +----------- +If no argument is provided, show available branches and mark current +branch with star. Otherwise, create a new branch of name <branchname>. + +If a starting point is also specified, that will be where the branch is +created, otherwise it will be created at the current HEAD. + +OPTIONS +------- +<branchname>:: + The name of the branch to create. + +start-point:: + Where to make the branch; defaults to HEAD. + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> and Junio C Hamano <junkio@cox.net> + +Documentation +-------------- +Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt new file mode 100644 index 0000000000..44983b692d --- /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 | <type>) <object> + +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 +------- +<object>:: + The sha1 identifier of the object. + +-t:: + Instead of the content, show the object type identified by + <object>. + +-s:: + Instead of the content, show the object size identified by + <object>. + +<type>:: + Typically this matches the real type of <object> but asking + for a type that can trivially dereferenced from the given + <object> is also permitted. An example is to ask for a + "tree" with <object> being a commit object that contains it, + or to ask for a "blob" with <object> being a tag object that + points at it. + +OUTPUT +------ +If '-t' is specified, one of the <type>. If '-s' is specified, +the size of the <object> in bytes. + +Otherwise the raw (though uncompressed) contents of the <object> will +be returned. + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-checkout-index.txt b/Documentation/git-checkout-index.txt new file mode 100644 index 0000000000..1ba6fb2d9c --- /dev/null +++ b/Documentation/git-checkout-index.txt @@ -0,0 +1,106 @@ +git-checkout-index(1) +===================== +v0.1, May 2005 + +NAME +---- +git-checkout-index - Copy files from the cache to the working directory + + +SYNOPSIS +-------- +'git-checkout-index' [-u] [-q] [-a] [-f] [-n] [--prefix=<string>] + [--] <file>... + +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=<string>:: + When creating files, prepend <string> (usually a directory + including a trailing /) + +--:: + Do not interpret any more arguments as options. + +Note that the order of the flags matters: + + git-checkout-index -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-index" does nothing. You probably meant +"git-checkout-index -a". And if you want to force it, you want +"git-checkout-index -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-index -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-index -n -f -a && git-update-index --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-index as an "export as tree" function. Just read the +desired tree into the index, and do a + + git-checkout-index --prefix=git-export-dir/ -a + +and git-checkout-index 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-index --prefix=.merged- Makefile + +to check out the currently cached copy of `Makefile` into the file +`.merged-Makefile` + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt new file mode 100644 index 0000000000..f753c149a5 --- /dev/null +++ b/Documentation/git-checkout.txt @@ -0,0 +1,43 @@ +git-checkout(1) +=============== + +NAME +---- +git-checkout - Checkout and switch to a branch. + +SYNOPSIS +-------- +'git-checkout' [-f] [-b <new_branch>] [<branch>] + +DESCRIPTION +----------- +Updates the index and working tree to reflect the specified branch, +<branch>. Updates HEAD to be <branch> or, if specified, <new_branch>. + +OPTIONS +------- +-f:: + Force an re-read of everything. + +-b:: + Create a new branch and start it at <branch>. + +<new_branch>:: + Name for the new branch. + +<branch>:: + Branch to checkout; may be any object ID that resolves to a + commit. Defaults to HEAD. + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt new file mode 100644 index 0000000000..e6a8c87853 --- /dev/null +++ b/Documentation/git-cherry-pick.txt @@ -0,0 +1,57 @@ +git-cherry-pick(1) +================== +v0.99.5 Aug 2005 + +NAME +---- +git-cherry-pick - Apply the change introduced by an existing commit. + +SYNOPSIS +-------- +'git-cherry-pick' [-n] [-r] <commit> + +DESCRIPTION +----------- +Given one existing commit, apply the change the patch introduces, and record a +new commit that records it. This requires your working tree to be clean (no +modifications from the HEAD commit). + +OPTIONS +------- +<commit>:: + Commit to cherry-pick. + +-r:: + Usuall the command appends which commit was + cherry-picked after the original commit message when + making a commit. This option, '--replay', causes it to + use the original commit message intact. This is useful + when you are reordering the patches in your private tree + before publishing, and is used by 'git rebase'. + +-n:: + Usually the command automatically creates a commit with + a commit log message stating which commit was + cherry-picked. This flag applies the change necessary + to cherry-pick the named commit to your working tree, + but does not make the commit. In addition, when this + option is used, your working tree does not have to match + the HEAD commit. The cherry-pick is done against the + beginning state of your working tree. + + This is useful when cherry-picking more than one commits' + effect to your working tree in a row. + + +Author +------ +Written by Junio C Hamano <junkio@cox.net> + +Documentation +-------------- +Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-cherry.txt b/Documentation/git-cherry.txt new file mode 100644 index 0000000000..af87966e51 --- /dev/null +++ b/Documentation/git-cherry.txt @@ -0,0 +1,42 @@ +git-cherry(1) +============= + +NAME +---- +git-cherry - Find commits not merged upstream. + +SYNOPSIS +-------- +'git-cherry' [-v] <upstream> [<head>] + +DESCRIPTION +----------- +Each commit between the fork-point and <head> is examined, and compared against +the change each commit between the fork-point and <upstream> introduces. +Commits already included in upstream are prefixed with '-' (meaning "drop from +my local pull"), while commits missing from upstream are prefixed with '+' +(meaning "add to the updated upstream"). + +OPTIONS +------- +-v:: + Verbose. + +<upstream>:: + Upstream branch to compare against. + +<head>:: + Working branch; defaults to HEAD. + +Author +------ +Written by Junio C Hamano <junkio@cox.net> + +Documentation +-------------- +Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-clone-pack.txt b/Documentation/git-clone-pack.txt new file mode 100644 index 0000000000..83d17a055f --- /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=<git-upload-pack>] [<host>:]<directory> [<head>...] + +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=<git-upload-pack>:: + 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). + +<host>:: + A remote host that houses the repository. When this + part is specified, 'git-upload-pack' is invoked via + ssh. + +<directory>:: + The repository to sync from. + +<head>...:: + 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 <torvalds@osdl.org> + +Documentation +-------------- +Documentation by Junio C Hamano. + + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt new file mode 100644 index 0000000000..bd53ef430d --- /dev/null +++ b/Documentation/git-clone.txt @@ -0,0 +1,60 @@ +git-clone(1) +============ +v0.1, July 2005 + +NAME +---- +git-clone - Clones a repository. + + +SYNOPSIS +-------- +'git clone' [-l] [-u <upload-pack>] [-q] <repository> <directory> + +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 <upload-pack>:: + When given, and the repository to clone from is handled + by 'git-clone-pack', '--exec=<upload-pack>' is passed to + the command to specify non-default path for the command + run on the other end. + +<repository>:: + The (possibly remote) repository to clone from. It can + be an "rsync://host/dir" URL, an "http://host/dir" URL, + or [<host>:]/dir notation that is used by 'git-clone-pack'. + Currently http transport is not supported. + +<directory>:: + The name of a new directory to be cloned into. It is an + error to specify an existing directory. + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by Junio C Hamano. + + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt new file mode 100644 index 0000000000..705be4e334 --- /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' <tree> [-p <parent commit>]\ < 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 +------- +<tree>:: + An existing tree object + +-p <parent commit>:: + 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 +-------- +gitlink:git-write-tree[1] + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt new file mode 100644 index 0000000000..790a8eb0dd --- /dev/null +++ b/Documentation/git-commit.txt @@ -0,0 +1,72 @@ +git-commit(1) +============= +v0.99.4, Aug 2005 + +NAME +---- +git-commit - Record your changes + +SYNOPSIS +-------- +'git commit' [-a] [-s] [-v] [(-c | -C) <commit> | -F <file> | -m <msg>] [-e] <file>... + +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. + +This command can run `commit-msg`, `pre-commit`, and +`post-commit` hooks. See link:hooks.html[hooks] for more +information. + +OPTIONS +------- +-a:: + Update all paths in the index file. + +-c or -C <commit>:: + 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 <file>:: + Take the commit message from the given file. Use '-' to + read the message from the standard input. + +-m <msg>:: + Use the given <msg> 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. + +-e:: + The message taken from file with `-F`, command line with + `-m`, and from file with `-C` are usually used as the + commit log message unmodified. This option lets you + further edit the message taken from these sources. + +<file>...:: + Update specified paths in the index file before committing. + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> and +Junio C Hamano <junkio@cox.net> + + +GIT +--- +Part of the gitlink:git[7] suite diff --git a/Documentation/git-convert-objects.txt b/Documentation/git-convert-objects.txt new file mode 100644 index 0000000000..6ce62dc672 --- /dev/null +++ b/Documentation/git-convert-objects.txt @@ -0,0 +1,30 @@ +git-convert-objects(1) +====================== +v0.1, May 2005 + +NAME +---- +git-convert-objects - Converts old-style GIT repository + + +SYNOPSIS +-------- +'git-convert-objects' + +DESCRIPTION +----------- +Converts old-style GIT repository to the latest format + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-count-objects.txt b/Documentation/git-count-objects.txt new file mode 100644 index 0000000000..36888d98bf --- /dev/null +++ b/Documentation/git-count-objects.txt @@ -0,0 +1,28 @@ +git-count-objects(1) +==================== + +NAME +---- +git-count-objects - Reports on unpacked objects. + +SYNOPSIS +-------- +'git-count-objects' + +DESCRIPTION +----------- +This counts the number of unpacked object files and disk space consumed by +them, to help you decide when it is a good time to repack. + +Author +------ +Written by Junio C Hamano <junkio@cox.net> + +Documentation +-------------- +Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-cvsimport.txt b/Documentation/git-cvsimport.txt new file mode 100644 index 0000000000..cd01994877 --- /dev/null +++ b/Documentation/git-cvsimport.txt @@ -0,0 +1,109 @@ +git-cvsimport(1) +================ +v0.1, July 2005 + +NAME +---- +git-cvsimport - Import a CVS repository into git + + +SYNOPSIS +-------- +'git-cvsimport' [ -o <branch-for-HEAD> ] [ -h ] [ -v ] + [ -d <CVSROOT> ] [ -p <options-for-cvsps> ] + [ -C <GIT_repository> ] [ -i ] [ -k ] + [ -s <subst> ] [ -m ] [ -M regex ] [ <CVS_module> ] + + +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 <CVSROOT>:: + 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 <target-dir>:: + 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. + +-u:: + Convert underscores in tag and branch names to dots. + +-o <branch-for-HEAD>:: + 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 <options-for-cvsps>:: + 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 <regex>:: + 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. + +<CVS_module>:: + The CVS module you want to import. Relative to <CVSROOT>. + +-h:: + Print a short usage message and exit. + +-z <fuzz>:: + Pass the timestamp fuzz factor to cvsps. + +-s <subst>:: + Substitute the character "/" in branch names with <subst> + +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 <smurf@smurf.noris.de>, with help from +various participants of the git-list <git@vger.kernel.org>. + +Documentation +-------------- +Documentation by Matthias Urlichs <smurf@smurf.noris.de>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-daemon.txt b/Documentation/git-daemon.txt new file mode 100644 index 0000000000..065f2aa721 --- /dev/null +++ b/Documentation/git-daemon.txt @@ -0,0 +1,53 @@ +git-daemon(1) +============= + +NAME +---- +git-daemon - A really simple server for GIT repositories. + +SYNOPSIS +-------- +'git-daemon' [--verbose] [--syslog] [--inetd | --port=n] + +DESCRIPTION +----------- +A really simple TCP git daemon that normally listens on port "DEFAULT_GIT_PORT" +aka 9418. It waits for a connection, and will just execute "git-upload-pack" +when it gets one. + +It's careful in that there's a magic request-line that gives the command and +what directory to upload, and it verifies that the directory is ok. + +It verifies that the directory has the magic file "git-daemon-export-ok", and +it will refuse to export any git directory that hasn't explicitly been marked +for export this way. + +This is ideally suited for read-only updates, ie pulling from git repositories. + +OPTIONS +------- +--inetd:: + Have the server run as an inetd service. + +--port:: + Listen on an alternative port. + +--syslog:: + Log to syslog instead of stderr. Note that this option does not imply + --verbose, thus by default only error conditions will be logged. + +--verbose:: + Log details about the incoming connections and requested files. + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> and YOSHIFUJI Hideaki <yoshfuji@linux-ipv6.org> + +Documentation +-------------- +Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-diff-files.txt b/Documentation/git-diff-files.txt new file mode 100644 index 0000000000..eb9fb74259 --- /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] [<common diff options>] [<path>...] + +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-index" 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 <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-diff-index.txt b/Documentation/git-diff-index.txt new file mode 100644 index 0000000000..56ed673eda --- /dev/null +++ b/Documentation/git-diff-index.txt @@ -0,0 +1,134 @@ +git-diff-index(1) +================= +v0.1, May 2005 + +NAME +---- +git-diff-index - Compares content and mode of blobs between the cache and repository + + +SYNOPSIS +-------- +'git-diff-index' [-m] [--cached] [<common diff options>] <tree-ish> [<path>...] + +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[] + +<tree-ish>:: + 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-index" 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-index --cached $(cat .git/HEAD) + +Example: let's say I had renamed `commit.c` to `git-commit.c`, and I had +done an "git-update-index" 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-index" does: + + torvalds@ppc970:~/git> git-diff-index --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-index --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-index --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-index" on it yet - there is no +"object" associated with the new state, and you get: + + torvalds@ppc970:~/v2.6/linux> git-diff-index $(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-index" 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 <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-diff-stages.txt b/Documentation/git-diff-stages.txt new file mode 100644 index 0000000000..276d7bdc43 --- /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' [<common diff options>] <stage1> <stage2> [<path>...] + +DESCRIPTION +----------- +Compares the content and mode of the blobs in two stages in an +unmerged index file. + +OPTIONS +------- +include::diff-options.txt[] + +<stage1>,<stage2>:: + The stage number to be compared. + +Output format +------------- +include::diff-format.txt[] + + +Author +------ +Written by Junio C Hamano <junkio@cox.net> + +Documentation +-------------- +Documentation by Junio C Hamano. + +GIT +--- +Part of the gitlink:git[7] suite diff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt new file mode 100644 index 0000000000..7f18bbfc60 --- /dev/null +++ b/Documentation/git-diff-tree.txt @@ -0,0 +1,133 @@ +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] [<common diff options>] <tree-ish> [<tree-ish>] [<path>...] + +DESCRIPTION +----------- +Compares the content and mode of the blobs found via two tree objects. + +If there is only one <tree-ish> given, the commit is compared with its parents +(see --stdin below). + +Note that "git-diff-tree" can use the tree encapsulated in a commit object. + +OPTIONS +------- +include::diff-options.txt[] + +<tree-ish>:: + The id of a tree object. + +<path>...:: + If provided, the results are limited to a subset of files + matching one of these prefix strings. + ie file matches `/^<pattern1>|<pattern2>|.../` + 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 + <tree-ish> arguments from the command line. Instead, it + reads either one <commit> or a pair of <tree-ish> + 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 <tree-ish> +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 "=<style>", it defaults to + medium. + + +Limiting Output +--------------- +If you're only interested in differences in a subset of files, for +example some architecture-specific files, you might do: + + git-diff-tree -r <tree-ish> <tree-ish> arch/ia64 include/asm-ia64 + +and it will only show you what changed in those two directories. + +Or if you are searching for what changed in just `kernel/sched.c`, just do + + git-diff-tree -r <tree-ish> <tree-ish> kernel/sched.c + +and it will ignore all differences to other files. + +The pattern is always the prefix, and is matched exactly. There are no +wildcards. Even stricter, it has to match a complete path component. +I.e. "foo" does not pick up `foobar.h`. "foo" does match `foo/bar.h` +so it can be used to name subdirectories. + +An example of normal usage is: + + torvalds@ppc970:~/git> git-diff-tree 5319e4...... + *100664->100664 blob ac348b.......->a01513....... git-fsck-objects.c + +which tells you that the last commit changed just one file (it's from +this one: + + commit 3c6f7ca19ad4043e9e72fa94106f352897e651a8 + tree 5319e4d609cdd282069cc4dce33c1db559539b03 + parent b4e628ea30d5ab3606119d2ea5caeab141d38df7 + author Linus Torvalds <torvalds@ppc970.osdl.org> Sat Apr 9 12:02:30 2005 + committer Linus Torvalds <torvalds@ppc970.osdl.org> Sat Apr 9 12:02:30 2005 + + Make "git-fsck-objects" print out all the root commits it finds. + + Once I do the reference tracking, I'll also make it print out all the + HEAD commits it finds, which is even more interesting. + +in case you care). + +Output format +------------- +include::diff-format.txt[] + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt new file mode 100644 index 0000000000..cadaf59455 --- /dev/null +++ b/Documentation/git-diff.txt @@ -0,0 +1,52 @@ +git-diff(1) +=========== + +NAME +---- +git-diff - Show changes between commits, commit and working tree, etc. + + +SYNOPSIS +-------- +'git-diff' [ --diff-options ] <ent>{0,2} [<path>...] + +DESCRIPTION +----------- +Show changes between two ents, an ent and the working tree, an +ent and the index file, or the index file and the working tree. +The combination of what is compared with what is determined by +the number of ents given to the command. + +`----------------`--------`-----------------------------`------------------ +Number of ents Options What's Compared Underlying command +--------------------------------------------------------------------------- +0 - index file and working tree git-diff-files +1 --cached ent and index file git-diff-index +1 - ent and working tree git-diff-index +2 - two ents git-diff-tree +--------------------------------------------------------------------------- + +OPTIONS +------- +--diff-options:: + '--diff-options' are passed to the `git-diff-files`, + `git-diff-index`, and `git-diff-tree` commands. See the + documentation for these commands for description. + +<path>...:: + The <path> arguments are also passed to `git-diff-\*` + commands. + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-fetch-pack.txt b/Documentation/git-fetch-pack.txt new file mode 100644 index 0000000000..1d281820cf --- /dev/null +++ b/Documentation/git-fetch-pack.txt @@ -0,0 +1,69 @@ +git-fetch-pack(1) +================= +v0.1, July 2005 + +NAME +---- +git-fetch-pack - Receive missing objects from another repository. + + +SYNOPSIS +-------- +git-fetch-pack [-q] [--exec=<git-upload-pack>] [<host>:]<directory> [<refs>...] + +DESCRIPTION +----------- +Invokes 'git-upload-pack' on a potentially remote repository, +and asks it to send objects missing from this repository, to +update the named heads. The list of commits available locally +is found out by scanning local $GIT_DIR/refs/ and sent to +'git-upload-pack' running on the other end. + +This command degenerates to download everything to complete the +asked refs from the remote side when the local side does not +have a common ancestor commit. + + +OPTIONS +------- +-q:: + Pass '-q' flag to 'git-unpack-objects'; this makes the + cloning process less verbose. + +--exec=<git-upload-pack>:: + 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). + +<host>:: + A remote host that houses the repository. When this + part is specified, 'git-upload-pack' is invoked via + ssh. + +<directory>:: + The repository to sync from. + +<refs>...:: + The remote heads to update from. This is relative to + $GIT_DIR (e.g. "HEAD", "refs/heads/master"). When + unspecified, update from all heads the remote side has. + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by Junio C Hamano. + +GIT +--- +Part of the gitlink:git[7] suite diff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt new file mode 100644 index 0000000000..0906510002 --- /dev/null +++ b/Documentation/git-fetch.txt @@ -0,0 +1,47 @@ +git-fetch(1) +============ +v0.99.5, Aug 2005 + +NAME +---- +git-fetch - Download objects and a head from another repository. + + +SYNOPSIS +-------- +'git-fetch' <repository> <refspec>... + + +DESCRIPTION +----------- +Fetches named heads or tags from another repository, along with +the objects necessary to complete them. + +The ref names and their object names of fetched refs are stored +in $GIT_DIR/FETCH_HEAD. This information is left for a later merge +operation done by "git resolve" or "git octopus". + + +OPTIONS +------- +include::pull-fetch-param.txt[] + +-u, \--update-head-ok:: + By default 'git-fetch' refuses to update the head which + corresponds to the current branch. This flag disables the + check. Note that fetching into the current branch will not + update the index and working directory, so use it with care. + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> and +Junio C Hamano <junkio@cox.net> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt new file mode 100644 index 0000000000..a1483ffd0f --- /dev/null +++ b/Documentation/git-format-patch.txt @@ -0,0 +1,69 @@ +git-format-patch(1) +=================== + +NAME +---- +git-format-patch - Prepare patches for e-mail submission. + + +SYNOPSIS +-------- +'git-format-patch' [-n][-o <dir>][-k][--mbox][--diff-options] <his> [<mine>] + +DESCRIPTION +----------- +Prepare each commit with its patch since <mine> head forked from +<his> head, one file per patch, for e-mail submission. Each +output file is numbered sequentially from 1, and uses the first +line of the commit message (massaged for pathname safety) as the +filename. + +When -o is specified, output files are created in that +directory; otherwise in the current working directory. + +When -n is specified, instead of "[PATCH] Subject", the first +line is formatted as "[PATCH N/M] Subject", unless you have only +one patch. + +When --mbox is specified, the output is formatted to resemble +UNIX mailbox format, and can be concatenated together for +processing with applymbox. + + +OPTIONS +------- +-o <dir>:: + Use <dir> to store the resulting files, instead of the + current working directory. + +-n:: + Name output in '[PATCH n/m]' format. + +-k:: + Do not strip/add '[PATCH]' from the first line of the + commit log message. + +--author, --date:: + Output From: and Date: headers for commits made by + yourself as well. Usually these are output only for + commits made by people other than yourself. + +--mbox:: + Format the output files for closer to mbox format by + adding a phony Unix "From " line, so they can be + concatenated together and fed to `git-applymbox`. + Implies --author and --date. + + +Author +------ +Written by Junio C Hamano <junkio@cox.net> + +Documentation +-------------- +Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-fsck-objects.txt b/Documentation/git-fsck-objects.txt new file mode 100644 index 0000000000..715defd2f6 --- /dev/null +++ b/Documentation/git-fsck-objects.txt @@ -0,0 +1,145 @@ +git-fsck-objects(1) +=================== +v0.1, May 2005 + +NAME +---- +git-fsck-objects - Verifies the connectivity and validity of the objects in the database + + +SYNOPSIS +-------- +'git-fsck-objects' [--tags] [--root] [--unreachable] [--cache] [--standalone | --full] [--strict] [<object>*] + +DESCRIPTION +----------- +Verifies the connectivity and validity of the objects in the database. + +OPTIONS +------- +<object>:: + An object to treat as the head of an unreachability trace. + + If no objects are given, git-fsck-objects defaults to using the + index file and all SHA1 references in .git/refs/* as heads. + +--unreachable:: + Print out objects that exist but that aren't readable from any + of the reference nodes. + +--root:: + Report root nodes. + +--tags:: + Report tags. + +--cache:: + Consider any object recorded in the cache also as a head node for + an unreachability trace. + +--standalone:: + Limit checks to the contents of GIT_OBJECT_DIRECTORY + ($GIT_DIR/objects), making sure that it is consistent and + complete without referring to objects found in alternate + object pools listed in GIT_ALTERNATE_OBJECT_DIRECTORIES, + nor packed GIT archives found in $GIT_DIR/objects/pack; + cannot be used with --full. + +--full:: + Check not just objects in GIT_OBJECT_DIRECTORY + ($GIT_DIR/objects), but also the ones found in alternate + object pools listed in GIT_ALTERNATE_OBJECT_DIRECTORIES, + and in packed GIT archives found in $GIT_DIR/objects/pack + and corresponding pack subdirectories in alternate + object pools; cannot be used with --standalone. + +--strict:: + Enable more strict checking, namely to catch a file mode + recorded with g+w bit set, which was created by older + versions of GIT. Existing repositories, including the + Linux kernel, GIT itself, and sparse repository have old + objects that triggers this check, but it is recommended + to check new projects with this flag. + +It tests SHA1 and general object sanity, and it does full tracking of +the resulting reachability and everything else. It prints out any +corruption it finds (missing or bad objects), and if you use the +'--unreachable' flag it will also print out objects that exist but +that aren't readable from any of the specified head nodes. + +So for example + + git-fsck-objects --unreachable $(cat .git/HEAD .git/refs/heads/*) + +will do quite a _lot_ of verification on the tree. There are a few +extra validity tests to be added (make sure that tree objects are +sorted properly etc), but on the whole if "git-fsck-objects" is happy, you +do have a valid tree. + +Any corrupt objects you will have to find in backups or other archives +(ie you can just remove them and do an "rsync" with some other site in +the hopes that somebody else has the object you have corrupted). + +Of course, "valid tree" doesn't mean that it wasn't generated by some +evil person, and the end result might be crap. Git is a revision +tracking system, not a quality assurance system ;) + +Extracted Diagnostics +--------------------- + +expect dangling commits - potential heads - due to lack of head information:: + You haven't specified any nodes as heads so it won't be + possible to differentiate between un-parented commits and + root nodes. + +missing sha1 directory '<dir>':: + The directory holding the sha1 objects is missing. + +unreachable <type> <object>:: + The <type> object <object>, isn't actually referred to directly + or indirectly in any of the trees or commits seen. This can + mean that there's another root node that you're not specifying + or that the tree is corrupt. If you haven't missed a root node + then you might as well delete unreachable nodes since they + can't be used. + +missing <type> <object>:: + The <type> object <object>, is referred to but isn't present in + the database. + +dangling <type> <object>:: + The <type> object <object>, is present in the database but never + 'directly' used. A dangling commit could be a root node. + +warning: git-fsck-objects: tree <tree> has full pathnames in it:: + And it shouldn't... + +sha1 mismatch <object>:: + The database has an object who's sha1 doesn't match the + database value. + This indicates a serious data integrity problem. + +Environment Variables +--------------------- + +GIT_OBJECT_DIRECTORY:: + used to specify the object database root (usually $GIT_DIR/objects) + +GIT_INDEX_FILE:: + used to specify the index file of the cache + +GIT_ALTERNATE_OBJECT_DIRECTORIES: + used to specify additional object database roots (usually unset) + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-get-tar-commit-id.txt b/Documentation/git-get-tar-commit-id.txt new file mode 100644 index 0000000000..30b1fbf6e7 --- /dev/null +++ b/Documentation/git-get-tar-commit-id.txt @@ -0,0 +1,37 @@ +git-get-tar-commit-id(1) +======================== + +NAME +---- +git-get-tar-commit-id - Extract commit ID from an archive created using git-tar-tree. + + +SYNOPSIS +-------- +'git-get-tar-commit-id' < <tarfile> + + +DESCRIPTION +----------- +Acts as a filter, extracting the commit ID stored in archives created by +git-tar-tree. It reads only the first 1024 bytes of input, thus its +runtime is not influenced by the size of <tarfile> very much. + +If no commit ID is found, git-get-tar-commit-id quietly exists with a +return code of 1. This can happen if <tarfile> had not been created +using git-tar-tree or if the first parameter of git-tar-tree had been +a tree ID instead of a commit ID or tag. + + +Author +------ +Written by Rene Scharfe <rene.scharfe@lsrfire.ath.cx> + +Documentation +-------------- +Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt new file mode 100644 index 0000000000..5f082167c1 --- /dev/null +++ b/Documentation/git-grep.txt @@ -0,0 +1,47 @@ +git-grep(1) +=========== +v0.99.6, Sep 2005 + +NAME +---- +git-grep - print lines matching a pattern + + +SYNOPSIS +-------- +'git-grep' <option>... <pattern> <path>... + +DESCRIPTION +----------- +Searches list of files `git-ls-files` produces for lines +containing a match to the given pattern. + + +OPTIONS +------- +<option>...:: + Either an option to pass to `grep` or `git-ls-files`. + Some `grep` options, such as `-C` and `-m`, that take + parameters are known to `git-grep`. + +<pattern>:: + The pattern to look for. + +<path>...:: + + Optional paths to limit the set of files to be searched; + passed to `git-ls-files`. + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-hash-object.txt b/Documentation/git-hash-object.txt new file mode 100644 index 0000000000..935cc66b38 --- /dev/null +++ b/Documentation/git-hash-object.txt @@ -0,0 +1,44 @@ +git-hash-object(1) +================== +v0.1, May 2005 + +NAME +---- +git-hash-object - Computes object ID and optionally creates a blob from a file. + + +SYNOPSIS +-------- +'git-hash-object' [-t <type>] [-w] <any-file-on-the-filesystem> + +DESCRIPTION +----------- +Computes the object ID value for an object with specified type +with the contents of the named file (which can be outside of the +work tree), and optionally writes the resulting object into the +object database. Reports its object ID to its standard output. +This is used by "git-cvsimport" to update the cache +without modifying files in the work tree. When <type> is not +specified, it defaults to "blob". + +OPTIONS +------- + +-t <type>:: + Specify the type (default: "blob"). + +-w:: + Actually write the object into the object database. + +Author +------ +Written by Junio C Hamano <junkio@cox.net> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-http-fetch.txt b/Documentation/git-http-fetch.txt new file mode 100644 index 0000000000..c034272568 --- /dev/null +++ b/Documentation/git-http-fetch.txt @@ -0,0 +1,42 @@ +git-http-fetch(1) +================= +v0.1, May 2005 + +NAME +---- +git-http-fetch - Downloads a remote GIT repository via HTTP + + +SYNOPSIS +-------- +'git-http-fetch' [-c] [-t] [-a] [-d] [-v] [-w filename] [--recover] commit-id url + +DESCRIPTION +----------- +Downloads a remote GIT repository via HTTP. + +-c:: + Get the commit objects. +-t:: + Get trees associated with the commit objects. +-a:: + Get all the objects. +-v:: + Report what is downloaded. + +-w <filename>:: + Writes the commit-id into the filename under $GIT_DIR/refs/<filename> on + the local end after the transfer is complete. + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-init-db.txt b/Documentation/git-init-db.txt new file mode 100644 index 0000000000..ef2d04a612 --- /dev/null +++ b/Documentation/git-init-db.txt @@ -0,0 +1,41 @@ +git-init-db(1) +============== +v0.1, May 2005 + +NAME +---- +git-init-db - Creates an empty git repository + + +SYNOPSIS +-------- +'git-init-db' + +DESCRIPTION +----------- +This simply creates an empty git repository - basically a `.git` directory +and `.git/object/??/`, `.git/refs/heads` and `.git/refs/tags` directories, +and links `.git/HEAD` symbolically to `.git/refs/heads/master`. + +If the 'GIT_DIR' environment variable is set then it specifies a path +to use instead of `./.git` for the base of the repository. + +If the object storage directory is specified via the 'GIT_OBJECT_DIRECTORY' +environment variable then the sha1 directories are created underneath - +otherwise the default `$GIT_DIR/objects` directory is used. + +"git-init-db" won't hurt an existing repository. + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-local-fetch.txt b/Documentation/git-local-fetch.txt new file mode 100644 index 0000000000..ccf9735924 --- /dev/null +++ b/Documentation/git-local-fetch.txt @@ -0,0 +1,44 @@ +git-local-fetch(1) +================== +v0.1, May 2005 + +NAME +---- +git-local-fetch - Duplicates another GIT repository on a local system + + +SYNOPSIS +-------- +'git-local-fetch' [-c] [-t] [-a] [-d] [-v] [-w filename] [--recover] [-l] [-s] [-n] commit-id path + +DESCRIPTION +----------- +Duplicates another GIT repository on a local system. + +OPTIONS +------- +-c:: + Get the commit objects. +-t:: + Get trees associated with the commit objects. +-a:: + Get all the objects. +-v:: + Report what is downloaded. + +-w <filename>:: + Writes the commit-id into the filename under $GIT_DIR/refs/<filename> on + the local end after the transfer is complete. + +Author +------ +Written by Junio C Hamano <junkio@cox.net> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt new file mode 100644 index 0000000000..2a0e5aceab --- /dev/null +++ b/Documentation/git-log.txt @@ -0,0 +1,45 @@ +git-log(1) +========== +v0.99.4, Aug 2005 + +NAME +---- +git-log - Show commit logs + + +SYNOPSIS +-------- +'git log' <option>... + +DESCRIPTION +----------- +Shows the commit logs. This command internally invokes +'git-rev-list', and the command line options are passed to that +command. + +This manual page describes only the most frequently used options. + +OPTIONS +------- +--pretty=<format>: + Controls the way the commit log is formatted. + +--max-count=<n>:: + Limits the number of commits to show. + +<since>..<until>:: + Show only commits between the named two commits. + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt new file mode 100644 index 0000000000..591f4ed462 --- /dev/null +++ b/Documentation/git-ls-files.txt @@ -0,0 +1,200 @@ +git-ls-files(1) +=============== + +NAME +---- +git-ls-files - Information about files in the cache/working directory + + +SYNOPSIS +-------- +'git-ls-files' [-z] [-t] + (--[cached|deleted|others|ignored|stage|unmerged|killed|modified])\* + (-[c|d|o|i|s|u|k|m])\* + [-x <pattern>|--exclude=<pattern>] + [-X <file>|--exclude-from=<file>] + [--exclude-per-directory=<file>] + +DESCRIPTION +----------- +This merges the file listing in the directory cache index with the +actual working directory list, and shows different combinations of the +two. + +One or more of the options below may be used to determine the files +shown: + +OPTIONS +------- +-c|--cached:: + Show cached files in the output (default) + +-d|--deleted:: + Show deleted files in the output + +-m|--modified:: + Show modified files in the output + +-o|--others:: + Show other files in the output + +-i|--ignored:: + Show ignored files in the output + Note the this also reverses any exclude list present. + +-s|--stage:: + Show stage files in the output + +-u|--unmerged:: + Show unmerged files in the output (forces --stage) + +-k|--killed:: + Show files on the filesystem that need to be removed due + to file/directory conflicts for checkout-cache to + succeed. + +-z:: + \0 line termination on output + +-x|--exclude=<pattern>:: + Skips files matching pattern. + Note that pattern is a shell wildcard pattern. + +-X|--exclude-from=<file>:: + exclude patterns are read from <file>; 1 per line. + +--exclude-per-directory=<file>:: + read additional exclude patterns that apply only to the + directory and its subdirectories in <file>. + +-t:: + Identify the file status with the following tags (followed by + a space) at the start of each line: + H cached + M unmerged + R removed/deleted + C modifed/changed + K to be killed + ? other + +Output +------ +show files just outputs the filename unless '--stage' is specified in +which case it outputs: + + [<tag> ]<mode> <object> <stage> <file> + +"git-ls-files --unmerged" and "git-ls-files --stage" can be used to examine +detailed information on unmerged paths. + +For an unmerged path, instead of recording a single mode/SHA1 pair, +the dircache records up to three such pairs; one from tree O in stage +1, A in stage 2, and B in stage 3. This information can be used by +the user (or the porcelain) to see what should eventually be recorded at the +path. (see git-read-tree for more information on state) + + +Exclude Patterns +---------------- + +'git-ls-files' can use a list of "exclude patterns" when +traversing the directory tree and finding files to show when the +flags --others or --ignored are specified. + +These exclude patterns come from these places: + + (1) command line flag --exclude=<pattern> specifies a single + pattern. + + (2) command line flag --exclude-from=<file> specifies a list of + patterns stored in a file. + + (3) command line flag --exclude-per-directory=<name> specifies + a name of the file in each directory 'git-ls-files' + examines, and if exists, its contents are used as an + additional list of patterns. + +An exclude pattern file used by (2) and (3) contains one pattern +per line. A line that starts with a '#' can be used as comment +for readability. + +There are three lists of patterns that are in effect at a given +time. They are built and ordered in the following way: + + * --exclude=<pattern> from the command line; patterns are + ordered in the same order as they appear on the command line. + + * lines read from --exclude-from=<file>; patterns are ordered + in the same order as they appear in the file. + + * When --exclude-per-directory=<name> is specified, upon + entering a directory that has such a file, its contents are + appended at the end of the current "list of patterns". They + are popped off when leaving the directory. + +Each pattern in the pattern list specifies "a match pattern" and +optionally the fate; either a file that matches the pattern is +considered excluded or included. A filename is matched against +the patterns in the three lists; the --exclude-from list is +checked first, then the --exclude-per-directory list, and then +finally the --exclude list. The last match determines its fate. +If there is no match in the three lists, the fate is "included". + +A pattern specified on the command line with --exclude or read +from the file specified with --exclude-from is relative to the +top of the directory tree. A pattern read from a file specified +by --exclude-per-directory is relative to the directory that the +pattern file appears in. + +An exclude pattern is of the following format: + + - an optional prefix '!' which means that the fate this pattern + specifies is "include", not the usual "exclude"; the + remainder of the pattern string is interpreted according to + the following rules. + + - if it does not contain a slash '/', it is a shell glob + pattern and used to match against the filename without + leading directories (i.e. the same way as the current + implementation). + + - otherwise, it is a shell glob pattern, suitable for + consumption by fnmatch(3) with FNM_PATHNAME flag. I.e. a + slash in the pattern must match a slash in the pathname. + "Documentation/*.html" matches "Documentation/git.html" but + not "ppc/ppc.html". As a natural exception, "/*.c" matches + "cat-file.c" but not "mozilla-sha1/sha1.c". + +An example: + + $ cat .git/ignore + # ignore objects and archives, anywhere in the tree. + *.[oa] + $ cat Documentation/.gitignore + # ignore generated html files, + *.html + # except foo.html which is maintained by hand + !foo.html + $ git-ls-files --ignored \ + --exclude='Documentation/*.[0-9]' \ + --exclude-from=.git/ignore \ + --exclude-per-directory=.gitignore + + +See Also +-------- +gitlink:git-read-tree[1] + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-ls-remote.txt b/Documentation/git-ls-remote.txt new file mode 100644 index 0000000000..89bd609d65 --- /dev/null +++ b/Documentation/git-ls-remote.txt @@ -0,0 +1,64 @@ +git-ls-remote(1) +================ +v0.1, May 2005 + +NAME +---- +git-ls-remote - Look at references other repository has. + + +SYNOPSIS +-------- +'git-ls-remote' [--heads] [--tags] <repository> <refs>... + +DESCRIPTION +----------- +Displays the references other repository has. + + +OPTIONS +------- +--heads --tags:: + Limit to only refs/heads and refs/tags, respectively. + These options are _not_ mutually exclusive; when given + both, references stored in refs/heads and refs/tags are + displayed. + +<repository>:: + Location of the repository. The shorthand defined in + $GIT_DIR/branches/ can be used. + +<refs>...:: + When unspecified, all references, after filtering done + with --heads and --tags, are shown. When <refs>... are + specified, only references matching the given patterns + are displayed. + +EXAMPLES +-------- + + $ git ls-remote --tags ./. + d6602ec5194c87b0fc87103ca4d67251c76f233a refs/tags/v0.99 + f25a265a342aed6041ab0cc484224d9ca54b6f41 refs/tags/v0.99.1 + 7ceca275d047c90c0c7d5afb13ab97efdf51bd6e refs/tags/v0.99.3 + c5db5456ae3b0873fc659c19fafdde22313cc441 refs/tags/v0.99.2 + 0918385dbd9656cab0d1d81ba7453d49bbc16250 refs/tags/junio-gpg-pub + $ git ls-remote http://www.kernel.org/pub/scm/git/git.git master pu rc + 5fe978a5381f1fbad26a80e682ddd2a401966740 refs/heads/master + c781a84b5204fb294c9ccc79f8b3baceeb32c061 refs/heads/pu + b1d096f2926c4e37c9c0b6a7bf2119bedaa277cb refs/heads/rc + $ echo http://www.kernel.org/pub/scm/git/git.git >.git/branches/public + $ git ls-remote --tags public v\* + d6602ec5194c87b0fc87103ca4d67251c76f233a refs/tags/v0.99 + f25a265a342aed6041ab0cc484224d9ca54b6f41 refs/tags/v0.99.1 + c5db5456ae3b0873fc659c19fafdde22313cc441 refs/tags/v0.99.2 + 7ceca275d047c90c0c7d5afb13ab97efdf51bd6e refs/tags/v0.99.3 + +Author +------ +Written by Junio C Hamano <junkio@cox.net> + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt new file mode 100644 index 0000000000..0d159fd5cc --- /dev/null +++ b/Documentation/git-ls-tree.txt @@ -0,0 +1,55 @@ +git-ls-tree(1) +============== +v0.1, May 2005 + +NAME +---- +git-ls-tree - Lists the contents of a tree object. + + +SYNOPSIS +-------- +'git-ls-tree' [-d] [-r] [-z] <tree-ish> [paths...] + +DESCRIPTION +----------- +Lists the contents of a tree object, like what "/bin/ls -a" does +in the current working directory. + +OPTIONS +------- +<tree-ish>:: + Id of a tree-ish. + +-d:: + show only the named tree entry itself, not its children + +-r:: + recurse into sub-trees + +-z:: + \0 line termination on output + +paths:: + When paths are given, show them. Otherwise implicitly + uses the root level of the tree as the sole path argument. + + +Output Format +------------- + <mode> SP <type> SP <object> TAB <file> + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> +Completely rewritten from scratch by Junio C Hamano <junkio@cox.net> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-mailinfo.txt b/Documentation/git-mailinfo.txt new file mode 100644 index 0000000000..dc7d725ea1 --- /dev/null +++ b/Documentation/git-mailinfo.txt @@ -0,0 +1,65 @@ +git-mailinfo(1) +=============== + +NAME +---- +git-mailinfo - Extracts patch from a single e-mail message. + + +SYNOPSIS +-------- +'git-mailinfo' [-k] [-u] <msg> <patch> + + +DESCRIPTION +----------- +Reading a single e-mail message from the standard input, and +writes the commit log message in <msg> file, and the patches in +<patch> file. The author name, e-mail and e-mail subject are +written out to the standard output to be used by git-applypatch +to create a commit. It is usually not necessary to use this +command directly. + + +OPTIONS +------- +-k:: + Usually the program 'cleans up' the Subject: header line + to extract the title line for the commit log message, + among which (1) remove 'Re:' or 're:', (2) leading + whitespaces, (3) '[' up to ']', typically '[PATCH]', and + then prepends "[PATCH] ". This flag forbids this + munging, and is most useful when used to read back 'git + format-patch --mbox' output. + +-u:: + By default, the commit log message, author name and + author email are taken from the e-mail without any + charset conversion, after minimally decoding MIME + transfer encoding. This flag causes the resulting + commit to be encoded in utf-8 by transliterating them. + Note that the patch is always used as is without charset + conversion, even with this flag. + +<msg>:: + The commit log message extracted from e-mail, usually + except the title line which comes from e-mail Subject. + +<patch>:: + The patch extracted from e-mail. + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> and +Junio C Hamano <junkio@cox.net> + + +Documentation +-------------- +Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-mailsplit.txt b/Documentation/git-mailsplit.txt new file mode 100644 index 0000000000..557d2e9056 --- /dev/null +++ b/Documentation/git-mailsplit.txt @@ -0,0 +1,36 @@ +git-mailsplit(1) +================ + +NAME +---- +git-mailsplit - Totally braindamaged mbox splitter program. + +SYNOPSIS +-------- +'git-mailsplit' <mbox> <directory> + +DESCRIPTION +----------- +Splits a mbox file into a list of files: "0001" "0002" .. in the specified +directory so you can process them further from there. + +OPTIONS +------- +<mbox>:: + Mbox file to split. + +<directory>:: + Directory in which to place the individual messages. + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-merge-base.txt b/Documentation/git-merge-base.txt new file mode 100644 index 0000000000..e4692163ea --- /dev/null +++ b/Documentation/git-merge-base.txt @@ -0,0 +1,34 @@ +git-merge-base(1) +================= +v0.1, May 2005 + +NAME +---- +git-merge-base - Finds as good a common ancestor as possible for a merge + + +SYNOPSIS +-------- +'git-merge-base' <commit> <commit> + +DESCRIPTION +----------- +"git-merge-base" finds as good a common ancestor as possible. Given a +selection of equally good common ancestors it should not be relied on +to decide in any particular way. + +The "git-merge-base" algorithm is still in flux - use the source... + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-merge-index.txt b/Documentation/git-merge-index.txt new file mode 100644 index 0000000000..5caee90adc --- /dev/null +++ b/Documentation/git-merge-index.txt @@ -0,0 +1,89 @@ +git-merge-index(1) +================== +v0.1, May 2005 + +NAME +---- +git-merge-index - Runs a merge for files needing merging + + +SYNOPSIS +-------- +'git-merge-index' [-o] [-q] <merge-program> (-a | -- | <file>\*) + +DESCRIPTION +----------- +This looks up the <file>(s) in the cache and, if there are any merge +entries, passes the SHA1 hash for those files as arguments 1, 2, 3 (empty +argument if no file), and <file> as argument 4. File modes for the three +files are passed as arguments 5, 6 and 7. + +OPTIONS +------- +--:: + Interpret all following arguments as filenames. + +-a:: + Run merge against all files in the cache that need merging. + +-o:: + Instead of stopping at the first failed merge, do all of them + in one shot - continue with merging even when previous merges + returned errors, and only return the error code after all the + merges are over. + +-q:: + Do not complain about failed merge program (the merge program + failure usually indicates conflicts during merge). This is for + porcelains which might want to emit custom messages. + +If "git-merge-index" is called with multiple <file>s (or -a) then it +processes them in turn only stopping if merge returns a non-zero exit +code. + +Typically this is run with the a script calling the merge command from +the RCS package. + +A sample script called "git-merge-one-file" is included in the +distribution. + +ALERT ALERT ALERT! The git "merge object order" is different from the +RCS "merge" program merge object order. In the above ordering, the +original is first. But the argument order to the 3-way merge program +"merge" is to have the original in the middle. Don't ask me why. + +Examples: + + torvalds@ppc970:~/merge-test> git-merge-index cat MM + This is MM from the original tree. # original + This is modified MM in the branch A. # merge1 + This is modified MM in the branch B. # merge2 + This is modified MM in the branch B. # current contents + +or + + torvalds@ppc970:~/merge-test> git-merge-index cat AA MM + cat: : No such file or directory + This is added AA in the branch A. + This is added AA in the branch B. + This is added AA in the branch B. + fatal: merge program failed + +where the latter example shows how "git-merge-index" will stop trying to +merge once anything has returned an error (ie "cat" returned an error +for the AA file, because it didn't exist in the original, and thus +"git-merge-index" didn't even try to merge the MM thing). + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> +One-shot merge by Petr Baudis <pasky@ucw.cz> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-merge-one-file.txt b/Documentation/git-merge-one-file.txt new file mode 100644 index 0000000000..712739777b --- /dev/null +++ b/Documentation/git-merge-one-file.txt @@ -0,0 +1,31 @@ +git-merge-one-file(1) +===================== +v0.99.4, Aug 2005 + +NAME +---- +git-merge-one-file - The standard helper program to use with "git-merge-index" + + +SYNOPSIS +-------- +'git-merge-one-file' + +DESCRIPTION +----------- +This is the standard helper program to use with "git-merge-index" +to resolve a merge after the trivial merge done with "git-read-tree -m". + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org>, +Junio C Hamano <junkio@cox.net> and Petr Baudis <pasky@suse.cz>. + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt new file mode 100644 index 0000000000..dca363dd5e --- /dev/null +++ b/Documentation/git-merge.txt @@ -0,0 +1,52 @@ +git-merge(1) +============ +v0.99.6, Sep 2005 + +NAME +---- +git-merge - Grand Unified Merge Driver + + +SYNOPSIS +-------- +'git-merge' [-n] [-s <strategy>]... <msg> <head> <remote> <remote>... + + +DESCRIPTION +----------- +This is the top-level user interface to the merge machinery +which drives multiple merge strategy scripts. + + +OPTIONS +------- +-n:: + Do not show diffstat at the end of the merge. + +-s <strategy>:: + use that merge strategy; can be given more than once to + specify them in the order they should be tried. If + there is no `-s` option, built-in list of strategies is + used instead. + +<head>:: + our branch head commit. + +<remote>:: + other branch head merged into our branch. You need at + least one <remote>. Specifying more than one <remote> + obviously means you are trying an Octopus. + + +Author +------ +Written by Junio C Hamano <junkio@cox.net> + + +Documentation +-------------- +Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite diff --git a/Documentation/git-mktag.txt b/Documentation/git-mktag.txt new file mode 100644 index 0000000000..44ed4b5408 --- /dev/null +++ b/Documentation/git-mktag.txt @@ -0,0 +1,48 @@ +git-mktag(1) +============ +v0.1, May 2005 + +NAME +---- +git-mktag - Creates a tag object + + +SYNOPSIS +-------- +'git-mktag' < signature_file + +DESCRIPTION +----------- +Reads a tag contents on standard input and creates a tag object +that can also be used to sign other objects. + +The output is the new tag's <object> identifier. + +Tag Format +---------- +A tag signature file has a very simple fixed format: three lines of + + object <sha1> + type <typename> + tag <tagname> + +followed by some 'optional' free-form signature that git itself +doesn't care about, but that can be verified with gpg or similar. + +The size of the full object is artificially limited to 8kB. (Just +because I'm a lazy bastard, and if you can't fit a signature in that +size, you're doing something wrong) + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-octopus.txt b/Documentation/git-octopus.txt new file mode 100644 index 0000000000..881c317ac5 --- /dev/null +++ b/Documentation/git-octopus.txt @@ -0,0 +1,39 @@ +git-octopus(1) +============== +v0.99.5, Aug 2005 + +NAME +---- +git-octopus - Merge more than two commits. + + +SYNOPSIS +-------- +'git-octopus' + +DESCRIPTION +----------- +After running 'git fetch', $GIT_DIR/FETCH_HEAD contains the +following information, one line per remote ref: + +------------------------------------------------ +<object name> <ref name> from <repository> +------------------------------------------------ + +Using this information, create and commit an Octopus merge on +top of the current HEAD. + + +Author +------ +Written by Junio C Hamano <junkio@cox.net> + + +Documentation +-------------- +Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt new file mode 100644 index 0000000000..970150a128 --- /dev/null +++ b/Documentation/git-pack-objects.txt @@ -0,0 +1,84 @@ +git-pack-objects(1) +=================== +v0.1, July 2005 + +NAME +---- +git-pack-objects - Create a packed archive of objects. + + +SYNOPSIS +-------- +'git-pack-objects' [--incremental] [--window=N] [--depth=N] {--stdout | base-name} < object-list + + +DESCRIPTION +----------- +Reads list of objects from the standard input, and writes a packed +archive with specified base-name, or to the standard output. + +A packed archive is an efficient way to transfer set of objects +between two repositories, and also is an archival format which +is efficient to access. The packed archive format (.pack) is +designed to be unpackable without having anything else, but for +random access, accompanied with the pack index file (.idx). + +'git-unpack-objects' command can read the packed archive and +expand the objects contained in the pack into "one-file +one-object" format; this is typically done by the smart-pull +commands when a pack is created on-the-fly for efficient network +transport by their peers. + +Placing both in the pack/ subdirectory of $GIT_OBJECT_DIRECTORY (or +any of the directories on $GIT_ALTERNATE_OBJECT_DIRECTORIES) +enables GIT to read from such an archive. + + +OPTIONS +------- +base-name:: + Write into a pair of files (.pack and .idx), using + <base-name> to determine the name of the created file. + When this option is used, the two files are written in + <base-name>-<SHA1>.{pack,idx} files. <SHA1> is a hash + of object names (currently in random order so it does + not have any useful meaning) to make the resulting + filename reasonably unique, and written to the standard + output of the command. + +--stdout:: + Write the pack contents (what would have been writtin to + .pack file) out to the standard output. + +--window and --depth:: + These two options affects how the objects contained in + the pack are stored using delta compression. The + objects are first internally sorted by type, size and + optionally names and compared against the other objects + within --window to see if using delta compression saves + space. --depth limits the maximum delta depth; making + it too deep affects the performance on the unpacker + side, because delta data needs to be applied that many + times to get to the necessary object. + +--incremental:: + This flag causes an object already in a pack ignored + even if it appears in the standard input. + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +------------- +Documentation by Junio C Hamano + +See-Also +-------- +git-repack(1) git-prune-packed(1) + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-parse-remote.txt b/Documentation/git-parse-remote.txt new file mode 100644 index 0000000000..fc27afe26d --- /dev/null +++ b/Documentation/git-parse-remote.txt @@ -0,0 +1,48 @@ +git-parse-remote(1) +=================== + +NAME +---- +git-parse-remote - Routines to help parsing $GIT_DIR/remotes/ + + +SYNOPSIS +-------- +'. git-parse-remote' + +DESCRIPTION +----------- +This script is included in various scripts to supply +routines to parse files under $GIT_DIR/remotes/ and +$GIT_DIR/branches/. + +The primary entry points are: + +get_remote_refs_for_fetch:: + Given the list of user-supplied `<repo> <refspec>...`, + return the list of refs to fetch after canonicalizing + them into `$GIT_DIR` relative paths + (e.g. `refs/heads/foo`). When `<refspec>...` is empty + the returned list of refs consists of the defaults + for the given `<repo>`, if specified in + `$GIT_DIR/remotes/` or `$GIT_DIR/branches/`. + +get_remote_refs_for_push:: + Given the list of user-supplied `<repo> <refspec>...`, + return the list of refs to push in a form suitable to be + fed to the `git-send-pack` command. When `<refspec>...` + is empty the returned list of refs consists of the + defaults for the given `<repo>`, if specified in + `$GIT_DIR/remotes/`. + +Author +------ +Written by Junio C Hamano. + +Documentation +-------------- +Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite diff --git a/Documentation/git-patch-id.txt b/Documentation/git-patch-id.txt new file mode 100644 index 0000000000..3e560a37e8 --- /dev/null +++ b/Documentation/git-patch-id.txt @@ -0,0 +1,37 @@ +git-patch-id(1) +=============== + +NAME +---- +git-patch-id - Generate a patch ID. + +SYNOPSIS +-------- +'git-patch-id' < <patch> + +DESCRIPTION +----------- +A "patch ID" is nothing but a SHA1 of the diff associated with a patch, with +whitespace and line numbers ignored. As such, it's "reasonably stable", but at +the same time also reasonably unique, ie two patches that have the same "patch +ID" are almost guaranteed to be the same thing. + +IOW, you can use this thing to look for likely duplicate commits. + +OPTIONS +------- +<patch>:: + The diff to create the ID of. + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-peek-remote.txt b/Documentation/git-peek-remote.txt new file mode 100644 index 0000000000..c1527f1bcf --- /dev/null +++ b/Documentation/git-peek-remote.txt @@ -0,0 +1,53 @@ +git-peek-remote(1) +================== +v0.1, July 2005 + +NAME +---- +git-peek-remote - Lists the references in a remote repository. + + +SYNOPSIS +-------- +'git-peek-remote' [--exec=<git-upload-pack>] [<host>:]<directory> + +DESCRIPTION +----------- +Lists the references the remote repository has, and optionally +stores them in the local repository under the same name. + +OPTIONS +------- +--exec=<git-upload-pack>:: + Use this to specify the path to 'git-upload-pack' on the + remote side, if it is not found on your $PATH. Some + 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, but prefer having a lean .bashrc file (they set most of + the things up in .bash_profile). + +<host>:: + A remote host that houses the repository. When this + part is specified, 'git-upload-pack' is invoked via + ssh. + +<directory>:: + The repository to sync from. + + +Author +------ +Written by Junio C Hamano <junkio@cox.net> + +Documentation +-------------- +Documentation by Junio C Hamano. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-prune-packed.txt b/Documentation/git-prune-packed.txt new file mode 100644 index 0000000000..0cb19b0058 --- /dev/null +++ b/Documentation/git-prune-packed.txt @@ -0,0 +1,42 @@ +git-prune-packed(1) +===================== +v0.1, August 2005 + +NAME +---- +git-prune-packed - Program used to remove the extra object files that are now +residing in a pack file. + + +SYNOPSIS +-------- +'git-prune-packed' + +DESCRIPTION +----------- +This program search the GIT_OBJECT_DIR for all objects that currently exist in +a pack file as well as the independent object directories. + +All such extra objects are removed. + +A pack is a collection of objects, individually compressed, with delta +compression applied, stored in a single file, with an associated index file. + +Packs are used to reduce the load on mirror systems, backup engines, disk storage, etc. + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by Ryan Anderson <ryan@michonline.com> + +See-Also +-------- +git-pack-objects(1) git-repack(1) + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-prune.txt b/Documentation/git-prune.txt new file mode 100644 index 0000000000..d1676cbfc8 --- /dev/null +++ b/Documentation/git-prune.txt @@ -0,0 +1,43 @@ +git-prune(1) +============ +v0.99.5, Aug 2005 + +NAME +---- +git-prune - Prunes all unreachable objects from the object database + + +SYNOPSIS +-------- +'git-prune' [-n] + +DESCRIPTION +----------- + +This runs `git-fsck-objects --unreachable` using the heads +specified on the command line (or `$GIT_DIR/refs/heads/\*` and +`$GIT_DIR/refs/tags/\*` if none is specified), and prunes all +unreachable objects from the object database. In addition, it +prunes the unpacked objects that are also found in packs by +running `git prune-packed`. + +OPTIONS +------- + +-n:: + Do not remove anything; just report what it would + remove. + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt new file mode 100644 index 0000000000..c35d2eb54c --- /dev/null +++ b/Documentation/git-pull.txt @@ -0,0 +1,41 @@ +git-pull(1) +=========== +v0.99.4, Aug 2005 + +NAME +---- +git-pull - Pull and merge from another repository. + + +SYNOPSIS +-------- +'git-pull' <repository> <refspec>... + + +DESCRIPTION +----------- +Runs 'git-fetch' with the given parameters. + +When only one ref is downloaded, runs 'git resolve' to merge it +into the local HEAD. Otherwise uses 'git octopus' to merge them +into the local HEAD. + + +OPTIONS +------- +include::pull-fetch-param.txt[] + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> +and Junio C Hamano <junkio@cox.net> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt new file mode 100644 index 0000000000..809ac8ba06 --- /dev/null +++ b/Documentation/git-push.txt @@ -0,0 +1,36 @@ +git-push(1) +=========== + +NAME +---- +git-push - Update remote refs along with associated objects. + + +SYNOPSIS +-------- +'git-push' [--all] [--force] <repository> <refspec>... + +DESCRIPTION +----------- + +Updates remote refs using local refs, while sending objects +necessary to complete the given refs. + + +OPTIONS +------- +include::pull-fetch-param.txt[] + + +Author +------ +Written by Junio C Hamano <junkio@cox.net> + +Documentation +-------------- +Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt new file mode 100644 index 0000000000..0639bd04b2 --- /dev/null +++ b/Documentation/git-read-tree.txt @@ -0,0 +1,278 @@ +git-read-tree(1) +================ +v0.1, May 2005 + +NAME +---- +git-read-tree - Reads tree information into the directory cache + + +SYNOPSIS +-------- +'git-read-tree' (<tree-ish> | [-m [-u|-i]] <tree-ish1> [<tree-ish2> [<tree-ish3>]]) + + +DESCRIPTION +----------- +Reads the tree information given by <tree-ish> into the directory cache, +but does not actually *update* any of the files it "caches". (see: +git-checkout-index) + +Optionally, it can merge a tree into the cache, perform a +fast-forward (i.e. 2-way) merge, or a 3-way merge, with the -m +flag. When used with -m, the -u flag causes it to also update +the files in the work tree with the result of the merge. + +Trivial merges are done by "git-read-tree" itself. Only conflicting paths +will be in unmerged state when "git-read-tree" returns. + +OPTIONS +------- +-m:: + Perform a merge, not just a read. + +-u:: + After a successful merge, update the files in the work + tree with the result of the merge. + +-i:: + Usually a merge requires the index file as well as the + files in the working tree are up to date with the + current head commit, in order not to lose local + changes. This flag disables the check with the working + tree and is meant to be used when creating a merge of + trees that are not directly related to the current + working tree status into a temporary index file. + + +<tree-ish#>:: + The id of the tree object(s) to be read/merged. + + +Merging +------- +If '-m' is specified, "git-read-tree" can perform 3 kinds of +merge, a single tree merge if only 1 tree is given, a +fast-forward merge with 2 trees, or a 3-way merge if 3 trees are +provided. + + +Single Tree Merge +~~~~~~~~~~~~~~~~~ +If only 1 tree is specified, git-read-tree operates as if the user did not +specify '-m', except that if the original cache has an entry for a +given pathname, and the contents of the path matches with the tree +being read, the stat info from the cache is used. (In other words, the +cache's stat()s take precedence over the merged tree's). + +That means that if you do a "git-read-tree -m <newtree>" followed by a +"git-checkout-index -f -u -a", the "git-checkout-index" only checks out +the stuff that really changed. + +This is used to avoid unnecessary false hits when "git-diff-files" is +run after git-read-tree. + + +Two Tree Merge +~~~~~~~~~~~~~~ + +Typically, this is invoked as "git-read-tree -m $H $M", where $H +is the head commit of the current repository, and $M is the head +of a foreign tree, which is simply ahead of $H (i.e. we are in a +fast forward situation). + +When two trees are specified, the user is telling git-read-tree +the following: + + (1) The current index and work tree is derived from $H, but + the user may have local changes in them since $H; + + (2) The user wants to fast-forward to $M. + +In this case, the "git-read-tree -m $H $M" command makes sure +that no local change is lost as the result of this "merge". +Here are the "carry forward" rules: + + I (index) H M Result + ------------------------------------------------------- + 0 nothing nothing nothing (does not happen) + 1 nothing nothing exists use M + 2 nothing exists nothing remove path from cache + 3 nothing exists exists use M + + clean I==H I==M + ------------------ + 4 yes N/A N/A nothing nothing keep index + 5 no N/A N/A nothing nothing keep index + + 6 yes N/A yes nothing exists keep index + 7 no N/A yes nothing exists keep index + 8 yes N/A no nothing exists fail + 9 no N/A no nothing exists fail + + 10 yes yes N/A exists nothing remove path from cache + 11 no yes N/A exists nothing fail + 12 yes no N/A exists nothing fail + 13 no no N/A exists nothing fail + + clean (H=M) + ------ + 14 yes exists exists keep index + 15 no exists exists keep index + + clean I==H I==M (H!=M) + ------------------ + 16 yes no no exists exists fail + 17 no no no exists exists fail + 18 yes no yes exists exists keep index + 19 no no yes exists exists keep index + 20 yes yes no exists exists use M + 21 no yes no exists exists fail + +In all "keep index" cases, the cache entry stays as in the +original index file. If the entry were not up to date, +git-read-tree keeps the copy in the work tree intact when +operating under the -u flag. + +When this form of git-read-tree returns successfully, you can +see what "local changes" you made are carried forward by running +"git-diff-index --cached $M". Note that this does not +necessarily match "git-diff-index --cached $H" would have +produced before such a two tree merge. This is because of cases +18 and 19 --- if you already had the changes in $M (e.g. maybe +you picked it up via e-mail in a patch form), "git-diff-index +--cached $H" would have told you about the change before this +merge, but it would not show in "git-diff-index --cached $M" +output after two-tree merge. + + +3-Way Merge +~~~~~~~~~~~ +Each "index" entry has two bits worth of "stage" state. stage 0 is the +normal one, and is the only one you'd see in any kind of normal use. + +However, when you do "git-read-tree" with three trees, the "stage" +starts out at 1. + +This means that you can do + + git-read-tree -m <tree1> <tree2> <tree3> + +and you will end up with an index with all of the <tree1> entries in +"stage1", all of the <tree2> entries in "stage2" and all of the +<tree3> entries in "stage3". + +Furthermore, "git-read-tree" has special-case logic that says: if you see +a file that matches in all respects in the following states, it +"collapses" back to "stage0": + + - stage 2 and 3 are the same; take one or the other (it makes no + difference - the same work has been done on stage 2 and 3) + + - stage 1 and stage 2 are the same and stage 3 is different; take + stage 3 (some work has been done on stage 3) + + - stage 1 and stage 3 are the same and stage 2 is different take + stage 2 (some work has been done on stage 2) + +The "git-write-tree" command refuses to write a nonsensical tree, and it +will complain about unmerged entries if it sees a single entry that is not +stage 0. + +Ok, this all sounds like a collection of totally nonsensical rules, +but it's actually exactly what you want in order to do a fast +merge. The different stages represent the "result tree" (stage 0, aka +"merged"), the original tree (stage 1, aka "orig"), and the two trees +you are trying to merge (stage 2 and 3 respectively). + +The order of stages 1, 2 and 3 (hence the order of three +<tree-ish> command line arguments) are significant when you +start a 3-way merge with an index file that is already +populated. Here is an outline of how the algorithm works: + +- if a file exists in identical format in all three trees, it will + automatically collapse to "merged" state by git-read-tree. + +- a file that has _any_ difference what-so-ever in the three trees + will stay as separate entries in the index. It's up to "porcelain + policy" to determine how to remove the non-0 stages, and insert a + merged version. + +- the index file saves and restores with all this information, so you + can merge things incrementally, but as long as it has entries in + stages 1/2/3 (ie "unmerged entries") you can't write the result. So + now the merge algorithm ends up being really simple: + + * you walk the index in order, and ignore all entries of stage 0, + since they've already been done. + + * if you find a "stage1", but no matching "stage2" or "stage3", you + know it's been removed from both trees (it only existed in the + original tree), and you remove that entry. + + * if you find a matching "stage2" and "stage3" tree, you remove one + of them, and turn the other into a "stage0" entry. Remove any + matching "stage1" entry if it exists too. .. all the normal + trivial rules .. + +You would normally use "git-merge-index" with supplied +"git-merge-one-file" to do this last step. The script +does not touch the files in the work tree, and the entire merge +happens in the index file. In other words, there is no need to +worry about what is in the working directory, since it is never +shown and never used. + +When you start a 3-way merge with an index file that is already +populated, it is assumed that it represents the state of the +files in your work tree, and you can even have files with +changes unrecorded in the index file. It is further assumed +that this state is "derived" from the stage 2 tree. The 3-way +merge refuses to run if it finds an entry in the original index +file that does not match stage 2. + +This is done to prevent you from losing your work-in-progress +changes. To illustrate, suppose you start from what has been +commited last to your repository: + + $ JC=`cat .git/HEAD` + $ git-checkout-index -f -u -a $JC + +You do random edits, without running git-update-index. And then +you notice that the tip of your "upstream" tree has advanced +since you pulled from him: + + $ git-fetch rsync://.... linus + $ LT=`cat .git/MERGE_HEAD` + +Your work tree is still based on your HEAD ($JC), but you have +some edits since. Three-way merge makes sure that you have not +added or modified cache entries since $JC, and if you haven't, +then does the right thing. So with the following sequence: + + $ git-read-tree -m -u `git-merge-base $JC $LT` $JC $LT + $ git-merge-index git-merge-one-file -a + $ echo "Merge with Linus" | \ + git-commit-tree `git-write-tree` -p $JC -p $LT + +what you would commit is a pure merge between $JC and LT without +your work-in-progress changes, and your work tree would be +updated to the result of the merge. + + +See Also +-------- +gitlink:git-write-tree[1]; gitlink:git-ls-files[1] + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt new file mode 100644 index 0000000000..16c158f439 --- /dev/null +++ b/Documentation/git-rebase.txt @@ -0,0 +1,35 @@ +git-rebase(1) +============= + +NAME +---- +git-rebase - Rebase local commits to new upstream head. + +SYNOPSIS +-------- +'git-rebase' <upstream> [<head>] + +DESCRIPTION +----------- +Rebases local commits to the new head of the upstream tree. + +OPTIONS +------- +<upstream>:: + Upstream branch to compare against. + +<head>:: + Working branch; defaults to HEAD. + +Author +------ +Written by Junio C Hamano <junkio@cox.net> + +Documentation +-------------- +Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-receive-pack.txt b/Documentation/git-receive-pack.txt new file mode 100644 index 0000000000..fb4b76b6c2 --- /dev/null +++ b/Documentation/git-receive-pack.txt @@ -0,0 +1,96 @@ +git-receive-pack(1) +=================== +v0.1, July 2005 + +NAME +---- +git-receive-pack - Receive what is pushed into it + + +SYNOPSIS +-------- +'git-receive-pack' <directory> + +DESCRIPTION +----------- +Invoked by 'git-send-pack' and updates the repository with the +information fed from the remote end. + +This command is usually not invoked directly by the end user. +The UI for the protocol is on the 'git-send-pack' side, and the +program pair is meant to be used to push updates to remote +repository. For pull operations, see 'git-fetch-pack' and +'git-clone-pack'. + +The command allows for creation and fast forwarding of sha1 refs +(heads/tags) on the remote end (strictly speaking, it is the +local end receive-pack runs, but to the user who is sitting at +the send-pack end, it is updating the remote. Confused?) + +Before each ref is updated, if $GIT_DIR/hooks/update file exists +and executable, it is called with three parameters: + + $GIT_DIR/hooks/update refname sha1-old sha1-new + +The refname parameter is relative to $GIT_DIR; e.g. for the +master head this is "refs/heads/master". Two sha1 are the +object names for the refname before and after the update. Note +that the hook is called before the refname is updated, so either +sha1-old is 0{40} (meaning there is no such ref yet), or it +should match what is recorded in refname. + +The hook should exit with non-zero status if it wants to +disallow updating the named ref. Otherwise it should exit with +zero. + +Using this hook, it is easy to generate mails on updates to +the local repository. This example script sends a mail with +the commits pushed to the repository: + + #!/bin/sh + # mail out commit update information. + if expr "$2" : '0*$' >/dev/null + then + echo "Created a new ref, with the following commits:" + git-rev-list --pretty "$2" + else + echo "New commits:" + git-rev-list --pretty "$3" "^$2" + fi | + mail -s "Changes to ref $1" commit-list@mydomain + exit 0 + +Another hook $GIT_DIR/hooks/post-update, if exists and +executable, is called with the list of refs that have been +updated. This can be used to implement repository wide cleanup +task if needed. The exit code from this hook invocation is +ignored; the only thing left for git-receive-pack to do at that +point is to exit itself anyway. This hook can be used, for +example, to run "git-update-server-info" if the repository is +packed and is served via a dumb transport. + + #!/bin/sh + exec git-update-server-info + +OPTIONS +------- +<directory>:: + The repository to sync into. + + +SEE ALSO +-------- +gitlink:git-send-pack[1] + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by Junio C Hamano. + +GIT +--- +Part of the gitlink:git[7] suite diff --git a/Documentation/git-relink.txt b/Documentation/git-relink.txt new file mode 100644 index 0000000000..62405358fc --- /dev/null +++ b/Documentation/git-relink.txt @@ -0,0 +1,37 @@ +git-relink(1) +============= + +NAME +---- +git-relink - Hardlink common objects in local repositories. + +SYNOPSIS +-------- +'git-relink' [--safe] <dir> <dir> [<dir>]\* + +DESCRIPTION +----------- +This will scan 2 or more object repositories and look for common objects, check +if they are hardlinked, and replace one with a hardlink to the other if not. + +OPTIONS +------- +--safe:: + Stops if two objects with the same hash exist but have different sizes. + Default is to warn and continue. + +<dir>:: + Directories containing a .git/objects/ subdirectory. + +Author +------ +Written by Ryan Anderson <ryan@michonline.com> + +Documentation +-------------- +Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-rename.txt b/Documentation/git-rename.txt new file mode 100644 index 0000000000..21928dc071 --- /dev/null +++ b/Documentation/git-rename.txt @@ -0,0 +1,33 @@ +git-rename(1) +============= +v0.1, May 2005 + +NAME +---- +git-rename - Script used to rename a file, directory or symlink. + + +SYNOPSIS +-------- +'git-rename' <source> <destination> + +DESCRIPTION +----------- +This script is used to rename a file, directory or symlink. + +The index is updated after successful completion, but the change must still be +committed. + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> +Rewritten by Ryan Anderson <ryan@michonline.com> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-repack.txt b/Documentation/git-repack.txt new file mode 100644 index 0000000000..2e95e111f3 --- /dev/null +++ b/Documentation/git-repack.txt @@ -0,0 +1,59 @@ +git-repack(1) +============= +v0.99.5, August 2005 + +NAME +---- +git-repack - Script used to pack a repository from a collection of +objects into pack files. + + +SYNOPSIS +-------- +'git-repack' [-a] [-d] + +DESCRIPTION +----------- + +This script is used to combine all objects that do not currently +reside in a "pack", into a pack. + +A pack is a collection of objects, individually compressed, with +delta compression applied, stored in a single file, with an +associated index file. + +Packs are used to reduce the load on mirror systems, backup +engines, disk storage, etc. + +OPTIONS +------- + +-a:: + Instead of incrementally packing the unpacked objects, + pack everything available into a single pack. + Especially useful when packing a repository that is used + for a private development and there no need to worry + about people fetching via dumb protocols from it. Use + with '-d'. + +-d:: + After packing, if the newly created packs make some + existing packs redundant, remove the redundant packs. + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by Ryan Anderson <ryan@michonline.com> + +See-Also +-------- +git-pack-objects(1) git-prune-packed(1) + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-request-pull.txt b/Documentation/git-request-pull.txt new file mode 100644 index 0000000000..2463ec91d5 --- /dev/null +++ b/Documentation/git-request-pull.txt @@ -0,0 +1,40 @@ +git-request-pull(1) +=================== + +NAME +---- +git-request-pull - Generates a summary of pending changes. + +SYNOPSIS +-------- +'git-request-pull' <start> <url> [<end>] + +DESCRIPTION +----------- + +Summarizes the changes between two commits to the standard output, and includes +the given URL in the generated summary. + +OPTIONS +------- +<start>:: + Commit to start at. + +<url>:: + URL to include in the summary. + +<end>:: + Commit to send at; defaults to HEAD. + +Author +------ +Written by Ryan Anderson <ryan@michonline.com> and Junio C Hamano <junkio@cox.net> + +Documentation +-------------- +Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt new file mode 100644 index 0000000000..31ec2076e7 --- /dev/null +++ b/Documentation/git-reset.txt @@ -0,0 +1,45 @@ +git-reset(1) +============ + +NAME +---- +git-reset - Reset current HEAD to the specified state. + +SYNOPSIS +-------- +'git-reset' [--mixed | --soft | --hard] [<commit-ish>] + +DESCRIPTION +----------- +Sets the current head to the specified commit and optionally resets the +index and working tree to match. + +OPTIONS +------- +--mixed:: + Like --soft but reports what has not been updated. This is the + default action. + +--soft:: + Does not touch the index file nor the working tree at all, but + requires them in a good order. + +--hard:: + Matches the working tree and index to that of the tree being + switched to. + +<commit-ish>:: + Commit to make the current HEAD. + +Author +------ +Written by Junio C Hamano <junkio@cox.net> and Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-resolve.txt b/Documentation/git-resolve.txt new file mode 100644 index 0000000000..7d3eb79033 --- /dev/null +++ b/Documentation/git-resolve.txt @@ -0,0 +1,37 @@ +git-resolve(1) +============== +v0.99.5, Aug 2005 + +NAME +---- +git-resolve - Merge two commits + + +SYNOPSIS +-------- +'git resolve' <current> <merged> <message> + +DESCRIPTION +----------- +Given two commits and a merge message, merge the <merged> commit +into <current> commit, with the commit log message <message>. + +When <current> is a descendant of <merged>, or <current> is an +ancestor of <merged>, no new commit is created and the <message> +is ignored. The former is informally called "already up to +date", and the latter is often called "fast forward". + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> and +Dan Holmsand <holmsand@gmail.com>. + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt new file mode 100644 index 0000000000..02ee93ee41 --- /dev/null +++ b/Documentation/git-rev-list.txt @@ -0,0 +1,99 @@ +git-rev-list(1) +=============== +v0.1, May 2005 + +NAME +---- +git-rev-list - Lists commit objects in reverse chronological order + + +SYNOPSIS +-------- +'git-rev-list' [ *--max-count*=number ] [ *--max-age*=timestamp ] [ *--min-age*=timestamp ] [ *--bisect* ] [ *--pretty* ] [ *--objects* ] [ *--merge-order* [ *--show-breaks* ] ] <commit> [ <commit> ...] [ ^<commit> ...] + +DESCRIPTION +----------- +Lists commit objects in reverse chronological order starting at the +given commit(s), taking ancestry relationship into account. This is +useful to produce human-readable log output. + +Commits which are stated with a preceding '^' cause listing to stop at +that point. Their parents are implied. "git-rev-list foo bar ^baz" thus +means "list all the commits which are included in 'foo' and 'bar', but +not in 'baz'". + +If *--pretty* is specified, print the contents of the commit changesets +in human-readable form. + +The *--objects* flag causes 'git-rev-list' to print the object IDs of +any object referenced by the listed commits. 'git-rev-list --objects foo +^bar' thus means "send me all object IDs which I need to download if +I have the commit object 'bar', but not 'foo'". + +The *--bisect* flag limits output to the one commit object which is +roughly halfway between the included and excluded commits. Thus, +if 'git-rev-list --bisect foo ^bar +^baz' outputs 'midpoint', the output +of 'git-rev-list foo ^midpoint' and 'git-rev-list midpoint +^bar +^baz' +would be of roughly the same length. Finding the change which introduces +a regression is thus reduced to a binary search: repeatedly generate and +test new 'midpoint's until the commit chain is of length one. + +If *--merge-order* is specified, the commit history is decomposed into a +unique sequence of minimal, non-linear epochs and maximal, linear epochs. +Non-linear epochs are then linearised by sorting them into merge order, which +is described below. + +Maximal, linear epochs correspond to periods of sequential development. +Minimal, non-linear epochs correspond to periods of divergent development +followed by a converging merge. The theory of epochs is described in more +detail at +link:http://blackcubes.dyndns.org/epoch/[http://blackcubes.dyndns.org/epoch/]. + +The merge order for a non-linear epoch is defined as a linearisation for which +the following invariants are true: + + 1. if a commit P is reachable from commit N, commit P sorts after commit N + in the linearised list. + 2. if Pi and Pj are any two parents of a merge M (with i < j), then any + commit N, such that N is reachable from Pj but not reachable from Pi, + sorts before all commits reachable from Pi. + +Invariant 1 states that later commits appear before earlier commits they are +derived from. + +Invariant 2 states that commits unique to "later" parents in a merge, appear +before all commits from "earlier" parents of a merge. + +If *--show-breaks* is specified, each item of the list is output with a +2-character prefix consisting of one of: (|), (^), (=) followed by a space. + +Commits marked with (=) represent the boundaries of minimal, non-linear epochs +and correspond either to the start of a period of divergent development or to +the end of such a period. + +Commits marked with (|) are direct parents of commits immediately preceding +the marked commit in the list. + +Commits marked with (^) are not parents of the immediately preceding commit. +These "breaks" represent necessary discontinuities implied by trying to +represent an arbtirary DAG in a linear form. + +*--show-breaks* is only valid if *--merge-order* is also specified. + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Original *--merge-order* logic by Jon Seymour <jon.seymour@gmail.com> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt new file mode 100644 index 0000000000..e2d94ff335 --- /dev/null +++ b/Documentation/git-rev-parse.txt @@ -0,0 +1,126 @@ +git-rev-parse(1) +================ + +NAME +---- +git-rev-parse - Pick out and massage parameters. + + +SYNOPSIS +-------- +'git-rev-parse' [ --option ] <args>... + +DESCRIPTION +----------- + +Many git Porcelainish commands take mixture of flags +(i.e. parameters that begin with a dash '-') and parameters +meant for underlying `git-rev-list` command they use internally +and flags and parameters for other commands they use as the +downstream of `git-rev-list`. This command is used to +distinguish between them. + + +OPTIONS +------- +--revs-only:: + Do not output flags and parameters not meant for + `git-rev-list` command. + +--no-revs:: + Do not output flags and parameters meant for + `git-rev-list` command. + +--flags:: + Do not output non-flag parameters. + +--no-flags:: + Do not output flag parameters. + +--default <arg>:: + If there is no parameter given by the user, use `<arg>` + instead. + +--verify:: + The parameter given must be usable as a single, valid + object name. Otherwise barf and abort. + +--sq:: + Usually the output is made one line per flag and + parameter. This option makes output a single line, + properly quoted for consumption by shell. Useful when + you expect your parameter to contain whitespaces and + newlines (e.g. when using pickaxe `-S` with + `git-diff-\*`). + +--not:: + When showing object names, prefix them with '^' and + strip '^' prefix from the object names that already have + one. + +--symbolic:: + Usually the object names are output in SHA1 form (with + possible '^' prefix); this option makes them output in a + form as close to the original input as possible. + + +--all:: + Show all refs found in `$GIT_DIR/refs`. + +--show-prefix:: + When the command is invoked from a directory show the + path of the current directory relative to the top-level + directory. + +<args>...:: + Flags and parameters to be parsed. + + +SPECIFYING REVISIONS +-------------------- + +A revision parameter typically names a commit object. They use +what is called an 'extended SHA1' syntax. + +* The full SHA1 object name (40-byte hexadecimal string), or + a substring of such that is unique within the repository. + E.g. dae86e1950b1277e545cee180551750029cfe735 and dae86e both + name the same commit object if there are no other object in + your repository whose object name starts with dae86e. + +* A symbolic ref name. E.g. 'master' typically means the commit + object referenced by $GIT_DIR/refs/heads/master. If you + happen to have both heads/master and tags/master, you can + explicitly say 'heads/master' to tell GIT which one you mean. + +* A suffix '^' to a revision parameter means the first parent of + that commit object. '^<n>' means the <n>th parent (i.e. + 'rev^' + is equivalent to 'rev^1'). As a special rule, + 'rev^0' means the commit itself and is used when 'rev' is the + object name of a tag object that refers to a commit object. + +* A suffix '~<n>' to a revision parameter means the commit + object that is the <n>th generation grand-parent of the named + commit object, following only the first parent. I.e. rev~3 is + equivalent to rev^^^ which is equivalent to rev^1^1^1. + +'git-rev-parse' also accepts a prefix '^' to revision parameter, +which is passed to 'git-rev-list'. Two revision parameters +concatenated with '..' is a short-hand for writing a range +between them. I.e. 'r1..r2' is equivalent to saying '^r1 r2' + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> and +Junio C Hamano <junkio@cox.net> + +Documentation +-------------- +Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt new file mode 100644 index 0000000000..47476586d9 --- /dev/null +++ b/Documentation/git-revert.txt @@ -0,0 +1,48 @@ +git-revert(1) +============= + +NAME +---- +git-revert - Revert an existing commit. + +SYNOPSIS +-------- +'git-revert' [-n] <commit> + +DESCRIPTION +----------- +Given one existing commit, revert the change the patch introduces, and record a +new commit that records it. This requires your working tree to be clean (no +modifications from the HEAD commit). + +OPTIONS +------- +<commit>:: + Commit to revert. + +-n:: + Usually the command automatically creates a commit with + a commit log message stating which commit was reverted. + This flag applies the change necessary to revert the + named commit to your working tree, but does not make the + commit. In addition, when this option is used, your + working tree does not have to match the HEAD commit. + The revert is done against the beginning state of your + working tree. + + This is useful when reverting more than one commits' + effect to your working tree in a row. + + +Author +------ +Written by Junio C Hamano <junkio@cox.net> + +Documentation +-------------- +Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt new file mode 100644 index 0000000000..a2763bd74f --- /dev/null +++ b/Documentation/git-send-email.txt @@ -0,0 +1,79 @@ +git-send-email(1) +================= +v0.1, July 2005 + +NAME +---- +git-send-email - Send a collection of patches as emails + + +SYNOPSIS +-------- +'git-send-email' [options] <file|directory> [... file|directory] + + + +DESCRIPTION +----------- +Takes the patches given on the command line and emails them out. + +The header of the email is configurable by command line options. If not +specified on the command line, the user will be prompted with a ReadLine +enabled interface to provide the necessary information. + +The options available are: + + --to + Specify the primary recipient of the emails generated. + Generally, this will be the upstream maintainer of the + project involved. + + --from + Specify the sender of the emails. This will default to + the value GIT_COMMITTER_IDENT, as returned by "git-var -l". + The user will still be prompted to confirm this entry. + + --compose + Use \$EDITOR to edit an introductory message for the + patch series. + + --subject + Specify the initial subject of the email thread. + Only necessary if --compose is also set. If --compose + is not set, this will be prompted for. + + --in-reply-to + Specify the contents of the first In-Reply-To header. + Subsequent emails will refer to the previous email + instead of this if --chain-reply-to is set (the default) + Only necessary if --compose is also set. If --compose + is not set, this will be prompted for. + + --chain-reply-to, --no-chain-reply-to + If this is set, each email will be sent as a reply to the previous + email sent. If disabled with "--no-chain-reply-to", all emails after + the first will be sent as replies to the first email sent. When using + this, it is recommended that the first file given be an overview of the + entire patch series. + Default is --chain-reply-to + + --smtp-server + If set, specifies the outgoing SMTP server to use. Defaults to + localhost. + + +Author +------ +Written by Ryan Anderson <ryan@michonline.com> + +git-send-email is originally based upon +send_lots_of_email.pl by Greg Kroah-Hartman. + +Documentation +-------------- +Documentation by Ryan Anderson + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-send-pack.txt b/Documentation/git-send-pack.txt new file mode 100644 index 0000000000..1837fb79c7 --- /dev/null +++ b/Documentation/git-send-pack.txt @@ -0,0 +1,111 @@ +git-send-pack(1) +================ +v0.1, July 2005 + +NAME +---- +git-send-pack - Push missing objects packed. + + +SYNOPSIS +-------- +'git-send-pack' [--all] [--force] [--exec=<git-receive-pack>] [<host>:]<directory> [<ref>...] + +DESCRIPTION +----------- +Invokes 'git-receive-pack' on a possibly remote repository, and +updates it from the current repository, sending named refs. + + +OPTIONS +------- +--exec=<git-receive-pack>:: + Path to the 'git-receive-pack' program on the remote + end. Sometimes useful when pushing to a remote + repository over ssh, and you do not have the program in + a directory on the default $PATH. + +--all:: + Instead of explicitly specifying which refs to update, + update all refs that locally exist. + +--force:: + Usually, the command refuses to update a remote ref that + is not an ancestor of the local ref used to overwrite it. + This flag disables the check. What this means is that + the remote repository can lose commits; use it with + care. + +<host>:: + A remote host to house the repository. When this + part is specified, 'git-receive-pack' is invoked via + ssh. + +<directory>:: + The repository to update. + +<ref>...: + The remote refs to update. + + +Specifying the Refs +------------------- + +There are three ways to specify which refs to update on the +remote end. + +With '--all' flag, all refs that exist locally are transfered to +the remote side. You cannot specify any '<ref>' if you use +this flag. + +Without '--all' and without any '<ref>', the refs that exist +both on the local side and on the remote side are updated. + +When '<ref>'s are specified explicitly, it can be either a +single pattern, or a pair of such pattern separated by a colon +':' (this means that a ref name cannot have a colon in it). A +single pattern '<name>' is just a shorthand for '<name>:<name>'. + +Each pattern pair consists of the source side (before the colon) +and the destination side (after the colon). The ref to be +pushed is determined by finding a match that matches the source +side, and where it is pushed is determined by using the +destination side. + + - It is an error if <src> does not match exactly one of the + local refs. + + - It is an error if <dst> matches more than one remote refs. + + - If <dst> does not match any remote ref, either + + - it has to start with "refs/"; <dst> is used as the + destination literally in this case. + + - <src> == <dst> and the ref that matched the <src> must not + exist in the set of remote refs; the ref matched <src> + locally is used as the name of the destination. + +Without '--force', the <src> ref is stored at the remote only if +<dst> does not exist, or <dst> is a proper subset (i.e. an +ancestor) of <src>. This check, known as "fast forward check", +is performed in order to avoid accidentally overwriting the +remote ref and lose other peoples' commits from there. + +With '--force', the fast forward check is disabled for all refs. + +Optionally, a <ref> parameter can be prefixed with a plus '+' sign +to disable the fast-forward check only on that ref. + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by Junio C Hamano. + +GIT +--- +Part of the gitlink:git[7] suite diff --git a/Documentation/git-sh-setup.txt b/Documentation/git-sh-setup.txt new file mode 100644 index 0000000000..a02a2b051c --- /dev/null +++ b/Documentation/git-sh-setup.txt @@ -0,0 +1,34 @@ +git-sh-setup(1) +=============== + +NAME +---- +git-sh-setup - Common git shell script setup code. + +SYNOPSIS +-------- +'git-sh-setup' + +DESCRIPTION +----------- + +Sets up the normal git environment variables and a few helper functions +(currently just "die()"), and returns ok if it all looks like a git archive. +So use it something like + + . git-sh-setup || die "Not a git archive" + +to make the rest of the git scripts more careful and readable. + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt new file mode 100644 index 0000000000..a852e9b865 --- /dev/null +++ b/Documentation/git-shortlog.txt @@ -0,0 +1,31 @@ +git-shortlog(1) +=============== +v0.99.4, Aug 2005 + +NAME +---- +git-shortlog - Summarize 'git log' output. + + +SYNOPSIS +-------- +'git log --pretty=short | git shortlog' + +DESCRIPTION +----------- +Summarizes 'git log' output in a format suitable for inclusion +in release announcements. + + +Author +------ +Written by Jeff Garzik <jgarzik@pobox.com> + +Documentation +-------------- +Documentation by Junio C Hamano. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt new file mode 100644 index 0000000000..5b80d5aa2a --- /dev/null +++ b/Documentation/git-show-branch.txt @@ -0,0 +1,120 @@ +git-show-branch(1) +================== +v0.99.5, Aug 2005 + +NAME +---- +git-show-branch - Show branches and their commits. + +SYNOPSIS +-------- +'git show-branch [--all] [--heads] [--tags] [--more=<n> | --list | --independent | --merge-base] <reference>...' + +DESCRIPTION +----------- +Shows the head commits from the named <reference> (or all refs under +$GIT_DIR/refs/heads), and displays concise list of commit logs +to show their relationship semi-visually. + +OPTIONS +------- +<reference>:: + Name of the reference under $GIT_DIR/refs/. + +--all --heads --tags:: + Show all refs under $GIT_DIR/refs, $GIT_DIR/refs/heads, + and $GIT_DIR/refs/tags, respectively. + +--more=<n>:: + Usually the command stops output upon showing the commit + that is the common ancestor of all the branches. This + flag tells the command to go <n> more common commits + beyond that. When <n> is negative, display only the + <reference>s given, without showing the commit ancestry + tree. + +--list:: + Synomym to `--more=-1` + +--merge-base:: + Instead of showing the commit list, just act like the + 'git-merge-base -a' command, except that it can accept + more than two heads. + +--independent:: + Among the <reference>s given, display only the ones that + cannot be reached from any other <reference>. + +Note that --more, --list, --independent and --merge-base options +are mutually exclusive. + + +OUTPUT +------ +Given N <references>, the first N lines are the one-line +description from their commit message. The branch head that is +pointed at by $GIT_DIR/HEAD is prefixed with an asterisk '*' +character while other heads are prefixed with a '!' character. + +Following these N lines, one-line log for each commit is +displayed, indented N places. If a commit is on the I-th +branch, the I-th indentation character shows a '+' sign; +otherwise it shows a space. Each commit shows a short name that +can be used as an exended SHA1 to name that commit. + +The following example shows three branches, "master", "fixes" +and "mhf": + +------------------------------------------------ +$ git show-branch master fixes mhf +! [master] Add 'git show-branch'. + ! [fixes] Introduce "reset type" flag to "git reset" + ! [mhf] Allow "+remote:local" refspec to cause --force when fetching. +--- + + [mhf] Allow "+remote:local" refspec to cause --force when fetching. + + [mhf~1] Use git-octopus when pulling more than one heads. + + [fixes] Introduce "reset type" flag to "git reset" + + [mhf~2] "git fetch --force". + + [mhf~3] Use .git/remote/origin, not .git/branches/origin. + + [mhf~4] Make "git pull" and "git fetch" default to origin + + [mhf~5] Infamous 'octopus merge' + + [mhf~6] Retire git-parse-remote. + + [mhf~7] Multi-head fetch. + + [mhf~8] Start adding the $GIT_DIR/remotes/ support. ++++ [master] Add 'git show-branch'. +------------------------------------------------ + +These three branches all forked from a common commit, [master], +whose commit message is "Add 'git show-branch'. "fixes" branch +adds one commit 'Introduce "reset type"'. "mhf" branch has many +other commits. + +When only one head is given, the output format changes slightly +to conserve space. The '+' sign to show which commit is +reachable from which head and the first N lines to show the list +of heads being displayed are both meaningless so they are +omitted. Also the label given to each commit does not repeat +the name of the branch because it is obvious. + +------------------------------------------------ +$ git show-branch --more=4 master +[master] Add 'git show-branch'. +[~1] Add a new extended SHA1 syntax <name>~<num> +[~2] Fix "git-diff A B" +[~3] git-ls-files: generalized pathspecs +[~4] Make "git-ls-files" work in subdirectories +------------------------------------------------ + +Author +------ +Written by Junio C Hamano <junkio@cox.net> + + +Documentation +-------------- +Documentation by Junio C Hamano. + + +GIT +--- +Part of the gitlink:git[7] suite diff --git a/Documentation/git-show-index.txt b/Documentation/git-show-index.txt new file mode 100644 index 0000000000..72720ada22 --- /dev/null +++ b/Documentation/git-show-index.txt @@ -0,0 +1,36 @@ +git-show-index(1) +================= +v0.1, July 2005 + +NAME +---- +git-show-index - Show packed archive index + + +SYNOPSIS +-------- +'git-show-index' < idx-file + + +DESCRIPTION +----------- +Reads given idx file for packed GIT archive created with +git-pack-objects command, and dumps its contents. + +The information it outputs is subset of what you can get from +'git-verify-pack -v'; this command only shows the packfile +offset and SHA1 of each object. + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by Junio C Hamano + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-ssh-fetch.txt b/Documentation/git-ssh-fetch.txt new file mode 100644 index 0000000000..e3887ace09 --- /dev/null +++ b/Documentation/git-ssh-fetch.txt @@ -0,0 +1,52 @@ +git-ssh-fetch(1) +================ +v0.1, May 2005 + +NAME +---- +git-ssh-fetch - Pulls from a remote repository over ssh connection + + + +SYNOPSIS +-------- +'git-ssh-fetch' [-c] [-t] [-a] [-d] [-v] [-w filename] [--recover] commit-id url + +DESCRIPTION +----------- +Pulls from a remote repository over ssh connection, invoking +git-ssh-upload on the other end. It functions identically to +git-ssh-upload, aside from which end you run it on. + + +OPTIONS +------- +commit-id:: + Either the hash or the filename under [URL]/refs/ to + pull. + +-c:: + Get the commit objects. +-t:: + Get trees associated with the commit objects. +-a:: + Get all the objects. +-v:: + Report what is downloaded. +-w:: + Writes the commit-id into the filename under $GIT_DIR/refs/ on + the local end after the transfer is complete. + + +Author +------ +Written by Daniel Barkalow <barkalow@iabervon.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-ssh-upload.txt b/Documentation/git-ssh-upload.txt new file mode 100644 index 0000000000..b625019812 --- /dev/null +++ b/Documentation/git-ssh-upload.txt @@ -0,0 +1,48 @@ +git-ssh-upload(1) +================= +v0.1, Jun 2005 + +NAME +---- +git-ssh-upload - Pushes to a remote repository over ssh connection + + +SYNOPSIS +-------- +'git-ssh-upload' [-c] [-t] [-a] [-d] [-v] [-w filename] [--recover] commit-id url + +DESCRIPTION +----------- +Pushes from a remote repository over ssh connection, invoking +git-ssh-fetch on the other end. It functions identically to +git-ssh-fetch, aside from which end you run it on. + +OPTIONS +------- +commit-id:: + Id of commit to push. + +-c:: + Get the commit objects. +-t:: + Get tree associated with the requested commit object. +-a:: + Get all the objects. +-v:: + Report what is uploaded. +-w:: + Writes the commit-id into the filename under [URL]/refs/ on + the remote end after the transfer is complete. + +Author +------ +Written by Daniel Barkalow <barkalow@iabervon.org> + +Documentation +-------------- +Documentation by Daniel Barkalow + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt new file mode 100644 index 0000000000..6d49a5aa0d --- /dev/null +++ b/Documentation/git-status.txt @@ -0,0 +1,46 @@ +git-status(1) +============= +v0.99.4, Aug 2005 + +NAME +---- +git-status - Show working tree status. + + +SYNOPSIS +-------- +'git status' + +DESCRIPTION +----------- +Examines paths in the working tree that has changes unrecorded +to the index file, and changes between the index file and the +current HEAD commit. The former paths are what you _could_ +commit by running 'git-update-index' before running 'git +commit', and the latter paths are what you _would_ commit by +running 'git commit'. + +If there is no path that is different between the index file and +the current HEAD commit, the command exits with non-zero +status. + + +OUTPUT +------ +The output from this command is designed to be used as a commit +template comments, and all the output lines are prefixed with '#'. + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> and +Junio C Hamano <junkio@cox.net>. + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-stripspace.txt b/Documentation/git-stripspace.txt new file mode 100644 index 0000000000..528a1b6ce3 --- /dev/null +++ b/Documentation/git-stripspace.txt @@ -0,0 +1,33 @@ +git-stripspace(1) +================= + +NAME +---- +git-stripspace - Filter out empty lines. + + +SYNOPSIS +-------- +'git-stripspace' < <stream> + +DESCRIPTION +----------- +Remove multiple empty lines, and empty lines at beginning and end. + +OPTIONS +------- +<stream>:: + Byte stream to act on. + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt new file mode 100644 index 0000000000..1e0d4f5f46 --- /dev/null +++ b/Documentation/git-tag.txt @@ -0,0 +1,39 @@ +git-tag(1) +========== +v0.99.4, Aug 2005 + +NAME +---- +git-tag - Create a tag object signed with GPG + + + +SYNOPSIS +-------- +'git-tag' [-s | -a] [-f] <name> + +DESCRIPTION +----------- +Adds a "tag" reference in .git/refs/tags/ + +Unless "-f" is given, the tag must not yet exist in ".git/refs/tags" + +If "-s" or "-a" is passed, the user will be prompted for a tag message. +and a tag object is created. Otherwise just the SHA1 object +name of the commit object is written. + +A GnuPG signed tag object will be created when "-s" is used. + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org>, +Junio C Hamano <junkio@cox.net> and Chris Wright <chrisw@osdl.org>. + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite diff --git a/Documentation/git-tar-tree.txt b/Documentation/git-tar-tree.txt new file mode 100644 index 0000000000..480a0cf0ba --- /dev/null +++ b/Documentation/git-tar-tree.txt @@ -0,0 +1,39 @@ +git-tar-tree(1) +=============== +v0.1, May 2005 + +NAME +---- +git-tar-tree - Creates a tar archive of the files in the named tree + + +SYNOPSIS +-------- +'git-tar-tree' <tree-ish> [ <base> ] + +DESCRIPTION +----------- +Creates a tar archive containing the tree structure for the named tree. +When <base> is specified it is added as a leading path to the files in the +generated tar archive. + +git-tar-tree behaves differently when given a tree ID versus when given +a commit ID or tag ID. In the first case the current time is used as +modification time of each file in the archive. In the latter case the +commit time as recorded in the referenced commit object is used instead. +Additionally the commit ID is stored in a global extended pax header. +It can be extracted using git-get-tar-commit-id. + + +Author +------ +Written by Rene Scharfe. + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-unpack-file.txt b/Documentation/git-unpack-file.txt new file mode 100644 index 0000000000..3903b2d99b --- /dev/null +++ b/Documentation/git-unpack-file.txt @@ -0,0 +1,37 @@ +git-unpack-file(1) +================== +v0.1, May 2005 + +NAME +---- +git-unpack-file - Creates a temporary file with a blob's contents + + + +SYNOPSIS +-------- +'git-unpack-file' <blob> + +DESCRIPTION +----------- +Creates a file holding the contents of the blob specified by sha1. It +returns the name of the temporary file in the following format: + .merge_file_XXXXX + +OPTIONS +------- +<blob>:: + Must be a blob id + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-unpack-objects.txt b/Documentation/git-unpack-objects.txt new file mode 100644 index 0000000000..9b982d996f --- /dev/null +++ b/Documentation/git-unpack-objects.txt @@ -0,0 +1,39 @@ +git-unpack-objects(1) +===================== +v0.1, July 2005 + +NAME +---- +git-unpack-objects - Unpack objects from a packed archive. + + +SYNOPSIS +-------- +'git-unpack-objects' [-q] <pack-file + + +DESCRIPTION +----------- +Reads a packed archive (.pack) from the standard input, and +expands the objects contained in the pack into "one-file +one-object" format in $GIT_OBJECT_DIRECTORY. + +OPTIONS +------- +-q:: + The command usually shows percentage progress. This + flag suppresses it. + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +------------- +Documentation by Junio C Hamano + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt new file mode 100644 index 0000000000..8d55659ede --- /dev/null +++ b/Documentation/git-update-index.txt @@ -0,0 +1,126 @@ +git-update-index(1) +=================== +v0.1, May 2005 + +NAME +---- +git-update-index - Modifies the index or directory cache + + +SYNOPSIS +-------- +'git-update-index' + [--add] [--remove] [--refresh] [--replace] + [--ignore-missing] + [--force-remove] + [--cacheinfo <mode> <object> <file>]\* + [--info-only] + [--] [<file>]\* + +DESCRIPTION +----------- +Modifies the index or directory cache. Each file mentioned is updated +into the cache and any 'unmerged' or 'needs updating' state is +cleared. + +The way "git-update-index" handles files it is told about can be modified +using the various options: + +OPTIONS +------- +--add:: + If a specified file isn't in the cache already then it's + added. + Default behaviour is to ignore new files. + +--remove:: + If a specified file is in the cache but is missing then it's + removed. + Default behaviour is to ignore removed file. + +--refresh:: + Looks at the current cache and checks to see if merges or + updates are needed by checking stat() information. + +--ignore-missing:: + Ignores missing files during a --refresh + +--cacheinfo <mode> <object> <path>:: + Directly insert the specified info into the cache. + +--info-only:: + Do not create objects in the object database for all + <file> arguments that follow this flag; just insert + their object IDs into the cache. + +--force-remove:: + Remove the file from the index even when the working directory + still has such a file. (Implies --remove.) + +--replace:: + By default, when a file `path` exists in the index, + git-update-index refuses an attempt to add `path/file`. + Similarly if a file `path/file` exists, a file `path` + cannot be added. With --replace flag, existing entries + that conflicts with the entry being added are + automatically removed with warning messages. + +--:: + Do not interpret any more arguments as options. + +<file>:: + Files to act on. + Note that files begining with '.' are discarded. This includes + `./file` and `dir/./file`. If you don't want this, then use + cleaner names. + The same applies to directories ending '/' and paths with '//' + +Using --refresh +--------------- +'--refresh' does not calculate a new sha1 file or bring the cache +up-to-date for mode/content changes. But what it *does* do is to +"re-match" the stat information of a file with the cache, so that you +can refresh the cache for a file that hasn't been changed but where +the stat entry is out of date. + +For example, you'd want to do this after doing a "git-read-tree", to link +up the stat cache details with the proper files. + +Using --cacheinfo or --info-only +-------------------------------- +'--cacheinfo' is used to register a file that is not in the +current working directory. This is useful for minimum-checkout +merging. + + To pretend you have a file with mode and sha1 at path, say: + + $ git-update-index --cacheinfo mode sha1 path + +'--info-only' is used to register files without placing them in the object +database. This is useful for status-only repositories. + +Both '--cacheinfo' and '--info-only' behave similarly: the index is updated +but the object database isn't. '--cacheinfo' is useful when the object is +in the database but the file isn't available locally. '--info-only' is +useful when the file is available, but you do not wish to update the +object database. + +Examples +-------- +To update and refresh only the files already checked out: + + git-checkout-index -n -f -a && git-update-index --ignore-missing --refresh + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-update-server-info.txt b/Documentation/git-update-server-info.txt new file mode 100644 index 0000000000..2efd5400a7 --- /dev/null +++ b/Documentation/git-update-server-info.txt @@ -0,0 +1,59 @@ +git-update-server-info(1) +========================= +v0.1, July 2005 + +NAME +---- +git-update-server-info - Update auxiliary info file to help dumb servers + + +SYNOPSIS +-------- +'git-update-server-info' [--force] + +DESCRIPTION +----------- +A dumb server that does not do on-the-fly pack generations can +have some auxiliary information files in $GIT_DIR/info and +$GIT_OBJECT_DIRECTORY/info directories to help clients discover +what references and packs the server has and make optimized +pull decisions. This command generates such auxiliary files. + + +OPTIONS +------- + +--force:: + Update the info files from scratch. + + +OUTPUT +------ + +Currently the command updates the following files. Please see +link:repository-layout.html[repository-layout] for description +of what they are for: + +* objects/info/packs + +* info/refs + + +BUGS +---- +When you remove an existing ref, the command fails to update +info/refs file unless `--force` flag is given. + + +Author +------ +Written by Junio C Hamano <junkio@cox.net> + +Documentation +-------------- +Documentation by Junio C Hamano. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-upload-pack.txt b/Documentation/git-upload-pack.txt new file mode 100644 index 0000000000..98815b6a10 --- /dev/null +++ b/Documentation/git-upload-pack.txt @@ -0,0 +1,40 @@ +git-upload-pack(1) +================== +v0.1, July 2005 + +NAME +---- +git-upload-pack - Send missing objects packed. + + +SYNOPSIS +-------- +'git-upload-pack' <directory> + +DESCRIPTION +----------- +Invoked by 'git-clone-pack' and/or 'git-fetch-pack', learns what +objects the other side is missing, and sends them after packing. + +This command is usually not invoked directly by the end user. +The UI for the protocol is on the 'git-fetch-pack' side, and the +program pair is meant to be used to pull updates from a remote +repository. For push operations, see 'git-send-pack'. + + +OPTIONS +------- +<directory>:: + The repository to sync from. + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by Junio C Hamano. + +GIT +--- +Part of the gitlink:git[7] suite diff --git a/Documentation/git-var.txt b/Documentation/git-var.txt new file mode 100644 index 0000000000..31f80a8b30 --- /dev/null +++ b/Documentation/git-var.txt @@ -0,0 +1,60 @@ +git-var(1) +========== +v0.1, July 2005 + +NAME +---- +git-var - Print the git users identity + + +SYNOPSIS +-------- +git-var [ -l | <variable> ] + +DESCRIPTION +----------- +Prints a git logical variable. + +-l causes the logical variables to be listed. + +EXAMPLE +-------- +$git-var GIT_AUTHOR_IDENT + +Eric W. Biederman <ebiederm@lnxi.com> 1121223278 -0600 + + +VARIABLES +---------- +GIT_AUTHOR_IDENT + The author of a piece of code. + +GIT_COMMITTER_IDENT + The person who put a piece of code into git. + +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 +-------- +gitlink:git-commit-tree[1] +gitlink:git-tag[1] + +Author +------ +Written by Eric Biederman <ebiederm@xmission.com> + +Documentation +-------------- +Documentation by Eric Biederman and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-verify-pack.txt b/Documentation/git-verify-pack.txt new file mode 100644 index 0000000000..a99172ca1e --- /dev/null +++ b/Documentation/git-verify-pack.txt @@ -0,0 +1,49 @@ +git-verify-pack(1) +================== +v0.1, June 2005 + +NAME +---- +git-verify-pack - Validate packed GIT archive files. + + +SYNOPSIS +-------- +'git-verify-pack' [-v] <pack>.idx ... + + +DESCRIPTION +----------- +Reads given idx file for packed GIT archive created with +git-pack-objects command and verifies idx file and the +corresponding pack file. + +OPTIONS +------- +<pack>.idx ...:: + The idx files to verify. + +-v:: + After verifying the pack, show list of objects contained + in the pack. The format used is: + + SHA1 type size offset-in-packfile + + for objects that are not deltified in the pack, and + + SHA1 type size offset-in-packfile depth base-SHA1 + + for objects that are deltified. + +Author +------ +Written by Junio C Hamano <junkio@cox.net> + +Documentation +-------------- +Documentation by Junio C Hamano + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-verify-tag.txt b/Documentation/git-verify-tag.txt new file mode 100644 index 0000000000..b8a73c47af --- /dev/null +++ b/Documentation/git-verify-tag.txt @@ -0,0 +1,32 @@ +git-verify-tag(1) +================= + +NAME +---- +git-verify-tag - Check the GPG signature of tag. + +SYNOPSIS +-------- +'git-verify-tag' <tag> + +DESCRIPTION +----------- +Validates the gpg signature created by git-tag. + +OPTIONS +------- +<tag>:: + SHA1 identifier of a git tag object. + +Author +------ +Written by Jan Harkes <jaharkes@cs.cmu.edu> and Eric W. Biederman <ebiederm@xmission.com> + +Documentation +-------------- +Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-whatchanged.txt b/Documentation/git-whatchanged.txt new file mode 100644 index 0000000000..056a9697c6 --- /dev/null +++ b/Documentation/git-whatchanged.txt @@ -0,0 +1,61 @@ +git-whatchanged(1) +================== +v0.99.4, Aug 2005 + +NAME +---- +git-whatchanged - Show logs with difference each commit introduces. + + +SYNOPSIS +-------- +'git whatchanged' <option>... + +DESCRIPTION +----------- +Shows commit logs and diff output each commit introduces. The +command internally invokes 'git-rev-list' piped to +'git-diff-tree', and takes command line options for both of +these commands. + +This manual page describes only the most frequently used options. + + +OPTIONS +------- +-p:: + Show textual diffs, instead of the git internal diff + output format that is useful only to tell the changed + paths and their nature of changes. + +--max-count=<n>:: + Limit output to <n> commits. + +<since>..<until>:: + Limit output to between the two named commits (bottom + exclusive, top inclusive). + +-r:: + Show git internal diff output, but for the whole tree, + not just the top level. + +--pretty=<format>:: + Controls the output format for the commit logs. + <format> can be one of 'raw', 'medium', 'short', 'full', + and 'oneline'. + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> and +Junio C Hamano <junkio@cox.net> + + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-write-tree.txt b/Documentation/git-write-tree.txt new file mode 100644 index 0000000000..71e16d128a --- /dev/null +++ b/Documentation/git-write-tree.txt @@ -0,0 +1,43 @@ +git-write-tree(1) +================= +v0.1, May 2005 + +NAME +---- +git-write-tree - Creates a tree object from the current cache + + +SYNOPSIS +-------- +'git-write-tree' [--missing-ok] + +DESCRIPTION +----------- +Creates a tree object using the current cache. + +The cache must be merged. + +Conceptually, "git-write-tree" sync()s the current directory cache contents +into a set of tree files. +In order to have that match what is actually in your directory right +now, you need to have done a "git-update-index" phase before you did the +"git-write-tree". + +OPTIONS +------- +--missing-ok:: + Normally "git-write-tree" ensures that the objects referenced by the + directory exist in the object database. This option disables this check. + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git.txt b/Documentation/git.txt new file mode 100644 index 0000000000..e141021279 --- /dev/null +++ b/Documentation/git.txt @@ -0,0 +1,531 @@ +git(7) +====== +v0.99.6, Sep 2005 + +NAME +---- +git - the stupid content tracker + + +SYNOPSIS +-------- +'git-<command>' <args> + +DESCRIPTION +----------- + +This is reference information for the core git commands. + +Before reading this cover to cover, you may want to take a look +at the link:tutorial.html[tutorial] document. + +The <<Discussion>> section below contains much useful definition and +clarification info - read that first. And of the commands, I suggest +reading gitlink:git-update-index[1] and +gitlink:git-read-tree[1] first - I wish I had! + +If you are migrating from CVS, link:cvs-migration.html[cvs migration] +document may be helpful after you finish the tutorial. + +After you get the general feel from the tutorial and this +overview page, you may want to take a look at the +link:howto-index.html[howto] documents. + + +David Greaves <david@dgreaves.com> +08/05/05 + +Updated by Junio C Hamano <junkio@cox.net> on 2005-05-05 to +reflect recent changes. + +Commands Overview +----------------- +The git commands can helpfully be split into those that manipulate +the repository, the cache and the working fileset, those that +interrogate and compare them, and those that moves objects and +references between repositories. + +In addition, git itself comes with a spartan set of porcelain +commands. They are usable but are not meant to compete with real +Porcelains. + +There are also some ancillary programs that can be viewed as useful +aids for using the core commands but which are unlikely to be used by +SCMs layered over git. + +Manipulation commands +~~~~~~~~~~~~~~~~~~~~~ +gitlink:git-apply[1]:: + Reads a "diff -up1" or git generated patch file and + applies it to the working tree. + +gitlink:git-checkout-index[1]:: + Copy files from the cache to the working directory + Previously this command was known as git-checkout-cache. + +gitlink:git-commit-tree[1]:: + Creates a new commit object + +gitlink:git-hash-object[1]:: + Computes the object ID from a file. + +gitlink:git-init-db[1]:: + Creates an empty git object database + +gitlink:git-merge-index[1]:: + Runs a merge for files needing merging + Previously this command was known as git-merge-cache. + +gitlink:git-mktag[1]:: + Creates a tag object + +gitlink:git-pack-objects[1]:: + Creates a packed archive of objects. + +gitlink:git-prune-packed[1]:: + Remove extra objects that are already in pack files. + +gitlink:git-read-tree[1]:: + Reads tree information into the directory cache + +gitlink:git-unpack-objects[1]:: + Unpacks objects out of a packed archive. + +gitlink:git-update-index[1]:: + Modifies the index or directory cache + Previously this command was known as git-update-cache. + +gitlink:git-write-tree[1]:: + Creates a tree from the current cache + + +Interrogation commands +~~~~~~~~~~~~~~~~~~~~~~ + +gitlink:git-cat-file[1]:: + Provide content or type information for repository objects + +gitlink:git-diff-index[1]:: + Compares content and mode of blobs between the cache and repository + Previously this command was known as git-diff-cache. + +gitlink:git-diff-files[1]:: + Compares files in the working tree and the cache + +gitlink:git-diff-stages[1]:: + Compares two "merge stages" in the index file. + +gitlink:git-diff-tree[1]:: + Compares the content and mode of blobs found via two tree objects + +gitlink:git-fsck-objects[1]:: + Verifies the connectivity and validity of the objects in the database + Previously this command was known as git-fsck-cache. + +gitlink:git-ls-files[1]:: + Information about files in the cache/working directory + +gitlink:git-ls-tree[1]:: + Displays a tree object in human readable form + +gitlink:git-merge-base[1]:: + Finds as good a common ancestor as possible for a merge + +gitlink:git-rev-list[1]:: + Lists commit objects in reverse chronological order + +gitlink:git-show-index[1]:: + Displays contents of a pack idx file. + +gitlink:git-tar-tree[1]:: + Creates a tar archive of the files in the named tree + +gitlink:git-unpack-file[1]:: + Creates a temporary file with a blob's contents + +gitlink:git-var[1]:: + Displays a git logical variable + +gitlink:git-verify-pack[1]:: + Validates packed GIT archive files + +The interrogate commands may create files - and you can force them to +touch the working file set - but in general they don't + + +Synching repositories +~~~~~~~~~~~~~~~~~~~~~ + +gitlink:git-clone-pack[1]:: + Clones a repository into the current repository (engine + for ssh and local transport) + +gitlink:git-fetch-pack[1]:: + Updates from a remote repository. + +gitlink:git-http-fetch[1]:: + Downloads a remote GIT repository via HTTP + Previously this command was known as git-http-pull. + +gitlink:git-local-fetch[1]:: + Duplicates another GIT repository on a local system + Previously this command was known as git-local-pull. + +gitlink:git-peek-remote[1]:: + Lists references on a remote repository using upload-pack protocol. + +gitlink:git-receive-pack[1]:: + Invoked by 'git-send-pack' to receive what is pushed to it. + +gitlink:git-send-pack[1]:: + Pushes to a remote repository, intelligently. + +gitlink:git-ssh-fetch[1]:: + Pulls from a remote repository over ssh connection + Previously this command was known as git-ssh-pull. + +gitlink:git-ssh-upload[1]:: + Helper "server-side" program used by git-ssh-fetch + Previously this command was known as git-ssh-push. + +gitlink:git-update-server-info[1]:: + Updates auxiliary information on a dumb server to help + clients discover references and packs on it. + +gitlink:git-upload-pack[1]:: + Invoked by 'git-clone-pack' and 'git-fetch-pack' to push + what are asked for. + + +Porcelain-ish Commands +---------------------- + +gitlink:git-add[1]:: + Add paths to the index file. + Previously this command was known as git-add-script. + +gitlink:git-applymbox[1]:: + Apply patches from a mailbox. + +gitlink:git-bisect[1]:: + Find the change that introduced a bug. + Previously this command was known as git-bisect-script. + +gitlink:git-branch[1]:: + Create and Show branches. + Previously this command was known as git-branch-script. + +gitlink:git-checkout[1]:: + Checkout and switch to a branch. + Previously this command was known as git-checkout-script. + +gitlink:git-cherry-pick[1]:: + Cherry-pick the effect of an existing commit. + Previously this command was known as git-cherry-pick-script. + +gitlink:git-clone[1]:: + Clones a repository into a new directory. + Previously this command was known as git-clone-script. + +gitlink:git-commit[1]:: + Record changes to the repository. + Previously this command was known as git-commit-script. + +gitlink:git-diff[1]:: + Show changes between commits, commit and working tree, etc. + Previously this command was known as git-diff-script. + +gitlink:git-fetch[1]:: + Download from a remote repository via various protocols. + Previously this command was known as git-fetch-script. + +gitlink:git-format-patch[1]:: + Prepare patches for e-mail submission. + Previously this command was known as git-format-patch-script. + +gitlink:git-grep[1]:: + Print lines matching a pattern + +gitlink:git-log[1]:: + Shows commit logs. + Previously this command was known as git-log-script. + +gitlink:git-ls-remote[1]:: + Shows references in a remote or local repository. + Previously this command was known as git-ls-remote-script. + +gitlink:git-merge[1]:: + Grand unified merge driver. + +gitlink:git-octopus[1]:: + Merge more than two commits. + Previously this command was known as git-octopus-script. + +gitlink:git-pull[1]:: + Fetch from and merge with a remote repository. + Previously this command was known as git-pull-script. + +gitlink:git-push[1]:: + Update remote refs along with associated objects. + Previously this command was known as git-push-script. + +gitlink:git-rebase[1]:: + Rebase local commits to new upstream head. + Previously this command was known as git-rebase-script. + +gitlink:git-rename[1]:: + Rename files and directories. + Previously this command was known as git-rename-script. + +gitlink:git-repack[1]:: + Pack unpacked objects in a repository. + Previously this command was known as git-repack-script. + +gitlink:git-reset[1]:: + Reset current HEAD to the specified state. + Previously this command was known as git-reset-script. + +gitlink:git-resolve[1]:: + Merge two commits. + Previously this command was known as git-resolve-script. + +gitlink:git-revert[1]:: + Revert an existing commit. + Previously this command was known as git-revert-script. + +gitlink:git-shortlog[1]:: + Summarizes 'git log' output. + +gitlink:git-show-branch[1]:: + Show branches and their commits. + +gitlink:git-status[1]:: + Shows the working tree status. + Previously this command was known as git-status-script. + +gitlink:git-verify-tag[1]:: + Check the GPG signature of tag. + Previously this command was known as git-verify-tag-script. + +gitlink:git-whatchanged[1]:: + Shows commit logs and differences they introduce. + + +Ancillary Commands +------------------ +Manipulators: + +gitlink:git-applypatch[1]:: + Apply one patch extracted from an e-mail. + +gitlink:git-archimport[1]:: + Import an arch repository into git. + Previously this command was known as git-archimport-script. + +gitlink:git-convert-objects[1]:: + Converts old-style GIT repository + Previously this command was known as git-convert-cache. + +gitlink:git-cvsimport[1]:: + Salvage your data out of another SCM people love to hate. + Previously this command was known as git-cvsimport-script. + +gitlink:git-merge-one-file[1]:: + The standard helper program to use with "git-merge-index" + Previously this command was known as git-merge-one-file-script. + +gitlink:git-prune[1]:: + Prunes all unreachable objects from the object database + Previously this command was known as git-prune-script. + +gitlink:git-relink[1]:: + Hardlink common objects in local repositories. + Previously this command was known as git-relink-script. + +gitlink:git-sh-setup[1]:: + Common git shell script setup code. + Previously this command was known as git-sh-setup-script. + +gitlink:git-tag[1]:: + An example script to create a tag object signed with GPG + Previously this command was known as git-tag-script. + + +Interrogators: + +gitlink:git-cherry[1]:: + Find commits not merged upstream. + +gitlink:git-count-objects[1]:: + Count unpacked number of objects and their disk consumption. + Previously this command was known as git-count-objects-script. + +gitlink:git-daemon[1]:: + A really simple server for GIT repositories. + +gitlink:git-get-tar-commit-id[1]:: + Extract commit ID from an archive created using git-tar-tree. + +gitlink:git-mailinfo[1]:: + Extracts patch from a single e-mail message. + +gitlink:git-mailsplit[1]:: + git-mailsplit. + +gitlink:git-patch-id[1]:: + Compute unique ID for a patch. + +gitlink:git-parse-remote[1]:: + Routines to help parsing $GIT_DIR/remotes/ + Previously this command was known as git-parse-remote-script. + +gitlink:git-request-pull[1]:: + git-request-pull. + Previously this command was known as git-request-pull-script. + +gitlink:git-rev-parse[1]:: + Pick out and massage parameters. + +gitlink:git-send-email[1]:: + Send patch e-mails out of "format-patch --mbox" output. + Previously this command was known as git-send-email-script. + +gitlink:git-stripspace[1]:: + Filter out empty lines. + + +Commands not yet documented +--------------------------- + +gitlink:gitk[1]:: + gitk. + + +Identifier Terminology +---------------------- +<object>:: + Indicates the sha1 identifier for any type of object + +<blob>:: + Indicates a blob object sha1 identifier + +<tree>:: + Indicates a tree object sha1 identifier + +<commit>:: + Indicates a commit object sha1 identifier + +<tree-ish>:: + Indicates a tree, commit or tag object sha1 identifier. A + command that takes a <tree-ish> argument ultimately wants to + operate on a <tree> object but automatically dereferences + <commit> and <tag> objects that point at a <tree>. + +<type>:: + Indicates that an object type is required. + Currently one of: blob/tree/commit/tag + +<file>:: + Indicates a filename - always relative to the root of + the tree structure GIT_INDEX_FILE describes. + +Symbolic Identifiers +-------------------- +Any git command accepting any <object> can also use the following +symbolic notation: + +HEAD:: + indicates the head of the repository (ie the contents of + `$GIT_DIR/HEAD`) +<tag>:: + a valid tag 'name'+ + (ie the contents of `$GIT_DIR/refs/tags/<tag>`) +<head>:: + a valid head 'name'+ + (ie the contents of `$GIT_DIR/refs/heads/<head>`) +<snap>:: + a valid snapshot 'name'+ + (ie the contents of `$GIT_DIR/refs/snap/<snap>`) + + +File/Directory Structure +------------------------ + +Please see link:repository-layout.html[repository layout] document. + +Higher level SCMs may provide and manage additional information in the +GIT_DIR. + + +Terminology +----------- +Please see link:glossary.html[glossary] document. + + +Environment Variables +--------------------- +Various git commands use the following environment variables: + +The git Repository +~~~~~~~~~~~~~~~~~~ +These environment variables apply to 'all' core git commands. Nb: it +is worth noting that they may be used/overridden by SCMS sitting above +git so take care if using Cogito etc + +'GIT_INDEX_FILE':: + This environment allows the specification of an alternate + cache/index file. If not specified, the default of + `$GIT_DIR/index` is used. + +'GIT_OBJECT_DIRECTORY':: + If the object storage directory is specified via this + environment variable then the sha1 directories are created + underneath - otherwise the default `$GIT_DIR/objects` + directory is used. + +'GIT_ALTERNATE_OBJECT_DIRECTORIES':: + Due to the immutable nature of git objects, old objects can be + archived into shared, read-only directories. This variable + specifies a ":" separated list of git object directories which + can be used to search for git objects. New objects will not be + written to these directories. + +'GIT_DIR':: + If the 'GIT_DIR' environment variable is set then it specifies + a path to use instead of `./.git` for the base of the + repository. + +git Commits +~~~~~~~~~~~ +'GIT_AUTHOR_NAME':: +'GIT_AUTHOR_EMAIL':: +'GIT_AUTHOR_DATE':: +'GIT_COMMITTER_NAME':: +'GIT_COMMITTER_EMAIL':: + see gitlink:git-commit-tree[1] + +git Diffs +~~~~~~~~~ +'GIT_DIFF_OPTS':: +'GIT_EXTERNAL_DIFF':: + see the "generating patches" section in : + gitlink:git-diff-index[1]; + gitlink:git-diff-files[1]; + gitlink:git-diff-tree[1] + +Discussion[[Discussion]] +------------------------ +include::../README[] + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> and the git-list <git@vger.kernel.org>. + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/gitk.txt b/Documentation/gitk.txt new file mode 100644 index 0000000000..e5ef6d6f47 --- /dev/null +++ b/Documentation/gitk.txt @@ -0,0 +1,38 @@ +gitk(1) +======= + +NAME +---- +gitk - Some git command not yet documented. + + +SYNOPSIS +-------- +'gitk' [ --option ] <args>... + +DESCRIPTION +----------- +Does something not yet documented. + + +OPTIONS +------- +--option:: + Some option not yet documented. + +<args>...:: + Some argument not yet documented. + + +Author +------ +Written by Paul Mackerras <paulus@samba.org> + +Documentation +-------------- +Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/glossary.txt b/Documentation/glossary.txt new file mode 100644 index 0000000000..a069b7bb0c --- /dev/null +++ b/Documentation/glossary.txt @@ -0,0 +1,242 @@ +object:: + The unit of storage in GIT. It is uniquely identified by + the SHA1 of its contents. Consequently, an object can not + be changed. + +object name:: + The unique identifier of an object. The hash of the object's contents + using the Secure Hash Algorithm 1 and usually represented by the 40 + character hexadecimal encoding of the hash of the object (possibly + followed by a white space). + +SHA1:: + Synonym for object name. + +object identifier:: + Synonym for object name. + +hash:: + In git's context, synonym to object name. + +object database:: + Stores a set of "objects", and an individial object is identified + by its object name. The object usually live in $GIT_DIR/objects/. + +blob object:: + Untyped object, e.g. the contents of a file. + +tree object:: + An object containing a list of file names and modes along with refs + to the associated blob and/or tree objects. A tree is equivalent + to a directory. + +tree:: + Either a working tree, or a tree object together with the + dependent blob and tree objects (i.e. a stored representation + of a working tree). + +DAG:: + Directed acyclic graph. The commit objects form a directed acyclic + graph, because they have parents (directed), and the graph of commit + objects is acyclic (there is no chain which begins and ends with the + same object). + +index:: + A collection of files with stat information, whose contents are + stored as objects. The cache is a stored version of your working + tree. Truth be told, it can also contain a second, and even a third + version of a working tree, which are used when merging. + +index entry:: + The information regarding a particular file, stored in the index. + An index entry can be unmerged, if a merge was started, but not + yet finished (i.e. if the cache contains multiple versions of + that file). + +unmerged index: + An index which contains unmerged index entries. + +cache:: + Obsolete for: index. + +working tree:: + The set of files and directories currently being worked on, + i.e. you can work in your working tree without using git at all. + +directory:: + The list you get with "ls" :-) + +revision:: + A particular state of files and directories which was stored in + the object database. It is referenced by a commit object. + +checkout:: + The action of updating the working tree to a revision which was + stored in the object database. + +commit:: + As a verb: The action of storing the current state of the cache in the + object database. The result is a revision. + As a noun: Short hand for commit object. + +commit object:: + An object which contains the information about a particular + revision, such as parents, committer, author, date and the + tree object which corresponds to the top directory of the + stored revision. + +parent:: + A commit object contains a (possibly empty) list of the logical + predecessor(s) in the line of development, i.e. its parents. + +changeset:: + BitKeeper/cvsps speak for "commit". Since git does not store + changes, but states, it really does not make sense to use + the term "changesets" with git. + +clean:: + A working tree is clean, if it corresponds to the revision + referenced by the current head. + +dirty:: + A working tree is said to be dirty if it contains modifications + which have not been committed to the current branch. + +head:: + The top of a branch. It contains a ref to the corresponding + commit object. + +branch:: + A non-cyclical graph of revisions, i.e. the complete history of + a particular revision, which is called the branch head. The + branch heads are stored in $GIT_DIR/refs/heads/. + +ref:: + A 40-byte hex representation of a SHA1 pointing to a particular + object. These may be stored in $GIT_DIR/refs/. + +head ref:: + A ref pointing to a head. Often, this is abbreviated to "head". + Head refs are stored in $GIT_DIR/refs/heads/. + +tree-ish:: + A ref pointing to either a commit object, a tree object, or a + tag object pointing to a tag or commit or tree object. + +ent:: + Favorite synonym to "tree-ish" by some total geeks. See + http://en.wikipedia.org/wiki/Ent_(Middle-earth) for an in-depth + explanation. + +tag object:: + An object containing a ref pointing to another object, which can + contain a message just like a commit object. It can also + contain a (PGP) signature, in which case it is called a "signed + tag object". + +tag:: + A ref pointing to a tag or commit object. In contrast to a head, + a tag is not changed by a commit. Tags (not tag objects) are + stored in $GIT_DIR/refs/tags/. A git tag has nothing to do with + a Lisp tag (which is called object type in git's context). + A tag is most typically used to mark a particular point in the + commit ancestry chain. + +merge:: + To merge branches means to try to accumulate the changes since a + common ancestor and apply them to the first branch. An automatic + merge uses heuristics to accomplish that. Evidently, an automatic + merge can fail. + +octopus:: + To merge more than two branches. Also denotes an intelligent + predator. + +resolve:: + The action of fixing up manually what a failed automatic merge + left behind. + +rewind:: + To throw away part of the development, i.e. to assign the head to + an earlier revision. + +rebase:: + To clean a branch by starting from the head of the main line of + development ("master"), and reapply the (possibly cherry-picked) + changes from that branch. + +repository:: + A collection of refs together with an object database containing + all objects, which are reachable from the refs, possibly accompanied + by meta data from one or more porcelains. A repository can + share an object database with other repositories. + +git archive:: + Synonym for repository (for arch people). + +file system:: + Linus Torvalds originally designed git to be a user space file + system, i.e. the infrastructure to hold files and directories. + That ensured the efficiency and speed of git. + +alternate object database:: + Via the alternates mechanism, a repository can inherit part of its + object database from another object database, which is called + "alternate". + +reachable:: + An object is reachable from a ref/commit/tree/tag, if there is a + chain leading from the latter to the former. + +chain:: + A list of objects, where each object in the list contains a + reference to its successor (for example, the successor of a commit + could be one of its parents). + +fetch:: + Fetching a branch means to get the branch's head ref from a + remote repository, to find out which objects are missing from + the local object database, and to get them, too. + +pull:: + Pulling a branch means to fetch it and merge it. + +push:: + Pushing a branch means to get the branch's head ref from a remote + repository, find out if it is an ancestor to the branch's local + head ref is a direct, and in that case, putting all objects, which + are reachable from the local head ref, and which are missing from + the remote repository, into the remote object database, and updating + the remote head ref. If the remote head is not an ancestor to the + local head, the push fails. + +pack:: + A set of objects which have been compressed into one file (to save + space or to transmit them efficiently). + +pack index:: + The list of identifiers, and other information, of the objects in a + pack, to assist in efficiently accessing the contents of a pack. + +core git:: + Fundamental data structures and utilities of git. Exposes only + limited source code management tools. + +plumbing:: + Cute name for core git. + +porcelain:: + Cute name for programs and program suites depending on core git, + presenting a high level access to core git. Porcelains expose + more of a SCM interface than the plumbing. + +object type: + One of the identifiers "commit","tree","tag" and "blob" describing + the type of an object. + +SCM:: + Source code management (tool). + +dircache:: + You are *waaaaay* behind. + diff --git a/Documentation/hooks.txt b/Documentation/hooks.txt new file mode 100644 index 0000000000..57f4720871 --- /dev/null +++ b/Documentation/hooks.txt @@ -0,0 +1,128 @@ +Hooks used by GIT +================= +v0.99.6, Sep 2005 + +Hooks are little scripts you can place in `$GIT_DIR/hooks` +directory to trigger action at certain points. When +`git-init-db` is run, a handful example hooks are copied in the +`hooks` directory of the new repository, but by default they are +all disabled. To enable a hook, make it executable with `chmod ++x`. + +This document describes the currently defined hooks. + +applypatch-msg +-------------- + +This hook is invoked by `git-applypatch` script, which is +typically invoked by `git-applymbox`. It takes a single +parameter, the name of the file that holds the proposed commit +log message. Exiting with non-zero status causes the +'git-applypatch' to abort before applying the patch. + +The hook is allowed to edit the message file in place, and can +be used to normalize the message into some project standard +format (if the project has one). It can also be used to refuse +the commit after inspecting the message file. + +The default applypatch-msg hook, when enabled, runs the +commit-msg hook, if the latter is enabled. + +pre-applypatch +-------------- + +This hook is invoked by `git-applypatch` script, which is +typically invoked by `git-applymbox`. It takes no parameter, +and is invoked after the patch is applied, but before a commit +is made. Exiting with non-zero status causes the working tree +after application of the patch not committed. + +It can be used to inspect the current working tree and refuse to +make a commit if it does not pass certain test. + +The default pre-applypatch hook, when enabled, runs the +pre-commit hook, if the latter is enabled. + +post-applypatch +--------------- + +This hook is invoked by `git-applypatch` script, which is +typically invoked by `git-applymbox`. It takes no parameter, +and is invoked after the patch is applied and a commit is made. + +This hook is meant primarily for notification, and cannot affect +the outcome of `git-applypatch`. + +pre-commit +---------- + +This hook is invoked by `git-commit`, and can be bypassed +with `\--no-verify` option. It takes no parameter, and is +invoked before obtaining the proposed commit log message and +making a commit. Exiting with non-zero status from this script +causes the `git-commit` to abort. + +The default pre-commit hook, when enabled, catches introduction +of lines with trailing whitespaces and aborts the commit when +a such line is found. + +commit-msg +---------- + +This hook is invoked by `git-commit`, and can be bypassed +with `\--no-verify` option. It takes a single parameter, the +name of the file that holds the proposed commit log message. +Exiting with non-zero status causes the `git-commit` to +abort. + +The hook is allowed to edit the message file in place, and can +be used to normalize the message into some project standard +format (if the project has one). It can also be used to refuse +the commit after inspecting the message file. + +The default commit-msg hook, when enabled, detects duplicate +Signed-off-by: lines, and aborts the commit when one is found. + +post-commit +----------- + +This hook is invoked by `git-commit`. It takes no +parameter, and is invoked after a commit is made. + +This hook is meant primarily for notification, and cannot affect +the outcome of `git-commit`. + +The default post-commit hook, when enabled, demonstrates how to +send out a commit notification e-mail. + +update +------ + +This hook is invoked by `git-receive-pack`, which is invoked +when a `git push` is done against the repository. It takes +three parameters, name of the ref being updated, old object name +stored in the ref, and the new objectname to be stored in the +ref. Exiting with non-zero status from this hook prevents +`git-receive-pack` from updating the ref. + +This can be used to prevent 'forced' update on certain refs by +making sure that the object name is a commit object that is a +descendant of the commit object named by the old object name. +Another use suggested on the mailing list is to use this hook to +implement access control which is finer grained than the one +based on filesystem group. + +post-update +----------- + +This hook is invoked by `git-receive-pack`, which is invoked +when a `git push` is done against the repository. It takes +variable number of parameters; each of which is the name of ref +that was actually updated. + +This hook is meant primarily for notification, and cannot affect +the outcome of `git-receive-pack`. + +The default post-update hook, when enabled, runs +`git-update-server-info` to keep the information used by dumb +transport up-to-date. diff --git a/Documentation/howto-index.sh b/Documentation/howto-index.sh new file mode 100755 index 0000000000..34aa30c5b9 --- /dev/null +++ b/Documentation/howto-index.sh @@ -0,0 +1,56 @@ +#!/bin/sh + +cat <<\EOF +GIT Howto Index +=============== + +Here is a collection of mailing list postings made by various +people describing how they use git in their workflow. + +EOF + +for txt +do + title=`expr "$txt" : '.*/\(.*\)\.txt$'` + from=`sed -ne ' + /^$/q + /^From:[ ]/{ + s/// + s/^[ ]*// + s/[ ]*$// + s/^/by / + p + } + ' "$txt"` + + abstract=`sed -ne ' + /^Abstract:[ ]/{ + s/^[^ ]*// + x + s/.*// + x + : again + /^[ ]/{ + s/^[ ]*// + H + n + b again + } + x + p + q + }' "$txt"` + + if grep 'Content-type: text/asciidoc' >/dev/null $txt + then + file=`expr "$txt" : '\(.*\)\.txt$'`.html + else + file="$txt" + fi + + echo "* link:$file[$title] $from +$abstract + +" + +done diff --git a/Documentation/howto/make-dist.txt b/Documentation/howto/make-dist.txt new file mode 100644 index 0000000000..00e330b293 --- /dev/null +++ b/Documentation/howto/make-dist.txt @@ -0,0 +1,52 @@ +Date: Fri, 12 Aug 2005 22:39:48 -0700 (PDT) +From: Linus Torvalds <torvalds@osdl.org> +To: Dave Jones <davej@redhat.com> +cc: git@vger.kernel.org +Subject: Re: Fwd: Re: git checkout -f branch doesn't remove extra files +Abstract: In this article, Linus talks about building a tarball, + incremental patch, and ChangeLog, given a base release and two + rc releases, following the convention of giving the patch from + the base release and the latest rc, with ChangeLog between the + last rc and the latest rc. + +On Sat, 13 Aug 2005, Dave Jones wrote: +> +> > Git actually has a _lot_ of nifty tools. I didn't realize that people +> > didn't know about such basic stuff as "git-tar-tree" and "git-ls-files". +> +> Maybe its because things are moving so fast :) Or maybe I just wasn't +> paying attention on that day. (I even read the git changes via RSS, +> so I should have no excuse). + +Well, git-tar-tree has been there since late April - it's actually one of +those really early commands. I'm pretty sure the RSS feed came later ;) + +I use it all the time in doing releases, it's a lot faster than creating a +tar tree by reading the filesystem (even if you don't have to check things +out). A hidden pearl. + +This is my crappy "release-script": + + [torvalds@g5 ~]$ cat bin/release-script + #!/bin/sh + stable="$1" + last="$2" + new="$3" + echo "# git-tag v$new" + echo "git-tar-tree v$new linux-$new | gzip -9 > ../linux-$new.tar.gz" + echo "git-diff-tree -p v$stable v$new | gzip -9 > ../patch-$new.gz" + echo "git-rev-list --pretty v$new ^v$last > ../ChangeLog-$new" + echo "git-rev-list --pretty=short v$new ^v$last | git-shortlog > ../ShortLog" + echo "git-diff-tree -p v$last v$new | git-apply --stat > ../diffstat-$new" + +and when I want to do a new kernel release I literally first tag it, and +then do + + release-script 2.6.12 2.6.13-rc6 2.6.13-rc7 + +and check that things look sane, and then just cut-and-paste the commands. + +Yeah, it's stupid. + + Linus + diff --git a/Documentation/howto/rebase-and-edit.txt b/Documentation/howto/rebase-and-edit.txt new file mode 100644 index 0000000000..6cc1c7921f --- /dev/null +++ b/Documentation/howto/rebase-and-edit.txt @@ -0,0 +1,81 @@ +Date: Sat, 13 Aug 2005 22:16:02 -0700 (PDT) +From: Linus Torvalds <torvalds@osdl.org> +To: Steve French <smfrench@austin.rr.com> +cc: git@vger.kernel.org +Subject: Re: sending changesets from the middle of a git tree +Abstract: In this article, Linus demonstrates how a broken commit + in a sequence of commits can be removed by rewinding the head and + reapplying selected changes. + +On Sat, 13 Aug 2005, Linus Torvalds wrote: + +> That's correct. Same things apply: you can move a patch over, and create a +> new one with a modified comment, but basically the _old_ commit will be +> immutable. + +Let me clarify. + +You can entirely _drop_ old branches, so commits may be immutable, but +nothing forces you to keep them. Of course, when you drop a commit, you'll +always end up dropping all the commits that depended on it, and if you +actually got somebody else to pull that commit you can't drop it from +_their_ repository, but undoing things is not impossible. + +For example, let's say that you've made a mess of things: you've committed +three commits "old->a->b->c", and you notice that "a" was broken, but you +want to save "b" and "c". What you can do is + + # Create a branch "broken" that is the current code + # for reference + git branch broken + + # Reset the main branch to three parents back: this + # effectively undoes the three top commits + git reset HEAD^^^ + git checkout -f + + # Check the result visually to make sure you know what's + # going on + gitk --all + + # Re-apply the two top ones from "broken" + # + # First "parent of broken" (aka b): + git-diff-tree -p broken^ | git-apply --index + git commit --reedit=broken^ + + # Then "top of broken" (aka c): + git-diff-tree -p broken | git-apply --index + git commit --reedit=broken + +and you've now re-applied (and possibly edited the comments) the two +commits b/c, and commit "a" is basically gone (it still exists in the +"broken" branch, of course). + +Finally, check out the end result again: + + # Look at the new commit history + gitk --all + +to see that everything looks sensible. + +And then, you can just remove the broken branch if you decide you really +don't want it: + + # remove 'broken' branch + rm .git/refs/heads/broken + + # Prune old objects if you're really really sure + git prune + +And yeah, I'm sure there are other ways of doing this. And as usual, the +above is totally untested, and I just wrote it down in this email, so if +I've done something wrong, you'll have to figure it out on your own ;) + + Linus +- +To unsubscribe from this list: send the line "unsubscribe git" in +the body of a message to majordomo@vger.kernel.org +More majordomo info at http://vger.kernel.org/majordomo-info.html + + diff --git a/Documentation/howto/rebase-from-internal-branch.txt b/Documentation/howto/rebase-from-internal-branch.txt new file mode 100644 index 0000000000..b2c021d917 --- /dev/null +++ b/Documentation/howto/rebase-from-internal-branch.txt @@ -0,0 +1,168 @@ +From: Junio C Hamano <junkio@cox.net> +To: git@vger.kernel.org +Cc: Petr Baudis <pasky@suse.cz>, Linus Torvalds <torvalds@osdl.org> +Subject: Re: sending changesets from the middle of a git tree +Date: Sun, 14 Aug 2005 18:37:39 -0700 +Abstract: In this article, JC talks about how he rebases the + public "pu" branch using the core GIT tools when he updates + the "master" branch, and how "rebase" works. Also discussed + is how this applies to individual developers who sends patches + upstream. + +Petr Baudis <pasky@suse.cz> writes: + +> Dear diary, on Sun, Aug 14, 2005 at 09:57:13AM CEST, I got a letter +> where Junio C Hamano <junkio@cox.net> told me that... +>> Linus Torvalds <torvalds@osdl.org> writes: +>> +>> > Junio, maybe you want to talk about how you move patches from your "pu" +>> > branch to the real branches. +>> +> Actually, wouldn't this be also precisely for what StGIT is intended to? + +Exactly my feeling. I was sort of waiting for Catalin to speak +up. With its basing philosophical ancestry on quilt, this is +the kind of task StGIT is designed to do. + +I just have done a simpler one, this time using only the core +GIT tools. + +I had a handful commits that were ahead of master in pu, and I +wanted to add some documentation bypassing my usual habit of +placing new things in pu first. At the beginning, the commit +ancestry graph looked like this: + + *"pu" head + master --> #1 --> #2 --> #3 + +So I started from master, made a bunch of edits, and committed: + + $ git checkout master + $ cd Documentation; ed git.txt ... + $ cd ..; git add Documentation/*.txt + $ git commit -s -v + +NOTE. The -v flag to commit is a handy way to make sure that +your additions are not introducing bogusly formatted lines. + +After the commit, the ancestry graph would look like this: + + *"pu" head + master^ --> #1 --> #2 --> #3 + \ + \---> master + +The old master is now master^ (the first parent of the master). +The new master commit holds my documentation updates. + +Now I have to deal with "pu" branch. + +This is the kind of situation I used to have all the time when +Linus was the maintainer and I was a contributor, when you look +at "master" branch being the "maintainer" branch, and "pu" +branch being the "contributor" branch. Your work started at the +tip of the "maintainer" branch some time ago, you made a lot of +progress in the meantime, and now the maintainer branch has some +other commits you do not have yet. And "git rebase" was written +with the explicit purpose of helping to maintain branches like +"pu". You _could_ merge master to pu and keep going, but if you +eventually want to cherrypick and merge some but not necessarily +all changes back to the master branch, it often makes later +operations for _you_ easier if you rebase (i.e. carry forward +your changes) "pu" rather than merge. So I ran "git rebase": + + $ git checkout pu + $ git rebase master pu + +What this does is to pick all the commits since the current +branch (note that I now am on "pu" branch) forked from the +master branch, and forward port these changes. + + master^ --> #1 --> #2 --> #3 + \ *"pu" head + \---> master --> #1' --> #2' --> #3' + +The diff between master^ and #1 is applied to master and +committed to create #1' commit with the commit information (log, +author and date) taken from commit #1. On top of that #2' and #3' +commits are made similarly out of #2 and #3 commits. + +Old #3 is not recorded in any of the .git/refs/heads/ file +anymore, so after doing this you will have dangling commit if +you ran fsck-cache, which is normal. After testing "pu", you +can run "git prune" to get rid of those original three commits. + +While I am talking about "git rebase", I should talk about how +to do cherrypicking using only the core GIT tools. + +Let's go back to the earlier picture, with different labels. + +You, as an individual developer, cloned upstream repository and +amde a couple of commits on top of it. + + *your "master" head + upstream --> #1 --> #2 --> #3 + +You would want changes #2 and #3 incorporated in the upstream, +while you feel that #1 may need further improvements. So you +prepare #2 and #3 for e-mail submission. + + $ git format-patch master^^ master + +This creates two files, 0001-XXXX.txt and 0002-XXXX.txt. Send +them out "To: " your project maintainer and "Cc: " your mailing +list. You could use contributed script git-send-email if +your host has necessary perl modules for this, but your usual +MUA would do as long as it does not corrupt whitespaces in the +patch. + +Then you would wait, and you find out that the upstream picked +up your changes, along with other changes. + + where *your "master" head + upstream --> #1 --> #2 --> #3 + used \ + to be \--> #A --> #2' --> #3' --> #B --> #C + *upstream head + +The two commits #2' and #3' in the above picture record the same +changes your e-mail submission for #2 and #3 contained, but +probably with the new sign-off line added by the upsteam +maintainer and definitely with different committer and ancestry +information, they are different objects from #2 and #3 commits. + +You fetch from upstream, but not merge. + + $ git fetch upstream + +This leaves the updated upstream head in .git/FETCH_HEAD but +does not touch your .git/HEAD nor .git/refs/heads/master. +You run "git rebase" now. + + $ git rebase FETCH_HEAD master + +Earlier, I said that rebase applies all the commits from your +branch on top of the upstream head. Well, I lied. "git rebase" +is a bit smarter than that and notices that #2 and #3 need not +be applied, so it only applies #1. The commit ancestry graph +becomes something like this: + + where *your old "master" head + upstream --> #1 --> #2 --> #3 + used \ your new "master" head* + to be \--> #A --> #2' --> #3' --> #B --> #C --> #1' + *upstream + head + +Again, "git prune" would discard the disused commits #1-#3 and +you continue on starting from the new "master" head, which is +the #1' commit. + +-jc + +- +To unsubscribe from this list: send the line "unsubscribe git" in +the body of a message to majordomo@vger.kernel.org +More majordomo info at http://vger.kernel.org/majordomo-info.html + + diff --git a/Documentation/howto/rebuild-from-update-hook.txt b/Documentation/howto/rebuild-from-update-hook.txt new file mode 100644 index 0000000000..ebd025db85 --- /dev/null +++ b/Documentation/howto/rebuild-from-update-hook.txt @@ -0,0 +1,83 @@ +Subject: [HOWTO] Using post-update hook +Message-ID: <7vy86o6usx.fsf@assigned-by-dhcp.cox.net> +From: Junio C Hamano <junkio@cox.net> +Date: Fri, 26 Aug 2005 18:19:10 -0700 +Abstract: In this how-to article, JC talks about how he + uses the post-update hook to automate git documentation page + shown at http://www.kernel.org/pub/software/scm/git/docs/. + +The pages under http://www.kernel.org/pub/software/scm/git/docs/ +are built from Documentation/ directory of the git.git project +and needed to be kept up-to-date. The www.kernel.org/ servers +are mirrored and I was told that the origin of the mirror is on +the machine master.kernel.org, on which I was given an account +when I took over git maintainership from Linus. + +The directories relevant to this how-to are these two: + + /pub/scm/git/git.git/ The public git repository. + /pub/software/scm/git/docs/ The HTML documentation page. + +So I made a repository to generate the documentation under my +home directory over there. + + $ cd + $ mkdir doc-git && cd doc-git + $ git clone /pub/scm/git/git.git/ docgen + +What needs to happen is to update the $HOME/doc-git/docgen/ +working tree, build HTML docs there and install the result in +/pub/software/scm/git/docs/ directory. So I wrote a little +script: + + $ cat >dododoc.sh <<\EOF + #!/bin/sh + cd $HOME/doc-git/docgen || exit + + unset GIT_DIR + + git pull /pub/scm/git/git.git/ master && + cd Documentation && + make install-webdoc + EOF + +Initially I used to run this by hand whenever I push into the +public git repository. Then I did a cron job that ran twice a +day. The current round uses the post-update hook mechanism, +like this: + + $ cat >/pub/scm/git/git.git/hooks/post-update <<\EOF + #!/bin/sh + # + # An example hook script to prepare a packed repository for use over + # dumb transports. + # + # To enable this hook, make this file executable by "chmod +x post-update". + + case " $* " in + *' refs/heads/master '*) + echo $HOME/doc-git/dododoc.sh | at now + ;; + esac + exec git-update-server-info + EOF + $ chmod +x /pub/scm/git/git.git/hooks/post-update + +There are three things worth mentioning: + + - The update-hook is run after the repository accepts a "git + push", under my user privilege. It is given the full names + of refs that have been updated as arguments. My post-update + runs the dododoc.sh script only when the master head is + updated. + + - When update-hook is run, GIT_DIR is set to '.' by the calling + receive-pack. This is inherited by the dododoc.sh run via + the "at" command, and needs to be unset; otherwise, "git + pull" it does into $HOME/doc-git/docgen/ repository would not + work correctly. + + - This is still crude and does not protect against simultaneous + make invocations stomping on each other. I would need to add + some locking mechanism for this. + diff --git a/Documentation/howto/revert-branch-rebase.txt b/Documentation/howto/revert-branch-rebase.txt new file mode 100644 index 0000000000..e4cce5bf7f --- /dev/null +++ b/Documentation/howto/revert-branch-rebase.txt @@ -0,0 +1,199 @@ +From: Junio C Hamano <junkio@cox.net> +To: git@vger.kernel.org +Subject: [HOWTO] Reverting an existing commit +Abstract: In this article, JC gives a small real-life example of using + 'git revert' command, and using a temporary branch and tag for safety + and easier sanity checking. +Date: Mon, 29 Aug 2005 21:39:02 -0700 +Content-type: text/asciidoc +Message-ID: <7voe7g3uop.fsf@assigned-by-dhcp.cox.net> + +Reverting an existing commit +============================ + +One of the changes I pulled into the 'master' branch turns out to +break building GIT with GCC 2.95. While they were well intentioned +portability fixes, keeping things working with gcc-2.95 was also +important. Here is what I did to revert the change in the 'master' +branch and to adjust the 'pu' branch, using core GIT tools and +barebone Porcelain. + +First, prepare a throw-away branch in case I screw things up. + +------------------------------------------------ +$ git checkout -b revert-c99 master +------------------------------------------------ + +Now I am on the 'revert-c99' branch. Let's figure out which commit to +revert. I happen to know that the top of the 'master' branch is a +merge, and its second parent (i.e. foreign commit I merged from) has +the change I would want to undo. Further I happen to know that that +merge introduced 5 commits or so: + +------------------------------------------------ +$ git show-branch --more=4 master master^2 | head +! [master] Merge refs/heads/portable from http://www.cs.berkeley.... + ! [master^2] Replace C99 array initializers with code. +-- ++ [master] Merge refs/heads/portable from http://www.cs.berkeley.... +++ [master^2] Replace C99 array initializers with code. +++ [master^2~1] Replace unsetenv() and setenv() with older putenv(). +++ [master^2~2] Include sys/time.h in daemon.c. +++ [master^2~3] Fix ?: statements. +++ [master^2~4] Replace zero-length array decls with []. ++ [master~1] tutorial note about git branch +------------------------------------------------ + +The '--more=4' above means "after we reach the merge base of refs, +show until we display four more common commits". That last commit +would have been where the "portable" branch was forked from the main +git.git repository, so this would show everything on both branches +since then. I just limited the output to the first handful using +'head'. + +Now I know 'master^2~4' (pronounce it as "find the second parent of +the 'master', and then go four generations back following the first +parent") is the one I would want to revert. Since I also want to say +why I am reverting it, the '-n' flag is given to 'git revert'. This +prevents it from actually making a commit, and instead 'git revert' +leaves the commit log message it wanted to use in '.msg' file: + +------------------------------------------------ +$ git revert -n master^2~4 +$ cat .msg +Revert "Replace zero-length array decls with []." + +This reverts 6c5f9baa3bc0d63e141e0afc23110205379905a4 commit. +$ git diff HEAD ;# to make sure what we are reverting makes sense. +$ make CC=gcc-2.95 clean test ;# make sure it fixed the breakage. +$ make clean test ;# make sure it did not cause other breakage. +------------------------------------------------ + +The reverted change makes sense (from reading the 'diff' output), does +fix the problem (from 'make CC=gcc-2.95' test), and does not cause new +breakage (from the last 'make test'). I'm ready to commit: + +------------------------------------------------ +$ git commit -a -s ;# read .msg into the log, + # and explain why I am reverting. +------------------------------------------------ + +I could have screwed up in any of the above steps, but in the worst +case I could just have done 'git checkout master' to start over. +Fortunately I did not have to; what I have in the current branch +'revert-c99' is what I want. So merge that back into 'master': + +------------------------------------------------ +$ git checkout master +$ git resolve master revert-c99 fast ;# this should be a fast forward +Updating from 10d781b9caa4f71495c7b34963bef137216f86a8 to e3a693c... + cache.h | 8 ++++---- + commit.c | 2 +- + ls-files.c | 2 +- + receive-pack.c | 2 +- + server-info.c | 2 +- + 5 files changed, 8 insertions(+), 8 deletions(-) +------------------------------------------------ + +The 'fast' in the above 'git resolve' is not a magic. I knew this +'resolve' would result in a fast forward merge, and if not, there is +something very wrong (so I would do 'git reset' on the 'master' branch +and examine the situation). When a fast forward merge is done, the +message parameter to 'git resolve' is discarded, because no new commit +is created. You could have said 'junk' or 'nothing' there as well. + +There is no need to redo the test at this point. We fast forwarded +and we know 'master' matches 'revert-c99' exactly. In fact: + +------------------------------------------------ +$ git diff master..revert-c99 +------------------------------------------------ + +says nothing. + +Then we rebase the 'pu' branch as usual. + +------------------------------------------------ +$ git checkout pu +$ git tag pu-anchor pu +$ git rebase master +* Applying: Redo "revert" using three-way merge machinery. +First trying simple merge strategy to cherry-pick. +Finished one cherry-pick. +* Applying: Remove git-apply-patch-script. +First trying simple merge strategy to cherry-pick. +Simple cherry-pick fails; trying Automatic cherry-pick. +Removing Documentation/git-apply-patch-script.txt +Removing git-apply-patch-script +Finished one cherry-pick. +* Applying: Document "git cherry-pick" and "git revert" +First trying simple merge strategy to cherry-pick. +Finished one cherry-pick. +* Applying: mailinfo and applymbox updates +First trying simple merge strategy to cherry-pick. +Finished one cherry-pick. +* Applying: Show commits in topo order and name all commits. +First trying simple merge strategy to cherry-pick. +Finished one cherry-pick. +* Applying: More documentation updates. +First trying simple merge strategy to cherry-pick. +Finished one cherry-pick. +------------------------------------------------ + +The temporary tag 'pu-anchor' is me just being careful, in case 'git +rebase' screws up. After this, I can do these for sanity check: + +------------------------------------------------ +$ git diff pu-anchor..pu ;# make sure we got the master fix. +$ make CC=gcc-2.95 clean test ;# make sure it fixed the breakage. +$ make clean test ;# make sure it did not cause other breakage. +------------------------------------------------ + +Everything is in the good order. I do not need the temporary branch +nor tag anymore, so remove them: + +------------------------------------------------ +$ rm -f .git/refs/tags/pu-anchor .git/refs/heads/revert-c99 +------------------------------------------------ + +It was an emergency fix, so we might as well merge it into the +'release candidate' branch, although I expect the next release would +be some days off: + +------------------------------------------------ +$ git checkout rc +$ git pull . master +Packing 0 objects +Unpacking 0 objects + +* committish: e3a693c... refs/heads/master from . +Trying to merge e3a693c... into 8c1f5f0... using 10d781b... +Committed merge 7fb9b7262a1d1e0a47bbfdcbbcf50ce0635d3f8f + cache.h | 8 ++++---- + commit.c | 2 +- + ls-files.c | 2 +- + receive-pack.c | 2 +- + server-info.c | 2 +- + 5 files changed, 8 insertions(+), 8 deletions(-) +------------------------------------------------ + +And the final repository status looks like this: + +------------------------------------------------ +$ git show-branch --more=1 master pu rc +! [master] Revert "Replace zero-length array decls with []." + ! [pu] git-repack: Add option to repack all objects. + * [rc] Merge refs/heads/master from . +--- + + [pu] git-repack: Add option to repack all objects. + + [pu~1] More documentation updates. + + [pu~2] Show commits in topo order and name all commits. + + [pu~3] mailinfo and applymbox updates + + [pu~4] Document "git cherry-pick" and "git revert" + + [pu~5] Remove git-apply-patch-script. + + [pu~6] Redo "revert" using three-way merge machinery. + + [rc] Merge refs/heads/master from . ++++ [master] Revert "Replace zero-length array decls with []." + + [rc~1] Merge refs/heads/master from . ++++ [master~1] Merge refs/heads/portable from http://www.cs.berkeley.... +------------------------------------------------ diff --git a/Documentation/howto/using-topic-branches.txt b/Documentation/howto/using-topic-branches.txt new file mode 100644 index 0000000000..d30fa85048 --- /dev/null +++ b/Documentation/howto/using-topic-branches.txt @@ -0,0 +1,288 @@ +Date: Mon, 15 Aug 2005 12:17:41 -0700 +From: tony.luck@intel.com +Subject: Some tutorial text (was git/cogito workshop/bof at linuxconf au?) +Abstract: In this article, Tony Luck discusses how he uses GIT + as a Linux subsystem maintainer. + +Here's something that I've been putting together on how I'm using +GIT as a Linux subsystem maintainer. + +-Tony + +Last updated w.r.t. GIT 0.99.5 + +Linux subsystem maintenance using GIT +------------------------------------- + +My requirements here are to be able to create two public trees: + +1) A "test" tree into which patches are initially placed so that they +can get some exposure when integrated with other ongoing development. +This tree is available to Andrew for pulling into -mm whenever he wants. + +2) A "release" tree into which tested patches are moved for final +sanity checking, and as a vehicle to send them upstream to Linus +(by sending him a "please pull" request.) + +Note that the period of time that each patch spends in the "test" tree +is dependent on the complexity of the change. Since GIT does not support +cherry picking, it is not practical to simply apply all patches to the +test tree and then pull to the release tree as that would leave trivial +patches blocked in the test tree waiting for complex changes to accumulate +enough test time to graduate. + +Back in the BitKeeper days I achieved this my creating small forests of +temporary trees, one tree for each logical grouping of patches, and then +pulling changes from these trees first to the test tree, and then to the +release tree. At first I replicated this in GIT, but then I realised +that I could so this far more efficiently using branches inside a single +GIT repository. + +So here is the step-by-step guide how this all works for me. + +First create your work tree by cloning Linus's public tree: + + $ git clone rsync://rsync.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git work + +Change directory into the cloned tree you just created + + $ cd work + +Set up a remotes file so that you can fetch the latest from Linus' master +branch into a local branch named "linus": + + $ cat > .git/remotes/linus + URL: rsync://rsync.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git + Pull: master:linus + ^D + +and create the linus branch: + + $ git branch linus + +The "linus" branch will be used to track the upstream kernel. To update it, +you simply run: + + $ git fetch linus + +you can do this frequently (and it should be safe to do so with pending +work in your tree, but perhaps not if you are in mid-merge). + +If you need to keep track of other public trees, you can add remote branches +for them too: + + $ git branch another + $ cat > .git/remotes/another + URL: ... insert URL here ... + Pull: name-of-branch-in-this-remote-tree:another + ^D + +and run: + + $ git fetch another + +Now create the branches in which you are going to work, these start +out at the current tip of the linus branch. + + $ git branch test linus + $ git branch release linus + +These can be easily kept up to date by merging from the "linus" branch: + + $ git checkout test && git resolve test linus "Auto-update from upstream" + $ git checkout release && git resolve release linus "Auto-update from upstream" + +Set up so that you can push upstream to your public tree (you need to +log-in to the remote system and create an empty tree there before the +first push). + + $ cat > .git/remotes/mytree + URL: master.kernel.org:/pub/scm/linux/kernel/git/aegl/linux-2.6.git + Push: release + Push: test + ^D + +and the push both the test and release trees using: + + $ git push mytree + +or push just one of the test and release branches using: + + $ git push mytree test +or + $ git push mytree release + +Now to apply some patches from the community. Think of a short +snappy name for a branch to hold this patch (or related group of +patches), and create a new branch from the current tip of the +linus branch: + + $ git checkout -b speed-up-spinlocks linus + +Now you apply the patch(es), run some tests, and commit the change(s). If +the patch is a multi-part series, then you should apply each as a separate +commit to this branch. + + $ ... patch ... test ... commit [ ... patch ... test ... commit ]* + +When you are happy with the state of this change, you can pull it into the +"test" branch in preparation to make it public: + + $ git checkout test && git resolve test speed-up-spinlocks "Pull speed-up-spinlock changes" + +It is unlikely that you would have any conflicts here ... but you might if you +spent a while on this step and had also pulled new versions from upstream. + +Some time later when enough time has passed and testing done, you can pull the +same branch into the "release" tree ready to go upstream. This is where you +see the value of keeping each patch (or patch series) in its own branch. It +means that the patches can be moved into the "release" tree in any order. + + $ git checkout release && git resolve release speed-up-spinlocks "Pull speed-up-spinlock changes" + +After a while, you will have a number of branches, and despite the +well chosen names you picked for each of them, you may forget what +they are for, or what status they are in. To get a reminder of what +changes are in a specific branch, use: + + $ git-whatchanged branchname ^linus | git-shortlog + +To see whether it has already been merged into the test or release branches +use: + + $ git-rev-list branchname ^test +or + $ git-rev-list branchname ^release + +[If this branch has not yet been merged you will see a set of SHA1 values +for the commits, if it has been merged, then there will be no output] + +Once a patch completes the great cycle (moving from test to release, then +pulled by Linus, and finally coming back into your local "linus" branch) +the branch for this change is no longer needed. You detect this when the +output from: + + $ git-rev-list branchname ^linus + +is empty. At this point the branch can be deleted: + + $ rm .git/refs/heads/branchname + +Some changes are so trivial that it is not necessary to create a separate +branch and then merge into each of the test and release branches. For +these changes, just apply directly to the "release" branch, and then +merge that into the "test" branch. + +To create diffstat and shortlog summaries of changes to include in a "please +pull" request to Linus you can use: + + $ git-whatchanged -p release ^linus | diffstat -p1 +and + $ git-whatchanged release ^linus | git-shortlog + + +Here are some of the scripts that I use to simplify all this even further. + +==== update script ==== +# Update a branch in my GIT tree. If the branch to be updated +# is "linus", then pull from kernel.org. Otherwise merge local +# linus branch into test|release branch + +case "$1" in +test|release) + git checkout $1 && git resolve $1 linus "Auto-update from upstream" + ;; +linus) + before=$(cat .git/refs/heads/linus) + git fetch linus + after=$(cat .git/refs/heads/linus) + if [ $before != $after ] + then + git-whatchanged $after ^$before | git-shortlog + fi + ;; +*) + echo "Usage: $0 linus|test|release" 1>&2 + exit 1 + ;; +esac + +==== merge script ==== +# Merge a branch into either the test or release branch + +pname=$0 + +usage() +{ + echo "Usage: $pname branch test|release" 1>&2 + exit 1 +} + +if [ ! -f .git/refs/heads/"$1" ] +then + echo "Can't see branch <$1>" 1>&2 + usage +fi + +case "$2" in +test|release) + if [ $(git-rev-list $1 ^$2 | wc -c) -eq 0 ] + then + echo $1 already merged into $2 1>&2 + exit 1 + fi + git checkout $2 && git resolve $2 $1 "Pull $1 into $2 branch" + ;; +*) + usage + ;; +esac + +==== status script ==== +# report on status of my ia64 GIT tree + +gb=$(tput setab 2) +rb=$(tput setab 1) +restore=$(tput setab 9) + +if [ `git-rev-list release ^test | wc -c` -gt 0 ] +then + echo $rb Warning: commits in release that are not in test $restore + git-whatchanged release ^test +fi + +for branch in `ls .git/refs/heads` +do + if [ $branch = linus -o $branch = test -o $branch = release ] + then + continue + fi + + echo -n $gb ======= $branch ====== $restore " " + status= + for ref in test release linus + do + if [ `git-rev-list $branch ^$ref | wc -c` -gt 0 ] + then + status=$status${ref:0:1} + fi + done + case $status in + trl) + echo $rb Need to pull into test $restore + ;; + rl) + echo "In test" + ;; + l) + echo "Waiting for linus" + ;; + "") + echo $rb All done $restore + ;; + *) + echo $rb "<$status>" $restore + ;; + esac + git-whatchanged $branch ^linus | git-shortlog +done diff --git a/Documentation/install-webdoc.sh b/Documentation/install-webdoc.sh new file mode 100755 index 0000000000..d593ab988b --- /dev/null +++ b/Documentation/install-webdoc.sh @@ -0,0 +1,25 @@ +#!/bin/sh + +T="$1" + +for h in *.html howto/*.txt howto/*.html +do + diff -u -I'Last updated [0-9][0-9]-[A-Z][a-z][a-z]-' "$T/$h" "$h" || { + echo >&2 "# install $h $T/$h" + rm -f "$T/$h" + mkdir -p `dirname "$T/$h"` + cp "$h" "$T/$h" + } +done +strip_leading=`echo "$T/" | sed -e 's|.|.|g'` +for th in "$T"/*.html "$T"/howto/*.txt "$T"/howto/*.html +do + h=`expr "$th" : "$strip_leading"'\(.*\)'` + case "$h" in + index.html) continue ;; + esac + test -f "$h" && continue + echo >&2 "# rm -f $th" + rm -f "$th" +done +ln -sf git.html "$T/index.html" diff --git a/Documentation/pack-protocol.txt b/Documentation/pack-protocol.txt new file mode 100644 index 0000000000..7d6aec409d --- /dev/null +++ b/Documentation/pack-protocol.txt @@ -0,0 +1,38 @@ +There are two Pack push-pull protocols. + +upload-pack (S) | fetch/clone-pack (C) protocol: + + # Tell the puller what commits we have and what their names are + S: SHA1 name + S: ... + S: SHA1 name + S: # flush -- it's your turn + # Tell the pusher what commits we want, and what we have + C: want name + C: .. + C: want name + C: have SHA1 + C: have SHA1 + C: ... + C: # flush -- occasionally ask "had enough?" + S: NAK + C: have SHA1 + C: ... + C: have SHA1 + S: ACK + C: done + S: XXXXXXX -- packfile contents. + +send-pack | receive-pack protocol. + + # Tell the pusher what commits we have and what their names are + C: SHA1 name + C: ... + C: SHA1 name + C: # flush -- it's your turn + # Tell the puller what the pusher has + S: old-SHA1 new-SHA1 name + S: old-SHA1 new-SHA1 name + S: ... + S: # flush -- done with the list + S: XXXXXXX --- packfile contents. diff --git a/Documentation/pull-fetch-param.txt b/Documentation/pull-fetch-param.txt new file mode 100644 index 0000000000..8642182c89 --- /dev/null +++ b/Documentation/pull-fetch-param.txt @@ -0,0 +1,93 @@ +<repository>:: + The "remote" repository to pull from. One of the + following notations can be used to name the repository + to pull from: + + Rsync URL + rsync://remote.machine/path/to/repo.git/ + + HTTP(s) URL + http://remote.machine/path/to/repo.git/ + + GIT URL + git://remote.machine/path/to/repo.git/ + remote.machine:/path/to/repo.git/ + + Local directory + /path/to/repo.git/ + + In addition to the above, as a short-hand, the name of a + file in $GIT_DIR/remotes directory can be given; the + named file should be in the following format: + + URL: one of the above URL format + Push: <refspec>... + Pull: <refspec>... + + When such a short-hand is specified in place of + <repository> without <refspec> parameters on the command + line, <refspec>... specified on Push lines or Pull lines + are used for "git push" and "git fetch/pull", + respectively. + + The name of a file in $GIT_DIR/branches directory can be + specified as an older notation short-hand; the named + file should contain a single line, a URL in one of the + above formats, optionally followed by a hash '#' and the + name of remote head (URL fragment notation). + $GIT_DIR/branches/<remote> file that stores a <url> + without the fragment is equivalent to have this in the + corresponding file in the $GIT_DIR/remotes/ directory + + URL: <url> + Pull: refs/heads/master:<remote> + + while having <url>#<head> is equivalent to + + URL: <url> + Pull: refs/heads/<head>:<remote> + +<refspec>:: + The canonical format of a <refspec> parameter is + '+?<src>:<dst>'; that is, an optional plus '+', followed + by the source ref, followed by a colon ':', followed by + the destination ref. + + When used in "git push", the <src> side can be an + arbitrary "SHA1 expression" that can be used as an + argument to "git-cat-file -t". E.g. "master~4" (push + four parents before the current master head). + + For "git push", the local ref that matches <src> is used + to fast forward the remote ref that matches <dst>. If + the optional plus '+' is used, the remote ref is updated + even if it does not result in a fast forward update. + + For "git fetch/pull", the remote ref that matches <src> + is fetched, and if <dst> is not empty string, the local + ref that matches it is fast forwarded using <src>. + Again, if the optional plus '+' is used, the local ref + is updated even if it does not result in a fast forward + update. + + Some short-cut notations are also supported. + + * For backward compatibility, "tag" is almost ignored; + it just makes the following parameter <tag> to mean a + refspec "refs/tags/<tag>:refs/tags/<tag>". + + * A parameter <ref> without a colon is equivalent to + <ref>: when pulling/fetching, and <ref>:<ref> when + pushing. That is, do not store it locally if + fetching, and update the same name if pushing. + +-a, \--append:: + Append ref names and object names of fetched refs to the + existing contents of $GIT_DIR/FETCH_HEAD. Without this + option old data in $GIT_DIR/FETCH_HEAD will be overwritten. + +-f, \--force:: + Usually, the command refuses to update a local ref that is + not an ancestor of the remote ref used to overwrite it. + This flag disables the check. What this means is that the + local repository can lose commits; use it with care. diff --git a/Documentation/repository-layout.txt b/Documentation/repository-layout.txt new file mode 100644 index 0000000000..d20fa80d87 --- /dev/null +++ b/Documentation/repository-layout.txt @@ -0,0 +1,129 @@ +GIT repository layout +===================== +v0.99.5, Sep 2005 + +You may find these things in your git repository (`.git` +directory for a repository associated with your working tree, or +`'project'.git` directory for a public 'naked' repository). + +objects:: + Object store associated with this repository. Usually + an object store is self sufficient (i.e. all the objects + that are referred to by an object found in it are also + found in it), but there are couple of ways to violate + it. ++ +. You could populate the repository by running a commit walker +without `-a` option. Depending on which options are given, you +could have only commit objects without associated blobs and +trees this way, for example. A repository with this kind of +incomplete object store is not suitable to be published to the +outside world but sometimes useful for private repository. +. You can be using `objects/info/alternates` mechanism, or +`$GIT_ALTERNATE_OBJECT_DIRECTORIES` mechanism to 'borrow' +objects from other object stores. A repository with this kind +of incompete object store is not suitable to be published for +use with dumb transports but otherwise is OK as long as +`objects/info/alternates` points at the right object stores +it borrows from. + +objects/[0-9a-f][0-9a-f]:: + Traditionally, each object is stored in its own file. + They are split into 256 subdirectories using the first + two letters from its object name to keep the number of + directory entries `objects` directory itself needs to + hold. Objects found here are often called 'unpacked' + objects. + +objects/pack:: + Packs (files that store many object in compressed form, + along with index files to allow them to be randomly + accessed) are found in this directory. + +objects/info:: + Additional information about the object store is + recorded in this directory. + +objects/info/packs:: + This file is to help dumb transports discover what packs + are available in this object store. Whenever a pack is + added or removed, `git update-server-info` should be run + to keep this file up-to-date if the repository is + published for dumb transports. `git repack` does this + by default. + +objects/info/alternates:: + This file records absolute filesystem paths of alternate + object stores that this object store borrows objects + from, one pathname per line. + +refs:: + References are stored in subdirectories of this + directory. The `git prune` command knows to keep + objects reachable from refs found in this directory and + its subdirectories. + +refs/heads/`name`:: + records tip-of-the-tree commit objects of branch `name` + +refs/tags/`name`:: + records any object name (not necessarily a commit + object, or a tag object that points at a commit object). + +HEAD:: + A symlink of the form `refs/heads/'name'` to point at + the current branch, if exists. It does not mean much if + the repository is not associated with any working tree + (i.e. 'naked' repository), but a valid git repository + *must* have such a symlink here. It is legal if the + named branch 'name' does not (yet) exist. + +branches:: + A slightly deprecated way to store shorthands to be used + to specify URL to `git fetch`, `git pull` and `git push` + commands is to store a file in `branches/'name'` and + give 'name' to these commands in place of 'repository' + argument. + +hooks:: + Hooks are customization scripts used by various git + commands. A handful of sample hooks are installed when + `git init-db` is run, but all of them are disabled by + default. To enable, they need to be made executable. + +index:: + The current index file for the repository. It is + usually not found in a naked repository. + +info:: + Additional information about the repository is recorded + in this directory. + +info/refs:: + This file is to help dumb transports to discover what + refs are available in this repository. Whenever you + create/delete a new branch or a new tag, `git + update-server-info` should be run to keep this file + up-to-date if the repository is published for dumb + transports. The `git-receive-pack` command, which is + run on a remote repository when you `git push` into it, + runs `hooks/update` hook to help you achive this. + +info/grafts:: + This file records fake commit ancestry information, to + pretend the set of parents a commit has is different + from how the commit was actually created. One record + per line describes a commit and its fake parents by + listing their 40-byte hexadecimal object names separated + by a space and terminated by a newline. + +info/exclude:: + This file, by convention among Porcelains, stores the + exclude pattern list. `git status` looks at it, but + otherwise it is not looked at by any of the core GIT + commands. + +remotes:: + Stores shorthands to be used to give URL and default + refnames to interact with remote repository to `git + fetch`, `git pull` and `git push` commands. diff --git a/Documentation/sort_glossary.pl b/Documentation/sort_glossary.pl new file mode 100644 index 0000000000..babbea0415 --- /dev/null +++ b/Documentation/sort_glossary.pl @@ -0,0 +1,70 @@ +#!/usr/bin/perl + +%terms=(); + +while(<>) { + if(/^(\S.*)::$/) { + my $term=$1; + if(defined($terms{$term})) { + die "$1 defined twice\n"; + } + $terms{$term}=""; + LOOP: while(<>) { + if(/^$/) { + last LOOP; + } + if(/^ \S/) { + $terms{$term}.=$_; + } else { + die "Error 1: $_"; + } + } + } +} + +sub format_tab_80 ($) { + my $text=$_[0]; + my $result=""; + $text=~s/\s+/ /g; + $text=~s/^\s+//; + while($text=~/^(.{1,72})(|\s+(\S.*)?)$/) { + $result.=" ".$1."\n"; + $text=$3; + } + return $result; +} + +sub no_spaces ($) { + my $result=$_[0]; + $result=~tr/ /_/; + return $result; +} + +print 'GIT Glossary +============ +Aug 2005 + +This list is sorted alphabetically: + +'; + +@keys=sort {uc($a) cmp uc($b)} keys %terms; +$pattern='(\b'.join('\b|\b',reverse @keys).'\b)'; +foreach $key (@keys) { + $terms{$key}=~s/$pattern/sprintf "<<ref_".no_spaces($1).",$1>>";/eg; + print '[[ref_'.no_spaces($key).']]'.$key."::\n" + .format_tab_80($terms{$key})."\n"; +} + +print ' + +Author +------ +Written by Johannes Schindelin <Johannes.Schindelin@gmx.de> and +the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the link:git.html[git] suite +'; + diff --git a/Documentation/technical/trivial-merge.txt b/Documentation/technical/trivial-merge.txt new file mode 100644 index 0000000000..24c84100b0 --- /dev/null +++ b/Documentation/technical/trivial-merge.txt @@ -0,0 +1,121 @@ +Trivial merge rules +=================== + +This document describes the outcomes of the trivial merge logic in read-tree. + +One-way merge +------------- + +This replaces the index with a different tree, keeping the stat info +for entries that don't change, and allowing -u to make the minimum +required changes to the working tree to have it match. + +Entries marked '+' have stat information. Spaces marked '*' don't +affect the result. + + index tree result + ----------------------- + * (empty) (empty) + (empty) tree tree + index+ tree tree + index+ index index+ + +Two-way merge +------------- + +It is permitted for the index to lack an entry; this does not prevent +any case from applying. + +If the index exists, it is an error for it not to match either the old +or the result. + +If multiple cases apply, the one used is listed first. + +A result which changes the index is an error if the index is not empty +and not up-to-date. + +Entries marked '+' have stat information. Spaces marked '*' don't +affect the result. + + case index old new result + ------------------------------------- + 0/2 (empty) * (empty) (empty) + 1/3 (empty) * new new + 4/5 index+ (empty) (empty) index+ + 6/7 index+ (empty) index index+ + 10 index+ index (empty) (empty) + 14/15 index+ old old index+ + 18/19 index+ old index index+ + 20 index+ index new new + +Three-way merge +--------------- + +It is permitted for the index to lack an entry; this does not prevent +any case from applying. + +If the index exists, it is an error for it not to match either the +head or (if the merge is trivial) the result. + +If multiple cases apply, the one used is listed first. + +A result of "no merge" means that index is left in stage 0, ancest in +stage 1, head in stage 2, and remote in stage 3 (if any of these are +empty, no entry is left for that stage). Otherwise, the given entry is +left in stage 0, and there are no other entries. + +A result of "no merge" is an error if the index is not empty and not +up-to-date. + +*empty* means that the tree must not have a directory-file conflict + with the entry. + +For multiple ancestors, a '+' means that this case applies even if +only one ancestor or remote fits; a '^' means all of the ancestors +must be the same. + +case ancest head remote result +---------------------------------------- +1 (empty)+ (empty) (empty) (empty) +2ALT (empty)+ *empty* remote remote +2 (empty)^ (empty) remote no merge +3ALT (empty)+ head *empty* head +3 (empty)^ head (empty) no merge +4 (empty)^ head remote no merge +5ALT * head head head +6 ancest+ (empty) (empty) no merge +8 ancest^ (empty) ancest no merge +7 ancest+ (empty) remote no merge +10 ancest^ ancest (empty) no merge +9 ancest+ head (empty) no merge +16 anc1/anc2 anc1 anc2 no merge +13 ancest+ head ancest head +14 ancest+ ancest remote remote +11 ancest+ head remote no merge + +Only #2ALT and #3ALT use *empty*, because these are the only cases +where there can be conflicts that didn't exist before. Note that we +allow directory-file conflicts between things in different stages +after the trivial merge. + +A possible alternative for #6 is (empty), which would make it like +#1. This is not used, due to the likelihood that it arises due to +moving the file to multiple different locations or moving and deleting +it in different branches. + +Case #1 is included for completeness, and also in case we decide to +put on '+' markings; any path that is never mentioned at all isn't +handled. + +Note that #16 is when both #13 and #14 apply; in this case, we refuse +the trivial merge, because we can't tell from this data which is +right. This is a case of a reverted patch (in some direction, maybe +multiple times), and the right answer depends on looking at crossings +of history or common ancestors of the ancestors. + +Note that, between #6, #7, #9, and #11, all cases not otherwise +covered are handled in this table. + +For #8 and #10, there is alternative behavior, not currently +implemented, where the result is (empty). As currently implemented, +the automatic merge will generally give this effect. diff --git a/Documentation/tutorial.txt b/Documentation/tutorial.txt new file mode 100644 index 0000000000..36f42e051c --- /dev/null +++ b/Documentation/tutorial.txt @@ -0,0 +1,1461 @@ +A short git tutorial +==================== +v0.99.5, Aug 2005 + +Introduction +------------ + +This is trying to be a short tutorial on setting up and using a git +repository, mainly because being hands-on and using explicit examples is +often the best way of explaining what is going on. + +In normal life, most people wouldn't use the "core" git programs +directly, but rather script around them to make them more palatable. +Understanding the core git stuff may help some people get those scripts +done, though, and it may also be instructive in helping people +understand what it is that the higher-level helper scripts are actually +doing. + +The core git is often called "plumbing", with the prettier user +interfaces on top of it called "porcelain". You may not want to use the +plumbing directly very often, but it can be good to know what the +plumbing does for when the porcelain isn't flushing... + + +Creating a git repository +------------------------- + +Creating a new git repository couldn't be easier: all git repositories start +out empty, and the only thing you need to do is find yourself a +subdirectory that you want to use as a working tree - either an empty +one for a totally new project, or an existing working tree that you want +to import into git. + +For our first example, we're going to start a totally new repository from +scratch, with no pre-existing files, and we'll call it `git-tutorial`. +To start up, create a subdirectory for it, change into that +subdirectory, and initialize the git infrastructure with `git-init-db`: + +------------------------------------------------ +mkdir git-tutorial +cd git-tutorial +git-init-db +------------------------------------------------ + +to which git will reply + + defaulting to local storage area + +which is just git's way of saying that you haven't been doing anything +strange, and that it will have created a local `.git` directory setup for +your new project. You will now have a `.git` directory, and you can +inspect that with `ls`. For your new empty project, it should show you +three entries, among other things: + + - a symlink called `HEAD`, pointing to `refs/heads/master` ++ +Don't worry about the fact that the file that the `HEAD` link points to +doesn't even exist yet -- you haven't created the commit that will +start your `HEAD` development branch yet. + + - a subdirectory called `objects`, which will contain all the + objects of your project. You should never have any real reason to + look at the objects directly, but you might want to know that these + objects are what contains all the real 'data' in your repository. + + - a subdirectory called `refs`, which contains references to objects. + +In particular, the `refs` subdirectory will contain two other +subdirectories, named `heads` and `tags` respectively. They do +exactly what their names imply: they contain references to any number +of different 'heads' of development (aka 'branches'), and to any +'tags' that you have created to name specific versions in your +repository. + +One note: the special `master` head is the default branch, which is +why the `.git/HEAD` file was created as a symlink to it even if it +doesn't yet exist. Basically, the `HEAD` link is supposed to always +point to the branch you are working on right now, and you always +start out expecting to work on the `master` branch. + +However, this is only a convention, and you can name your branches +anything you want, and don't have to ever even 'have' a `master` +branch. A number of the git tools will assume that `.git/HEAD` is +valid, though. + +[NOTE] +An 'object' is identified by its 160-bit SHA1 hash, aka 'object name', +and a reference to an object is always the 40-byte hex +representation of that SHA1 name. The files in the `refs` +subdirectory are expected to contain these hex references +(usually with a final `\'\n\'` at the end), and you should thus +expect to see a number of 41-byte files containing these +references in these `refs` subdirectories when you actually start +populating your tree. + +[NOTE] +An advanced user may want to take a look at the +link:repository-layout.html[repository layout] document +after finishing this tutorial. + +You have now created your first git repository. Of course, since it's +empty, that's not very useful, so let's start populating it with data. + + +Populating a git repository +--------------------------- + +We'll keep this simple and stupid, so we'll start off with populating a +few trivial files just to get a feel for it. + +Start off with just creating any random files that you want to maintain +in your git repository. We'll start off with a few bad examples, just to +get a feel for how this works: + +------------------------------------------------ +echo "Hello World" >hello +echo "Silly example" >example +------------------------------------------------ + +you have now created two files in your working tree (aka 'working directory'), but to +actually check in your hard work, you will have to go through two steps: + + - fill in the 'index' file (aka 'cache') with the information about your + working tree state. + + - commit that index file as an object. + +The first step is trivial: when you want to tell git about any changes +to your working tree, you use the `git-update-index` program. That +program normally just takes a list of filenames you want to update, but +to avoid trivial mistakes, it refuses to add new entries to the cache +(or remove existing ones) unless you explicitly tell it that you're +adding a new entry with the `\--add` flag (or removing an entry with the +`\--remove`) flag. + +So to populate the index with the two files you just created, you can do + +------------------------------------------------ +git-update-index --add hello example +------------------------------------------------ + +and you have now told git to track those two files. + +In fact, as you did that, if you now look into your object directory, +you'll notice that git will have added two new objects to the object +database. If you did exactly the steps above, you should now be able to do + + ls .git/objects/??/* + +and see two files: + + .git/objects/55/7db03de997c86a4a028e1ebd3a1ceb225be238 + .git/objects/f2/4c74a2e500f5ee1332c86b94199f52b1d1d962 + +which correspond with the objects with names of 557db... and f24c7.. +respectively. + +If you want to, you can use `git-cat-file` to look at those objects, but +you'll have to use the object name, not the filename of the object: + + git-cat-file -t 557db03de997c86a4a028e1ebd3a1ceb225be238 + +where the `-t` tells `git-cat-file` to tell you what the "type" of the +object is. Git will tell you that you have a "blob" object (ie just a +regular file), and you can see the contents with + + git-cat-file "blob" 557db03 + +which will print out "Hello World". The object 557db03 is nothing +more than the contents of your file `hello`. + +[NOTE] +Don't confuse that object with the file `hello` itself. The +object is literally just those specific *contents* of the file, and +however much you later change the contents in file `hello`, the object +we just looked at will never change. Objects are immutable. + +[NOTE] +The second example demonstrates that you can +abbreviate the object name to only the first several +hexadecimal digits in most places. + +Anyway, as we mentioned previously, you normally never actually take a +look at the objects themselves, and typing long 40-character hex +names is not something you'd normally want to do. The above digression +was just to show that `git-update-index` did something magical, and +actually saved away the contents of your files into the git object +database. + +Updating the cache did something else too: it created a `.git/index` +file. This is the index that describes your current working tree, and +something you should be very aware of. Again, you normally never worry +about the index file itself, but you should be aware of the fact that +you have not actually really "checked in" your files into git so far, +you've only *told* git about them. + +However, since git knows about them, you can now start using some of the +most basic git commands to manipulate the files or look at their status. + +In particular, let's not even check in the two files into git yet, we'll +start off by adding another line to `hello` first: + +------------------------------------------------ +echo "It's a new day for git" >>hello +------------------------------------------------ + +and you can now, since you told git about the previous state of `hello`, ask +git what has changed in the tree compared to your old index, using the +`git-diff-files` command: + +------------ +git-diff-files +------------ + +Oops. That wasn't very readable. It just spit out its own internal +version of a `diff`, but that internal version really just tells you +that it has noticed that "hello" has been modified, and that the old object +contents it had have been replaced with something else. + +To make it readable, we can tell git-diff-files to output the +differences as a patch, using the `-p` flag: + +------------ +git-diff-files -p +------------ + +which will spit out + +------------ +diff --git a/hello b/hello +--- a/hello ++++ b/hello +@@ -1 +1,2 @@ + Hello World ++It's a new day for git +---- + +i.e. the diff of the change we caused by adding another line to `hello`. + +In other words, `git-diff-files` always shows us the difference between +what is recorded in the index, and what is currently in the working +tree. That's very useful. + +A common shorthand for `git-diff-files -p` is to just write `git +diff`, which will do the same thing. + + +Committing git state +-------------------- + +Now, we want to go to the next stage in git, which is to take the files +that git knows about in the index, and commit them as a real tree. We do +that in two phases: creating a 'tree' object, and committing that 'tree' +object as a 'commit' object together with an explanation of what the +tree was all about, along with information of how we came to that state. + +Creating a tree object is trivial, and is done with `git-write-tree`. +There are no options or other input: git-write-tree will take the +current index state, and write an object that describes that whole +index. In other words, we're now tying together all the different +filenames with their contents (and their permissions), and we're +creating the equivalent of a git "directory" object: + +------------------------------------------------ +git-write-tree +------------------------------------------------ + +and this will just output the name of the resulting tree, in this case +(if you have done exactly as I've described) it should be + + 8988da15d077d4829fc51d8544c097def6644dbb + +which is another incomprehensible object name. Again, if you want to, +you can use `git-cat-file -t 8988d\...` to see that this time the object +is not a "blob" object, but a "tree" object (you can also use +`git-cat-file` to actually output the raw object contents, but you'll see +mainly a binary mess, so that's less interesting). + +However -- normally you'd never use `git-write-tree` on its own, because +normally you always commit a tree into a commit object using the +`git-commit-tree` command. In fact, it's easier to not actually use +`git-write-tree` on its own at all, but to just pass its result in as an +argument to `git-commit-tree`. + +`git-commit-tree` normally takes several arguments -- it wants to know +what the 'parent' of a commit was, but since this is the first commit +ever in this new repository, and it has no parents, we only need to pass in +the object name of the tree. However, `git-commit-tree` +also wants to get a commit message +on its standard input, and it will write out the resulting object name for the +commit to its standard output. + +And this is where we start using the `.git/HEAD` file. The `HEAD` file is +supposed to contain the reference to the top-of-tree, and since that's +exactly what `git-commit-tree` spits out, we can do this all with a simple +shell pipeline: + +------------------------------------------------ +echo "Initial commit" | git-commit-tree $(git-write-tree) > .git/HEAD +------------------------------------------------ + +which will say: + + Committing initial tree 8988da15d077d4829fc51d8544c097def6644dbb + +just to warn you about the fact that it created a totally new commit +that is not related to anything else. Normally you do this only *once* +for a project ever, and all later commits will be parented on top of an +earlier commit, and you'll never see this "Committing initial tree" +message ever again. + +Again, normally you'd never actually do this by hand. There is a +helpful script called `git commit` that will do all of this for you. So +you could have just written `git commit` +instead, and it would have done the above magic scripting for you. + + +Making a change +--------------- + +Remember how we did the `git-update-index` on file `hello` and then we +changed `hello` afterward, and could compare the new state of `hello` with the +state we saved in the index file? + +Further, remember how I said that `git-write-tree` writes the contents +of the *index* file to the tree, and thus what we just committed was in +fact the *original* contents of the file `hello`, not the new ones. We did +that on purpose, to show the difference between the index state, and the +state in the working tree, and how they don't have to match, even +when we commit things. + +As before, if we do `git-diff-files -p` in our git-tutorial project, +we'll still see the same difference we saw last time: the index file +hasn't changed by the act of committing anything. However, now that we +have committed something, we can also learn to use a new command: +`git-diff-index`. + +Unlike `git-diff-files`, which showed the difference between the index +file and the working tree, `git-diff-index` shows the differences +between a committed *tree* and either the index file or the working +tree. In other words, `git-diff-index` wants a tree to be diffed +against, and before we did the commit, we couldn't do that, because we +didn't have anything to diff against. + +But now we can do + + git-diff-index -p HEAD + +(where `-p` has the same meaning as it did in `git-diff-files`), and it +will show us the same difference, but for a totally different reason. +Now we're comparing the working tree not against the index file, +but against the tree we just wrote. It just so happens that those two +are obviously the same, so we get the same result. + +Again, because this is a common operation, you can also just shorthand +it with + + git diff HEAD + +which ends up doing the above for you. + +In other words, `git-diff-index` normally compares a tree against the +working tree, but when given the `\--cached` flag, it is told to +instead compare against just the index cache contents, and ignore the +current working tree state entirely. Since we just wrote the index +file to HEAD, doing `git-diff-index \--cached -p HEAD` should thus return +an empty set of differences, and that's exactly what it does. + +[NOTE] +================ +`git-diff-index` really always uses the index for its +comparisons, and saying that it compares a tree against the working +tree is thus not strictly accurate. In particular, the list of +files to compare (the "meta-data") *always* comes from the index file, +regardless of whether the `\--cached` flag is used or not. The `\--cached` +flag really only determines whether the file *contents* to be compared +come from the working tree or not. + +This is not hard to understand, as soon as you realize that git simply +never knows (or cares) about files that it is not told about +explicitly. Git will never go *looking* for files to compare, it +expects you to tell it what the files are, and that's what the index +is there for. +================ + +However, our next step is to commit the *change* we did, and again, to +understand what's going on, keep in mind the difference between "working +tree contents", "index file" and "committed tree". We have changes +in the working tree that we want to commit, and we always have to +work through the index file, so the first thing we need to do is to +update the index cache: + +------------------------------------------------ +git-update-index hello +------------------------------------------------ + +(note how we didn't need the `\--add` flag this time, since git knew +about the file already). + +Note what happens to the different `git-diff-\*` versions here. After +we've updated `hello` in the index, `git-diff-files -p` now shows no +differences, but `git-diff-index -p HEAD` still *does* show that the +current state is different from the state we committed. In fact, now +`git-diff-index` shows the same difference whether we use the `--cached` +flag or not, since now the index is coherent with the working tree. + +Now, since we've updated `hello` in the index, we can commit the new +version. We could do it by writing the tree by hand again, and +committing the tree (this time we'd have to use the `-p HEAD` flag to +tell commit that the HEAD was the *parent* of the new commit, and that +this wasn't an initial commit any more), but you've done that once +already, so let's just use the helpful script this time: + +------------------------------------------------ +git commit +------------------------------------------------ + +which starts an editor for you to write the commit message and tells you +a bit about what you have done. + +Write whatever message you want, and all the lines that start with '#' +will be pruned out, and the rest will be used as the commit message for +the change. If you decide you don't want to commit anything after all at +this point (you can continue to edit things and update the cache), you +can just leave an empty message. Otherwise `git commit` will commit +the change for you. + +You've now made your first real git commit. And if you're interested in +looking at what `git commit` really does, feel free to investigate: +it's a few very simple shell scripts to generate the helpful (?) commit +message headers, and a few one-liners that actually do the +commit itself (`git-commit`). + + +Inspecting Changes +------------------ + +While creating changes is useful, it's even more useful if you can tell +later what changed. The most useful command for this is another of the +`diff` family, namely `git-diff-tree`. + +`git-diff-tree` can be given two arbitrary trees, and it will tell you the +differences between them. Perhaps even more commonly, though, you can +give it just a single commit object, and it will figure out the parent +of that commit itself, and show the difference directly. Thus, to get +the same diff that we've already seen several times, we can now do + + git-diff-tree -p HEAD + +(again, `-p` means to show the difference as a human-readable patch), +and it will show what the last commit (in `HEAD`) actually changed. + +More interestingly, you can also give `git-diff-tree` the `-v` flag, which +tells it to also show the commit message and author and date of the +commit, and you can tell it to show a whole series of diffs. +Alternatively, you can tell it to be "silent", and not show the diffs at +all, but just show the actual commit message. + +In fact, together with the `git-rev-list` program (which generates a +list of revisions), `git-diff-tree` ends up being a veritable fount of +changes. A trivial (but very useful) script called `git-whatchanged` is +included with git which does exactly this, and shows a log of recent +activities. + +To see the whole history of our pitiful little git-tutorial project, you +can do + + git log + +which shows just the log messages, or if we want to see the log together +with the associated patches use the more complex (and much more +powerful) + + git-whatchanged -p --root + +and you will see exactly what has changed in the repository over its +short history. + +[NOTE] +The `\--root` flag is a flag to `git-diff-tree` to tell it to +show the initial aka 'root' commit too. Normally you'd probably not +want to see the initial import diff, but since the tutorial project +was started from scratch and is so small, we use it to make the result +a bit more interesting. + +With that, you should now be having some inkling of what git does, and +can explore on your own. + +[NOTE] +Most likely, you are not directly using the core +git Plumbing commands, but using Porcelain like Cogito on top +of it. Cogito works a bit differently and you usually do not +have to run `git-update-index` yourself for changed files (you +do tell underlying git about additions and removals via +`cg-add` and `cg-rm` commands). Just before you make a commit +with `cg-commit`, Cogito figures out which files you modified, +and runs `git-update-index` on them for you. + + +Tagging a version +----------------- + +In git, there are two kinds of tags, a "light" one, and an "annotated tag". + +A "light" tag is technically nothing more than a branch, except we put +it in the `.git/refs/tags/` subdirectory instead of calling it a `head`. +So the simplest form of tag involves nothing more than + +------------------------------------------------ +git tag my-first-tag +------------------------------------------------ + +which just writes the current `HEAD` into the `.git/refs/tags/my-first-tag` +file, after which point you can then use this symbolic name for that +particular state. You can, for example, do + + git diff my-first-tag + +to diff your current state against that tag (which at this point will +obviously be an empty diff, but if you continue to develop and commit +stuff, you can use your tag as an "anchor-point" to see what has changed +since you tagged it. + +An "annotated tag" is actually a real git object, and contains not only a +pointer to the state you want to tag, but also a small tag name and +message, along with optionally a PGP signature that says that yes, +you really did +that tag. You create these annotated tags with either the `-a` or +`-s` flag to `git tag`: + + git tag -s <tagname> + +which will sign the current `HEAD` (but you can also give it another +argument that specifies the thing to tag, ie you could have tagged the +current `mybranch` point by using `git tag <tagname> mybranch`). + +You normally only do signed tags for major releases or things +like that, while the light-weight tags are useful for any marking you +want to do -- any time you decide that you want to remember a certain +point, just create a private tag for it, and you have a nice symbolic +name for the state at that point. + + +Copying repositories +-------------------- + +Git repositories are normally totally self-sufficient, and it's worth noting +that unlike CVS, for example, there is no separate notion of +"repository" and "working tree". A git repository normally *is* the +working tree, with the local git information hidden in the `.git` +subdirectory. There is nothing else. What you see is what you got. + +[NOTE] +You can tell git to split the git internal information from +the directory that it tracks, but we'll ignore that for now: it's not +how normal projects work, and it's really only meant for special uses. +So the mental model of "the git information is always tied directly to +the working tree that it describes" may not be technically 100% +accurate, but it's a good model for all normal use. + +This has two implications: + + - if you grow bored with the tutorial repository you created (or you've + made a mistake and want to start all over), you can just do simple + + rm -rf git-tutorial ++ +and it will be gone. There's no external repository, and there's no +history outside the project you created. + + - if you want to move or duplicate a git repository, you can do so. There + is `git clone` command, but if all you want to do is just to + create a copy of your repository (with all the full history that + went along with it), you can do so with a regular + `cp -a git-tutorial new-git-tutorial`. ++ +Note that when you've moved or copied a git repository, your git index +file (which caches various information, notably some of the "stat" +information for the files involved) will likely need to be refreshed. +So after you do a `cp -a` to create a new copy, you'll want to do + + git-update-index --refresh ++ +in the new repository to make sure that the index file is up-to-date. + +Note that the second point is true even across machines. You can +duplicate a remote git repository with *any* regular copy mechanism, be it +`scp`, `rsync` or `wget`. + +When copying a remote repository, you'll want to at a minimum update the +index cache when you do this, and especially with other peoples' +repositories you often want to make sure that the index cache is in some +known state (you don't know *what* they've done and not yet checked in), +so usually you'll precede the `git-update-index` with a + + git-read-tree --reset HEAD + git-update-index --refresh + +which will force a total index re-build from the tree pointed to by `HEAD`. +It resets the index contents to `HEAD`, and then the `git-update-index` +makes sure to match up all index entries with the checked-out files. +If the original repository had uncommitted changes in its +working tree, `git-update-index --refresh` notices them and +tells you they need to be updated. + +The above can also be written as simply + + git reset + +and in fact a lot of the common git command combinations can be scripted +with the `git xyz` interfaces. You can learn things by just looking +at what the various git scripts do. For example, `git reset` is the +above two lines implemented in `git-reset`, but some things like +`git status` and `git commit` are slightly more complex scripts around +the basic git commands. + +Many (most?) public remote repositories will not contain any of +the checked out files or even an index file, and will *only* contain the +actual core git files. Such a repository usually doesn't even have the +`.git` subdirectory, but has all the git files directly in the +repository. + +To create your own local live copy of such a "raw" git repository, you'd +first create your own subdirectory for the project, and then copy the +raw repository contents into the `.git` directory. For example, to +create your own copy of the git repository, you'd do the following + + mkdir my-git + cd my-git + rsync -rL rsync://rsync.kernel.org/pub/scm/git/git.git/ .git + +followed by + + git-read-tree HEAD + +to populate the index. However, now you have populated the index, and +you have all the git internal files, but you will notice that you don't +actually have any of the working tree files to work on. To get +those, you'd check them out with + + git-checkout-index -u -a + +where the `-u` flag means that you want the checkout to keep the index +up-to-date (so that you don't have to refresh it afterward), and the +`-a` flag means "check out all files" (if you have a stale copy or an +older version of a checked out tree you may also need to add the `-f` +flag first, to tell git-checkout-index to *force* overwriting of any old +files). + +Again, this can all be simplified with + + git clone rsync://rsync.kernel.org/pub/scm/git/git.git/ my-git + cd my-git + git checkout + +which will end up doing all of the above for you. + +You have now successfully copied somebody else's (mine) remote +repository, and checked it out. + + +Creating a new branch +--------------------- + +Branches in git are really nothing more than pointers into the git +object database from within the `.git/refs/` subdirectory, and as we +already discussed, the `HEAD` branch is nothing but a symlink to one of +these object pointers. + +You can at any time create a new branch by just picking an arbitrary +point in the project history, and just writing the SHA1 name of that +object into a file under `.git/refs/heads/`. You can use any filename you +want (and indeed, subdirectories), but the convention is that the +"normal" branch is called `master`. That's just a convention, though, +and nothing enforces it. + +To show that as an example, let's go back to the git-tutorial repository we +used earlier, and create a branch in it. You do that by simply just +saying that you want to check out a new branch: + +------------ +git checkout -b mybranch +------------ + +will create a new branch based at the current `HEAD` position, and switch +to it. + +[NOTE] +================================================ +If you make the decision to start your new branch at some +other point in the history than the current `HEAD`, you can do so by +just telling `git checkout` what the base of the checkout would be. +In other words, if you have an earlier tag or branch, you'd just do + + git checkout -b mybranch earlier-commit + +and it would create the new branch `mybranch` at the earlier commit, +and check out the state at that time. +================================================ + +You can always just jump back to your original `master` branch by doing + + git checkout master + +(or any other branch-name, for that matter) and if you forget which +branch you happen to be on, a simple + + ls -l .git/HEAD + +will tell you where it's pointing. To get the list of branches +you have, you can say + + git branch + +which is nothing more than a simple script around `ls .git/refs/heads`. +There will be asterisk in front of the branch you are currently on. + +Sometimes you may wish to create a new branch _without_ actually +checking it out and switching to it. If so, just use the command + + git branch <branchname> [startingpoint] + +which will simply _create_ the branch, but will not do anything further. +You can then later -- once you decide that you want to actually develop +on that branch -- switch to that branch with a regular `git checkout` +with the branchname as the argument. + + +Merging two branches +-------------------- + +One of the ideas of having a branch is that you do some (possibly +experimental) work in it, and eventually merge it back to the main +branch. So assuming you created the above `mybranch` that started out +being the same as the original `master` branch, let's make sure we're in +that branch, and do some work there. + +------------------------------------------------ +git checkout mybranch +echo "Work, work, work" >>hello +git commit -m 'Some work.' hello +------------------------------------------------ + +Here, we just added another line to `hello`, and we used a shorthand for +doing both `git-update-index hello` and `git commit` by just giving the +filename directly to `git commit`. The `-m` flag is to give the +commit log message from the command line. + +Now, to make it a bit more interesting, let's assume that somebody else +does some work in the original branch, and simulate that by going back +to the master branch, and editing the same file differently there: + +------------ +git checkout master +------------ + +Here, take a moment to look at the contents of `hello`, and notice how they +don't contain the work we just did in `mybranch` -- because that work +hasn't happened in the `master` branch at all. Then do + +------------ +echo "Play, play, play" >>hello +echo "Lots of fun" >>example +git commit -m 'Some fun.' hello example +------------ + +since the master branch is obviously in a much better mood. + +Now, you've got two branches, and you decide that you want to merge the +work done. Before we do that, let's introduce a cool graphical tool that +helps you view what's going on: + + gitk --all + +will show you graphically both of your branches (that's what the `\--all` +means: normally it will just show you your current `HEAD`) and their +histories. You can also see exactly how they came to be from a common +source. + +Anyway, let's exit `gitk` (`^Q` or the File menu), and decide that we want +to merge the work we did on the `mybranch` branch into the `master` +branch (which is currently our `HEAD` too). To do that, there's a nice +script called `git resolve`, which wants to know which branches you want +to resolve and what the merge is all about: + +------------ +git resolve HEAD mybranch "Merge work in mybranch" +------------ + +where the third argument is going to be used as the commit message if +the merge can be resolved automatically. + +Now, in this case we've intentionally created a situation where the +merge will need to be fixed up by hand, though, so git will do as much +of it as it can automatically (which in this case is just merge the `example` +file, which had no differences in the `mybranch` branch), and say: + + Simple merge failed, trying Automatic merge + Auto-merging hello. + merge: warning: conflicts during merge + ERROR: Merge conflict in hello. + fatal: merge program failed + Automatic merge failed, fix up by hand + +which is way too verbose, but it basically tells you that it failed the +really trivial merge ("Simple merge") and did an "Automatic merge" +instead, but that too failed due to conflicts in `hello`. + +Not to worry. It left the (trivial) conflict in `hello` in the same form you +should already be well used to if you've ever used CVS, so let's just +open `hello` in our editor (whatever that may be), and fix it up somehow. +I'd suggest just making it so that `hello` contains all four lines: + +------------ +Hello World +It's a new day for git +Play, play, play +Work, work, work +------------ + +and once you're happy with your manual merge, just do a + +------------ +git commit hello +------------ + +which will very loudly warn you that you're now committing a merge +(which is correct, so never mind), and you can write a small merge +message about your adventures in git-merge-land. + +After you're done, start up `gitk \--all` to see graphically what the +history looks like. Notice that `mybranch` still exists, and you can +switch to it, and continue to work with it if you want to. The +`mybranch` branch will not contain the merge, but next time you merge it +from the `master` branch, git will know how you merged it, so you'll not +have to do _that_ merge again. + +Another useful tool, especially if you do not always work in X-Window +environment, is `git show-branch`. + +------------------------------------------------ +$ git show-branch master mybranch +* [master] Merged "mybranch" changes. + ! [mybranch] Some work. +-- ++ [master] Merged "mybranch" changes. ++ [master~1] Some fun. +++ [mybranch] Some work. +------------------------------------------------ + +The first two lines indicate that it is showing the two branches +and the first line of the commit log message from their +top-of-the-tree commits, you are currently on `master` branch +(notice the asterisk `*` character), and the first column for +the later output lines is used to show commits contained in the +`master` branch, and the second column for the `mybranch` +branch. Three commits are shown along with their log messages. +All of them have plus `+` characters in the first column, which +means they are now part of the `master` branch. Only the "Some +work" commit has the plus `+` character in the second column, +because `mybranch` has not been merged to incorporate these +commits from the master branch. The string inside brackets +before the commit log message is a short name you can use to +name the commit. In the above example, 'master' and 'mybranch' +are branch heads. 'master~1' is the first parent of 'master' +branch head. Please see 'git-rev-parse' documentation if you +see more complex cases. + +Now, let's pretend you are the one who did all the work in +`mybranch`, and the fruit of your hard work has finally been merged +to the `master` branch. Let's go back to `mybranch`, and run +resolve to get the "upstream changes" back to your branch. + + git checkout mybranch + git resolve HEAD master "Merge upstream changes." + +This outputs something like this (the actual commit object names +would be different) + + Updating from ae3a2da... to a80b4aa.... + example | 1 + + hello | 1 + + 2 files changed, 2 insertions(+), 0 deletions(-) + +Because your branch did not contain anything more than what are +already merged into the `master` branch, the resolve operation did +not actually do a merge. Instead, it just updated the top of +the tree of your branch to that of the `master` branch. This is +often called 'fast forward' merge. + +You can run `gitk \--all` again to see how the commit ancestry +looks like, or run `show-branch`, which tells you this. + +------------------------------------------------ +$ git show-branch master mybranch +! [master] Merged "mybranch" changes. + * [mybranch] Merged "mybranch" changes. +-- +++ [master] Merged "mybranch" changes. +------------------------------------------------ + + +Merging external work +--------------------- + +It's usually much more common that you merge with somebody else than +merging with your own branches, so it's worth pointing out that git +makes that very easy too, and in fact, it's not that different from +doing a `git resolve`. In fact, a remote merge ends up being nothing +more than "fetch the work from a remote repository into a temporary tag" +followed by a `git resolve`. + +Fetching from a remote repository is done by, unsurprisingly, +`git fetch`: + + git fetch <remote-repository> + +One of the following transports can be used to name the +repository to download from: + +Rsync:: + `rsync://remote.machine/path/to/repo.git/` ++ +Rsync transport is usable for both uploading and downloading, +but is completely unaware of what git does, and can produce +unexpected results when you download from the public repository +while the repository owner is uploading into it via `rsync` +transport. Most notably, it could update the files under +`refs/` which holds the object name of the topmost commits +before uploading the files in `objects/` -- the downloader would +obtain head commit object name while that object itself is still +not available in the repository. For this reason, it is +considered deprecated. + +SSH:: + `remote.machine:/path/to/repo.git/` or ++ +`ssh://remote.machine/path/to/repo.git/` ++ +This transport can be used for both uploading and downloading, +and requires you to have a log-in privilege over `ssh` to the +remote machine. It finds out the set of objects the other side +lacks by exchanging the head commits both ends have and +transfers (close to) minimum set of objects. It is by far the +most efficient way to exchange git objects between repositories. + +Local directory:: + `/path/to/repo.git/` ++ +This transport is the same as SSH transport but uses `sh` to run +both ends on the local machine instead of running other end on +the remote machine via `ssh`. + +GIT Native:: + `git://remote.machine/path/to/repo.git/` ++ +This transport was designed for anonymous downloading. Like SSH +transport, it finds out the set of objects the downstream side +lacks and transfers (close to) minimum set of objects. + +HTTP(s):: + `http://remote.machine/path/to/repo.git/` ++ +HTTP and HTTPS transport are used only for downloading. They +first obtain the topmost commit object name from the remote site +by looking at `repo.git/info/refs` file, tries to obtain the +commit object by downloading from `repo.git/objects/xx/xxx\...` +using the object name of that commit object. Then it reads the +commit object to find out its parent commits and the associate +tree object; it repeats this process until it gets all the +necessary objects. Because of this behaviour, they are +sometimes also called 'commit walkers'. ++ +The 'commit walkers' are sometimes also called 'dumb +transports', because they do not require any GIT aware smart +server like GIT Native transport does. Any stock HTTP server +would suffice. ++ +There are (confusingly enough) `git-ssh-fetch` and `git-ssh-upload` +programs, which are 'commit walkers'; they outlived their +usefulness when GIT Native and SSH transports were introduced, +and not used by `git pull` or `git push` scripts. + +Once you fetch from the remote repository, you `resolve` that +with your current branch. + +However -- it's such a common thing to `fetch` and then +immediately `resolve`, that it's called `git pull`, and you can +simply do + + git pull <remote-repository> + +and optionally give a branch-name for the remote end as a second +argument. + +[NOTE] +You could do without using any branches at all, by +keeping as many local repositories as you would like to have +branches, and merging between them with `git pull`, just like +you merge between branches. The advantage of this approach is +that it lets you keep set of files for each `branch` checked +out and you may find it easier to switch back and forth if you +juggle multiple lines of development simultaneously. Of +course, you will pay the price of more disk usage to hold +multiple working trees, but disk space is cheap these days. + +[NOTE] +You could even pull from your own repository by +giving '.' as <remote-repository> parameter to `git pull`. + +It is likely that you will be pulling from the same remote +repository from time to time. As a short hand, you can store +the remote repository URL in a file under .git/remotes/ +directory, like this: + +------------------------------------------------ +mkdir -p .git/remotes/ +cat >.git/remotes/linus <<\EOF +URL: http://www.kernel.org/pub/scm/git/git.git/ +EOF +------------------------------------------------ + +and use the filename to `git pull` instead of the full URL. +The URL specified in such file can even be a prefix +of a full URL, like this: + +------------------------------------------------ +cat >.git/remotes/jgarzik <<\EOF +URL: http://www.kernel.org/pub/scm/linux/git/jgarzik/ +EOF +------------------------------------------------ + + +Examples. + +. `git pull linus` +. `git pull linus tag v0.99.1` +. `git pull jgarzik/netdev-2.6.git/ e100` + +the above are equivalent to: + +. `git pull http://www.kernel.org/pub/scm/git/git.git/ HEAD` +. `git pull http://www.kernel.org/pub/scm/git/git.git/ tag v0.99.1` +. `git pull http://www.kernel.org/pub/.../jgarzik/netdev-2.6.git e100` + + +Publishing your work +-------------------- + +So we can use somebody else's work from a remote repository; but +how can *you* prepare a repository to let other people pull from +it? + +Your do your real work in your working tree that has your +primary repository hanging under it as its `.git` subdirectory. +You *could* make that repository accessible remotely and ask +people to pull from it, but in practice that is not the way +things are usually done. A recommended way is to have a public +repository, make it reachable by other people, and when the +changes you made in your primary working tree are in good shape, +update the public repository from it. This is often called +'pushing'. + +[NOTE] +This public repository could further be mirrored, and that is +how git repositories at `kernel.org` are managed. + +Publishing the changes from your local (private) repository to +your remote (public) repository requires a write privilege on +the remote machine. You need to have an SSH account there to +run a single command, `git-receive-pack`. + +First, you need to create an empty repository on the remote +machine that will house your public repository. This empty +repository will be populated and be kept up-to-date by pushing +into it later. Obviously, this repository creation needs to be +done only once. + +[NOTE] +`git push` uses a pair of programs, +`git-send-pack` on your local machine, and `git-receive-pack` +on the remote machine. The communication between the two over +the network internally uses an SSH connection. + +Your private repository's GIT directory is usually `.git`, but +your public repository is often named after the project name, +i.e. `<project>.git`. Let's create such a public repository for +project `my-git`. After logging into the remote machine, create +an empty directory: + + mkdir my-git.git + +Then, make that directory into a GIT repository by running +`git init-db`, but this time, since its name is not the usual +`.git`, we do things slightly differently: + + GIT_DIR=my-git.git git-init-db + +Make sure this directory is available for others you want your +changes to be pulled by via the transport of your choice. Also +you need to make sure that you have the `git-receive-pack` +program on the `$PATH`. + +[NOTE] +Many installations of sshd do not invoke your shell as the login +shell when you directly run programs; what this means is that if +your login shell is `bash`, only `.bashrc` is read and not +`.bash_profile`. As a workaround, make sure `.bashrc` sets up +`$PATH` so that you can run `git-receive-pack` program. + +[NOTE] +If you plan to publish this repository to be accessed over http, +you should do `chmod +x my-git.git/hooks/post-update` at this +point. This makes sure that every time you push into this +repository, `git-update-server-info` is run. + +Your "public repository" is now ready to accept your changes. +Come back to the machine you have your private repository. From +there, run this command: + + git push <public-host>:/path/to/my-git.git master + +This synchronizes your public repository to match the named +branch head (i.e. `master` in this case) and objects reachable +from them in your current repository. + +As a real example, this is how I update my public git +repository. Kernel.org mirror network takes care of the +propagation to other publicly visible machines: + + git push master.kernel.org:/pub/scm/git/git.git/ + + +Packing your repository +----------------------- + +Earlier, we saw that one file under `.git/objects/??/` directory +is stored for each git object you create. This representation +is efficient to create atomically and safely, but +not so convenient to transport over the network. Since git objects are +immutable once they are created, there is a way to optimize the +storage by "packing them together". The command + + git repack + +will do it for you. If you followed the tutorial examples, you +would have accumulated about 17 objects in `.git/objects/??/` +directories by now. `git repack` tells you how many objects it +packed, and stores the packed file in `.git/objects/pack` +directory. + +[NOTE] +You will see two files, `pack-\*.pack` and `pack-\*.idx`, +in `.git/objects/pack` directory. They are closely related to +each other, and if you ever copy them by hand to a different +repository for whatever reason, you should make sure you copy +them together. The former holds all the data from the objects +in the pack, and the latter holds the index for random +access. + +If you are paranoid, running `git-verify-pack` command would +detect if you have a corrupt pack, but do not worry too much. +Our programs are always perfect ;-). + +Once you have packed objects, you do not need to leave the +unpacked objects that are contained in the pack file anymore. + + git prune-packed + +would remove them for you. + +You can try running `find .git/objects -type f` before and after +you run `git prune-packed` if you are curious. Also `git +count-objects` would tell you how many unpacked objects are in +your repository and how much space they are consuming. + +[NOTE] +`git pull` is slightly cumbersome for HTTP transport, as a +packed repository may contain relatively few objects in a +relatively large pack. If you expect many HTTP pulls from your +public repository you might want to repack & prune often, or +never. + +If you run `git repack` again at this point, it will say +"Nothing to pack". Once you continue your development and +accumulate the changes, running `git repack` again will create a +new pack, that contains objects created since you packed your +repository the last time. We recommend that you pack your project +soon after the initial import (unless you are starting your +project from scratch), and then run `git repack` every once in a +while, depending on how active your project is. + +When a repository is synchronized via `git push` and `git pull` +objects packed in the source repository are usually stored +unpacked in the destination, unless rsync transport is used. +While this allows you to use different packing strategies on +both ends, it also means you may need to repack both +repositories every once in a while. + + +Working with Others +------------------- + +Although git is a truly distributed system, it is often +convenient to organize your project with an informal hierarchy +of developers. Linux kernel development is run this way. There +is a nice illustration (page 17, "Merges to Mainline") in Randy +Dunlap's presentation (`http://tinyurl.com/a2jdg`). + +It should be stressed that this hierarchy is purely *informal*. +There is nothing fundamental in git that enforces the "chain of +patch flow" this hierarchy implies. You do not have to pull +from only one remote repository. + +A recommended workflow for a "project lead" goes like this: + +1. Prepare your primary repository on your local machine. Your + work is done there. + +2. Prepare a public repository accessible to others. ++ +If other people are pulling from your repository over dumb +transport protocols, you need to keep this repository 'dumb +transport friendly'. After `git init-db`, +`$GIT_DIR/hooks/post-update` copied from the standard templates +would contain a call to `git-update-server-info` but the +`post-update` hook itself is disabled by default -- enable it +with `chmod +x post-update`. + +3. Push into the public repository from your primary + repository. + +4. `git repack` the public repository. This establishes a big + pack that contains the initial set of objects as the + baseline, and possibly `git prune` if the transport + used for pulling from your repository supports packed + repositories. + +5. Keep working in your primary repository. Your changes + include modifications of your own, patches you receive via + e-mails, and merges resulting from pulling the "public" + repositories of your "subsystem maintainers". ++ +You can repack this private repository whenever you feel like. + +6. Push your changes to the public repository, and announce it + to the public. + +7. Every once in a while, "git repack" the public repository. + Go back to step 5. and continue working. + + +A recommended work cycle for a "subsystem maintainer" who works +on that project and has an own "public repository" goes like this: + +1. Prepare your work repository, by `git clone` the public + repository of the "project lead". The URL used for the + initial cloning is stored in `.git/remotes/origin`. + +2. Prepare a public repository accessible to others, just like + the "project lead" person does. + +3. Copy over the packed files from "project lead" public + repository to your public repository. + +4. Push into the public repository from your primary + repository. Run `git repack`, and possibly `git prune` if the + transport used for pulling from your repository supports + packed repositories. + +5. Keep working in your primary repository. Your changes + include modifications of your own, patches you receive via + e-mails, and merges resulting from pulling the "public" + repositories of your "project lead" and possibly your + "sub-subsystem maintainers". ++ +You can repack this private repository whenever you feel +like. + +6. Push your changes to your public repository, and ask your + "project lead" and possibly your "sub-subsystem + maintainers" to pull from it. + +7. Every once in a while, `git repack` the public repository. + Go back to step 5. and continue working. + + +A recommended work cycle for an "individual developer" who does +not have a "public" repository is somewhat different. It goes +like this: + +1. Prepare your work repository, by `git clone` the public + repository of the "project lead" (or a "subsystem + maintainer", if you work on a subsystem). The URL used for + the initial cloning is stored in `.git/remotes/origin`. + +2. Do your work in your repository on 'master' branch. + +3. Run `git fetch origin` from the public repository of your + upstream every once in a while. This does only the first + half of `git pull` but does not merge. The head of the + public repository is stored in `.git/refs/heads/origin`. + +4. Use `git cherry origin` to see which ones of your patches + were accepted, and/or use `git rebase origin` to port your + unmerged changes forward to the updated upstream. + +5. Use `git format-patch origin` to prepare patches for e-mail + submission to your upstream and send it out. Go back to + step 2. and continue. + + +Working with Others, Shared Repository Style +-------------------------------------------- + +If you are coming from CVS background, the style of cooperation +suggested in the previous section may be new to you. You do not +have to worry. git supports "shared public repository" style of +cooperation you are probably more familiar with as well. + +For this, set up a public repository on a machine that is +reachable via SSH by people with "commit privileges". Put the +committers in the same user group and make the repository +writable by that group. + +You, as an individual committer, then: + +- First clone the shared repository to a local repository: +------------------------------------------------ +$ git clone repo.shared.xz:/pub/scm/project.git/ my-project +$ cd my-project +$ hack away +------------------------------------------------ + +- Merge the work others might have done while you were hacking + away: +------------------------------------------------ +$ git pull origin +$ test the merge result +------------------------------------------------ +[NOTE] +================================ +The first `git clone` would have placed the following in +`my-project/.git/remotes/origin` file, and that's why this and +the next step work. +------------ +URL: repo.shared.xz:/pub/scm/project.git/ my-project +Pull: master:origin +------------ +================================ + +- push your work as the new head of the shared + repository. +------------------------------------------------ +$ git push origin master +------------------------------------------------ +If somebody else pushed into the same shared repository while +you were working locally, `git push` in the last step would +complain, telling you that the remote `master` head does not +fast forward. You need to pull and merge those other changes +back before you push your work when it happens. + + +Bundling your work together +--------------------------- + +It is likely that you will be working on more than one thing at +a time. It is easy to use those more-or-less independent tasks +using branches with git. + +We have already seen how branches work in a previous example, +with "fun and work" example using two branches. The idea is the +same if there are more than two branches. Let's say you started +out from "master" head, and have some new code in the "master" +branch, and two independent fixes in the "commit-fix" and +"diff-fix" branches: + +------------ +$ git show-branch +! [commit-fix] Fix commit message normalization. + ! [diff-fix] Fix rename detection. + * [master] Release candidate #1 +--- + + [diff-fix] Fix rename detection. + + [diff-fix~1] Better common substring algorithm. ++ [commit-fix] Fix commit message normalization. + + [master] Release candidate #1 ++++ [diff-fix~2] Pretty-print messages. +------------ + +Both fixes are tested well, and at this point, you want to merge +in both of them. You could merge in 'diff-fix' first and then +'commit-fix' next, like this: + +------------ +$ git resolve master diff-fix 'Merge fix in diff-fix' +$ git resolve master commit-fix 'Merge fix in commit-fix' +------------ + +Which would result in: + +------------ +$ git show-branch +! [commit-fix] Fix commit message normalization. + ! [diff-fix] Fix rename detection. + * [master] Merge fix in commit-fix +--- + + [master] Merge fix in commit-fix ++ + [commit-fix] Fix commit message normalization. + + [master~1] Merge fix in diff-fix + ++ [diff-fix] Fix rename detection. + ++ [diff-fix~1] Better common substring algorithm. + + [master~2] Release candidate #1 ++++ [master~3] Pretty-print messages. +------------ + +However, there is no particular reason to merge in one branch +first and the other next, when what you have are a set of truly +independent changes (if the order mattered, then they are not +independent by definition). You could instead merge those two +branches into the current branch at once. First let's undo what +we just did and start over. We would want to get the master +branch before these two merges by resetting it to 'master~2': + +------------ +$ git reset --hard master~2 +------------ + +You can make sure 'git show-branch' matches the state before +those two 'git resolve' you just did. Then, instead of running +two 'git resolve' commands in a row, you would pull these two +branch heads (this is known as 'making an Octopus'): + +------------ +$ git pull . commit-fix diff-fix +$ git show-branch +! [commit-fix] Fix commit message normalization. + ! [diff-fix] Fix rename detection. + * [master] Octopus merge of branches 'diff-fix' and 'commit-fix' +--- + + [master] Octopus merge of branches 'diff-fix' and 'commit-fix' ++ + [commit-fix] Fix commit message normalization. + ++ [diff-fix] Fix rename detection. + ++ [diff-fix~1] Better common substring algorithm. + + [master~1] Release candidate #1 ++++ [master~2] Pretty-print messages. +------------ + +Note that you should not do Octopus because you can. An octopus +is a valid thing to do and often makes it easier to view the +commit history if you are pulling more than two independent +changes at the same time. However, if you have merge conflicts +with any of the branches you are merging in and need to hand +resolve, that is an indication that the development happened in +those branches were not independent after all, and you should +merge two at a time, documenting how you resolved the conflicts, +and the reason why you preferred changes made in one side over +the other. Otherwise it would make the project history harder +to follow, not easier. + +[ to be continued.. cvsimports ] |