{"thread":{"id":"6413","subject":"[PATCH] sanitize content of README file","startedAt":"2007-01-17T18:04:39Z","lastAt":"2007-01-17T19:39:55Z","messageCount":2,"participants":["Nicolas Pitre","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"31903","messageId":"Pine.LNX.4.64.0701171255150.2577@xanadu.home","threadId":"6413","inReplyTo":null,"subject":"[PATCH] sanitize content of README file","fromName":"Nicolas Pitre","fromEmail":"nico@cam.org","sentAt":"2007-01-17T18:04:39Z","receivedAt":"2007-01-17T18:04:39Z","isPatch":true,"sender":{"key":"nico@fluxnic.net","avatar":"https://avatars.githubusercontent.com/u/702790?v=4"},"body":"Current README content is way too esoteric for someone looking at GIT \nfor the first time. Instead it should provide a quick summary of what \nGIT is with a few pointers to other resources.\n\nThe bulk of the previous README content is moved to \nDocumentation/core-intro.txt.\n\nSigned-of-by: Nicolas Pitre \n---\ndiff --git a/README b/Documentation/core-intro.txt\nsimilarity index 99%\ncopy from README\ncopy to Documentation/core-intro.txt\nindex cee7e43..2bad1a7 100644\n--- a/README\n+++ b/Documentation/core-intro.txt\n@@ -3,6 +3,7 @@\n \tGIT - the stupid content tracker\n \n ////////////////////////////////////////////////////////////////\n+\n \"git\" can mean anything, depending on your mood.\n \n - random three-letter combination that is pronounceable, and not\n@@ -14,9 +15,9 @@\n works for you. Angels sing, and a light suddenly fills the room. \n - \"goddamn idiotic truckload of sh*t\": when it breaks\n \n-This is a stupid (but extremely fast) directory content manager. It\n-doesn't do a whole lot, but what it 'does' do is track directory\n-contents efficiently. \n+This is a (not so) stupid but extremely fast directory content manager.\n+It doesn't do a whole lot at its core, but what it 'does' do is track \n+directory contents efficiently. \n \n There are two object abstractions: the \"object database\", and the\n \"current directory cache\" aka \"index\".\ndiff --git a/README b/README\nindex cee7e43..a49b182 100644\n--- a/README\n+++ b/README\n@@ -3,6 +3,7 @@\n \tGIT - the stupid content tracker\n \n ////////////////////////////////////////////////////////////////\n+\n \"git\" can mean anything, depending on your mood.\n \n - random three-letter combination that is pronounceable, and not\n@@ -14,576 +15,26 @@\n works for you. Angels sing, and a light suddenly fills the room. \n - \"goddamn idiotic truckload of sh*t\": when it breaks\n \n-This is a stupid (but extremely fast) directory content manager. It\n-doesn't do a whole lot, but what it 'does' do is track directory\n-contents efficiently. \n-\n-There are two object abstractions: the \"object database\", and the\n-\"current directory cache\" aka \"index\".\n-\n-The Object Database\n-~~~~~~~~~~~~~~~~~~~\n-The object database is literally just a content-addressable collection\n-of objects. All objects are named by their content, which is\n-approximated by the SHA1 hash of the object itself. Objects may refer\n-to other objects (by referencing their SHA1 hash), and so you can\n-build up a hierarchy of objects.\n-\n-All objects have a statically determined \"type\" aka \"tag\", which is\n-determined at object creation time, and which identifies the format of\n-the object (i.e. how it is used, and how it can refer to other\n-objects). There are currently four different object types: \"blob\",\n-\"tree\", \"commit\" and \"tag\".\n-\n-A \"blob\" object cannot refer to any other object, and is, like the type\n-implies, a pure storage object containing some user data. It is used to\n-actually store the file data, i.e. a blob object is associated with some\n-particular version of some file. \n-\n-A \"tree\" object is an object that ties one or more \"blob\" objects into a\n-directory structure. In addition, a tree object can refer to other tree\n-objects, thus creating a directory hierarchy. \n-\n-A \"commit\" object ties such directory hierarchies together into\n-a DAG of revisions - each \"commit\" is associated with exactly one tree\n-(the directory hierarchy at the time of the commit). In addition, a\n-\"commit\" refers to one or more \"parent\" commit objects that describe the\n-history of how we arrived at that directory hierarchy.\n-\n-As a special case, a commit object with no parents is called the \"root\"\n-object, and is the point of an initial project commit. Each project\n-must have at least one root, and while you can tie several different\n-root objects together into one project by creating a commit object which\n-has two or more separate roots as its ultimate parents, that's probably\n-just going to confuse people. So aim for the notion of \"one root object\n-per project\", even if git itself does not enforce that. \n-\n-A \"tag\" object symbolically identifies and can be used to sign other\n-objects. It contains the identifier and type of another object, a\n-symbolic name (of course!) and, optionally, a signature.\n-\n-Regardless of object type, all objects share the following\n-characteristics: they are all deflated with zlib, and have a header\n-that not only specifies their type, but also provides size information\n-about the data in the object. It's worth noting that the SHA1 hash\n-that is used to name the object is the hash of the original data\n-plus this header, so `sha1sum` 'file' does not match the object name\n-for 'file'.\n-(Historical note: in the dawn of the age of git the hash\n-was the sha1 of the 'compressed' object.)\n-\n-As a result, the general consistency of an object can always be tested\n-independently of the contents or the type of the object: all objects can\n-be validated by verifying that (a) their hashes match the content of the\n-file and (b) the object successfully inflates to a stream of bytes that\n-forms a sequence of + + + + . \n-\n-The structured objects can further have their structure and\n-connectivity to other objects verified. This is generally done with\n-the `git-fsck-objects` program, which generates a full dependency graph\n-of all objects, and verifies their internal consistency (in addition\n-to just verifying their superficial consistency through the hash).\n-\n-The object types in some more detail:\n-\n-Blob Object\n-~~~~~~~~~~~\n-A \"blob\" object is nothing but a binary blob of data, and doesn't\n-refer to anything else. There is no signature or any other\n-verification of the data, so while the object is consistent (it 'is'\n-indexed by its sha1 hash, so the data itself is certainly correct), it\n-has absolutely no other attributes. No name associations, no\n-permissions. It is purely a blob of data (i.e. normally \"file\n-contents\").\n-\n-In particular, since the blob is entirely defined by its data, if two\n-files in a directory tree (or in multiple different versions of the\n-repository) have the same contents, they will share the same blob\n-object. The object is totally independent of its location in the\n-directory tree, and renaming a file does not change the object that\n-file is associated with in any way.\n-\n-A blob is typically created when gitlink:git-update-index[1]\n-is run, and its data can be accessed by gitlink:git-cat-file[1].\n-\n-Tree Object\n-~~~~~~~~~~~\n-The next hierarchical object type is the \"tree\" object. A tree object\n-is a list of mode/name/blob data, sorted by name. Alternatively, the\n-mode data may specify a directory mode, in which case instead of\n-naming a blob, that name is associated with another TREE object.\n-\n-Like the \"blob\" object, a tree object is uniquely determined by the\n-set contents, and so two separate but identical trees will always\n-share the exact same object. This is true at all levels, i.e. it's\n-true for a \"leaf\" tree (which does not refer to any other trees, only\n-blobs) as well as for a whole subdirectory.\n-\n-For that reason a \"tree\" object is just a pure data abstraction: it\n-has no history, no signatures, no verification of validity, except\n-that since the contents are again protected by the hash itself, we can\n-trust that the tree is immutable and its contents never change.\n-\n-So you can trust the contents of a tree to be valid, the same way you\n-can trust the contents of a blob, but you don't know where those\n-contents 'came' from.\n-\n-Side note on trees: since a \"tree\" object is a sorted list of\n-\"filename+content\", you can create a diff between two trees without\n-actually having to unpack two trees. Just ignore all common parts,\n-and your diff will look right. In other words, you can effectively\n-(and efficiently) tell the difference between any two random trees by\n-O(n) where \"n\" is the size of the difference, rather than the size of\n-the tree.\n-\n-Side note 2 on trees: since the name of a \"blob\" depends entirely and\n-exclusively on its contents (i.e. there are no names or permissions\n-involved), you can see trivial renames or permission changes by\n-noticing that the blob stayed the same. However, renames with data\n-changes need a smarter \"diff\" implementation.\n-\n-A tree is created with gitlink:git-write-tree[1] and\n-its data can be accessed by gitlink:git-ls-tree[1].\n-Two trees can be compared with gitlink:git-diff-tree[1].\n-\n-Commit Object\n-~~~~~~~~~~~~~\n-The \"commit\" object is an object that introduces the notion of\n-history into the picture. In contrast to the other objects, it\n-doesn't just describe the physical state of a tree, it describes how\n-we got there, and why.\n-\n-A \"commit\" is defined by the tree-object that it results in, the\n-parent commits (zero, one or more) that led up to that point, and a\n-comment on what happened. Again, a commit is not trusted per se:\n-the contents are well-defined and \"safe\" due to the cryptographically\n-strong signatures at all levels, but there is no reason to believe\n-that the tree is \"good\" or that the merge information makes sense.\n-The parents do not have to actually have any relationship with the\n-result, for example.\n-\n-Note on commits: unlike real SCM's, commits do not contain\n-rename information or file mode change information. All of that is\n-implicit in the trees involved (the result tree, and the result trees\n-of the parents), and describing that makes no sense in this idiotic\n-file manager.\n-\n-A commit is created with gitlink:git-commit-tree[1] and\n-its data can be accessed by gitlink:git-cat-file[1].\n-\n-Trust\n-~~~~~\n-An aside on the notion of \"trust\". Trust is really outside the scope\n-of \"git\", but it's worth noting a few things. First off, since\n-everything is hashed with SHA1, you 'can' trust that an object is\n-intact and has not been messed with by external sources. So the name\n-of an object uniquely identifies a known state - just not a state that\n-you may want to trust.\n-\n-Furthermore, since the SHA1 signature of a commit refers to the\n-SHA1 signatures of the tree it is associated with and the signatures\n-of the parent, a single named commit specifies uniquely a whole set\n-of history, with full contents. You can't later fake any step of the\n-way once you have the name of a commit.\n-\n-So to introduce some real trust in the system, the only thing you need\n-to do is to digitally sign just 'one' special note, which includes the\n-name of a top-level commit. Your digital signature shows others\n-that you trust that commit, and the immutability of the history of\n-commits tells others that they can trust the whole history.\n-\n-In other words, you can easily validate a whole archive by just\n-sending out a single email that tells the people the name (SHA1 hash)\n-of the top commit, and digitally sign that email using something\n-like GPG/PGP.\n-\n-To assist in this, git also provides the tag object...\n-\n-Tag Object\n-~~~~~~~~~~\n-Git provides the \"tag\" object to simplify creating, managing and\n-exchanging symbolic and signed tokens. The \"tag\" object at its\n-simplest simply symbolically identifies another object by containing\n-the sha1, type and symbolic name.\n-\n-However it can optionally contain additional signature information\n-(which git doesn't care about as long as there's less than 8k of\n-it). This can then be verified externally to git.\n-\n-Note that despite the tag features, \"git\" itself only handles content\n-integrity; the trust framework (and signature provision and\n-verification) has to come from outside.\n-\n-A tag is created with gitlink:git-mktag[1],\n-its data can be accessed by gitlink:git-cat-file[1],\n-and the signature can be verified by\n-gitlink:git-verify-tag[1].\n-\n-\n-The \"index\" aka \"Current Directory Cache\"\n------------------------------------------\n-The index is a simple binary file, which contains an efficient\n-representation of a virtual directory content at some random time. It\n-does so by a simple array that associates a set of names, dates,\n-permissions and content (aka \"blob\") objects together. The cache is\n-always kept ordered by name, and names are unique (with a few very\n-specific rules) at any point in time, but the cache has no long-term\n-meaning, and can be partially updated at any time.\n-\n-In particular, the index certainly does not need to be consistent with\n-the current directory contents (in fact, most operations will depend on\n-different ways to make the index 'not' be consistent with the directory\n-hierarchy), but it has three very important attributes:\n-\n-'(a) it can re-generate the full state it caches (not just the\n-directory structure: it contains pointers to the \"blob\" objects so\n-that it can regenerate the data too)'\n-\n-As a special case, there is a clear and unambiguous one-way mapping\n-from a current directory cache to a \"tree object\", which can be\n-efficiently created from just the current directory cache without\n-actually looking at any other data. So a directory cache at any one\n-time uniquely specifies one and only one \"tree\" object (but has\n-additional data to make it easy to match up that tree object with what\n-has happened in the directory)\n-\n-'(b) it has efficient methods for finding inconsistencies between that\n-cached state (\"tree object waiting to be instantiated\") and the\n-current state.'\n-\n-'(c) it can additionally efficiently represent information about merge\n-conflicts between different tree objects, allowing each pathname to be\n-associated with sufficient information about the trees involved that\n-you can create a three-way merge between them.'\n-\n-Those are the three ONLY things that the directory cache does. It's a\n-cache, and the normal operation is to re-generate it completely from a\n-known tree object, or update/compare it with a live tree that is being\n-developed. If you blow the directory cache away entirely, you generally\n-haven't lost any information as long as you have the name of the tree\n-that it described. \n-\n-At the same time, the index is at the same time also the\n-staging area for creating new trees, and creating a new tree always\n-involves a controlled modification of the index file. In particular,\n-the index file can have the representation of an intermediate tree that\n-has not yet been instantiated. So the index can be thought of as a\n-write-back cache, which can contain dirty information that has not yet\n-been written back to the backing store.\n-\n-\n-\n-The Workflow\n-------------\n-Generally, all \"git\" operations work on the index file. Some operations\n-work *purely* on the index file (showing the current state of the\n-index), but most operations move data to and from the index file. Either\n-from the database or from the working directory. Thus there are four\n-main combinations: \n-\n-1) working directory -> index\n-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n-\n-You update the index with information from the working directory with\n-the gitlink:git-update-index[1] command. You\n-generally update the index information by just specifying the filename\n-you want to update, like so:\n-\n-\tgit-update-index filename\n-\n-but to avoid common mistakes with filename globbing etc, the command\n-will not normally add totally new entries or remove old entries,\n-i.e. it will normally just update existing cache entries.\n-\n-To tell git that yes, you really do realize that certain files no\n-longer exist, or that new files should be added, you\n-should use the `--remove` and `--add` flags respectively.\n-\n-NOTE! A `--remove` flag does 'not' mean that subsequent filenames will\n-necessarily be removed: if the files still exist in your directory\n-structure, the index will be updated with their new status, not\n-removed. The only thing `--remove` means is that update-cache will be\n-considering a removed file to be a valid thing, and if the file really\n-does not exist any more, it will update the index accordingly.\n-\n-As a special case, you can also do `git-update-index --refresh`, which\n-will refresh the \"stat\" information of each index to match the current\n-stat information. It will 'not' update the object status itself, and\n-it will only update the fields that are used to quickly test whether\n-an object still matches its old backing store object.\n-\n-2) index -> object database\n-~~~~~~~~~~~~~~~~~~~~~~~~~~~\n-\n-You write your current index file to a \"tree\" object with the program\n-\n-\tgit-write-tree\n-\n-that doesn't come with any options - it will just write out the\n-current index into the set of tree objects that describe that state,\n-and it will return the name of the resulting top-level tree. You can\n-use that tree to re-generate the index at any time by going in the\n-other direction:\n-\n-3) object database -> index\n-~~~~~~~~~~~~~~~~~~~~~~~~~~~\n-\n-You read a \"tree\" file from the object database, and use that to\n-populate (and overwrite - don't do this if your index contains any\n-unsaved state that you might want to restore later!) your current\n-index. Normal operation is just\n-\n-\t\tgit-read-tree \n-\n-and your index file will now be equivalent to the tree that you saved\n-earlier. However, that is only your 'index' file: your working\n-directory contents have not been modified.\n-\n-4) index -> working directory\n-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n-\n-You update your working directory from the index by \"checking out\"\n-files. This is not a very common operation, since normally you'd just\n-keep your files updated, and rather than write to your working\n-directory, you'd tell the index files about the changes in your\n-working directory (i.e. `git-update-index`).\n-\n-However, if you decide to jump to a new version, or check out somebody\n-else's version, or just restore a previous tree, you'd populate your\n-index file with read-tree, and then you need to check out the result\n-with\n-\n-\t\tgit-checkout-index filename\n-\n-or, if you want to check out all of the index, use `-a`.\n-\n-NOTE! git-checkout-index normally refuses to overwrite old files, so\n-if you have an old version of the tree already checked out, you will\n-need to use the \"-f\" flag ('before' the \"-a\" flag or the filename) to\n-'force' the checkout.\n-\n-\n-Finally, there are a few odds and ends which are not purely moving\n-from one representation to the other:\n-\n-5) Tying it all together\n-~~~~~~~~~~~~~~~~~~~~~~~~\n-To commit a tree you have instantiated with \"git-write-tree\", you'd\n-create a \"commit\" object that refers to that tree and the history\n-behind it - most notably the \"parent\" commits that preceded it in\n-history.\n-\n-Normally a \"commit\" has one parent: the previous state of the tree\n-before a certain change was made. However, sometimes it can have two\n-or more parent commits, in which case we call it a \"merge\", due to the\n-fact that such a commit brings together (\"merges\") two or more\n-previous states represented by other commits.\n-\n-In other words, while a \"tree\" represents a particular directory state\n-of a working directory, a \"commit\" represents that state in \"time\",\n-and explains how we got there.\n-\n-You create a commit object by giving it the tree that describes the\n-state at the time of the commit, and a list of parents:\n-\n-\tgit-commit-tree -p [-p ..]\n-\n-and then giving the reason for the commit on stdin (either through\n-redirection from a pipe or file, or by just typing it at the tty).\n-\n-git-commit-tree will return the name of the object that represents\n-that commit, and you should save it away for later use. Normally,\n-you'd commit a new `HEAD` state, and while git doesn't care where you\n-save the note about that state, in practice we tend to just write the\n-result to the file pointed at by `.git/HEAD`, so that we can always see\n-what the last committed state was.\n-\n-Here is an ASCII art by Jon Loeliger that illustrates how\n-various pieces fit together.\n-\n-------------\n-\n- commit-tree\n- commit obj\n- +----+\n- | |\n- | |\n- V V\n- +-----------+\n- | Object DB |\n- | Backing |\n- | Store |\n- +-----------+\n- ^\n- write-tree | |\n- tree obj | |\n- | | read-tree\n- | | tree obj\n- V\n- +-----------+\n- | Index |\n- | \"cache\" |\n- +-----------+\n- update-index ^\n- blob obj | |\n- | |\n- checkout-index -u | | checkout-index\n- stat | | blob obj\n- V\n- +-----------+\n- | Working |\n- | Directory |\n- +-----------+\n-\n-------------\n-\n-\n-6) Examining the data\n-~~~~~~~~~~~~~~~~~~~~~\n-\n-You can examine the data represented in the object database and the\n-index with various helper tools. For every object, you can use\n-gitlink:git-cat-file[1] to examine details about the\n-object:\n-\n-\t\tgit-cat-file -t \n-\n-shows the type of the object, and once you have the type (which is\n-usually implicit in where you find the object), you can use\n-\n-\t\tgit-cat-file blob|tree|commit|tag \n-\n-to show its contents. NOTE! Trees have binary content, and as a result\n-there is a special helper for showing that content, called\n-`git-ls-tree`, which turns the binary content into a more easily\n-readable form.\n-\n-It's especially instructive to look at \"commit\" objects, since those\n-tend to be small and fairly self-explanatory. In particular, if you\n-follow the convention of having the top commit name in `.git/HEAD`,\n-you can do\n-\n-\t\tgit-cat-file commit HEAD\n-\n-to see what the top commit was.\n-\n-7) Merging multiple trees\n-~~~~~~~~~~~~~~~~~~~~~~~~~\n-\n-Git helps you do a three-way merge, which you can expand to n-way by\n-repeating the merge procedure arbitrary times until you finally\n-\"commit\" the state. The normal situation is that you'd only do one\n-three-way merge (two parents), and commit it, but if you like to, you\n-can do multiple parents in one go.\n-\n-To do a three-way merge, you need the two sets of \"commit\" objects\n-that you want to merge, use those to find the closest common parent (a\n-third \"commit\" object), and then use those commit objects to find the\n-state of the directory (\"tree\" object) at these points.\n-\n-To get the \"base\" for the merge, you first look up the common parent\n-of two commits with\n-\n-\t\tgit-merge-base \n-\n-which will return you the commit they are both based on. You should\n-now look up the \"tree\" objects of those commits, which you can easily\n-do with (for example)\n-\n-\t\tgit-cat-file commit | head -1\n-\n-since the tree object information is always the first line in a commit\n-object.\n-\n-Once you know the three trees you are going to merge (the one\n-\"original\" tree, aka the common case, and the two \"result\" trees, aka\n-the branches you want to merge), you do a \"merge\" read into the\n-index. This will complain if it has to throw away your old index contents, so you should\n-make sure that you've committed those - in fact you would normally\n-always do a merge against your last commit (which should thus match\n-what you have in your current index anyway).\n-\n-To do the merge, do\n-\n-\t\tgit-read-tree -m -u \n-\n-which will do all trivial merge operations for you directly in the\n-index file, and you can just write the result out with\n-`git-write-tree`.\n-\n-Historical note. We did not have `-u` facility when this\n-section was first written, so we used to warn that\n-the merge is done in the index file, not in your\n-working tree, and your working tree will not match your\n-index after this step.\n-This is no longer true. The above command, thanks to `-u`\n-option, updates your working tree with the merge results for\n-paths that have been trivially merged.\n-\n-\n-8) Merging multiple trees, continued\n-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n-\n-Sadly, many merges aren't trivial. If there are files that have\n-been added.moved or removed, or if both branches have modified the\n-same file, you will be left with an index tree that contains \"merge\n-entries\" in it. Such an index tree can 'NOT' be written out to a tree\n-object, and you will have to resolve any such merge clashes using\n-other tools before you can write out the result.\n-\n-You can examine such index state with `git-ls-files --unmerged`\n-command. An example:\n-\n-------------------------------------------------\n-$ git-read-tree -m $orig HEAD $target\n-$ git-ls-files --unmerged\n-100644 263414f423d0e4d70dae8fe53fa34614ff3e2860 1\thello.c\n-100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 2\thello.c\n-100644 cc44c73eb783565da5831b4d820c962954019b69 3\thello.c\n-------------------------------------------------\n-\n-Each line of the `git-ls-files --unmerged` output begins with\n-the blob mode bits, blob SHA1, 'stage number', and the\n-filename. The 'stage number' is git's way to say which tree it\n-came from: stage 1 corresponds to `$orig` tree, stage 2 `HEAD`\n-tree, and stage3 `$target` tree.\n-\n-Earlier we said that trivial merges are done inside\n-`git-read-tree -m`. For example, if the file did not change\n-from `$orig` to `HEAD` nor `$target`, or if the file changed\n-from `$orig` to `HEAD` and `$orig` to `$target` the same way,\n-obviously the final outcome is what is in `HEAD`. What the\n-above example shows is that file `hello.c` was changed from\n-`$orig` to `HEAD` and `$orig` to `$target` in a different way.\n-You could resolve this by running your favorite 3-way merge\n-program, e.g. `diff3` or `merge`, on the blob objects from\n-these three stages yourself, like this:\n-\n-------------------------------------------------\n-$ git-cat-file blob 263414f... >hello.c~1\n-$ git-cat-file blob 06fa6a2... >hello.c~2\n-$ git-cat-file blob cc44c73... >hello.c~3\n-$ merge hello.c~2 hello.c~1 hello.c~3\n-------------------------------------------------\n-\n-This would leave the merge result in `hello.c~2` file, along\n-with conflict markers if there are conflicts. After verifying\n-the merge result makes sense, you can tell git what the final\n-merge result for this file is by:\n-\n-\tmv -f hello.c~2 hello.c\n-\tgit-update-index hello.c\n-\n-When a path is in unmerged state, running `git-update-index` for\n-that path tells git to mark the path resolved.\n-\n-The above is the description of a git merge at the lowest level,\n-to help you understand what conceptually happens under the hood.\n-In practice, nobody, not even git itself, uses three `git-cat-file`\n-for this. There is `git-merge-index` program that extracts the\n-stages to temporary files and calls a \"merge\" script on it:\n-\n-\tgit-merge-index git-merge-one-file hello.c\n-\n-and that is what higher level `git resolve` is implemented with.\n+Git is a fast, scalable, distributed revision control system with an\n+unusually rich command set that provides both high-level operations\n+and full access to internals.\n+\n+Git is an Open Source project covered by the GNU General Public License.\n+It was originally written by Linus Torvalds with help of a group of\n+hackers around the net. It is currently maintained by Junio C Hamano.\n+\n+Please read the file INSTALL for installation instructions.\n+See Documentation/tutorial.txt to get started, then see\n+Documentation/everyday.txt for a useful minimum set of commands,\n+and \"man git-commandname\" for documentation of each command.\n+CVS users may also want to read Documentation/cvs-migration.txt.\n+\n+Many Git online resources are accessible from http://git.or.cz/\n+including full documentation and Git related tools.\n+\n+The user discussion and development of Git take place on the Git\n+mailing list -- everyone is welcome to post bug reports, feature\n+requests, comments and patches to git@vger.kernel.org. To subscribe\n+to the list, send an email with just \"subscribe git\" in the body to\n+majordomo@vger.kernel.org. The mailing list archives are available at\n+http://marc.theaimsgroup.com/?l=git and other archival sites.\n"},{"id":"31913","messageId":"7vtzypqw6s.fsf@assigned-by-dhcp.cox.net","threadId":"6413","inReplyTo":"Pine.LNX.4.64.0701171255150.2577@xanadu.home","subject":"Re: [PATCH] sanitize content of README file","fromName":"Junio C Hamano","fromEmail":"junkio@cox.net","sentAt":"2007-01-17T19:39:55Z","receivedAt":"2007-01-17T19:39:55Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"I do not think it is a bad idea to make the top-level README\nconcise and sweet, but this has fallout in Documentation/git.txt\nwhich includes README and makes it into the Discussion section.\n\nThe attached patch on top of yours would resurrect it.\n\n---\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 93c7024..9f2d242 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -71,14 +71,11 @@ doc.dep : $(wildcard *.txt) build-docdep.perl\n \n -include doc.dep\n \n-git.7: README\n-\n-README: ../README\n-\tcp $< $@\n+git.7 git.html: git.txt core-intro.txt\n \n \n clean:\n-\trm -f *.xml *.html *.1 *.7 howto-index.txt howto/*.html doc.dep README\n+\trm -f *.xml *.html *.1 *.7 howto-index.txt howto/*.html doc.dep\n \n %.html : %.txt\n \tasciidoc -b xhtml11 -d manpage -f asciidoc.conf $<\n@@ -89,8 +86,6 @@ clean:\n %.xml : %.txt\n \tasciidoc -b docbook -d manpage -f asciidoc.conf $<\n \n-git.html: git.txt README\n-\n glossary.html : glossary.txt sort_glossary.pl\n \tcat $< | \\\n \tperl sort_glossary.pl | \\\ndiff --git a/Documentation/git.txt b/Documentation/git.txt\nindex 6a82803..a0bcef7 100644\n--- a/Documentation/git.txt\n+++ b/Documentation/git.txt\n@@ -699,7 +699,7 @@ other\n \n Discussion[[Discussion]]\n ------------------------\n-include::README[]\n+include::core-intro.txt[]\n \n Authors\n -------\n"}]}