{"thread":{"id":"534","subject":"[FILES] core-git documentation update","startedAt":"2005-05-08T17:22:53Z","lastAt":"2005-05-08T21:25:36Z","messageCount":5,"participants":["David Greaves","Petr Baudis","Junio C Hamano"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"2784","messageId":"427E4AED.9050702@dgreaves.com","threadId":"534","inReplyTo":null,"subject":"[FILES] core-git documentation update","fromName":"David Greaves","fromEmail":"david@dgreaves.com","sentAt":"2005-05-08T17:22:53Z","receivedAt":"2005-05-08T17:22:53Z","isPatch":false,"sender":{"key":"david@dgreaves.com","avatar":"https://gravatar.com/avatar/ca67bad50999edcdd137c9a65da2381557d175bea99ae956afdabc5785e42b79?d=mp&s=160"},"body":"Here are some updates to the core-git docs as attachements to make them\neasier to read.\n\nI've converted the core-git.txt to asciidoc format and created a trivial\nsplitter to create individual txt, html and man pages.\n\nAs html there is a master git page with hyperlinks to all the sub-pages\nto make it easier to navigate.\n\nTo create the html:\nperl split_docs.pl -html < core-git.txt\n\nTo create the man pages:\nperl split_docs.pl -man < core-git.txt\n\nBoth create the split txt pages.\n\nRequired software:\nasciidoc for html and man pages\nxmlto for manpages\n\nDavid\n\n\n\nGIT(1)\n======\nv0.1, May 2005\n\n////////////////////////\nPlease note that this document is in asciidoc format.\n http://www.methods.co.nz/asciidoc/index.html\n\nYou should be able to read it but be aware that there is some minor\ntypographical bludgeoning to allow the production of clean man and\nhtml output.\n\n(eg in some synopsis lines the '*' character is preceded by a '\\' and\nthere are one or two '+' characters)\n\n////////////////////////\n\nNAME\n----\ngit - the stupid content tracker\n\nSYNOPSIS\n--------\n'git-' \n\nDESCRIPTION\n-----------\n\nThis is reference information for the core git commands.\n\nThe link:README[] contains much useful definition and clarification\ninfo - read that first. And of the commands, I suggest reading\n'git-update-cache' and 'git-read-tree' first - I wish I had!\n\nDavid Greaves \n08/05/05\n\nUpdated by Junio C Hamano on 2005-05-05 to\nreflect recent changes.\n\nCommands Overview\n-----------------\nThe git commands can helpfully be split into those that manipulate\nthe repository, the cache and the working fileset and those that\ninterrogate and compare them.\n\nManipulation commands\n~~~~~~~~~~~~~~~~~~~~~\nlink:git-apply-patch-script.html[git-apply-patch-script]::\n\tSample script to apply the diffs from git-diff-*\n\nlink:git-checkout-cache.html[git-checkout-cache]::\n\tCopy files from the cache to the working directory\n\nlink:git-commit-tree.html[git-commit-tree]::\n\tCreates a new commit object\n\nlink:git-convert-cache.html[git-convert-cache]::\n\tConverts old-style GIT repository\n\nlink:git-http-pull.html[git-http-pull]::\n\tDownloads a remote GIT repository via HTTP\n\nlink:git-init-db.html[git-init-db]::\n\tCreates an empty git object database\n\nlink:git-local-pull.html[git-local-pull]::\n\tDuplicates another GIT repository on a local system\n\nlink:git-merge-base.html[git-merge-base]::\n\tFinds as good a common ancestor as possible for a merge\n\nlink:git-merge-one-file-script.html[git-merge-one-file-script]::\n\tThe standard helper program to use with \"git-merge-cache\"\n\nlink:git-mktag.html[git-mktag]::\n\tCreates a tag object\n\nlink:git-prune-script.html[git-prune-script]::\n\tPrunes all unreachable objects from the object database\n\nlink:git-pull-script.html[git-pull-script]::\n\tScript used by Linus to pull and merge a remote repository\n\nlink:git-read-tree.html[git-read-tree]::\n\tReads tree information into the directory cache\n\nlink:git-resolve-script.html[git-resolve-script]::\n\tScript used to merge two trees\n\nlink:git-rpull.html[git-rpull]::\n\tPulls from a remote repository over ssh connection\n\nlink:git-tag-script.html[git-tag-script]::\n\tAn example script to create a tag object signed with GPG\n\nlink:git-update-cache.html[git-update-cache]::\n\tModifies the index or directory cache\n\nlink:git-write-blob.html[git-write-blob]::\n\tCreates a blob from a file\n\nlink:git-write-tree.html[git-write-tree]::\n\tCreates a tree from the current cache\n\nInterrogation commands\n~~~~~~~~~~~~~~~~~~~~~~\nlink:git-cat-file.html[git-cat-file]::\n\tProvide content or type information for repository objects\n\nlink:git-check-files.html[git-check-files]::\n\tVerify a list of files are up-to-date\n\nlink:git-diff-cache.html[git-diff-cache]::\n\tCompares content and mode of blobs between the cache and repository\n\nlink:git-diff-files.html[git-diff-files]::\n\tCompares files in the working tree and the cache\n\nlink:git-diff-tree.html[git-diff-tree]::\n\tCompares the content and mode of blobs found via two tree objects\n\nlink:git-diff-tree-helper.html[git-diff-tree-helper]::\n\tGenerates patch format output for git-diff-*\n\nlink:git-export.html[git-export]::\n\tExports each commit and a diff against each of its parents\n\nlink:git-fsck-cache.html[git-fsck-cache]::\n\tVerifies the connectivity and validity of the objects in the database\n\nlink:git-ls-files.html[git-ls-files]::\n\tInformation about files in the cache/working directory\n\nlink:git-ls-tree.html[git-ls-tree]::\n\tDisplays a tree object in human readable form\n\nlink:git-merge-cache.html[git-merge-cache]::\n\tRuns a merge for files needing merging\n\nlink:git-rev-list.html[git-rev-list]::\n\tLists commit objects in reverse chronological order\n\nlink:git-rev-tree.html[git-rev-tree]::\n\tProvides the revision tree for one or more commits\n\nlink:git-rpush.html[git-rpush]::\n\tHelper \"server-side\" program used by git-rpull\n\nlink:git-tar-tree.html[git-tar-tree]::\n\tCreates a tar archive of the files in the named tree\n\nlink:git-unpack-file.html[git-unpack-file]::\n\tCreates a temporary file with a blob's contents\n\nThe interrogate commands may create files - and you can force them to\ntouch the working file set - but in general they don't\n\n\nTerminology\n-----------\nsee README for description\n\nIdentifier terminology\n----------------------\n::\n\tIndicates any object sha1 identifier\n\n::\n\tIndicates a blob object sha1 identifier\n\n::\n\tIndicates a tree object sha1 identifier\n\n::\n\tIndicates a commit object sha1 identifier\n\n::\n\tIndicates a tree, commit or tag object sha1 identifier.\n\tA command that takes a argument ultimately\n\twants to operate on a object but automatically\n\tdereferences and that points at a\n\t.\n\n::\n\tIndicates that an object type is required.\n\tCurrently one of: blob/tree/commit/tag\n\n::\n\tIndicates a filename - always relative to the root of\n\tthe tree structure GIT_INDEX_FILE describes.\n\nTerminology\n-----------\nEach line contains terms used interchangeably\n\n object database, .git directory\n directory cache, index\n id, sha1, sha1-id, sha1 hash\n type, tag\n blob, blob object\n tree, tree object\n commit, commit object\n parent\n root object\n changeset\n\n\nEnvironment Variables\n---------------------\nVarious git commands use the following environment variables:\n\n- 'AUTHOR_NAME'\n- 'AUTHOR_EMAIL'\n- 'AUTHOR_DATE'\n- 'COMMIT_AUTHOR_NAME'\n- 'COMMIT_AUTHOR_EMAIL'\n- 'GIT_DIFF_OPTS'\n- 'GIT_EXTERNAL_DIFF'\n- 'GIT_INDEX_FILE'\n- 'SHA1_FILE_DIRECTORY'\n\n\nNAME\n----\ngit-apply-patch-script - Sample script to apply the diffs from git-diff-*\n\nSYNOPSIS\n--------\n'git-apply-patch-script'\n\nDESCRIPTION\n-----------\nThis is a sample script to be used via the 'GIT_EXTERNAL_DIFF'\nenvironment variable to apply the differences that the \"git-diff-*\"\nfamily of commands report to the current work tree.\n\n\nNAME\n----\ngit-cat-file - Provide content or type information for repository objects\n\nSYNOPSIS\n--------\n'git-cat-file' (-t | ) \n\nDESCRIPTION\n-----------\nProvides content or type of objects in the repository. The type\nis required if '-t' is not being used to find the object type.\n\nOPTIONS\n-------\n::\n\tThe sha1 identifier of the object.\n\n-t::\n\tInstead of the content, show the object type identified by\n\t.\n\n::\n\tTypically this matches the real type of but asking\n\tfor a type that can trivially dereferenced from the given\n\t is also permitted. An example is to ask for a\n\t\"tree\" with being a commit object that contains it,\n\tor to ask for a \"blob\" with being a tag object that\n\tpoints at it.\n\nOUTPUT\n------\nIf '-t' is specified, one of the .\n\nOtherwise the raw (though uncompressed) contents of the will\nbe returned.\n\n\nNAME\n----\ngit-check-files - Verify a list of files are up-to-date\n\n\nSYNOPSIS\n--------\n'git-check-files' ...\n\nDESCRIPTION\n-----------\nCheck that a list of files are up-to-date between the filesystem and\nthe cache. Used to verify a patch target before doing a patch.\n\nFiles that do not exist on the filesystem are considered up-to-date\n(whether or not they are in the cache).\n\nEmits an error message on failure:\n\npreparing to update existing file not in cache::\n\t exists but is not in the cache\n\npreparing to update file not uptodate in cache::\n\t on disk is not up-to-date with the cache\n\nExits with a status code indicating success if all files are\nup-to-date.\n\nsee also: link:git-update-cache.html[git-update-cache]\n\n\nNAME\n----\ngit-checkout-cache - Copy files from the cache to the working directory\n\nSYNOPSIS\n--------\n'git-checkout-cache' [-q] [-a] [-f] [-n] [--prefix=]\n\t [--] ...\n\nDESCRIPTION\n-----------\nWill copy all files listed from the cache to the working directory\n(not overwriting existing files).\n\nOPTIONS\n-------\n-q::\n\tbe quiet if files exist or are not in the cache\n\n-f::\n\tforces overwrite of existing files\n\n-a::\n\tchecks out all files in the cache (will then continue to\n\tprocess listed files).\n\n-n::\n\tDon't checkout new files, only refresh files already checked\n\tout.\n\n--prefix=::\n\tWhen creating files, prepend (usually a directory\n\tincluding a trailing /)\n\n--::\n\tDo not interpret any more arguments as options.\n\nNote that the order of the flags matters:\n\n git-checkout-cache -a -f file.c\n\nwill first check out all files listed in the cache (but not overwrite\nany old ones), and then force-checkout `file.c` a second time (ie that\none *will* overwrite any old contents with the same filename).\n\nAlso, just doing \"git-checkout-cache\" does nothing. You probably meant\n\"git-checkout-cache -a\". And if you want to force it, you want\n\"git-checkout-cache -f -a\".\n\nIntuitiveness is not the goal here. Repeatability is. The reason for\nthe \"no arguments means no work\" thing is that from scripts you are\nsupposed to be able to do things like:\n\n\tfind . -name '*.h' -print0 | xargs -0 git-checkout-cache -f --\n\nwhich will force all existing `*.h` files to be replaced with their\ncached copies. If an empty command line implied \"all\", then this would\nforce-refresh everything in the cache, which was not the point.\n\nTo update and refresh only the files already checked out:\n\n git-checkout-cache -n -f -a && git-update-cache --ignore-missing --refresh\n\nOh, and the \"--\" is just a good idea when you know the rest will be\nfilenames. Just so that you wouldn't have a filename of \"-a\" causing\nproblems (not possible in the above example, but get used to it in\nscripting!).\n\nThe prefix ability basically makes it trivial to use\ngit-checkout-cache as an \"export as tree\" function. Just read the\ndesired tree into the index, and do a\n \n git-checkout-cache --prefix=git-export-dir/ -a\n \nand git-checkout-cache will \"export\" the cache into the specified\ndirectory.\n \nNOTE The final \"/\" is important. The exported name is literally just\nprefixed with the specified string, so you can also do something like\n\n git-checkout-cache --prefix=.merged- Makefile\n\nto check out the currently cached copy of `Makefile` into the file\n`.merged-Makefile`\n\nNAME\n----\ngit-commit-tree - Creates a new commit object\n\nSYNOPSIS\n--------\n'git-commit-tree' [-p ]\\ < changelog\n\nDESCRIPTION\n-----------\nCreates a new commit object based on the provided tree object and\nemits the new commit object id on stdout. If no parent is given then\nit is considered to be an initial tree.\n\nA commit object usually has 1 parent (a commit after a change) or up\nto 16 parents. More than one parent represents a merge of branches\nthat led to them.\n\nWhile a tree represents a particular directory state of a working\ndirectory, a commit represents that state in \"time\", and explains how\nto get there.\n\nNormally a commit would identify a new \"HEAD\" state, and while git\ndoesn't care where you save the note about that state, in practice we\ntend to just write the result to the file `.git/HEAD`, so that we can\nalways see what the last committed state was.\n\nOPTIONS\n-------\n::\n\tAn existing tree object\n\n-p ::\n\tEach '-p' indicates a the id of a parent commit object.\n\t\n\nCommit Information\n------------------\n\nA commit encapsulates:\n\n- all parent object ids\n- author name, email and date\n- committer name and email and the commit time.\n\nIf not provided, \"git-commit-tree\" uses your name, hostname and domain to\nprovide author and committer info. This can be overridden using the\nfollowing environment variables.\n\n\tAUTHOR_NAME\n\tAUTHOR_EMAIL\n\tAUTHOR_DATE\n\tCOMMIT_AUTHOR_NAME\n\tCOMMIT_AUTHOR_EMAIL\n\n(nb <,> and '\\n's are stripped)\n\nA commit comment is read from stdin (max 999 chars). If a changelog\nentry is not provided via '<' redirection, \"git-commit-tree\" will just wait\nfor one to be entered and terminated with ^D\n\nsee also: link:git-write-tree.html[git-write-tree]\n\n\nNAME\n----\ngit-convert-cache - Converts old-style GIT repository\n\nSYNOPSIS\n--------\n'git-convert-cache'\n\nDESCRIPTION\n-----------\nConverts old-style GIT repository to the latest format\n\n\nNAME\n----\ngit-diff-cache - Compares content and mode of blobs between the cache and repository\n\nSYNOPSIS\n--------\n'git-diff-cache' [-p] [-r] [-z] [--cached] \n\nDESCRIPTION\n-----------\nCompares the content and mode of the blobs found via a tree object\nwith the content of the current cache and, optionally ignoring the\nstat state of the file on disk.\n\nOPTIONS\n-------\n::\n\tThe id of a tree object to diff against.\n\n-p::\n\tGenerate patch (see section on generating patches)\n\n-r::\n\tThis flag does not mean anything. It is there only to match\n\t\"git-diff-tree\". Unlike \"git-diff-tree\", \"git-diff-cache\"\n\talways looks at all the subdirectories.\n\n-z::\n\t\\0 line termination on output\n\n--cached::\n\tdo not consider the on-disk file at all\n\nOutput format\n-------------\ninclude::diff-format.txt[]\n\nOperating Modes\n---------------\nYou can choose whether you want to trust the index file entirely\n(using the '--cached' flag) or ask the diff logic to show any files\nthat don't match the stat state as being \"tentatively changed\". Both\nof these operations are very useful indeed.\n\nCached Mode\n-----------\nIf '--cached' is specified, it allows you to ask:\n\n\tshow me the differences between HEAD and the current index\n\tcontents (the ones I'd write with a \"git-write-tree\")\n\nFor example, let's say that you have worked on your index file, and are\nready to commit. You want to see eactly *what* you are going to commit is\nwithout having to write a new tree object and compare it that way, and to\ndo that, you just do\n\n\tgit-diff-cache --cached $(cat .git/HEAD)\n\nExample: let's say I had renamed `commit.c` to `git-commit.c`, and I had\ndone an \"git-update-cache\" to make that effective in the index file.\n\"git-diff-files\" wouldn't show anything at all, since the index file\nmatches my working directory. But doing a \"git-diff-cache\" does:\n\n torvalds@ppc970:~/git> git-diff-cache --cached $(cat .git/HEAD)\n -100644 blob 4161aecc6700a2eb579e842af0b7f22b98443f74 commit.c\n +100644 blob 4161aecc6700a2eb579e842af0b7f22b98443f74 git-commit.c\n\nYou can trivially see that the above is a rename.\n\nIn fact, \"git-diff-cache --cached\" *should* always be entirely equivalent to\nactually doing a \"git-write-tree\" and comparing that. Except this one is much\nnicer for the case where you just want to check where you are.\n\nSo doing a \"git-diff-cache --cached\" is basically very useful when you are \nasking yourself \"what have I already marked for being committed, and \nwhat's the difference to a previous tree\".\n\nNon-cached Mode\n---------------\nThe \"non-cached\" mode takes a different approach, and is potentially\nthe more useful of the two in that what it does can't be emulated with\na \"git-write-tree\" + \"git-diff-tree\". Thus that's the default mode.\nThe non-cached version asks the question:\n\n show me the differences between HEAD and the currently checked out\n tree - index contents _and_ files that aren't up-to-date\n\nwhich is obviously a very useful question too, since that tells you what\nyou *could* commit. Again, the output matches the \"git-diff-tree -r\"\noutput to a tee, but with a twist.\n\nThe twist is that if some file doesn't match the cache, we don't have\na backing store thing for it, and we use the magic \"all-zero\" sha1 to\nshow that. So let's say that you have edited `kernel/sched.c`, but\nhave not actually done a \"git-update-cache\" on it yet - there is no\n\"object\" associated with the new state, and you get:\n\n torvalds@ppc970:~/v2.6/linux> git-diff-cache $(cat .git/HEAD )\n *100644->100664 blob 7476bb......->000000...... kernel/sched.c\n\nie it shows that the tree has changed, and that `kernel/sched.c` has is\nnot up-to-date and may contain new stuff. The all-zero sha1 means that to\nget the real diff, you need to look at the object in the working directory\ndirectly rather than do an object-to-object diff.\n\nNOTE! As with other commands of this type, \"git-diff-cache\" does not\nactually look at the contents of the file at all. So maybe\n`kernel/sched.c` hasn't actually changed, and it's just that you\ntouched it. In either case, it's a note that you need to\n\"git-upate-cache\" it to make the cache be in sync.\n\nNOTE 2! You can have a mixture of files show up as \"has been updated\"\nand \"is still dirty in the working directory\" together. You can always\ntell which file is in which state, since the \"has been updated\" ones\nshow a valid sha1, and the \"not in sync with the index\" ones will\nalways have the special all-zero sha1.\n\n\nNAME\n----\ngit-diff-files - Compares files in the working tree and the cache\n\nSYNOPSIS\n--------\n'git-diff-files' [-p] [-q] [-r] [-z] [...]\n\nDESCRIPTION\n-----------\nCompares the files in the working tree and the cache. When paths\nare specified, compares only those named paths. Otherwise all\nentries in the cache are compared. The output format is the\nsame as \"git-diff-cache\" and \"git-diff-tree\".\n\nOPTIONS\n-------\n-p::\n\tgenerate patch (see section on generating patches).\n\n-q::\n\tRemain silent even on nonexisting files\n\n-r::\n\tThis flag does not mean anything. It is there only to match\n\tgit-diff-tree. Unlike git-diff-tree, git-diff-files always looks\n\tat all the subdirectories.\n\n\nOutput format\n-------------\ninclude::diff-format.txt[]\n\n\nNAME\n----\ngit-diff-tree - Compares the content and mode of blobs found via two tree objects\n\nSYNOPSIS\n--------\n'git-diff-tree' [-p] [-r] [-z] [--stdin] [-m] [-s] [-v] []\\*\n\nDESCRIPTION\n-----------\nCompares the content and mode of the blobs found via two tree objects.\n\nNote that \"git-diff-tree\" can use the tree encapsulated in a commit object.\n\nOPTIONS\n-------\n::\n\tThe id of a tree object.\n\n::\n\tIf provided, the results are limited to a subset of files\n\tmatching one of these prefix strings.\n\tie file matches `/^||.../`\n\tNote that pattern does not provide any wildcard or regexp\n\tfeatures.\n\n-p::\n\tgenerate patch (see section on generating patches). For\n\tgit-diff-tree, this flag implies '-r' as well.\n\n-r::\n\trecurse\n\n-z::\n\t\\0 line termination on output\n\n--stdin::\n\tWhen '--stdin' is specified, the command does not take\n\t arguments from the command line. Instead, it\n\treads either one or a pair of \n\tseparated with a single space from its standard input.\n+\nWhen a single commit is given on one line of such input, it compares\nthe commit with its parents. The following flags further affects its\nbehaviour. This does not apply to the case where two \nseparated with a single space are given.\n\n-m::\n\tBy default, \"git-diff-tree --stdin\" does not show\n\tdifferences for merge commits. With this flag, it shows\n\tdifferences to that commit from all of its parents.\n\n-s::\n\tBy default, \"git-diff-tree --stdin\" shows differences,\n\teither in machine-readable form (without '-p') or in patch\n\tform (with '-p'). This output can be supressed. It is\n\tonly useful with '-v' flag.\n\n-v::\n\tThis flag causes \"git-diff-tree --stdin\" to also show\n\tthe commit message before the differences.\n\n\nLimiting Output\n---------------\nIf you're only interested in differences in a subset of files, for\nexample some architecture-specific files, you might do:\n\n\tgit-diff-tree -r arch/ia64 include/asm-ia64\n\nand it will only show you what changed in those two directories.\n\nOr if you are searching for what changed in just `kernel/sched.c`, just do\n\n\tgit-diff-tree -r kernel/sched.c\n\nand it will ignore all differences to other files.\n\nThe pattern is always the prefix, and is matched exactly. There are no\nwildcards. Even stricter, it has to match complete path comonent.\nI.e. \"foo\" does not pick up `foobar.h`. \"foo\" does match `foo/bar.h`\nso it can be used to name subdirectories.\n\nAn example of normal usage is:\n\n torvalds@ppc970:~/git> git-diff-tree 5319e4......\n *100664->100664 blob ac348b.......->a01513....... git-fsck-cache.c\n\nwhich tells you that the last commit changed just one file (it's from\nthis one:\n\n commit 3c6f7ca19ad4043e9e72fa94106f352897e651a8\n tree 5319e4d609cdd282069cc4dce33c1db559539b03\n parent b4e628ea30d5ab3606119d2ea5caeab141d38df7\n author Linus Torvalds Sat Apr 9 12:02:30 2005\n committer Linus Torvalds Sat Apr 9 12:02:30 2005\n\n Make \"git-fsck-cache\" print out all the root commits it finds.\n\n Once I do the reference tracking, I'll also make it print out all the\n HEAD commits it finds, which is even more interesting.\n\nin case you care).\n\nOutput format\n-------------\ninclude::diff-format.txt[]\n\n\nNAME\n----\ngit-diff-tree-helper - Generates patch format output for git-diff-*\n\nSYNOPSIS\n--------\n'git-diff-tree-helper' [-z] [-R]\n\nDESCRIPTION\n-----------\nReads output from \"git-diff-cache\", \"git-diff-tree\" and \"git-diff-files\" and\ngenerates patch format output.\n\nOPTIONS\n-------\n-z::\n\t\\0 line termination on input\n\n-R::\n\tOutput diff in reverse. This is useful for displaying output from\n\t\"git-diff-cache\" which always compares tree with cache or working\n\tfile. E.g.\n\n\t\tgit-diff-cache | git-diff-tree-helper -R file.c\n+\nwould show a diff to bring the working file back to what is in the .\n\nSee also the section on generating patches in link:git-diff-cache.html[git-diff-cache]\n\n\nNAME\n----\ngit-export - Exports each commit and a diff against each of its parents\n\nSYNOPSIS\n--------\n'git-export' top [base]\n\nDESCRIPTION\n-----------\nExports each commit and diff against each of its parents, between\ntop and base. If base is not specified it exports everything.\n\n\nNAME\n----\ngit-fsck-cache - Verifies the connectivity and validity of the objects in the database\n\nSYNOPSIS\n--------\n'git-fsck-cache' [--tags] [--root] [[--unreachable] [--cache] \\*]\n\nDESCRIPTION\n-----------\nVerifies the connectivity and validity of the objects in the database.\n\nOPTIONS\n-------\n::\n\tAn object to treat as the head of an unreachability trace.\n\n--unreachable::\n\tPrint out objects that exist but that aren't readable from any\n\tof the specified head nodes.\n\n--root::\n\tReport root nodes.\n\n--tags::\n\tReport tags.\n\n--cache::\n\tConsider any object recorded in the cache also as a head node for\n\tan unreachability trace.\n\nIt tests SHA1 and general object sanity, and it does full tracking of\nthe resulting reachability and everything else. It prints out any\ncorruption it finds (missing or bad objects), and if you use the\n'--unreachable' flag it will also print out objects that exist but\nthat aren't readable from any of the specified head nodes.\n\nSo for example\n\n\tgit-fsck-cache --unreachable $(cat .git/HEAD)\n\nor, for Cogito users:\n\n\tgit-fsck-cache --unreachable $(cat .git/refs/heads/*)\n\nwill do quite a _lot_ of verification on the tree. There are a few\nextra validity tests to be added (make sure that tree objects are\nsorted properly etc), but on the whole if \"git-fsck-cache\" is happy, you\ndo have a valid tree.\n\nAny corrupt objects you will have to find in backups or other archives\n(ie you can just remove them and do an \"rsync\" with some other site in\nthe hopes that somebody else has the object you have corrupted).\n\nOf course, \"valid tree\" doesn't mean that it wasn't generated by some\nevil person, and the end result might be crap. Git is a revision\ntracking system, not a quality assurance system ;)\n\nExtracted Diagnostics\n---------------------\n\nexpect dangling commits - potential heads - due to lack of head information::\n\tYou haven't specified any nodes as heads so it won't be\n\tpossible to differentiate between un-parented commits and\n\troot nodes.\n\nmissing sha1 directory ''::\n\tThe directory holding the sha1 objects is missing.\n\nunreachable ::\n\tThe object , isn't actually referred to directly\n\tor indirectly in any of the trees or commits seen. This can\n\tmean that there's another root node that you're not specifying\n\tor that the tree is corrupt. If you haven't missed a root node\n\tthen you might as well delete unreachable nodes since they\n\tcan't be used.\n\nmissing ::\n\tThe object , is referred to but isn't present in\n\tthe database.\n\ndangling ::\n\tThe object , is present in the database but never\n\t'directly' used. A dangling commit could be a root node.\n\nwarning: git-fsck-cache: tree has full pathnames in it::\n\tAnd it shouldn't...\n\nsha1 mismatch ::\n\tThe database has an object who's sha1 doesn't match the\n\tdatabase value.\n\tThis indicates a serious data integrity problem.\n\t(note: this error occured during early git development when\n\tthe database format changed.)\n\nEnvironment Variables\n---------------------\n\nSHA1_FILE_DIRECTORY::\n\tused to specify the object database root (usually .git/objects)\n\nGIT_INDEX_FILE::\n\tused to specify the cache\n\n\nNAME\n----\ngit-http-pull - Downloads a remote GIT repository via HTTP\n\nSYNOPSIS\n--------\n'git-http-pull' [-c] [-t] [-a] [-v] commit-id url\n\nDESCRIPTION\n-----------\nDownloads a remote GIT repository via HTTP.\n\n-c::\n\tGet the commit objects.\n-t::\n\tGet trees associated with the commit objects.\n-a::\n\tGet all the objects.\n-v::\n\tReport what is downloaded.\n\n\nNAME\n----\ngit-init-db - Creates an empty git object database\n\nSYNOPSIS\n--------\n'git-init-db'\n\nDESCRIPTION\n-----------\nThis simply creates an empty git object database - basically a `.git`\ndirectory and `.git/object/??/` directories.\n\nIf the object storage directory is specified via the 'SHA1_FILE_DIRECTORY'\nenvironment variable then the sha1 directories are created underneath -\notherwise the default `.git/objects` directory is used.\n\n\"git-init-db\" won't hurt an existing repository.\n\n\nNAME\n----\ngit-local-pull - Duplicates another GIT repository on a local system\n\nSYNOPSIS\n--------\n'git-local-pull' [-c] [-t] [-a] [-l] [-s] [-n] [-v] commit-id path\n\nDESCRIPTION\n-----------\nDuplicates another GIT repository on a local system.\n\nOPTIONS\n-------\n-c::\n\tGet the commit objects.\n-t::\n\tGet trees associated with the commit objects.\n-a::\n\tGet all the objects.\n-v::\n\tReport what is downloaded.\n\nNAME\n----\ngit-ls-files - Information about files in the cache/working directory\n\nSYNOPSIS\n--------\n'git-ls-files' [-z] [-t]\n\t\t(--[cached|deleted|others|ignored|stage|unmerged])\\*\n\t\t(-[c|d|o|i|s|u])\\*\n\t\t[-x |--exclude=]\n\t\t[-X |--exclude-from=]\n\nDESCRIPTION\n-----------\nThis merges the file listing in the directory cache index with the\nactual working directory list, and shows different combinations of the\ntwo.\n\nOne or more of the options below may be used to determine the files\nshown:\n\nOPTIONS\n-------\n-c|--cached::\n\tShow cached files in the output (default)\n\n-d|--deleted::\n\tShow deleted files in the output\n\n-o|--others::\n\tShow other files in the output\n\n-i|--ignored::\n\tShow ignored files in the output\n\tNote the this also reverses any exclude list present.\n\n-s|--stage::\n\tShow stage files in the output\n\n-u|--unmerged::\n\tShow unmerged files in the output (forces --stage)\n\n-z::\n\t\\0 line termination on output\n\n-x|--exclude=::\n\tSkips files matching pattern.\n\tNote that pattern is a shell wildcard pattern.\n\n-X|--exclude-from=::\n\texclude patterns are read from ; 1 per line.\n\tAllows the use of the famous dontdiff file as follows to find\n\tout about uncommitted files just as dontdiff is used with\n\tthe diff command:\n\t git-ls-files --others --exclude-from=dontdiff\n\n-t::\n\tIdentify the file status with the following tags (followed by\n\ta space) at the start of each line:\n\tH\tcached\n\tM\tunmerged\n\tR\tremoved/deleted\n\t?\tother\n\nOutput\n------\nshow files just outputs the filename unless '--stage' is specified in\nwhich case it outputs:\n\n [ ] \n\n\"git-ls-files --unmerged\" and \"git-ls-files --stage\" can be used to examine\ndetailed information on unmerged paths.\n\nFor an unmerged path, instead of recording a single mode/SHA1 pair,\nthe dircache records up to three such pairs; one from tree O in stage\n1, A in stage 2, and B in stage 3. This information can be used by\nthe user (or Cogito) to see what should eventually be recorded at the\npath. (see read-cache for more information on state)\n\nsee also: link:read-cache.html[read-cache]\n\n\nNAME\n----\ngit-ls-tree - Displays a tree object in human readable form\n\nSYNOPSIS\n--------\n'git-ls-tree' [-r] [-z] \n\nDESCRIPTION\n-----------\nConverts the tree object to a human readable (and script processable)\nform.\n\nOPTIONS\n-------\n::\n\tId of a tree.\n\n-r::\n\trecurse into sub-trees\n\n-z::\n\t\\0 line termination on output\n\nOutput Format\n-------------\n \\t\t\\t\t\\t\t\n\n\nNAME\n----\ngit-merge-base - Finds as good a common ancestor as possible for a merge\n\nSYNOPSIS\n--------\n'git-merge-base' \n\nDESCRIPTION\n-----------\n\"git-merge-base\" finds as good a common ancestor as possible. Given a\nselection of equally good common ancestors it should not be relied on\nto decide in any particular way.\n\nThe \"git-merge-base\" algorithm is still in flux - use the source...\n\n\nNAME\n----\ngit-merge-cache - Runs a merge for files needing merging\n\nSYNOPSIS\n--------\n'git-merge-cache' (-a | -- | \\*) \n\nDESCRIPTION\n-----------\nThis looks up the (s) in the cache and, if there are any merge\nentries, passes the SHA1 hash for those files as arguments 1, 2, 3 (empty\nargument if no file), and as argument 4. File modes for the three\nfiles are passed as arguments 5, 6 and 7.\n\nOPTIONS\n-------\n--::\n\tInterpret all future arguments as filenames.\n\n-a::\n\tRun merge against all files in the cache that need merging.\n\nIf \"git-merge-cache\" is called with multiple s (or -a) then it\nprocesses them in turn only stopping if merge returns a non-zero exit\ncode.\n\nTypically this is run with the a script calling the merge command from\nthe RCS package.\n\nA sample script called \"git-merge-one-file-script\" is included in the\nditribution.\n\nALERT ALERT ALERT! The git \"merge object order\" is different from the\nRCS \"merge\" program merge object order. In the above ordering, the\noriginal is first. But the argument order to the 3-way merge program\n\"merge\" is to have the original in the middle. Don't ask me why.\n\nExamples:\n\n torvalds@ppc970:~/merge-test> git-merge-cache cat MM\n This is MM from the original tree.\t\t\t# original\n This is modified MM in the branch A.\t\t\t# merge1\n This is modified MM in the branch B.\t\t\t# merge2\n This is modified MM in the branch B.\t\t\t# current contents\n\nor \n\n torvalds@ppc970:~/merge-test> git-merge-cache cat AA MM\n cat: : No such file or directory\n This is added AA in the branch A.\n This is added AA in the branch B.\n This is added AA in the branch B.\n fatal: merge program failed\n\nwhere the latter example shows how \"git-merge-cache\" will stop trying to\nmerge once anything has returned an error (ie \"cat\" returned an error\nfor the AA file, because it didn't exist in the original, and thus\n\"git-merge-cache\" didn't even try to merge the MM thing).\n\nNAME\n----\ngit-merge-one-file-script - The standard helper program to use with \"git-merge-cache\"\n\nSYNOPSIS\n--------\n'git-merge-one-file-script'\n\nDESCRIPTION\n-----------\nThis is the standard helper program to use with \"git-merge-cache\"\nto resolve a merge after the trivial merge done with \"git-read-tree -m\".\n\nNAME\n----\ngit-mktag - Creates a tag object\n\nSYNOPSIS\n--------\n'git-mktag'\n\nDESCRIPTION\n-----------\nReads a tag contents from its standard input and creates a tag object.\nThe input must be a well formed tag object.\n\n\nNAME\n----\ngit-prune-script - Prunes all unreachable objects from the object database\n\nSYNOPSIS\n--------\n'git-prune-script'\n\nDESCRIPTION\n-----------\nThis runs \"git-fsck-cache --unreachable\" program using the heads specified\non the command line (or `.git/refs/heads/\\*` and `.git/refs/tags/\\*` if none is\nspecified), and prunes all unreachable objects from the object database.\n\n\nNAME\n----\ngit-pull-script - Script used by Linus to pull and merge a remote repository\n\nSYNOPSIS\n--------\n'git-pull-script'\n\nDESCRIPTION\n-----------\nThis script is used by Linus to pull from a remote repository and perform\na merge.\n\n\nNAME\n----\ngit-read-tree - Reads tree information into the directory cache\n\nSYNOPSIS\n--------\n'git-read-tree' ( | -m [ ])\"\n\nDESCRIPTION\n-----------\nReads the tree information given by into the directory cache,\nbut does not actually _update_ any of the files it \"caches\". (see:\ngit-checkout-cache)\n\nOptionally, it can merge a tree into the cache or perform a 3-way\nmerge.\n\nTrivial merges are done by \"git-read-tree\" itself. Only conflicting paths\nwill be in unmerged state when \"git-read-tree\" returns.\n\nOPTIONS\n-------\n-m::\n\tPerform a merge, not just a read\n\n::\n\tThe id of the tree object(s) to be read/merged.\n\n\nMerging\n-------\nIf '-m' is specified, \"git-read-tree\" performs 2 kinds of merge, a single tree\nmerge if only 1 tree is given or a 3-way merge if 3 trees are\nprovided.\n\nSingle Tree Merge\n~~~~~~~~~~~~~~~~~\nIf only 1 tree is specified, git-read-tree operates as if the user did not\nspecify '-m', except that if the original cache has an entry for a\ngiven pathname; and the contents of the path matches with the tree\nbeing read, the stat info from the cache is used. (In other words, the\ncache's stat()s take precedence over the merged tree's)\n\nThat means that if you do a \"git-read-tree -m \" followed by a\n\"git-checkout-cache -f -a\", the \"git-checkout-cache\" only checks out\nthe stuff that really changed.\n\nThis is used to avoid unnecessary false hits when \"git-diff-files\" is\nrun after git-read-tree.\n\n3-Way Merge\n~~~~~~~~~~~\nEach \"index\" entry has two bits worth of \"stage\" state. stage 0 is the\nnormal one, and is the only one you'd see in any kind of normal use.\n\nHowever, when you do \"git-read-tree\" with three trees, the \"stage\"\nstarts out at 1.\n\nThis means that you can do\n\n\tgit-read-tree -m \n\nand you will end up with an index with all of the entries in\n\"stage1\", all of the entries in \"stage2\" and all of the\n entries in \"stage3\".\n\nFurthermore, \"git-read-tree\" has special-case logic that says: if you see\na file that matches in all respects in the following states, it\n\"collapses\" back to \"stage0\":\n\n - stage 2 and 3 are the same; take one or the other (it makes no\n difference - the same work has been done on stage 2 and 3)\n\n - stage 1 and stage 2 are the same and stage 3 is different; take\n stage 3 (some work has been done on stage 3)\n\n - stage 1 and stage 3 are the same and stage 2 is different take\n stage 2 (some work has been done on stage 2)\n\nThe \"git-write-tree\" command refuses to write a nonsensical tree, and it\nwill complain about unmerged entries if it sees a single entry that is not\nstage 0.\n\nOk, this all sounds like a collection of totally nonsensical rules,\nbut it's actually exactly what you want in order to do a fast\nmerge. The different stages represent the \"result tree\" (stage 0, aka\n\"merged\"), the original tree (stage 1, aka \"orig\"), and the two trees\nyou are trying to merge (stage 2 and 3 respectively).\n\nIn fact, the way \"git-read-tree\" works, it's entirely agnostic about how\nyou assign the stages, and you could really assign them any which way,\nand the above is just a suggested way to do it (except since\n\"git-write-tree\" refuses to write anything but stage0 entries, it makes\nsense to always consider stage 0 to be the \"full merge\" state).\n\nSo what happens? Try it out. Select the original tree, and two trees\nto merge, and look how it works:\n\n- if a file exists in identical format in all three trees, it will\n automatically collapse to \"merged\" state by the new git-read-tree.\n\n- a file that has _any_ difference what-so-ever in the three trees\n will stay as separate entries in the index. It's up to \"script\n policy\" to determine how to remove the non-0 stages, and insert a\n merged version. But since the index is always sorted, they're easy\n to find: they'll be clustered together.\n\n- the index file saves and restores with all this information, so you\n can merge things incrementally, but as long as it has entries in\n stages 1/2/3 (ie \"unmerged entries\") you can't write the result. So\n now the merge algorithm ends up being really simple:\n\n * you walk the index in order, and ignore all entries of stage 0,\n since they've already been done.\n\n * if you find a \"stage1\", but no matching \"stage2\" or \"stage3\", you\n know it's been removed from both trees (it only existed in the\n original tree), and you remove that entry.\n\n * if you find a matching \"stage2\" and \"stage3\" tree, you remove one\n of them, and turn the other into a \"stage0\" entry. Remove any\n matching \"stage1\" entry if it exists too. .. all the normal\n trivial rules ..\n\nIncidentally - it also means that you don't even have to have a\nseparate subdirectory for this. All the information literally is in\nthe index file, which is a temporary thing anyway. There is no need to\nworry about what is in the working directory, since it is never shown\nand never used.\n\nsee also: link:git-write-tree.html[git-write-tree], link:git-ls-files.html[git-ls-files]\n\n\nNAME\n----\ngit-resolve-script - Script used to merge two trees\n\nSYNOPSIS\n--------\n'git-resolve-script'\n\nDESCRIPTION\n-----------\nThis script is used by Linus to merge two trees.\n\n\nNAME\n----\ngit-rev-list - Lists commit objects in reverse chronological order\n\nSYNOPSIS\n--------\n'git-rev-list' \n\nDESCRIPTION\n-----------\nLists commit objects in reverse chronological order starting at the\ngiven commit, taking ancestry relationship into account. This is\nuseful to produce human-readable log output.\n\n\nNAME\n----\ngit-rev-tree - Provides the revision tree for one or more commits\n\nSYNOPSIS\n--------\n'git-rev-tree' [--edges] [--cache ] [^] [[^]]\n\nDESCRIPTION\n-----------\nProvides the revision tree for one or more commits.\n\nOPTIONS\n-------\n--edges::\n\tShow edges (ie places where the marking changes between parent\n\tand child)\n\n--cache ::\n\tUse the specified file as a cache from a previous git-rev-list run\n\tto speed things up. Note that this \"cache\" is totally different\n\tconcept from the directory index. Also this option is not\n\timplemented yet.\n\n[^]::\n\tThe commit id to trace (a leading caret means to ignore this\n\tcommit-id and below)\n\nOutput\n------\n\n : [: ]\\*\n\n::\n\tDate in 'seconds since epoch'\n\n::\n\tid of commit object\n\n::\n\tid of each parent commit object (>1 indicates a merge)\n\n::\n\n\tThe flags are read as a bitmask representing each commit\n\tprovided on the commandline. eg: given the command:\n\n\t\t $ git-rev-tree \n\n\tThe output:\n\n\t :5\n\n\t means that is reachable from (1) and (4)\n\t\nA revtree can get quite large. \"git-rev-tree\" will eventually allow\nyou to cache previous state so that you don't have to follow the whole\nthing down.\n\nSo the change difference between two commits is literally\n\n\tgit-rev-tree [commit-id1] > commit1-revtree\n\tgit-rev-tree [commit-id2] > commit2-revtree\n\tjoin -t : commit1-revtree commit2-revtree > common-revisions\n\n(this is also how to find the most common parent - you'd look at just\nthe head revisions - the ones that aren't referred to by other\nrevisions - in \"common-revision\", and figure out the best one. I\nthink.)\n\n\nNAME\n----\ngit-rpull - Pulls from a remote repository over ssh connection\n\n\nSYNOPSIS\n--------\n'git-rpull' [-c] [-t] [-a] [-v] commit-id url\n\nDESCRIPTION\n-----------\nPulls from a remote repository over ssh connection, invoking git-rpush on\nthe other end.\n\nOPTIONS\n-------\n-c::\n\tGet the commit objects.\n-t::\n\tGet trees associated with the commit objects.\n-a::\n\tGet all the objects.\n-v::\n\tReport what is downloaded.\n\n\nNAME\n----\ngit-rpush - Helper \"server-side\" program used by git-rpull\n\nSYNOPSIS\n--------\n'git-rpush'\n\nDESCRIPTION\n-----------\nHelper \"server-side\" program used by git-rpull.\n\n\nNAME\n----\ngit-tag-script - An example script to create a tag object signed with GPG\n\n\nSYNOPSIS\n--------\n'git-tag-script'\n\nDESCRIPTION\n-----------\nThis is an example script that uses \"git-mktag\" to create a tag object\nsigned with GPG.\n\n\nNAME\n----\ngit-tar-tree - Creates a tar archive of the files in the named tree\n\nSYNOPSIS\n--------\n'git-tar-tree' [ ]\n\nDESCRIPTION\n-----------\nCreates a tar archive containing the tree structure for the named tree.\nWhen is specified it is added as a leading path as the files in the\ngenerated tar archive.\n\n\nNAME\n----\ngit-unpack-file - Creates a temporary file with a blob's contents\n\n\nSYNOPSIS\n--------\n'git-unpack-file' \n\nDESCRIPTION\n-----------\nCreates a file holding the contents of the blob specified by sha1. It\nreturns the name of the temporary file in the following format:\n\t.merge_file_XXXXX\n\nOPTIONS\n-------\n::\n\tMust be a blob id\n\nNAME\n----\ngit-update-cache - Modifies the index or directory cache\n\nSYNOPSIS\n--------\n'git-update-cache'\n\t [--add] [--remove] [--refresh]\n\t [--ignore-missing]\n\t [--force-remove ]\n\t [--cacheinfo ]\\*\n\t [--] []\\*\n\nDESCRIPTION\n-----------\nModifies the index or directory cache. Each file mentioned is updated\ninto the cache and any 'unmerged' or 'needs updating' state is\ncleared.\n\nThe way \"git-update-cache\" handles files it is told about can be modified\nusing the various options:\n\nOPTIONS\n-------\n--add::\n\tIf a specified file isn't in the cache already then it's\n\tadded.\n\tDefault behaviour is to ignore new files.\n\n--remove::\n\tIf a specified file is in the cache but is missing then it's\n\tremoved.\n\tDefault behaviour is to ignore removed file.\n\n--refresh::\n\tLooks at the current cache and checks to see if merges or\n\tupdates are needed by checking stat() information.\n\n--ignore-missing::\n\tIgnores missing files during a --refresh\n\n--cacheinfo ::\n\tDirectly insert the specified info into the cache.\n\t\n--force-remove::\n\tRemove the file from the index even when the working directory\n\tstill has such a file.\n\n--::\n\tDo not interpret any more arguments as options.\n\n::\n\tFiles to act on.\n\tNote that files begining with '.' are discarded. This includes\n\t`./file` and `dir/./file`. If you don't want this, then use\t\n\tcleaner names.\n\tThe same applies to directories ending '/' and paths with '//'\n\nUsing --refresh\n---------------\n'--refresh' does not calculate a new sha1 file or bring the cache\nup-to-date for mode/content changes. But what it *does* do is to\n\"re-match\" the stat information of a file with the cache, so that you\ncan refresh the cache for a file that hasn't been changed but where\nthe stat entry is out of date.\n\nFor example, you'd want to do this after doing a \"git-read-tree\", to link\nup the stat cache details with the proper files.\n\nUsing --cacheinfo\n-----------------\n'--cacheinfo' is used to register a file that is not in the current\nworking directory. This is useful for minimum-checkout merging.\n\nTo pretend you have a file with mode and sha1 at path, say:\n\n $ git-update-cache --cacheinfo mode sha1 path\n\nTo update and refresh only the files already checked out:\n\n git-checkout-cache -n -f -a && git-update-cache --ignore-missing --refresh\n\n\nNAME\n----\ngit-write-blob - Creates a blob from a file\n\nSYNOPSIS\n--------\n'git-write-blob' \n\nDESCRIPTION\n-----------\nWrites the contents of the named file (which can be outside of the work\ntree) as a blob into the object database, and reports its object ID to its\nstandard output. This is used by \"git-merge-one-file-script\" to update the\ncache without modifying files in the work tree.\n\n\nNAME\n----\ngit-write-tree - Creates a tree from the current cache\n\nSYNOPSIS\n--------\n'git-write-tree'\n\nDESCRIPTION\n-----------\nCreates a tree object using the current cache.\n\nThe cache must be merged.\n\nConceptually, \"git-write-tree\" sync()s the current directory cache contents\ninto a set of tree files.\nIn order to have that match what is actually in your directory right\nnow, you need to have done a \"git-update-cache\" phase before you did the\n\"git-write-tree\".\n\n\n\n\n////////////////////////////////////////////////////////////////\n\nProducing man pages and html\n\nTo create a set of html pages run:\n perl split-docs.pl -html < core-git.txt\n\nTo create a set of man pages run:\n perl split-docs.pl -man < core-git.txt\n\n\n////////////////////////////////////////////////////////////////\n\n\n\nThe output format from \"git-diff-cache\", \"git-diff-tree\" and\n\"git-diff-files\" is very similar.\n\nThese commands all compare two sets of things; what are\ncompared are different:\n\ngit-diff-cache ::\n compares the and the files on the filesystem.\n\ngit-diff-cache --cached ::\n compares the and the cache.\n\ngit-diff-tree [-r] [...]::\n compares the trees named by the two arguments.\n\ngit-diff-files [...]::\n compares the cache and the files on the filesystem.\n\nThe following desription uses \"old\" and \"new\" to mean those\ncompared entities.\n\nFor files in old but not in new (i.e. removed):\n\n - \\t \\t \\t \n\nFor files not in old but in new (i.e. added):\n\n + \\t \\t \\t \n\nFor files that differ:\n\n *-> \\t \\t -> \\t \n\n is shown as all 0's if new is a file on the\nfilesystem and it is out of sync with the cache. Example:\n\n *100644->100644 blob 5be4a4.......->000000....... file.c\n\n\nGenerating patches with -p\n--------------------------\n\nWhen \"git-diff-cache\", \"git-diff-tree\", or \"git-diff-files\" are run\nwith a '-p' option, they do not produce the output described above\ninstead they produce a patch file.\n\nThe patch generation can be customized at two levels. This\ncustomization also applies to \"git-diff-tree-helper\".\n\n1. When the environment variable 'GIT_EXTERNAL_DIFF' is not set,\n these commands internally invoke \"diff\" like this:\n\n diff -L a/ -L a/ -pu \n\n For added files, `/dev/null` is used for . For removed\n files, `/dev/null` is used for \n\n The \"diff\" formatting options can be customized via the\n environment variable 'GIT_DIFF_OPTS'. For example, if you\n prefer context diff:\n\n\t GIT_DIFF_OPTS=-c git-diff-cache -p $(cat .git/HEAD)\n\n\n2. When the environment variable 'GIT_EXTERNAL_DIFF' is set, the\n program named by it is called, instead of the diff invocation\n described above.\n+\nFor a path that is added, removed, or modified,\n'GIT_EXTERNAL_DIFF' is called with 7 parameters:\n\n path old-file old-hex old-mode new-file new-hex new-mode\n+\nwhere:\n\n -file:: are files GIT_EXTERNAL_DIFF can use to read the\n\t\t contents of ,\n -hex:: are the 40-hexdigit SHA1 hashes,\n -mode:: are the octal representation of the file modes.\n\n+ \nThe file parameters can point at the user's working file\n(e.g. `new-file` in \"git-diff-files\"), `/dev/null` (e.g. `old-file`\nwhen a new file is added), or a temporary file (e.g. `old-file` in the\ncache). 'GIT_EXTERNAL_DIFF' should not worry about unlinking the\ntemporary file --- it is removed when 'GIT_EXTERNAL_DIFF' exits.\n\nFor a path that is unmerged, 'GIT_EXTERNAL_DIFF' is called with 1\nparameter, .\n"},{"id":"2785","messageId":"20050508173109.GZ9495@pasky.ji.cz","threadId":"534","inReplyTo":"427E4AED.9050702@dgreaves.com","subject":"Re: [FILES] core-git documentation update","fromName":"Petr Baudis","fromEmail":"pasky@ucw.cz","sentAt":"2005-05-08T17:31:09Z","receivedAt":"2005-05-08T17:31:09Z","isPatch":false,"sender":{"key":"pasky@ucw.cz","avatar":"https://avatars.githubusercontent.com/u/18439?v=4"},"body":"Dear diary, on Sun, May 08, 2005 at 07:22:53PM CEST, I got a letter\nwhere David Greaves told me that...\n> I've converted the core-git.txt to asciidoc format and created a trivial\n> splitter to create individual txt, html and man pages.\n\nIs there any reason to keep the source in a single huge monolithic file?\n\n-- \n\t\t\t\tPetr \"Pasky\" Baudis\nStuff: http://pasky.or.cz/\nC++: an octopus made by nailing extra legs onto a dog. -- Steve Taylor\n"},{"id":"2790","messageId":"427E4F6C.6090302@dgreaves.com","threadId":"534","inReplyTo":"20050508173109.GZ9495@pasky.ji.cz","subject":"Re: [FILES] core-git documentation update","fromName":"David Greaves","fromEmail":"david@dgreaves.com","sentAt":"2005-05-08T17:42:04Z","receivedAt":"2005-05-08T17:42:04Z","isPatch":false,"sender":{"key":"david@dgreaves.com","avatar":"https://gravatar.com/avatar/ca67bad50999edcdd137c9a65da2381557d175bea99ae956afdabc5785e42b79?d=mp&s=160"},"body":"Petr Baudis wrote:\n\n>Dear diary, on Sun, May 08, 2005 at 07:22:53PM CEST, I got a letter\n>where David Greaves told me that...\n> \n>\n>>I've converted the core-git.txt to asciidoc format and created a trivial\n>>splitter to create individual txt, html and man pages.\n>> \n>>\n>\n>Is there any reason to keep the source in a single huge monolithic file?\n> \n>\nit just makes across the board changes easier and at the minute the\nstuff I've been doing is systemic.\n\nI have no problems with breaking it up - hence the script...\n\nDavid\n\n-- \n\n"},{"id":"2803","messageId":"7vpsw15xdf.fsf@assigned-by-dhcp.cox.net","threadId":"534","inReplyTo":"427E4F6C.6090302@dgreaves.com","subject":"Re: [FILES] core-git documentation update","fromName":"Junio C Hamano","fromEmail":"junkio@cox.net","sentAt":"2005-05-08T19:30:20Z","receivedAt":"2005-05-08T19:30:20Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":">>>>> \"DG\" == David Greaves writes:\n\nDG> it just makes across the board changes easier and at the minute the\nDG> stuff I've been doing is systemic.\nDG> I have no problems with breaking it up - hence the script...\n\nMonolithic version is easier to work with when there is only one\nor very few people working on it but when the document matures\nenough to describe the current state of affairs accurately\nenough, further changes would come almost solely from changing\nthe programs the document describes. At that point having\nseparate files describing each program is easier to work with,\nand I think that point is now.\n\n\n"},{"id":"2830","messageId":"427E83D0.5040607@dgreaves.com","threadId":"534","inReplyTo":"7vpsw15xdf.fsf@assigned-by-dhcp.cox.net","subject":"[BUG] in asciidoc was Re: [FILES] core-git documentation update","fromName":"David Greaves","fromEmail":"david@dgreaves.com","sentAt":"2005-05-08T21:25:36Z","receivedAt":"2005-05-08T21:25:36Z","isPatch":false,"sender":{"key":"david@dgreaves.com","avatar":"https://gravatar.com/avatar/ca67bad50999edcdd137c9a65da2381557d175bea99ae956afdabc5785e42b79?d=mp&s=160"},"body":"Junio C Hamano wrote:\n\n>>>>>>\"DG\" == David Greaves writes:\n>>>>>> \n>>>>>>\n>\n>DG> it just makes across the board changes easier and at the minute the\n>DG> stuff I've been doing is systemic.\n>DG> I have no problems with breaking it up - hence the script...\n>\n>Monolithic version is easier to work with when there is only one\n>or very few people working on it but when the document matures\n>enough to describe the current state of affairs accurately\n>enough, further changes would come almost solely from changing\n>the programs the document describes. At that point having\n>separate files describing each program is easier to work with,\n>and I think that point is now.\n> \n>\nI was waiting for comments on this set in case there were comments like:\nevery document should have 'x' or change all 'y' to 'z'\nI fully intend to split it out...\n\nI will send patches next time.\n\nOne thing I failed to mention.\nThere's a minor bug in asciidoc for which I've submitted a patch to the\nauthor. IIRC the bug causes problems with the -man option and is\ncosmetically wrong with the html.\n\n>From the asciidoc docs:\nThe first manpage section is mandatory and must be called /NAME/ and\ncontain a single paragraph (usually a single line) consisting of a list\nof one or more comma separated command name(s) separated from the\ncommand purpose by a dash character. **The dash must have at least one\nwhite space character on either side.**\n\nHowever this is not enforced (or indeed possible) at the moment - the\nNAME section seems to split on the first hyphen.\n\nThis patch fixes that for me.\n\n--- /usr/bin/asciidoc.orig 2005-05-08 17:03:42.666249974 +0100\n+++ /usr/bin/asciidoc 2005-05-08 16:56:00.518923960 +0100\n@@ -1067,7 +1067,7 @@\n error('malformed NAME section body')\n lines = reader.read_until(r'^$')\n s = string.join(lines)\n- mo = re.match(r'^(?P.*?)-(?P.*)$',s)\n+ mo =\nre.match(r'^(?P.*?)\\s+-\\s+(?P.*)$',s)\n if not mo:\n error('malformed NAME section body')\n attrs['manname'] = string.strip(mo.group('manname'))\n\n\n"}]}