diff options
author | David Greaves <david@dgreaves.com> | 2005-05-10 22:32:30 +0100 |
---|---|---|
committer | Junio C Hamano <junkio@cox.net> | 2005-05-10 14:55:22 -0700 |
commit | 2cf565c53c88c557eedd7e5629437b3c6fe74329 (patch) | |
tree | bb04b39cf3fef50bc05825d953486a4d6bada056 /Documentation | |
parent | Link with -lcrypto instead of -lssl when using openssl libraries. (diff) | |
download | tgif-2cf565c53c88c557eedd7e5629437b3c6fe74329.tar.xz |
[PATCH 1/4] split core-git.txt and update
Split the core-git.txt file
Formatting fix to the diff-format.txt
Signed-off-by: David Greaves <david@dgreaves.com>
Diffstat (limited to 'Documentation')
39 files changed, 2262 insertions, 1712 deletions
diff --git a/Documentation/core-git.txt b/Documentation/core-git.txt deleted file mode 100644 index 4c80c7e9c7..0000000000 --- a/Documentation/core-git.txt +++ /dev/null @@ -1,1660 +0,0 @@ -GIT(1) -====== -v0.1, May 2005 - -//////////////////////// -Please note that this document is in asciidoc format. - http://www.methods.co.nz/asciidoc/index.html - -You should be able to read it but be aware that there is some minor -typographical bludgeoning to allow the production of clean man and -html output. - -(eg in some synopsis lines the '*' character is preceded by a '\' and -there are one or two '+' characters) - -//////////////////////// - -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. - -Manipulation commands -~~~~~~~~~~~~~~~~~~~~~ -link:git-apply-patch-script.html[git-apply-patch-script]:: - Sample script to apply the diffs from git-diff-* - -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-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-init-db.html[git-init-db]:: - Creates an empty git object database - -link:git-local-pull.html[git-local-pull]:: - Duplicates another GIT repository on a local system - -link:git-merge-base.html[git-merge-base]:: - Finds as good a common ancestor as possible for a merge - -link:git-merge-one-file-script.html[git-merge-one-file-script]:: - The standard helper program to use with "git-merge-cache" - -link:git-mktag.html[git-mktag]:: - Creates a tag object - -link:git-prune-script.html[git-prune-script]:: - Prunes all unreachable objects from the object database - -link:git-pull-script.html[git-pull-script]:: - Script used by Linus to pull and merge a remote repository - -link:git-read-tree.html[git-read-tree]:: - Reads tree information into the directory cache - -link:git-resolve-script.html[git-resolve-script]:: - Script used to merge two trees - -link:git-rpull.html[git-rpull]:: - Pulls from a remote repository over ssh connection - -link:git-tag-script.html[git-tag-script]:: - An example script to create a tag object signed with GPG - -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-diff-tree-helper.html[git-diff-tree-helper]:: - Generates patch format output for git-diff-* - -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-rpush.html[git-rpush]:: - Helper "server-side" program used by git-rpull - -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 - - -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. - -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: - -- 'GIT_AUTHOR_NAME' -- 'GIT_AUTHOR_EMAIL' -- 'GIT_AUTHOR_DATE' -- 'GIT_COMMITTER_NAME' -- 'GIT_COMMITTER_EMAIL' -- 'GIT_DIFF_OPTS' -- 'GIT_EXTERNAL_DIFF' -- 'GIT_INDEX_FILE' -- 'GIT_OBJECT_DIRECTORY' -- 'GIT_ALTERNATE_OBJECT_DIRECTORIES' - - -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. - - -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. - - -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] - - -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` - -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 - -see also: link:git-write-tree.html[git-write-tree] - - -NAME ----- -git-convert-cache - Converts old-style GIT repository - -SYNOPSIS --------- -'git-convert-cache' - -DESCRIPTION ------------ -Converts old-style GIT repository to the latest format - - -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. - - -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[] - - -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[] - - -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] - - -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. - - -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. - |