diff options
Diffstat (limited to 'Documentation')
78 files changed, 7340 insertions, 0 deletions
diff --git a/Documentation/Makefile b/Documentation/Makefile new file mode 100644 index 0000000000..7fad5ba0e9 --- /dev/null +++ b/Documentation/Makefile @@ -0,0 +1,61 @@ +MAN1_TXT=$(wildcard git-*.txt) +MAN7_TXT=git.txt + +DOC_HTML=$(patsubst %.txt,%.html,$(MAN1_TXT) $(MAN7_TXT)) glossary.html + +DOC_MAN1=$(patsubst %.txt,%.1,$(MAN1_TXT)) +DOC_MAN7=$(patsubst %.txt,%.7,$(MAN7_TXT)) + +prefix=$(HOME) +bin=$(prefix)/bin +mandir=$(prefix)/man +man1=$(mandir)/man1 +man7=$(mandir)/man7 +# DESTDIR= + +INSTALL=install + +# +# Please note that there is a minor bug in asciidoc. +# The version after 6.0.3 _will_ include the patch found here: +# http://marc.theaimsgroup.com/?l=git&m=111558757202243&w=2 +# +# Until that version is released you may have to apply the patch +# yourself - yes, all 6 characters of it! +# + +all: html man + +html: $(DOC_HTML) + + +man: man1 man7 +man1: $(DOC_MAN1) +man7: $(DOC_MAN7) + +install: + $(INSTALL) -m755 -d $(DESTDIR)/$(man1) $(DESTDIR)/$(man7) + $(INSTALL) $(DOC_MAN1) $(DESTDIR)/$(man1) + $(INSTALL) $(DOC_MAN7) $(DESTDIR)/$(man7) + +# 'include' dependencies +git-diff-%.txt: diff-format.txt diff-options.txt + touch $@ + +clean: + rm -f *.xml *.html *.1 *.7 + +%.html : %.txt + asciidoc -b xhtml11 -d manpage $< + +%.1 %.7 : %.xml + xmlto man $< + +%.xml : %.txt + asciidoc -b docbook -d manpage $< + +glossary.html : glossary.txt sort_glossary.pl + cat $< | \ + perl sort_glossary.pl | \ + asciidoc -b xhtml11 - > glossary.html + diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches new file mode 100644 index 0000000000..6121e902ae --- /dev/null +++ b/Documentation/SubmittingPatches @@ -0,0 +1,130 @@ +I started reading over the SubmittingPatches document for Linux +kernel, primarily because I wanted to have a document similar to +it for the core GIT to make sure people understand what they are +doing when they write "Signed-off-by" line. + +But the patch submission requirements are a lot more relaxed +here, because the core GIT is thousand times smaller ;-). So +here is only the relevant bits. + + +(1) Make separate commits for logically separate changes. + +Unless your patch is really trivial, you should not be sending +out a patch that was generated between your working tree and +your commit head. Instead, always make a commit with complete +commit message and generate a series of patches from your +repository. It is a good discipline. + +Describe the technical detail of the change(s). + +If your description starts to get long, that's a sign that you +probably need to split up your commit to finer grained pieces. + + +(2) Generate your patch using git/cogito out of your commits. + +git diff tools generate unidiff which is the preferred format. +You do not have to be afraid to use -M option to "git diff" or +"git format-patch", if your patch involves file renames. The +receiving end can handle them just fine. + +Please make sure your patch does not include any extra files +which do not belong in a patch submission. Make sure to review +your patch after generating it, to ensure accuracy. Before +sending out, please make sure it cleanly applies to the "master" +branch head. + + +(3) Sending your patches. + +People on the git mailing list needs to be able to read and +comment on the changes you are submitting. It is important for +a developer to be able to "quote" your changes, using standard +e-mail tools, so that they may comment on specific portions of +your code. For this reason, all patches should be submitting +e-mail "inline". WARNING: Be wary of your MUAs word-wrap +corrupting your patch. Do not cut-n-paste your patch. + +It is common convention to prefix your subject line with +[PATCH]. This lets people easily distinguish patches from other +e-mail discussions. + +"git format-patch" command follows the best current practice to +format the body of an e-mail message. At the beginning of the +patch should come your commit message, ending with the +Signed-off-by: lines, and a line that consists of three dashes, +followed by the diffstat information and the patch itself. If +you are forwarding a patch from somebody else, optionally, at +the beginning of the e-mail message just before the commit +message starts, you can put a "From: " line to name that person. + +You often want to add additional explanation about the patch, +other than the commit message itself. Place such "cover letter" +material between the three dash lines and the diffstat. + +Do not attach the patch as a MIME attachment, compressed or not. +Do not let your e-mail client send quoted-printable. Many +popular e-mail applications will not always transmit a MIME +attachment as plain text, making it impossible to comment on +your code. A MIME attachment also takes a bit more time to +process. This does not decrease the likelihood of your +MIME-attached change being accepted, but it makes it more likely +that it will be postponed. + +Exception: If your mailer is mangling patches then someone may ask +you to re-send them using MIME. + +Note that your maintainer does not subscribe to the git mailing +list (he reads it via mail-to-news gateway). If your patch is +for discussion first, send it "To:" the mailing list, and +optoinally "cc:" him. If it is trivially correct or after list +discussion reached consensus, send it "To:" the maintainer and +optionally "cc:" the list. + + +(6) Sign your work + +To improve tracking of who did what, we've borrowed the +"sign-off" procedure from the Linux kernel project on patches +that are being emailed around. Although core GIT is a lot +smaller project it is a good discipline to follow it. + +The sign-off is a simple line at the end of the explanation for +the patch, which certifies that you wrote it or otherwise have +the right to pass it on as a open-source patch. The rules are +pretty simple: if you can certify the below: + + Developer's Certificate of Origin 1.1 + + By making a contribution to this project, I certify that: + + (a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + + (b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + + (c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + + (d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. + +then you just add a line saying + + Signed-off-by: Random J Developer <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. diff --git a/Documentation/cvs-migration.txt b/Documentation/cvs-migration.txt new file mode 100644 index 0000000000..8db1409e43 --- /dev/null +++ b/Documentation/cvs-migration.txt @@ -0,0 +1,246 @@ +Git for CVS users +================= + +Ok, so you're a CVS user. That's ok, it's a treatable condition, and the +first step to recovery is admitting you have a problem. The fact that +you are reading this file means that you may be well on that path +already. + +The thing about CVS is that it absolutely sucks as a source control +manager, and you'll thus be happy with almost anything else. Git, +however, may be a bit _too_ different (read: "good") for your taste, and +does a lot of things differently. + +One particular suckage of CVS is very hard to work around: CVS is +basically a tool for tracking _file_ history, while git is a tool for +tracking _project_ history. This sometimes causes problems if you are +used to doing very strange things in CVS, in particular if you're doing +things like making branches of just a subset of the project. Git can't +track that, since git never tracks things on the level of an individual +file, only on the whole project level. + +The good news is that most people don't do that, and in fact most sane +people think it's a bug in CVS that makes it tag (and check in changes) +one file at a time. So most projects you'll ever see will use CVS +_as_if_ it was sane. In which case you'll find it very easy indeed to +move over to Git. + +First off: this is not a git tutorial. See Documentation/tutorial.txt +for how git actually works. This is more of a random collection of +gotcha's and notes on converting from CVS to git. + +Second: CVS has the notion of a "repository" as opposed to the thing +that you're actually working in (your working directory, or your +"checked out tree"). Git does not have that notion at all, and all git +working directories _are_ the repositories. However, you can easily +emulate the CVS model by having one special "global repository", which +people can synchronize with. See details later, but in the meantime +just keep in mind that with git, every checked out working tree will +have a full revision control history of its own. + + +Importing a CVS archive +----------------------- + +Ok, you have an old project, and you want to at least give git a chance +to see how it performs. The first thing you want to do (after you've +gone through the git tutorial, and generally familiarized yourself with +how to commit stuff etc in git) is to create a git'ified version of your +CVS archive. + +Happily, that's very easy indeed. Git will do it for you, although git +will need the help of a program called "cvsps": + + http://www.cobite.com/cvsps/ + +which is not actually related to git at all, but which makes CVS usage +look almost sane (ie you almost certainly want to have it even if you +decide to stay with CVS). However, git will want at _least_ version 2.1 +of cvsps (available at the address above), and in fact will currently +refuse to work with anything else. + +Once you've gotten (and installed) cvsps, you may or may not want to get +any more familiar with it, but make sure it is in your path. After that, +the magic command line is + + git cvsimport -v -d <cvsroot> -C <destination> <module> + +which will do exactly what you'd think it does: it will create a git +archive of the named CVS module. The new archive will be created in the +subdirectory named <destination>; it'll be created if it doesn't exist. +Default is the local directory. + +It can take some time to actually do the conversion for a large archive +since it involves checking out from CVS every revision of every file, +and the conversion script is reasonably chatty unless you omit the '-v' +option, but on some not very scientific tests it averaged about twenty +revisions per second, so a medium-sized project should not take more +than a couple of minutes. For larger projects or remote repositories, +the process may take longer. + +After the (initial) import is done, the CVS archive's current head +revision will be checked out -- thus, you can start adding your own +changes right away. + +The import is incremental, i.e. if you call it again next month it'll +fetch any CVS updates that have been happening in the meantime. The +cut-off is date-based, so don't change the branches that were imported +from CVS. + +You can merge those updates (or, in fact, a different CVS branch) into +your main branch: + + git resolve HEAD origin "merge with current CVS HEAD" + +The HEAD revision from CVS is named "origin", not "HEAD", because git +already uses "HEAD". (If you don't like 'origin', use cvsimport's +'-o' option to change it.) + + +Emulating CVS behaviour +----------------------- + + +So, by now you are convinced you absolutely want to work with git, but +at the same time you absolutely have to have a central repository. +Step back and think again. Okay, you still need a single central +repository? There are several ways to go about that: + +1. Designate a person responsible to pull all branches. Make the +repository of this person public, and make every team member +pull regularly from it. + +2. Set up a public repository with read/write access for every team +member. Use "git pull/push" as you used "cvs update/commit". Be +sure that your repository is up to date before pushing, just +like you used to do with "cvs commit"; your push will fail if +what you are pushing is not up to date. + +3. Make the repository of every team member public. It is the +responsibility of each single member to pull from every other +team member. + + +CVS annotate +------------ + +So, something has gone wrong, and you don't know whom to blame, and +you're an ex-CVS user and used to do "cvs annotate" to see who caused +the breakage. You're looking for the "git annotate", and it's just +claiming not to find such a script. You're annoyed. + +Yes, that's right. Core git doesn't do "annotate", although it's +technically possible, and there are at least two specialized scripts out +there that can be used to get equivalent information (see the git +mailing list archives for details). + +Git has a couple of alternatives, though, that you may find sufficient +or even superior depending on your use. One is called "git-whatchanged" +(for obvious reasons) and the other one is called "pickaxe" ("a tool for +the software archeologist"). + +The "git-whatchanged" script is a truly trivial script that can give you +a good overview of what has changed in a file or a directory (or an +arbitrary list of files or directories). The "pickaxe" support is an +additional layer that can be used to further specify exactly what you're +looking for, if you already know the specific area that changed. + +Let's step back a bit and think about the reason why you would +want to do "cvs annotate a-file.c" to begin with. + +You would use "cvs annotate" on a file when you have trouble +with a function (or even a single "if" statement in a function) +that happens to be defined in the file, which does not do what +you want it to do. And you would want to find out why it was +written that way, because you are about to modify it to suit +your needs, and at the same time you do not want to break its +current callers. For that, you are trying to find out why the +original author did things that way in the original context. + +Many times, it may be enough to see the commit log messages of +commits that touch the file in question, possibly along with the +patches themselves, like this: + + $ git-whatchanged -p a-file.c + +This will show log messages and patches for each commit that +touches a-file. + +This, however, may not be very useful when this file has many +modifications that are not related to the piece of code you are +interested in. You would see many log messages and patches that +do not have anything to do with the piece of code you are +interested in. As an example, assuming that you have this piece +of code that you are interested in in the HEAD version: + + if (frotz) { + nitfol(); + } + +you would use git-rev-list and git-diff-tree like this: + + $ git-rev-list HEAD | + git-diff-tree --stdin -v -p -S'if (frotz) { + nitfol(); + }' + +We have already talked about the "--stdin" form of git-diff-tree +command that reads the list of commits and compares each commit +with its parents. The git-whatchanged command internally runs +the equivalent of the above command, and can be used like this: + + $ git-whatchanged -p -S'if (frotz) { + nitfol(); + }' + +When the -S option is used, git-diff-tree command outputs +differences between two commits only if one tree has the +specified string in a file and the corresponding file in the +other tree does not. The above example looks for a commit that +has the "if" statement in it in a file, but its parent commit +does not have it in the same shape in the corresponding file (or +the other way around, where the parent has it and the commit +does not), and the differences between them are shown, along +with the commit message (thanks to the -v flag). It does not +show anything for commits that do not touch this "if" statement. + +Also, in the original context, the same statement might have +appeared at first in a different file and later the file was +renamed to "a-file.c". CVS annotate would not help you to go +back across such a rename, but GIT would still help you in such +a situation. For that, you can give the -C flag to +git-diff-tree, like this: + + $ git-whatchanged -p -C -S'if (frotz) { + nitfol(); + }' + +When the -C flag is used, file renames and copies are followed. +So if the "if" statement in question happens to be in "a-file.c" +in the current HEAD commit, even if the file was originally +called "o-file.c" and then renamed in an earlier commit, or if +the file was created by copying an existing "o-file.c" in an +earlier commit, you will not lose track. If the "if" statement +did not change across such a rename or copy, then the commit that +does rename or copy would not show in the output, and if the +"if" statement was modified while the file was still called +"o-file.c", it would find the commit that changed the statement +when it was in "o-file.c". + +[ BTW, the current versions of "git-diff-tree -C" is not eager + enough to find copies, and it will miss the fact that a-file.c + was created by copying o-file.c unless o-file.c was somehow + changed in the same commit.] + +You can use the --pickaxe-all flag in addition to the -S flag. +This causes the differences from all the files contained in +those two commits, not just the differences between the files +that contain this changed "if" statement: + + $ git-whatchanged -p -C -S'if (frotz) { + nitfol(); + }' --pickaxe-all + +[ Side note. This option is called "--pickaxe-all" because -S + option is internally called "pickaxe", a tool for software + archaeologists.] diff --git a/Documentation/diff-format.txt b/Documentation/diff-format.txt new file mode 100644 index 0000000000..9298d79e51 --- /dev/null +++ b/Documentation/diff-format.txt @@ -0,0 +1,135 @@ +The output format from "git-diff-cache", "git-diff-tree" and +"git-diff-files" is very similar. + +These commands all compare two sets of things; what are +compared are different: + +git-diff-cache <tree-ish>:: + compares the <tree-ish> and the files on the filesystem. + +git-diff-cache --cached <tree-ish>:: + compares the <tree-ish> and the cache. + +git-diff-tree [-r] <tree-ish-1> <tree-ish-2> [<pattern>...]:: + compares the trees named by the two arguments. + +git-diff-files [<pattern>...]:: + compares the cache and the files on the filesystem. + + +An output line is formatted this way: + +in-place edit :100644 100644 bcd1234... 0123456... M file0 +copy-edit :100644 100644 abcd123... 1234567... C68 file1 file2 +rename-edit :100644 100644 abcd123... 1234567... R86 file1 file3 +create :000000 100644 0000000... 1234567... N file4 +delete :100644 000000 1234567... 0000000... D file5 +unmerged :000000 000000 0000000... 0000000... U file6 + +That is, from the left to the right: + + (1) a colon. + (2) mode for "src"; 000000 if creation or unmerged. + (3) a space. + (4) mode for "dst"; 000000 if deletion or unmerged. + (5) a space. + (6) sha1 for "src"; 0{40} if creation or unmerged. + (7) a space. + (8) sha1 for "dst"; 0{40} if creation, unmerged or "look at work tree". + (9) a space. + (10) status, followed by optional "score" number. + (11) a tab or a NUL when '-z' option is used. + (12) path for "src" + (13) a tab or a NUL when '-z' option is used; only exists for C or R. + (14) path for "dst"; only exists for C or R. + (15) an LF or a NUL when '-z' option is used, to terminate the record. + +<sha1> is shown as all 0's if new is a file on the filesystem +and it is out of sync with the cache. Example: + + :100644 100644 5be4a4...... 000000...... M file.c + +Generating patches with -p +-------------------------- + +When "git-diff-cache", "git-diff-tree", or "git-diff-files" are run +with a '-p' option, they do not produce the output described above; +instead they produce a patch file. + +The patch generation can be customized at two levels. This +customization also applies to "git-diff-helper". + +1. When the environment variable 'GIT_EXTERNAL_DIFF' is not set, + these commands internally invoke "diff" like this: + + diff -L a/<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-cache -p $(cat .git/HEAD) + + +2. When the environment variable 'GIT_EXTERNAL_DIFF' is set, the + program named by it is called, instead of the diff invocation + described above. ++ +For a path that is added, removed, or modified, +'GIT_EXTERNAL_DIFF' is called with 7 parameters: + + path old-file old-hex old-mode new-file new-hex new-mode ++ +where: + + <old|new>-file:: are files GIT_EXTERNAL_DIFF can use to read the + contents of <old|ne>, + <old|new>-hex:: are the 40-hexdigit SHA1 hashes, + <old|new>-mode:: are the octal representation of the file modes. + ++ +The file parameters can point at the user's working file +(e.g. `new-file` in "git-diff-files"), `/dev/null` (e.g. `old-file` +when a new file is added), or a temporary file (e.g. `old-file` in the +cache). 'GIT_EXTERNAL_DIFF' should not worry about unlinking the +temporary file --- it is removed when 'GIT_EXTERNAL_DIFF' exits. + +For a path that is unmerged, 'GIT_EXTERNAL_DIFF' is called with 1 +parameter, <path>. + + +Git specific extension to diff format +------------------------------------- + +What -p option produces is slightly different from the +traditional diff format. + + (1) It is preceeded with a "git diff" header, that looks like + this: + + diff --git a/file1 b/file2 + + The a/ and b/ filenames are the same unless rename/copy is + involved. Especially, even for a creation or a deletion, + /dev/null is _not_ used in place of a/ or b/ filename. + + When rename/copy is involved, file1 and file2 shows the + name of the source file of the rename/copy and the name of + the file that rename/copy produces, respectively. + + (2) It is followed by extended header lines that are one or + more of: + + old mode <mode> + new mode <mode> + deleted file mode <mode> + new file mode <mode> + copy from <path> + copy to <path> + rename from <path> + rename to <path> + similarity index <number> + dissimilarity index <number> diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt new file mode 100644 index 0000000000..b28496e5c8 --- /dev/null +++ b/Documentation/diff-options.txt @@ -0,0 +1,53 @@ +-p:: + Generate patch (see section on generating patches) + +-u:: + Synonym for "-p". + +-r:: + Look recursively in subdirectories; this flag does not + mean anything to commands other than "git-diff-tree"; + other diff commands always look at all the subdirectories. + +-z:: + \0 line termination on output + +--name-only:: + Show only names of changed files. + +--name-only-z:: + Same as --name-only, but terminate lines with NUL. + +-B:: + Break complete rewrite changes into pairs of delete and create. + +-M:: + Detect renames. + +-C:: + Detect copies as well as renames. + +--find-copies-harder:: + By default, -C option finds copies only if the original + file of the copy was modified in the same changeset for + performance reasons. This flag makes the command + inspect unmodified files as candidates for the source of + copy. This is a very expensive operation for large + projects, so use it with caution. + +-S<string>:: + Look for differences that contains the change in <string>. + +--pickaxe-all:: + When -S finds a change, show all the changes in that + changeset, not just the files that contains the change + in <string>. + +-O<orderfile>:: + Output the patch in the order specified in the + <orderfile>, which has one shell glob pattern per line. + +-R:: + Swap two inputs; that is, show differences from cache or + on-disk file to tree contents. + diff --git a/Documentation/diffcore.txt b/Documentation/diffcore.txt new file mode 100644 index 0000000000..6c474d1c0c --- /dev/null +++ b/Documentation/diffcore.txt @@ -0,0 +1,248 @@ +Tweaking diff output +==================== +June 2005 + + +Introduction +------------ + +The diff commands git-diff-cache, git-diff-files, and +git-diff-tree can be told to manipulate differences they find +in unconventional ways before showing diff(1) output. The +manipulation is collectively called "diffcore transformation". +This short note describes what they are and how to use them to +produce diff outputs that are easier to understand than the +conventional kind. + + +The chain of operation +---------------------- + +The git-diff-* family works by first comparing two sets of +files: + + - git-diff-cache compares contents of a "tree" object and the + working directory (when --cached flag is not used) or a + "tree" object and the index file (when --cached flag is + used); + + - git-diff-files compares contents of the index file and the + working directory; + + - git-diff-tree compares contents of two "tree" objects. + +In all of these cases, the commands themselves compare +corresponding paths in the two sets of files. The result of +comparison is passed from these commands to what is internally +called "diffcore", in a format similar to what is output when +the -p option is not used. E.g. + + in-place edit :100644 100644 bcd1234... 0123456... M file0 + create :000000 100644 0000000... 1234567... N file4 + delete :100644 000000 1234567... 0000000... D file5 + unmerged :000000 000000 0000000... 0000000... U file6 + +The diffcore mechanism is fed a list of such comparison results +(each of which is called "filepair", although at this point each +of them talks about a single file), and transforms such a list +into another list. There are currently 6 such transformations: + + - diffcore-pathspec + - diffcore-break + - diffcore-rename + - diffcore-merge-broken + - diffcore-pickaxe + - diffcore-order + +These are applied in sequence. The set of filepairs git-diff-* +commands find are used as the input to diffcore-pathspec, and +the output from diffcore-pathspec is used as the input to the +next transformation. The final result is then passed to the +output routine and generates either diff-raw format (see Output +format sections of the manual for git-diff-* commands) or +diff-patch format. + + +diffcore-pathspec +----------------- + +The first transformation in the chain is diffcore-pathspec, and +is controlled by giving the pathname parameters to the +git-diff-* commands on the command line. The pathspec is used +to limit the world diff operates in. It removes the filepairs +outside the specified set of pathnames. + +Implementation note. For performance reasons, git-diff-tree +uses the pathname parameters on the command line to cull set of +filepairs it feeds the diffcore mechanism itself, and does not +use diffcore-pathspec, but the end result is the same. + + +diffcore-break +-------------- + +The second transformation in the chain is diffcore-break, and is +controlled by the -B option to the git-diff-* commands. This is +used to detect a filepair that represents "complete rewrite" and +break such filepair into two filepairs that represent delete and +create. E.g. If the input contained this filepair: + + :100644 100644 bcd1234... 0123456... M file0 + +and if it detects that the file "file0" is completely rewritten, +it changes it to: + + :100644 000000 bcd1234... 0000000... D file0 + :000000 100644 0000000... 0123456... N file0 + +For the purpose of breaking a filepair, diffcore-break examines +the extent of changes between the contents of the files before +and after modification (i.e. the contents that have "bcd1234..." +and "0123456..." as their SHA1 content ID, in the above +example). The amount of deletion of original contents and +insertion of new material are added together, and if it exceeds +the "break score", the filepair is broken into two. The break +score defaults to 50% of the size of the smaller of the original +and the result (i.e. if the edit shrinks the file, the size of +the result is used; if the edit lengthens the file, the size of +the original is used), and can be customized by giving a number +after "-B" option (e.g. "-B75" to tell it to use 75%). + + +diffcore-rename +--------------- + +This transformation is used to detect renames and copies, and is +controlled by the -M option (to detect renames) and the -C option +(to detect copies as well) to the git-diff-* commands. If the +input contained these filepairs: + + :100644 000000 0123456... 0000000... D fileX + :000000 100644 0000000... 0123456... N file0 + +and the contents of the deleted file fileX is similar enough to +the contents of the created file file0, then rename detection +merges these filepairs and creates: + + :100644 100644 0123456... 0123456... R100 fileX file0 + +When the "-C" option is used, the original contents of modified +files and contents of unchanged files are considered as +candidates of the source files in rename/copy operation, in +addition to the deleted files. If the input were like these +filepairs, that talk about a modified file fileY and a newly +created file file0: + + :100644 100644 0123456... 1234567... M fileY + :000000 100644 0000000... 0123456... N file0 + +the original contents of fileY and the resulting contents of +file0 are compared, and if they are similar enough, they are +changed to: + + :100644 100644 0123456... 1234567... M fileY + :100644 100644 0123456... 0123456... C100 fileY file0 + +In both rename and copy detection, the same "extent of changes" +algorithm used in diffcore-break is used to determine if two +files are "similar enough", and can be customized to use +similarity score different from the default 50% by giving a +number after "-M" or "-C" option (e.g. "-M8" to tell it to use +8/10 = 80%). + +Note. When the "-C" option is used with --find-copies-harder +option, git-diff-* commands feed unmodified filepairs to +diffcore mechanism as well as modified ones. This lets the copy +detector consider unmodified files as copy source candidates at +the expense of making it slower. Without --find-copies-harder, +git-diff-* commands can detect copies only if the file that was +copied happened to have been modified in the same changeset. + + +diffcore-merge-broken +--------------------- + +This transformation is used to merge filepairs broken by +diffcore-break, and were not transformed into rename/copy by +diffcore-rename, back into a single modification. This always +runs when diffcore-break is used. + +For the purpose of merging broken filepairs back, it uses a +different "extent of changes" computation from the ones used by +diffcore-break and diffcore-rename. It counts only the deletion +from the original, and does not count insertion. If you removed +only 10 lines from a 100-line document, even if you added 910 +new lines to make a new 1000-line document, you did not do a +complete rewrite. diffcore-break breaks such a case in order to +help diffcore-rename to consider such filepairs as candidate of +rename/copy detection, but if filepairs broken that way were not +matched with other filepairs to create rename/copy, then this +transformation merges them back into the original +"modification". + +The "extent of changes" parameter can be tweaked from the +default 80% (that is, unless more than 80% of the original +material is deleted, the broken pairs are merged back into a +single modification) by giving a second number to -B option, +like these: + + -B50/60 (give 50% "break score" to diffcore-break, use + 60% for diffcore-merge-broken). + -B/60 (the same as above, since diffcore-break defautls to + 50%). + +Note that earlier implementation left a broken pair as a separate +creation and deletion patches. This was unnecessary hack and +the latest implementation always merges all the broken pairs +back into modifications, but the resulting patch output is +formatted differently to still let the reviewing easier for such +a complete rewrite by showing the entire contents of old version +prefixed with '-', followed by the entire contents of new +version prefixed with '+'. + + +diffcore-pickaxe +---------------- + +This transformation is used to find filepairs that represent +changes that touch a specified string, and is controlled by the +-S option and the --pickaxe-all option to the git-diff-* +commands. + +When diffcore-pickaxe is in use, it checks if there are +filepairs whose "original" side has the specified string and +whose "result" side does not. Such a filepair represents "the +string appeared in this changeset". It also checks for the +opposite case that loses the specified string. + +When --pickaxe-all is not in effect, diffcore-pickaxe leaves +only such filepairs that touches the specified string in its +output. When --pickaxe-all is used, diffcore-pickaxe leaves all +filepairs intact if there is such a filepair, or makes the +output empty otherwise. The latter behaviour is designed to +make reviewing of the changes in the context of the whole +changeset easier. + + +diffcore-order +-------------- + +This is used to reorder the filepairs according to the user's +(or project's) taste, and is controlled by the -O option to the +git-diff-* commands. + +This takes a text file each of whose line is a shell glob +pattern. Filepairs that match a glob pattern on an earlier line +in the file are output before ones that match a later line, and +filepairs that do not match any glob pattern are output last. + +As an example, typical orderfile for the core GIT probably +should look like this: + + README + Makefile + Documentation + *.h + *.c + t + diff --git a/Documentation/git-apply-patch-script.txt b/Documentation/git-apply-patch-script.txt new file mode 100644 index 0000000000..808d3cdc1b --- /dev/null +++ b/Documentation/git-apply-patch-script.txt @@ -0,0 +1,32 @@ +git-apply-patch-script(1) +========================= +v0.99.4, May 2005 + +NAME +---- +git-apply-patch-script - Sample script to apply the diffs from git-diff-* + + +SYNOPSIS +-------- +'git-apply-patch-script' + +DESCRIPTION +----------- +This is a sample script to be used via the 'GIT_EXTERNAL_DIFF' +environment variable to apply the differences that the "git-diff-*" +family of commands report to the current work tree. + + +Author +------ +Written by Junio C Hamano <junkio@cox.net> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt new file mode 100644 index 0000000000..391d6f5c2f --- /dev/null +++ b/Documentation/git-apply.txt @@ -0,0 +1,76 @@ +git-apply(1) +============ +v0.1, June 2005 + +NAME +---- +git-apply - Apply patch on a GIT index file and a work tree + + +SYNOPSIS +-------- +'git-apply' [--no-merge] [--stat] [--summary] [--check] [--index] [--show-files] [--apply] [<patch>...] + +DESCRIPTION +----------- +Reads supplied diff output and applies it on a GIT index file +and a work tree. + +OPTIONS +------- +<patch>...:: + The files to read patch from. '-' can be used to read + from the standard input. + +--no-merge:: + The default mode of operation is the merge behaviour + which is not implemented yet. This flag explicitly + tells the program not to use the merge behaviour. + +--stat:: + Instead of applying the patch, output diffstat for the + input. Turns off "apply". + +--summary:: + Instead of applying the patch, output a condensed + summary of information obtained from git diff extended + headers, such as creations, renames and mode changes. + Turns off "apply". + +--check:: + Instead of applying the patch, see if the patch is + applicable to the current work tree and/or the index + file and detects errors. Turns off "apply". + +--index:: + When --check is in effect, or when applying the patch + (which is the default when none of the options that + disables it is in effect), make sure the patch is + applicable to what the current index file records. If + the file to be patched in the work tree is not + up-to-date, it is flagged as an error. This flag also + causes the index file to be updated. + +--show-files:: + Show summary of files that are affected by the patch. + +--apply:: + If you use any of the options marked ``Turns off + "apply"'' above, git-apply reads and outputs the + information you asked without actually applying the + patch. Give this flag after those flags to also apply + the patch. + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by Junio C Hamano + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt new file mode 100644 index 0000000000..2131a29993 --- /dev/null +++ b/Documentation/git-cat-file.txt @@ -0,0 +1,61 @@ +git-cat-file(1) +=============== +v0.1, May 2005 + +NAME +---- +git-cat-file - Provide content or type information for repository objects + + +SYNOPSIS +-------- +'git-cat-file' (-t | -s | <type>) <object> + +DESCRIPTION +----------- +Provides content or type of objects in the repository. The type +is required unless '-t' is used to find the object type, +or '-s' is used to find the object size. + +OPTIONS +------- +<object>:: + The sha1 identifier of the object. + +-t:: + Instead of the content, show the object type identified by + <object>. + +-s:: + Instead of the content, show the object size identified by + <object>. + +<type>:: + Typically this matches the real type of <object> but asking + for a type that can trivially dereferenced from the given + <object> is also permitted. An example is to ask for a + "tree" with <object> being a commit object that contains it, + or to ask for a "blob" with <object> being a tag object that + points at it. + +OUTPUT +------ +If '-t' is specified, one of the <type>. If '-s' is specified, +the size of the <object> in bytes. + +Otherwise the raw (though uncompressed) contents of the <object> will +be returned. + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-checkout-cache.txt b/Documentation/git-checkout-cache.txt new file mode 100644 index 0000000000..321a00c251 --- /dev/null +++ b/Documentation/git-checkout-cache.txt @@ -0,0 +1,106 @@ +git-checkout-cache(1) +===================== +v0.1, May 2005 + +NAME +---- +git-checkout-cache - Copy files from the cache to the working directory + + +SYNOPSIS +-------- +'git-checkout-cache' [-u] [-q] [-a] [-f] [-n] [--prefix=<string>] + [--] <file>... + +DESCRIPTION +----------- +Will copy all files listed from the cache to the working directory +(not overwriting existing files). + +OPTIONS +------- +-u:: + update stat information for the checked out entries in + the cache file. + +-q:: + be quiet if files exist or are not in the cache + +-f:: + forces overwrite of existing files + +-a:: + checks out all files in the cache (will then continue to + process listed files). + +-n:: + Don't checkout new files, only refresh files already checked + out. + +--prefix=<string>:: + When creating files, prepend <string> (usually a directory + including a trailing /) + +--:: + Do not interpret any more arguments as options. + +Note that the order of the flags matters: + + git-checkout-cache -a -f file.c + +will first check out all files listed in the cache (but not overwrite +any old ones), and then force-checkout `file.c` a second time (ie that +one *will* overwrite any old contents with the same filename). + +Also, just doing "git-checkout-cache" does nothing. You probably meant +"git-checkout-cache -a". And if you want to force it, you want +"git-checkout-cache -f -a". + +Intuitiveness is not the goal here. Repeatability is. The reason for +the "no arguments means no work" thing is that from scripts you are +supposed to be able to do things like: + + find . -name '*.h' -print0 | xargs -0 git-checkout-cache -f -- + +which will force all existing `*.h` files to be replaced with their +cached copies. If an empty command line implied "all", then this would +force-refresh everything in the cache, which was not the point. + +To update and refresh only the files already checked out: + + git-checkout-cache -n -f -a && git-update-cache --ignore-missing --refresh + +Oh, and the "--" is just a good idea when you know the rest will be +filenames. Just so that you wouldn't have a filename of "-a" causing +problems (not possible in the above example, but get used to it in +scripting!). + +The prefix ability basically makes it trivial to use +git-checkout-cache as an "export as tree" function. Just read the +desired tree into the index, and do a + + git-checkout-cache --prefix=git-export-dir/ -a + +and git-checkout-cache will "export" the cache into the specified +directory. + +NOTE The final "/" is important. The exported name is literally just +prefixed with the specified string, so you can also do something like + + git-checkout-cache --prefix=.merged- Makefile + +to check out the currently cached copy of `Makefile` into the file +`.merged-Makefile` + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-clone-pack.txt b/Documentation/git-clone-pack.txt new file mode 100644 index 0000000000..0dc89a9072 --- /dev/null +++ b/Documentation/git-clone-pack.txt @@ -0,0 +1,65 @@ +git-clone-pack(1) +================= +v0.1, July 2005 + +NAME +---- +git-clone-pack - Clones a repository by receiving packed objects. + + +SYNOPSIS +-------- +'git-clone-pack' [-q] [--exec=<git-upload-pack>] [<host>:]<directory> [<head>...] + +DESCRIPTION +----------- +Clones a repository into the current repository by invoking +'git-upload-pack', possibly on the remote host via ssh, in +the named repository, and invoking 'git-unpack-objects' locally +to receive the pack. + +OPTIONS +------- +-q:: + Pass '-q' flag to 'git-unpack-objects'; this makes the + cloning process less verbose. + +--exec=<git-upload-pack>:: + Use this to specify the path to 'git-upload-pack' on the + remote side, if is not found on your $PATH. + Installations of sshd ignores the user's environment + setup scripts for login shells (e.g. .bash_profile) and + your privately installed GIT may not be found on the system + default $PATH. Another workaround suggested is to set + up your $PATH in ".bashrc", but this flag is for people + who do not want to pay the overhead for non-interactive + shells by having a lean .bashrc file (they set most of + the things up in .bash_profile). + +<host>:: + A remote host that houses the repository. When this + part is specified, 'git-upload-pack' is invoked via + ssh. + +<directory>:: + The repository to sync from. + +<head>...:: + The heads to update. This is relative to $GIT_DIR + (e.g. "HEAD", "refs/heads/master"). When unspecified, + all heads are updated to match the remote repository. + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by Junio C Hamano. + + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-clone-script.txt b/Documentation/git-clone-script.txt new file mode 100644 index 0000000000..afb25bd83c --- /dev/null +++ b/Documentation/git-clone-script.txt @@ -0,0 +1,60 @@ +git-clone-script(1) +=================== +v0.1, July 2005 + +NAME +---- +git-clone-script - Clones a repository. + + +SYNOPSIS +-------- +'git clone' [-l] [-u <upload-pack>] [-q] <repository> <directory> + +DESCRIPTION +----------- +Clones a repository into a newly created directory. + +OPTIONS +------- +-l:: + When the repository to clone from is on a local machine, + this flag bypasses normal "git aware" transport + mechanism and clones the repository by making a copy of + HEAD and everything under objects and refs directories. + The files under .git/objects/ directory are hardlinked + to save space when possible. + +-q:: + Operate quietly. This flag is passed to "rsync" and + "git-clone-pack" commands when given. + +-u <upload-pack>:: + When given, and the repository to clone from is handled + by 'git-clone-pack', '--exec=<upload-pack>' is passed to + the command to specify non-default path for the command + run on the other end. + +<repository>:: + The (possibly remote) repository to clone from. It can + be an "rsync://host/dir" URL, an "http://host/dir" URL, + or [<host>:]/dir notation that is used by 'git-clone-pack'. + Currently http transport is not supported. + +<directory>:: + The name of a new directory to be cloned into. It is an + error to specify an existing directory. + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by Junio C Hamano. + + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-commit-script.txt b/Documentation/git-commit-script.txt new file mode 100644 index 0000000000..cf6b5c3da2 --- /dev/null +++ b/Documentation/git-commit-script.txt @@ -0,0 +1,62 @@ +git-commit-script(1) +==================== +v0.99.4, Aug 2005 + +NAME +---- +git-commit-script - Record your changes + +SYNOPSIS +-------- +'git commit' [-a] [-s] [-v] [(-c | -C) <commit> | -F <file> | -m <msg>] <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. + +OPTIONS +------- +-a:: + Update all paths in the index file. + +-c or -C <commit>:: + Take existing commit object, and reuse the log message + and the authorship information (including the timestamp) + when creating the commit. With '-C', the editor is not + invoked; with '-c' the user can further edit the commit + message. + +-F <file>:: + Take the commit message from the given file. Use '-' to + read the message from the standard input. + +-m <msg>:: + Use the given <msg> as the commit message. + +-s:: + Add Signed-off-by line at the end of the commit message. + +-v:: + Look for suspicious lines the commit introduces, and + abort committing if there is one. The definition of + 'suspicious lines' is currently the lines that has + trailing whitespaces, and the lines whose indentation + has a SP character immediately followed by a TAB + character. + +<file>...:: + Update specified paths in the index file. + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> and +Junio C Hamano <junkio@cox.net> + + +GIT +--- +Part of the link:git.html[git] suite diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt new file mode 100644 index 0000000000..5536668813 --- /dev/null +++ b/Documentation/git-commit-tree.txt @@ -0,0 +1,92 @@ +git-commit-tree(1) +================== +v0.1, May 2005 + +NAME +---- +git-commit-tree - Creates a new commit object + + +SYNOPSIS +-------- +'git-commit-tree' <tree> [-p <parent commit>]\ < changelog + +DESCRIPTION +----------- +Creates a new commit object based on the provided tree object and +emits the new commit object id on stdout. If no parent is given then +it is considered to be an initial tree. + +A commit object usually has 1 parent (a commit after a change) or up +to 16 parents. More than one parent represents a merge of branches +that led to them. + +While a tree represents a particular directory state of a working +directory, a commit represents that state in "time", and explains how +to get there. + +Normally a commit would identify a new "HEAD" state, and while git +doesn't care where you save the note about that state, in practice we +tend to just write the result to the file `.git/HEAD`, so that we can +always see what the last committed state was. + +OPTIONS +------- +<tree>:: + An existing tree object + +-p <parent commit>:: + Each '-p' indicates a the id of a parent commit object. + + +Commit Information +------------------ + +A commit encapsulates: + +- all parent object ids +- author name, email and date +- committer name and email and the commit time. + +If not provided, "git-commit-tree" uses your name, hostname and domain to +provide author and committer info. This can be overridden using the +following environment variables. + + GIT_AUTHOR_NAME + GIT_AUTHOR_EMAIL + GIT_AUTHOR_DATE + GIT_COMMITTER_NAME + GIT_COMMITTER_EMAIL + +(nb <,> and '\n's are stripped) + +A commit comment is read from stdin (max 999 chars). If a changelog +entry is not provided via '<' redirection, "git-commit-tree" will just wait +for one to be entered and terminated with ^D + +Diagnostics +----------- +You don't exist. Go away!:: + The passwd(5) gecos field couldn't be read +Your parents must have hated you!:: + The password(5) gecos field is longer than a giant static buffer. +Your sysadmin must hate you!:: + The password(5) name field is longer than a giant static buffer. + +See Also +-------- +link:git-write-tree.html[git-write-tree] + + +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 link:git.html[git] suite + diff --git a/Documentation/git-convert-cache.txt b/Documentation/git-convert-cache.txt new file mode 100644 index 0000000000..66d7fe7855 --- /dev/null +++ b/Documentation/git-convert-cache.txt @@ -0,0 +1,30 @@ +git-convert-cache(1) +==================== +v0.1, May 2005 + +NAME +---- +git-convert-cache - Converts old-style GIT repository + + +SYNOPSIS +-------- +'git-convert-cache' + +DESCRIPTION +----------- +Converts old-style GIT repository to the latest format + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-cvsimport-script.txt b/Documentation/git-cvsimport-script.txt new file mode 100644 index 0000000000..d01a15d8a3 --- /dev/null +++ b/Documentation/git-cvsimport-script.txt @@ -0,0 +1,106 @@ +git-cvsimport-script(1) +======================= +v0.1, July 2005 + +NAME +---- +git-cvsimport-script - Import a CVS repository into git + + +SYNOPSIS +-------- +'git-cvsimport-script' [ -o <branch-for-HEAD> ] [ -h ] [ -v ] + [ -d <CVSROOT> ] [ -p <options-for-cvsps> ] + [ -C <GIT_repository> ] [ -i ] [ -k ] + [ -s <subst> ] [ -m ] [ -M regex ] [ <CVS_module> ] + + +DESCRIPTION +----------- +Imports a CVS repository into git. It will either create a new +repository, or incrementally import into an existing one. + +Splitting the CVS log into patch sets is done by 'cvsps'. +At least version 2.1 is required. + +OPTIONS +------- +-d <CVSROOT>:: + The root of the CVS archive. May be local (a simple path) or remote; + currently, only the :local:, :ext: and :pserver: access methods + are supported. + +-C <target-dir>:: + The GIT repository to import to. If the directory doesn't + exist, it will be created. Default is the current directory. + +-i:: + Import-only: don't perform a checkout after importing. This option + ensures the working directory and cache remain untouched and will + not create them if they do not exist. + +-k:: + Kill keywords: will extract files with -kk from the CVS archive + to avoid noisy changesets. Highly recommended, but off by default + to preserve compatibility with early imported trees. + +-o <branch-for-HEAD>:: + The 'HEAD' branch from CVS is imported to the 'origin' branch within + the git repository, as 'HEAD' already has a special meaning for git. + Use this option if you want to import into a different branch. + + Use '-o master' for continuing an import that was initially done by + the old cvs2git tool. + +-p <options-for-cvsps>:: + Additional options for cvsps. + The options '-u' and '-A' are implicit and should not be used here. + + If you need to pass multiple options, separate them with a comma. + +-m:: + Attempt to detect merges based on the commit message. This option + will enable default regexes that try to capture the name source + branch name from the commit message. + +-M <regex>:: + Attempt to detect merges based on the commit message with a custom + regex. It can be used with -m to also see the default regexes. + You must escape forward slashes. + +-v:: + Verbosity: let 'cvsimport' report what it is doing. + +<CVS_module>:: + The CVS module you want to import. Relative to <CVSROOT>. + +-h:: + Print a short usage message and exit. + +-z <fuzz>:: + Pass the timestamp fuzz factor to cvsps. + +-s <subst>:: + Substitute the character "/" in branch names with <subst> + +OUTPUT +------ +If '-v' is specified, the script reports what it is doing. + +Otherwise, success is indicated the Unix way, i.e. by simply exiting with +a zero exit status. + + +Author +------ +Written by Matthias Urlichs <smurf@smurf.noris.de>, with help from +various participants of the git-list <git@vger.kernel.org>. + +Documentation +-------------- +Documentation by Matthias Urlichs <smurf@smurf.noris.de>. + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-diff-cache.txt b/Documentation/git-diff-cache.txt new file mode 100644 index 0000000000..a353d12628 --- /dev/null +++ b/Documentation/git-diff-cache.txt @@ -0,0 +1,134 @@ +git-diff-cache(1) +================= +v0.1, May 2005 + +NAME +---- +git-diff-cache - Compares content and mode of blobs between the cache and repository + + +SYNOPSIS +-------- +'git-diff-cache' [-m] [--cached] [<common diff options>] <tree-ish> [<path>...] + +DESCRIPTION +----------- +Compares the content and mode of the blobs found via a tree +object with the content of the current cache and, optionally +ignoring the stat state of the file on disk. When paths are +specified, compares only those named paths. Otherwise all +entries in the cache are compared. + +OPTIONS +------- +include::diff-options.txt[] + +<tree-ish>:: + The id of a tree object to diff against. + +--cached:: + do not consider the on-disk file at all + +-m:: + By default, files recorded in the index but not checked + out are reported as deleted. This flag makes + "git-diff-cache" say that all non-checked-out files are up + to date. + +Output format +------------- +include::diff-format.txt[] + +Operating Modes +--------------- +You can choose whether you want to trust the index file entirely +(using the '--cached' flag) or ask the diff logic to show any files +that don't match the stat state as being "tentatively changed". Both +of these operations are very useful indeed. + +Cached Mode +----------- +If '--cached' is specified, it allows you to ask: + + show me the differences between HEAD and the current cache + contents (the ones I'd write with a "git-write-tree") + +For example, let's say that you have worked on your working directory, updated +some files in the cache and are ready to commit. You want to see eactly +*what* you are going to commit is without having to write a new tree +object and compare it that way, and to do that, you just do + + git-diff-cache --cached $(cat .git/HEAD) + +Example: let's say I had renamed `commit.c` to `git-commit.c`, and I had +done an "git-update-cache" to make that effective in the index file. +"git-diff-files" wouldn't show anything at all, since the index file +matches my working directory. But doing a "git-diff-cache" does: + + torvalds@ppc970:~/git> git-diff-cache --cached $(cat .git/HEAD) + -100644 blob 4161aecc6700a2eb579e842af0b7f22b98443f74 commit.c + +100644 blob 4161aecc6700a2eb579e842af0b7f22b98443f74 git-commit.c + +You can trivially see that the above is a rename. + +In fact, "git-diff-cache --cached" *should* always be entirely equivalent to +actually doing a "git-write-tree" and comparing that. Except this one is much +nicer for the case where you just want to check where you are. + +So doing a "git-diff-cache --cached" is basically very useful when you are +asking yourself "what have I already marked for being committed, and +what's the difference to a previous tree". + +Non-cached Mode +--------------- +The "non-cached" mode takes a different approach, and is potentially +the more useful of the two in that what it does can't be emulated with +a "git-write-tree" + "git-diff-tree". Thus that's the default mode. +The non-cached version asks the question: + + show me the differences between HEAD and the currently checked out + tree - index contents _and_ files that aren't up-to-date + +which is obviously a very useful question too, since that tells you what +you *could* commit. Again, the output matches the "git-diff-tree -r" +output to a tee, but with a twist. + +The twist is that if some file doesn't match the cache, we don't have +a backing store thing for it, and we use the magic "all-zero" sha1 to +show that. So let's say that you have edited `kernel/sched.c`, but +have not actually done a "git-update-cache" on it yet - there is no +"object" associated with the new state, and you get: + + torvalds@ppc970:~/v2.6/linux> git-diff-cache $(cat .git/HEAD ) + *100644->100664 blob 7476bb......->000000...... kernel/sched.c + +ie it shows that the tree has changed, and that `kernel/sched.c` has is +not up-to-date and may contain new stuff. The all-zero sha1 means that to +get the real diff, you need to look at the object in the working directory +directly rather than do an object-to-object diff. + +NOTE! As with other commands of this type, "git-diff-cache" does not +actually look at the contents of the file at all. So maybe +`kernel/sched.c` hasn't actually changed, and it's just that you +touched it. In either case, it's a note that you need to +"git-upate-cache" it to make the cache be in sync. + +NOTE 2! You can have a mixture of files show up as "has been updated" +and "is still dirty in the working directory" together. You can always +tell which file is in which state, since the "has been updated" ones +show a valid sha1, and the "not in sync with the index" ones will +always have the special all-zero sha1. + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-diff-files.txt b/Documentation/git-diff-files.txt new file mode 100644 index 0000000000..3e1244f8d3 --- /dev/null +++ b/Documentation/git-diff-files.txt @@ -0,0 +1,44 @@ +git-diff-files(1) +================= +v0.1, May 2005 + +NAME +---- +git-diff-files - Compares files in the working tree and the cache + + +SYNOPSIS +-------- +'git-diff-files' [-q] [<common diff options>] [<path>...] + +DESCRIPTION +----------- +Compares the files in the working tree and the cache. When paths +are specified, compares only those named paths. Otherwise all +entries in the cache are compared. The output format is the +same as "git-diff-cache" and "git-diff-tree". + +OPTIONS +------- +include::diff-options.txt[] + +-q:: + Remain silent even on nonexisting files + +Output format +------------- +include::diff-format.txt[] + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-diff-helper.txt b/Documentation/git-diff-helper.txt new file mode 100644 index 0000000000..d826deb42e --- /dev/null +++ b/Documentation/git-diff-helper.txt @@ -0,0 +1,53 @@ +git-diff-helper(1) +================== +v0.1, May 2005 + +NAME +---- +git-diff-helper - Generates patch format output for git-diff-* + + +SYNOPSIS +-------- +'git-diff-helper' [-z] [-S<string>] [-O<orderfile>] + +DESCRIPTION +----------- +Reads output from "git-diff-cache", "git-diff-tree" and "git-diff-files" and +generates patch format output. + +OPTIONS +------- +-z:: + \0 line termination on input + +-S<string>:: + Look for differences that contains the change in <string>. + +--pickaxe-all:: + When -S finds a change, show all the changes in that + changeset, not just the files that contains the change + in <string>. + +-O<orderfile>:: + Output the patch in the order specified in the + <orderfile>, which has one shell glob pattern per line. + +See Also +-------- +The section on generating patches in link:git-diff-cache.html[git-diff-cache] + + +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 link:git.html[git] suite + diff --git a/Documentation/git-diff-stages.txt b/Documentation/git-diff-stages.txt new file mode 100644 index 0000000000..2084c7041f --- /dev/null +++ b/Documentation/git-diff-stages.txt @@ -0,0 +1,41 @@ +git-diff-stages(1) +================== +v0.1, June 2005 + +NAME +---- +git-diff-stages - Compares content and mode of blobs between stages in an unmerged index file. + + +SYNOPSIS +-------- +'git-diff-stages' [<common diff options>] <stage1> <stage2> [<path>...] + +DESCRIPTION +----------- +Compares the content and mode of the blobs in two stages in an +unmerged index file. + +OPTIONS +------- +include::diff-options.txt[] + +<stage1>,<stage2>:: + The stage number to be compared. + +Output format +------------- +include::diff-format.txt[] + + +Author +------ +Written by Junio C Hamano <junkio@cox.net> + +Documentation +-------------- +Documentation by Junio C Hamano. + +GIT +--- +Part of the link:git.html[git] suite diff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt new file mode 100644 index 0000000000..5ccf0ba129 --- /dev/null +++ b/Documentation/git-diff-tree.txt @@ -0,0 +1,130 @@ +git-diff-tree(1) +================ +v0.1, May 2005 + +NAME +---- +git-diff-tree - Compares the content and mode of blobs found via two tree objects + + +SYNOPSIS +-------- +'git-diff-tree' [--stdin] [-m] [-s] [-v] [--pretty] [-t] [<common diff options>] <tree-ish> <tree-ish> [<path>...] + +DESCRIPTION +----------- +Compares the content and mode of the blobs found via two tree objects. + +Note that "git-diff-tree" can use the tree encapsulated in a commit object. + +OPTIONS +------- +include::diff-options.txt[] + +<tree-ish>:: + The id of a tree object. + +<path>...:: + If provided, the results are limited to a subset of files + matching one of these prefix strings. + ie file matches `/^<pattern1>|<pattern2>|.../` + Note that this parameter does not provide any wildcard or regexp + features. + +-t:: + show tree entry itself as well as subtrees. Implies -r. + +--root:: + When '--root' is specified the initial commit will be showed as a big + creation event. This is equivalent to a diff against the NULL tree. + +--stdin:: + When '--stdin' is specified, the command does not take + <tree-ish> arguments from the command line. Instead, it + reads either one <commit> or a pair of <tree-ish> + separated with a single space from its standard input. ++ +When a single commit is given on one line of such input, it compares +the commit with its parents. The following flags further affects its +behaviour. This does not apply to the case where two <tree-ish> +separated with a single space are given. + +-m:: + By default, "git-diff-tree --stdin" does not show + differences for merge commits. With this flag, it shows + differences to that commit from all of its parents. + +-s:: + By default, "git-diff-tree --stdin" shows differences, + either in machine-readable form (without '-p') or in patch + form (with '-p'). This output can be supressed. It is + only useful with '-v' flag. + +-v:: + This flag causes "git-diff-tree --stdin" to also show + the commit message before the differences. + +--pretty[=(raw|medium|short)]:: + This is used to control "pretty printing" format of the + commit message. Without "=<style>", it defaults to + medium. + + +Limiting Output +--------------- +If you're only interested in differences in a subset of files, for +example some architecture-specific files, you might do: + + git-diff-tree -r <tree-ish> <tree-ish> arch/ia64 include/asm-ia64 + +and it will only show you what changed in those two directories. + +Or if you are searching for what changed in just `kernel/sched.c`, just do + + git-diff-tree -r <tree-ish> <tree-ish> kernel/sched.c + +and it will ignore all differences to other files. + +The pattern is always the prefix, and is matched exactly. There are no +wildcards. Even stricter, it has to match a complete path component. +I.e. "foo" does not pick up `foobar.h`. "foo" does match `foo/bar.h` +so it can be used to name subdirectories. + +An example of normal usage is: + + torvalds@ppc970:~/git> git-diff-tree 5319e4...... + *100664->100664 blob ac348b.......->a01513....... git-fsck-cache.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-cache" 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 link:git.html[git] suite + diff --git a/Documentation/git-export.txt b/Documentation/git-export.txt new file mode 100644 index 0000000000..d2d0dc498e --- /dev/null +++ b/Documentation/git-export.txt @@ -0,0 +1,31 @@ +git-export(1) +============= +v0.1, May 2005 + +NAME +---- +git-export - Exports each commit and a diff against each of its parents + + +SYNOPSIS +-------- +'git-export' top [base] + +DESCRIPTION +----------- +Exports each commit and diff against each of its parents, between +top and base. If base is not specified it exports everything. + + +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 link:git.html[git] suite + diff --git a/Documentation/git-fetch-pack.txt b/Documentation/git-fetch-pack.txt new file mode 100644 index 0000000000..59afa14a30 --- /dev/null +++ b/Documentation/git-fetch-pack.txt @@ -0,0 +1,69 @@ +git-fetch-pack(1) +================= +v0.1, July 2005 + +NAME +---- +git-fetch-pack - Receive missing objects from another repository. + + +SYNOPSIS +-------- +git-fetch-pack [-q] [--exec=<git-upload-pack>] [<host>:]<directory> [<refs>...] + +DESCRIPTION +----------- +Invokes 'git-upload-pack' on a potentially remote repository, +and asks it to send objects missing from this repository, to +update the named heads. The list of commits available locally +is found out by scanning local $GIT_DIR/refs/ and sent to +'git-upload-pack' running on the other end. + +This command degenerates to download everything to complete the +asked refs from the remote side when the local side does not +have a common ancestor commit. + + +OPTIONS +------- +-q:: + Pass '-q' flag to 'git-unpack-objects'; this makes the + cloning process less verbose. + +--exec=<git-upload-pack>:: + Use this to specify the path to 'git-upload-pack' on the + remote side, if is not found on your $PATH. + Installations of sshd ignores the user's environment + setup scripts for login shells (e.g. .bash_profile) and + your privately installed GIT may not be found on the system + default $PATH. Another workaround suggested is to set + up your $PATH in ".bashrc", but this flag is for people + who do not want to pay the overhead for non-interactive + shells by having a lean .bashrc file (they set most of + the things up in .bash_profile). + +<host>:: + A remote host that houses the repository. When this + part is specified, 'git-upload-pack' is invoked via + ssh. + +<directory>:: + The repository to sync from. + +<refs>...:: + The remote heads to update from. This is relative to + $GIT_DIR (e.g. "HEAD", "refs/heads/master"). When + unspecified, update from all heads the remote side has. + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by Junio C Hamano. + +GIT +--- +Part of the link:git.html[git] suite diff --git a/Documentation/git-fetch-script.txt b/Documentation/git-fetch-script.txt new file mode 100644 index 0000000000..db3086c732 --- /dev/null +++ b/Documentation/git-fetch-script.txt @@ -0,0 +1,48 @@ +git-fetch-script(1) +=================== +v0.99.4, Aug 2005 + +NAME +---- +git-fetch-script - Download objects and a head from another repository. + + +SYNOPSIS +-------- +'git-fetch-script' <repository> [ <head> | tag <tag> ] + + +DESCRIPTION +----------- +Fetches a named head or a tag from another repository, along +with the objects necessary to complete that head or tag. The +head to pull defaults to HEAD if unspecified. The head or tag +fetched from the remote repository is stored in +$GIT_DIR/FETCH_HEAD. + +When a <tag> is specified, the <tag> fetched from the remote is +also copied to the local $GIT_DIR/tags/<tag> file. When no +<head> nor <tag> is specified, and <repository> was specified +with the short-hand notation (i.e. naming a file under the +$GIT_DIR/branches directory), the head fetched from the remote +repository is also copied to the local $GIT_DIR/heads/<repository> +file. + + +OPTIONS +------- +include::pull-fetch-param.txt[] + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> and +Junio C Hamano <junkio@cox.net> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the link:git.html[git] suite diff --git a/Documentation/git-fsck-cache.txt b/Documentation/git-fsck-cache.txt new file mode 100644 index 0000000000..13f19653fe --- /dev/null +++ b/Documentation/git-fsck-cache.txt @@ -0,0 +1,145 @@ +git-fsck-cache(1) +================= +v0.1, May 2005 + +NAME +---- +git-fsck-cache - Verifies the connectivity and validity of the objects in the database + + +SYNOPSIS +-------- +'git-fsck-cache' [--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-cache defaults to using the + index file and all SHA1 references in .git/refs/* as heads. + +--unreachable:: + Print out objects that exist but that aren't readable from any + of the reference nodes. + +--root:: + Report root nodes. + +--tags:: + Report tags. + +--cache:: + Consider any object recorded in the cache also as a head node for + an unreachability trace. + +--standalone:: + Limit checks to the contents of GIT_OBJECT_DIRECTORY + ($GIT_DIR/objects), making sure that it is consistent and + complete without referring to objects found in alternate + object pools listed in GIT_ALTERNATE_OBJECT_DIRECTORIES, + nor packed GIT archives found in $GIT_DIR/objects/pack; + cannot be used with --full. + +--full:: + Check not just objects in GIT_OBJECT_DIRECTORY + ($GIT_DIR/objects), but also the ones found in alternate + object pools listed in GIT_ALTERNATE_OBJECT_DIRECTORIES, + and in packed GIT archives found in $GIT_DIR/objects/pack + and corresponding pack subdirectories in alternate + object pools; cannot be used with --standalone. + +--strict:: + Enable more strict checking, namely to catch a file mode + recorded with g+w bit set, which was created by older + versions of GIT. Existing repositories, including the + Linux kernel, GIT itself, and sparse repository have old + objects that triggers this check, but it is recommended + to check new projects with this flag. + +It tests SHA1 and general object sanity, and it does full tracking of +the resulting reachability and everything else. It prints out any +corruption it finds (missing or bad objects), and if you use the +'--unreachable' flag it will also print out objects that exist but +that aren't readable from any of the specified head nodes. + +So for example + + git-fsck-cache --unreachable $(cat .git/HEAD .git/refs/heads/*) + +will do quite a _lot_ of verification on the tree. There are a few +extra validity tests to be added (make sure that tree objects are +sorted properly etc), but on the whole if "git-fsck-cache" 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-cache: tree <tree> has full pathnames in it:: + And it shouldn't... + +sha1 mismatch <object>:: + The database has an object who's sha1 doesn't match the + database value. + This indicates a serious data integrity problem. + +Environment Variables +--------------------- + +GIT_OBJECT_DIRECTORY:: + used to specify the object database root (usually $GIT_DIR/objects) + +GIT_INDEX_FILE:: + used to specify the index file of the cache + +GIT_ALTERNATE_OBJECT_DIRECTORIES: + used to specify additional object database roots (usually unset) + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-hash-object.txt b/Documentation/git-hash-object.txt new file mode 100644 index 0000000000..a77adab143 --- /dev/null +++ b/Documentation/git-hash-object.txt @@ -0,0 +1,44 @@ +git-hash-object(1) +================== +v0.1, May 2005 + +NAME +---- +git-hash-object - Computes object ID and optionally creates a blob from a file. + + +SYNOPSIS +-------- +'git-hash-object' [-t <type>] [-w] <any-file-on-the-filesystem> + +DESCRIPTION +----------- +Computes the object ID value for an object with specified type +with the contents of the named file (which can be outside of the +work tree), and optionally writes the resulting object into the +object database. Reports its object ID to its standard output. +This is used by "git-cvsimport-script" to update the cache +without modifying files in the work tree. When <type> is not +specified, it defaults to "blob". + +OPTIONS +------- + +-t <type>:: + Specify the type (default: "blob"). + +-w:: + Actually write the object into the object database. + +Author +------ +Written by Junio C Hamano <junkio@cox.net> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-http-pull.txt b/Documentation/git-http-pull.txt new file mode 100644 index 0000000000..edc5cebf7c --- /dev/null +++ b/Documentation/git-http-pull.txt @@ -0,0 +1,42 @@ +git-http-pull(1) +================ +v0.1, May 2005 + +NAME +---- +git-http-pull - Downloads a remote GIT repository via HTTP + + +SYNOPSIS +-------- +'git-http-pull' [-c] [-t] [-a] [-d] [-v] [-w filename] [--recover] commit-id url + +DESCRIPTION +----------- +Downloads a remote GIT repository via HTTP. + +-c:: + Get the commit objects. +-t:: + Get trees associated with the commit objects. +-a:: + Get all the objects. +-v:: + Report what is downloaded. + +-w <filename>:: + Writes the commit-id into the filename under $GIT_DIR/refs/<filename> on + the local end after the transfer is complete. + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-init-db.txt b/Documentation/git-init-db.txt new file mode 100644 index 0000000000..fb8b52253e --- /dev/null +++ b/Documentation/git-init-db.txt @@ -0,0 +1,41 @@ +git-init-db(1) +============== +v0.1, May 2005 + +NAME +---- +git-init-db - Creates an empty git repository + + +SYNOPSIS +-------- +'git-init-db' + +DESCRIPTION +----------- +This simply creates an empty git repository - basically a `.git` directory +and `.git/object/??/`, `.git/refs/heads` and `.git/refs/tags` directories, +and links `.git/HEAD` symbolically to `.git/refs/heads/master`. + +If the 'GIT_DIR' environment variable is set then it specifies a path +to use instead of `./.git` for the base of the repository. + +If the object storage directory is specified via the 'GIT_OBJECT_DIRECTORY' +environment variable then the sha1 directories are created underneath - +otherwise the default `$GIT_DIR/objects` directory is used. + +"git-init-db" won't hurt an existing repository. + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-local-pull.txt b/Documentation/git-local-pull.txt new file mode 100644 index 0000000000..4651e81581 --- /dev/null +++ b/Documentation/git-local-pull.txt @@ -0,0 +1,44 @@ +git-local-pull(1) +================= +v0.1, May 2005 + +NAME +---- +git-local-pull - Duplicates another GIT repository on a local system + + +SYNOPSIS +-------- +'git-local-pull' [-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 link:git.html[git] suite + diff --git a/Documentation/git-log-script.txt b/Documentation/git-log-script.txt new file mode 100644 index 0000000000..ed359bec86 --- /dev/null +++ b/Documentation/git-log-script.txt @@ -0,0 +1,45 @@ +git-log-script(1) +================= +v0.99.4, Aug 2005 + +NAME +---- +git-log-script - Show commit logs + + +SYNOPSIS +-------- +'git log' <option>... + +DESCRIPTION +----------- +Shows the commit logs. This command internally invokes +'git-rev-list', and the command line options are passed to that +command. + +This manual page describes only the most frequently used options. + +OPTIONS +------- +--pretty=<format>: + Controls the way the commit log is formatted. + +--max-count=<n>:: + Limits the number of commits to show. + +<since>..<until>:: + Show only commits between the named two commits. + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt new file mode 100644 index 0000000000..d05827f611 --- /dev/null +++ b/Documentation/git-ls-files.txt @@ -0,0 +1,197 @@ +git-ls-files(1) +=============== +v0.1, May 2005 + +NAME +---- +git-ls-files - Information about files in the cache/working directory + + +SYNOPSIS +-------- +'git-ls-files' [-z] [-t] + (--[cached|deleted|others|ignored|stage|unmerged|killed])\* + (-[c|d|o|i|s|u|k])\* + [-x <pattern>|--exclude=<pattern>] + [-X <file>|--exclude-from=<file>] + [--exclude-per-directory=<file>] + +DESCRIPTION +----------- +This merges the file listing in the directory cache index with the +actual working directory list, and shows different combinations of the +two. + +One or more of the options below may be used to determine the files +shown: + +OPTIONS +------- +-c|--cached:: + Show cached files in the output (default) + +-d|--deleted:: + Show deleted files in the output + +-o|--others:: + Show other files in the output + +-i|--ignored:: + Show ignored files in the output + Note the this also reverses any exclude list present. + +-s|--stage:: + Show stage files in the output + +-u|--unmerged:: + Show unmerged files in the output (forces --stage) + +-k|--killed:: + Show files on the filesystem that need to be removed due + to file/directory conflicts for checkout-cache to + succeed. + +-z:: + \0 line termination on output + +-x|--exclude=<pattern>:: + Skips files matching pattern. + Note that pattern is a shell wildcard pattern. + +-X|--exclude-from=<file>:: + exclude patterns are read from <file>; 1 per line. + +--exclude-per-directory=<file>:: + read additional exclude patterns that apply only to the + directory and its subdirectories in <file>. + +-t:: + Identify the file status with the following tags (followed by + a space) at the start of each line: + H cached + M unmerged + R removed/deleted + K to be killed + ? other + +Output +------ +show files just outputs the filename unless '--stage' is specified in +which case it outputs: + + [<tag> ]<mode> <object> <stage> <file> + +"git-ls-files --unmerged" and "git-ls-files --stage" can be used to examine +detailed information on unmerged paths. + +For an unmerged path, instead of recording a single mode/SHA1 pair, +the dircache records up to three such pairs; one from tree O in stage +1, A in stage 2, and B in stage 3. This information can be used by +the user (or the porcelain) to see what should eventually be recorded at the +path. (see read-cache for more information on state) + + +Exclude Patterns +---------------- + +'git-ls-files' can use a list of "exclude patterns" when +traversing the directory tree and finding files to show when the +flags --others or --ignored are specified. + +These exclude patterns come from these places: + + (1) command line flag --exclude=<pattern> specifies a single + pattern. + + (2) command line flag --exclude-from=<file> specifies a list of + patterns stored in a file. + + (3) command line flag --exclude-per-directory=<name> specifies + a name of the file in each directory 'git-ls-files' + examines, and if exists, its contents are used as an + additional list of patterns. + +An exclude pattern file used by (2) and (3) contains one pattern +per line. A line that starts with a '#' can be used as comment +for readability. + +There are three lists of patterns that are in effect at a given +time. They are built and ordered in the following way: + + * --exclude=<pattern> from the command line; patterns are + ordered in the same order as they appear on the command line. + + * lines read from --exclude-from=<file>; patterns are ordered + in the same order as they appear in the file. + + * When --exclude-per-directory=<name> is specified, upon + entering a directory that has such a file, its contents are + appended at the end of the current "list of patterns". They + are popped off when leaving the directory. + +Each pattern in the pattern list specifies "a match pattern" and +optionally the fate; either a file that matches the pattern is +considered excluded or included. A filename is matched against +the patterns in the three lists; the --exclude-from list is +checked first, then the --exclude-per-directory list, and then +finally the --exclude list. The last match determines its fate. +If there is no match in the three lists, the fate is "included". + +A pattern specified on the command line with --exclude or read +from the file specified with --exclude-from is relative to the +top of the directory tree. A pattern read from a file specified +by --exclude-per-directory is relative to the directory that the +pattern file appears in. + +An exclude pattern is of the following format: + + - an optional prefix '!' which means that the fate this pattern + specifies is "include", not the usual "exclude"; the + remainder of the pattern string is interpreted according to + the following rules. + + - if it does not contain a slash '/', it is a shell glob + pattern and used to match against the filename without + leading directories (i.e. the same way as the current + implementation). + + - otherwise, it is a shell glob pattern, suitable for + consumption by fnmatch(3) with FNM_PATHNAME flag. I.e. a + slash in the pattern must match a slash in the pathname. + "Documentation/*.html" matches "Documentation/git.html" but + not "ppc/ppc.html". As a natural exception, "/*.c" matches + "cat-file.c" but not "mozilla-sha1/sha1.c". + +An example: + + $ cat .git/ignore + # ignore objects and archives, anywhere in the tree. + *.[oa] + $ cat Documentation/.gitignore + # ignore generated html files, + *.html + # except foo.html which is maintained by hand + !foo.html + $ git-ls-files --ignored \ + --exclude='Documentation/*.[0-9]' \ + --exclude-from=.git/ignore \ + --exclude-per-directory=.gitignore + + +See Also +-------- +link:read-cache.html[read-cache] + + +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 link:git.html[git] suite + diff --git a/Documentation/git-ls-remote-script.txt b/Documentation/git-ls-remote-script.txt new file mode 100644 index 0000000000..0b98e6a9f4 --- /dev/null +++ b/Documentation/git-ls-remote-script.txt @@ -0,0 +1,64 @@ +git-ls-remote-script(1) +======================= +v0.1, May 2005 + +NAME +---- +git-ls-remote-script - Look at references other repository has. + + +SYNOPSIS +-------- +'git-ls-remote' [--heads] [--tags] <repository> <refs>... + +DESCRIPTION +----------- +Displays the references other repository has. + + +OPTIONS +------- +--heads --tags:: + Limit to only refs/heads and refs/tags, respectively. + These options are _not_ mutually exclusive; when given + both, references stored in refs/heads and refs/tags are + displayed. + +<repository>:: + Location of the repository. The shorthand defined in + $GIT_DIR/branches/ can be used. + +<refs>...:: + When unspecified, all references, after filtering done + with --heads and --tags, are shown. When <refs>... are + specified, only references matching the given patterns + are displayed. + +EXAMPLES +-------- + + $ git ls-remote --tags ./. + d6602ec5194c87b0fc87103ca4d67251c76f233a refs/tags/v0.99 + f25a265a342aed6041ab0cc484224d9ca54b6f41 refs/tags/v0.99.1 + 7ceca275d047c90c0c7d5afb13ab97efdf51bd6e refs/tags/v0.99.3 + c5db5456ae3b0873fc659c19fafdde22313cc441 refs/tags/v0.99.2 + 0918385dbd9656cab0d1d81ba7453d49bbc16250 refs/tags/junio-gpg-pub + $ git ls-remote http://www.kernel.org/pub/scm/git/git.git master pu rc + 5fe978a5381f1fbad26a80e682ddd2a401966740 refs/heads/master + c781a84b5204fb294c9ccc79f8b3baceeb32c061 refs/heads/pu + b1d096f2926c4e37c9c0b6a7bf2119bedaa277cb refs/heads/rc + $ echo http://www.kernel.org/pub/scm/git/git.git >.git/branches/public + $ git ls-remote --tags public v\* + d6602ec5194c87b0fc87103ca4d67251c76f233a refs/tags/v0.99 + f25a265a342aed6041ab0cc484224d9ca54b6f41 refs/tags/v0.99.1 + c5db5456ae3b0873fc659c19fafdde22313cc441 refs/tags/v0.99.2 + 7ceca275d047c90c0c7d5afb13ab97efdf51bd6e refs/tags/v0.99.3 + +Author +------ +Written by Junio C Hamano <junkio@cox.net> + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt new file mode 100644 index 0000000000..fdb215ec60 --- /dev/null +++ b/Documentation/git-ls-tree.txt @@ -0,0 +1,55 @@ +git-ls-tree(1) +============== +v0.1, May 2005 + +NAME +---- +git-ls-tree - Lists the contents of a tree object. + + +SYNOPSIS +-------- +'git-ls-tree' [-d] [-r] [-z] <tree-ish> [paths...] + +DESCRIPTION +----------- +Lists the contents of a tree object, like what "/bin/ls -a" does +in the current working directory. + +OPTIONS +------- +<tree-ish>:: + Id of a tree-ish. + +-d:: + show only the named tree entry itself, not its children + +-r:: + recurse into sub-trees + +-z:: + \0 line termination on output + +paths:: + When paths are given, show them. Otherwise implicitly + uses the root level of the tree as the sole path argument. + + +Output Format +------------- + <mode> SP <type> SP <object> TAB <file> + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> +Completely rewritten from scratch by Junio C Hamano <junkio@cox.net> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-merge-base.txt b/Documentation/git-merge-base.txt new file mode 100644 index 0000000000..1e27bf2301 --- /dev/null +++ b/Documentation/git-merge-base.txt @@ -0,0 +1,34 @@ +git-merge-base(1) +================= +v0.1, May 2005 + +NAME +---- +git-merge-base - Finds as good a common ancestor as possible for a merge + + +SYNOPSIS +-------- +'git-merge-base' <commit> <commit> + +DESCRIPTION +----------- +"git-merge-base" finds as good a common ancestor as possible. Given a +selection of equally good common ancestors it should not be relied on +to decide in any particular way. + +The "git-merge-base" algorithm is still in flux - use the source... + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-merge-cache.txt b/Documentation/git-merge-cache.txt new file mode 100644 index 0000000000..bd3c9ca75f --- /dev/null +++ b/Documentation/git-merge-cache.txt @@ -0,0 +1,89 @@ +git-merge-cache(1) +================== +v0.1, May 2005 + +NAME +---- +git-merge-cache - Runs a merge for files needing merging + + +SYNOPSIS +-------- +'git-merge-cache' [-o] [-q] <merge-program> (-a | -- | <file>\*) + +DESCRIPTION +----------- +This looks up the <file>(s) in the cache and, if there are any merge +entries, passes the SHA1 hash for those files as arguments 1, 2, 3 (empty +argument if no file), and <file> as argument 4. File modes for the three +files are passed as arguments 5, 6 and 7. + +OPTIONS +------- +--:: + Interpret all following arguments as filenames. + +-a:: + Run merge against all files in the cache that need merging. + +-o:: + Instead of stopping at the first failed merge, do all of them + in one shot - continue with merging even when previous merges + returned errors, and only return the error code after all the + merges are over. + +-q:: + Do not complain about failed merge program (the merge program + failure usually indicates conflicts during merge). This is for + porcelains which might want to emit custom messages. + +If "git-merge-cache" 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-script" 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-cache 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-cache 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-cache" 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-cache" 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 link:git.html[git] suite + diff --git a/Documentation/git-merge-one-file-script.txt b/Documentation/git-merge-one-file-script.txt new file mode 100644 index 0000000000..1cfe9548e1 --- /dev/null +++ b/Documentation/git-merge-one-file-script.txt @@ -0,0 +1,31 @@ +git-merge-one-file-script(1) +============================ +v0.99.4, Aug 2005 + +NAME +---- +git-merge-one-file-script - The standard helper program to use with "git-merge-cache" + + +SYNOPSIS +-------- +'git-merge-one-file-script' + +DESCRIPTION +----------- +This is the standard helper program to use with "git-merge-cache" +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 link:git.html[git] suite + diff --git a/Documentation/git-mktag.txt b/Documentation/git-mktag.txt new file mode 100644 index 0000000000..708f4ef8da --- /dev/null +++ b/Documentation/git-mktag.txt @@ -0,0 +1,48 @@ +git-mktag(1) +============ +v0.1, May 2005 + +NAME +---- +git-mktag - Creates a tag object + + +SYNOPSIS +-------- +'git-mktag' < signature_file + +DESCRIPTION +----------- +Reads a tag contents on standard input and creates a tag object +that can also be used to sign other objects. + +The output is the new tag's <object> identifier. + +Tag Format +---------- +A tag signature file has a very simple fixed format: three lines of + + object <sha1> + type <typename> + tag <tagname> + +followed by some 'optional' free-form signature that git itself +doesn't care about, but that can be verified with gpg or similar. + +The size of the full object is artificially limited to 8kB. (Just +because I'm a lazy bastard, and if you can't fit a signature in that +size, you're doing something wrong) + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt new file mode 100644 index 0000000000..7710be0851 --- /dev/null +++ b/Documentation/git-pack-objects.txt @@ -0,0 +1,84 @@ +git-pack-objects(1) +=================== +v0.1, July 2005 + +NAME +---- +git-pack-objects - Create a packed archive of objects. + + +SYNOPSIS +-------- +'git-pack-objects' [--incremental] [--window=N] [--depth=N] {--stdout | base-name} < object-list + + +DESCRIPTION +----------- +Reads list of objects from the standard input, and writes a packed +archive with specified base-name, or to the standard output. + +A packed archive is an efficient way to transfer set of objects +between two repositories, and also is an archival format which +is efficient to access. The packed archive format (.pack) is +designed to be unpackable without having anything else, but for +random access, accompanied with the pack index file (.idx). + +'git-unpack-objects' command can read the packed archive and +expand the objects contained in the pack into "one-file +one-object" format; this is typically done by the smart-pull +commands when a pack is created on-the-fly for efficient network +transport by their peers. + +Placing both in the pack/ subdirectory of $GIT_OBJECT_DIRECTORY (or +any of the directories on $GIT_ALTERNATE_OBJECT_DIRECTORIES) +enables GIT to read from such an archive. + + +OPTIONS +------- +base-name:: + Write into a pair of files (.pack and .idx), using + <base-name> to determine the name of the created file. + When this option is used, the two files are written in + <base-name>-<SHA1>.{pack,idx} files. <SHA1> is a hash + of object names (currently in random order so it does + not have any useful meaning) to make the resulting + filename reasonably unique, and written to the standard + output of the command. + +--stdout:: + Write the pack contents (what would have been writtin to + .pack file) out to the standard output. + +--window and --depth:: + These two options affects how the objects contained in + the pack are stored using delta compression. The + objects are first internally sorted by type, size and + optionally names and compared against the other objects + within --window to see if using delta compression saves + space. --depth limits the maximum delta depth; making + it too deep affects the performance on the unpacker + side, because delta data needs to be applied that many + times to get to the necessary object. + +--incremental:: + This flag causes an object already in a pack ignored + even if it appears in the standard input. + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +------------- +Documentation by Junio C Hamano + +See-Also +-------- +git-repack-script(1) git-prune-packed(1) + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-peek-remote.txt b/Documentation/git-peek-remote.txt new file mode 100644 index 0000000000..90075403dc --- /dev/null +++ b/Documentation/git-peek-remote.txt @@ -0,0 +1,53 @@ +git-peek-remote(1) +================== +v0.1, July 2005 + +NAME +---- +git-peek-remote - Lists the references in a remote repository. + + +SYNOPSIS +-------- +'git-peek-remote' [--exec=<git-upload-pack>] [<host>:]<directory> + +DESCRIPTION +----------- +Lists the references the remote repository has, and optionally +stores them in the local repository under the same name. + +OPTIONS +------- +--exec=<git-upload-pack>:: + Use this to specify the path to 'git-upload-pack' on the + remote side, if it is not found on your $PATH. Some + installations of sshd ignores the user's environment + setup scripts for login shells (e.g. .bash_profile) and + your privately installed GIT may not be found on the system + default $PATH. Another workaround suggested is to set + up your $PATH in ".bashrc", but this flag is for people + who do not want to pay the overhead for non-interactive + shells, but prefer having a lean .bashrc file (they set most of + the things up in .bash_profile). + +<host>:: + A remote host that houses the repository. When this + part is specified, 'git-upload-pack' is invoked via + ssh. + +<directory>:: + The repository to sync from. + + +Author +------ +Written by Junio C Hamano <junkio@cox.net> + +Documentation +-------------- +Documentation by Junio C Hamano. + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-prune-packed.txt b/Documentation/git-prune-packed.txt new file mode 100644 index 0000000000..893c1df55e --- /dev/null +++ b/Documentation/git-prune-packed.txt @@ -0,0 +1,42 @@ +git-prune-packed(1) +===================== +v0.1, August 2005 + +NAME +---- +git-prune-packed - Program used to remove the extra object files that are now +residing in a pack file. + + +SYNOPSIS +-------- +'git-prune-packed' + +DESCRIPTION +----------- +This program search the GIT_OBJECT_DIR for all objects that currently exist in +a pack file as well as the independent object directories. + +All such extra objects are removed. + +A pack is a collection of objects, individually compressed, with delta +compression applied, stored in a single file, with an associated index file. + +Packs are used to reduce the load on mirror systems, backup engines, disk storage, etc. + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by Ryan Anderson <ryan@michonline.com> + +See-Also +-------- +git-pack-objects(1) git-repack-script(1) + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-prune-script.txt b/Documentation/git-prune-script.txt new file mode 100644 index 0000000000..e8305a6f3d --- /dev/null +++ b/Documentation/git-prune-script.txt @@ -0,0 +1,33 @@ +git-prune-script(1) +=================== +v0.1, May 2005 + +NAME +---- +git-prune-script - Prunes all unreachable objects from the object database + + +SYNOPSIS +-------- +'git-prune-script' + +DESCRIPTION +----------- +This runs "git-fsck-cache --unreachable" program using the heads specified +on the command line (or `$GIT_DIR/refs/heads/\*` and `$GIT_DIR/refs/tags/\*` +if none is specified), and prunes all unreachable objects from the object +database. + + +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 link:git.html[git] suite + diff --git a/Documentation/git-pull-script.txt b/Documentation/git-pull-script.txt new file mode 100644 index 0000000000..ad9d3ab315 --- /dev/null +++ b/Documentation/git-pull-script.txt @@ -0,0 +1,38 @@ +git-pull-script(1) +================== +v0.99.4, Aug 2005 + +NAME +---- +git-pull-script - Pull and merge from another repository. + + +SYNOPSIS +-------- +'git-pull-script' <repository> [ <head> | tag <tag> ] + + +DESCRIPTION +----------- +Runs 'git-fetch-script' with the given parameters, then +'git-resolve-script' to merge the local HEAD and FETCH_HEAD. + + +OPTIONS +------- +include::pull-fetch-param.txt[] + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> +and Junio C Hamano <junkio@cox.net> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt new file mode 100644 index 0000000000..e1be6cc0bc --- /dev/null +++ b/Documentation/git-read-tree.txt @@ -0,0 +1,268 @@ +git-read-tree(1) +================ +v0.1, May 2005 + +NAME +---- +git-read-tree - Reads tree information into the directory cache + + +SYNOPSIS +-------- +'git-read-tree' (<tree-ish> | [-m [-u]] <tree-ish1> [<tree-ish2> [<tree-ish3>]]) + + +DESCRIPTION +----------- +Reads the tree information given by <tree-ish> into the directory cache, +but does not actually *update* any of the files it "caches". (see: +git-checkout-cache) + +Optionally, it can merge a tree into the cache, perform a +fast-forward (i.e. 2-way) merge, or a 3-way merge, with the -m +flag. When used with -m, the -u flag causes it to also update +the files in the work tree with the result of the merge. + +Trivial merges are done by "git-read-tree" itself. Only conflicting paths +will be in unmerged state when "git-read-tree" returns. + +OPTIONS +------- +-m:: + Perform a merge, not just a read. + +-u:: + After a successful merge, update the files in the work + tree with the result of the merge. + +<tree-ish#>:: + The id of the tree object(s) to be read/merged. + + +Merging +------- +If '-m' is specified, "git-read-tree" can perform 3 kinds of +merge, a single tree merge if only 1 tree is given, a +fast-forward merge with 2 trees, or a 3-way merge if 3 trees are +provided. + + +Single Tree Merge +~~~~~~~~~~~~~~~~~ +If only 1 tree is specified, git-read-tree operates as if the user did not +specify '-m', except that if the original cache has an entry for a +given pathname, and the contents of the path matches with the tree +being read, the stat info from the cache is used. (In other words, the +cache's stat()s take precedence over the merged tree's). + +That means that if you do a "git-read-tree -m <newtree>" followed by a +"git-checkout-cache -f -u -a", the "git-checkout-cache" only checks out +the stuff that really changed. + +This is used to avoid unnecessary false hits when "git-diff-files" is +run after git-read-tree. + + +Two Tree Merge +~~~~~~~~~~~~~~ + +Typically, this is invoked as "git-read-tree -m $H $M", where $H +is the head commit of the current repository, and $M is the head +of a foreign tree, which is simply ahead of $H (i.e. we are in a +fast forward situation). + +When two trees are specified, the user is telling git-read-tree +the following: + + (1) The current index and work tree is derived from $H, but + the user may have local changes in them since $H; + + (2) The user wants to fast-forward to $M. + +In this case, the "git-read-tree -m $H $M" command makes sure +that no local change is lost as the result of this "merge". +Here are the "carry forward" rules: + + I (index) H M Result + ------------------------------------------------------- + 0 nothing nothing nothing (does not happen) + 1 nothing nothing exists use M + 2 nothing exists nothing remove path from cache + 3 nothing exists exists use M + + clean I==H I==M + ------------------ + 4 yes N/A N/A nothing nothing keep index + 5 no N/A N/A nothing nothing keep index + + 6 yes N/A yes nothing exists keep index + 7 no N/A yes nothing exists keep index + 8 yes N/A no nothing exists fail + 9 no N/A no nothing exists fail + + 10 yes yes N/A exists nothing remove path from cache + 11 no yes N/A exists nothing fail + 12 yes no N/A exists nothing fail + 13 no no N/A exists nothing fail + + clean (H=M) + ------ + 14 yes exists exists keep index + 15 no exists exists keep index + + clean I==H I==M (H!=M) + ------------------ + 16 yes no no exists exists fail + 17 no no no exists exists fail + 18 yes no yes exists exists keep index + 19 no no yes exists exists keep index + 20 yes yes no exists exists use M + 21 no yes no exists exists fail + +In all "keep index" cases, the cache entry stays as in the +original index file. If the entry were not up to date, +git-read-tree keeps the copy in the work tree intact when +operating under the -u flag. + +When this form of git-read-tree returns successfully, you can +see what "local changes" you made are carried forward by running +"git-diff-cache --cached $M". Note that this does not +necessarily match "git-diff-cache --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-cache +--cached $H" would have told you about the change before this +merge, but it would not show in "git-diff-cache --cached $M" +output after two-tree merge. + + +3-Way Merge +~~~~~~~~~~~ +Each "index" entry has two bits worth of "stage" state. stage 0 is the +normal one, and is the only one you'd see in any kind of normal use. + +However, when you do "git-read-tree" with three trees, the "stage" +starts out at 1. + +This means that you can do + + git-read-tree -m <tree1> <tree2> <tree3> + +and you will end up with an index with all of the <tree1> entries in +"stage1", all of the <tree2> entries in "stage2" and all of the +<tree3> entries in "stage3". + +Furthermore, "git-read-tree" has special-case logic that says: if you see +a file that matches in all respects in the following states, it +"collapses" back to "stage0": + + - stage 2 and 3 are the same; take one or the other (it makes no + difference - the same work has been done on stage 2 and 3) + + - stage 1 and stage 2 are the same and stage 3 is different; take + stage 3 (some work has been done on stage 3) + + - stage 1 and stage 3 are the same and stage 2 is different take + stage 2 (some work has been done on stage 2) + +The "git-write-tree" command refuses to write a nonsensical tree, and it +will complain about unmerged entries if it sees a single entry that is not +stage 0. + +Ok, this all sounds like a collection of totally nonsensical rules, +but it's actually exactly what you want in order to do a fast +merge. The different stages represent the "result tree" (stage 0, aka +"merged"), the original tree (stage 1, aka "orig"), and the two trees +you are trying to merge (stage 2 and 3 respectively). + +The order of stages 1, 2 and 3 (hence the order of three +<tree-ish> command line arguments) are significant when you +start a 3-way merge with an index file that is already +populated. Here is an outline of how the algorithm works: + +- if a file exists in identical format in all three trees, it will + automatically collapse to "merged" state by git-read-tree. + +- a file that has _any_ difference what-so-ever in the three trees + will stay as separate entries in the index. It's up to "porcelain + policy" to determine how to remove the non-0 stages, and insert a + merged version. + +- the index file saves and restores with all this information, so you + can merge things incrementally, but as long as it has entries in + stages 1/2/3 (ie "unmerged entries") you can't write the result. So + now the merge algorithm ends up being really simple: + + * you walk the index in order, and ignore all entries of stage 0, + since they've already been done. + + * if you find a "stage1", but no matching "stage2" or "stage3", you + know it's been removed from both trees (it only existed in the + original tree), and you remove that entry. + + * if you find a matching "stage2" and "stage3" tree, you remove one + of them, and turn the other into a "stage0" entry. Remove any + matching "stage1" entry if it exists too. .. all the normal + trivial rules .. + +You would normally use "git-merge-cache" with supplied +"git-merge-one-file-script" to do this last step. The script +does not touch the files in the work tree, and the entire merge +happens in the index file. In other words, there is no need to +worry about what is in the working directory, since it is never +shown and never used. + +When you start a 3-way merge with an index file that is already +populated, it is assumed that it represents the state of the +files in your work tree, and you can even have files with +changes unrecorded in the index file. It is further assumed +that this state is "derived" from the stage 2 tree. The 3-way +merge refuses to run if it finds an entry in the original index +file that does not match stage 2. + +This is done to prevent you from losing your work-in-progress +changes. To illustrate, suppose you start from what has been +commited last to your repository: + + $ JC=`cat .git/HEAD` + $ git-checkout-cache -f -u -a $JC + +You do random edits, without running git-update-cache. And then +you notice that the tip of your "upstream" tree has advanced +since you pulled from him: + + $ git-fetch-script rsync://.... linus + $ LT=`cat .git/MERGE_HEAD` + +Your work tree is still based on your HEAD ($JC), but you have +some edits since. Three-way merge makes sure that you have not +added or modified cache entries since $JC, and if you haven't, +then does the right thing. So with the following sequence: + + $ git-read-tree -m -u `git-merge-base $JC $LT` $JC $LT + $ git-merge-cache git-merge-one-file-script -a + $ echo "Merge with Linus" | \ + git-commit-tree `git-write-tree` -p $JC -p $LT + +what you would commit is a pure merge between $JC and LT without +your work-in-progress changes, and your work tree would be +updated to the result of the merge. + + +See Also +-------- +link:git-write-tree.html[git-write-tree]; link:git-ls-files.html[git-ls-files] + + +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 link:git.html[git] suite + diff --git a/Documentation/git-receive-pack.txt b/Documentation/git-receive-pack.txt new file mode 100644 index 0000000000..2f1a1f8ebb --- /dev/null +++ b/Documentation/git-receive-pack.txt @@ -0,0 +1,90 @@ +git-receive-pack(1) +=================== +v0.1, July 2005 + +NAME +---- +git-receive-pack - Receive what is pushed into it + + +SYNOPSIS +-------- +'git-receive-pack' <directory> + +DESCRIPTION +----------- +Invoked by 'git-send-pack' and updates the repository with the +information fed from the remote end. + +This command is usually not invoked directly by the end user. +The UI for the protocol is on the 'git-send-pack' side, and the +program pair is meant to be used to push updates to remote +repository. For pull operations, see 'git-fetch-pack' and +'git-clone-pack'. + +The command allows for creation and fast forwarding of sha1 refs +(heads/tags) on the remote end (strictly speaking, it is the +local end receive-pack runs, but to the user who is sitting at +the send-pack end, it is updating the remote. Confused?) + +Before each ref is updated, if $GIT_DIR/hooks/update file exists +and executable, it is called with three parameters: + + $GIT_DIR/hooks/update refname sha1-old sha1-new + +The refname parameter is relative to $GIT_DIR; e.g. for the +master head this is "refs/heads/master". Two sha1 are the +object names for the refname before and after the update. Note +that the hook is called before the refname is updated, so either +sha1-old is 0{40} (meaning there is no such ref yet), or it +should match what is recorded in refname. + +The hook should exit with non-zero status if it wants to +disallow updating the named ref. Otherwise it should exit with +zero. + +Using this hook, it is easy to generate mails on updates to +the local repository. This example script sends a mail with +the commits pushed to the repository: + + #!/bin/sh + # mail out commit update information. + if expr "$2" : '0*$' >/dev/null + then + echo "Created a new ref, with the following commits:" + git-rev-list --pretty "$2" + else + echo "New commits:" + git-rev-list --pretty "$3" "^$2" + fi | + mail -s "Changes to ref $1" commit-list@mydomain + exit 0 + +Another hook $GIT_DIR/hooks/post-update, if exists and +executable, is called with the list of refs that have been +updated. This can be used to implement repository wide cleanup +task if needed. The exit code from this hook invocation is +ignored; the only thing left for git-receive-pack to do at that +point is to exit itself anyway. This hook can be used, for +example, to run "git-update-server-info" if the repository is +packed and is served via a dumb transport. + + #!/bin/sh + exec git-update-server-info + +OPTIONS +------- +<directory>:: + The repository to sync into. + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by Junio C Hamano. + +GIT +--- +Part of the link:git.html[git] suite diff --git a/Documentation/git-rename-script.txt b/Documentation/git-rename-script.txt new file mode 100644 index 0000000000..1abc68b7dd --- /dev/null +++ b/Documentation/git-rename-script.txt @@ -0,0 +1,34 @@ + +git-rename-script(1) +===================== +v0.1, May 2005 + +NAME +---- +git-rename-script - Script used to rename a file, directory or symlink. + + +SYNOPSIS +-------- +'git-rename-script' <source> <destination> + +DESCRIPTION +----------- +This script is used to rename a file, directory or symlink. + +The index is updated after successful completion, but the change must still be +committed. + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> +Rewritten by Ryan Anderson <ryan@michonline.com> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-repack-script.txt b/Documentation/git-repack-script.txt new file mode 100644 index 0000000000..497d0dfe80 --- /dev/null +++ b/Documentation/git-repack-script.txt @@ -0,0 +1,40 @@ +git-repack-script(1) +===================== +v0.1, August 2005 + +NAME +---- +git-repack-script - Script used to pack a repository from a collection of +objects into pack files. + + +SYNOPSIS +-------- +'git-repack-script' + +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. + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by Ryan Anderson <ryan@michonline.com> + +See-Also +-------- +git-pack-objects(1) git-prune-packed(1) + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-resolve-script.txt b/Documentation/git-resolve-script.txt new file mode 100644 index 0000000000..99c399a073 --- /dev/null +++ b/Documentation/git-resolve-script.txt @@ -0,0 +1,31 @@ +git-resolve-script(1) +===================== +v0.99.4, Aug 2005 + +NAME +---- +git-resolve-script - Script used to merge two trees + + +SYNOPSIS +-------- +'git-resolve-script' + +DESCRIPTION +----------- +This script is used by Linus to merge two trees. + + +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 link:git.html[git] suite + diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt new file mode 100644 index 0000000000..35fecf3f83 --- /dev/null +++ b/Documentation/git-rev-list.txt @@ -0,0 +1,96 @@ +git-rev-list(1) +=============== +v0.1, May 2005 + +NAME +---- +git-rev-list - Lists commit objects in reverse chronological order + + +SYNOPSIS +-------- +'git-rev-list' [ *--max-count*=number ] [ *--max-age*=timestamp ] [ *--min-age*=timestamp ] [ *--bisect* ] [ *--pretty* ] [ *--objects* ] [ *--merge-order* [ *--show-breaks* ] ] <commit> [ <commit> ...] [ ^<commit> ...] + +DESCRIPTION +----------- +Lists commit objects in reverse chronological order starting at the +given commit(s), taking ancestry relationship into account. This is +useful to produce human-readable log output. + +Commits which are stated with a preceding '^' cause listing to stop at +that point. Their parents are implied. "git-rev-list foo bar ^baz" thus +means "list all the commits which are included in 'foo' and 'bar', but +not in 'baz'". + +If *--pretty* is specified, print the contents of the commit changesets +in human-readable form. + +The *--objects* flag causes 'git-rev-list' to print the object IDs of +any object referenced by the listed commits. 'git-rev-list --objects foo +^bar' thus means "send me all object IDs which I need to download if +I have the commit object 'bar', but not 'foo'". + +The *--bisect* flag limits output to the one commit object which is +roughly halfway between the included and excluded commits. Thus, +if "git-rev-list --bisect foo ^bar ^baz" outputs 'midpoint', the output +of "git-rev-list foo ^midpoint" and "git-rev-list midpoint ^bar ^baz" +would be of roughly the same length. Finding the change which introduces +a regression is thus reduced to a binary search: repeatedly generate and +test new 'midpoint's until the commit chain is of length one. + +If *--merge-order* is specified, the commit history is decomposed into a +unique sequence of minimal, non-linear epochs and maximal, linear epochs. +Non-linear epochs are then linearised by sorting them into merge order, which +is described below. + +Maximal, linear epochs correspond to periods of sequential development. +Minimal, non-linear epochs correspond to periods of divergent development +followed by a converging merge. The theory of epochs is described in more +detail at +link:http://blackcubes.dyndns.org/epoch/[http://blackcubes.dyndns.org/epoch/]. + +The merge order for a non-linear epoch is defined as a linearisation for which +the following invariants are true: + + 1. if a commit P is reachable from commit N, commit P sorts after commit N + in the linearised list. + 2. if Pi and Pj are any two parents of a merge M (with i < j), then any + commit N, such that N is reachable from Pj but not reachable from Pi, + sorts before all commits reachable from Pi. + +Invariant 1 states that later commits appear before earlier commits they are +derived from. + +Invariant 2 states that commits unique to "later" parents in a merge, appear +before all commits from "earlier" parents of a merge. + +If *--show-breaks* is specified, each item of the list is output with a +2-character prefix consisting of one of: (|), (^), (=) followed by a space. + +Commits marked with (=) represent the boundaries of minimal, non-linear epochs +and correspond either to the start of a period of divergent development or to +the end of such a period. + +Commits marked with (|) are direct parents of commits immediately preceding +the marked commit in the list. + +Commits marked with (^) are not parents of the immediately preceding commit. +These "breaks" represent necessary discontinuities implied by trying to +represent an arbtirary DAG in a linear form. + +*--show-breaks* is only valid if *--merge-order* is also specified. + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Original *--merge-order* logic by Jon Seymour <jon.seymour@gmail.com> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-rev-tree.txt b/Documentation/git-rev-tree.txt new file mode 100644 index 0000000000..2ec7ed073b --- /dev/null +++ b/Documentation/git-rev-tree.txt @@ -0,0 +1,88 @@ +git-rev-tree(1) +=============== +v0.1, May 2005 + +NAME +---- +git-rev-tree - Provides the revision tree for one or more commits + + +SYNOPSIS +-------- +'git-rev-tree' [--edges] [--cache <cache-file>] [^]<commit> [[^]<commit>] + +DESCRIPTION +----------- +Provides the revision tree for one or more commits. + +OPTIONS +------- +--edges:: + Show edges (ie places where the marking changes between parent + and child) + +--cache <cache-file>:: + Use the specified file as a cache from a previous git-rev-list run + to speed things up. Note that this "cache" is totally different + concept from the directory index. Also this option is not + implemented yet. + +[^]<commit>:: + The commit id to trace (a leading caret means to ignore this + commit-id and below) + +Output +------ + + <date> <commit>:<flags> [<parent-commit>:<flags> ]\* + +<date>:: + Date in 'seconds since epoch' + +<commit>:: + id of commit object + +<parent-commit>:: + id of each parent commit object (>1 indicates a merge) + +<flags>:: + + The flags are read as a bitmask representing each commit + provided on the commandline. eg: given the command: + + $ git-rev-tree <com1> <com2> <com3> + + The output: + + <date> <commit>:5 + + means that <commit> is reachable from <com1>(1) and <com3>(4) + +A revtree can get quite large. "git-rev-tree" will eventually allow +you to cache previous state so that you don't have to follow the whole +thing down. + +So the change difference between two commits is literally + + git-rev-tree [commit-id1] > commit1-revtree + git-rev-tree [commit-id2] > commit2-revtree + join -t : commit1-revtree commit2-revtree > common-revisions + +(this is also how to find the most common parent - you'd look at just +the head revisions - the ones that aren't referred to by other +revisions - in "common-revision", and figure out the best one. I +think.) + + +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 link:git.html[git] suite + diff --git a/Documentation/git-send-email-script.txt b/Documentation/git-send-email-script.txt new file mode 100644 index 0000000000..89f98bbf70 --- /dev/null +++ b/Documentation/git-send-email-script.txt @@ -0,0 +1,74 @@ +git-send-email-script(1) +======================= +v0.1, July 2005 + +NAME +---- +git-send-email-script - Send a collection of patches as emails + + +SYNOPSIS +-------- +'git-send-email-script' [options] <file|directory> [... file|directory] + + + +DESCRIPTION +----------- +Takes the patches given on the command line and emails them out. + +The header of the email is configurable by command line options. If not +specified on the command line, the user will be prompted with a ReadLine +enabled interface to provide the necessary information. + +The options available are: + + --to + Specify the primary recipient of the emails generated. + Generally, this will be the upstream maintainer of the + project involved. + + --from + Specify the sender of the emails. This will default to + the value GIT_COMMITTER_IDENT, as returned by "git-var -l". + The user will still be prompted to confirm this entry. + + --subject + Specify the initial subject of the email thread. + + --in-reply-to + Specify the contents of the first In-Reply-To header. + Subsequent emails will refer to the previous email + instead of this. + When overriding on the command line, it may be necessary + to set this to a space. For example + --in-reply-to=" " + + --chain-reply-to, --no-chain-reply-to + If this is set, each email will be sent as a reply to the previous + email sent. If disabled with "--no-chain-reply-to", all emails after + the first will be sent as replies to the first email sent. When using + this, it is recommended that the first file given be an overview of the + entire patch series. + Default is --chain-reply-to + + --smtp-server + If set, specifies the outgoing SMTP server to use. Defaults to + localhost. + + +Author +------ +Written by Ryan Anderson <ryan@michonline.com> + +git-send-email-script is originally based upon +send_lots_of_email.pl by Greg Kroah-Hartman. + +Documentation +-------------- +Documentation by Ryan Anderson + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-send-pack.txt b/Documentation/git-send-pack.txt new file mode 100644 index 0000000000..6192c5dc41 --- /dev/null +++ b/Documentation/git-send-pack.txt @@ -0,0 +1,92 @@ +git-send-pack(1) +================ +v0.1, July 2005 + +NAME +---- +git-send-pack - Push missing objects packed. + + +SYNOPSIS +-------- +'git-send-pack' [--all] [--exec=<git-receive-pack>] [<host>:]<directory> [<head>...] + +DESCRIPTION +----------- +Invokes 'git-receive-pack' on a possibly remote repository, and +updates it from the current repository, sending named heads. + + +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. + +<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. + +<head>...: + 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 '<head>' if you use +this flag. + +Without '--all' and without any '<head>', the refs that exist +both on the local side and on the remote side are updated. + +When '<head>'s are specified explicitly, it can be either a +single pattern, or a pair of such pattern separated by a colon +':' (this means that a ref name cannot have a colon in it). A +single pattern '<name>' is just a shorthand for '<name>:<name>'. +Each pattern pair consists of the source side (before the colon) +and the destination side (after the colon). The ref that is +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 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. + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by Junio C Hamano. + +GIT +--- +Part of the link:git.html[git] suite diff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt new file mode 100644 index 0000000000..6968ca6060 --- /dev/null +++ b/Documentation/git-shortlog.txt @@ -0,0 +1,31 @@ +git-shortlog(1) +=============== +v0.99.4, Aug 2005 + +NAME +---- +git-shortlog - Summarize 'git log' output. + + +SYNOPSIS +-------- +'git log --pretty=short | git shortlog' + +DESCRIPTION +----------- +Summarizes 'git log' output in a format suitable for inclusion +in release announcements. + + +Author +------ +Written by Jeff Garzik <jgarzik@pobox.com> + +Documentation +-------------- +Documentation by Junio C Hamano. + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-show-branches-script.txt b/Documentation/git-show-branches-script.txt new file mode 100644 index 0000000000..c7fb02cf7b --- /dev/null +++ b/Documentation/git-show-branches-script.txt @@ -0,0 +1,71 @@ +git-show-branches-script(1) +=========================== +v0.99.4, Aug 2005 + +NAME +---- +git-show-branches-script - Show branches and their commits. + +SYNOPSIS +-------- +'git show-branches <reference>...' + +DESCRIPTION +----------- +Shows the head commits from the named <reference> (or all refs under +$GIT_DIR/refs/heads), and displays concise list of commit logs +to show their relationship semi-visually. + +OPTIONS +------- +<reference>:: + Name of the reference under $GIT_DIR/refs/heads/. + + +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. + +The following example shows three branches, "pu", "master" and +"rc": + +------------------------------------------------ +* [pu] Add cheap local clone '-s' flag to git-clone-script + ! [master] Documentation updates. + ! [rc] Merge master into rc ++ Add cheap local clone '-s' flag to git-clone-script ++ Alternate object pool mechanism updates. ++ Audit rev-parse users. +++ Documentation updates. + + Merge master into rc ++++ [PATCH] plug memory leak in diff.c::diff_free_filepair() +------------------------------------------------ + +These three branches all forked from a common commit, "[PATCH] +plug memory leak...", and "rc" has one commit ahead of it. The +"master" branch has one different commit that is also shared by +"pu" branch, and "pu" branch has three more commits on top of +"master" branch. + + +Author +------ +Written by Junio C Hamano <junkio@cox.net> + + +Documentation +-------------- +Documentation by Junio C Hamano. + + +GIT +--- +Part of the link:git.html[git] suite diff --git a/Documentation/git-show-index.txt b/Documentation/git-show-index.txt new file mode 100644 index 0000000000..beefe947af --- /dev/null +++ b/Documentation/git-show-index.txt @@ -0,0 +1,36 @@ +git-show-index(1) +================= +v0.1, July 2005 + +NAME +---- +git-show-index - Show packed archive index + + +SYNOPSIS +-------- +'git-show-index' < idx-file + + +DESCRIPTION +----------- +Reads given idx file for packed GIT archive created with +git-pack-objects command, and dumps its contents. + +The information it outputs is subset of what you can get from +'git-verify-pack -v'; this command only shows the packfile +offset and SHA1 of each object. + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by Junio C Hamano + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-ssh-pull.txt b/Documentation/git-ssh-pull.txt new file mode 100644 index 0000000000..ac3fb342f0 --- /dev/null +++ b/Documentation/git-ssh-pull.txt @@ -0,0 +1,52 @@ +git-ssh-pull(1) +=============== +v0.1, May 2005 + +NAME +---- +git-ssh-pull - Pulls from a remote repository over ssh connection + + + +SYNOPSIS +-------- +'git-ssh-pull' [-c] [-t] [-a] [-d] [-v] [-w filename] [--recover] commit-id url + +DESCRIPTION +----------- +Pulls from a remote repository over ssh connection, invoking +git-ssh-push on the other end. It functions identically to +git-ssh-push, 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 link:git.html[git] suite + diff --git a/Documentation/git-ssh-push.txt b/Documentation/git-ssh-push.txt new file mode 100644 index 0000000000..e38679deb9 --- /dev/null +++ b/Documentation/git-ssh-push.txt @@ -0,0 +1,48 @@ +git-ssh-push(1) +=============== +v0.1, Jun 2005 + +NAME +---- +git-ssh-push - Pushes to a remote repository over ssh connection + + +SYNOPSIS +-------- +'git-ssh-push' [-c] [-t] [-a] [-d] [-v] [-w filename] [--recover] commit-id url + +DESCRIPTION +----------- +Pushes from a remote repository over ssh connection, invoking +git-ssh-pull on the other end. It functions identically to +git-ssh-pull, 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 link:git.html[git] suite + diff --git a/Documentation/git-status-script.txt b/Documentation/git-status-script.txt new file mode 100644 index 0000000000..2fb7f74a0f --- /dev/null +++ b/Documentation/git-status-script.txt @@ -0,0 +1,46 @@ +git-status-script(1) +==================== +v0.99.4, Aug 2005 + +NAME +---- +git-status-script - 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-cache' 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 link:git.html[git] suite + diff --git a/Documentation/git-tag-script.txt b/Documentation/git-tag-script.txt new file mode 100644 index 0000000000..5032acb172 --- /dev/null +++ b/Documentation/git-tag-script.txt @@ -0,0 +1,39 @@ +git-tag-script(1) +================= +v0.99.4, Aug 2005 + +NAME +---- +git-tag-script - Create a tag object signed with GPG + + + +SYNOPSIS +-------- +'git-tag-script' [-s | -a] [-f] <name> + +DESCRIPTION +----------- +Adds a "tag" reference in .git/refs/tags/ + +Unless "-f" is given, the tag must not yet exist in ".git/refs/tags" + +If "-s" or "-a" is passed, the user will be prompted for a tag message. +and a tag object is created. Otherwise just the SHA1 object +name of the commit object is written. + +A GnuPG signed tag object will be created when "-s" is used. + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org>, +Junio C Hamano <junkio@cox.net> and Chris Wright <chrisw@osdl.org>. + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the link:git.html[git] suite diff --git a/Documentation/git-tar-tree.txt b/Documentation/git-tar-tree.txt new file mode 100644 index 0000000000..9323dddfa7 --- /dev/null +++ b/Documentation/git-tar-tree.txt @@ -0,0 +1,39 @@ +git-tar-tree(1) +=============== +v0.1, May 2005 + +NAME +---- +git-tar-tree - Creates a tar archive of the files in the named tree + + +SYNOPSIS +-------- +'git-tar-tree' <tree-ish> [ <base> ] + +DESCRIPTION +----------- +Creates a tar archive containing the tree structure for the named tree. +When <base> is specified it is added as a leading path to the files in the +generated tar archive. + +git-tar-tree behaves differently when given a tree ID versus when given +a commit ID or tag ID. In the first case the current time is used as +modification time of each file in the archive. In the latter case the +commit time as recorded in the referenced commit object is used instead. +Additionally the commit ID is stored in a global extended pax header. +It can be extracted using git-get-tar-commit-id. + + +Author +------ +Written by Rene Scharfe. + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-unpack-file.txt b/Documentation/git-unpack-file.txt new file mode 100644 index 0000000000..2f2130d511 --- /dev/null +++ b/Documentation/git-unpack-file.txt @@ -0,0 +1,37 @@ +git-unpack-file(1) +================== +v0.1, May 2005 + +NAME +---- +git-unpack-file - Creates a temporary file with a blob's contents + + + +SYNOPSIS +-------- +'git-unpack-file' <blob> + +DESCRIPTION +----------- +Creates a file holding the contents of the blob specified by sha1. It +returns the name of the temporary file in the following format: + .merge_file_XXXXX + +OPTIONS +------- +<blob>:: + Must be a blob id + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-unpack-objects.txt b/Documentation/git-unpack-objects.txt new file mode 100644 index 0000000000..a42a75e077 --- /dev/null +++ b/Documentation/git-unpack-objects.txt @@ -0,0 +1,39 @@ +git-unpack-objects(1) +===================== +v0.1, July 2005 + +NAME +---- +git-unpack-objects - Unpack objects from a packed archive. + + +SYNOPSIS +-------- +'git-unpack-objects' [-q] <pack-file + + +DESCRIPTION +----------- +Reads a packed archive (.pack) from the standard input, and +expands the objects contained in the pack into "one-file +one-object" format in $GIT_OBJECT_DIRECTORY. + +OPTIONS +------- +-q:: + The command usually shows percentage progress. This + flag suppresses it. + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +------------- +Documentation by Junio C Hamano + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-update-cache.txt b/Documentation/git-update-cache.txt new file mode 100644 index 0000000000..7340e89c1f --- /dev/null +++ b/Documentation/git-update-cache.txt @@ -0,0 +1,126 @@ +git-update-cache(1) +=================== +v0.1, May 2005 + +NAME +---- +git-update-cache - Modifies the index or directory cache + + +SYNOPSIS +-------- +'git-update-cache' + [--add] [--remove] [--refresh] [--replace] + [--ignore-missing] + [--force-remove] + [--cacheinfo <mode> <object> <file>]\* + [--info-only] + [--] [<file>]\* + +DESCRIPTION +----------- +Modifies the index or directory cache. Each file mentioned is updated +into the cache and any 'unmerged' or 'needs updating' state is +cleared. + +The way "git-update-cache" handles files it is told about can be modified +using the various options: + +OPTIONS +------- +--add:: + If a specified file isn't in the cache already then it's + added. + Default behaviour is to ignore new files. + +--remove:: + If a specified file is in the cache but is missing then it's + removed. + Default behaviour is to ignore removed file. + +--refresh:: + Looks at the current cache and checks to see if merges or + updates are needed by checking stat() information. + +--ignore-missing:: + Ignores missing files during a --refresh + +--cacheinfo <mode> <object> <path>:: + Directly insert the specified info into the cache. + +--info-only:: + Do not create objects in the object database for all + <file> arguments that follow this flag; just insert + their object IDs into the cache. + +--force-remove:: + Remove the file from the index even when the working directory + still has such a file. (Implies --remove.) + +--replace:: + By default, when a file `path` exists in the index, + git-update-cache refuses an attempt to add `path/file`. + Similarly if a file `path/file` exists, a file `path` + cannot be added. With --replace flag, existing entries + that conflicts with the entry being added are + automatically removed with warning messages. + +--:: + Do not interpret any more arguments as options. + +<file>:: + Files to act on. + Note that files begining with '.' are discarded. This includes + `./file` and `dir/./file`. If you don't want this, then use + cleaner names. + The same applies to directories ending '/' and paths with '//' + +Using --refresh +--------------- +'--refresh' does not calculate a new sha1 file or bring the cache +up-to-date for mode/content changes. But what it *does* do is to +"re-match" the stat information of a file with the cache, so that you +can refresh the cache for a file that hasn't been changed but where +the stat entry is out of date. + +For example, you'd want to do this after doing a "git-read-tree", to link +up the stat cache details with the proper files. + +Using --cacheinfo or --info-only +-------------------------------- +'--cacheinfo' is used to register a file that is not in the +current working directory. This is useful for minimum-checkout +merging. + + To pretend you have a file with mode and sha1 at path, say: + + $ git-update-cache --cacheinfo mode sha1 path + +'--info-only' is used to register files without placing them in the object +database. This is useful for status-only repositories. + +Both '--cacheinfo' and '--info-only' behave similarly: the index is updated +but the object database isn't. '--cacheinfo' is useful when the object is +in the database but the file isn't available locally. '--info-only' is +useful when the file is available, but you do not wish to update the +object database. + +Examples +-------- +To update and refresh only the files already checked out: + + git-checkout-cache -n -f -a && git-update-cache --ignore-missing --refresh + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-update-server-info.txt b/Documentation/git-update-server-info.txt new file mode 100644 index 0000000000..830f398034 --- /dev/null +++ b/Documentation/git-update-server-info.txt @@ -0,0 +1,42 @@ +git-update-server-info(1) +========================= +v0.1, July 2005 + +NAME +---- +git-update-server-info - Update auxiliary info file to help dumb servers + + +SYNOPSIS +-------- +'git-update-server-info' [--force] + +DESCRIPTION +----------- +A dumb server that does not do on-the-fly pack generations can +have some auxiliary information files in $GIT_DIR/info and +$GIT_OBJECT_DIRECTORY/info directories to help clients discover +what references and packs the server has and make optimized +pull decisions. This command generates such auxiliary files. + + +OPTIONS +------- + +--force:: + Update the info files even when they do not appear + stale. + + +Author +------ +Written by Junio C Hamano <junkio@cox.net> + +Documentation +-------------- +Documentation by Junio C Hamano. + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-upload-pack.txt b/Documentation/git-upload-pack.txt new file mode 100644 index 0000000000..be597a1787 --- /dev/null +++ b/Documentation/git-upload-pack.txt @@ -0,0 +1,40 @@ +git-upload-pack(1) +================== +v0.1, July 2005 + +NAME +---- +git-upload-pack - Send missing objects packed. + + +SYNOPSIS +-------- +'git-upload-pack' <directory> + +DESCRIPTION +----------- +Invoked by 'git-clone-pack' and/or 'git-fetch-pack', learns what +objects the other side is missing, and sends them after packing. + +This command is usually not invoked directly by the end user. +The UI for the protocol is on the 'git-fetch-pack' side, and the +program pair is meant to be used to pull updates from a remote +repository. For push operations, see 'git-send-pack'. + + +OPTIONS +------- +<directory>:: + The repository to sync from. + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by Junio C Hamano. + +GIT +--- +Part of the link:git.html[git] suite diff --git a/Documentation/git-var.txt b/Documentation/git-var.txt new file mode 100644 index 0000000000..45b100694a --- /dev/null +++ b/Documentation/git-var.txt @@ -0,0 +1,60 @@ +git-var(1) +========== +v0.1, July 2005 + +NAME +---- +git-var - Print the git users identity + + +SYNOPSIS +-------- +git-var [ -l | <variable> ] + +DESCRIPTION +----------- +Prints a git logical variable. + +-l causes the logical variables to be listed. + +EXAMPLE +-------- +$git-var GIT_AUTHOR_IDENT + +Eric W. Biederman <ebiederm@lnxi.com> 1121223278 -0600 + + +VARIABLES +---------- +GIT_AUTHOR_IDENT + The author of a piece of code. + +GIT_COMMITTER_IDENT + The person who put a piece of code into git. + +Diagnostics +----------- +You don't exist. Go away!:: + The passwd(5) gecos field couldn't be read +Your parents must have hated you!:: + The password(5) gecos field is longer than a giant static buffer. +Your sysadmin must hate you!:: + The password(5) name field is longer than a giant static buffer. + +See Also +-------- +link:git-commit-tree.html[git-commit-tree] +link:git-tag-script.html[git-tag-script] + +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 link:git.html[git] suite + diff --git a/Documentation/git-verify-pack.txt b/Documentation/git-verify-pack.txt new file mode 100644 index 0000000000..d1043eb8df --- /dev/null +++ b/Documentation/git-verify-pack.txt @@ -0,0 +1,49 @@ +git-verify-pack(1) +================== +v0.1, June 2005 + +NAME +---- +git-verify-pack - Validate packed GIT archive files. + + +SYNOPSIS +-------- +'git-verify-pack' [-v] <pack>.idx ... + + +DESCRIPTION +----------- +Reads given idx file for packed GIT archive created with +git-pack-objects command and verifies idx file and the +corresponding pack file. + +OPTIONS +------- +<pack>.idx ...:: + The idx files to verify. + +-v:: + After verifying the pack, show list of objects contained + in the pack. The format used is: + + SHA1 type size offset-in-packfile + + for objects that are not deltified in the pack, and + + SHA1 type size offset-in-packfile depth base-SHA1 + + for objects that are deltified. + +Author +------ +Written by Junio C Hamano <junkio@cox.net> + +Documentation +-------------- +Documentation by Junio C Hamano + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-whatchanged.txt b/Documentation/git-whatchanged.txt new file mode 100644 index 0000000000..742005353a --- /dev/null +++ b/Documentation/git-whatchanged.txt @@ -0,0 +1,61 @@ +git-whatchanged(1) +================== +v0.99.4, Aug 2005 + +NAME +---- +git-whatchanged - Show logs with difference each commit introduces. + + +SYNOPSIS +-------- +'git whatchanged' <option>... + +DESCRIPTION +----------- +Shows commit logs and diff output each commit introduces. The +command internally invokes 'git-rev-list' piped to +'git-diff-tree', and takes command line options for both of +these commands. + +This manual page describes only the most frequently used options. + + +OPTIONS +------- +-p:: + Show textual diffs, instead of the git internal diff + output format that is useful only to tell the changed + paths and their nature of changes. + +--max-count=<n>:: + Limit output to <n> commits. + +<since>..<until>:: + Limit output to between the two named commits (bottom + exclusive, top inclusive). + +-r:: + Show git internal diff output, but for the whole tree, + not just the top level. + +--pretty=<format>:: + Controls the output format for the commit logs. + <format> can be one of 'raw', 'medium', 'short', 'full', + and 'oneline'. + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> and +Junio C Hamano <junkio@cox.net> + + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-write-tree.txt b/Documentation/git-write-tree.txt new file mode 100644 index 0000000000..3cf8c934c1 --- /dev/null +++ b/Documentation/git-write-tree.txt @@ -0,0 +1,43 @@ +git-write-tree(1) +================= +v0.1, May 2005 + +NAME +---- +git-write-tree - Creates a tree object from the current cache + + +SYNOPSIS +-------- +'git-write-tree' [--missing-ok] + +DESCRIPTION +----------- +Creates a tree object using the current cache. + +The cache must be merged. + +Conceptually, "git-write-tree" sync()s the current directory cache contents +into a set of tree files. +In order to have that match what is actually in your directory right +now, you need to have done a "git-update-cache" 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 link:git.html[git] suite + diff --git a/Documentation/git.txt b/Documentation/git.txt new file mode 100644 index 0000000000..be26614ffb --- /dev/null +++ b/Documentation/git.txt @@ -0,0 +1,405 @@ +git(7) +====== +v0.99.4, Aug 2005 + +NAME +---- +git - the stupid content tracker + + +SYNOPSIS +-------- +'git-<command>' <args> + +DESCRIPTION +----------- + +This is reference information for the core git commands. + +The Discussion section below contains much useful definition and +clarification info - read that first. And of the commands, I suggest +reading link:git-update-cache.html[git-update-cache] and +link:git-read-tree.html[git-read-tree] first - I wish I had! + +David Greaves <david@dgreaves.com> +08/05/05 + +Updated by Junio C Hamano <junkio@cox.net> on 2005-05-05 to +reflect recent changes. + +Commands Overview +----------------- +The git commands can helpfully be split into those that manipulate +the repository, the cache and the working fileset, those that +interrogate and compare them, and those that moves objects and +references between repositories. + +In addition, git itself comes with a spartan set of porcelain +commands. They are usable but are not meant to compete with real +Porcelains. + +There are also some ancillary programs that can be viewed as useful +aids for using the core commands but which are unlikely to be used by +SCMs layered over git. + +Manipulation commands +~~~~~~~~~~~~~~~~~~~~~ +link:git-checkout-cache.html[git-checkout-cache]:: + Copy files from the cache to the working directory + +link:git-commit-tree.html[git-commit-tree]:: + Creates a new commit object + +link:git-init-db.html[git-init-db]:: + Creates an empty git object database + +link:git-merge-base.html[git-merge-base]:: + Finds as good a common ancestor as possible for a merge + +link:git-mktag.html[git-mktag]:: + Creates a tag object + +link:git-read-tree.html[git-read-tree]:: + Reads tree information into the directory cache + +link:git-update-cache.html[git-update-cache]:: + Modifies the index or directory cache + +link:git-hash-object.html[git-hash-object]:: + Computes the object ID from a file. + +link:git-write-tree.html[git-write-tree]:: + Creates a tree from the current cache + +link:git-pack-objects.html[git-pack-objects]:: + Creates a packed archive of objects. + +link:git-unpack-objects.html[git-unpack-objects]:: + Unpacks objects out of a packed archive. + +link:git-prune-packed.html[git-prune-packed]:: + Remove extra objects that are already in pack files. + +link:git-apply.html[git-apply]:: + Reads a "diff -up1" or git generated patch file and + applies it to the working tree. + + +Interrogation commands +~~~~~~~~~~~~~~~~~~~~~~ +link:git-cat-file.html[git-cat-file]:: + Provide content or type information for repository objects + +link:git-diff-cache.html[git-diff-cache]:: + Compares content and mode of blobs between the cache and repository + +link:git-diff-files.html[git-diff-files]:: + Compares files in the working tree and the cache + +link:git-diff-tree.html[git-diff-tree]:: + Compares the content and mode of blobs found via two tree objects + +link:git-diff-stages.html[git-diff-stages]:: + Compares two "merge stages" in the index file. + +link:git-export.html[git-export]:: + Exports each commit and a diff against each of its parents + +link:git-fsck-cache.html[git-fsck-cache]:: + Verifies the connectivity and validity of the objects in the database + +link:git-ls-files.html[git-ls-files]:: + Information about files in the cache/working directory + +link:git-ls-tree.html[git-ls-tree]:: + Displays a tree object in human readable form + +link:git-merge-cache.html[git-merge-cache]:: + Runs a merge for files needing merging + +link:git-rev-list.html[git-rev-list]:: + Lists commit objects in reverse chronological order + +link:git-rev-tree.html[git-rev-tree]:: + Provides the revision tree for one or more commits + +link:git-tar-tree.html[git-tar-tree]:: + Creates a tar archive of the files in the named tree + +link:git-unpack-file.html[git-unpack-file]:: + Creates a temporary file with a blob's contents + +link:git-var.html[git-var]:: + Displays a git logical variable + +link:git-show-index.html[git-show-index]:: + Displays contents of a pack idx file. + +link:git-verify-pack.html[git-verify-pack]:: + Validates packed GIT archive files + +The interrogate commands may create files - and you can force them to +touch the working file set - but in general they don't + + +Synching repositories +~~~~~~~~~~~~~~~~~~~~~ + +link:git-clone-script.html[git-clone-script]:: + Clones a repository into the current repository (user interface) + +link:git-clone-pack.html[git-clone-pack]:: + Clones a repository into the current repository (engine + for ssh and local transport) + +link:git-http-pull.html[git-http-pull]:: + Downloads a remote GIT repository via HTTP + +link:git-local-pull.html[git-local-pull]:: + Duplicates another GIT repository on a local system + +link:git-ssh-pull.html[git-ssh-pull]:: + Pulls from a remote repository over ssh connection + +link:git-send-pack.html[git-send-pack]:: + Pushes to a remote repository, intelligently. + +link:git-receive-pack.html[git-receive-pack]:: + Invoked by 'git-send-pack' to receive what is pushed to it. + +link:git-clone-pack.html[git-clone-pack]:: + Clones from a remote repository. + +link:git-fetch-pack.html[git-fetch-pack]:: + Updates from a remote repository. + +link:git-peek-remote.html[git-peek-remote]:: + Lists references on a remote repository using upload-pack protocol. + +link:git-upload-pack.html[git-upload-pack]:: + Invoked by 'git-clone-pack' and 'git-fetch-pack' to push + what are asked for. + +link:git-update-server-info.html[git-update-server-info]:: + Updates auxiliary information on a dumb server to help + clients discover references and packs on it. + + +Porcelain-ish Commands +---------------------- +link:git-whatchanged.html[git-whatchanged]:: + Shows commit logs and differences they introduce. + +link:git-log-script.html[git-log-script]:: + Shows commit logs. + +link:git-shortlog.html[git-shortlog]:: + Summarizes 'git log' output. + +link:git-status-script.html[git-status-script]:: + Shows the working tree status. + +link:git-fetch-script.html[git-fetch-script]:: + Download from a remote repository via various protocols. + +link:git-pull-script.html[git-pull-script]:: + Fetch from and merge with a remote repository. + +link:git-commit-script.html[git-commit-script]:: + Record changes to the repository. + +link:git-show-branches-script.html[git-show-branches-script]:: + Show branches and their commits. + +link:git-repack-script.html[git-repack-script]:: + Pack unpacked objects in a repository. + +link:git-rename-script.html[git-rename]:: + Rename files and directories. + +link:git-ls-remote-script.html[git-ls-remote-script]:: + Shows references in a remote or local repository. + + +Ancillary Commands +------------------ +Manipulators: + +link:git-apply-patch-script.html[git-apply-patch-script]:: + Sample script to apply the diffs from git-diff-* + +link:git-convert-cache.html[git-convert-cache]:: + Converts old-style GIT repository + +link:git-merge-one-file-script.html[git-merge-one-file-script]:: + The standard helper program to use with "git-merge-cache" + +link:git-prune-script.html[git-prune-script]:: + Prunes all unreachable objects from the object database + +link:git-resolve-script.html[git-resolve-script]:: + Script used to merge two trees + +link:git-tag-script.html[git-tag-script]:: + An example script to create a tag object signed with GPG + +link:git-cvsimport-script.html[git-cvsimport-script]:: + Salvage your data out of another SCM people love to hate. + + +Interrogators: + +link:git-diff-helper.html[git-diff-helper]:: + Generates patch format output for git-diff-* + +link:git-ssh-push.html[git-ssh-push]:: + Helper "server-side" program used by git-ssh-pull + +link:git-send-email-script.html[git-send-email]:: + Send patch e-mails out of "format-patch --mbox" output. + + +Identifier Terminology +---------------------- +<object>:: + Indicates the sha1 identifier for any type of object + +<blob>:: + Indicates a blob object sha1 identifier + +<tree>:: + Indicates a tree object sha1 identifier + +<commit>:: + Indicates a commit object sha1 identifier + +<tree-ish>:: + Indicates a tree, commit or tag object sha1 identifier. A + command that takes a <tree-ish> argument ultimately wants to + operate on a <tree> object but automatically dereferences + <commit> and <tag> objects that point at a <tree>. + +<type>:: + Indicates that an object type is required. + Currently one of: blob/tree/commit/tag + +<file>:: + Indicates a filename - always relative to the root of + the tree structure GIT_INDEX_FILE describes. + +Symbolic Identifiers +-------------------- +Any git command accepting any <object> can also use the following +symbolic notation: + +HEAD:: + indicates the head of the repository (ie the contents of + `$GIT_DIR/HEAD`) +<tag>:: + a valid tag 'name'+ + (ie the contents of `$GIT_DIR/refs/tags/<tag>`) +<head>:: + a valid head 'name'+ + (ie the contents of `$GIT_DIR/refs/heads/<head>`) +<snap>:: + a valid snapshot 'name'+ + (ie the contents of `$GIT_DIR/refs/snap/<snap>`) + + +File/Directory Structure +------------------------ +The git-core manipulates the following areas in the directory: + + .git/ The base (overridden with $GIT_DIR) + objects/ The object base (overridden with $GIT_OBJECT_DIRECTORY) + ??/ 'First 2 chars of object' directories. + pack/ Packed archives. + + refs/ Directories containing symbolic names for objects + (each file contains the hex SHA1 + newline) + heads/ Commits which are heads of various sorts + tags/ Tags, by the tag name (or some local renaming of it) + */ Any other subdirectory of refs/ can be used to store + files similar to what are under refs/heads/. + HEAD Symlink to refs/heads/<current-branch-name> + +Higher level SCMs may provide and manage additional information in the +GIT_DIR. + +Terminology +----------- +Each line contains terms which you may see used interchangeably + + object database, .git directory + directory cache, index + id, sha1, sha1-id, sha1 hash + type, tag + + +Environment Variables +--------------------- +Various git commands use the following environment variables: + +The git Repository +~~~~~~~~~~~~~~~~~~ +These environment variables apply to 'all' core git commands. Nb: it +is worth noting that they may be used/overridden by SCMS sitting above +git so take care if using Cogito etc + +'GIT_INDEX_FILE':: + This environment allows the specification of an alternate + cache/index file. If not specified, the default of + `$GIT_DIR/index` is used. + +'GIT_OBJECT_DIRECTORY':: + If the object storage directory is specified via this + environment variable then the sha1 directories are created + underneath - otherwise the default `$GIT_DIR/objects` + directory is used. + +'GIT_ALTERNATE_OBJECT_DIRECTORIES':: + Due to the immutable nature of git objects, old objects can be + archived into shared, read-only directories. This variable + specifies a ":" separated list of git object directories which + can be used to search for git objects. New objects will not be + written to these directories. + +'GIT_DIR':: + If the 'GIT_DIR' environment variable is set then it specifies + a path to use instead of `./.git` for the base of the + repository. + +git Commits +~~~~~~~~~~~ +'GIT_AUTHOR_NAME':: +'GIT_AUTHOR_EMAIL':: +'GIT_AUTHOR_DATE':: +'GIT_COMMITTER_NAME':: +'GIT_COMMITTER_EMAIL':: + see link:git-commit-tree.html[git-commit-tree] + +git Diffs +~~~~~~~~~ +'GIT_DIFF_OPTS':: +'GIT_EXTERNAL_DIFF':: + see the "generating patches" section in : + link:git-diff-cache.html[git-diff-cache]; + link:git-diff-files.html[git-diff-files]; + link:git-diff-tree.html[git-diff-tree] + +Discussion +---------- +include::../README[] + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> and the git-list <git@vger.kernel.org>. + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/glossary.txt b/Documentation/glossary.txt new file mode 100644 index 0000000000..015d51018d --- /dev/null +++ b/Documentation/glossary.txt @@ -0,0 +1,216 @@ +object:: + The unit of storage in GIT. It is uniquely identified by + the SHA1 of its contents. Consequently, an object can not + be changed. + +object name:: + The unique identifier of an object. The hash of the object's contents + using the Secure Hash Algorithm 1 and usually represented by the 40 + character hexadecimal encoding of the hash of the object (possibly + followed by a white space). + +SHA1:: + Synonym for object name. + +object identifier:: + Synonym for object name. + +hash:: + In git's context, synonym to object name. + +object database:: + Stores a set of "objects", and an individial object is identified + by its object name. The object usually live in $GIT_DIR/objects/. + +blob object:: + Untyped object, e.g. the contents of a file. + +tree object:: + An object containing a list of blob and/or tree objects. + (A tree usually corresponds to a directory without + subdirectories). + +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). + +index:: + A collection of files with stat information, whose contents are + stored as objects. The cache is a stored version of your working + tree. Truth be told, it can also contain a second, and even a third + version of a working tree, which are used when merging. + +index entry:: + The information regarding a particular file, stored in the index. + An index entry can be unmerged, if a merge was started, but not + yet finished (i.e. if the cache contains multiple versions of + that file). + +unmerged index: + An index which contains unmerged index entries. + +cache:: + Obsolete for: index. + +working tree:: + The set of files and directories currently being worked on, + i.e. you can work in your working tree without using git at all. + +directory:: + The list you get with "ls" :-) + +revision:: + A particular state of files and directories which was stored in + the object database. It is referenced by a commit object. + +checkout:: + The action of updating the working tree to a revision which was + stored in the object database. + +commit:: + As a verb: The action of storing the current state of the cache in the + object database. The result is a revision. + As a noun: Short hand for commit object. + +commit object:: + An object which contains the information about a particular + revision, such as parents, committer, author, date and the + tree object which corresponds to the top directory of the + stored revision. + +parent:: + A commit object contains a (possibly empty) list of the logical + predecessor(s) in the line of development, i.e. its parents. + +changeset:: + BitKeeper/cvsps speak for "commit". Since git does not store + changes, but states, it really does not make sense to use + the term "changesets" with git. + +clean:: + A working tree is clean, if it corresponds to the revision + referenced by the current head. + +dirty:: + A working tree is said to be dirty if it contains modifications + which have not been committed to the current branch. + +head:: + The top of a branch. It contains a ref to the corresponding + commit object. + +branch:: + A non-cyclical graph of revisions, i.e. the complete history of + a particular revision, which is called the branch head. The + branch heads are stored in $GIT_DIR/refs/heads/. + +ref:: + A 40-byte hex representation of a SHA1 pointing to a particular + object. These may be stored in $GIT_DIR/refs/. + +head ref:: + A ref pointing to a head. Often, this is abbreviated to "head". + Head refs are stored in $GIT_DIR/refs/heads/. + +tree-ish:: + A ref pointing to either a commit object, a tree object, or a + tag object pointing to a tag or commit or tree object. + +ent:: + Favorite synonym to "tree-ish" by some total geeks. + +tag object:: + An object containing a ref pointing to another object. It can + contain a (PGP) signature, in which case it is called "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. + +resolve:: + The action of fixing up manually what a failed automatic merge + left behind. + +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. + +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/howto/make-dist.txt b/Documentation/howto/make-dist.txt new file mode 100644 index 0000000000..ae9094157c --- /dev/null +++ b/Documentation/howto/make-dist.txt @@ -0,0 +1,47 @@ +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 + +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-script v$new" + echo "git-tar-tree v$new linux-$new | gzip -9 > ../linux-$new.tar.gz" + echo "git-diff-tree -p v$stable v$new | gzip -9 > ../patch-$new.gz" + echo "git-rev-list --pretty v$new ^v$last > ../ChangeLog-$new" + echo "git-rev-list --pretty=short v$new ^v$last | git-shortlog > ../ShortLog" + echo "git-diff-tree -p v$last v$new | git-apply --stat > ../diffstat-$new" + +and when I want to do a new kernel release I literally first tag it, and +then do + + release-script 2.6.12 2.6.13-rc6 2.6.13-rc7 + +and check that things look sane, and then just cut-and-paste the commands. + +Yeah, it's stupid. + + Linus + diff --git a/Documentation/howto/rebase-and-edit.txt b/Documentation/howto/rebase-and-edit.txt new file mode 100644 index 0000000000..8299ca5cdc --- /dev/null +++ b/Documentation/howto/rebase-and-edit.txt @@ -0,0 +1,78 @@ +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 + +On Sat, 13 Aug 2005, Linus Torvalds wrote: + +> That's correct. Same things apply: you can move a patch over, and create a +> new one with a modified comment, but basically the _old_ commit will be +> immutable. + +Let me clarify. + +You can entirely _drop_ old branches, so commits may be immutable, but +nothing forces you to keep them. Of course, when you drop a commit, you'll +always end up dropping all the commits that depended on it, and if you +actually got somebody else to pull that commit you can't drop it from +_their_ repository, but undoing things is not impossible. + +For example, let's say that you've made a mess of things: you've committed +three commits "old->a->b->c", and you notice that "a" was broken, but you +want to save "b" and "c". What you can do is + + # Create a branch "broken" that is the current code + # for reference + git branch broken + + # Reset the main branch to three parents back: this + # effectively undoes the three top commits + git reset HEAD^^^ + git checkout -f + + # Check the result visually to make sure you know what's + # going on + gitk --all + + # Re-apply the two top ones from "broken" + # + # First "parent of broken" (aka b): + git-diff-tree -p broken^ | git-apply --index + git commit --reedit=broken^ + + # Then "top of broken" (aka c): + git-diff-tree -p broken | git-apply --index + git commit --reedit=broken + +and you've now re-applied (and possibly edited the comments) the two +commits b/c, and commit "a" is basically gone (it still exists in the +"broken" branch, of course). + +Finally, check out the end result again: + + # Look at the new commit history + gitk --all + +to see that everything looks sensible. + +And then, you can just remove the broken branch if you decide you really +don't want it: + + # remove 'broken' branch + rm .git/refs/heads/broken + + # Prune old objects if you're really really sure + git prune + +And yeah, I'm sure there are other ways of doing this. And as usual, the +above is totally untested, and I just wrote it down in this email, so if +I've done something wrong, you'll have to figure it out on your own ;) + + Linus +- +To unsubscribe from this list: send the line "unsubscribe git" in +the body of a message to majordomo@vger.kernel.org +More majordomo info at http://vger.kernel.org/majordomo-info.html + + diff --git a/Documentation/howto/rebase-from-internal-branch.txt b/Documentation/howto/rebase-from-internal-branch.txt new file mode 100644 index 0000000000..8109b7ff26 --- /dev/null +++ b/Documentation/howto/rebase-from-internal-branch.txt @@ -0,0 +1,163 @@ +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 + +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 git-apply-patch-script.txt ... + $ cd ..; git add Documentation/*.txt + $ git commit -s -v + +NOTE. The -v flag to commit is a handy way to make sure that +your additions are not introducing bogusly formatted lines. + +After the commit, the ancestry graph would look like this: + + *"pu" head + master^ --> #1 --> #2 --> #3 + \ + \---> master + +The old master is now master^ (the first parent of the master). +The new master commit holds my documentation updates. + +Now I have to deal with "pu" branch. + +This is the kind of situation I used to have all the time when +Linus was the maintainer and I was a contributor, when you look +at "master" branch being the "maintainer" branch, and "pu" +branch being the "contributor" branch. Your work started at the +tip of the "maintainer" branch some time ago, you made a lot of +progress in the meantime, and now the maintainer branch has some +other commits you do not have yet. And "git rebase" was written +with the explicit purpose of helping to maintain branches like +"pu". You _could_ merge master to pu and keep going, but if you +eventually want to cherrypick and merge some but not necessarily +all changes back to the master branch, it often makes later +operations for _you_ easier if you rebase (i.e. carry forward +your changes) "pu" rather than merge. So I ran "git rebase": + + $ git checkout pu + $ git rebase master pu + +What this does is to pick all the commits since the current +branch (note that I now am on "pu" branch) forked from the +master branch, and forward port these changes. + + master^ --> #1 --> #2 --> #3 + \ *"pu" head + \---> master --> #1' --> #2' --> #3' + +The diff between master^ and #1 is applied to master and +committed to create #1' commit with the commit information (log, +author and date) taken from commit #1. On top of that #2' and #3' +commits are made similarly out of #2 and #3 commits. + +Old #3 is not recorded in any of the .git/refs/heads/ file +anymore, so after doing this you will have dangling commit if +you ran fsck-cache, which is normal. After testing "pu", you +can run "git prune" to get rid of those original three commits. + +While I am talking about "git rebase", I should talk about how +to do cherrypicking using only the core GIT tools. + +Let's go back to the earlier picture, with different labels. + +You, as an individual developer, cloned upstream repository and +amde a couple of commits on top of it. + + *your "master" head + upstream --> #1 --> #2 --> #3 + +You would want changes #2 and #3 incorporated in the upstream, +while you feel that #1 may need further improvements. So you +prepare #2 and #3 for e-mail submission. + + $ git format-patch master^^ master + +This creates two files, 0001-XXXX.txt and 0002-XXXX.txt. Send +them out "To: " your project maintainer and "Cc: " your mailing +list. You could use contributed script git-send-email-script 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/using-topic-branches.txt b/Documentation/howto/using-topic-branches.txt new file mode 100644 index 0000000000..52fa4c012a --- /dev/null +++ b/Documentation/howto/using-topic-branches.txt @@ -0,0 +1,264 @@ +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?) + +Here's something that I've been putting together on how I'm using +GIT as a Linux subsystem maintainer. + +I suspect that I'm a bit slap-happy with the "git checkout" commands in +the examples below, and perhaps missing some of the _true-git_ ways of +doing things. + +-Tony + +Linux subsystem maintenance using GIT +------------------------------------- + +My requirements here are to be able to create two public trees: + +1) A "test" tree into which patches are initially placed so that they +can get some exposure when integrated with other ongoing development. +This tree is available to Andrew for pulling into -mm whenever he wants. + +2) A "release" tree into which tested patches are moved for final +sanity checking, and as a vehicle to send them upstream to Linus +(by sending him a "please pull" request.) + +Note that the period of time that each patch spends in the "test" tree +is dependent on the complexity of the change. Since GIT does not support +cherry picking, it is not practical to simply apply all patches to the +test tree and then pull to the release tree as that would leave trivial +patches blocked in the test tree waiting for complex changes to accumulate +enough test time to graduate. + +Back in the BitKeeper days I achieved this my creating small forests of +temporary trees, one tree for each logical grouping of patches, and then +pulling changes from these trees first to the test tree, and then to the +release tree. At first I replicated this in GIT, but then I realised +that I could so this far more efficiently using branches inside a single +GIT repository. + +So here is the step-by-step guide how this all works for me. + +First create your work tree by cloning Linus's public tree: + + $ git clone rsync://rsync.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git work + +Change directory into the cloned tree you just created + + $ cd work + +Make a GIT branch named "linus", and rename the "origin" branch as linus too: + + $ git checkout -b linus + $ mv .git/branches/origin .git/branches/linus + +The "linus" branch will be used to track the upstream kernel. To update it, +you simply run: + + $ git checkout linus && git pull linus + +you can do this frequently (as long as you don't have any uncommited work +in your tree). + +If you need to keep track of other public trees, you can add branches for +them too: + + $ git checkout -b another linus + $ echo URL-for-another-public-tree > .git/branches/another + +Now create the branches in which you are going to work, these start +out at the current tip of the linus branch. + + $ git branch test linus + $ git branch release linus + +These can be easily kept up to date by merging from the "linus" branch: + + $ git checkout test && git resolve test linus "Auto-update from upstream" + $ git checkout release && git resolve release linus "Auto-update from upstream" + +Set up so that you can push upstream to your public tree: + + $ echo master.kernel.org:/ftp/pub/scm/linux/kernel/git/aegl/linux-2.6.git > .git/branches/origin + +and then push each of the test and release branches using: + + $ git push origin test +and + $ git push origin release + +Now to apply some patches from the community. Think of a short +snappy name for a branch to hold this patch (or related group of +patches), and create a new branch from the current tip of the +linus branch: + + $ git checkout -b speed-up-spinlocks linus + +Now you apply the patch(es), run some tests, and commit the change(s). If +the patch is a multi-part series, then you should apply each as a separate +commit to this branch. + + $ ... patch ... test ... commit [ ... patch ... test ... commit ]* + +When you are happy with the state of this change, you can pull it into the +"test" branch in preparation to make it public: + + $ git checkout test && git resolve test speed-up-spinlocks "Pull speed-up-spinlock changes" + +It is unlikely that you would have any conflicts here ... but you might if you +spent a while on this step and had also pulled new versions from upstream. + +Some time later when enough time has passed and testing done, you can pull the +same branch into the "release" tree ready to go upstream. This is where you +see the value of keeping each patch (or patch series) in its own branch. It +means that the patches can be moved into the "release" tree in any order. + + $ git checkout release && git resolve release speed-up-spinlocks "Pull speed-up-spinlock changes" + +After a while, you will have a number of branches, and despite the +well chosen names you picked for each of them, you may forget what +they are for, or what status they are in. To get a reminder of what +changes are in a specific branch, use: + + $ git-whatchanged branchname ^linus | git-shortlog + +To see whether it has already been merged into the test or release branches +use: + + $ git-rev-list branchname ^test +or + $ git-rev-list branchname ^release + +[If this branch has not yet been merged you will see a set of SHA1 values +for the commits, if it has been merged, then there will be no output] + +Once a patch completes the great cycle (moving from test to release, then +pulled by Linus, and finally coming back into your local "linus" branch) +the branch for this change is no longer needed. You detect this when the +output from: + + $ git-rev-list branchname ^linus + +is empty. At this point the branch can be deleted: + + $ rm .git/refs/heads/branchname + +Some changes are so trivial that it is not necessary to create a separate +branch and then merge into each of the test and release branches. For +these changes, just apply directly to the "release" branch, and then +merge that into the "test" branch. + +To create diffstat and shortlog summaries of changes to include in a "please +pull" request to Linus you can use: + + $ git-whatchanged -p release ^linus | diffstat -p1 +and + $ git-whatchanged release ^linus | git-shortlog + + +Here are some of the scripts that I use to simplify all this even further. + +==== update script ==== +# Update a branch in my GIT tree. If the branch to be updated +# is "linus", then pull from kernel.org. Otherwise merge local +# linus branch into test|release branch + +case "$1" in +test|release) + git checkout $1 && git resolve $1 linus "Auto-update from upstream" + ;; +linus) + before=$(cat .git/HEAD) + git checkout linus && git pull linus + after=$(cat .git/HEAD) + if [ $before != $after ] + then + git-whatchanged $after ^$before | git-shortlog + fi + ;; +*) + echo "Usage: $0 linus|test|release" 1>&2 + exit 1 + ;; +esac + +==== merge script ==== +# Merge a branch into either the test or release branch + +pname=$0 + +usage() +{ + echo "Usage: $pname branch test|release" 1>&2 + exit 1 +} + +if [ ! -f .git/refs/heads/"$1" ] +then + echo "Can't see branch <$1>" 1>&2 + usage +fi + +case "$2" in +test|release) + if [ $(git-rev-list $1 ^$2 | wc -c) -eq 0 ] + then + echo $1 already merged into $2 1>&2 + exit 1 + fi + git checkout $2 && git resolve $2 $1 "Pull $1 into $2 branch" + ;; +*) + usage + ;; +esac + +==== status script ==== +# report on status of my ia64 GIT tree + +gb=$(tput setab 2) +rb=$(tput setab 1) +restore=$(tput setab 9) + +if [ `git-rev-tree 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-tree $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/pack-protocol.txt b/Documentation/pack-protocol.txt new file mode 100644 index 0000000000..7d6aec409d --- /dev/null +++ b/Documentation/pack-protocol.txt @@ -0,0 +1,38 @@ +There are two Pack push-pull protocols. + +upload-pack (S) | fetch/clone-pack (C) protocol: + + # Tell the puller what commits we have and what their names are + S: SHA1 name + S: ... + S: SHA1 name + S: # flush -- it's your turn + # Tell the pusher what commits we want, and what we have + C: want name + C: .. + C: want name + C: have SHA1 + C: have SHA1 + C: ... + C: # flush -- occasionally ask "had enough?" + S: NAK + C: have SHA1 + C: ... + C: have SHA1 + S: ACK + C: done + S: XXXXXXX -- packfile contents. + +send-pack | receive-pack protocol. + + # Tell the pusher what commits we have and what their names are + C: SHA1 name + C: ... + C: SHA1 name + C: # flush -- it's your turn + # Tell the puller what the pusher has + S: old-SHA1 new-SHA1 name + S: old-SHA1 new-SHA1 name + S: ... + S: # flush -- done with the list + S: XXXXXXX --- packfile contents. diff --git a/Documentation/pull-fetch-param.txt b/Documentation/pull-fetch-param.txt new file mode 100644 index 0000000000..7ae4ba0bd8 --- /dev/null +++ b/Documentation/pull-fetch-param.txt @@ -0,0 +1,36 @@ +<repository>:: + The "remote" repository to pull from. One of the + following notations can be used to name the repository + to pull from: + + Rsync URL + rsync://remote.machine/path/to/repo.git/ + + HTTP(s) URL + http://remote.machine/path/to/repo.git/ + + GIT URL + git://remote.machine/path/to/repo.git/ + remote.machine:/path/to/repo.git/ + + Local directory + /path/to/repo.git/ + + In addition to that, as a short-hand, the name of a file + in $GIT_DIR/branches directory can be specified; 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. + +<head>:: + The remote head name to fetch from. That is, make the + objects reachable from the commit recorded in + $GIT_DIR/refs/heads/<head> in the remote repository + available locally. + +tag <tag>:: + The remote head tag to fetch from. That is, make the + objects reachable from the commit recorded in + $GIT_DIR/refs/tags/<tag> in the remote repository + available locally. + diff --git a/Documentation/sort_glossary.pl b/Documentation/sort_glossary.pl new file mode 100644 index 0000000000..babbea0415 --- /dev/null +++ b/Documentation/sort_glossary.pl @@ -0,0 +1,70 @@ +#!/usr/bin/perl + +%terms=(); + +while(<>) { + if(/^(\S.*)::$/) { + my $term=$1; + if(defined($terms{$term})) { + die "$1 defined twice\n"; + } + $terms{$term}=""; + LOOP: while(<>) { + if(/^$/) { + last LOOP; + } + if(/^ \S/) { + $terms{$term}.=$_; + } else { + die "Error 1: $_"; + } + } + } +} + +sub format_tab_80 ($) { + my $text=$_[0]; + my $result=""; + $text=~s/\s+/ /g; + $text=~s/^\s+//; + while($text=~/^(.{1,72})(|\s+(\S.*)?)$/) { + $result.=" ".$1."\n"; + $text=$3; + } + return $result; +} + +sub no_spaces ($) { + my $result=$_[0]; + $result=~tr/ /_/; + return $result; +} + +print 'GIT Glossary +============ +Aug 2005 + +This list is sorted alphabetically: + +'; + +@keys=sort {uc($a) cmp uc($b)} keys %terms; +$pattern='(\b'.join('\b|\b',reverse @keys).'\b)'; +foreach $key (@keys) { + $terms{$key}=~s/$pattern/sprintf "<<ref_".no_spaces($1).",$1>>";/eg; + print '[[ref_'.no_spaces($key).']]'.$key."::\n" + .format_tab_80($terms{$key})."\n"; +} + +print ' + +Author +------ +Written by Johannes Schindelin <Johannes.Schindelin@gmx.de> and +the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the link:git.html[git] suite +'; + diff --git a/Documentation/tutorial.txt b/Documentation/tutorial.txt new file mode 100644 index 0000000000..a2a7b7cd41 --- /dev/null +++ b/Documentation/tutorial.txt @@ -0,0 +1,1109 @@ +A short git tutorial +==================== +May 2005 + + +Introduction +------------ + +This is trying to be a short tutorial on setting up and using a git +archive, mainly because being hands-on and using explicit examples is +often the best way of explaining what is going on. + +In normal life, most people wouldn't use the "core" git programs +directly, but rather script around them to make them more palatable. +Understanding the core git stuff may help some people get those scripts +done, though, and it may also be instructive in helping people +understand what it is that the higher-level helper scripts are actually +doing. + +The core git is often called "plumbing", with the prettier user +interfaces on top of it called "porcelain". You may not want to use the +plumbing directly very often, but it can be good to know what the +plumbing does for when the porcelain isn't flushing... + + +Creating a git archive +---------------------- + +Creating a new git archive couldn't be easier: all git archives 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 archive 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, ls should show you +three entries: + + - a symlink called HEAD, pointing to "refs/heads/master" + + Don't worry about the fact that the file that the HEAD link points to + doesn't even exist yet - you haven't created the commit that will + start your HEAD development branch yet. + + - a subdirectory called "objects", which will contain all the git SHA1 + 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 of your + repository. + + One note: the special "master" head is the default branch, which is + why the .git/HEAD file was created as a symlink to it even if it + doesn't yet exist. Basically, the HEAD link is supposed to always + point to the branch you are working on right now, and you always + start out expecting to work on the "master" branch. + + However, this is only a convention, and you can name your branches + anything you want, and don't have to ever even _have_ a "master" + branch. A number of the git tools will assume that .git/HEAD is + valid, though. + + [ Implementation note: an "object" is identified by its 160-bit SHA1 + hash, aka "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 this refs + subdirectories when you actually start populating your tree ] + +You have now created your first git archive. Of course, since it's +empty, that's not very useful, so let's start populating it with data. + + + Populating a git archive + ------------------------ + +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 archive. 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 directory, but to +actually check in your hard work, you will have to go through two steps: + + - fill in the "cache" aka "index" file with the information about your + working directory 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 directory, you use the "git-update-cache" program. That +program normally just takes a list of filenames you want to update, but +to avoid trivial mistakes, it refuses to add new entries to the cache +(or remove existing ones) unless you explicitly tell it that you're +adding a new entry with the "--add" flag (or removing an entry with the +"--remove") flag. + +So to populate the index with the two files you just created, you can do + + git-update-cache --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 +store. 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 object with SHA1 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" 557db03de997c86a4a028e1ebd3a1ceb225be238 + +which will print out "Hello World". The object 557db... is nothing +more than the contents of your file "hello". + +[ Digression: 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. ] + +Anyway, as we mentioned previously, you normally never actually take a +look at the objects themselves, and typing long 40-character hex SHA1 +names is not something you'd normally want to do. The above digression +was just to show that "git-update-cache" did something magical, and +actually saved away the contents of your files into the git content +store. + +Updating the cache did something else too: it created a ".git/index" +file. This is the index that describes your current working tree, and +something you should be very aware of. Again, you normally never worry +about the index file itself, but you should be aware of the fact that +you have not actually really "checked in" your files into git so far, +you've only _told_ git about them. + +However, since git knows about them, you can now start using some of the +most basic git commands to manipulate the files or look at their status. + +In particular, let's not even check in the two files into git yet, we'll +start off by adding another line to "hello" first: + + echo "It's a new day for git" >>hello + +and you can now, since you told git about the previous state of "hello", ask +git what has changed in the tree compared to your old index, using the +"git-diff-files" command: + + git-diff-files + +oops. That wasn't very readable. It just spit out its own internal +version of a "diff", but that internal version really just tells you +that it has noticed that "hello" has been modified, and that the old object +contents it had have been replaced with something else. + +To make it readable, we can tell git-diff-files to output the +differences as a patch, using the "-p" flag: + + git-diff-files -p + +which will spit out + + diff --git a/hello b/hello + --- a/hello + +++ b/hello + @@ -1 +1,2 @@ + Hello World + +It's a new day for git + +ie the diff of the change we caused by adding another line to "hello". + +In other words, git-diff-files always shows us the difference between +what is recorded in the index, and what is currently in the working +tree. That's very useful. + +A common shorthand for "git-diff-files -p" is to just write + + git diff + +which will do the same thing. + + + Committing git state + -------------------- + +Now, we want to go to the next stage in git, which is to take the files +that git knows about in the index, and commit them as a real tree. We do +that in two phases: creating a "tree" object, and committing that "tree" +object as a "commit" object together with an explanation of what the +tree was all about, along with information of how we came to that state. + +Creating a tree object is trivial, and is done with "git-write-tree". +There are no options or other input: git-write-tree will take the +current index state, and write an object that describes that whole +index. In other words, we're now tying together all the different +filenames with their contents (and their permissions), and we're +creating the equivalent of a git "directory" object: + + git-write-tree + +and this will just output the name of the resulting tree, in this case +(if you have done exactly as I've described) it should be + + 8988da15d077d4829fc51d8544c097def6644dbb + +which is another incomprehensible object name. Again, if you want to, +you can use "git-cat-file -t 8988d.." to see that this time the object +is not a "blob" object, but a "tree" object (you can also use +git-cat-file to actually output the raw object contents, but you'll see +mainly a binary mess, so that's less interesting). + +However - normally you'd never use "git-write-tree" on its own, because +normally you always commit a tree into a commit object using the +"git-commit-tree" command. In fact, it's easier to not actually use +git-write-tree on its own at all, but to just pass its result in as an +argument to "git-commit-tree". + +"git-commit-tree" normally takes several arguments - it wants to know +what the _parent_ of a commit was, but since this is the first commit +ever in this new archive, and it has no parents, we only need to pass in +the tree ID. However, git-commit-tree also wants to get a commit message +on its standard input, and it will write out the resulting ID for the +commit to its standard output. + +And this is where we start using the .git/HEAD file. The HEAD file is +supposed to contain the reference to the top-of-tree, and since that's +exactly what git-commit-tree spits out, we can do this all with a simple +shell pipeline: + + echo "Initial commit" | git-commit-tree $(git-write-tree) > .git/HEAD + +which will say: + + Committing initial tree 8988da15d077d4829fc51d8544c097def6644dbb + +just to warn you about the fact that it created a totally new commit +that is not related to anything else. Normally you do this only _once_ +for a project ever, and all later commits will be parented on top of an +earlier commit, and you'll never see this "Committing initial tree" +message ever again. + +Again, normally you'd never actually do this by hand. There is a +helpful script called "git commit" that will do all of this for you. So +you could have just written + + git commit + +instead, and it would have done the above magic scripting for you. + + + Making a change + --------------- + +Remember how we did the "git-update-cache" 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 directory, 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-cache". + +Unlike "git-diff-files", which showed the difference between the index +file and the working directory, "git-diff-cache" shows the differences +between a committed _tree_ and either the index file or the working +directory. In other words, git-diff-cache 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-cache -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 directory 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-cache" normally compares a tree against the +working directory, but when given the "--cached" flag, it is told to +instead compare against just the index cache contents, and ignore the +current working directory state entirely. Since we just wrote the index +file to HEAD, doing "git-diff-cache --cached -p HEAD" should thus return +an empty set of differences, and that's exactly what it does. + +[ Digression: "git-diff-cache" really always uses the index for its + comparisons, and saying that it compares a tree against the working + directory 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 directory 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 +directory contents", "index file" and "committed tree". We have changes +in the working directory 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-cache 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-xxx versions here. After +we've updated "hello" in the index, "git-diff-files -p" now shows no +differences, but "git-diff-cache -p HEAD" still _does_ show that the +current state is different from the state we committed. In fact, now +"git-diff-cache" shows the same difference whether we use the "--cached" +flag or not, since now the index is coherent with the working directory. + +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're doing. + +Write whatever message you want, and all the lines that start with '#' +will be pruned out, and the rest will be used as the commit message for +the change. If you decide you don't want to commit anything after all at +this point (you can continue to edit things and update the cache), you +can just leave an empty message. Otherwise git-commit-script 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-script 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. + + + Checking it out + --------------- + +While creating changes is useful, it's even more useful if you can tell +later what changed. The most useful command for this is another of the +"diff" family, namely "git-diff-tree". + +git-diff-tree can be given two arbitrary trees, and it will tell you the +differences between them. Perhaps even more commonly, though, you can +give it just a single commit object, and it will figure out the parent +of that commit itself, and show the difference directly. Thus, to get +the same diff that we've already seen several times, we can now do + + git-diff-tree -p HEAD + +(again, "-p" means to show the difference as a human-readable patch), +and it will show what the last commit (in HEAD) actually changed. + +More interestingly, you can also give git-diff-tree the "-v" flag, which +tells it to also show the commit message and author and date of the +commit, and you can tell it to show a whole series of diffs. +Alternatively, you can tell it to be "silent", and not show the diffs at +all, but just show the actual commit message. + +In fact, together with the "git-rev-list" program (which generates a +list of revisions), git-diff-tree ends up being a veritable fount of +changes. A trivial (but very useful) script called "git-whatchanged" is +included with git which does exactly this, and shows a log of recent +activity. + +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. + +[ Side 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. + + +[ Side 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-cache" 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-cache" on them for you. ] + + + Tagging a version + ----------------- + +In git, there's two kinds of tags, a "light" one, and a "signed 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. + +A "signed 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 a PGP signature that says that yes, you really did +that tag. You create these signed tags with the "-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 archives + ----------------- + +Git archives are normally totally self-sufficient, and it's worth noting +that unlike CVS, for example, there is no separate notion of +"repository" and "working tree". A git repository normally _is_ the +working tree, with the local git information hidden in the ".git" +subdirectory. There is nothing else. What you see is what you got. + +[ Side 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 directory 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 archive 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 of the project you created. + + - if you want to move or duplicate a git archive, you can do so. There + is "git clone" command, but if all you want to do is just to + create a copy of your archive (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 archive, 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-cache --refresh + + to make sure that the index file is up-to-date in the new one. + +Note that the second point is true even across machines. You can +duplicate a remote git archive 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-cache" with a + + git-read-tree --reset HEAD + git-update-cache --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-cache +makes sure to match up all index entries with the checked-out files). + +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, and you can learn things by just looking +at what the git-*-script scripts do ("git reset" is the above two lines +implemented in "git-reset-script", but some things like "git status" and +"git commit" are slightly more complex scripts around the basic git +commands). + +NOTE! 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_directory_ files to work on. To get +those, you'd check them out with + + git-checkout-cache -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-cache 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 space 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 archive 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. + +[ Side 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-branch + + and it would create the new branch "mybranch" at the earlier point, + and check out the state at that time. ] + +You can always just jump back to your original "master" branch by doing + + git checkout master + +(or any other branch-name, for that matter) and if you forget which +branch you happen to be on, a simple + + ls -l .git/HEAD + +will tell you where it's pointing. + +NOTE! 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 hello + +Here, we just added another line to "hello", and we used a shorthand for +both going a "git-update-cache hello" and "git commit" by just giving the +filename directly to "git commit". + +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 hello example + +since the master branch is obviously in a much better mood. + +Now, you've got two branches, and you decide that you want to merge the +work done. Before we do that, let's introduce a cool graphical tool that +helps you view what's going on: + + gitk --all + +will show you graphically both of your branches (that's what the "--all" +means: normally it will just show you your current HEAD) and their +histories. You can also see exactly how they came to be from a common +source. + +Anyway, let's exit gitk (^Q or the File menu), and decide that we want +to merge the work we did on the "mybranch" branch into the "master" +branch (which is currently our HEAD too). To do that, there's a nice +script called "git resolve", which wants to know which branches you want +to resolve and what the merge is all about: + + git resolve HEAD mybranch "Merge work in mybranch" + +where the third argument is going to be used as the commit message if +the merge can be resolved automatically. + +Now, in this case we've intentionally created a situation where the +merge will need to be fixed up by hand, though, so git will do as much +of it as it can automatically (which in this case is just merge the "b" +file, which had no differences in the "mybranch" branch), and say: + + Simple merge failed, trying Automatic merge + Auto-merging hello. + merge: warning: conflicts during merge + ERROR: Merge conflict in hello. + fatal: merge program failed + Automatic merge failed, fix up by hand + +which is way too verbose, but it basically tells you that it failed the +really trivial merge ("Simple merge") and did an "Automatic merge" +instead, but that too failed due to conflicts in "hello". + +Not to worry. It left the (trivial) conflict in "hello" in the same form you +should already be well used to if you've ever used CVS, so let's just +open "hello" in our editor (whatever that may be), and fix it up somehow. +I'd suggest just making it so that "hello" contains all four lines: + + Hello World + It's a new day for git + Play, play, play + Work, work, work + +and once you're happy with your manual merge, just do a + + git commit hello + +which will very loudly warn you that you're now committing a merge +(which is correct, so never mind), and you can write a small merge +message about your adventures in git-merge-land. + +After you're done, start up "gitk --all" to see graphically what the +history looks like. Notice that "mybranch" still exists, and you can +switch to it, and continue to work with it if you want to. The +"mybranch" branch will not contain the merge, but next time you merge it +from the "master" branch, git will know how you merged it, so you'll not +have to do _that_ merge again. + + + Merging external work + --------------------- + +It's usually much more common that you merge with somebody else than +merging with your own branches, so it's worth pointing out that git +makes that very easy too, and in fact, it's not that different from +doing a "git resolve". In fact, a remote merge ends up being nothing +more than "fetch the work from a remote repository into a temporary tag" +followed by a "git resolve". + +It's such a common thing to do 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. + +The "remote" repository can even be on the same machine. One of +the following notations can be used to name the repository to +pull from: + + Rsync URL + rsync://remote.machine/path/to/repo.git/ + + HTTP(s) URL + http://remote.machine/path/to/repo.git/ + + GIT URL + git://remote.machine/path/to/repo.git/ + + SSH URL + remote.machine:/path/to/repo.git/ + + Local directory + /path/to/repo.git/ + +[ Digression: 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. ] + +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/branches/ +directory, like this: + + mkdir -p .git/branches + echo rsync://kernel.org/pub/scm/git/git.git/ \ + >.git/branches/linus + +and use the filename to "git pull" instead of the full URL. +The contents of a file under .git/branches can even be a prefix +of a full URL, like this: + + echo rsync://kernel.org/pub/.../jgarzik/ + >.git/branches/jgarzik + +Examples. + + (1) git pull linus + (2) git pull linus tag v0.99.1 + (3) git pull jgarzik/netdev-2.6.git/ e100 + +the above are equivalent to: + + (1) git pull rsync://kernel.org/pub/scm/git/git.git/ HEAD + (2) git pull rsync://kernel.org/pub/scm/git/git.git/ tag v0.99.1 + (3) git pull rsync://kernel.org/pub/.../jgarzik/netdev-2.6.git e100 + + + Publishing your work + -------------------- + +So we can use somebody else's work from a remote repository; but +how can _you_ prepare a repository to let other people pull from +it? + +Your do your real work in your working directory 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 directory are in good +shape, update the public repository from it. This is often +called "pushing". + +[ Side note: this public repository could further be mirrored, + and that is how kernel.org git repositories are done. ] + +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. + +[ Digression: "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. + +[ Side 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. ] + +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/ + + +[ Digression: your GIT "public" repository people can pull from + is different from a public CVS repository that lets read-write + access to multiple developers. It is a copy of _your_ primary + repository published for others to use, and you should not + push into it from more than one repository (this means, not + just disallowing other developers to push into it, but also + you should push into it from a single repository of yours). + Sharing the result of work done by multiple people are always + done by pulling (i.e. fetching and merging) from public + repositories of those people. Typically this is done by the + "project lead" person, and the resulting repository is + published as the public repository of the "project lead" for + everybody to base further changes on. ] + + + Packing your repository + ----------------------- + +Earlier, we saw that one file under .git/objects/??/ directory +is stored for each git object you create. This representation +is convenient and efficient to create atomically and safely, but +not so 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. + +[ Side 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. + +[ Side 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 +archive 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. + + + 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. + + (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-packed" 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/branches/origin. + + (2) Prepare a public repository accessible to others. + + (3) Copy over the packed files from "project lead" public + repository to your public repository by hand; preferrably + use rsync for that task. + + (4) Push into the public repository from your primary + repository. Run "git repack", and possibly "git + prune-packed" 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/branches/origin. + + (2) Do your work there. Make commits. + + (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. + + +[ to be continued.. cvsimports ] |