diff options
Diffstat (limited to 'Documentation')
139 files changed, 15175 insertions, 0 deletions
diff --git a/Documentation/.gitignore b/Documentation/.gitignore new file mode 100644 index 0000000..c87c61a --- /dev/null +++ b/Documentation/.gitignore @@ -0,0 +1,7 @@ +*.xml +*.html +*.1 +*.7 +howto-index.txt +doc.dep +README diff --git a/Documentation/Makefile b/Documentation/Makefile new file mode 100644 index 0000000..a3bca86 --- /dev/null +++ b/Documentation/Makefile @@ -0,0 +1,106 @@ +MAN1_TXT=$(wildcard git-*.txt) gitk.txt +MAN7_TXT=git.txt + +DOC_HTML=$(patsubst %.txt,%.html,$(MAN1_TXT) $(MAN7_TXT)) + +ARTICLES = tutorial +ARTICLES += core-tutorial +ARTICLES += cvs-migration +ARTICLES += diffcore +ARTICLES += howto-index +ARTICLES += repository-layout +ARTICLES += hooks +ARTICLES += everyday +# 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) + + +# +# Determine "include::" file references in asciidoc files. +# +doc.dep : $(wildcard *.txt) build-docdep.perl + rm -f $@+ $@ + perl ./build-docdep.perl >$@+ + mv $@+ $@ + +-include doc.dep + +git.7: README + +README: ../README + cp $< $@ + + +clean: + rm -f *.xml *.html *.1 *.7 howto-index.txt howto/*.html doc.dep README + +%.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 0000000..9ccb8f7 --- /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 0000000..fa0877d --- /dev/null +++ b/Documentation/asciidoc.conf @@ -0,0 +1,26 @@ +## 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. + +[attributes] +caret=^ + +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/build-docdep.perl b/Documentation/build-docdep.perl new file mode 100755 index 0000000..489389c --- /dev/null +++ b/Documentation/build-docdep.perl @@ -0,0 +1,50 @@ +#!/usr/bin/perl + +my %include = (); +my %included = (); + +for my $text (<*.txt>) { + open I, '<', $text || die "cannot read: $text"; + while (<I>) { + if (/^include::/) { + chomp; + s/^include::\s*//; + s/\[\]//; + $include{$text}{$_} = 1; + $included{$_} = 1; + } + } + close I; +} + +# Do we care about chained includes??? +my $changed = 1; +while ($changed) { + $changed = 0; + while (my ($text, $included) = each %include) { + for my $i (keys %$included) { + # $text has include::$i; if $i includes $j + # $text indirectly includes $j. + if (exists $include{$i}) { + for my $j (keys %{$include{$i}}) { + if (!exists $include{$text}{$j}) { + $include{$text}{$j} = 1; + $included{$j} = 1; + $changed = 1; + } + } + } + } + } +} + +while (my ($text, $included) = each %include) { + if (! exists $included{$text} && + (my $base = $text) =~ s/\.txt$//) { + my ($suffix) = '1'; + if ($base eq 'git') { + $suffix = '7'; # yuck... + } + print "$base.html $base.$suffix : ", join(" ", keys %$included), "\n"; + } +} diff --git a/Documentation/core-tutorial.txt b/Documentation/core-tutorial.txt new file mode 100644 index 0000000..4211c81 --- /dev/null +++ b/Documentation/core-tutorial.txt @@ -0,0 +1,1722 @@ +A short git tutorial +==================== + +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. + +The material presented here often goes deep describing how things +work internally. If you are mostly interested in using git as a +SCM, you can skip them during your first pass. + +[NOTE] +And those "too deep" descriptions are often marked as Note. + +[NOTE] +If you are already familiar with another version control system, +like CVS, you may want to take a look at +link:everyday.html[Everyday GIT in 20 commands or so] first +before reading this. + + +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 file called `HEAD`, that has `ref: refs/heads/master` in it. + This is similar to a symbolic link and points at + `refs/heads/master` relative to the `HEAD` file. ++ +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 points 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 index +(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 index 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 +diff --git a/hello b/hello +index 557db03..263414f 100644 +--- 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. + +------------ +$ git diff +diff --git a/hello b/hello +index 557db03..263414f 100644 +--- a/hello ++++ b/hello +@@ -1 +1,2 @@ + Hello World ++It's a new day for git +------------ + + +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 create the `.git/refs/heads/master` file +which is pointed at by `HEAD`. This file is supposed to contain +the reference to the top-of-tree of the master branch, and since +that's exactly what `git-commit-tree` spits out, we can do this +all with a sequence of simple shell commands: + +------------------------------------------------ +$ tree=$(git-write-tree) +$ commit=$(echo 'Initial commit' | git-commit-tree $tree) +$ git-update-ref HEAD $commit +------------------------------------------------ + +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 index), 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. + +[NOTE] +============ +Here is an ASCII art by Jon Loeliger that illustrates how +various diff-\* commands compare things. + + diff-tree + +----+ + | | + | | + V V + +-----------+ + | Object DB | + | Backing | + | Store | + +-----------+ + ^ ^ + | | + | | diff-index --cached + | | + diff-index | V + | +-----------+ + | | Index | + | | "cache" | + | +-----------+ + | ^ + | | + | | diff-files + | | + V V + +-----------+ + | Working | + | Directory | + +-----------+ +============ + +More interestingly, you can also give `git-diff-tree` the `--pretty` 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 relocatable +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 + +------------ +$ cat .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.' -i 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`, with an `-i` flag (it tells +git to 'include' that file in addition to what you have done to +the index file so far when making the 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.' -i 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 merge`, which wants to know which branches you want +to resolve and what the merge is all about: + +------------ +$ git merge "Merge work in mybranch" HEAD mybranch +------------ + +where the first 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: + +---------------- + Trying really trivial in-index merge... + fatal: Merge requires file-level merging + Nope. + ... + Auto-merging hello + CONFLICT (content): Merge conflict in hello + 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 -i 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 --topo-order master mybranch +* [master] Merge work in mybranch + ! [mybranch] Some work. +-- +- [master] Merge work in mybranch +*+ [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 non blank characters in the first column (`*` +shows an ordinary commit on the current branch, `.` is a merge commit), 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 merge "Merge upstream changes." HEAD master +------------ + +This outputs something like this (the actual commit object names +would be different) + +---------------- +Updating from ae3a2da... to a80b4aa.... +Fast forward + 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] Merge work in mybranch + * [mybranch] Merge work in mybranch +-- +-- [master] Merge work in mybranch +------------------------------------------------ + + +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 merge`. 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 merge`. + +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/` ++ +Downloader from http and https URL +first obtains the topmost commit object name from the remote site +by looking at the specified refname under `repo.git/refs/` directory, +and then 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 +that does not even support directory index would suffice. But +you must prepare your repository with `git-update-server-info` +to help dumb transport downloaders. ++ +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`. This +is useful when you want to merge a local branch (or more, if you +are making an Octopus) into the current branch. + +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` + + +How does the merge work? +------------------------ + +We said this tutorial shows what plumbing does to help you cope +with the porcelain that isn't flushing, but we so far did not +talk about how the merge really works. If you are following +this tutorial the first time, I'd suggest to skip to "Publishing +your work" section and come back here later. + +OK, still with me? To give us an example to look at, let's go +back to the earlier repository with "hello" and "example" file, +and bring ourselves back to the pre-merge state: + +------------ +$ git show-branch --more=3 master mybranch +! [master] Merge work in mybranch + * [mybranch] Merge work in mybranch +-- +-- [master] Merge work in mybranch ++* [master^2] Some work. ++* [master^] Some fun. +------------ + +Remember, before running `git merge`, our `master` head was at +"Some fun." commit, while our `mybranch` head was at "Some +work." commit. + +------------ +$ git checkout mybranch +$ git reset --hard master^2 +$ git checkout master +$ git reset --hard master^ +------------ + +After rewinding, the commit structure should look like this: + +------------ +$ git show-branch +* [master] Some fun. + ! [mybranch] Some work. +-- + + [mybranch] Some work. +* [master] Some fun. +*+ [mybranch^] New day. +------------ + +Now we are ready to experiment with the merge by hand. + +`git merge` command, when merging two branches, uses 3-way merge +algorithm. First, it finds the common ancestor between them. +The command it uses is `git-merge-base`: + +------------ +$ mb=$(git-merge-base HEAD mybranch) +------------ + +The command writes the commit object name of the common ancestor +to the standard output, so we captured its output to a variable, +because we will be using it in the next step. BTW, the common +ancestor commit is the "New day." commit in this case. You can +tell it by: + +------------ +$ git-name-rev $mb +my-first-tag +------------ + +After finding out a common ancestor commit, the second step is +this: + +------------ +$ git-read-tree -m -u $mb HEAD mybranch +------------ + +This is the same `git-read-tree` command we have already seen, +but it takes three trees, unlike previous examples. This reads +the contents of each tree into different 'stage' in the index +file (the first tree goes to stage 1, the second stage 2, +etc.). After reading three trees into three stages, the paths +that are the same in all three stages are 'collapsed' into stage +0. Also paths that are the same in two of three stages are +collapsed into stage 0, taking the SHA1 from either stage 2 or +stage 3, whichever is different from stage 1 (i.e. only one side +changed from the common ancestor). + +After 'collapsing' operation, paths that are different in three +trees are left in non-zero stages. At this point, you can +inspect the index file with this command: + +------------ +$ git-ls-files --stage +100644 7f8b141b65fdcee47321e399a2598a235a032422 0 example +100644 263414f423d0e4d70dae8fe53fa34614ff3e2860 1 hello +100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 2 hello +100644 cc44c73eb783565da5831b4d820c962954019b69 3 hello +------------ + +In our example of only two files, we did not have unchanged +files so only 'example' resulted in collapsing, but in real-life +large projects, only small number of files change in one commit, +and this 'collapsing' tends to trivially merge most of the paths +fairly quickly, leaving only a handful the real changes in non-zero +stages. + +To look at only non-zero stages, use `\--unmerged` flag: + +------------ +$ git-ls-files --unmerged +100644 263414f423d0e4d70dae8fe53fa34614ff3e2860 1 hello +100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 2 hello +100644 cc44c73eb783565da5831b4d820c962954019b69 3 hello +------------ + +The next step of merging is to merge these three versions of the +file, using 3-way merge. This is done by giving +`git-merge-one-file` command as one of the arguments to +`git-merge-index` command: + +------------ +$ git-merge-index git-merge-one-file hello +Auto-merging hello. +merge: warning: conflicts during merge +ERROR: Merge conflict in hello. +fatal: merge program failed +------------ + +`git-merge-one-file` script is called with parameters to +describe those three versions, and is responsible to leave the +merge results in the working tree. +It is a fairly straightforward shell script, and +eventually calls `merge` program from RCS suite to perform a +file-level 3-way merge. In this case, `merge` detects +conflicts, and the merge result with conflict marks is left in +the working tree.. This can be seen if you run `ls-files +--stage` again at this point: + +------------ +$ git-ls-files --stage +100644 7f8b141b65fdcee47321e399a2598a235a032422 0 example +100644 263414f423d0e4d70dae8fe53fa34614ff3e2860 1 hello +100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 2 hello +100644 cc44c73eb783565da5831b4d820c962954019b69 3 hello +------------ + +This is the state of the index file and the working file after +`git merge` returns control back to you, leaving the conflicting +merge for you to resolve. Notice that the path `hello` is still +unmerged, and what you see with `git diff` at this point is +differences since stage 2 (i.e. your version). + + +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 (HTTP), 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`. This makes sure `git-update-server-info` +keeps the necessary files up-to-date. + +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, unless the "project + lead" repository lives on the same machine as yours. In the + latter case, you can use `objects/info/alternates` file to + point at the repository you are borrowing from. + +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. + +See link:cvs-migration.txt[git for CVS users] for the details. + +Bundling your work together +--------------------------- + +It is likely that you will be working on more than one thing at +a time. It is easy to manage those more-or-less independent tasks +using branches with git. + +We have already seen how branches work previously, +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 merge 'Merge fix in diff-fix' master diff-fix +$ git merge 'Merge fix in commit-fix' master 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 merge' you just did. Then, instead of running +two 'git merge' 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 ] diff --git a/Documentation/cvs-migration.txt b/Documentation/cvs-migration.txt new file mode 100644 index 0000000..fa94efd --- /dev/null +++ b/Documentation/cvs-migration.txt @@ -0,0 +1,304 @@ +git for CVS users +================= + +So you're a CVS user. That's ok, it's a treatable condition. The job of +this document is to put you on the road to recovery, by helping you +convert an existing cvs repository to git, and by showing you how to use a +git repository in a cvs-like fashion. + +Some basic familiarity with git is required. This +link:tutorial.html[tutorial introduction to git] should be sufficient. + +First, note some ways that git differs from CVS: + + * Commits are atomic and project-wide, not per-file as in CVS. + + * Offline work is supported: you can make multiple commits locally, + then submit them when you're ready. + + * Branching is fast and easy. + + * Every working tree contains a repository with a full copy of the + project history, and no repository is inherently more important than + any other. However, you can emulate the CVS model by designating a + single shared repository which people can synchronize with; see below + for details. + +Importing a CVS archive +----------------------- + +First, install version 2.1 or higher of cvsps from +link:http://www.cobite.com/cvsps/[http://www.cobite.com/cvsps/] and make +sure it is in your path. The magic command line is then + +------------------------------------------- +$ git cvsimport -v -d <cvsroot> -C <destination> <module> +------------------------------------------- + +This puts a git archive of the named CVS module in the directory +<destination>, which will be created if necessary. The -v option makes +the conversion script very chatty. + +The import checks out from CVS every revision of every file. Reportedly +cvsimport can average some twenty revisions per second, so for a +medium-sized project this should not take more than a couple of minutes. +Larger projects or remote repositories may take longer. + +The main trunk is stored in the git branch named `origin`, and additional +CVS branches are stored in git branches with the same names. The most +recent version of the main trunk is also left checked out on the `master` +branch, so you can start adding your own changes right away. + +The import is incremental, so if you call it again next month it will +fetch any CVS updates that have been made in the meantime. For this to +work, you must not modify the imported branches; instead, create new +branches for your own changes, and merge in the imported branches as +necessary. + +Development Models +------------------ + +CVS users are accustomed to giving a group of developers commit access to +a common repository. In the next section we'll explain how to do this +with git. However, the distributed nature of git allows other development +models, and you may want to first consider whether one of them might be a +better fit for your project. + +For example, you can choose a single person to maintain the project's +primary public repository. Other developers then clone this repository +and each work in their own clone. When they have a series of changes that +they're happy with, they ask the maintainer to pull from the branch +containing the changes. The maintainer reviews their changes and pulls +them into the primary repository, which other developers pull from as +necessary to stay coordinated. The Linux kernel and other projects use +variants of this model. + +With a small group, developers may just pull changes from each other's +repositories without the need for a central maintainer. + +Emulating the CVS Development Model +----------------------------------- + +Start with an ordinary git working directory containing the project, and +remove the checked-out files, keeping just the bare .git directory: + +------------------------------------------------ +$ mv project/.git /pub/repo.git +$ rm -r project/ +------------------------------------------------ + +Next, give every team member read/write access to this repository. One +easy way to do this is to give all the team members ssh access to the +machine where the repository is hosted. If you don't want to give them a +full shell on the machine, there is a restricted shell which only allows +users to do git pushes and pulls; see gitlink:git-shell[1]. + +Put all the committers should in the same group, and make the repository +writable by that group: + +------------------------------------------------ +$ chgrp -R $group repo.git +$ find repo.git -mindepth 1 -type d |xargs chmod ug+rwx,g+s +$ GIT_DIR=repo.git git repo-config core.sharedrepository true +------------------------------------------------ + +Make sure committers have a umask of at most 027, so that the directories +they create are writable and searchable by other group members. + +Suppose this repository is now set up in /pub/repo.git on the host +foo.com. Then as an individual commiter you can clone the shared +repository: + +------------------------------------------------ +$ git clone foo.com:/pub/repo.git/ my-project +$ cd my-project +------------------------------------------------ + +and hack away. The equivalent of `cvs update` is + +------------------------------------------------ +$ git pull origin +------------------------------------------------ + +which merges in any work that others might have done since the clone +operation. + +[NOTE] +================================ +The first `git clone` places the following in the +`my-project/.git/remotes/origin` file, and that's why the previous step +and the next step both work. +------------ +URL: foo.com:/pub/project.git/ my-project +Pull: master:origin +------------ +================================ + +You can update the shared repository with your changes using: + +------------------------------------------------ +$ git push origin master +------------------------------------------------ + +If someone else has updated the repository more recently, `git push`, like +`cvs commit`, will complain, in which case you must pull any changes +before attempting the push again. + +In the `git push` command above we specify the name of the remote branch +to update (`master`). If we leave that out, `git push` tries to update +any branches in the remote repository that have the same name as a branch +in the local repository. So the last `push` can be done with either of: + +------------ +$ git push origin +$ git push repo.shared.xz:/pub/scm/project.git/ +------------ + +as long as the shared repository does not have any branches +other than `master`. + +[NOTE] +============ +Because of this behaviour, if the shared repository and the developer's +repository both have branches named `origin`, then a push like the above +attempts to update the `origin` branch in the shared repository from the +developer's `origin` branch. The results may be unexpected, so it's +usually best to remove any branch named `origin` from the shared +repository. +============ + +Advanced Shared Repository Management +------------------------------------- + +Git allows you to specify scripts called "hooks" to be run at certain +points. You can use these, for example, to send all commits to the shared +repository to a mailing list. See link:hooks.txt[Hooks used by git]. + +You can enforce finer grained permissions using update hooks. See +link:howto/update-hook-example.txt[Controlling access to branches using +update hooks]. + +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 archaeologist"). + +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 (otherwise you should go back and read the tutorial). +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". + +NOTE: The current version 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 + +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 0000000..617d8f5 --- /dev/null +++ b/Documentation/diff-format.txt @@ -0,0 +1,197 @@ +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 is +compared differs: + +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 index. + +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 index 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 a file is new on the filesystem +and it is out of sync with the index. + +Example: + +------------------------------------------------ +:100644 100644 5be4a4...... 000000...... M file.c +------------------------------------------------ + +When `-z` option is not used, TAB, LF, and backslash characters +in pathnames are represented as `\t`, `\n`, and `\\`, +respectively. + + +Generating patches with -p +-------------------------- + +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 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|new>, + <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 +index). '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 preceded 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` show 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 one or more extended header lines: + + 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> + index <hash>..<hash> <mode> + +3. TAB, LF, and backslash characters in pathnames are + represented as `\t`, `\n`, and `\\`, respectively. + + +combined diff format +-------------------- + +git-diff-tree and git-diff-files can take '-c' or '--cc' option +to produce 'combined diff', which looks like this: + +------------ +diff --combined describe.c +@@@ +98,7 @@@ + return (a_date > b_date) ? -1 : (a_date == b_date) ? 0 : 1; + } + +- static void describe(char *arg) + -static void describe(struct commit *cmit, int last_one) +++static void describe(char *arg, int last_one) + { + + unsigned char sha1[20]; + + struct commit *cmit; +------------ + +Unlike the traditional 'unified' diff format, which shows two +files A and B with a single column that has `-` (minus -- +appears in A but removed in B), `+` (plus -- missing in A but +added to B), or ` ` (space -- unchanged) prefix, this format +compares two or more files file1, file2,... with one file X, and +shows how X differs from each of fileN. One column for each of +fileN is prepended to the output line to note how X's line is +different from it. + +A `-` character in the column N means that the line appears in +fileN but it does not appear in the last file. A `+` character +in the column N means that the line appears in the last file, +and fileN does not have that line. + +In the above example output, the function signature was changed +from both files (hence two `-` removals from both file1 and +file2, plus `++` to mean one line that was added does not appear +in either file1 nor file2). Also two other lines are the same +from file1 but do not appear in file2 (hence prefixed with ` +`). + +When shown by `git diff-tree -c`, it compares the parents of a +merge commit with the merge result (i.e. file1..fileN are the +parents). When shown by `git diff-files -c`, it compares the +two unresolved merge parents with the working tree file +(i.e. file1 is stage 2 aka "our version", file2 is stage 3 aka +"their version"). + diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt new file mode 100644 index 0000000..5c85167 --- /dev/null +++ b/Documentation/diff-options.txt @@ -0,0 +1,70 @@ +-p:: + Generate patch (see section on generating patches) + +-u:: + Synonym for "-p". + +-z:: + \0 line termination on output + +--name-only:: + Show only names of changed files. + +--name-status:: + Show only names and status of changed files. + +--full-index:: + Instead of the first handful characters, show full + object name of pre- and post-image blob on the "index" + line when generating a patch format output. + +--abbrev[=<n>]:: + Instead of showing the full 40-byte hexadecimal object + name in diff-raw format output and diff-tree header + lines, show only handful hexdigits prefix. This is + independent of --full-index option above, which controls + the diff-patch output format. Non default number of + digits can be specified with --abbrev=<n>. + +-B:: + Break complete rewrite changes into pairs of delete and create. + +-M:: + Detect renames. + +-C:: + Detect copies as well as renames. + +--find-copies-harder:: + For performance reasons, by default, -C option finds copies only + if the original file of the copy was modified in the same + changeset. 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 + is the number of potential rename/copy targets. This + option prevents rename/copy detection from running if + the number of rename/copy targets exceeds the specified + number. + +-S<string>:: + Look for differences that contain the change in <string>. + +--pickaxe-all:: + When -S finds a change, show all the changes in that + changeset, not just the files that contain 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 index 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 0000000..cb4e562 --- /dev/null +++ b/Documentation/diffcore.txt @@ -0,0 +1,275 @@ +Tweaking diff output +==================== +June 2005 + + +Introduction +------------ + +The diff commands git-diff-index, git-diff-files, git-diff-tree, and +git-diff-stages can be told to manipulate differences they find in +unconventional ways before showing diff(1) output. The manipulation +is collectively called "diffcore transformation". This short note +describes what they are and how to use them to produce diff outputs +that are easier to understand than the conventional kind. + + +The chain of operation +---------------------- + +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; + + - git-diff-stages compares contents of blobs at two stages in an + unmerged index file. + +In all of these cases, the commands themselves compare +corresponding paths in the two sets of files. The result of +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: For Ignoring Files Outside Our Consideration +--------------------------------------------------------------- + +The first transformation in the chain is diffcore-pathspec, and +is controlled by giving the pathname parameters to the +git-diff-* commands on the command line. The pathspec is used +to limit the world diff operates in. It removes the filepairs +outside the specified set of pathnames. E.g. If the input set +of filepairs included: + +------------------------------------------------ +:100644 100644 bcd1234... 0123456... M junkfile +------------------------------------------------ + +but the command invocation was "git-diff-files myfile", then the +junkfile entry would be removed from the list because only "myfile" +is under consideration. + +Implementation note. For performance reasons, git-diff-tree +uses the pathname parameters on the command line to cull set of +filepairs it feeds the diffcore mechanism itself, and does not +use diffcore-pathspec, but the end result is the same. + + +diffcore-break: For Splitting Up "Complete Rewrites" +---------------------------------------------------- + +The second transformation in the chain is diffcore-break, and is +controlled by the -B option to the git-diff-* commands. This is +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: For Detection Renames and Copies +------------------------------------------------- + +This transformation is used to detect renames and copies, and is +controlled by the -M option (to detect renames) and the -C option +(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 deleted files (and also unmodified files, if the +"\--find-copies-harder" option is used) are considered as candidates +of the source files in rename/copy operation. If the input were like +these filepairs, that talk about a modified file fileY and a newly +created file file0: + +------------------------------------------------ +:100644 100644 0123456... 1234567... M fileY +:000000 100644 0000000... bcd3456... 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... bcd3456... C100 fileY file0 +------------------------------------------------ + +In both rename and copy detection, the same "extent of changes" +algorithm used in diffcore-break is used to determine if two +files are "similar enough", and can be customized to use +a similarity score different from the default of 50% by giving a +number after the "-M" or "-C" option (e.g. "-M8" to tell it to use +8/10 = 80%). + +Note. When the "-C" option is used with `\--find-copies-harder` +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: For Putting "Complete Rewrites" Back Together +-------------------------------------------------------------------- + +This transformation is used to merge filepairs broken by +diffcore-break, and 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 an unnecessary hack and +the latest implementation always merges all the broken pairs +back into modifications, but the resulting patch output is +formatted differently for easier review in case of 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: For Detecting Addition/Deletion of Specified String +--------------------------------------------------------------------- + +This transformation is used to find filepairs that represent +changes that touch a specified string, and is controlled by the +-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 touch the specified string in its +output. When `\--pickaxe-all` is used, diffcore-pickaxe leaves all +filepairs intact if there is such a filepair, or makes the +output empty otherwise. The latter behaviour is designed to +make reviewing of the changes in the context of the whole +changeset easier. + + +diffcore-order: For Sorting the Output Based on Filenames +--------------------------------------------------------- + +This is used to reorder the filepairs according to the user's +(or project's) taste, and is controlled by the -O option to the +git-diff-* commands. + +This takes a text file each of whose lines is a shell glob +pattern. Filepairs that match a glob pattern on an earlier line +in the file are output before ones that match a later line, and +filepairs that do not match any glob pattern are output last. + +As an example, a typical orderfile for the core git probably +would look like this: + +------------------------------------------------ +README +Makefile +Documentation +*.h +*.c +t +------------------------------------------------ + diff --git a/Documentation/everyday.txt b/Documentation/everyday.txt new file mode 100644 index 0000000..3ab9b91 --- /dev/null +++ b/Documentation/everyday.txt @@ -0,0 +1,441 @@ +Everyday GIT With 20 Commands Or So +=================================== + +GIT suite has over 100 commands, and the manual page for each of +them discusses what the command does and how it is used in +detail, but until you know what command should be used in order +to achieve what you want to do, you cannot tell which manual +page to look at, and if you know that already you do not need +the manual. + +Does that mean you need to know all of them before you can use +git? Not at all. Depending on the role you play, the set of +commands you need to know is slightly different, but in any case +what you need to learn is far smaller than the full set of +commands to carry out your day-to-day work. This document is to +serve as a cheat-sheet and a set of pointers for people playing +various roles. + +<<Basic Repository>> commands are needed by people who has a +repository --- that is everybody, because every working tree of +git is a repository. + +In addition, <<Individual Developer (Standalone)>> commands are +essential for anybody who makes a commit, even for somebody who +works alone. + +If you work with other people, you will need commands listed in +<<Individual Developer (Participant)>> section as well. + +People who play <<Integrator>> role need to learn some more +commands in addition to the above. + +<<Repository Administration>> commands are for system +administrators who are responsible to care and feed git +repositories to support developers. + + +Basic Repository[[Basic Repository]] +------------------------------------ + +Everybody uses these commands to feed and care git repositories. + + * gitlink:git-init-db[1] or gitlink:git-clone[1] to create a + new repository. + + * gitlink:git-fsck-objects[1] to validate the repository. + + * gitlink:git-prune[1] to garbage collect crufts in the + repository. + + * gitlink:git-repack[1] to pack loose objects for efficiency. + +Examples +~~~~~~~~ + +Check health and remove cruft.:: ++ +------------ +$ git fsck-objects <1> +$ git prune +$ git count-objects <2> +$ git repack <3> +$ git prune <4> + +<1> running without "--full" is usually cheap and assures the +repository health reasonably well. +<2> check how many loose objects there are and how much +diskspace is wasted by not repacking. +<3> without "-a" repacks incrementally. repacking every 4-5MB +of loose objects accumulation may be a good rule of thumb. +<4> after repack, prune removes the duplicate loose objects. +------------ + +Repack a small project into single pack.:: ++ +------------ +$ git repack -a -d <1> +$ git prune + +<1> pack all the objects reachable from the refs into one pack +and remove unneeded other packs +------------ + + +Individual Developer (Standalone)[[Individual Developer (Standalone)]] +---------------------------------------------------------------------- + +A standalone individual developer does not exchange patches with +other poeple, and works alone in a single repository, using the +following commands. + + * gitlink:git-show-branch[1] to see where you are. + + * gitlink:git-log[1] to see what happened. + + * gitlink:git-whatchanged[1] to find out where things have + come from. + + * gitlink:git-checkout[1] and gitlink:git-branch[1] to switch + branches. + + * gitlink:git-add[1] and gitlink:git-update-index[1] to manage + the index file. + + * gitlink:git-diff[1] and gitlink:git-status[1] to see what + you are in the middle of doing. + + * gitlink:git-commit[1] to advance the current branch. + + * gitlink:git-reset[1] and gitlink:git-checkout[1] (with + pathname parameters) to undo changes. + + * gitlink:git-pull[1] with "." as the remote to merge between + local branches. + + * gitlink:git-rebase[1] to maintain topic branches. + + * gitlink:git-tag[1] to mark known point. + +Examples +~~~~~~~~ + +Extract a tarball and create a working tree and a new repository to keep track of it.:: ++ +------------ +$ tar zxf frotz.tar.gz +$ cd frotz +$ git-init-db +$ git add . <1> +$ git commit -m 'import of frotz source tree.' +$ git tag v2.43 <2> + +<1> add everything under the current directory. +<2> make a lightweight, unannotated tag. +------------ + +Create a topic branch and develop.:: ++ +------------ +$ git checkout -b alsa-audio <1> +$ edit/compile/test +$ git checkout -- curses/ux_audio_oss.c <2> +$ git add curses/ux_audio_alsa.c <3> +$ edit/compile/test +$ git diff <4> +$ git commit -a -s <5> +$ edit/compile/test +$ git reset --soft HEAD^ <6> +$ edit/compile/test +$ git diff ORIG_HEAD <7> +$ git commit -a -c ORIG_HEAD <8> +$ git checkout master <9> +$ git pull . alsa-audio <10> +$ git log --since='3 days ago' <11> +$ git log v2.43.. curses/ <12> + +<1> create a new topic branch. +<2> revert your botched changes in "curses/ux_audio_oss.c". +<3> you need to tell git if you added a new file; removal and +modification will be caught if you do "commit -a" later. +<4> to see what changes you are committing. +<5> commit everything as you have tested, with your sign-off. +<6> take the last commit back, keeping what is in the working tree. +<7> look at the changes since the premature commit we took back. +<8> redo the commit undone in the previous step, using the message +you originally wrote. +<9> switch to the master branch. +<10> merge a topic branch into your master branch +<11> review commit logs; other forms to limit output can be +combined and include --max-count=10 (show 10 commits), --until='2005-12-10'. +<12> view only the changes that touch what's in curses/ +directory, since v2.43 tag. +------------ + + +Individual Developer (Participant)[[Individual Developer (Participant)]] +------------------------------------------------------------------------ + +A developer working as a participant in a group project needs to +learn how to communicate with others, and uses these commands in +addition to the ones needed by a standalone developer. + + * gitlink:git-clone[1] from the upstream to prime your local + repository. + + * gitlink:git-pull[1] and gitlink:git-fetch[1] from "origin" + to keep up-to-date with the upstream. + + * gitlink:git-push[1] to shared repository, if you adopt CVS + style shared repository workflow. + + * gitlink:git-format-patch[1] to prepare e-mail submission, if + you adopt Linux kernel-style public forum workflow. + +Examples +~~~~~~~~ + +Clone the upstream and work on it. Feed changes to upstream.:: ++ +------------ +$ git clone git://git.kernel.org/pub/scm/.../torvalds/linux-2.6 my2.6 +$ cd my2.6 +$ edit/compile/test; git commit -a -s <1> +$ git format-patch origin <2> +$ git pull <3> +$ git whatchanged -p ORIG_HEAD.. arch/i386 include/asm-i386 <4> +$ git pull git://git.kernel.org/pub/.../jgarzik/libata-dev.git ALL <5> +$ git reset --hard ORIG_HEAD <6> +$ git prune <7> +$ git fetch --tags <8> + +<1> repeat as needed. +<2> extract patches from your branch for e-mail submission. +<3> "pull" fetches from "origin" by default and merges into the +current branch. +<4> immediately after pulling, look at the changes done upstream +since last time we checked, only in the +area we are interested in. +<5> fetch from a specific branch from a specific repository and merge. +<6> revert the pull. +<7> garbage collect leftover objects from reverted pull. +<8> from time to time, obtain official tags from the "origin" +and store them under .git/refs/tags/. +------------ + + +Push into another repository.:: ++ +------------ +satellite$ git clone mothership:frotz/.git frotz <1> +satellite$ cd frotz +satellite$ cat .git/remotes/origin <2> +URL: mothership:frotz/.git +Pull: master:origin +satellite$ echo 'Push: master:satellite' >>.git/remotes/origin <3> +satellite$ edit/compile/test/commit +satellite$ git push origin <4> + +mothership$ cd frotz +mothership$ git checkout master +mothership$ git pull . satellite <5> + +<1> mothership machine has a frotz repository under your home +directory; clone from it to start a repository on the satellite +machine. +<2> clone creates this file by default. It arranges "git pull" +to fetch and store the master branch head of mothership machine +to local "origin" branch. +<3> arrange "git push" to push local "master" branch to +"satellite" branch of the mothership machine. +<4> push will stash our work away on "satellite" branch on the +mothership machine. You could use this as a back-up method. +<5> on mothership machine, merge the work done on the satellite +machine into the master branch. +------------ + +Branch off of a specific tag.:: ++ +------------ +$ git checkout -b private2.6.14 v2.6.14 <1> +$ edit/compile/test; git commit -a +$ git checkout master +$ git format-patch -k -m --stdout v2.6.14..private2.6.14 | + git am -3 -k <2> + +<1> create a private branch based on a well known (but somewhat behind) +tag. +<2> forward port all changes in private2.6.14 branch to master branch +without a formal "merging". +------------ + + +Integrator[[Integrator]] +------------------------ + +A fairly central person acting as the integrator in a group +project receives changes made by others, reviews and integrates +them and publishes the result for others to use, using these +commands in addition to the ones needed by participants. + + * gitlink:git-am[1] to apply patches e-mailed in from your + contributors. + + * gitlink:git-pull[1] to merge from your trusted lieutenants. + + * gitlink:git-format-patch[1] to prepare and send suggested + alternative to contributors. + + * gitlink:git-revert[1] to undo botched commits. + + * gitlink:git-push[1] to publish the bleeding edge. + + +Examples +~~~~~~~~ + +My typical GIT day.:: ++ +------------ +$ git status <1> +$ git show-branch <2> +$ mailx <3> +& s 2 3 4 5 ./+to-apply +& s 7 8 ./+hold-linus +& q +$ git checkout master +$ git am -3 -i -s -u ./+to-apply <4> +$ compile/test +$ git checkout -b hold/linus && git am -3 -i -s -u ./+hold-linus <5> +$ git checkout topic/one && git rebase master <6> +$ git checkout pu && git reset --hard master <7> +$ git pull . topic/one topic/two && git pull . hold/linus <8> +$ git checkout maint +$ git cherry-pick master~4 <9> +$ compile/test +$ git tag -s -m 'GIT 0.99.9x' v0.99.9x <10> +$ git fetch ko && git show-branch master maint 'tags/ko-*' <11> +$ git push ko <12> +$ git push ko v0.99.9x <13> + +<1> see what I was in the middle of doing, if any. +<2> see what topic branches I have and think about how ready +they are. +<3> read mails, save ones that are applicable, and save others +that are not quite ready. +<4> apply them, interactively, with my sign-offs. +<5> create topic branch as needed and apply, again with my +sign-offs. +<6> rebase internal topic branch that has not been merged to the +master, nor exposed as a part of a stable branch. +<7> restart "pu" every time from the master. +<8> and bundle topic branches still cooking. +<9> backport a critical fix. +<10> create a signed tag. +<11> make sure I did not accidentally rewind master beyond what I +already pushed out. "ko" shorthand points at the repository I have +at kernel.org, and looks like this: + $ cat .git/remotes/ko + URL: kernel.org:/pub/scm/git/git.git + Pull: master:refs/tags/ko-master + Pull: maint:refs/tags/ko-maint + Push: master + Push: +pu + Push: maint +In the output from "git show-branch", "master" should have +everything "ko-master" has. +<12> push out the bleeding edge. +<13> push the tag out, too. +------------ + + +Repository Administration[[Repository Administration]] +------------------------------------------------------ + +A repository administrator uses the following tools to set up +and maintain access to the repository by developers. + + * gitlink:git-daemon[1] to allow anonymous download from + repository. + + * gitlink:git-shell[1] can be used as a 'restricted login shell' + for shared central repository users. + +link:howto/update-hook-example.txt[update hook howto] has a good +example of managing a shared central repository. + + +Examples +~~~~~~~~ + +Run git-daemon to serve /pub/scm from inetd.:: ++ +------------ +$ grep git /etc/inet.conf +git stream tcp nowait nobody \ + /usr/bin/git-daemon git-daemon --inetd --syslog --export-all /pub/scm +------------ ++ +The actual configuration line should be on one line. + +Give push/pull only access to developers.:: ++ +------------ +$ grep git /etc/passwd <1> +alice:x:1000:1000::/home/alice:/usr/bin/git-shell +bob:x:1001:1001::/home/bob:/usr/bin/git-shell +cindy:x:1002:1002::/home/cindy:/usr/bin/git-shell +david:x:1003:1003::/home/david:/usr/bin/git-shell +$ grep git /etc/shells <2> +/usr/bin/git-shell + +<1> log-in shell is set to /usr/bin/git-shell, which does not +allow anything but "git push" and "git pull". The users should +get an ssh access to the machine. +<2> in many distributions /etc/shells needs to list what is used +as the login shell. +------------ + +CVS-style shared repository.:: ++ +------------ +$ grep git /etc/group <1> +git:x:9418:alice,bob,cindy,david +$ cd /home/devo.git +$ ls -l <2> + lrwxrwxrwx 1 david git 17 Dec 4 22:40 HEAD -> refs/heads/master + drwxrwsr-x 2 david git 4096 Dec 4 22:40 branches + -rw-rw-r-- 1 david git 84 Dec 4 22:40 config + -rw-rw-r-- 1 david git 58 Dec 4 22:40 description + drwxrwsr-x 2 david git 4096 Dec 4 22:40 hooks + -rw-rw-r-- 1 david git 37504 Dec 4 22:40 index + drwxrwsr-x 2 david git 4096 Dec 4 22:40 info + drwxrwsr-x 4 david git 4096 Dec 4 22:40 objects + drwxrwsr-x 4 david git 4096 Nov 7 14:58 refs + drwxrwsr-x 2 david git 4096 Dec 4 22:40 remotes +$ ls -l hooks/update <3> + -r-xr-xr-x 1 david git 3536 Dec 4 22:40 update +$ cat info/allowed-users <4> +refs/heads/master alice\|cindy +refs/heads/doc-update bob +refs/tags/v[0-9]* david + +<1> place the developers into the same git group. +<2> and make the shared repository writable by the group. +<3> use update-hook example by Carl from Documentation/howto/ +for branch policy control. +<4> alice and cindy can push into master, only bob can push into doc-update. +david is the release manager and is the only person who can +create and push version tags. +------------ + +HTTP server to support dumb protocol transfer.:: ++ +------------ +dev$ git update-server-info <1> +dev$ ftp user@isp.example.com <2> +ftp> cp -r .git /home/user/myproject.git + +<1> make sure your info/refs and objects/info/packs are up-to-date +<2> upload to public HTTP server hosted by your ISP. +------------ diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt new file mode 100644 index 0000000..13f34d3 --- /dev/null +++ b/Documentation/fetch-options.txt @@ -0,0 +1,41 @@ +-a, \--append:: + Append ref names and object names of fetched refs to the + existing contents of `.git/FETCH_HEAD`. Without this + option old data in `.git/FETCH_HEAD` will be overwritten. + +\--upload-pack <upload-pack>:: + When given, and the repository to fetch from is handled + by 'git-fetch-pack', '--exec=<upload-pack>' is passed to + the command to specify non-default path for the command + run on the other end. + +-f, \--force:: + When `git-fetch` is used with `<rbranch>:<lbranch>` + refspec, it refuses to update the local branch + `<lbranch>` unless the remote branch `<rbranch>` it + fetches is a descendant of `<lbranch>`. This option + overrides that check. + +\--no-tags:: + By default, `git-fetch` fetches tags that point at + objects that are downloaded from the remote repository + and stores them locally. This option disables this + automatic tag following. + +-t, \--tags:: + Most of the tags are fetched automatically as branch + heads are downloaded, but tags that do not point at + objects reachable from the branch heads that are being + tracked will not be fetched by this mechanism. This + flag lets all tags and their associated objects be + downloaded. + +-k, \--keep:: + Keep downloaded pack. + +-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. + diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt new file mode 100644 index 0000000..89e4614 --- /dev/null +++ b/Documentation/git-add.txt @@ -0,0 +1,75 @@ +git-add(1) +========== + +NAME +---- +git-add - Add files to the index file. + +SYNOPSIS +-------- +'git-add' [-n] [-v] <file>... + +DESCRIPTION +----------- +A simple wrapper for git-update-index to add files to the index, +for people used to do "cvs add". + + +OPTIONS +------- +<file>...:: + Files to add to the index. + +-n:: + Don't actually add the file(s), just show if they exist. + +-v:: + Be verbose. + + +DISCUSSION +---------- + +The list of <file> given to the command is fed to `git-ls-files` +command to list files that are not registered in the index and +are not ignored/excluded by `$GIT_DIR/info/exclude` file or +`.gitignore` file in each directory. This means two things: + +. You can put the name of a directory on the command line, and + the command will add all files in it and its subdirectories; + +. Giving the name of a file that is already in index does not + run `git-update-index` on that path. + + +EXAMPLES +-------- +git-add Documentation/\\*.txt:: + + Adds all `\*.txt` files that are not in the index under + `Documentation` directory and its subdirectories. ++ +Note that the asterisk `\*` is quoted from the shell in this +example; this lets the command to include the files from +subdirectories of `Documentation/` directory. + +git-add git-*.sh:: + + Adds all git-*.sh scripts that are not in the index. + Because this example lets shell expand the asterisk + (i.e. you are listing the files explicitly), it does not + add `subdir/git-foo.sh` to the index. + + +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-am.txt b/Documentation/git-am.txt new file mode 100644 index 0000000..02cabc9 --- /dev/null +++ b/Documentation/git-am.txt @@ -0,0 +1,97 @@ +git-am(1) +========= + +NAME +---- +git-am - Apply a series of patches in a mailbox + + +SYNOPSIS +-------- +[verse] +'git-am' [--signoff] [--dotest=<dir>] [--utf8] [--binary] [--3way] <mbox>... +'git-am' [--skip | --resolved] + +DESCRIPTION +----------- +Splits mail messages in a mailbox into commit log message, +authorship information and patches, and applies them to the +current branch. + +OPTIONS +------- +--signoff:: + Add `Signed-off-by:` line to the commit message, using + the committer identity of yourself. + +--dotest=<dir>:: + Instead of `.dotest` directory, use <dir> as a working + area to store extracted patches. + +--utf8, --keep:: + Pass `-u` and `-k` flags to `git-mailinfo` (see + gitlink:git-mailinfo[1]). + +--binary:: + Pass `--allow-binary-replacement` flag to `git-apply` + (see gitlink:git-apply[1]). + +--3way:: + When the patch does not apply cleanly, fall back on + 3-way merge, if the patch records the identity of blobs + it is supposed to apply to, and we have those blobs + locally. + +--skip:: + Skip the current patch. This is only meaningful when + restarting an aborted patch. + +--interactive:: + Run interactively, just like git-applymbox. + +--resolved:: + After a patch failure (e.g. attempting to apply + conflicting patch), the user has applied it by hand and + the index file stores the result of the application. + Make a commit using the authorship and commit log + extracted from the e-mail message and the current index + file, and continue. + +DISCUSSION +---------- + +When initially invoking it, you give it names of the mailboxes +to crunch. Upon seeing the first patch that does not apply, it +aborts in the middle, just like 'git-applymbox' does. You can +recover from this in one of two ways: + +. skip the current one by re-running the command with '--skip' + option. + +. hand resolve the conflict in the working directory, and update + the index file to bring it in a state that the patch should + have produced. Then run the command with '--resolved' option. + +The command refuses to process new mailboxes while `.dotest` +directory exists, so if you decide to start over from scratch, +run `rm -f .dotest` before running the command with mailbox +names. + + +SEE ALSO +-------- +gitlink:git-applymbox[1], gitlink:git-applypatch[1]. + + +Author +------ +Written by Junio C Hamano <junkio@cox.net> + +Documentation +-------------- +Documentation by Petr Baudis, 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 0000000..75076b6 --- /dev/null +++ b/Documentation/git-apply.txt @@ -0,0 +1,111 @@ +git-apply(1) +============ + +NAME +---- +git-apply - Apply patch on a git index file and a work tree + + +SYNOPSIS +-------- +[verse] +'git-apply' [--stat] [--numstat] [--summary] [--check] [--index] [--apply] + [--no-add] [--index-info] [--allow-binary-replacement] [-z] [-pNUM] + [<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. + +--stat:: + Instead of applying the patch, output diffstat for the + input. Turns off "apply". + +--numstat:: + Similar to \--stat, but shows number of added and + deleted lines in decimal notation and pathname without + abbreviation, to make it more machine friendly. 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. + +--index-info:: + Newer git-diff output has embedded 'index information' + for each blob to help identify the original version that + the patch applies to. When this flag is given, and if + the original version of the blob is available locally, + outputs information about them to the standard output. + +-z:: + When showing the index information, do not munge paths, + but use NUL terminated machine readable format. Without + this flag, the pathnames output will have TAB, LF, and + backslash characters replaced with `\t`, `\n`, and `\\`, + respectively. + +-p<n>:: + Remove <n> leading slashes from traditional diff paths. The + default is 1. + +--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. + +--no-add:: + When applying a patch, ignore additions made by the + patch. This can be used to extract common part between + two files by first running `diff` on them and applying + the result with this option, which would apply the + deletion part but not addition part. + +--allow-binary-replacement:: + When applying a patch, which is a git-enhanced patch + that was prepared to record the pre- and post-image object + name in full, and the path being patched exactly matches + the object the patch applies to (i.e. "index" line's + pre-image object name is what is in the working tree), + and the post-image object is available in the object + database, use the post-image object as the patch + result. This allows binary files to be patched in a + very limited way. + +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 0000000..f74c6a4 --- /dev/null +++ b/Documentation/git-applymbox.txt @@ -0,0 +1,92 @@ +git-applymbox(1) +================ + +NAME +---- +git-applymbox - Apply a series of patches in a mailbox + + +SYNOPSIS +-------- +'git-applymbox' [-u] [-k] [-q] [-m] ( -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 it. + +-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. + +-m:: + Patches are applied with `git-apply` command, and unless + it cleanly applies without fuzz, the processing fails. + With this flag, if a tree that the patch applies cleanly + is found in a repository, the patch is applied to the + tree and then a 3-way merge between the resulting tree + and the current tree. + +-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-am[1], 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 0000000..5b9037d --- /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 0000000..023d3ae --- /dev/null +++ b/Documentation/git-archimport.txt @@ -0,0 +1,106 @@ +git-archimport(1) +================= + +NAME +---- +git-archimport - Import an Arch repository into git + + +SYNOPSIS +-------- +[verse] +`git-archimport` [-h] [-v] [-o] [-a] [-f] [-T] [-D depth] [-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 supplied. 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. + +-f:: + Use the fast patchset import strategy. This can be significantly + faster for large trees, but cannot handle directory renames or + permissions changes. The default strategy is slow and safe. + +-o:: + Use this for compatibility with old-style branch names used by + earlier versions of git-archimport. Old-style branch names + were category--branch, whereas new-style branch names are + archive,category--branch--version. + +-D <depth>:: + Follow merge ancestry and attempt to import trees that have been + merged from. Specify a depth greater than 1 if patch logs have been + pruned. + +-a:: + Attempt to auto-register archives at http://mirrors.sourcecontrol.net + This is particularly useful with the -D option. + +-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 0000000..ac4b496 --- /dev/null +++ b/Documentation/git-bisect.txt @@ -0,0 +1,136 @@ +git-bisect(1) +============= + +NAME +---- +git-bisect - Find the change that introduced a bug + + +SYNOPSIS +-------- +'git bisect' <subcommand> <options> + +DESCRIPTION +----------- +The command takes various subcommands, and different options +depending on the subcommand: + + git bisect start [<paths>...] + git bisect bad <rev> + git bisect good <rev> + git bisect reset [<branch>] + git bisect visualize + git bisect replay <logfile> + git bisect log + +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 input 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. + +If in a middle of bisect session, you know what the bisect +suggested to try next is not a good one to test (e.g. the change +the commit introduces is known not to work in your environment +and you know it does not have anything to do with the bug you +are chasing), you may want to find a near-by commit and try that +instead. It goes something like this: + +------------ +$ git bisect good/bad # previous round was good/bad. +Bisecting: 337 revisions left to test after this +$ git bisect visualize # oops, that is uninteresting. +$ git reset --hard HEAD~3 # try 3 revs before what + # was suggested +------------ + +Then compile and test the one you chose to try. After that, +tell bisect what the result was as usual. + +You can further cut down the number of trials if you know what +part of the tree is involved in the problem you are tracking +down, by giving paths parameters when you say `bisect start`, +like this: + +------------ +$ git bisect start arch/i386 include/asm-i386 +------------ + + +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 0000000..b1bc827 --- /dev/null +++ b/Documentation/git-branch.txt @@ -0,0 +1,75 @@ +git-branch(1) +============= + +NAME +---- +git-branch - Create a new branch, or remove an old one. + +SYNOPSIS +-------- +'git-branch' [(-d | -D) <branchname>] | [[-f] <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 +------- +-d:: + Delete a branch. The branch must be fully merged. + +-D:: + Delete a branch irrespective of its index status. + +-f:: + Force a reset of <branchname> to <start-point> (or current head). + +<branchname>:: + The name of the branch to create or delete. + +<start-point>:: + Where to create the branch; defaults to HEAD. This + option has no meaning with -d and -D. + + +Examples +~~~~~~~~ + +Start development off of a know tag:: ++ +------------ +$ git clone git://git.kernel.org/pub/scm/.../linux-2.6 my2.6 +$ cd my2.6 +$ git branch my2.6.14 v2.6.14 <1> +$ git checkout my2.6.14 + +<1> These two steps are the same as "checkout -b my2.6.14 v2.6.14". +------------ + +Delete unneeded branch:: ++ +------------ +$ git clone git://git.kernel.org/.../git.git my.git +$ cd my.git +$ git branch -D todo <1> + +<1> delete todo branch even if the "master" branch does not have all +commits from todo branch. +------------ + +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 0000000..504eb1b --- /dev/null +++ b/Documentation/git-cat-file.txt @@ -0,0 +1,67 @@ +git-cat-file(1) +=============== + +NAME +---- +git-cat-file - Provide content or type information for repository objects + + +SYNOPSIS +-------- +'git-cat-file' [-t | -s | -e | <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>. + +-e:: + Suppress all output; instead exit with zero status if <object> + exists and is a valid object. + +<type>:: + Typically this matches the real type of <object> but asking + for a type that can trivially be 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. + +If '-e' is specified, no output. + +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-check-ref-format.txt b/Documentation/git-check-ref-format.txt new file mode 100644 index 0000000..f7f84c6 --- /dev/null +++ b/Documentation/git-check-ref-format.txt @@ -0,0 +1,52 @@ +git-check-ref-format(1) +======================= + +NAME +---- +git-check-ref-format - Make sure ref name is well formed. + +SYNOPSIS +-------- +'git-check-ref-format' <refname> + +DESCRIPTION +----------- +Checks if a given 'refname' is acceptable, and exits non-zero if +it is not. + +A reference is used in git to specify branches and tags. A +branch head is stored under `$GIT_DIR/refs/heads` directory, and +a tag is stored under `$GIT_DIR/refs/tags` directory. git +imposes the following rules on how refs are named: + +. It could be named hierarchically (i.e. separated with slash + `/`), but each of its component cannot begin with a dot `.`; + +. It cannot have two consecutive dots `..` anywhere; + +. It cannot have ASCII control character (i.e. bytes whose + values are lower than \040, or \177 `DEL`), space, tilde `~`, + caret `{caret}`, colon `:`, question-mark `?`, asterisk `*`, + or open bracket `[` anywhere; + +. It cannot end with a slash `/`. + +These rules makes it easy for shell script based tools to parse +refnames, pathname expansion by the shell when a refname is used +unquoted (by mistake), and also avoids ambiguities in certain +refname expressions (see gitlink:git-rev-parse[1]). Namely: + +. double-dot `..` are often used as in `ref1..ref2`, and in some + context this notation means `{caret}ref1 ref2` (i.e. not in + ref1 and in ref2). + +. tilde `~` and caret `{caret}` are used to introduce postfix + 'nth parent' and 'peel onion' operation. + +. colon `:` is used as in `srcref:dstref` to mean "use srcref\'s + value and store it in dstref" in fetch and push operations. + + +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 0000000..2a1e526 --- /dev/null +++ b/Documentation/git-checkout-index.txt @@ -0,0 +1,122 @@ +git-checkout-index(1) +===================== + +NAME +---- +git-checkout-index - Copy files from the index to the working directory + + +SYNOPSIS +-------- +[verse] +'git-checkout-index' [-u] [-q] [-a] [-f] [-n] [--prefix=<string>] + [--stage=<number>] [--] <file>... + +DESCRIPTION +----------- +Will copy all files listed from the index to the working directory +(not overwriting existing files). + +OPTIONS +------- +-u|--index:: + update stat information for the checked out entries in + the index file. + +-q|--quiet:: + be quiet if files exist or are not in the index + +-f|--force:: + forces overwrite of existing files + +-a|--all:: + checks out all files in the index. Cannot be used + together with explicit filenames. + +-n|--no-create:: + Don't checkout new files, only refresh files already checked + out. + +--prefix=<string>:: + When creating files, prepend <string> (usually a directory + including a trailing /) + +--stage=<number>:: + Instead of checking out unmerged entries, copy out the + files from named stage. <number> must be between 1 and 3. + +--:: + Do not interpret any more arguments as options. + +The order of the flags used to matter, but not anymore. + +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" behavior is that from scripts you are +supposed to be able to do: + +---------------- +$ 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 index, which was not the point. + +The `--` is just a good idea when you know the rest will be filenames; +it will prevent problems with a filename of, for example, `-a`. +Using `--` is probably a good policy in scripts. + + +EXAMPLES +-------- +To update and refresh only the files already checked out:: ++ +---------------- +$ git-checkout-index -n -f -a && git-update-index --ignore-missing --refresh +---------------- + +Using `git-checkout-index` to "export an entire tree":: + 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: ++ +---------------- +$ git-checkout-index --prefix=git-export-dir/ -a +---------------- ++ +`git-checkout-index` will "export" the index into the specified +directory. ++ +The final "/" is important. The exported name is literally just +prefixed with the specified string. Contrast this with the +following example. + +Export files with a prefix:: ++ +---------------- +$ git-checkout-index --prefix=.merged- Makefile +---------------- ++ +This will 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 0000000..df9a618 --- /dev/null +++ b/Documentation/git-checkout.txt @@ -0,0 +1,145 @@ +git-checkout(1) +=============== + +NAME +---- +git-checkout - Checkout and switch to a branch. + +SYNOPSIS +-------- +'git-checkout' [-f] [-b <new_branch>] [-m] [<branch>] [<paths>...] + +DESCRIPTION +----------- + +When <paths> are not given, this command switches branches, by +updating the index and working tree to reflect the specified +branch, <branch>, and updating HEAD to be <branch> or, if +specified, <new_branch>. + +When <paths> are given, this command does *not* switch +branches. It updates the named paths in the working tree from +the index file (i.e. it runs `git-checkout-index -f -u`). In +this case, `-f` and `-b` options are meaningless and giving +either of them results in an error. <branch> argument can be +used to specify a specific tree-ish to update the index for the +given paths before updating the working tree. + + +OPTIONS +------- +-f:: + Force an re-read of everything. + +-b:: + Create a new branch and start it at <branch>. + +-m:: + If you have local modifications to a file that is + different between the current branch and the branch you + are switching to, the command refuses to switch + branches, to preserve your modifications in context. + With this option, a three-way merge between the current + branch, your working tree contents, and the new branch + is done, and you will be on the new branch. ++ +When a merge conflict happens, the index entries for conflicting +paths are left unmerged, and you need to resolve the conflicts +and mark the resolved paths with `git update-index`. + +<new_branch>:: + Name for the new branch. + +<branch>:: + Branch to checkout; may be any object ID that resolves to a + commit. Defaults to HEAD. + + +EXAMPLES +-------- + +. The following sequence checks out the `master` branch, reverts +the `Makefile` to two revisions back, deletes hello.c by +mistake, and gets it back from the index. ++ +------------ +$ git checkout master <1> +$ git checkout master~2 Makefile <2> +$ rm -f hello.c +$ git checkout hello.c <3> + +<1> switch branch +<2> take out a file out of other commit +<3> or "git checkout -- hello.c", as in the next example. +------------ ++ +If you have an unfortunate branch that is named `hello.c`, the +last step above would be confused as an instruction to switch to +that branch. You should instead write: ++ +------------ +$ git checkout -- hello.c +------------ + +. After working in a wrong branch, switching to the correct +branch you would want to is done with: ++ +------------ +$ git checkout mytopic +------------ ++ +However, your "wrong" branch and correct "mytopic" branch may +differ in files that you have locally modified, in which case, +the above checkout would fail like this: ++ +------------ +$ git checkout mytopic +fatal: Entry 'frotz' not uptodate. Cannot merge. +------------ ++ +You can give the `-m` flag to the command, which would try a +three-way merge: ++ +------------ +$ git checkout -m mytopic +Auto-merging frotz +------------ ++ +After this three-way merge, the local modifications are _not_ +registered in your index file, so `git diff` would show you what +changes you made since the tip of the new branch. + +. When a merge conflict happens during switching branches with +the `-m` option, you would see something like this: ++ +------------ +$ git checkout -m mytopic +Auto-merging frotz +merge: warning: conflicts during merge +ERROR: Merge conflict in frotz +fatal: merge program failed +------------ ++ +At this point, `git diff` shows the changes cleanly merged as in +the previous example, as well as the changes in the conflicted +files. Edit and resolve the conflict and mark it resolved with +`git update-index` as usual: ++ +------------ +$ edit frotz +$ git update-index frotz +------------ + + +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 0000000..4f323fa --- /dev/null +++ b/Documentation/git-cherry-pick.txt @@ -0,0 +1,60 @@ +git-cherry-pick(1) +================== + +NAME +---- +git-cherry-pick - Apply the change introduced by an existing commit. + +SYNOPSIS +-------- +'git-cherry-pick' [--edit] [-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. + +-e|--edit:: + With this option, `git-cherry-pick` will let you edit the commit + message prior committing. + +-r|--replay:: + Usually 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. + +-n|--no-commit:: + 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 0000000..af87966 --- /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 0000000..39906fc --- /dev/null +++ b/Documentation/git-clone-pack.txt @@ -0,0 +1,64 @@ +git-clone-pack(1) +================= + +NAME +---- +git-clone-pack - Clones a repository by receiving packed objects. + + +SYNOPSIS +-------- +'git-clone-pack' [--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 stores the sent pack in the local +repository. + +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. + Installations of sshd ignore 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. ++ +Usually all the refs from existing repository are stored +under the same name in the new repository. Giving explicit +<head> arguments instead writes the object names and refs to +the standard output, just like get-fetch-pack does. + +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 0000000..684e4bd --- /dev/null +++ b/Documentation/git-clone.txt @@ -0,0 +1,143 @@ +git-clone(1) +============ + +NAME +---- +git-clone - Clones a repository. + + +SYNOPSIS +-------- +[verse] +'git-clone' [-l [-s]] [-q] [-n] [--bare] [-o <name>] [-u <upload-pack>] + <repository> [<directory>] + +DESCRIPTION +----------- +Clones a repository into a newly created directory. All remote +branch heads are copied under `$GIT_DIR/refs/heads/`, except +that the remote `master` is also copied to `origin` branch. + +In addition, `$GIT_DIR/remotes/origin` file is set up to have +this line: + + Pull: master:origin + +This is to help the typical workflow of working off of the +remote `master` branch. Every time `git pull` without argument +is run, the progress on the remote `master` branch is tracked by +copying it into the local `origin` branch, and merged into the +branch you are currently working on. Remote branches other than +`master` are also added there to be tracked. + + +OPTIONS +------- +--local:: +-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. + +--shared:: +-s:: + When the repository to clone is on the local machine, + instead of using hard links, automatically setup + .git/objects/info/alternatives to share the objects + with the source repository. The resulting repository + starts out without any object of its own. + +--quiet:: +-q:: + Operate quietly. This flag is passed to "rsync" and + "git-clone-pack" commands when given. + +-n:: + No checkout of HEAD is performed after the clone is complete. + +--bare:: + Make a 'bare' GIT repository. That is, instead of + creating `<directory>` and placing the administrative + files in `<directory>/.git`, make the `<directory>` + itself the `$GIT_DIR`. This implies `-n` option. When + this option is used, neither the `origin` branch nor the + default `remotes/origin` file is created. + +-o <name>:: + Instead of using the branch name 'origin' to keep track + of the upstream repository, use <name> instead. Note + that the shorthand name stored in `remotes/origin` is + not affected, but the local branch name to pull the + remote `master` branch into is. + +--upload-pack <upload-pack>:: +-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 any URL git-fetch supports. + +<directory>:: + The name of a new directory to clone into. The "humanish" + part of the source repository is used if no directory is + explicitly given ("repo" for "/path/to/repo.git" and "foo" + for "host.xz:foo/.git"). Cloning into an existing directory + is not allowed. + +Examples +~~~~~~~~ + +Clone from upstream:: ++ +------------ +$ git clone git://git.kernel.org/pub/scm/.../linux-2.6 my2.6 +$ cd my2.6 +$ make +------------ + + +Make a local clone that borrows from the current directory, without checking things out:: ++ +------------ +$ git clone -l -s -n . ../copy +$ cd copy +$ git show-branch +------------ + + +Create a bare repository to publish your changes to the public:: ++ +------------ +$ git clone --bare -l /home/proj/.git /pub/scm/proj.git +------------ + + +Create a repository on the kernel.org machine that borrows from Linus:: ++ +------------ +$ git clone --bare -l -s /pub/scm/.../torvalds/linux-2.6.git \ + /pub/scm/.../me/subsys-2.6.git +------------ + + +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-commit-tree.txt b/Documentation/git-commit-tree.txt new file mode 100644 index 0000000..41d1a1c --- /dev/null +++ b/Documentation/git-commit-tree.txt @@ -0,0 +1,100 @@ +git-commit-tree(1) +================== + +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 that is pointed at by +`.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 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 by +either `.git/config` file, or 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) + +In `.git/config` file, the following items are used for GIT_AUTHOR_NAME and +GIT_AUTHOR_EMAIL: + + [user] + name = "Your Name" + email = "your@email.address.xz" + +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 0000000..53b64fa --- /dev/null +++ b/Documentation/git-commit.txt @@ -0,0 +1,138 @@ +git-commit(1) +============= + +NAME +---- +git-commit - Record your changes + +SYNOPSIS +-------- +[verse] +'git-commit' [-a] [-i] [-s] [-v] [(-c | -C) <commit> | -F <file> | -m <msg>] + [-e] [--author <author>] [--] <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|--all:: + Update all paths in the index file. This flag notices + files that have been modified and deleted, but new files + you have not told git about are not affected. + +-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. + +--author <author>:: + Override the author name used in the commit. Use + `A U Thor <author@example.com>` format. + +-m <msg>:: + Use the given <msg> as the commit message. + +-s|--signoff:: + Add Signed-off-by line at the end of the commit message. + +-v|--verify:: + 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. This is the default. + +-n|--no-verify:: + The opposite of `--verify`. + +-e|--edit:: + 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. + +-i|--include:: + Instead of committing only the files specified on the + command line, update them in the index file and then + commit the whole index. This is the traditional + behaviour. + +--:: + Do not interpret any more arguments as options. + +<file>...:: + Commit only the files specified on the command line. + This format cannot be used during a merge, nor when the + index and the latest commit does not match on the + specified paths to avoid confusion. + +If you make a commit and then found a mistake immediately after +that, you can recover from it with gitlink:git-reset[1]. + + +Discussion +---------- + +`git commit` without _any_ parameter commits the tree structure +recorded by the current index file. This is a whole-tree commit +even the command is invoked from a subdirectory. + +`git commit --include paths...` is equivalent to + + git update-index --remove paths... + git commit + +That is, update the specified paths to the index and then commit +the whole tree. + +`git commit paths...` largely bypasses the index file and +commits only the changes made to the specified paths. It has +however several safety valves to prevent confusion. + +. It refuses to run during a merge (i.e. when + `$GIT_DIR/MERGE_HEAD` exists), and reminds trained git users + that the traditional semantics now needs -i flag. + +. It refuses to run if named `paths...` are different in HEAD + and the index (ditto about reminding). Added paths are OK. + This is because an earlier `git diff` (not `git diff HEAD`) + would have shown the differences since the last `git + update-index paths...` to the user, and an inexperienced user + may mistakenly think that the changes between the index and + the HEAD (i.e. earlier changes made before the last `git + update-index paths...` was done) are not being committed. + +. It reads HEAD commit into a temporary index file, updates the + specified `paths...` and makes a commit. At the same time, + the real index file is also updated with the same `paths...`. + +`git commit --all` updates the index file with _all_ changes to +the working tree, and makes a whole-tree commit, regardless of +which subdirectory the command is invoked in. + + +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 0000000..b1220c0 --- /dev/null +++ b/Documentation/git-convert-objects.txt @@ -0,0 +1,29 @@ +git-convert-objects(1) +====================== + +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 0000000..36888d9 --- /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-cvsexportcommit.txt b/Documentation/git-cvsexportcommit.txt new file mode 100644 index 0000000..d30435a --- /dev/null +++ b/Documentation/git-cvsexportcommit.txt @@ -0,0 +1,76 @@ +git-cvsexportcommit(1) +====================== + +NAME +---- +git-cvsexportcommit - Export a commit to a CVS checkout + + +SYNOPSIS +-------- +'git-cvsexportcommmit' [-h] [-v] [-c] [-p] [PARENTCOMMIT] COMMITID + + +DESCRIPTION +----------- +Exports a commit from GIT to a CVS checkout, making it easier +to merge patches from a git repository into a CVS repository. + +Execute it from the root of the CVS working copy. GIT_DIR must be defined. +See examples below. + +It does its best to do the safe thing, it will check that the files are +unchanged and up to date in the CVS checkout, and it will not autocommit +by default. + +Supports file additions, removals, and commits that affect binary files. + +If the commit is a merge commit, you must tell git-cvsapplycommit what parent +should the changeset be done against. + +OPTIONS +------- + +-c:: + Commit automatically if the patch applied cleanly. It will not + commit if any hunks fail to apply or there were other problems. + +-p:: + Be pedantic (paranoid) when applying patches. Invokes patch with + --fuzz=0 + +-v:: + Verbose. + +EXAMPLES +-------- + +Merge one patch into CVS:: ++ +------------ +$ export GIT_DIR=~/project/.git +$ cd ~/project_cvs_checkout +$ git-cvsexportcommit -v <commit-sha1> +$ cvs commit -F .mgs <files> +------------ + +Merge pending patches into CVS automatically -- only if you really know what you are doing :: ++ +------------ +$ export GIT_DIR=~/project/.git +$ cd ~/project_cvs_checkout +$ git-cherry cvshead myhead | sed -n 's/^+ //p' | xargs -l1 git-cvsexportcommit -c -p -v +------------ + +Author +------ +Written by Martin Langhoff <martin@catalyst.net.nz> + +Documentation +-------------- +Documentation by Martin Langhoff <martin@catalyst.net.nz> + +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 0000000..dfe86ce --- /dev/null +++ b/Documentation/git-cvsimport.txt @@ -0,0 +1,132 @@ +git-cvsimport(1) +================ + +NAME +---- +git-cvsimport - Import a CVS repository into git + + +SYNOPSIS +-------- +[verse] +'git-cvsimport' [-o <branch-for-HEAD>] [-h] [-v] [-d <CVSROOT>] [-s <subst>] + [-p <options-for-cvsps>] [-C <git_repository>] [-i] [-P <file>] + [-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 index 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. + +-P <cvsps-output-file>:: + Instead of calling cvsps, read the provided cvsps output file. Useful + for debugging or when cvsps is being handled outside cvsimport. + +-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> + +-A <author-conv-file>:: + CVS by default uses the unix username when writing its + commit logs. Using this option and an author-conv-file + in this format + + exon=Andreas Ericsson <ae@op5.se> + spawn=Simon Pawn <spawn@frog-pond.org> + + git-cvsimport will make it appear as those authors had + their GIT_AUTHOR_NAME and GIT_AUTHOR_EMAIL set properly + all along. + + For convenience, this data is saved to $GIT_DIR/cvs-authors + each time the -A option is provided and read from that same + file each time git-cvsimport is run. + + It is not recommended to use this feature if you intend to + export changes back to CVS again later with + git-link[1]::git-cvsexportcommit. + +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 0000000..2cc6075 --- /dev/null +++ b/Documentation/git-daemon.txt @@ -0,0 +1,102 @@ +git-daemon(1) +============= + +NAME +---- +git-daemon - A really simple server for git repositories. + +SYNOPSIS +-------- +[verse] +'git-daemon' [--verbose] [--syslog] [--inetd | --port=n] [--export-all] + [--timeout=n] [--init-timeout=n] [--strict-paths] + [--base-path=path] [--user-path | --user-path=path] + [directory...] + +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 (unless the '--export-all' parameter is specified). If you +pass some directory paths as 'git-daemon' arguments, you can further restrict +the offers to a whitelist comprising of those. + +This is ideally suited for read-only updates, ie pulling from git repositories. + +OPTIONS +------- +--strict-paths:: + Match paths exactly (i.e. don't allow "/foo/repo" when the real path is + "/foo/repo.git" or "/foo/repo/.git") and don't do user-relative paths. + git-daemon will refuse to start when this option is enabled and no + whitelist is specified. + +--base-path:: + Remap all the path requests as relative to the given path. + This is sort of "GIT root" - if you run git-daemon with + '--base-path=/srv/git' on example.com, then if you later try to pull + 'git://example.com/hello.git', `git-daemon` will interpret the path + as '/srv/git/hello.git'. + +--export-all:: + Allow pulling from all directories that look like GIT repositories + (have the 'objects' and 'refs' subdirectories), even if they + do not have the 'git-daemon-export-ok' file. + +--inetd:: + Have the server run as an inetd service. Implies --syslog. + +--port:: + Listen on an alternative port. + +--init-timeout:: + Timeout between the moment the connection is established and the + client request is received (typically a rather low value, since + that should be basically immediate). + +--timeout:: + Timeout for specific client sub-requests. This includes the time + it takes for the server to process the sub-request and time spent + waiting for next client's request. + +--syslog:: + Log to syslog instead of stderr. Note that this option does not imply + --verbose, thus by default only error conditions will be logged. + +--user-path, --user-path=path:: + Allow ~user notation to be used in requests. When + specified with no parameter, requests to + git://host/~alice/foo is taken as a request to access + 'foo' repository in the home directory of user `alice`. + If `--user-path=path` is specified, the same request is + taken as a request to access `path/foo` repository in + the home directory of user `alice`. + +--verbose:: + Log details about the incoming connections and requested files. + +<directory>:: + A directory to add to the whitelist of allowed directories. Unless + --strict-paths is specified this will also include subdirectories + of each named directory. + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org>, YOSHIFUJI Hideaki +<yoshfuji@linux-ipv6.org> and the git-list <git@vger.kernel.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-describe.txt b/Documentation/git-describe.txt new file mode 100644 index 0000000..0efe82a --- /dev/null +++ b/Documentation/git-describe.txt @@ -0,0 +1,79 @@ +git-describe(1) +=============== + +NAME +---- +git-describe - Show the most recent tag that is reachable from a commit. + + +SYNOPSIS +-------- +'git-describe' [--all] [--tags] [--abbrev=<n>] <committish>... + +DESCRIPTION +----------- +The command finds the most recent tag that is reachable from a +commit, and if the commit itself is pointed at by the tag, shows +the tag. Otherwise, it suffixes the tag name with abbreviated +object name of the commit. + + +OPTIONS +------- +<committish>:: + The object name of the comittish. + +--all:: + Instead of using only the annotated tags, use any ref + found in `.git/refs/`. + +--tags:: + Instead of using only the annotated tags, use any tag + found in `.git/refs/tags`. + +--abbrev=<n>:: + Instead of using the default 8 hexadecimal digits as the + abbreviated object name, use <n> digits. + + +EXAMPLES +-------- + +With something like git.git current tree, I get: + + [torvalds@g5 git]$ git-describe parent + v1.0.4-g2414721b + +i.e. the current head of my "parent" branch is based on v1.0.4, +but since it has a few commits on top of that, it has added the +git hash of the thing to the end: "-g" + 8-char shorthand for +the commit `2414721b194453f058079d897d13c4e377f92dc6`. + +Doing a "git-describe" on a tag-name will just show the tag name: + + [torvalds@g5 git]$ git-describe v1.0.4 + v1.0.4 + +With --all, the command can use branch heads as references, so +the output shows the reference path as well: + + [torvalds@g5 git]$ git describe --all --abbrev=4 v1.0.5^2 + tags/v1.0.0-g975b + + [torvalds@g5 git]$ git describe --all HEAD^ + heads/lt/describe-g975b + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org>, but somewhat +butchered 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-diff-files.txt b/Documentation/git-diff-files.txt new file mode 100644 index 0000000..481b8b3 --- /dev/null +++ b/Documentation/git-diff-files.txt @@ -0,0 +1,58 @@ +git-diff-files(1) +================= + +NAME +---- +git-diff-files - Compares files in the working tree and the index + + +SYNOPSIS +-------- +'git-diff-files' [-q] [-0|-1|-2|-3|-c|--cc] [<common diff options>] [<path>...] + +DESCRIPTION +----------- +Compares the files in the working tree and the index. When paths +are specified, compares only those named paths. Otherwise all +entries in the index are compared. The output format is the +same as "git-diff-index" and "git-diff-tree". + +OPTIONS +------- +include::diff-options.txt[] + +-1 -2 -3 or --base --ours --theirs, and -0:: + Diff against the "base" version, "our branch" or "their + branch" respectively. With these options, diffs for + merged entries are not shown. ++ +The default is to diff against our branch (-2) and the +cleanly resolved paths. The option -0 can be given to +omit diff output for unmerged entries and just show "Unmerged". + +-c,--cc:: + This compares stage 2 (our branch), stage 3 (their + branch) and the working tree file and outputs a combined + diff, similar to the way 'diff-tree' shows a merge + commit with these flags. + +-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 0000000..5d2096a --- /dev/null +++ b/Documentation/git-diff-index.txt @@ -0,0 +1,133 @@ +git-diff-index(1) +================= + +NAME +---- +git-diff-index - Compares content and mode of blobs between the index 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 index 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 index 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 index + 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 index and are ready to commit. You want to see exactly +*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 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 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 index, 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 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-update-index" it to make the index be in sync. + +NOTE: 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 0000000..28c60fc --- /dev/null +++ b/Documentation/git-diff-stages.txt @@ -0,0 +1,40 @@ +git-diff-stages(1) +================== + +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 0000000..674ee61 --- /dev/null +++ b/Documentation/git-diff-tree.txt @@ -0,0 +1,158 @@ +git-diff-tree(1) +================ + +NAME +---- +git-diff-tree - Compares the content and mode of blobs found via two tree objects + + +SYNOPSIS +-------- +[verse] +'git-diff-tree' [--stdin] [-m] [-s] [-v] [--no-commit-id] [--pretty] + [-t] [-r] [-c | --cc] [--root] [<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. + +-r:: + recurse into sub-trees + +-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 suppressed. 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. + +--no-commit-id:: + git-diff-tree outputs a line with the commit ID when + applicable. This flag suppressed the commit ID output. + +-c,--cc:: + These flags change the way a merge commit is displayed + (which means it is useful only when the command is given + one <tree-ish>, or '--stdin'). It shows the differences + from each of the parents to the merge result + simultaneously, instead of showing pairwise diff between + a parent and the result one at a time, which '-m' option + output does. '--cc' further compresses the output by + omiting hunks that show differences from only one + parent, or show the same change from all but one parent + for an Octopus merge. When this optimization makes all + hunks disappear, the commit itself and the commit log + message is not shown, just like any other "empty diff" cases. + + +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 0000000..ca41634 --- /dev/null +++ b/Documentation/git-diff.txt @@ -0,0 +1,116 @@ +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. + +* When no <ent> is given, the working tree and the index + file is compared, using `git-diff-files`. + +* When one <ent> is given, the working tree and the named + tree is compared, using `git-diff-index`. The option + `--cached` can be given to compare the index file and + the named tree. + +* When two <ent>s are given, these two trees are compared + using `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. + + +EXAMPLES +-------- + +Various ways to check your working tree:: ++ +------------ +$ git diff <1> +$ git diff --cached <2> +$ git diff HEAD <3> + +<1> changes in the working tree since your last git-update-index. +<2> changes between the index and your last commit; what you +would be committing if you run "git commit" without "-a" option. +<3> changes in the working tree since your last commit; what you +would be committing if you run "git commit -a" +------------ + +Comparing with arbitrary commits:: ++ +------------ +$ git diff test <1> +$ git diff HEAD -- ./test <2> +$ git diff HEAD^ HEAD <3> + +<1> instead of using the tip of the current branch, compare with the +tip of "test" branch. +<2> instead of comparing with the tip of "test" branch, compare with +the tip of the current branch, but limit the comparison to the +file "test". +<3> compare the version before the last commit and the last commit. +------------ + + +Limiting the diff output:: ++ +------------ +$ git diff --diff-filter=MRC <1> +$ git diff --name-status -r <2> +$ git diff arch/i386 include/asm-i386 <3> + +<1> show only modification, rename and copy, but not addition +nor deletion. +<2> show only names and the nature of change, but not actual +diff output. --name-status disables usual patch generation +which in turn also disables recursive behaviour, so without -r +you would only see the directory name if there is a change in a +file in a subdirectory. +<3> limit diff output to named subtrees. +------------ + +Munging the diff output:: ++ +------------ +$ git diff --find-copies-harder -B -C <1> +$ git diff -R <2> + +<1> spend extra cycles to find renames, copies and complete +rewrites (very expensive). +<2> output diff in reverse. +------------ + + +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 0000000..b507e9b --- /dev/null +++ b/Documentation/git-fetch-pack.txt @@ -0,0 +1,73 @@ +git-fetch-pack(1) +================= + +NAME +---- +git-fetch-pack - Receive missing objects from another repository. + + +SYNOPSIS +-------- +git-fetch-pack [-q] [-k] [--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. + +-k:: + Do not invoke 'git-unpack-objects' on received data, but + create a single packfile out of it instead, and store it + in the object database. + +--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 0000000..a67dc34 --- /dev/null +++ b/Documentation/git-fetch.txt @@ -0,0 +1,48 @@ +git-fetch(1) +============ + +NAME +---- +git-fetch - Download objects and a head from another repository. + + +SYNOPSIS +-------- +'git-fetch' <options> <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/FETCH_HEAD`. This information is left for a later merge +operation done by "git merge". + + +OPTIONS +------- +include::fetch-options.txt[] + +include::pull-fetch-param.txt[] + +include::urls.txt[] + +SEE ALSO +-------- +gitlink:git-pull[1] + + +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-fmt-merge-msg.txt b/Documentation/git-fmt-merge-msg.txt new file mode 100644 index 0000000..a70eb39 --- /dev/null +++ b/Documentation/git-fmt-merge-msg.txt @@ -0,0 +1,39 @@ +git-fmt-merge-msg(1) +==================== + +NAME +---- +git-fmt-merge-msg - Produce a merge commit message + + +SYNOPSIS +-------- +'git-fmt-merge-msg' <$GIT_DIR/FETCH_HEAD + +DESCRIPTION +----------- +Takes the list of merged objects on stdin and produces a suitable +commit message to be used for the merge commit, usually to be +passed as the '<merge-message>' argument of `git-merge`. + +This script is intended mostly for internal use by scripts +automatically invoking `git-merge`. + + +SEE ALSO +-------- +gitlink:git-merge[1] + + +Author +------ +Written by Junio C Hamano <junkio@cox.net> + +Documentation +-------------- +Documentation by Petr Baudis, 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 0000000..47705de --- /dev/null +++ b/Documentation/git-format-patch.txt @@ -0,0 +1,115 @@ +git-format-patch(1) +=================== + +NAME +---- +git-format-patch - Prepare patches for e-mail submission. + + +SYNOPSIS +-------- +[verse] +'git-format-patch' [-n | -k] [-o <dir> | --stdout] [-s] [-c] [--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|--output-directory <dir>:: + Use <dir> to store the resulting files, instead of the + current working directory. + +-n|--numbered:: + Name output in '[PATCH n/m]' format. + +-k|--keep-subject:: + Do not strip/add '[PATCH]' from the first line of the + commit log message. + +-a|--author, -d|--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. + +-s|--signoff:: + Add `Signed-off-by:` line to the commit message, using + the committer identity of yourself. + +-c|--check:: + Display suspicious lines in the patch. 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. + +-m|--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. + +--stdout:: + This flag generates the mbox formatted output to the + standard output, instead of saving them into a file per + patch and implies --mbox. + + +EXAMPLES +-------- + +git-format-patch -k --stdout R1..R2 | git-am -3 -k:: + Extract commits between revisions R1 and R2, and apply + them on top of the current branch using `git-am` to + cherry-pick them. + +git-format-patch origin:: + Extract commits the current branch accumulated since it + pulled from origin the last time in a patch form for + e-mail submission. + +git-format-patch -M -B origin:: + The same as the previous one, except detect and handle + renames and complete rewrites intelligently to produce + renaming patch. A renaming patch reduces the amount of + text output, and generally makes it easier to review + it. Note that the "patch" program does not understand + renaming patch well, so use it only when you know the + recipient uses git to apply your patch. + + +See Also +-------- +gitlink:git-am[1], gitlink:git-send-email[1] + + +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 0000000..387b435 --- /dev/null +++ b/Documentation/git-fsck-objects.txt @@ -0,0 +1,146 @@ +git-fsck-objects(1) +=================== + +NAME +---- +git-fsck-objects - Verifies the connectivity and validity of the objects in the database + + +SYNOPSIS +-------- +[verse] +'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 index 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 HEAD $(cat .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 index + +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 0000000..30b1fbf --- /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 0000000..bf4b592 --- /dev/null +++ b/Documentation/git-grep.txt @@ -0,0 +1,56 @@ +git-grep(1) +=========== + +NAME +---- +git-grep - print lines matching a pattern + + +SYNOPSIS +-------- +'git-grep' [<option>...] [-e] <pattern> [--] [<path>...] + +DESCRIPTION +----------- +Searches list of files `git-ls-files` produces for lines +containing a match to the given pattern. + + +OPTIONS +------- +`--`:: + Signals the end of options; the rest of the parameters + are <path> limiters. + +<option>...:: + Either an option to pass to `grep` or `git-ls-files`. + + The following are the specific `git-ls-files` options + that may be given: `-o`, `--cached`, `--deleted`, `--others`, + `--killed`, `--ignored`, `--modified`, `--exclude=*`, + `--exclude-from=*`, and `--exclude-per-directory=*`. + + All other options will be passed to `grep`. + +<pattern>:: + The pattern to look for. The first non option is taken + as the pattern; if your pattern begins with a dash, use + `-e <pattern>`. + +<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 0000000..0924931 --- /dev/null +++ b/Documentation/git-hash-object.txt @@ -0,0 +1,46 @@ +git-hash-object(1) +================== + +NAME +---- +git-hash-object - Computes object ID and optionally creates a blob from a file. + + +SYNOPSIS +-------- +'git-hash-object' [-t <type>] [-w] [--stdin] [--] <file>... + +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 index +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. + +--stdin:: + Read the object from standard input instead of from a file. + +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 0000000..bc1a132 --- /dev/null +++ b/Documentation/git-http-fetch.txt @@ -0,0 +1,47 @@ +git-http-fetch(1) +================= + +NAME +---- +git-http-fetch - downloads a remote git repository via HTTP + + +SYNOPSIS +-------- +'git-http-fetch' [-c] [-t] [-a] [-d] [-v] [-w filename] [--recover] <commit> <url> + +DESCRIPTION +----------- +Downloads a remote git repository via HTTP. + +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 <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-http-push.txt b/Documentation/git-http-push.txt new file mode 100644 index 0000000..c7066d6 --- /dev/null +++ b/Documentation/git-http-push.txt @@ -0,0 +1,89 @@ +git-http-push(1) +================ + +NAME +---- +git-http-push - Push missing objects using HTTP/DAV. + + +SYNOPSIS +-------- +'git-http-push' [--complete] [--force] [--verbose] <url> <ref> [<ref>...] + +DESCRIPTION +----------- +Sends missing objects to remote repository, and updates the +remote branch. + + +OPTIONS +------- +--complete:: + Do not assume that the remote repository is complete in its + current state, and verify all objects in the entire local + ref's history exist in the remote repository. + +--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. + +--verbose:: + Report the list of objects being walked locally and the + list of objects successfully sent to the remote repository. + +<ref>...: + The remote refs to update. + + +Specifying the Refs +------------------- + +A '<ref>' specification can be either a single pattern, or a pair +of such patterns 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. + + - 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 Nick Hengeveld <nickh@reactrix.com> + +Documentation +-------------- +Documentation by Nick Hengeveld + +GIT +--- +Part of the gitlink:git[7] suite diff --git a/Documentation/git-index-pack.txt b/Documentation/git-index-pack.txt new file mode 100644 index 0000000..71ce557 --- /dev/null +++ b/Documentation/git-index-pack.txt @@ -0,0 +1,44 @@ +git-index-pack(1) +================= + +NAME +---- +git-index-pack - Build pack index file for an existing packed archive + + +SYNOPSIS +-------- +'git-index-pack' [-o <index-file>] <pack-file> + + +DESCRIPTION +----------- +Reads a packed archive (.pack) from the specified file, and +builds a pack index file (.idx) for it. The packed archive +together with the pack index can then be placed in the +objects/pack/ directory of a git repository. + + +OPTIONS +------- +-o <index-file>:: + Write the generated pack index into the specified + file. Without this option the name of pack index + file is constructed from the name of packed archive + file by replacing .pack with .idx (and the program + fails if the name of packed archive does not end + with .pack). + + +Author +------ +Written by Sergey Vlasov <vsu@altlinux.ru> + +Documentation +------------- +Documentation by Sergey Vlasov + +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 0000000..ea4d849 --- /dev/null +++ b/Documentation/git-init-db.txt @@ -0,0 +1,74 @@ +git-init-db(1) +============== + +NAME +---- +git-init-db - Creates an empty git repository + + +SYNOPSIS +-------- +'git-init-db' [--template=<template_directory>] [--shared] + + +OPTIONS +------- +--template=<template_directory>:: + Provide the directory in from which templates will be used. + +--shared:: + Specify that the git repository is to be shared amongst several users. + + +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. + +A shared repository allows users belonging to the same group to push into that +repository. When specifying `--shared` the config variable "core.sharedRepository" +is set to 'true' so that directories under `$GIT_DIR` are made group writable +(and g+sx, since the git group may be not the primary group of all users). + + +Running `git-init-db` in an existing repository is safe. It will not overwrite +things that are already there. The primary reason for rerunning `git-init-db` +is to pick up newly added templates. + + + +EXAMPLES +-------- + +Start a new git repository for an existing code base:: ++ +---------------- +$ cd /path/to/my/codebase +$ git-init-db <1> +$ git-add . <2> + +<1> prepare /path/to/my/codebase/.git directory +<2> add all existing file to the index +---------------- + + +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 0000000..87abec1 --- /dev/null +++ b/Documentation/git-local-fetch.txt @@ -0,0 +1,43 @@ +git-local-fetch(1) +================== + +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 0000000..e995d1b --- /dev/null +++ b/Documentation/git-log.txt @@ -0,0 +1,62 @@ +git-log(1) +========== + +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. + + +Examples +-------- +git log --no-merges:: + + Show the whole commit history, but skip any merges + +git log v2.6.12.. include/scsi drivers/scsi:: + + Show all commits since version 'v2.6.12' that changed any file + in the include/scsi or drivers/scsi subdirectories + +git log --since="2 weeks ago" -- gitk:: + + Show the changes during the last two weeks to the file 'gitk'. + The "--" is necessary to avoid confusion with the *branch* named + 'gitk' + + +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-lost-found.txt b/Documentation/git-lost-found.txt new file mode 100644 index 0000000..03156f2 --- /dev/null +++ b/Documentation/git-lost-found.txt @@ -0,0 +1,78 @@ +git-lost-found(1) +================= + +NAME +---- +git-lost-found - Recover lost refs that luckily have not yet been pruned. + +SYNOPSIS +-------- +'git-lost-found' + +DESCRIPTION +----------- +Finds dangling commits and tags from the object database, and +creates refs to them in .git/lost-found/ directory. Commits and +tags that dereference to commits go to .git/lost-found/commit +and others are stored in .git/lost-found/other directory. + + +OUTPUT +------ +One line description from the commit and tag found along with +their object name are printed on the standard output. + + +EXAMPLE +------- + +Suppose you run 'git tag -f' and mistyped the tag to overwrite. +The ref to your tag is overwritten, but until you run 'git +prune', it is still there. + +------------ +$ git lost-found +[1ef2b196d909eed523d4f3c9bf54b78cdd6843c6] GIT 0.99.9c +... +------------ + +Also you can use gitk to browse how they relate to each other +and existing (probably old) tags. + +------------ +$ gitk $(cd .git/lost-found/commit && echo ??*) +------------ + +After making sure that it is the object you are looking for, you +can reconnect it to your regular .git/refs hierarchy. + +------------ +$ git cat-file -t 1ef2b196 +tag +$ git cat-file tag 1ef2b196 +object fa41bbce8e38c67a218415de6cfa510c7e50032a +type commit +tag v0.99.9c +tagger Junio C Hamano <junkio@cox.net> 1131059594 -0800 + +GIT 0.99.9c + +This contains the following changes from the "master" branch, since +... +$ git update-ref refs/tags/not-lost-anymore 1ef2b196 +$ git rev-parse not-lost-anymore +1ef2b196d909eed523d4f3c9bf54b78cdd6843c6 +------------ + +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-ls-files.txt b/Documentation/git-ls-files.txt new file mode 100644 index 0000000..e433407 --- /dev/null +++ b/Documentation/git-ls-files.txt @@ -0,0 +1,224 @@ +git-ls-files(1) +=============== + +NAME +---- +git-ls-files - Information about files in the index/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>] + [--full-name] [--] [<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 + +--directory:: + If a whole directory is classified as "other", show just its + name (with a trailing slash) and not its whole contents. + +-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-index 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:: modified/changed + K:: to be killed + ? other + +--full-name:: + When run from a subdirectory, the command usually + outputs paths relative to the current directory. This + option forces paths to be output relative to the project + top directory. + +--:: + Do not interpret any more arguments as options. + +<file>:: + Files to show. If no files are given all files which match the other + specified criteria are shown. + +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) + +When `-z` option is not used, TAB, LF, and backslash characters +in pathnames are represented as `\t`, `\n`, and `\\`, +respectively. + + +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 0000000..66fe60f --- /dev/null +++ b/Documentation/git-ls-remote.txt @@ -0,0 +1,63 @@ +git-ls-remote(1) +================ + +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 +------- +-h|--heads, -t|--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 0000000..b92a8b2 --- /dev/null +++ b/Documentation/git-ls-tree.txt @@ -0,0 +1,73 @@ +git-ls-tree(1) +============== + +NAME +---- +git-ls-tree - Lists the contents of a tree object. + + +SYNOPSIS +-------- +'git-ls-tree' [-d] [-r] [-t] [-z] [--name-only] [--name-status] <tree-ish> [paths...] + +DESCRIPTION +----------- +Lists the contents of a given tree object, like what "/bin/ls -a" does +in the current working directory. Note that the usage is subtly different, +though - 'paths' denote just a list of patterns to match, e.g. so specifying +directory name (without '-r') will behave differently, and order of the +arguments does not matter. + +OPTIONS +------- +<tree-ish>:: + Id of a tree-ish. + +-d:: + Show only the named tree entry itself, not its children. + +-r:: + Recurse into sub-trees. + +-t:: + Show tree entries even when going to recurse them. Has no effect + if '-r' was not passed. '-d' implies '-t'. + +-z:: + \0 line termination on output. + +--name-only:: +--name-status:: + List only filenames (instead of the "long" output), one per line. + +paths:: + When paths are given, show them (note that this isn't really raw + pathnames, but rather a list of patterns to match). Otherwise + implicitly uses the root level of the tree as the sole path argument. + + +Output Format +------------- + <mode> SP <type> SP <object> TAB <file> + +When the `-z` option is not used, TAB, LF, and backslash characters +in pathnames are represented as `\t`, `\n`, and `\\`, respectively. + + +Author +------ +Written by Petr Baudis <pasky@suse.cz> +Completely rewritten from scratch by Junio C Hamano <junkio@cox.net>, +another major rewrite by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list +<git@vger.kernel.org>. + +This manual page is a stub. You can help the git documentation by expanding it. + +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 0000000..8890754 --- /dev/null +++ b/Documentation/git-mailinfo.txt @@ -0,0 +1,72 @@ +git-mailinfo(1) +=============== + +NAME +---- +git-mailinfo - Extracts patch from a single e-mail message. + + +SYNOPSIS +-------- +'git-mailinfo' [-k] [-u | --encoding=<encoding>] <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 the encoding specified by + i18n.commitencoding configuration (defaults to utf-8) by + transliterating them. + Note that the patch is always used as is without charset + conversion, even with this flag. + +--encoding=<encoding>:: + Similar to -u but if the local convention is different + from what is specified by i18n.commitencoding, this flag + can be used to override it. + +<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 0000000..e0703e9 --- /dev/null +++ b/Documentation/git-mailsplit.txt @@ -0,0 +1,52 @@ +git-mailsplit(1) +================ + +NAME +---- +git-mailsplit - Totally braindamaged mbox splitter program. + +SYNOPSIS +-------- +'git-mailsplit' [-b] [-f<nn>] [-d<prec>] -o<directory> [--] [<mbox>...] + +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. If not given, the mbox is read from + the standard input. + +<directory>:: + Directory in which to place the individual messages. + +-b:: + If any file doesn't begin with a From line, assume it is a + single mail message instead of signalling error. + +-d<prec>:: + Instead of the default 4 digits with leading zeros, + different precision can be specified for the generated + filenames. + +-f<nn>:: + Skip the first <nn> numbers, for example if -f3 is specified, + start the numbering with 0004. + +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-merge-base.txt b/Documentation/git-merge-base.txt new file mode 100644 index 0000000..d1d56f1 --- /dev/null +++ b/Documentation/git-merge-base.txt @@ -0,0 +1,33 @@ +git-merge-base(1) +================= + +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 0000000..fbc986a --- /dev/null +++ b/Documentation/git-merge-index.txt @@ -0,0 +1,88 @@ +git-merge-index(1) +================== + +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 index 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 +------- +--:: + Do not interpret any more arguments as options. + +-a:: + Run merge against all files in the index 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 0000000..86aad37 --- /dev/null +++ b/Documentation/git-merge-one-file.txt @@ -0,0 +1,30 @@ +git-merge-one-file(1) +===================== + +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 0000000..4ce799b --- /dev/null +++ b/Documentation/git-merge.txt @@ -0,0 +1,158 @@ +git-merge(1) +============ + +NAME +---- +git-merge - Grand Unified Merge Driver + + +SYNOPSIS +-------- +'git-merge' [-n] [--no-commit] [-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 +------- +include::merge-options.txt[] + +<msg>:: + The commit message to be used for the merge commit (in case + it is created). The `git-fmt-merge-msg` script can be used + to give a good default for automated `git-merge` invocations. + +<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. + +include::merge-strategies.txt[] + + +If you tried a merge which resulted in a complex conflicts and +would want to start over, you can recover with +gitlink:git-reset[1]. + + +HOW MERGE WORKS +--------------- + +A merge is always between the current `HEAD` and one or more +remote branch heads, and the index file must exactly match the +tree of `HEAD` commit (i.e. the contents of the last commit) when +it happens. In other words, `git-diff --cached HEAD` must +report no changes. + +[NOTE] +This is a bit of lie. In certain special cases, your index are +allowed to be different from the tree of `HEAD` commit. The most +notable case is when your `HEAD` commit is already ahead of what +is being merged, in which case your index can have arbitrary +difference from your `HEAD` commit. Otherwise, your index entries +are allowed have differences from your `HEAD` commit that match +the result of trivial merge (e.g. you received the same patch +from external source to produce the same result as what you are +merging). For example, if a path did not exist in the common +ancestor and your head commit but exists in the tree you are +merging into your repository, and if you already happen to have +that path exactly in your index, the merge does not have to +fail. + +Otherwise, merge will refuse to do any harm to your repository +(that is, it may fetch the objects from remote, and it may even +update the local branch used to keep track of the remote branch +with `git pull remote rbranch:lbranch`, but your working tree, +`.git/HEAD` pointer and index file are left intact). + +You may have local modifications in the working tree files. In +other words, `git-diff` is allowed to report changes. +However, the merge uses your working tree as the working area, +and in order to prevent the merge operation from losing such +changes, it makes sure that they do not interfere with the +merge. Those complex tables in read-tree documentation define +what it means for a path to "interfere with the merge". And if +your local modifications interfere with the merge, again, it +stops before touching anything. + +So in the above two "failed merge" case, you do not have to +worry about lossage of data --- you simply were not ready to do +a merge, so no merge happened at all. You may want to finish +whatever you were in the middle of doing, and retry the same +pull after you are done and ready. + +When things cleanly merge, these things happen: + +1. the results are updated both in the index file and in your + working tree, +2. index file is written out as a tree, +3. the tree gets committed, and +4. the `HEAD` pointer gets advanced. + +Because of 2., we require that the original state of the index +file to match exactly the current `HEAD` commit; otherwise we +will write out your local changes already registered in your +index file along with the merge result, which is not good. +Because 1. involves only the paths different between your +branch and the remote branch you are pulling from during the +merge (which is typically a fraction of the whole tree), you can +have local modifications in your working tree as long as they do +not overlap with what the merge updates. + +When there are conflicts, these things happen: + +1. `HEAD` stays the same. + +2. Cleanly merged paths are updated both in the index file and + in your working tree. + +3. For conflicting paths, the index file records up to three + versions; stage1 stores the version from the common ancestor, + stage2 from `HEAD`, and stage3 from the remote branch (you + can inspect the stages with `git-ls-files -u`). The working + tree files have the result of "merge" program; i.e. 3-way + merge result with familiar conflict markers `<<< === >>>`. + +4. No other changes are done. In particular, the local + modifications you had before you started merge will stay the + same and the index entries for them stay as they were, + i.e. matching `HEAD`. + +After seeing a conflict, you can do two things: + + * Decide not to merge. The only clean-up you need are to reset + the index file to the `HEAD` commit to reverse 2. and to clean + up working tree changes made by 2. and 3.; `git-reset` can + be used for this. + + * Resolve the conflicts. `git-diff` would report only the + conflicting paths because of the above 2. and 3.. Edit the + working tree files into a desirable shape, `git-update-index` + them, to make the index file contain what the merge result + should be, and run `git-commit` to commit the result. + + +SEE ALSO +-------- +gitlink:git-fmt-merge-msg[1], gitlink:git-pull[1] + + +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 0000000..2860a3d --- /dev/null +++ b/Documentation/git-mktag.txt @@ -0,0 +1,47 @@ +git-mktag(1) +============ + +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-mv.txt b/Documentation/git-mv.txt new file mode 100644 index 0000000..d242b39 --- /dev/null +++ b/Documentation/git-mv.txt @@ -0,0 +1,54 @@ +git-mv(1) +========= + +NAME +---- +git-mv - Script used to move or rename a file, directory or symlink. + + +SYNOPSIS +-------- +'git-mv' <options>... <args>... + +DESCRIPTION +----------- +This script is used to move or rename a file, directory or symlink. + + git-mv [-f] [-n] <source> <destination> + git-mv [-f] [-n] [-k] <source> ... <destination directory> + +In the first form, it renames <source>, which must exist and be either +a file, symlink or directory, to <destination>. +In the second form, the last argument has to be an existing +directory; the given sources will be moved into this directory. + +The index is updated after successful completion, but the change must still be +committed. + +OPTIONS +------- +-f:: + Force renaming or moving of a file even if the target exists +-k:: + Skip move or rename actions which would lead to an error + condition. An error happens when a source is neither existing nor + controlled by GIT, or when it would overwrite an existing + file unless '-f' is given. +-n:: + Do nothing; only show what would happen + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> +Rewritten by Ryan Anderson <ryan@michonline.com> +Move functionality added by Josef Weidendorfer <Josef.Weidendorfer@gmx.de> + +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-name-rev.txt b/Documentation/git-name-rev.txt new file mode 100644 index 0000000..e37b0b8 --- /dev/null +++ b/Documentation/git-name-rev.txt @@ -0,0 +1,66 @@ +git-name-rev(1) +=============== + +NAME +---- +git-name-rev - Find symbolic names for given revs. + + +SYNOPSIS +-------- +'git-name-rev' [--tags] ( --all | --stdin | <commitish>... ) + +DESCRIPTION +----------- +Finds symbolic names suitable for human digestion for revisions given in any +format parsable by git-rev-parse. + + +OPTIONS +------- + +--tags:: + Do not use branch names, but only tags to name the commits + +--all:: + List all commits reachable from all refs + +--stdin:: + Read from stdin, append "(<rev_name>)" to all sha1's of name'able + commits, and pass to stdout + +EXAMPLE +------- + +Given a commit, find out where it is relative to the local refs. Say somebody +wrote you about that phantastic commit 33db5f4d9027a10e477ccf054b2c1ab94f74c85a. +Of course, you look into the commit, but that only tells you what happened, but +not the context. + +Enter git-name-rev: + +------------ +% git name-rev 33db5f4d9027a10e477ccf054b2c1ab94f74c85a +------------ + +Now you are wiser, because you know that it happened 940 revisions before v0.99. + +Another nice thing you can do is: + +------------ +% git log | git name-rev --stdin +------------ + + +Author +------ +Written by Johannes Schindelin <Johannes.Schindelin@gmx.de> + +Documentation +-------------- +Documentation by Johannes Schindelin. + +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 0000000..2d67d39 --- /dev/null +++ b/Documentation/git-pack-objects.txt @@ -0,0 +1,93 @@ +git-pack-objects(1) +=================== + +NAME +---- +git-pack-objects - Create a packed archive of objects. + + +SYNOPSIS +-------- +'git-pack-objects' [--non-empty] [--local] [--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 written 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. + +--local:: + This flag is similar to `--incremental`; instead of + ignoring all packed objects, it only ignores objects + that are packed and not in the local object store + (i.e. borrowed from an alternate). + +--non-empty:: + Only create a packed archive if it would contain at + least one object. + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +------------- +Documentation by Junio C Hamano + +See-Also +-------- +gitlink:git-repack[1] +gitlink:git-prune-packed[1] + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-pack-redundant.txt b/Documentation/git-pack-redundant.txt new file mode 100644 index 0000000..9fe86ae --- /dev/null +++ b/Documentation/git-pack-redundant.txt @@ -0,0 +1,58 @@ +git-pack-redundant(1) +===================== + +NAME +---- +git-pack-redundant - Program used to find redundant pack files. + + +SYNOPSIS +-------- +'git-pack-redundant [ --verbose ] [ --alt-odb ] < --all | .pack filename ... >' + +DESCRIPTION +----------- +This program computes which packs in your repository +are redundant. The output is suitable for piping to +'xargs rm' if you are in the root of the repository. + +git-pack-redundant accepts a list of objects on standard input. Any objects +given will be ignored when checking which packs are required. This makes the +following command useful when wanting to remove packs which contain unreachable +objects. + +git-fsck-objects --full --unreachable | cut -d ' ' -f3 | \ +git-pack-redundant --all | xargs rm + +OPTIONS +------- + + +--all:: + Processes all packs. Any filenames on the commandline are ignored. + +--alt-odb:: + Don't require objects present in packs from alternate object + directories to be present in local packs. + +--verbose:: + Outputs some statistics to stderr. Has a small performance penalty. + +Author +------ +Written by Lukas Sandström <lukass@etek.chalmers.se> + +Documentation +-------------- +Documentation by Lukas Sandström <lukass@etek.chalmers.se> + +See-Also +-------- +gitlink:git-pack-objects[1] +gitlink:git-repack[1] +gitlink: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 0000000..fc27afe --- /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 0000000..c8bd197 --- /dev/null +++ b/Documentation/git-patch-id.txt @@ -0,0 +1,43 @@ +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. + +When dealing with git-diff-tree output, it takes advantage of +the fact that the patch is prefixed with the object name of the +commit, and outputs two 40-byte hexadecimal string. The first +string is the patch ID, and the second string is the commit ID. +This can be used to make a mapping from patch ID to commit ID. + +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 0000000..915d3f8 --- /dev/null +++ b/Documentation/git-peek-remote.txt @@ -0,0 +1,52 @@ +git-peek-remote(1) +================== + +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 0000000..37c53a9 --- /dev/null +++ b/Documentation/git-prune-packed.txt @@ -0,0 +1,51 @@ +git-prune-packed(1) +===================== + +NAME +---- +git-prune-packed - Program used to remove the extra object files that are now +residing in a pack file. + + +SYNOPSIS +-------- +'git-prune-packed' [-n] + + +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. + + +OPTIONS +------- +-n:: + Don't actually remove any objects, only show those that would have been + removed. + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by Ryan Anderson <ryan@michonline.com> + +See-Also +-------- +gitlink:git-pack-objects[1] +gitlink: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 0000000..f694fcb --- /dev/null +++ b/Documentation/git-prune.txt @@ -0,0 +1,61 @@ +git-prune(1) +============ + +NAME +---- +git-prune - Prunes all unreachable objects from the object database + + +SYNOPSIS +-------- +'git-prune' [-n] [--] [<head>...] + +DESCRIPTION +----------- + +This runs `git-fsck-objects --unreachable` using all the refs +available in `$GIT_DIR/refs`, optionally with additional set of +objects specified on the command line, and prunes all +objects unreachable from any of these head 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. + +--:: + Do not interpret any more arguments as options. + +<head>...:: + In addition to objects + reachable from any of our references, keep objects + reachable from listed <head>s. + +EXAMPLE +------- + +To prune objects not used by your repository nor another that +borrows from your repository via its +`.git/objects/info/alternates`: + +------------ +$ git prune $(cd ../another && $(git-rev-parse --all)) +------------ + +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 0000000..20175f4 --- /dev/null +++ b/Documentation/git-pull.txt @@ -0,0 +1,132 @@ +git-pull(1) +=========== + +NAME +---- +git-pull - Pull and merge from another repository. + + +SYNOPSIS +-------- +'git-pull' <options> <repository> <refspec>... + + +DESCRIPTION +----------- +Runs `git-fetch` with the given parameters, and calls `git-merge` +to merge the retrieved head(s) into the current branch. + +Note that you can use `.` (current directory) as the +<repository> to pull from the local repository -- this is useful +when merging local branches into the current branch. + + +OPTIONS +------- +include::merge-options.txt[] + +include::fetch-options.txt[] + +include::pull-fetch-param.txt[] + +include::urls.txt[] + +include::merge-strategies.txt[] + +EXAMPLES +-------- + +git pull, git pull origin:: + Fetch the default head from the repository you cloned + from and merge it into your current branch. + +git pull -s ours . obsolete:: + Merge local branch `obsolete` into the current branch, + using `ours` merge strategy. + +git pull . fixes enhancements:: + Bundle local branch `fixes` and `enhancements` on top of + the current branch, making an Octopus merge. + +git pull --no-commit . maint:: + Merge local branch `maint` into the current branch, but + do not make a commit automatically. This can be used + when you want to include further changes to the merge, + or want to write your own merge commit message. ++ +You should refrain from abusing this option to sneak substantial +changes into a merge commit. Small fixups like bumping +release/version name would be acceptable. + +Command line pull of multiple branches from one repository:: ++ +------------------------------------------------ +$ cat .git/remotes/origin +URL: git://git.kernel.org/pub/scm/git/git.git +Pull: master:origin + +$ git checkout master +$ git fetch origin master:origin +pu:pu maint:maint +$ git pull . origin +------------------------------------------------ ++ +Here, a typical `.git/remotes/origin` file from a +`git-clone` operation is used in combination with +command line options to `git-fetch` to first update +multiple branches of the local repository and then +to merge the remote `origin` branch into the local +`master` branch. The local `pu` branch is updated +even if it does not result in a fast forward update. +Here, the pull can obtain its objects from the local +repository using `.`, as the previous `git-fetch` is +known to have already obtained and made available +all the necessary objects. + + +Pull of multiple branches from one repository using `.git/remotes` file:: ++ +------------------------------------------------ +$ cat .git/remotes/origin +URL: git://git.kernel.org/pub/scm/git/git.git +Pull: master:origin +Pull: +pu:pu +Pull: maint:maint + +$ git checkout master +$ git pull origin +------------------------------------------------ ++ +Here, a typical `.git/remotes/origin` file from a +`git-clone` operation has been hand-modified to include +the branch-mapping of additional remote and local +heads directly. A single `git-pull` operation while +in the `master` branch will fetch multiple heads and +merge the remote `origin` head into the current, +local `master` branch. + + +If you tried a pull which resulted in a complex conflicts and +would want to start over, you can recover with +gitlink:git-reset[1]. + + +SEE ALSO +-------- +gitlink:git-fetch[1], gitlink:git-merge[1] + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> +and Junio C Hamano <junkio@cox.net> + +Documentation +-------------- +Documentation by Jon Loeliger, +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 0000000..5b89110 --- /dev/null +++ b/Documentation/git-push.txt @@ -0,0 +1,81 @@ +git-push(1) +=========== + +NAME +---- +git-push - Update remote refs along with associated objects. + + +SYNOPSIS +-------- +'git-push' [--all] [--tags] [--force] <repository> <refspec>... + +DESCRIPTION +----------- + +Updates remote refs using local refs, while sending objects +necessary to complete the given refs. + +You can make interesting things happen to a repository +every time you push into it, by setting up 'hooks' there. See +documentation for gitlink:git-receive-pack[1]. + + +OPTIONS +------- +<repository>:: + The "remote" repository that is destination of a push + operation. See the section <<URLS,GIT URLS>> below. + +<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. ++ +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). ++ +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. ++ +Some short-cut notations are also supported. ++ +* `tag <tag>` means the same as `refs/tags/<tag>:refs/tags/<tag>`. +* A parameter <ref> without a colon is equivalent to + <ref>`:`<ref>, hence updates <ref> in the destination from <ref> + in the source. + +\--all:: + Instead of naming each ref to push, specifies that all + refs be pushed. + +\--tags:: + All refs under `$GIT_DIR/refs/tags` are pushed, in + addition to refspecs explicitly listed on the command + line. + +-f, \--force:: + Usually, the command refuses to update a remote ref that is + not a descendent of the local ref used to overwrite it. + This flag disables the check. This can cause the + remote repository to lose commits; use it with care. + +include::urls.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 0000000..6fbd6d9 --- /dev/null +++ b/Documentation/git-read-tree.txt @@ -0,0 +1,310 @@ +git-read-tree(1) +================ + +NAME +---- +git-read-tree - Reads tree information into the index + + +SYNOPSIS +-------- +'git-read-tree' (<tree-ish> | [[-m | --reset] [-u | -i]] <tree-ish1> [<tree-ish2> [<tree-ish3>]]) + + +DESCRIPTION +----------- +Reads the tree information given by <tree-ish> into the index, +but does not actually *update* any of the files it "caches". (see: +gitlink:git-checkout-index[1]) + +Optionally, it can merge a tree into the index, 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. The command will + refuse to run if your index file has unmerged entries, + indicating that you have not finished previous merge you + started. + +--reset:: + Same as -m, except that unmerged entries are discarded + instead of failing. + +-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 index has an entry for a +given pathname, and the contents of the path matches with the tree +being read, the stat info from the index is used. (In other words, the +index'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 index + 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 index + 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 index 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". When performing a merge of another +branch into the current branch, we use the common ancestor tree +as <tree1>, the current branch head as <tree2>, and the other +branch head as <tree3>. + +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 our branch in + stage 2 and their branch in stage 3) + + - stage 1 and stage 2 are the same and stage 3 is different; take + stage 3 (our branch in stage 2 did not do anything since the + ancestor in stage 1 while their branch in stage 3 worked on + it) + + - stage 1 and stage 3 are the same and stage 2 is different take + stage 2 (we did something while they did nothing) + +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 updates +the files in the working tree as it merges each path and at the +end of a successful merge. + +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, and mixing your random changes in an unrelated merge +commit. To illustrate, suppose you start from what has been +commited last to your repository: + +---------------- +$ JC=`git-rev-parse --verify "HEAD^0"` +$ 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 git://.... linus +$ LT=`cat .git/FETCH_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 index 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. + +However, if you have local changes in the working tree that +would be overwritten by this merge,`git-read-tree` will refuse +to run to prevent your changes from being lost. + +In other words, there is no need to worry about what exists only +in the working tree. When you have local changes in a part of +the project that is not involved in the merge, your changes do +not interfere with the merge, and are kept intact. When they +*do* interfere, the merge does not even start (`git-read-tree` +complains loudly and fails without modifying anything). In such +a case, you can simply continue doing what you were in the +middle of doing, and when your working tree is ready (i.e. you +have finished your work-in-progress), attempt the merge again. + + +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 0000000..16c158f --- /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 0000000..60debca --- /dev/null +++ b/Documentation/git-receive-pack.txt @@ -0,0 +1,99 @@ +git-receive-pack(1) +=================== + +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 + +There are other real-world examples of using update and +post-update hooks found in the Documentation/howto directory. + + +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 0000000..6240535 --- /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-repack.txt b/Documentation/git-repack.txt new file mode 100644 index 0000000..9060fe8 --- /dev/null +++ b/Documentation/git-repack.txt @@ -0,0 +1,66 @@ +git-repack(1) +============= + +NAME +---- +git-repack - Script used to pack a repository from a collection of +objects into pack files. + + +SYNOPSIS +-------- +'git-repack' [-a] [-d] [-l] [-n] + +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. + +-l:: + Pass the `--local` option to `git pack-objects`, see + gitlink:git-pack-objects[1]. + +-n:: + Do not update the server information with + `git update-server-info`. + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by Ryan Anderson <ryan@michonline.com> + +See-Also +-------- +gitlink:git-pack-objects[1] +gitlink:git-prune-packed[1] + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-repo-config.txt b/Documentation/git-repo-config.txt new file mode 100644 index 0000000..3069464 --- /dev/null +++ b/Documentation/git-repo-config.txt @@ -0,0 +1,170 @@ +git-repo-config(1) +================== + +NAME +---- +git-repo-config - Get and set options in .git/config. + + +SYNOPSIS +-------- +'git-repo-config' name [value [value_regex]] +'git-repo-config' --replace-all name [value [value_regex]] +'git-repo-config' --get name [value_regex] +'git-repo-config' --get-all name [value_regex] +'git-repo-config' --unset name [value_regex] +'git-repo-config' --unset-all name [value_regex] + +DESCRIPTION +----------- +You can query/set/replace/unset options with this command. The name is +actually the section and the key separated by a dot, and the value will be +escaped. + +If you want to set/unset an option which can occur on multiple lines, you +should provide a POSIX regex for the value. If you want to handle the lines +*not* matching the regex, just prepend a single exclamation mark in front +(see EXAMPLES). + +This command will fail if + +. .git/config is invalid, +. .git/config can not be written to, +. no section was provided, +. the section or key is invalid, +. you try to unset an option which does not exist, or +. you try to unset/set an option for which multiple lines match. + + +OPTIONS +------- + +--replace-all:: + Default behaviour is to replace at most one line. This replaces + all lines matching the key (and optionally the value_regex) + +--get:: + Get the value for a given key (optionally filtered by a regex + matching the value). + +--get-all:: + Like get, but does not fail if the number of values for the key + is not exactly one. + +--unset:: + Remove the line matching the key from .git/config. + +--unset-all:: + Remove all matching lines from .git/config. + + +EXAMPLE +------- + +Given a .git/config like this: + + # + # This is the config file, and + # a '#' or ';' character indicates + # a comment + # + + ; core variables + [core] + ; Don't trust file modes + filemode = false + + ; Our diff algorithm + [diff] + external = "/usr/local/bin/gnu-diff -u" + renames = true + + ; Proxy settings + [proxy] + command="ssh" for "ssh://kernel.org/" + command="proxy-command" for kernel.org + command="myprotocol-command" for "my://" + command=default-proxy ; for all the rest + +you can set the filemode to true with + +------------ +% git repo-config core.filemode true +------------ + +The hypothetic proxy command entries actually have a postfix to discern +to what URL they apply. Here is how to change the entry for kernel.org +to "ssh". + +------------ +% git repo-config proxy.command '"ssh" for kernel.org' 'for kernel.org$' +------------ + +This makes sure that only the key/value pair for kernel.org is replaced. + +To delete the entry for renames, do + +------------ +% git repo-config --unset diff.renames +------------ + +If you want to delete an entry for a multivar (like proxy.command above), +you have to provide a regex matching the value of exactly one line. + +To query the value for a given key, do + +------------ +% git repo-config --get core.filemode +------------ + +or + +------------ +% git repo-config core.filemode +------------ + +or, to query a multivar: + +------------ +% git repo-config --get proxy.command "for kernel.org$" +------------ + +If you want to know all the values for a multivar, do: + +------------ +% git repo-config --get-all proxy.command +------------ + +If you like to live dangerous, you can replace *all* proxy.commands by a +new one with + +------------ +% git repo-config --replace-all proxy.command ssh +------------ + +However, if you really only want to replace the line for the default proxy, +i.e. the one without a "for ..." postfix, do something like this: + +------------ +% git repo-config proxy.command ssh '! for ' +------------ + +To actually match only values with an exclamation mark, you have to + +------------ +% git repo-config section.key value '[!]' +------------ + + +Author +------ +Written by Johannes Schindelin <Johannes.Schindelin@gmx.de> + +Documentation +-------------- +Documentation by Johannes Schindelin. + +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 0000000..2463ec9 --- /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-rerere.txt b/Documentation/git-rerere.txt new file mode 100644 index 0000000..8b6b651 --- /dev/null +++ b/Documentation/git-rerere.txt @@ -0,0 +1,177 @@ +git-rerere(1) +============= + +NAME +---- +git-rerere - Reuse recorded resolve + +SYNOPSIS +-------- +'git-rerere' + + +DESCRIPTION +----------- + +In a workflow that employs relatively long lived topic branches, +the developer sometimes needs to resolve the same conflict over +and over again until the topic branches are done (either merged +to the "release" branch, or sent out and accepted upstream). + +This command helps this process by recording conflicted +automerge results and corresponding hand-resolve results on the +initial manual merge, and later by noticing the same automerge +results and applying the previously recorded hand resolution. + +[NOTE] +You need to create `$GIT_DIR/rr-cache` directory to enable this +command. + +DISCUSSION +---------- + +When your topic branch modifies overlapping area that your +master branch (or upstream) touched since your topic branch +forked from it, you may want to test it with the latest master, +even before your topic branch is ready to be pushed upstream: + +------------ + o---*---o topic + / + o---o---o---*---o---o master +------------ + +For such a test, you need to merge master and topic somehow. +One way to do it is to pull master into the topic branch: + +------------ + $ git checkout topic + $ git pull . master + + o---*---o---+ topic + / / + o---o---o---*---o---o master +------------ + +The commits marked with `*` touch the same area in the same +file; you need to resolve the conflicts when creating the commit +marked with `+`. Then you can test the result to make sure your +work-in-progress still works with what is in the latest master. + +After this test merge, there are two ways to continue your work +on the topic. The easiest is to build on top of the test merge +commit `+`, and when your work in the topic branch is finally +ready, pull the topic branch into master, and/or ask the +upstream to pull from you. By that time, however, the master or +the upstream might have been advanced since the test merge `+`, +in which case the final commit graph would look like this: + +------------ + $ git checkout topic + $ git pull . master + $ ... work on both topic and master branches + $ git checkout master + $ git pull . topic + + o---*---o---+---o---o topic + / / \ + o---o---o---*---o---o---o---o---+ master +------------ + +When your topic branch is long-lived, however, your topic branch +would end up having many such "Merge from master" commits on it, +which would unnecessarily clutter the development history. +Readers of the Linux kernel mailing list may remember that Linus +complained about such too frequent test merges when a subsystem +maintainer asked to pull from a branch full of "useless merges". + +As an alternative, to keep the topic branch clean of test +merges, you could blow away the test merge, and keep building on +top of the tip before the test merge: + +------------ + $ git checkout topic + $ git pull . master + $ git reset --hard HEAD^ ;# rewind the test merge + $ ... work on both topic and master branches + $ git checkout master + $ git pull . topic + + o---*---o-------o---o topic + / \ + o---o---o---*---o---o---o---o---+ master +------------ + +This would leave only one merge commit when your topic branch is +finally ready and merged into the master branch. This merge +would require you to resolve the conflict, introduced by the +commits marked with `*`. However, often this conflict is the +same conflict you resolved when you created the test merge you +blew away. `git-rerere` command helps you to resolve this final +conflicted merge using the information from your earlier hand +resolve. + +Running `git-rerere` command immediately after a conflicted +automerge records the conflicted working tree files, with the +usual conflict markers `<<<<<<<`, `=======`, and `>>>>>>>` in +them. Later, after you are done resolving the conflicts, +running `git-rerere` again records the resolved state of these +files. Suppose you did this when you created the test merge of +master into the topic branch. + +Next time, running `git-rerere` after seeing a conflicted +automerge, if the conflict is the same as the earlier one +recorded, it is noticed and a three-way merge between the +earlier conflicted automerge, the earlier manual resolution, and +the current conflicted automerge is performed by the command. +If this three-way merge resolves cleanly, the result is written +out to your working tree file, so you would not have to manually +resolve it. Note that `git-rerere` leaves the index file alone, +so you still need to do the final sanity checks with `git diff` +(or `git diff -c`) and `git update-index` when you are +satisfied. + +As a convenience measure, `git-merge` automatically invokes +`git-rerere` when it exits with a failed automerge, which +records it if it is a new conflict, or reuses the earlier hand +resolve when it is not. `git-commit` also invokes `git-rerere` +when recording a merge result. What this means is that you do +not have to do anything special yourself (Note: you still have +to create `$GIT_DIR/rr-cache` directory to enable this command). + +In our example, when you did the test merge, the manual +resolution is recorded, and it will be reused when you do the +actual merge later with updated master and topic branch, as long +as the earlier resolution is still applicable. + +The information `git-rerere` records is also used when running +`git-rebase`. After blowing away the test merge and continuing +development on the topic branch: + +------------ + o---*---o-------o---o topic + / + o---o---o---*---o---o---o---o master + + $ git rebase master topic + + o---*---o-------o---o topic + / + o---o---o---*---o---o---o---o master +------------ + +you could run `git rebase master topic`, to keep yourself +up-to-date even before your topic is ready to be sent upstream. +This would result in falling back to three-way merge, and it +would conflict the same way the test merge you resolved earlier. +`git-rerere` is run by `git rebase` to help you resolve this +conflict. + + +Author +------ +Written by Junio C Hamano <junkio@cox.net> + +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 0000000..b4e737e --- /dev/null +++ b/Documentation/git-reset.txt @@ -0,0 +1,184 @@ +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. + +This command is useful if you notice some small error in a recent +commit (or set of commits) and want to redo that part without showing +the undo in the history. + +If you want to undo a commit other than the latest on a branch, +gitlink:git-revert[1] is your friend. + +OPTIONS +------- +--mixed:: + Resets the index but not the working tree (ie, the changed files + are preserved but not marked for commit) and 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 to be in a good order. This leaves all your changed + files "Updated but not checked in", as gitlink:git-status[1] would + put it. + +--hard:: + Matches the working tree and index to that of the tree being + switched to. Any changes to tracked files in the working tree + since <commit-ish> are lost. + +<commit-ish>:: + Commit to make the current HEAD. + +Examples +~~~~~~~~ + +Undo a commit and redo:: ++ +------------ +$ git commit ... +$ git reset --soft HEAD^ <1> +$ edit <2> +$ git commit -a -c ORIG_HEAD <3> + +<1> This is most often done when you remembered what you +just committed is incomplete, or you misspelled your commit +message, or both. Leaves working tree as it was before "reset". +<2> make corrections to working tree files. +<3> "reset" copies the old head to .git/ORIG_HEAD; redo the +commit by starting with its log message. If you do not need to +edit the message further, you can give -C option instead. +------------ + +Undo commits permanently:: ++ +------------ +$ git commit ... +$ git reset --hard HEAD~3 <1> + +<1> The last three commits (HEAD, HEAD^, and HEAD~2) were bad +and you do not want to ever see them again. Do *not* do this if +you have already given these commits to somebody else. +------------ + +Undo a commit, making it a topic branch:: ++ +------------ +$ git branch topic/wip <1> +$ git reset --hard HEAD~3 <2> +$ git checkout topic/wip <3> + +<1> You have made some commits, but realize they were premature +to be in the "master" branch. You want to continue polishing +them in a topic branch, so create "topic/wip" branch off of the +current HEAD. +<2> Rewind the master branch to get rid of those three commits. +<3> Switch to "topic/wip" branch and keep working. +------------ + +Undo update-index:: ++ +------------ +$ edit <1> +$ git-update-index frotz.c filfre.c +$ mailx <2> +$ git reset <3> +$ git pull git://info.example.com/ nitfol <4> + +<1> you are happily working on something, and find the changes +in these files are in good order. You do not want to see them +when you run "git diff", because you plan to work on other files +and changes with these files are distracting. +<2> somebody asks you to pull, and the changes sounds worthy of merging. +<3> however, you already dirtied the index (i.e. your index does +not match the HEAD commit). But you know the pull you are going +to make does not affect frotz.c nor filfre.c, so you revert the +index changes for these two files. Your changes in working tree +remain there. +<4> then you can pull and merge, leaving frotz.c and filfre.c +changes still in the working tree. +------------ + +Undo a merge or pull:: ++ +------------ +$ git pull <1> +Trying really trivial in-index merge... +fatal: Merge requires file-level merging +Nope. +... +Auto-merging nitfol +CONFLICT (content): Merge conflict in nitfol +Automatic merge failed/prevented; fix up by hand +$ git reset --hard <2> + +<1> try to update from the upstream resulted in a lot of +conflicts; you were not ready to spend a lot of time merging +right now, so you decide to do that later. +<2> "pull" has not made merge commit, so "git reset --hard" +which is a synonym for "git reset --hard HEAD" clears the mess +from the index file and the working tree. + +$ git pull . topic/branch <3> +Updating from 41223... to 13134... +Fast forward +$ git reset --hard ORIG_HEAD <4> + +<3> merge a topic branch into the current branch, which resulted +in a fast forward. +<4> but you decided that the topic branch is not ready for public +consumption yet. "pull" or "merge" always leaves the original +tip of the current branch in ORIG_HEAD, so resetting hard to it +brings your index file and the working tree back to that state, +and resets the tip of the branch to that commit. +------------ + +Interrupted workflow:: ++ +Suppose you are interrupted by an urgent fix request while you +are in the middle of a large change. The files in your +working tree are not in any shape to be committed yet, but you +need to get to the other branch for a quick bugfix. ++ +------------ +$ git checkout feature ;# you were working in "feature" branch and +$ work work work ;# got interrupted +$ git commit -a -m 'snapshot WIP' <1> +$ git checkout master +$ fix fix fix +$ git commit ;# commit with real log +$ git checkout feature +$ git reset --soft HEAD^ ;# go back to WIP state <2> +$ git reset <3> + +<1> This commit will get blown away so a throw-away log message is OK. +<2> This removes the 'WIP' commit from the commit history, and sets + your working tree to the state just before you made that snapshot. +<3> After <2>, the index file still has all the WIP changes you + committed in <1>. This sets it to the last commit you were + basing the WIP changes on. +------------ + +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 0000000..4e57c2b --- /dev/null +++ b/Documentation/git-resolve.txt @@ -0,0 +1,36 @@ +git-resolve(1) +============== + +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 0000000..1c6146c --- /dev/null +++ b/Documentation/git-rev-list.txt @@ -0,0 +1,155 @@ +git-rev-list(1) +=============== + +NAME +---- +git-rev-list - Lists commit objects in reverse chronological order + + +SYNOPSIS +-------- +[verse] +'git-rev-list' [ \--max-count=number ] + [ \--max-age=timestamp ] + [ \--min-age=timestamp ] + [ \--sparse ] + [ \--no-merges ] + [ \--remove-empty ] + [ \--all ] + [ [ \--merge-order [ \--show-breaks ] ] | [ \--topo-order ] ] + [ \--parents ] + [ \--objects [ \--unpacked ] ] + [ \--pretty | \--header ] + [ \--bisect ] + <commit>... [ \-- <paths>... ] + +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 '{caret}' cause listing to stop at +that point. Their parents are implied. "git-rev-list foo bar {caret}baz" thus +means "list all the commits which are included in 'foo' and 'bar', but +not in 'baz'". + +A special notation <commit1>..<commit2> can be used as a +short-hand for {caret}<commit1> <commit2>. + + +OPTIONS +------- +--pretty:: + Print the contents of the commit changesets in human-readable form. + +--header:: + Print the contents of the commit in raw-format; each + record is separated with a NUL character. + +--objects:: + 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'". + +--unpacked:: + Only useful with `--objects`; print the object IDs that + are not in packs. + +--bisect:: + Limit 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. + +--max-count:: + Limit the number of commits output. + +--max-age=timestamp, --min-age=timestamp:: + Limit the commits output to specified time range. + +--sparse:: + When optional paths are given, the command outputs only + the commits that changes at least one of them, and also + ignores merges that do not touch the given paths. This + flag makes the command output all eligible commits + (still subject to count and age limitation), but apply + merge simplification nevertheless. + +--remove-empty:: + Stop when a given path disappears from the tree. + +--all:: + Pretend as if all the refs in `$GIT_DIR/refs/` are + listed on the command line as <commit>. + +--topo-order:: + By default, the commits are shown in reverse + chronological order. This option makes them appear in + topological order (i.e. descendant commits are shown + before their parents). + +--merge-order:: + When 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. + +--show-breaks:: + 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 arbitrary 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 0000000..d638bfc --- /dev/null +++ b/Documentation/git-rev-parse.txt @@ -0,0 +1,179 @@ +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 '{caret}' and + strip '{caret}' prefix from the object names that already have + one. + +--symbolic:: + Usually the object names are output in SHA1 form (with + possible '{caret}' 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 subdirectory, show the + path of the current directory relative to the top-level + directory. + +--show-cdup:: + When the command is invoked from a subdirectory, show the + path of the top-level directory relative to the current + directory (typically a sequence of "../", or an empty string). + +--since=datestring, --after=datestring:: + Parses the date string, and outputs corresponding + --max-age= parameter for git-rev-list command. + +--until=datestring, --before=datestring:: + Parses the date string, and outputs corresponding + --min-age= parameter for git-rev-list command. + +<args>...:: + Flags and parameters to be parsed. + + +SPECIFYING REVISIONS +-------------------- + +A revision parameter typically, but not necessarily, 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 '{caret}' to a revision parameter means the first parent of + that commit object. '{caret}<n>' means the <n>th parent (i.e. + 'rev{caret}' + is equivalent to 'rev{caret}1'). As a special rule, + 'rev{caret}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{caret}{caret}{caret} which is equivalent to\ + rev{caret}1{caret}1{caret}1. + +* A suffix '{caret}' followed by an object type name enclosed in + brace pair (e.g. `v0.99.8{caret}\{commit\}`) means the object + could be a tag, and dereference the tag recursively until an + object of that type is found or the object cannot be + dereferenced anymore (in which case, barf). `rev{caret}0` + introduced earlier is a short-hand for `rev{caret}\{commit\}`. + +* A suffix '{caret}' followed by an empty brace pair + (e.g. `v0.99.8{caret}\{\}`) means the object could be a tag, + and dereference the tag recursively until a non-tag object is + found. + +'git-rev-parse' also accepts a prefix '{caret}' 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 '{caret}r1 r2' + +Here is an illustration, by Jon Loeliger. Both node B and C are +a commit parents of commit node A. Parent commits are ordered +left-to-right. + + G H I J + \ / \ / + D E F + \ | / + \ | / + \|/ + B C + \ / + \ / + A + + A = = A^0 + B = A^ = A^1 = A~1 + C = A^2 = A^2 + D = A^^ = A^1^1 = A~2 + E = B^2 = A^^2 + F = B^3 = A^^3 + G = A^^^ = A^1^1^1 = A~3 + H = D^2 = B^^2 = A^^^2 = A~2^2 + I = F^ = B^3^ = A^^3^ + J = F^2 = B^3^2 = A^^3^2 + + +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 0000000..e27c680 --- /dev/null +++ b/Documentation/git-revert.txt @@ -0,0 +1,57 @@ +git-revert(1) +============= + +NAME +---- +git-revert - Revert an existing commit. + +SYNOPSIS +-------- +'git-revert' [--edit | --no-edit] [-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. + +-e|--edit:: + With this option, `git-revert` will let you edit the commit + message prior committing the revert. This is the default if + you run the command from a terminal. + +--no-edit:: + With this option, `git-revert` will not start the commit + message editor. + +-n|--no-commit:: + 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 0000000..00537d8 --- /dev/null +++ b/Documentation/git-send-email.txt @@ -0,0 +1,84 @@ +git-send-email(1) +================= + +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. + +OPTIONS +------- +The options available are: + +--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 + +--compose:: + Use $EDITOR to edit an introductory message for the + patch series. + +--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. + +--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. + +--quiet:: + Make git-send-email less verbose. One line per email should be + all that is output. + +--smtp-server:: + If set, specifies the outgoing SMTP server to use. Defaults to + localhost. + +--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. + +--to:: + Specify the primary recipient of the emails generated. + Generally, this will be the upstream maintainer of the + project involved. + + +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 0000000..577f06a --- /dev/null +++ b/Documentation/git-send-pack.txt @@ -0,0 +1,110 @@ +git-send-pack(1) +================ + +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 one or more '<ref>' 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 0000000..6ef59ac --- /dev/null +++ b/Documentation/git-sh-setup.txt @@ -0,0 +1,35 @@ +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, to make the rest of the git scripts more careful and readable, +use it as follows: + +------------------------------------------------- +. git-sh-setup || die "Not a git archive" +------------------------------------------------- + +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-shell.txt b/Documentation/git-shell.txt new file mode 100644 index 0000000..3f4d804 --- /dev/null +++ b/Documentation/git-shell.txt @@ -0,0 +1,35 @@ +git-shell(1) +============ + +NAME +---- +git-shell - Restricted login shell for GIT over SSH only + + +SYNOPSIS +-------- +'git-shell -c <command> <argument>' + +DESCRIPTION +----------- +This is meant to be used as a login shell for SSH accounts you want +to restrict to GIT pull/push access only. It permits execution only +of server-side GIT commands implementing the pull/push functionality. +The commands can be executed only by the '-c' option; the shell is not +interactive. + +Currently, only the `git-receive-pack` and `git-upload-pack` commands +are permitted to be called, with a single required argument. + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by Petr Baudis 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 0000000..65ca77f --- /dev/null +++ b/Documentation/git-shortlog.txt @@ -0,0 +1,30 @@ +git-shortlog(1) +=============== + +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 0000000..7b1a9c9 --- /dev/null +++ b/Documentation/git-show-branch.txt @@ -0,0 +1,162 @@ +git-show-branch(1) +================== + +NAME +---- +git-show-branch - Show branches and their commits. + +SYNOPSIS +-------- +[verse] +git-show-branch [--all] [--heads] [--tags] [--topo-order] [--current] + [--more=<n> | --list | --independent | --merge-base] + [--no-name | --sha1-name] [<rev> | <glob>]... + +DESCRIPTION +----------- + +Shows the commit ancestry graph starting from the commits named +with <rev>s or <globs>s (or all refs under $GIT_DIR/refs/heads +and/or $GIT_DIR/refs/tags) semi-visually. + +It cannot show more than 29 branches and commits at a time. + +It uses `showbranch.default` multi-valued configuration items if +no <rev> nor <glob> is given on the command line. + + +OPTIONS +------- +<rev>:: + Arbitrary extended SHA1 expression (see `git-rev-parse`) + that typically names a branch HEAD or a tag. + +<glob>:: + A glob pattern that matches branch or tag names under + $GIT_DIR/refs. For example, if you have many topic + branches under $GIT_DIR/refs/heads/topic, giving + `topic/*` would show all of them. + +--all --heads --tags:: + Show all refs under $GIT_DIR/refs, $GIT_DIR/refs/heads, + and $GIT_DIR/refs/tags, respectively. + +--current:: + With this option, the command includes the current + branch to the list of revs to be shown when it is not + given on the command line. + +--topo-order:: + By default, the branches and their commits are shown in + reverse chronological order. This option makes them + appear in topological order (i.e., descendant commits + are shown before their parents). + +--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:: + Synonym 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>. + +--no-name:: + Do not show naming strings for each commit. + +--sha1-name:: + Instead of naming the commits using the path to reach + them from heads (e.g. "master~2" to mean the grandparent + of "master"), name them with the unique prefix of their + object names. + +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. Merge commits are denoted by +a `-` sign. Each commit shows a short name that +can be used as an extended 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. The current branch is "master". + + +EXAMPLE +------- + +If you keep your primary branches immediately under +`$GIT_DIR/refs/heads`, and topic branches in subdirectories of +it, having the following in the configuration file may help: + +------------ +[showbranch] + default = --topo-order + default = heads/* + +------------ + +With this,`git show-branch` without extra parameters would show +only the primary branches. In addition, if you happen to be on +your topic branch, it is shown as well. + + + +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 0000000..be09b62 --- /dev/null +++ b/Documentation/git-show-index.txt @@ -0,0 +1,35 @@ +git-show-index(1) +================= + +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 0000000..b7116b3 --- /dev/null +++ b/Documentation/git-ssh-fetch.txt @@ -0,0 +1,51 @@ +git-ssh-fetch(1) +================ + +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 0000000..702674e --- /dev/null +++ b/Documentation/git-ssh-upload.txt @@ -0,0 +1,47 @@ +git-ssh-upload(1) +================= + +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 0000000..753fc08 --- /dev/null +++ b/Documentation/git-status.txt @@ -0,0 +1,45 @@ +git-status(1) +============= + +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 0000000..528a1b6 --- /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-svnimport.txt b/Documentation/git-svnimport.txt new file mode 100644 index 0000000..63e28b8 --- /dev/null +++ b/Documentation/git-svnimport.txt @@ -0,0 +1,130 @@ +git-svnimport(1) +================ +v0.1, July 2005 + +NAME +---- +git-svnimport - Import a SVN repository into git + + +SYNOPSIS +-------- +'git-svnimport' [ -o <branch-for-HEAD> ] [ -h ] [ -v ] [ -d | -D ] + [ -C <GIT_repository> ] [ -i ] [ -u ] [-l limit_rev] + [ -b branch_subdir ] [ -T trunk_subdir ] [ -t tag_subdir ] + [ -s start_chg ] [ -m ] [ -M regex ] + <SVN_repository_URL> [ <path> ] + + +DESCRIPTION +----------- +Imports a SVN repository into git. It will either create a new +repository, or incrementally import into an existing one. + +SVN access is done by the SVN::Perl module. + +git-svnimport assumes that SVN repositories are organized into one +"trunk" directory where the main development happens, "branch/FOO" +directories for branches, and "/tags/FOO" directories for tags. +Other subdirectories are ignored. + +git-svnimport creates a file ".git/svn2git", which is required for +incremental SVN imports. + +OPTIONS +------- +-C <target-dir>:: + The GIT repository to import to. If the directory doesn't + exist, it will be created. Default is the current directory. + +-s <start_rev>:: + Start importing at this SVN change number. The default is 1. ++ +When importing incrementally, you might need to edit the .git/svn2git file. + +-i:: + Import-only: don't perform a checkout after importing. This option + ensures the working directory and index remain untouched and will + not create them if they do not exist. + +-T <trunk_subdir>:: + Name the SVN trunk. Default "trunk". + +-t <tag_subdir>:: + Name the SVN subdirectory for tags. Default "tags". + +-b <branch_subdir>:: + Name the SVN subdirectory for branches. Default "branches". + +-o <branch-for-HEAD>:: + The 'trunk' branch from SVN is imported to the 'origin' branch within + the git repository. Use this option if you want to import into a + different branch. + +-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. + +-l <max_rev>:: + Specify a maximum revision number to pull. + + Formerly, this option controlled how many revisions to pull, + due to SVN memory leaks. (These have been worked around.) + +-v:: + Verbosity: let 'svnimport' report what it is doing. + +-d:: + Use direct HTTP requests if possible. The "<path>" argument is used + only for retrieving the SVN logs; the path to the contents is + included in the SVN log. + +-D:: + Use direct HTTP requests if possible. The "<path>" argument is used + for retrieving the logs, as well as for the contents. ++ +There's no safe way to automatically find out which of these options to +use, so you need to try both. Usually, the one that's wrong will die +with a 40x error pretty quickly. + +<SVN_repository_URL>:: + The URL of the SVN module you want to import. For local + repositories, use "file:///absolute/path". ++ +If you're using the "-d" or "-D" option, this is the URL of the SVN +repository itself; it usually ends in "/svn". + +<path>:: + The path to the module you want to check out. + +-h:: + Print a short usage message and exit. + +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>. + +Based on a cvs2git script by the same author. + +Documentation +-------------- +Documentation by Matthias Urlichs <smurf@smurf.noris.de>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-symbolic-ref.txt b/Documentation/git-symbolic-ref.txt new file mode 100644 index 0000000..68ac6a6 --- /dev/null +++ b/Documentation/git-symbolic-ref.txt @@ -0,0 +1,52 @@ +git-symbolic-ref(1) +=================== + +NAME +---- +git-symbolic-ref - read and modify symbolic refs + +SYNOPSIS +-------- +'git-symbolic-ref' <name> [<ref>] + +DESCRIPTION +----------- +Given one argument, reads which branch head the given symbolic +ref refers to and outputs its path, relative to the `.git/` +directory. Typically you would give `HEAD` as the <name> +argument to see on which branch your working tree is on. + +Give two arguments, create or update a symbolic ref <name> to +point at the given branch <ref>. + +Traditionally, `.git/HEAD` is a symlink pointing at +`refs/heads/master`. When we want to switch to another branch, +we did `ln -sf refs/heads/newbranch .git/HEAD`, and when we want +to find out which branch we are on, we did `readlink .git/HEAD`. +This was fine, and internally that is what still happens by +default, but on platforms that do not have working symlinks, +or that do not have the `readlink(1)` command, this was a bit +cumbersome. On some platforms, `ln -sf` does not even work as +advertised (horrors). + +A symbolic ref can be a regular file that stores a string that +begins with `ref: refs/`. For example, your `.git/HEAD` *can* +be a regular file whose contents is `ref: refs/heads/master`. +This can be used on a filesystem that does not support symbolic +links. Instead of doing `readlink .git/HEAD`, `git-symbolic-ref +HEAD` can be used to find out which branch we are on. To point +the HEAD to `newbranch`, instead of `ln -sf refs/heads/newbranch +.git/HEAD`, `git-symbolic-ref HEAD refs/heads/newbranch` can be +used. + +Currently, .git/HEAD uses a regular file symbolic ref on Cygwin, +and everywhere else it is implemented as a symlink. This can be +changed at compilation time. + +Author +------ +Written by Junio C Hamano <junkio@cox.net> + +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 0000000..e8892bb --- /dev/null +++ b/Documentation/git-tag.txt @@ -0,0 +1,67 @@ +git-tag(1) +========== + +NAME +---- +git-tag - Create a tag object signed with GPG + + +SYNOPSIS +-------- +'git-tag' [-a | -s | -u <key-id>] [-f | -d] [-m <msg>] <name> [<head>] + +DESCRIPTION +----------- +Adds a 'tag' reference in .git/refs/tags/ + +Unless `-f` is given, the tag must not yet exist in +`.git/refs/tags/` directory. + +If one of `-a`, `-s`, or `-u <key-id>` is passed, the command +creates a 'tag' object, and requires the tag message. Unless +`-m <msg>` is given, an editor is started for the user to type +in the tag message. + +Otherwise just the SHA1 object name of the commit object is +written (i.e. a lightweight tag). + +A GnuPG signed tag object will be created when `-s` or `-u +<key-id>` is used. When `-u <key-id>` is not used, the +committer identity for the current user is used to find the +GnuPG key for signing. + +`-d <tag>` deletes the tag. + +OPTIONS +------- +-a:: + Make an unsigned, annotated tag object + +-s:: + Make a GPG-signed tag, using the default e-mail address's key + +-u <key-id>:: + Make a GPG-signed tag, using the given key + +-f:: + Replace an existing tag with the given name (instead of failing) + +-d:: + Delete an existing tag with the given name + +-m <msg>:: + Use the given tag message (instead of prompting) + + +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 0000000..2139b6f --- /dev/null +++ b/Documentation/git-tar-tree.txt @@ -0,0 +1,38 @@ +git-tar-tree(1) +=============== + +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 0000000..213dc81 --- /dev/null +++ b/Documentation/git-unpack-file.txt @@ -0,0 +1,36 @@ +git-unpack-file(1) +================== + +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 0000000..31ea34d --- /dev/null +++ b/Documentation/git-unpack-objects.txt @@ -0,0 +1,42 @@ +git-unpack-objects(1) +===================== + +NAME +---- +git-unpack-objects - Unpack objects from a packed archive. + + +SYNOPSIS +-------- +'git-unpack-objects' [-n] [-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 +------- +-n:: + Only list the objects that would be unpacked, don't actually unpack + them. + +-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 0000000..c74311d --- /dev/null +++ b/Documentation/git-update-index.txt @@ -0,0 +1,233 @@ +git-update-index(1) +=================== + +NAME +---- +git-update-index - Modifies the index or directory cache + + +SYNOPSIS +-------- +'git-update-index' + [--add] [--remove | --force-remove] [--replace] + [--refresh [-q] [--unmerged] [--ignore-missing]] + [--cacheinfo <mode> <object> <file>]\* + [--chmod=(+|-)x] + [--info-only] [--index-info] + [-z] [--stdin] + [--verbose] + [--] [<file>]\* + +DESCRIPTION +----------- +Modifies the index or directory cache. Each file mentioned is updated +into the index 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 index already then it's + added. + Default behaviour is to ignore new files. + +--remove:: + If a specified file is in the index but is missing then it's + removed. + Default behaviour is to ignore removed file. + +--refresh:: + Looks at the current index and checks to see if merges or + updates are needed by checking stat() information. + +-q:: + Quiet. If --refresh finds that the index needs an update, the + default behavior is to error out. This option makes + git-update-index continue anyway. + +--unmerged:: + If --refresh finds unmerged changes in the index, the default + behavior is to error out. This option makes git-update-index + continue anyway. + +--ignore-missing:: + Ignores missing files during a --refresh + +--cacheinfo <mode> <object> <path>:: + Directly insert the specified info into the index. + +--index-info:: + Read index information from stdin. + +--chmod=(+|-)x:: + Set the execute permissions on the updated files. + +--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 index. + +--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. + +--stdin:: + Instead of taking list of paths from the command line, + read list of paths from the standard input. Paths are + separated by LF (i.e. one path per line) by default. + +--verbose:: + Report what is being added and removed from index. + +-z:: + Only meaningful with `--stdin`; paths are separated with + NUL character instead of LF. + +--:: + Do not interpret any more arguments as options. + +<file>:: + Files to act on. + Note that files beginning 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 index +up-to-date for mode/content changes. But what it *does* do is to +"re-match" the stat information of a file with the index, so that you +can refresh the index 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 index 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. + + +Using --index-info +------------------ + +`--index-info` is a more powerful mechanism that lets you feed +multiple entry definitions from the standard input, and designed +specifically for scripts. It can take inputs of three formats: + + . mode SP sha1 TAB path ++ +The first format is what "git-apply --index-info" +reports, and used to reconstruct a partial tree +that is used for phony merge base tree when falling +back on 3-way merge. + + . mode SP type SP sha1 TAB path ++ +The second format is to stuff git-ls-tree output +into the index file. + + . mode SP sha1 SP stage TAB path ++ +This format is to put higher order stages into the +index file and matches git-ls-files --stage output. + +To place a higher stage entry to the index, the path should +first be removed by feeding a mode=0 entry for the path, and +then feeding necessary input lines in the third format. + +For example, starting with this index: + +------------ +$ git ls-files -s +100644 8a1218a1024a212bb3db30becd860315f9f3ac52 0 frotz +------------ + +you can feed the following input to `--index-info`: + +------------ +$ git update-index --index-info +0 0000000000000000000000000000000000000000 frotz +100644 8a1218a1024a212bb3db30becd860315f9f3ac52 1 frotz +100755 8a1218a1024a212bb3db30becd860315f9f3ac52 2 frotz +------------ + +The first line of the input feeds 0 as the mode to remove the +path; the SHA1 does not matter as long as it is well formatted. +Then the second and third line feeds stage 1 and stage 2 entries +for that path. After the above, we would end up with this: + +------------ +$ git ls-files -s +100644 8a1218a1024a212bb3db30becd860315f9f3ac52 1 frotz +100755 8a1218a1024a212bb3db30becd860315f9f3ac52 2 frotz +------------ + + +Examples +-------- +To update and refresh only the files already checked out: + +---------------- +$ git-checkout-index -n -f -a && git-update-index --ignore-missing --refresh +---------------- + + +Configuration +------------- + +The command honors `core.filemode` configuration variable. If +your repository is on an filesystem whose executable bits are +unreliable, this should be set to 'false' (see gitlink:git-repo-config[1]). +This causes the command to ignore differences in file modes recorded +in the index and the file mode on the filesystem if they differ only on +executable bit. On such an unfortunate filesystem, you may +need to use `git-update-index --chmod=`. + + +See Also +-------- +gitlink:git-repo-config[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-update-ref.txt b/Documentation/git-update-ref.txt new file mode 100644 index 0000000..69715aa --- /dev/null +++ b/Documentation/git-update-ref.txt @@ -0,0 +1,58 @@ +git-update-ref(1) +================= + +NAME +---- +git-update-ref - update the object name stored in a ref safely + +SYNOPSIS +-------- +`git-update-ref` <ref> <newvalue> [<oldvalue>] + +DESCRIPTION +----------- +Given two arguments, stores the <newvalue> in the <ref>, possibly +dereferencing the symbolic refs. E.g. `git-update-ref HEAD +<newvalue>` updates the current branch head to the new object. + +Given three arguments, stores the <newvalue> in the <ref>, +possibly dereferencing the symbolic refs, after verifying that +the current value of the <ref> matches <oldvalue>. +E.g. `git-update-ref refs/heads/master <newvalue> <oldvalue>` +updates the master branch head to <newvalue> only if its current +value is <oldvalue>. + +It also allows a "ref" file to be a symbolic pointer to another +ref file by starting with the four-byte header sequence of +"ref:". + +More importantly, it allows the update of a ref file to follow +these symbolic pointers, whether they are symlinks or these +"regular file symbolic refs". It follows *real* symlinks only +if they start with "refs/": otherwise it will just try to read +them and update them as a regular file (i.e. it will allow the +filesystem to follow them, but will overwrite such a symlink to +somewhere else with a regular filename). + +In general, using + + git-update-ref HEAD "$head" + +should be a _lot_ safer than doing + + echo "$head" > "$GIT_DIR/HEAD" + +both from a symlink following standpoint *and* an error checking +standpoint. The "refs/" rule for symlinks means that symlinks +that point to "outside" the tree are safe: they'll be followed +for reading but not for writing (so we'll never write through a +ref symlink to some other tree, if you have copied a whole +archive by creating a symlink tree). + +Author +------ +Written by Linus Torvalds <torvalds@osdl.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 0000000..88a03c7 --- /dev/null +++ b/Documentation/git-update-server-info.txt @@ -0,0 +1,58 @@ +git-update-server-info(1) +========================= + +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 must +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. This command +generates such auxiliary files. + + +OPTIONS +------- + +-f|--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 0000000..3d8f8ef --- /dev/null +++ b/Documentation/git-upload-pack.txt @@ -0,0 +1,39 @@ +git-upload-pack(1) +================== + +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 0000000..c22d34f --- /dev/null +++ b/Documentation/git-var.txt @@ -0,0 +1,61 @@ +git-var(1) +========== + +NAME +---- +git-var - Print the git users identity + + +SYNOPSIS +-------- +git-var [ -l | <variable> ] + +DESCRIPTION +----------- +Prints a git logical variable. + +OPTIONS +------- +-l:: + Cause 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 0000000..d032280 --- /dev/null +++ b/Documentation/git-verify-pack.txt @@ -0,0 +1,54 @@ +git-verify-pack(1) +================== + +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. +--:: + Do not interpret any more arguments as options. + +OUTPUT FORMAT +------------- +When specifying the -v option 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 0000000..b8a73c4 --- /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 0000000..6c150b0 --- /dev/null +++ b/Documentation/git-whatchanged.txt @@ -0,0 +1,81 @@ +git-whatchanged(1) +================== + +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'. + +-m:: + By default, differences for merge commits are not shown. + With this flag, show differences to that commit from all + of its parents. + + However, it is not very useful in general, although it + *is* useful on a file-by-file basis. + +Examples +-------- +git-whatchanged -p v2.6.12.. include/scsi drivers/scsi:: + + Show as patches the commits since version 'v2.6.12' that changed + any file in the include/scsi or drivers/scsi subdirectories + +git-whatchanged --since="2 weeks ago" -- gitk:: + + Show the changes during the last two weeks to the file 'gitk'. + The "--" is necessary to avoid confusion with the *branch* named + 'gitk' + + +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 0000000..77e12cb --- /dev/null +++ b/Documentation/git-write-tree.txt @@ -0,0 +1,44 @@ +git-write-tree(1) +================= + +NAME +---- +git-write-tree - Creates a tree object from the current index + + +SYNOPSIS +-------- +'git-write-tree' [--missing-ok] + +DESCRIPTION +----------- +Creates a tree object using the current index. + +The index must be in a fully merged state. + +Conceptually, `git-write-tree` sync()s the current index 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 0000000..2d0ca9d --- /dev/null +++ b/Documentation/git.txt @@ -0,0 +1,610 @@ +git(7) +====== + +NAME +---- +git - the stupid content tracker + + +SYNOPSIS +-------- +'git' [--version] [--exec-path[=GIT_EXEC_PATH]] [--help] COMMAND [ARGS] + +DESCRIPTION +----------- +'git' is both a program and a directory content tracker system. +The program 'git' is just a wrapper to reach the core git programs +(or a potty if you like, as it's not exactly porcelain but still +brings your stuff to the plumbing). + +OPTIONS +------- +--version:: + prints the git suite version that the 'git' program came from. + +--help:: + prints the synopsis and a list of available commands. + If a git command is named this option will bring up the + man-page for that command. + +--exec-path:: + path to wherever your core git programs are installed. + This can also be controlled by setting the GIT_EXEC_PATH + environment variable. If no path is given 'git' will print + the current setting and then exit. + + +NOT LEARNING CORE GIT COMMANDS +------------------------------ + +This manual is intended to give complete background information +and internal workings of git, which may be too much for most +people. The <<Discussion>> section below contains much useful +definition and clarification - read that first. + +If you are interested in using git to manage (version control) +projects, use link:tutorial.html[The Tutorial] to get you started, +and then link:everyday.html[Everyday GIT] as a guide to the +minimum set of commands you need to know for day-to-day work. +Most likely, that will get you started, and you can go a long +way without knowing the low level details too much. + +The link:core-tutorial.html[Core tutorial] document covers how things +internally work. + +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. + + +CORE GIT COMMANDS +----------------- + +If you are writing your own Porcelain, you need to be familiar +with most of the low level commands --- I suggest starting from +gitlink:git-update-index[1] and gitlink:git-read-tree[1]. + + +Commands Overview +----------------- +The git commands can helpfully be split into those that manipulate +the repository, the index and the files in the working tree, 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 index to the working tree. + +gitlink:git-commit-tree[1]:: + Creates a new commit object. + +gitlink:git-hash-object[1]:: + Computes the object ID from a file. + +gitlink:git-index-pack[1]:: + Build pack idx file for an existing packed archive. + +gitlink:git-init-db[1]:: + Creates an empty git object database, or reinitialize an + existing one. + +gitlink:git-merge-index[1]:: + Runs a merge for files needing merging. + +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 index. + +gitlink:git-repo-config[1]:: + Get and set options in .git/config. + +gitlink:git-unpack-objects[1]:: + Unpacks objects out of a packed archive. + +gitlink:git-update-index[1]:: + Registers files in the working tree to the index. + +gitlink:git-write-tree[1]:: + Creates a tree from the index. + + +Interrogation commands +~~~~~~~~~~~~~~~~~~~~~~ + +gitlink:git-cat-file[1]:: + Provide content or type/size information for repository objects. + +gitlink:git-describe[1]:: + Show the most recent tag that is reachable from a commit. + +gitlink:git-diff-index[1]:: + Compares content and mode of blobs between the index and repository. + +gitlink:git-diff-files[1]:: + Compares files in the working tree and the index. + +gitlink:git-diff-stages[1]:: + Compares two "merge stages" in the index. + +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. + +gitlink:git-ls-files[1]:: + Information about files in the index and the working tree. + +gitlink:git-ls-tree[1]:: + Displays a tree object in human readable form. + +gitlink:git-merge-base[1]:: + Finds as good common ancestors as possible for a merge. + +gitlink:git-name-rev[1]:: + Find symbolic names for given revs. + +gitlink:git-pack-redundant[1]:: + Find redundant pack files. + +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 object. + +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. + +In general, the interrogate commands do not touch the files in +the working tree. + + +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 (engine for ssh and + local transport). + +gitlink:git-http-fetch[1]:: + Downloads a remote git repository via HTTP by walking + commit chain. + +gitlink:git-local-fetch[1]:: + Duplicates another git repository on a local system by + walking commit chain. + +gitlink:git-peek-remote[1]:: + Lists references on a remote repository using + upload-pack protocol (engine for ssh and local + transport). + +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-http-push[1]:: + Push missing objects using HTTP/DAV. + +gitlink:git-shell[1]:: + Restricted shell for GIT-only SSH access. + +gitlink:git-ssh-fetch[1]:: + Pulls from a remote repository over ssh connection by + walking commit chain. + +gitlink:git-ssh-upload[1]:: + Helper "server-side" program used by git-ssh-fetch. + +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. + +gitlink:git-am[1]:: + Apply patches from a mailbox, but cooler. + +gitlink:git-applymbox[1]:: + Apply patches from a mailbox, original version by Linus. + +gitlink:git-bisect[1]:: + Find the change that introduced a bug by binary search. + +gitlink:git-branch[1]:: + Create and Show branches. + +gitlink:git-checkout[1]:: + Checkout and switch to a branch. + +gitlink:git-cherry-pick[1]:: + Cherry-pick the effect of an existing commit. + +gitlink:git-clone[1]:: + Clones a repository into a new directory. + +gitlink:git-commit[1]:: + Record changes to the repository. + +gitlink:git-diff[1]:: + Show changes between commits, commit and working tree, etc. + +gitlink:git-fetch[1]:: + Download from a remote repository via various protocols. + +gitlink:git-format-patch[1]:: + Prepare patches for e-mail submission. + +gitlink:git-grep[1]:: + Print lines matching a pattern. + +gitlink:git-log[1]:: + Shows commit logs. + +gitlink:git-ls-remote[1]:: + Shows references in a remote or local repository. + +gitlink:git-merge[1]:: + Grand unified merge driver. + +gitlink:git-mv[1]:: + Move or rename a file, a directory, or a symlink. + +gitlink:git-pull[1]:: + Fetch from and merge with a remote repository. + +gitlink:git-push[1]:: + Update remote refs along with associated objects. + +gitlink:git-rebase[1]:: + Rebase local commits to the updated upstream head. + +gitlink:git-repack[1]:: + Pack unpacked objects in a repository. + +gitlink:git-rerere[1]:: + Reuse recorded resolution of conflicted merges. + +gitlink:git-reset[1]:: + Reset current HEAD to the specified state. + +gitlink:git-resolve[1]:: + Merge two commits. + +gitlink:git-revert[1]:: + Revert an existing commit. + +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. + +gitlink:git-verify-tag[1]:: + Check the GPG signature of tag. + +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. + +gitlink:git-convert-objects[1]:: + Converts old-style git repository. + +gitlink:git-cvsimport[1]:: + Salvage your data out of another SCM people love to hate. + +gitlink:git-cvsexportcommit[1]:: + Export a single commit to a CVS checkout. + +gitlink:git-lost-found[1]:: + Recover lost refs that luckily have not yet been pruned. + +gitlink:git-merge-one-file[1]:: + The standard helper program to use with `git-merge-index`. + +gitlink:git-prune[1]:: + Prunes all unreachable objects from the object database. + +gitlink:git-relink[1]:: + Hardlink common objects in local repositories. + +gitlink:git-svnimport[1]:: + Import a SVN repository into git. + +gitlink:git-sh-setup[1]:: + Common git shell script setup code. + +gitlink:git-symbolic-ref[1]:: + Read and modify symbolic refs. + +gitlink:git-tag[1]:: + An example script to create a tag object signed with GPG. + +gitlink:git-update-ref[1]:: + Update the object name stored in a ref safely. + + +Interrogators: + +gitlink:git-check-ref-format[1]:: + Make sure ref name is well formed. + +gitlink:git-cherry[1]:: + Find commits not merged upstream. + +gitlink:git-count-objects[1]:: + Count unpacked number of objects and their disk consumption. + +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 and authorship information from a single + e-mail message, optionally transliterating the commit + message into utf-8. + +gitlink:git-mailsplit[1]:: + A stupid program to split UNIX mbox format mailbox into + individual pieces of e-mail. + +gitlink:git-patch-id[1]:: + Compute unique ID for a patch. + +gitlink:git-parse-remote[1]:: + Routines to help parsing `$GIT_DIR/remotes/` files. + +gitlink:git-request-pull[1]:: + git-request-pull. + +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. + +gitlink:git-symbolic-ref[1]:: + Read and modify symbolic refs. + +gitlink:git-stripspace[1]:: + Filter out empty lines. + + +Commands not yet documented +--------------------------- + +gitlink:gitk[1]:: + The gitk repository browser. + + +Configuration Mechanism +----------------------- + +Starting from 0.99.9 (actually mid 0.99.8.GIT), `.git/config` file +is used to hold per-repository configuration options. It is a +simple text file modelled after `.ini` format familiar to some +people. Here is an example: + +------------ +# +# A '#' or ';' character indicates a comment. +# + +; core variables +[core] + ; Don't trust file modes + filemode = false + +; user identity +[user] + name = "Junio C Hamano" + email = "junkio@twinsun.com" + +------------ + +Various commands read from the configuration file and adjust +their operation accordingly. + + +Identifier Terminology +---------------------- +<object>:: + Indicates the object name for any type of object. + +<blob>:: + Indicates a blob object name. + +<tree>:: + Indicates a tree object name. + +<commit>:: + Indicates a commit object name. + +<tree-ish>:: + Indicates a tree, commit or tag object name. 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`, or `tag`. + +<file>:: + Indicates a filename - almost 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 current branch (i.e. the + contents of `$GIT_DIR/HEAD`). + +<tag>:: + a valid tag 'name' + (i.e. the contents of `$GIT_DIR/refs/tags/<tag>`). + +<head>:: + a valid head 'name' + (i.e. the contents of `$GIT_DIR/refs/heads/<head>`). + +<snap>:: + a valid snapshot 'name' + (i.e. 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 + 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 the default `.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[] + +Authors +------- +* git's founding father is Linus Torvalds <torvalds@osdl.org>. +* The current git nurse is Junio C Hamano <junkio@cox.net>. +* The git potty was written by Andres Ericsson <ae@op5.se>. +* General upbringing is handled by the git-list <git@vger.kernel.org>. + +Documentation +-------------- +The documentation for git suite was started by David Greaves +<david@dgreaves.com>, and later enhanced greatly by the +contributors on 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 0000000..eb126d7 --- /dev/null +++ b/Documentation/gitk.txt @@ -0,0 +1,51 @@ +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. + + +Examples +-------- +gitk v2.6.12.. include/scsi drivers/scsi:: + + Show as the changes since version 'v2.6.12' that changed any + file in the include/scsi or drivers/scsi subdirectories + +gitk --since="2 weeks ago" -- gitk:: + + Show the changes during the last two weeks to the file 'gitk'. + The "--" is necessary to avoid confusion with the *branch* named + 'gitk' + +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 0000000..02a9d9c --- /dev/null +++ b/Documentation/glossary.txt @@ -0,0 +1,253 @@ +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 individual object is identified + by its object name. The objects 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 index 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 index 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 index 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/`. + +master:: + The default branch. Whenever you create a git repository, a branch + named "master" is created, and becomes the active branch. In most + cases, this contains the local development. + +origin:: + The default upstream branch. Most projects have one upstream + project which they track, and by default 'origin' is used for + that purpose. New updates from upstream will be fetched into + this branch; you should never commit to it yourself. + +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 0000000..4ad1920 --- /dev/null +++ b/Documentation/hooks.txt @@ -0,0 +1,135 @@ +Hooks used by git +================= + +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. + +The standard output of this hook is sent to /dev/null; if you +want to report something to the git-send-pack on the other end, +you can redirect your output to your stderr. + +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. + +The standard output of this hook is sent to /dev/null; if you +want to report something to the git-send-pack on the other end, +you can redirect your output to your stderr. diff --git a/Documentation/howto-index.sh b/Documentation/howto-index.sh new file mode 100755 index 0000000..34aa30c --- /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/isolate-bugs-with-bisect.txt b/Documentation/howto/isolate-bugs-with-bisect.txt new file mode 100644 index 0000000..edbcd4c --- /dev/null +++ b/Documentation/howto/isolate-bugs-with-bisect.txt @@ -0,0 +1,65 @@ +From: Linus Torvalds <torvalds () osdl ! org> +To: git@vger.kernel.org +Date: 2005-11-08 1:31:34 +Subject: Real-life kernel debugging scenario +Abstract: Short-n-sweet, Linus tells us how to leverage `git-bisect` to perform + bug isolation on a repository where "good" and "bad" revisions are known + in order to identify a suspect commit. + + +How To Use git-bisect To Isolate a Bogus Commit +=============================================== + +The way to use "git bisect" couldn't be easier. + +Figure out what the oldest bad state you know about is (that's usually the +head of "master", since that's what you just tried to boot and failed at). +Also, figure out the most recent known-good commit (usually the _previous_ +kernel you ran: and if you've only done a single "pull" in between, it +will be ORIG_HEAD). + +Then do + + git bisect start + git bisect bad master <- mark "master" as the bad state + git bisect good ORIG_HEAD <- mark ORIG_HEAD as good (or + whatever other known-good + thing you booted last) + +and at this point "git bisect" will churn for a while, and tell you what +the mid-point between those two commits are, and check that state out as +the head of the bew "bisect" branch. + +Compile and reboot. + +If it's good, just do + + git bisect good <- mark current head as good + +otherwise, reboot into a good kernel instead, and do (surprise surprise, +git really is very intuitive): + + git bisect bad <- mark current head as bad + +and whatever you do, git will select a new half-way point. Do this for a +while, until git tells you exactly which commit was the first bad commit. +That's your culprit. + +It really works wonderfully well, except for the case where there was +_another_ commit that broke something in between, like introduced some +stupid compile error. In that case you should not mark that commit good or +bad: you should try to find another commit close-by, and do a "git reset +--hard <newcommit>" to try out _that_ commit instead, and then test that +instead (and mark it good or bad). + +You can do "git bisect visualize" while you do all this to see what's +going on by starting up gitk on the bisection range. + +Finally, once you've figured out exactly which commit was bad, you can +then go back to the master branch, and try reverting just that commit: + + git checkout master + git revert <bad-commit-id> + +to verify that the top-of-kernel works with that single commit reverted. + diff --git a/Documentation/howto/make-dist.txt b/Documentation/howto/make-dist.txt new file mode 100644 index 0000000..00e330b --- /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 0000000..646c55c --- /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 + git branch -d 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 0000000..c2d4a91 --- /dev/null +++ b/Documentation/howto/rebase-from-internal-branch.txt @@ -0,0 +1,165 @@ +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 + +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 +made 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 0000000..02621b5 --- /dev/null +++ b/Documentation/howto/rebuild-from-update-hook.txt @@ -0,0 +1,87 @@ +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 $some.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 four 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. + + - The stdout of update hook script is not connected to git + push; I run the heavy part of the command inside "at", to + receive the execution report via e-mail. + + - 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 0000000..d10476b --- /dev/null +++ b/Documentation/howto/revert-branch-rebase.txt @@ -0,0 +1,200 @@ +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 branch -d 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/update-hook-example.txt b/Documentation/howto/update-hook-example.txt new file mode 100644 index 0000000..3a33696 --- /dev/null +++ b/Documentation/howto/update-hook-example.txt @@ -0,0 +1,172 @@ +From: Junio C Hamano <junkio@cox.net> and Carl Baldwin <cnb@fc.hp.com> +Subject: control access to branches. +Date: Thu, 17 Nov 2005 23:55:32 -0800 +Message-ID: <7vfypumlu3.fsf@assigned-by-dhcp.cox.net> +Abstract: An example hooks/update script is presented to + implement repository maintenance policies, such as who can push + into which branch and who can make a tag. + +When your developer runs git-push into the repository, +git-receive-pack is run (either locally or over ssh) as that +developer, so is hooks/update script. Quoting from the relevant +section of the documentation: + + 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. + +So if your policy is (1) always require fast-forward push +(i.e. never allow "git-push repo +branch:branch"), (2) you +have a list of users allowed to update each branch, and (3) you +do not let tags to be overwritten, then you can use something +like this as your hooks/update script. + +[jc: editorial note. This is a much improved version by Carl +since I posted the original outline] + +-- >8 -- beginning of script -- >8 -- + +#!/bin/bash + +umask 002 + +# If you are having trouble with this access control hook script +# you can try setting this to true. It will tell you exactly +# why a user is being allowed/denied access. + +verbose=false + +# Default shell globbing messes things up downstream +GLOBIGNORE=* + +function grant { + $verbose && echo >&2 "-Grant- $1" + echo grant + exit 0 +} + +function deny { + $verbose && echo >&2 "-Deny- $1" + echo deny + exit 1 +} + +function info { + $verbose && echo >&2 "-Info- $1" +} + +# Implement generic branch and tag policies. +# - Tags should not be updated once created. +# - Branches should only be fast-forwarded. +case "$1" in + refs/tags/*) + [ -f "$GIT_DIR/$1" ] && + deny >/dev/null "You can't overwrite an existing tag" + ;; + refs/heads/*) + # No rebasing or rewinding + if expr "$2" : '0*$' >/dev/null; then + info "The branch '$1' is new..." + else + # updating -- make sure it is a fast forward + mb=$(git-merge-base "$2" "$3") + case "$mb,$2" in + "$2,$mb") info "Update is fast-forward" ;; + *) deny >/dev/null "This is not a fast-forward update." ;; + esac + fi + ;; + *) + deny >/dev/null \ + "Branch is not under refs/heads or refs/tags. What are you trying to do?" + ;; +esac + +# Implement per-branch controls based on username +allowed_users_file=$GIT_DIR/info/allowed-users +username=$(id -u -n) +info "The user is: '$username'" + +if [ -f "$allowed_users_file" ]; then + rc=$(cat $allowed_users_file | grep -v '^#' | grep -v '^$' | + while read head_pattern user_patterns; do + matchlen=$(expr "$1" : "$head_pattern") + if [ "$matchlen" == "${#1}" ]; then + info "Found matching head pattern: '$head_pattern'" + for user_pattern in $user_patterns; do + info "Checking user: '$username' against pattern: '$user_pattern'" + matchlen=$(expr "$username" : "$user_pattern") + if [ "$matchlen" == "${#username}" ]; then + grant "Allowing user: '$username' with pattern: '$user_pattern'" + fi + done + deny "The user is not in the access list for this branch" + fi + done + ) + case "$rc" in + grant) grant >/dev/null "Granting access based on $allowed_users_file" ;; + deny) deny >/dev/null "Denying access based on $allowed_users_file" ;; + *) ;; + esac +fi + +allowed_groups_file=$GIT_DIR/info/allowed-groups +groups=$(id -G -n) +info "The user belongs to the following groups:" +info "'$groups'" + +if [ -f "$allowed_groups_file" ]; then + rc=$(cat $allowed_groups_file | grep -v '^#' | grep -v '^$' | + while read head_pattern group_patterns; do + matchlen=$(expr "$1" : "$head_pattern") + if [ "$matchlen" == "${#1}" ]; then + info "Found matching head pattern: '$head_pattern'" + for group_pattern in $group_patterns; do + for groupname in $groups; do + info "Checking group: '$groupname' against pattern: '$group_pattern'" + matchlen=$(expr "$groupname" : "$group_pattern") + if [ "$matchlen" == "${#groupname}" ]; then + grant "Allowing group: '$groupname' with pattern: '$group_pattern'" + fi + done + done + deny "None of the user's groups are in the access list for this branch" + fi + done + ) + case "$rc" in + grant) grant >/dev/null "Granting access based on $allowed_groups_file" ;; + deny) deny >/dev/null "Denying access based on $allowed_groups_file" ;; + *) ;; + esac +fi + +deny >/dev/null "There are no more rules to check. Denying access" + +-- >8 -- end of script -- >8 -- + +This uses two files, $GIT_DIR/info/allowed-users and +allowed-groups, to describe which heads can be pushed into by +whom. The format of each file would look like this: + + refs/heads/master junio + refs/heads/cogito$ pasky + refs/heads/bw/ linus + refs/heads/tmp/ * + refs/tags/v[0-9]* junio + +With this, Linus can push or create "bw/penguin" or "bw/zebra" +or "bw/panda" branches, Pasky can do only "cogito", and JC can +do master branch and make versioned tags. And anybody can do +tmp/blah branches. + +------------ diff --git a/Documentation/howto/using-topic-branches.txt b/Documentation/howto/using-topic-branches.txt new file mode 100644 index 0000000..2c98194 --- /dev/null +++ b/Documentation/howto/using-topic-branches.txt @@ -0,0 +1,296 @@ +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 1.1 + +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 by 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 git://git.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: git://git.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 merge "Auto-update from upstream" test linus + $ git checkout release && git merge "Auto-update from upstream" release linus + +Important note! If you have any local changes in these branches, then +this merge will create a commit object in the history (with no local +changes git will simply do a "Fast forward" merge). Many people dislike +the "noise" that this creates in the Linux history, so you should avoid +doing this capriciously in the "release" branch, as these noisy commits +will become part of the permanent history when you ask Linus to pull +from the release branch. + +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 merge "Pull speed-up-spinlock changes" test speed-up-spinlocks + +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 merge "Pull speed-up-spinlock changes" release speed-up-spinlocks + +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: + + $ git branch -d 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 merge "Auto-update from upstream" $1 linus + ;; +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 merge "Pull $1 into $2 branch" $2 $1 + ;; +*) + 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 0000000..50638c7 --- /dev/null +++ b/Documentation/install-webdoc.sh @@ -0,0 +1,25 @@ +#!/bin/sh + +T="$1" + +for h in *.html *.txt 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"/*.txt "$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/merge-options.txt b/Documentation/merge-options.txt new file mode 100644 index 0000000..53cc355 --- /dev/null +++ b/Documentation/merge-options.txt @@ -0,0 +1,16 @@ +-n, \--no-summary:: + Do not show diffstat at the end of the merge. + +--no-commit:: + Perform the merge but pretend the merge failed and do + not autocommit, to give the user a chance to inspect and + further tweak the merge result before committing. + + +-s <strategy>, \--strategy=<strategy>:: + Use the given merge strategy; can be supplied more than + once to specify them in the order they should be tried. + If there is no `-s` option, a built-in list of strategies + is used instead (`git-merge-recursive` when merging a single + head, `git-merge-octopus` otherwise). + diff --git a/Documentation/merge-strategies.txt b/Documentation/merge-strategies.txt new file mode 100644 index 0000000..7df0266 --- /dev/null +++ b/Documentation/merge-strategies.txt @@ -0,0 +1,35 @@ +MERGE STRATEGIES +---------------- + +resolve:: + This can only resolve two heads (i.e. the current branch + and another branch you pulled from) using 3-way merge + algorithm. It tries to carefully detect criss-cross + merge ambiguities and is considered generally safe and + fast. + +recursive:: + This can only resolve two heads using 3-way merge + algorithm. When there are more than one common + ancestors that can be used for 3-way merge, it creates a + merged tree of the common ancestors and uses that as + the reference tree for the 3-way merge. This has been + reported to result in fewer merge conflicts without + causing mis-merges by tests done on actual merge commits + taken from Linux 2.6 kernel development history. + Additionally this can detect and handle merges involving + renames. This is the default merge strategy when + pulling or merging one branch. + +octopus:: + This resolves more than two-head case, but refuses to do + complex merge that needs manual resolution. It is + primarily meant to be used for bundling topic branch + heads together. This is the default merge strategy when + pulling or merging more than one branches. + +ours:: + This resolves any number of heads, but the result of the + merge is always the current branch head. It is meant to + be used to supersede old development history of side + branches. diff --git a/Documentation/pull-fetch-param.txt b/Documentation/pull-fetch-param.txt new file mode 100644 index 0000000..e852f41 --- /dev/null +++ b/Documentation/pull-fetch-param.txt @@ -0,0 +1,69 @@ +<repository>:: + The "remote" repository that is the source of a fetch + or pull operation. See the section <<URLS,GIT URLS>> below. + +<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. ++ +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. ++ +[NOTE] +If the remote branch from which you want to pull is +modified in non-linear ways such as being rewound and +rebased frequently, then a pull will attempt a merge with +an older version of itself, likely conflict, and fail. +It is under these conditions that you would want to use +the `+` sign to indicate non-fast-forward updates will +be needed. There is currently no easy way to determine +or declare that a branch will be made available in a +repository with this behavior; the pulling user simply +must know this is the expected usage pattern for a branch. ++ +[NOTE] +You never do your own development on branches that appear +on the right hand side of a <refspec> colon on `Pull:` lines; +they are to be updated by `git-fetch`. If you intend to do +development derived from a remote branch `B`, have a `Pull:` +line to track it (i.e. `Pull: B:remote-B`), and have a separate +branch `my-B` to do your development on top of it. The latter +is created by `git branch my-B remote-B` (or its equivalent `git +checkout -b my-B remote-B`). Run `git fetch` to keep track of +the progress of the remote side, and when you see something new +on the remote branch, merge it into your development branch with +`git pull . remote-B`, while you are on `my-B` branch. +The common `Pull: master:origin` mapping of a remote `master` +branch to a local `origin` branch, which is then merged to a +local development branch, again typically named `master`, is made +when you run `git clone` for you to follow this pattern. ++ +[NOTE] +There is a difference between listing multiple <refspec> +directly on `git-pull` command line and having multiple +`Pull:` <refspec> lines for a <repository> and running +`git-pull` command without any explicit <refspec> parameters. +<refspec> listed explicitly on the command line are always +merged into the current branch after fetching. In other words, +if you list more than one remote refs, you would be making +an Octopus. While `git-pull` run without any explicit <refspec> +parameter takes default <refspec>s from `Pull:` lines, it +merges only the first <refspec> found into the current branch, +after fetching all the remote refs. This is because making an +Octopus from remote refs is rarely done, while keeping track +of multiple remote heads in one-go by fetching more than one +is often useful. ++ +Some short-cut notations are also supported. ++ +* `tag <tag>` means the same as `refs/tags/<tag>:refs/tags/<tag>`; + it requests fetching everything up to the given tag. +* A parameter <ref> without a colon is equivalent to + <ref>: when pulling/fetching, so it merges <ref> into the current + branch without storing the remote branch anywhere locally diff --git a/Documentation/repository-layout.txt b/Documentation/repository-layout.txt new file mode 100644 index 0000000..1f19bf8 --- /dev/null +++ b/Documentation/repository-layout.txt @@ -0,0 +1,128 @@ +git repository layout +===================== + +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 'bare' 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 incomplete 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. a 'bare' 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 bare 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 achieve 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 0000000..e57dc78 --- /dev/null +++ b/Documentation/sort_glossary.pl @@ -0,0 +1,69 @@ +#!/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 +============ + +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/pack-protocol.txt b/Documentation/technical/pack-protocol.txt new file mode 100644 index 0000000..9cd48b4 --- /dev/null +++ b/Documentation/technical/pack-protocol.txt @@ -0,0 +1,41 @@ +Pack transfer protocols +======================= + +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/technical/trivial-merge.txt b/Documentation/technical/trivial-merge.txt new file mode 100644 index 0000000..24c8410 --- /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 0000000..66680d7 --- /dev/null +++ b/Documentation/tutorial.txt @@ -0,0 +1,404 @@ +A tutorial introduction to git +============================== + +This tutorial explains how to import a new project into git, make +changes to it, and share changes with other developers. + +First, note that you can get documentation for a command such as "git +diff" with: + +------------------------------------------------ +$ man git-diff +------------------------------------------------ + +Importing a new project +----------------------- + +Assume you have a tarball project.tar.gz with your initial work. You +can place it under git revision control as follows. + +------------------------------------------------ +$ tar xzf project.tar.gz +$ cd project +$ git init-db +------------------------------------------------ + +Git will reply + +------------------------------------------------ +defaulting to local storage area +------------------------------------------------ + +You've now initialized the working directory--you may notice a new +directory created, named ".git". Tell git that you want it to track +every file under the current directory with + +------------------------------------------------ +$ git add . +------------------------------------------------ + +Finally, + +------------------------------------------------ +$ git commit -a +------------------------------------------------ + +will prompt you for a commit message, then record the current state +of all the files to the repository. + +Try modifying some files, then run + +------------------------------------------------ +$ git diff +------------------------------------------------ + +to review your changes. When you're done, + +------------------------------------------------ +$ git commit -a +------------------------------------------------ + +will again prompt your for a message describing the change, and then +record the new versions of the modified files. + +A note on commit messages: Though not required, it's a good idea to +begin the commit message with a single short (less than 50 character) +line summarizing the change, followed by a blank line and then a more +thorough description. Tools that turn commits into email, for +example, use the first line on the Subject line and the rest of the +commit in the body. + +To add a new file, first create the file, then + +------------------------------------------------ +$ git add path/to/new/file +------------------------------------------------ + +then commit as usual. No special command is required when removing a +file; just remove it, then commit. + +At any point you can view the history of your changes using + +------------------------------------------------ +$ git whatchanged +------------------------------------------------ + +If you also want to see complete diffs at each step, use + +------------------------------------------------ +$ git whatchanged -p +------------------------------------------------ + +Managing branches +----------------- + +A single git repository can maintain multiple branches of +development. To create a new branch named "experimental", use + +------------------------------------------------ +$ git branch experimental +------------------------------------------------ + +If you now run + +------------------------------------------------ +$ git branch +------------------------------------------------ + +you'll get a list of all existing branches: + +------------------------------------------------ + experimental +* master +------------------------------------------------ + +The "experimental" branch is the one you just created, and the +"master" branch is a default branch that was created for you +automatically. The asterisk marks the branch you are currently on; +type + +------------------------------------------------ +$ git checkout experimental +------------------------------------------------ + +to switch to the experimental branch. Now edit a file, commit the +change, and switch back to the master branch: + +------------------------------------------------ +(edit file) +$ git commit -a +$ git checkout master +------------------------------------------------ + +Check that the change you made is no longer visible, since it was +made on the experimental branch and you're back on the master branch. + +You can make a different change on the master branch: + +------------------------------------------------ +(edit file) +$ git commit -a +------------------------------------------------ + +at this point the two branches have diverged, with different changes +made in each. To merge the changes made in the two branches, run + +------------------------------------------------ +$ git pull . experimental +------------------------------------------------ + +If the changes don't conflict, you're done. If there are conflicts, +markers will be left in the problematic files showing the conflict; + +------------------------------------------------ +$ git diff +------------------------------------------------ + +will show this. Once you've edited the files to resolve the +conflicts, + +------------------------------------------------ +$ git commit -a +------------------------------------------------ + +will commit the result of the merge. Finally, + +------------------------------------------------ +$ gitk +------------------------------------------------ + +will show a nice graphical representation of the resulting history. + +If you develop on a branch crazy-idea, then regret it, you can always +delete the branch with + +------------------------------------- +$ git branch -D crazy-idea +------------------------------------- + +Branches are cheap and easy, so this is a good way to try something +out. + +Using git for collaboration +--------------------------- + +Suppose that Alice has started a new project with a git repository in +/home/alice/project, and that Bob, who has a home directory on the +same machine, wants to contribute. + +Bob begins with: + +------------------------------------------------ +$ git clone /home/alice/project myrepo +------------------------------------------------ + +This creates a new directory "myrepo" containing a clone of Alice's +repository. The clone is on an equal footing with the original +project, posessing its own copy of the original project's history. + +Bob then makes some changes and commits them: + +------------------------------------------------ +(edit files) +$ git commit -a +(repeat as necessary) +------------------------------------------------ + +When he's ready, he tells Alice to pull changes from the repository +at /home/bob/myrepo. She does this with: + +------------------------------------------------ +$ cd /home/alice/project +$ git pull /home/bob/myrepo +------------------------------------------------ + +This actually pulls changes from the branch in Bob's repository named +"master". Alice could request a different branch by adding the name +of the branch to the end of the git pull command line. + +This merges Bob's changes into her repository; "git whatchanged" will +now show the new commits. If Alice has made her own changes in the +meantime, then Bob's changes will be merged in, and she will need to +manually fix any conflicts. + +A more cautious Alice might wish to examine Bob's changes before +pulling them. She can do this by creating a temporary branch just +for the purpose of studying Bob's changes: + +------------------------------------- +$ git fetch /home/bob/myrepo master:bob-incoming +------------------------------------- + +which fetches the changes from Bob's master branch into a new branch +named bob-incoming. (Unlike git pull, git fetch just fetches a copy +of Bob's line of development without doing any merging). Then + +------------------------------------- +$ git whatchanged -p master..bob-incoming +------------------------------------- + +shows a list of all the changes that Bob made since he branched from +Alice's master branch. + +After examing those changes, and possibly fixing things, Alice can +pull the changes into her master branch: + +------------------------------------- +$ git checkout master +$ git pull . bob-incoming +------------------------------------- + +The last command is a pull from the "bob-incoming" branch in Alice's +own repository. + +Later, Bob can update his repo with Alice's latest changes using + +------------------------------------- +$ git pull +------------------------------------- + +Note that he doesn't need to give the path to Alice's repository; +when Bob cloned Alice's repository, git stored the location of her +repository in the file .git/remotes/origin, and that location is used +as the default for pulls. + +Bob may also notice a branch in his repository that he didn't create: + +------------------------------------- +$ git branch +* master + origin +------------------------------------- + +The "origin" branch, which was created automatically by "git clone", +is a pristine copy of Alice's master branch; Bob should never commit +to it. + +If Bob later decides to work from a different host, he can still +perform clones and pulls using the ssh protocol: + +------------------------------------- +$ git clone alice.org:/home/alice/project myrepo +------------------------------------- + +Alternatively, git has a native protocol, or can use rsync or http; +see gitlink:git-pull[1] for details. + +Git can also be used in a CVS-like mode, with a central repository +that various users push changes to; see gitlink:git-push[1] and +link:cvs-migration.html[git for CVS users]. + +Keeping track of history +------------------------ + +Git history is represented as a series of interrelated commits. The +most recent commit in the currently checked-out branch can always be +referred to as HEAD, and the "parent" of any commit can always be +referred to by appending a caret, "^", to the end of the name of the +commit. So, for example, + +------------------------------------- +git diff HEAD^ HEAD +------------------------------------- + +shows the difference between the most-recently checked-in state of +the tree and the previous state, and + +------------------------------------- +git diff HEAD^^ HEAD^ +------------------------------------- + +shows the difference between that previous state and the state two +commits ago. Also, HEAD~5 can be used as a shorthand for HEAD^^^^^, +and more generally HEAD~n can refer to the nth previous commit. +Commits representing merges have more than one parent, and you can +specify which parent to follow in that case; see +gitlink:git-rev-parse[1]. + +The name of a branch can also be used to refer to the most recent +commit on that branch; so you can also say things like + +------------------------------------- +git diff HEAD experimental +------------------------------------- + +to see the difference between the most-recently committed tree in +the current branch and the most-recently committed tree in the +experimental branch. + +But you may find it more useful to see the list of commits made in +the experimental branch but not in the current branch, and + +------------------------------------- +git whatchanged HEAD..experimental +------------------------------------- + +will do that, just as + +------------------------------------- +git whatchanged experimental..HEAD +------------------------------------- + +will show the list of commits made on the HEAD but not included in +experimental. + +You can also give commits convenient names of your own: after running + +------------------------------------- +$ git-tag v2.5 HEAD^^ +------------------------------------- + +you can refer to HEAD^^ by the name "v2.5". If you intend to share +this name with other people (for example, to identify a release +version), you should create a "tag" object, and perhaps sign it; see +gitlink:git-tag[1] for details. + +You can revisit the old state of a tree, and make further +modifications if you wish, using git branch: the command + +------------------------------------- +$ git branch stable-release v2.5 +------------------------------------- + +will create a new branch named "stable-release" starting from the +commit which you tagged with the name v2.5. + +You can reset the state of any branch to an earlier commit at any +time with + +------------------------------------- +$ git reset --hard v2.5 +------------------------------------- + +This will remove all later commits from this branch and reset the +working tree to the state it had when the given commit was made. If +this branch is the only branch containing the later commits, those +later changes will be lost. Don't use "git reset" on a +publicly-visible branch that other developers pull from, as git will +be confused by history that disappears in this way. + +Next Steps +---------- + +Some good commands to explore next: + + * gitlink:git-diff[1]: This flexible command does much more than + we've seen in the few examples above. + + * gitlink:git-format-patch[1], gitlink:git-am[1]: These convert + series of git commits into emailed patches, and vice versa, + useful for projects such as the linux kernel which rely heavily + on emailed patches. + + * gitlink:git-bisect[1]: When there is a regression in your + project, one way to track down the bug is by searching through + the history to find the exact commit that's to blame. Git bisect + can help you perform a binary search for that commit. It is + smart enough to perform a close-to-optimal search even in the + case of complex non-linear history with lots of merged branches. + +Other good starting points include link:everyday.html[Everday GIT +with 20 Commands Or So] and link:cvs-migration.html[git for CVS +users]. Also, link:core-tutorial.html[A short git tutorial] gives an +introduction to lower-level git commands for advanced users and +developers. diff --git a/Documentation/urls.txt b/Documentation/urls.txt new file mode 100644 index 0000000..7477413 --- /dev/null +++ b/Documentation/urls.txt @@ -0,0 +1,68 @@ +GIT URLS[[URLS]] +---------------- + +One of the following notations can be used +to name the remote repository: + +=============================================================== +- rsync://host.xz/path/to/repo.git/ +- http://host.xz/path/to/repo.git/ +- https://host.xz/path/to/repo.git/ +- git://host.xz/path/to/repo.git/ +- git://host.xz/~user/path/to/repo.git/ +- ssh://host.xz/path/to/repo.git/ +- ssh://host.xz/~user/path/to/repo.git/ +- ssh://host.xz/~/path/to/repo.git +=============================================================== + +SSH Is the default transport protocol and also supports an +scp-like syntax. Both syntaxes support username expansion, +as does the native git protocol. The following three are +identical to the last three above, respectively: + +=============================================================== +- host.xz:/path/to/repo.git/ +- host.xz:~user/path/to/repo.git/ +- host.xz:path/to/repo.git +=============================================================== + +To sync with a local directory, use: + +=============================================================== +- /path/to/repo.git/ +=============================================================== + +REMOTES +------- + +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> + +Then 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`/`git-pull`, +respectively. Multiple `Push:` and and `Pull:` lines may +be specified for additional branch mappings. + +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> |