diff options
Diffstat (limited to 'Documentation')
39 files changed, 2487 insertions, 1307 deletions
diff --git a/Documentation/Makefile b/Documentation/Makefile new file mode 100644 index 0000000000..b23991d52b --- /dev/null +++ b/Documentation/Makefile @@ -0,0 +1,24 @@ +DOC_SRC=$(wildcard git*.txt) +DOC_HTML=$(patsubst %.txt,%.html,$(DOC_SRC)) +DOC_MAN=$(patsubst %.txt,%.1,$(DOC_SRC)) + +all: $(DOC_HTML) $(DOC_MAN) + +html: $(DOC_HTML) + +man: $(DOC_MAN) + +git-%: %.c $(LIB_FILE) + $(CC) $(CFLAGS) -o $@ $(filter %.c,$^) $(LIBS) + +clean: + rm -f *.xml *.html *.1 + +%.html : %.txt + asciidoc -b css-embedded -d manpage $< + +%.1 : %.xml + xmlto man $< + +%.xml : %.txt + asciidoc -b docbook -d manpage $< diff --git a/Documentation/core-git.txt b/Documentation/core-git.txt deleted file mode 100644 index 8bd893197e..0000000000 --- a/Documentation/core-git.txt +++ /dev/null @@ -1,1307 +0,0 @@ -This file contains reference information for the core git commands. - -The README contains much useful definition and clarification -info - read that first. And of the commands, I suggest reading -'git-update-cache' and 'git-read-tree' first - I wish I had! - -David Greaves <david@dgreaves.com> -24/4/05 - -Updated by Junio C Hamano <junkio@cox.net> on 2005-05-05 to -reflect recent changes. - -Identifier terminology used: - -<object> - Indicates any object sha1 identifier - -<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> that points 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. - - -################################################################ -git-apply-patch-script - -This is a sample script to be used as GIT_EXTERNAL_DIFF to apply -differences git-diff-* family of commands reports to the current -work tree. - - -################################################################ -git-cat-file - git-cat-file (-t | <type>) <object> - -Provides contents or type of objects in the repository. The type -is required if -t is not being used to find the object type. - -<object> - The sha1 identifier of the object. - --t - Instead of the content, show the object type identified - by <object>. - -<type> - Typically this matches the real type of <object> but - asking for type that can trivially dereferenced from the - given <object> is also permitted. An example is to ask - "tree" with <object> for a commit object that contains - it, or to ask "blob" with <object> for a tag object that - points at it. - -Output - -If -t is specified, one of the <type>. - -Otherwise the raw (though uncompressed) contents of the <object> will -be returned. - - -################################################################ -git-check-files - git-check-files <file>... - -Check that a list of files are up-to-date between the filesystem and -the cache. Used to verify a patch target before doing a patch. - -Files that do not exist on the filesystem are considered up-to-date -(whether or not they are in the cache). - -Emits an error message on failure. -preparing to update existing file <file> not in cache - <file> exists but is not in the cache - -preparing to update file <file> not uptodate in cache - <file> on disk is not up-to-date with the cache - -Exits with a status code indicating success if all files are -up-to-date. - -see also: git-update-cache - - -################################################################ -git-checkout-cache - git-checkout-cache [-q] [-a] [-f] [-n] [--prefix=<string>] - [--] <file>... - -Will copy all files listed from the cache to the working directory -(not overwriting existing files). - --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 -a "git-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 "git-export" the cache into the specified -directory. - -NOTE! The final "/" is important. The git-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". - - -################################################################ -git-commit-tree - git-commit-tree <tree> [-p <parent commit>]* < changelog - -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. - AUTHOR_NAME - AUTHOR_EMAIL - AUTHOR_DATE - COMMIT_AUTHOR_NAME - COMMIT_AUTHOR_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 - -see also: git-write-tree - - -################################################################ -git-convert-cache - -Converts old-style GIT repository to the latest. - - -################################################################ -git-diff-cache - git-diff-cache [-p] [-r] [-z] [--cached] <tree-ish> - -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. - -<tree-ish> - The id of a tree object to diff against. - --p - Generate patch (see section on generating patches) - --r - This flag does not mean anything. It is there only to match - git-diff-tree. Unlike git-diff-tree, git-diff-cache always looks - at all the subdirectories. - --z - \0 line termination on output - ---cached - do not consider the on-disk file at all - -Output format: - -See "Output format from git-diff-cache, git-diff-tree and git-diff-files" -section. - -Operating Modes - -You can choose whether you want to trust the index file entirely -(using the "--cached" flag) or ask the diff logic to show any files -that don't match the stat state as being "tentatively changed". Both -of these operations are very useful indeed. - -Cached Mode - -If --cached is specified, it allows you to ask: - - show me the differences between HEAD and the current index - contents (the ones I'd write with a "git-write-tree") - -For example, let's say that you have worked on your index file, and are -ready to commit. You want to see eactly _what_ you are going to commit is -without having to write a new tree object and compare it that way, and to -do that, you just do - - git-diff-cache --cached $(cat .git/HEAD) - -Example: let's say I had renamed "commit.c" to "git-commit.c", and I had -done an "git-update-cache" to make that effective in the index file. -"git-diff-files" wouldn't show anything at all, since the index file -matches my working directory. But doing a git-diff-cache does: - - torvalds@ppc970:~/git> git-diff-cache --cached $(cat .git/HEAD) - -100644 blob 4161aecc6700a2eb579e842af0b7f22b98443f74 commit.c - +100644 blob 4161aecc6700a2eb579e842af0b7f22b98443f74 git-commit.c - -You can trivially see that the above is a rename. - -In fact, "git-diff-cache --cached" _should_ always be entirely equivalent to -actually doing a "git-write-tree" and comparing that. Except this one is much -nicer for the case where you just want to check where you are. - -So doing a "git-diff-cache --cached" is basically very useful when you are -asking yourself "what have I already marked for being committed, and -what's the difference to a previous tree". - -Non-cached Mode - -The "non-cached" mode takes a different approach, and is potentially the -even 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 an 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 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. - - -################################################################ -git-diff-tree - git-diff-tree [-p] [-r] [-z] [--stdin] [-m] [-s] [-v] <tree-ish> <tree-ish> [<pattern>]* - -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. - -<tree-ish> - The id of a tree object. - -<pattern> - If provided, the results are limited to a subset of files - matching one of these prefix strings. - ie file matches /^<pattern1>|<pattern2>|.../ - Note that pattern does not provide any wildcard or regexp - features. - --p - generate patch (see section on generating patches). For - git-diff-tree, this flag implies -r as well. - --r - recurse - --z - \0 line termination on output - ---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. - - -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 complete path comonent. -I.e. "foo" does not pick up "foobar.h". "foo" does match "foo/bar.h" -so it can be used to name subdirectories. - -Output format: - -See "Output format from git-diff-cache, git-diff-tree and git-diff-files" -section. - -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). - - -################################################################ -git-diff-tree-helper - git-diff-tree-helper [-z] [-R] - -Reads output from git-diff-cache, git-diff-tree and git-diff-files and -generates patch format output. - --z - \0 line termination on input - --R - Output diff in reverse. This is useful for displaying output from - git-diff-cache which always compares tree with cache or working - file. E.g. - - git-diff-cache <tree> | git-diff-tree-helper -R file.c - - would show a diff to bring the working file back to what is in the - <tree>. - -See also the section on generating patches. - - -################################################################ -git-fsck-cache - git-fsck-cache [--tags] [--root] [[--unreachable] [--cache] <object>*] - -Verifies the connectivity and validity of the objects in the database. - -<object> - An object to treat as the head of an unreachability trace. - ---unreachable - Print out objects that exist but that aren't readable from any - of the specified head 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. - -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) - -or, for Cogito users: - - git-fsck-cache --unreachable $(cat .git/refs/heads/*) - -will do quite a _lot_ of verification on the tree. There are a few -extra validity tests to be added (make sure that tree objects are -sorted properly etc), but on the whole if "git-fsck-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 na SHA1_ode 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. - (note: this error occured during early git development when - the database format changed.) - -Environment Variables - -SHA1_FILE_DIRECTORY - used to specify the object database root (usually .git/objects) - -GIT_INDEX_FILE - used to specify the cache - - -################################################################ -git-export - git-export top [base] - -Exports each commit and diff against each of its parents, between -top and base. If base is not specified it exports everything. - - -################################################################ -git-init-db - git-init-db - -This simply creates an empty git object database - basically a .git -directory and .git/object/??/ directories. - -If the object storage directory is specified via the SHA1_FILE_DIRECTORY -environment variable then the sha1 directories are created underneath - -otherwise the default .git/objects directory is used. - -git-init-db won't hurt an existing repository. - - -################################################################ -git-http-pull - - git-http-pull [-c] [-t] [-a] [-v] commit-id url - -Downloads a remote GIT repository via HTTP protocol. - --c - Get the commit objects. --t - Get trees associated with the commit objects. --a - Get all the objects. --v - Report what is downloaded. - - -################################################################ -git-local-pull - - git-local-pull [-c] [-t] [-a] [-l] [-s] [-n] [-v] commit-id path - -Downloads another GIT repository on a local system. - --c - Get the commit objects. --t - Get trees associated with the commit objects. --a - Get all the objects. --v - Report what is downloaded. - -################################################################ -git-ls-tree - git-ls-tree [-r] [-z] <tree-ish> - -Converts the tree object to a human readable (and script processable) -form. - -<tree-ish> - Id of a tree. - --r - recurse into sub-trees - --z - \0 line termination on output - -Output Format -<mode>\t <type>\t <object>\t <file> - - -################################################################ -git-merge-base - git-merge-base <commit> <commit> - -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... - - -################################################################ -git-merge-cache - git-merge-cache <merge-program> (-a | -- | <file>*) - -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. - --- - Interpret all future arguments as filenames. - --a - Run merge against all files in the cache that need merging. - -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 -ditribution. - -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). - -################################################################ -git-merge-one-file-script - -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. - -################################################################ -git-mktag - -Reads a tag contents from its standard input and creates a tag object. -The input must be a well formed tag object. - - -################################################################ -git-prune-script - -This runs git-fsck-cache --unreachable program using the heads specified -on the command line (or .git/refs/heads/* and .git/refs/tags/* if none is -specified), and prunes all unreachable objects from the object database. - - -################################################################ -git-pull-script - -This script is used by Linus to pull from a remote repository and perform -a merge. - - -################################################################ -git-read-tree - git-read-tree (<tree-ish> | -m <tree-ish1> [<tree-ish2> <tree-ish3>])" - -Reads the tree information given by <tree> 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 or perform a 3-way -merge. - -Trivial merges are done by git-read-tree itself. Only conflicting paths -will be in unmerged state when git-read-tree returns. - --m - Perform a merge, not just a read - -<tree-ish#> - The id of the tree object(s) to be read/merged. - - -Merging -If -m is specified, git-read-tree performs 2 kinds of merge, a single tree -merge if only 1 tree is given 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 -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. - -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). - -In fact, the way "git-read-tree" works, it's entirely agnostic about how -you assign the stages, and you could really assign them any which way, -and the above is just a suggested way to do it (except since -"git-write-tree" refuses to write anything but stage0 entries, it makes -sense to always consider stage 0 to be the "full merge" state). - -So what happens? Try it out. Select the original tree, and two trees -to merge, and look how it works: - - - if a file exists in identical format in all three trees, it will - automatically collapse to "merged" state by the new 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 "script - policy" to determine how to remove the non-0 stages, and insert a - merged version. But since the index is always sorted, they're easy - to find: they'll be clustered together. - - - 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 .. - -Incidentally - it also means that you don't even have to have a separate -subdirectory for this. All the information literally is in the index file, -which is a temporary thing anyway. There is no need to worry about what is -in the working directory, since it is never shown and never used. - -see also: -git-write-tree -git-ls-files - - -################################################################ -git-resolve-script - -This script is used by Linus to merge two trees. - - -################################################################ -git-rev-list <commit> - -Lists commit objects in reverse chronological order starting at the -given commit, taking ancestry relationship into account. This is -useful to produce human-readable log output. - - -################################################################ -git-rev-tree - git-rev-tree [--edges] [--cache <cache-file>] [^]<commit> [[^]<commit>] - -Provides the revision tree for one or more commits. - ---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.) - - -################################################################ -git-rpull - - git-rpull [-c] [-t] [-a] [-v] commit-id url - -Pulls from a remote repository over ssh connection, invoking git-rpush on -the other end. - --c - Get the commit objects. --t - Get trees associated with the commit objects. --a - Get all the objects. --v - Report what is downloaded. - - -################################################################ -git-rpush - -Helper "server-side" program used by git-rpull. - - -################################################################ -git-diff-files - git-diff-files [-p] [-q] [-r] [-z] [<pattern>...] - -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. - --p - generate patch (see section on generating patches). - --q - Remain silent even on nonexisting files - --r - This flag does not mean anything. It is there only to match - git-diff-tree. Unlike git-diff-tree, git-diff-files always looks - at all the subdirectories. - - -Output format: - -See "Output format from git-diff-cache, git-diff-tree and git-diff-files" -section. - - -################################################################ -git-tag-script - -This is an example script that uses git-mktag to create a tag object -signed with GPG. - - -################################################################ -git-tar-tree - - git-tar-tree <tree-ish> [ <base> ] - -Creates a tar archive containing the tree structure for the named tree. -When <base> is specified it is added as a leading path as the files in the -generated tar archive. - - -################################################################ -git-ls-files - git-ls-files [-z] [-t] - (--[cached|deleted|others|ignored|stage|unmerged])* - (-[c|d|o|i|s|u])* - [-x <pattern>|--exclude=<pattern>] - [-X <file>|--exclude-from=<file>] - -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: - --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) - --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. - Allows the use of the famous dontdiff file as follows to find - out about uncommitted files just as dontdiff is used with - the diff command: - git-ls-files --others --exclude-from=dontdiff - --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 - ? 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 Cogito) to see what should eventually be recorded at the -path. (see read-cache for more information on state) - -see also: -read-cache - - -################################################################ -git-unpack-file - git-unpack-file <blob> - -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 - -<blob> - Must be a blob id - -################################################################ -git-update-cache - git-update-cache - [--add] [--remove] [--refresh] - [--ignore-missing] - [--force-remove <file>] - [--cacheinfo <mode> <object> <file>]* - [--] [<file>]* - -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: - ---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. - ---force-remove - Remove the file from the index even when the working directory - still has such a file. - --- - 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 ---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 - -To update and refresh only the files already checked out: - - git-checkout-cache -n -f -a && git-update-cache --ignore-missing --refresh - - -################################################################ -git-write-blob - - git-write-blob <any-file-on-the-filesystem> - -Writes the contents of the named file (which can be outside of the work -tree) as a blob into the object database, and reports its object ID to its -standard output. This is used by git-merge-one-file-script to update the -cache without modifying files in the work tree. - - -################################################################ -git-write-tree - git-write-tree - -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". - - -################################################################ - -Output format from git-diff-cache, git-diff-tree and git-diff-files. - -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. - -The following desription uses "old" and "new" to mean those -compared entities. - -For files in old but not in new (i.e. removed): --<mode> \t <type> \t <object> \t <path> - -For files not in old but in new (i.e. added): -+<mode> \t <type> \t <object> \t <path> - -For files that differ: -*<old-mode>-><new-mode> \t <type> \t <old-sha1>-><new-sha1> \t <path> - -<new-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 blob 5be4a4.......->000000....... file.c - -################################################################ - -Generating patches - -When git-diff-cache, git-diff-tree, or git-diff-files are run with a -p -option, they do not produce the output described in "Output format from -git-diff-cache, git-diff-tree and git-diff-files" section. It instead -produces a patch file. - -The patch generation can be customized at two levels. This -customization also applies to git-diff-tree-helper. - -1. When the environment variable GIT_EXTERNAL_DIFF is not set, - these commands internally invoke diff like this: - - diff -L a/<path> -L a/<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. - -################################################################ - -Terminology: - see README for description -Each line contains terms used interchangeably - -object database, .git directory -directory cache, index -id, sha1, sha1-id, sha1 hash -type, tag -blob, blob object -tree, tree object -commit, commit object -parent -root object -changeset - - -git Environment Variables -AUTHOR_NAME -AUTHOR_EMAIL -AUTHOR_DATE -COMMIT_AUTHOR_NAME -COMMIT_AUTHOR_EMAIL -GIT_DIFF_OPTS -GIT_EXTERNAL_DIFF -GIT_INDEX_FILE -SHA1_FILE_DIRECTORY diff --git a/Documentation/diff-format.txt b/Documentation/diff-format.txt new file mode 100644 index 0000000000..1a99e85ee5 --- /dev/null +++ b/Documentation/diff-format.txt @@ -0,0 +1,89 @@ +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. + +The following desription uses "old" and "new" to mean those +compared entities. + +For files in old but not in new (i.e. removed): + + -<mode> \t <type> \t <object> \t <path> + +For files not in old but in new (i.e. added): + + +<mode> \t <type> \t <object> \t <path> + +For files that differ: + + *<old-mode>-><new-mode> \t <type> \t <old-sha1>-><new-sha1> \t <path> + +<new-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 blob 5be4a4.......->000000....... 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-tree-helper". + +1. When the environment variable 'GIT_EXTERNAL_DIFF' is not set, + these commands internally invoke "diff" like this: + + diff -L a/<path> -L a/<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>. diff --git a/Documentation/git-apply-patch-script.txt b/Documentation/git-apply-patch-script.txt new file mode 100644 index 0000000000..a6f860d424 --- /dev/null +++ b/Documentation/git-apply-patch-script.txt @@ -0,0 +1,32 @@ +git-apply-patch-script(1) +========================= +v0.1, May 2005 + +NAME +---- +git-apply-patch-script - Sample script to apply the diffs from git-diff-* + + +SYNOPSIS +-------- +'git-apply-patch-script' + +DESCRIPTION +----------- +This is a sample script to be used via the 'GIT_EXTERNAL_DIFF' +environment variable to apply the differences that the "git-diff-*" +family of commands report to the current work tree. + + +Author +------ +Written by Linus Torvalds <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-cat-file.txt b/Documentation/git-cat-file.txt new file mode 100644 index 0000000000..48fb37769c --- /dev/null +++ b/Documentation/git-cat-file.txt @@ -0,0 +1,55 @@ +git-cat-file(1) +=============== +v0.1, May 2005 + +NAME +---- +git-cat-file - Provide content or type information for repository objects + + +SYNOPSIS +-------- +'git-cat-file' (-t | <type>) <object> + +DESCRIPTION +----------- +Provides content or type of objects in the repository. The type +is required if '-t' is not being used to find the object type. + +OPTIONS +------- +<object>:: + The sha1 identifier of the object. + +-t:: + Instead of the content, show the object type 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>. + +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-check-files.txt b/Documentation/git-check-files.txt new file mode 100644 index 0000000000..6146098022 --- /dev/null +++ b/Documentation/git-check-files.txt @@ -0,0 +1,50 @@ +git-check-files(1) +================== +v0.1, May 2005 + +NAME +---- +git-check-files - Verify a list of files are up-to-date + + + +SYNOPSIS +-------- +'git-check-files' <file>... + +DESCRIPTION +----------- +Check that a list of files are up-to-date between the filesystem and +the cache. Used to verify a patch target before doing a patch. + +Files that do not exist on the filesystem are considered up-to-date +(whether or not they are in the cache). + +Emits an error message on failure: + +preparing to update existing file <file> not in cache:: + <file> exists but is not in the cache + +preparing to update file <file> not uptodate in cache:: + <file> on disk is not up-to-date with the cache + +Exits with a status code indicating success if all files are +up-to-date. + +See Also +-------- +link:git-update-cache.html[git-update-cache] + + +Author +------ +Written by Linus Torvalds <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..9d41626d97 --- /dev/null +++ b/Documentation/git-checkout-cache.txt @@ -0,0 +1,102 @@ +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' [-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 +------- +-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-commit-tree.txt b/Documentation/git-commit-tree.txt new file mode 100644 index 0000000000..c0dc1f46c5 --- /dev/null +++ b/Documentation/git-commit-tree.txt @@ -0,0 +1,88 @@ +git-commit-tree(1) +================== +v0.1, May 2005 + +NAME +---- +git-commit-tree - Creates a new commit object + + +SYNOPSIS +-------- +'git-commit-tree' <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 + +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-diff-cache.txt b/Documentation/git-diff-cache.txt new file mode 100644 index 0000000000..b54b8226ad --- /dev/null +++ b/Documentation/git-diff-cache.txt @@ -0,0 +1,141 @@ +git-diff-cache(1) +================= +v0.1, May 2005 + +NAME +---- +git-diff-cache - Compares content and mode of blobs between the cache and repository + + +SYNOPSIS +-------- +'git-diff-cache' [-p] [-r] [-z] [-m] [--cached] <tree-ish> + +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. + +OPTIONS +------- +<tree-ish>:: + The id of a tree object to diff against. + +-p:: + Generate patch (see section on generating patches) + +-r:: + This flag does not mean anything. It is there only to match + "git-diff-tree". Unlike "git-diff-tree", "git-diff-cache" + always looks at all the subdirectories. + +-z:: + \0 line termination on output + +--cached:: + do not consider the on-disk file at all + +-m:: + By default, files recorded in the index but not checked + out are reported as deleted. This flag makes + "git-diff-cache" say that all non-checked-out files are up + to date. + +Output format +------------- +include::diff-format.txt[] + +Operating Modes +--------------- +You can choose whether you want to trust the index file entirely +(using the '--cached' flag) or ask the diff logic to show any files +that don't match the stat state as being "tentatively changed". Both +of these operations are very useful indeed. + +Cached Mode +----------- +If '--cached' is specified, it allows you to ask: + + show me the differences between HEAD and the current index + contents (the ones I'd write with a "git-write-tree") + +For example, let's say that you have worked on your index file, and are +ready to commit. You want to see eactly *what* you are going to commit is +without having to write a new tree object and compare it that way, and to +do that, you just do + + git-diff-cache --cached $(cat .git/HEAD) + +Example: let's say I had renamed `commit.c` to `git-commit.c`, and I had +done an "git-update-cache" to make that effective in the index file. +"git-diff-files" wouldn't show anything at all, since the index file +matches my working directory. But doing a "git-diff-cache" does: + + torvalds@ppc970:~/git> git-diff-cache --cached $(cat .git/HEAD) + -100644 blob 4161aecc6700a2eb579e842af0b7f22b98443f74 commit.c + +100644 blob 4161aecc6700a2eb579e842af0b7f22b98443f74 git-commit.c + +You can trivially see that the above is a rename. + +In fact, "git-diff-cache --cached" *should* always be entirely equivalent to +actually doing a "git-write-tree" and comparing that. Except this one is much +nicer for the case where you just want to check where you are. + +So doing a "git-diff-cache --cached" is basically very useful when you are +asking yourself "what have I already marked for being committed, and +what's the difference to a previous tree". + +Non-cached Mode +--------------- +The "non-cached" mode takes a different approach, and is potentially +the more useful of the two in that what it does can't be emulated with +a "git-write-tree" + "git-diff-tree". Thus that's the default mode. +The non-cached version asks the question: + + show me the differences between HEAD and the currently checked out + tree - index contents _and_ files that aren't up-to-date + +which is obviously a very useful question too, since that tells you what +you *could* commit. Again, the output matches the "git-diff-tree -r" +output to a tee, but with a twist. + +The twist is that if some file doesn't match the cache, we don't have +a backing store thing for it, and we use the magic "all-zero" sha1 to +show that. So let's say that you have edited `kernel/sched.c`, but +have not actually done a "git-update-cache" on it yet - there is no +"object" associated with the new state, and you get: + + torvalds@ppc970:~/v2.6/linux> git-diff-cache $(cat .git/HEAD ) + *100644->100664 blob 7476bb......->000000...... kernel/sched.c + +ie it shows that the tree has changed, and that `kernel/sched.c` has is +not up-to-date and may contain new stuff. The all-zero sha1 means that to +get the real diff, you need to look at the object in the working directory +directly rather than do an object-to-object diff. + +NOTE! As with other commands of this type, "git-diff-cache" does not +actually look at the contents of the file at all. So maybe +`kernel/sched.c` hasn't actually changed, and it's just that you +touched it. In either case, it's a note that you need to +"git-upate-cache" it to make the cache be in sync. + +NOTE 2! You can have a mixture of files show up as "has been updated" +and "is still dirty in the working directory" together. You can always +tell which file is in which state, since the "has been updated" ones +show a valid sha1, and the "not in sync with the index" ones will +always have the special all-zero sha1. + + +Author +------ +Written by Linus Torvalds <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..0ad2f89550 --- /dev/null +++ b/Documentation/git-diff-files.txt @@ -0,0 +1,51 @@ +git-diff-files(1) +================= +v0.1, May 2005 + +NAME +---- +git-diff-files - Compares files in the working tree and the cache + + +SYNOPSIS +-------- +'git-diff-files' [-p] [-q] [-r] [-z] [<pattern>...] + +DESCRIPTION +----------- +Compares the files in the working tree and the cache. When paths +are specified, compares only those named paths. Otherwise all +entries in the cache are compared. The output format is the +same as "git-diff-cache" and "git-diff-tree". + +OPTIONS +------- +-p:: + generate patch (see section on generating patches). + +-q:: + Remain silent even on nonexisting files + +-r:: + This flag does not mean anything. It is there only to match + git-diff-tree. Unlike git-diff-tree, git-diff-files always looks + at all the subdirectories. + + +Output format +------------- +include::diff-format.txt[] + + +Author +------ +Written by Linus Torvalds <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-tree-helper.txt b/Documentation/git-diff-tree-helper.txt new file mode 100644 index 0000000000..58f27172a9 --- /dev/null +++ b/Documentation/git-diff-tree-helper.txt @@ -0,0 +1,49 @@ +git-diff-tree-helper(1) +======================= +v0.1, May 2005 + +NAME +---- +git-diff-tree-helper - Generates patch format output for git-diff-* + + +SYNOPSIS +-------- +'git-diff-tree-helper' [-z] [-R] + +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 + +-R:: + Output diff in reverse. This is useful for displaying output from + "git-diff-cache" which always compares tree with cache or working + file. E.g. + + git-diff-cache <tree> | git-diff-tree-helper -R file.c ++ +would show a diff to bring the working file back to what is in the <tree>. + +See Also +-------- +The section on generating patches in link:git-diff-cache.html[git-diff-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-diff-tree.txt b/Documentation/git-diff-tree.txt new file mode 100644 index 0000000000..ff7f25f3f4 --- /dev/null +++ b/Documentation/git-diff-tree.txt @@ -0,0 +1,126 @@ +git-diff-tree(1) +================ +v0.1, May 2005 + +NAME +---- +git-diff-tree - Compares the content and mode of blobs found via two tree objects + + +SYNOPSIS +-------- +'git-diff-tree' [-p] [-r] [-z] [--stdin] [-m] [-s] [-v] <tree-ish> <tree-ish> [<pattern>]\* + +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 +------- +<tree-ish>:: + The id of a tree object. + +<pattern>:: + If provided, the results are limited to a subset of files + matching one of these prefix strings. + ie file matches `/^<pattern1>|<pattern2>|.../` + Note that pattern does not provide any wildcard or regexp + features. + +-p:: + generate patch (see section on generating patches). For + git-diff-tree, this flag implies '-r' as well. + +-r:: + recurse + +-z:: + \0 line termination on output + +--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. + + +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 complete path comonent. +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-fsck-cache.txt b/Documentation/git-fsck-cache.txt new file mode 100644 index 0000000000..bcd3b0adcc --- /dev/null +++ b/Documentation/git-fsck-cache.txt @@ -0,0 +1,122 @@ +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] <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. + +--unreachable:: + Print out objects that exist but that aren't readable from any + of the specified head 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. + +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) + +or, for Cogito users: + + git-fsck-cache --unreachable $(cat .git/refs/heads/*) + +will do quite a _lot_ of verification on the tree. There are a few +extra validity tests to be added (make sure that tree objects are +sorted properly etc), but on the whole if "git-fsck-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. + (note: this error occured during early git development when + the database format changed.) + +Environment Variables +--------------------- + +GIT_OBJECT_DIRECTORY:: + used to specify the object database root (usually .git/objects) + +GIT_INDEX_FILE:: + used to specify the 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-http-pull.txt b/Documentation/git-http-pull.txt new file mode 100644 index 0000000000..59cd090a78 --- /dev/null +++ b/Documentation/git-http-pull.txt @@ -0,0 +1,39 @@ +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] [-v] 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. + + +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..99f96f7d4f --- /dev/null +++ b/Documentation/git-init-db.txt @@ -0,0 +1,40 @@ +git-init-db(1) +============== +v0.1, May 2005 + +NAME +---- +git-init-db - Creates an empty git object database + + +SYNOPSIS +-------- +'git-init-db' + +DESCRIPTION +----------- +This simply creates an empty git object database - basically a `.git` +directory and `.git/object/??/` directories. + +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/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..53f5d39682 --- /dev/null +++ b/Documentation/git-local-pull.txt @@ -0,0 +1,40 @@ +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] [-l] [-s] [-n] [-v] 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. + +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..14ca695317 --- /dev/null +++ b/Documentation/git-ls-files.txt @@ -0,0 +1,102 @@ +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])\* + (-[c|d|o|i|s|u])\* + [-x <pattern>|--exclude=<pattern>] + [-X <file>|--exclude-from=<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) + +-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. + Allows the use of the famous dontdiff file as follows to find + out about uncommitted files just as dontdiff is used with + the diff command: + git-ls-files --others --exclude-from=dontdiff + +-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 + ? 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 Cogito) to see what should eventually be recorded at the +path. (see read-cache for more information on state) + +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-tree.txt b/Documentation/git-ls-tree.txt new file mode 100644 index 0000000000..f6e15ad7fa --- /dev/null +++ b/Documentation/git-ls-tree.txt @@ -0,0 +1,46 @@ +git-ls-tree(1) +============== +v0.1, May 2005 + +NAME +---- +git-ls-tree - Displays a tree object in human readable form + + +SYNOPSIS +-------- +'git-ls-tree' [-r] [-z] <tree-ish> + +DESCRIPTION +----------- +Converts the tree object to a human readable (and script processable) +form. + +OPTIONS +------- +<tree-ish>:: + Id of a tree. + +-r:: + recurse into sub-trees + +-z:: + \0 line termination on output + +Output Format +------------- + <mode>\t <type>\t <object>\t <file> + + +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-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..343607cf9a --- /dev/null +++ b/Documentation/git-merge-cache.txt @@ -0,0 +1,77 @@ +git-merge-cache(1) +================== +v0.1, May 2005 + +NAME +---- +git-merge-cache - Runs a merge for files needing merging + + +SYNOPSIS +-------- +'git-merge-cache' <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 future arguments as filenames. + +-a:: + Run merge against all files in the cache that need merging. + +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 +ditribution. + +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> + +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..387601d7e4 --- /dev/null +++ b/Documentation/git-merge-one-file-script.txt @@ -0,0 +1,30 @@ +git-merge-one-file-script(1) +============================ +v0.1, May 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> + +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-prune-script.txt b/Documentation/git-prune-script.txt new file mode 100644 index 0000000000..537b7905b6 --- /dev/null +++ b/Documentation/git-prune-script.txt @@ -0,0 +1,32 @@ +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/refs/heads/\*` and `.git/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..44fd09a97a --- /dev/null +++ b/Documentation/git-pull-script.txt @@ -0,0 +1,31 @@ +git-pull-script(1) +================== +v0.1, May 2005 + +NAME +---- +git-pull-script - Script used by Linus to pull and merge a remote repository + + +SYNOPSIS +-------- +'git-pull-script' + +DESCRIPTION +----------- +This script is used by Linus to pull from a remote repository and perform +a merge. + + +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-read-tree.txt b/Documentation/git-read-tree.txt new file mode 100644 index 0000000000..cbde13dba9 --- /dev/null +++ b/Documentation/git-read-tree.txt @@ -0,0 +1,152 @@ +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 <tree-ish1> [<tree-ish2> <tree-ish3>])" + +DESCRIPTION +----------- +Reads the tree information given by <tree> 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 or perform a 3-way +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 + +<tree-ish#>:: + The id of the tree object(s) to be read/merged. + + +Merging +------- +If '-m' is specified, "git-read-tree" performs 2 kinds of merge, a single tree +merge if only 1 tree is given 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 -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. + +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). + +In fact, the way "git-read-tree" works, it's entirely agnostic about how +you assign the stages, and you could really assign them any which way, +and the above is just a suggested way to do it (except since +"git-write-tree" refuses to write anything but stage0 entries, it makes +sense to always consider stage 0 to be the "full merge" state). + +So what happens? Try it out. Select the original tree, and two trees +to merge, and look how it works: + +- if a file exists in identical format in all three trees, it will + automatically collapse to "merged" state by the new 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 "script + policy" to determine how to remove the non-0 stages, and insert a + merged version. But since the index is always sorted, they're easy + to find: they'll be clustered together. + +- 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 .. + +Incidentally - it also means that you don't even have to have a +separate subdirectory for this. All the information literally is in +the index file, which is a temporary thing anyway. There is no need to +worry about what is in the working directory, since it is never shown +and never used. + +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-resolve-script.txt b/Documentation/git-resolve-script.txt new file mode 100644 index 0000000000..8dd84a381a --- /dev/null +++ b/Documentation/git-resolve-script.txt @@ -0,0 +1,30 @@ +git-resolve-script(1) +===================== +v0.1, May 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> + +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..f2c5fa9f4c --- /dev/null +++ b/Documentation/git-rev-list.txt @@ -0,0 +1,32 @@ +git-rev-list(1) +=============== +v0.1, May 2005 + +NAME +---- +git-rev-list - Lists commit objects in reverse chronological order + + +SYNOPSIS +-------- +'git-rev-list' <commit> + +DESCRIPTION +----------- +Lists commit objects in reverse chronological order starting at the +given commit, taking ancestry relationship into account. This is +useful to produce human-readable log output. + + +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-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-rpull.txt b/Documentation/git-rpull.txt new file mode 100644 index 0000000000..1807fc571a --- /dev/null +++ b/Documentation/git-rpull.txt @@ -0,0 +1,43 @@ +git-rpull(1) +============ +v0.1, May 2005 + +NAME +---- +git-rpull - Pulls from a remote repository over ssh connection + + + +SYNOPSIS +-------- +'git-rpull' [-c] [-t] [-a] [-v] commit-id url + +DESCRIPTION +----------- +Pulls from a remote repository over ssh connection, invoking git-rpush on +the other end. + +OPTIONS +------- +-c:: + Get the commit objects. +-t:: + Get trees associated with the commit objects. +-a:: + Get all the objects. +-v:: + Report what is downloaded. + + +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-rpush.txt b/Documentation/git-rpush.txt new file mode 100644 index 0000000000..1c1cbab1cf --- /dev/null +++ b/Documentation/git-rpush.txt @@ -0,0 +1,30 @@ +git-rpush(1) +============ +v0.1, May 2005 + +NAME +---- +git-rpush - Helper "server-side" program used by git-rpull + + +SYNOPSIS +-------- +'git-rpush' + +DESCRIPTION +----------- +Helper "server-side" program used by git-rpull. + + +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-tag-script.txt b/Documentation/git-tag-script.txt new file mode 100644 index 0000000000..daf350b5bf --- /dev/null +++ b/Documentation/git-tag-script.txt @@ -0,0 +1,32 @@ +git-tag-script(1) +================= +v0.1, May 2005 + +NAME +---- +git-tag-script - An example script to create a tag object signed with GPG + + + +SYNOPSIS +-------- +'git-tag-script' + +DESCRIPTION +----------- +This is an example script that uses "git-mktag" to create a tag object +signed with GPG. + + +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-tar-tree.txt b/Documentation/git-tar-tree.txt new file mode 100644 index 0000000000..7870e92ae9 --- /dev/null +++ b/Documentation/git-tar-tree.txt @@ -0,0 +1,32 @@ +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 as the files in the +generated tar archive. + + +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-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-update-cache.txt b/Documentation/git-update-cache.txt new file mode 100644 index 0000000000..604411d6d7 --- /dev/null +++ b/Documentation/git-update-cache.txt @@ -0,0 +1,108 @@ +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 <file>] + [--cacheinfo <mode> <object> <file>]\* + [--] [<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. + +--force-remove:: + Remove the file from the index even when the working directory + still has such a file. + +--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 +----------------- +'--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 + +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-write-blob.txt b/Documentation/git-write-blob.txt new file mode 100644 index 0000000000..22d75556e2 --- /dev/null +++ b/Documentation/git-write-blob.txt @@ -0,0 +1,33 @@ +git-write-blob(1) +================= +v0.1, May 2005 + +NAME +---- +git-write-blob - Creates a blob from a file + + +SYNOPSIS +-------- +'git-write-blob' <any-file-on-the-filesystem> + +DESCRIPTION +----------- +Writes the contents of the named file (which can be outside of the work +tree) as a blob into the object database, and reports its object ID to its +standard output. This is used by "git-merge-one-file-script" to update the +cache without modifying files in the work 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-write-tree.txt b/Documentation/git-write-tree.txt new file mode 100644 index 0000000000..458d97ac98 --- /dev/null +++ b/Documentation/git-write-tree.txt @@ -0,0 +1,52 @@ +git-write-tree(1) +================= +v0.1, May 2005 + +NAME +---- +git-write-tree - Creates a tree from the current cache + + +SYNOPSIS +-------- +'git-write-tree' + +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". + + + + +//////////////////////////////////////////////////////////////// + +Producing man pages and html + +To create a set of html pages run: + perl split-docs.pl -html < core-git.txt + +To create a set of man pages run: + perl split-docs.pl -man < core-git.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.txt b/Documentation/git.txt new file mode 100644 index 0000000000..a02ed6f426 --- /dev/null +++ b/Documentation/git.txt @@ -0,0 +1,309 @@ +git(1) +====== +v0.1, May 2005 + +NAME +---- +git - the stupid content tracker + + +SYNOPSIS +-------- +'git-<command>' <args> + +DESCRIPTION +----------- + +This is reference information for the core git commands. + +The link:README[] contains much useful definition and clarification +info - read that first. And of the commands, I suggest reading +'git-update-cache' and '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 and those that +interrogate and compare them. + +There are also some ancilliary 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-write-blob.html[git-write-blob]:: + Creates a blob from a file + +link:git-write-tree.html[git-write-tree]:: + Creates a tree from the current cache + +Interrogation commands +~~~~~~~~~~~~~~~~~~~~~~ +link:git-cat-file.html[git-cat-file]:: + Provide content or type information for repository objects + +link:git-check-files.html[git-check-files]:: + Verify a list of files are up-to-date + +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-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 + +The interrogate commands may create files - and you can force them to +touch the working file set - but in general they don't + + +Ancilliary 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-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-merge-one-file-script.html[git-merge-one-file-script]:: + The standard helper program to use with "git-merge-cache" + +link:git-pull-script.html[git-pull-script]:: + Script used by Linus to pull and merge a remote repository + +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-rpull.html[git-rpull]:: + Pulls from a remote repository over ssh connection + +Interogators: + +link:git-diff-tree-helper.html[git-diff-tree-helper]:: + Generates patch format output for git-diff-* + +link:git-rpush.html[git-rpush]:: + Helper "server-side" program used by git-rpull + + + +Terminology +----------- +see README for description + +Identifier terminology +---------------------- +<object>:: + Indicates any object sha1 identifier + +<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> that points 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 comand 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 + +It can interrogate (but never updates) the following areas: + + 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) + snap/ ???? + ... Everything else isn't shared + HEAD Symlink to refs/heads/<something> + +Higher level SCMs may provide and manage additional information in the +GIT_DIR. + +Terminology +----------- +Each line contains terms used interchangeably + + object database, .git directory + directory cache, index + id, sha1, sha1-id, sha1 hash + type, tag + blob, blob object + tree, tree object + commit, commit object + parent + root object + changeset + + +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 ":" seperated 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] + +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 + |