From 30eba7bf2caa327b4251d66bf7157dda97512e96 Mon Sep 17 00:00:00 2001 From: Christian Couder Date: Fri, 6 Jun 2008 09:07:28 +0200 Subject: documentation: convert "diffcore" and "repository-layout" to man pages This patch renames the following documents and at the same time converts them to the man format: diffcore.txt -> gitdiffcore.txt (man section 7) repository-layout.txt -> gitrepository-layout.txt (man section 5) Other documents that reference the above ones are changed accordingly. Signed-off-by: Christian Couder Signed-off-by: Junio C Hamano diff --git a/Documentation/Makefile b/Documentation/Makefile index ca4dadf..5bd0e7c 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -2,9 +2,11 @@ MAN1_TXT= \ $(filter-out $(addsuffix .txt, $(ARTICLES) $(SP_ARTICLES)), \ $(wildcard git-*.txt)) \ gitk.txt -MAN5_TXT=gitattributes.txt gitignore.txt gitmodules.txt githooks.txt +MAN5_TXT=gitattributes.txt gitignore.txt gitmodules.txt githooks.txt \ + gitrepository-layout.txt MAN7_TXT=git.txt gitcli.txt gittutorial.txt gittutorial-2.txt \ - gitcvs-migration.txt gitcore-tutorial.txt gitglossary.txt + gitcvs-migration.txt gitcore-tutorial.txt gitglossary.txt \ + gitdiffcore.txt MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT) MAN_XML=$(patsubst %.txt,%.xml,$(MAN_TXT)) @@ -12,9 +14,7 @@ MAN_HTML=$(patsubst %.txt,%.html,$(MAN_TXT)) DOC_HTML=$(MAN_HTML) -ARTICLES = diffcore -ARTICLES += howto-index -ARTICLES += repository-layout +ARTICLES = howto-index ARTICLES += everyday ARTICLES += git-tools # with their own formatting rules. diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index 859d679..5721548 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -241,4 +241,4 @@ endif::git-format-patch[] Do not show any source or destination prefix. For more detailed explanation on these common options, see also -link:diffcore.html[diffcore documentation]. +linkgit:gitdiffcore[7][diffcore documentation]. diff --git a/Documentation/diffcore.txt b/Documentation/diffcore.txt deleted file mode 100644 index c6a983a..0000000 --- a/Documentation/diffcore.txt +++ /dev/null @@ -1,271 +0,0 @@ -Tweaking diff output -==================== -June 2005 - - -Introduction ------------- - -The diff commands git-diff-index, git-diff-files, and git-diff-tree -can be told to manipulate differences they find in -unconventional ways before showing diff(1) output. The manipulation -is collectively called "diffcore transformation". This short note -describes what they are and how to use them to produce diff outputs -that are easier to understand than the conventional kind. - - -The chain of operation ----------------------- - -The git-diff-* family works by first comparing two sets of -files: - - - git-diff-index compares contents of a "tree" object and the - working directory (when '\--cached' flag is not used) or a - "tree" object and the index file (when '\--cached' flag is - used); - - - git-diff-files compares contents of the index file and the - working directory; - - - git-diff-tree compares contents of two "tree" objects; - -In all of these cases, the commands themselves compare -corresponding paths in the two sets of files. The result of -comparison is passed from these commands to what is internally -called "diffcore", in a format similar to what is output when -the -p option is not used. E.g. - ------------------------------------------------- -in-place edit :100644 100644 bcd1234... 0123456... M file0 -create :000000 100644 0000000... 1234567... A file4 -delete :100644 000000 1234567... 0000000... D file5 -unmerged :000000 000000 0000000... 0000000... U file6 ------------------------------------------------- - -The diffcore mechanism is fed a list of such comparison results -(each of which is called "filepair", although at this point each -of them talks about a single file), and transforms such a list -into another list. There are currently 6 such transformations: - -- diffcore-pathspec -- diffcore-break -- diffcore-rename -- diffcore-merge-broken -- diffcore-pickaxe -- diffcore-order - -These are applied in sequence. The set of filepairs git-diff-\* -commands find are used as the input to diffcore-pathspec, and -the output from diffcore-pathspec is used as the input to the -next transformation. The final result is then passed to the -output routine and generates either diff-raw format (see Output -format sections of the manual for git-diff-\* commands) or -diff-patch format. - - -diffcore-pathspec: For Ignoring Files Outside Our Consideration ---------------------------------------------------------------- - -The first transformation in the chain is diffcore-pathspec, and -is controlled by giving the pathname parameters to the -git-diff-* commands on the command line. The pathspec is used -to limit the world diff operates in. It removes the filepairs -outside the specified set of pathnames. E.g. If the input set -of filepairs included: - ------------------------------------------------- -:100644 100644 bcd1234... 0123456... M junkfile ------------------------------------------------- - -but the command invocation was "git-diff-files myfile", then the -junkfile entry would be removed from the list because only "myfile" -is under consideration. - -Implementation note. For performance reasons, git-diff-tree -uses the pathname parameters on the command line to cull set of -filepairs it feeds the diffcore mechanism itself, and does not -use diffcore-pathspec, but the end result is the same. - - -diffcore-break: For Splitting Up "Complete Rewrites" ----------------------------------------------------- - -The second transformation in the chain is diffcore-break, and is -controlled by the -B option to the git-diff-* commands. This is -used to detect a filepair that represents "complete rewrite" and -break such filepair into two filepairs that represent delete and -create. E.g. If the input contained this filepair: - ------------------------------------------------- -:100644 100644 bcd1234... 0123456... M file0 ------------------------------------------------- - -and if it detects that the file "file0" is completely rewritten, -it changes it to: - ------------------------------------------------- -:100644 000000 bcd1234... 0000000... D file0 -:000000 100644 0000000... 0123456... A file0 ------------------------------------------------- - -For the purpose of breaking a filepair, diffcore-break examines -the extent of changes between the contents of the files before -and after modification (i.e. the contents that have "bcd1234..." -and "0123456..." as their SHA1 content ID, in the above -example). The amount of deletion of original contents and -insertion of new material are added together, and if it exceeds -the "break score", the filepair is broken into two. The break -score defaults to 50% of the size of the smaller of the original -and the result (i.e. if the edit shrinks the file, the size of -the result is used; if the edit lengthens the file, the size of -the original is used), and can be customized by giving a number -after "-B" option (e.g. "-B75" to tell it to use 75%). - - -diffcore-rename: For Detection Renames and Copies -------------------------------------------------- - -This transformation is used to detect renames and copies, and is -controlled by the -M option (to detect renames) and the -C option -(to detect copies as well) to the git-diff-* commands. If the -input contained these filepairs: - ------------------------------------------------- -:100644 000000 0123456... 0000000... D fileX -:000000 100644 0000000... 0123456... A file0 ------------------------------------------------- - -and the contents of the deleted file fileX is similar enough to -the contents of the created file file0, then rename detection -merges these filepairs and creates: - ------------------------------------------------- -:100644 100644 0123456... 0123456... R100 fileX file0 ------------------------------------------------- - -When the "-C" option is used, the original contents of modified files, -and deleted files (and also unmodified files, if the -"\--find-copies-harder" option is used) are considered as candidates -of the source files in rename/copy operation. If the input were like -these filepairs, that talk about a modified file fileY and a newly -created file file0: - ------------------------------------------------- -:100644 100644 0123456... 1234567... M fileY -:000000 100644 0000000... bcd3456... A file0 ------------------------------------------------- - -the original contents of fileY and the resulting contents of -file0 are compared, and if they are similar enough, they are -changed to: - ------------------------------------------------- -:100644 100644 0123456... 1234567... M fileY -:100644 100644 0123456... bcd3456... C100 fileY file0 ------------------------------------------------- - -In both rename and copy detection, the same "extent of changes" -algorithm used in diffcore-break is used to determine if two -files are "similar enough", and can be customized to use -a similarity score different from the default of 50% by giving a -number after the "-M" or "-C" option (e.g. "-M8" to tell it to use -8/10 = 80%). - -Note. When the "-C" option is used with `\--find-copies-harder` -option, git-diff-\* commands feed unmodified filepairs to -diffcore mechanism as well as modified ones. This lets the copy -detector consider unmodified files as copy source candidates at -the expense of making it slower. Without `\--find-copies-harder`, -git-diff-\* commands can detect copies only if the file that was -copied happened to have been modified in the same changeset. - - -diffcore-merge-broken: For Putting "Complete Rewrites" Back Together --------------------------------------------------------------------- - -This transformation is used to merge filepairs broken by -diffcore-break, and not transformed into rename/copy by -diffcore-rename, back into a single modification. This always -runs when diffcore-break is used. - -For the purpose of merging broken filepairs back, it uses a -different "extent of changes" computation from the ones used by -diffcore-break and diffcore-rename. It counts only the deletion -from the original, and does not count insertion. If you removed -only 10 lines from a 100-line document, even if you added 910 -new lines to make a new 1000-line document, you did not do a -complete rewrite. diffcore-break breaks such a case in order to -help diffcore-rename to consider such filepairs as candidate of -rename/copy detection, but if filepairs broken that way were not -matched with other filepairs to create rename/copy, then this -transformation merges them back into the original -"modification". - -The "extent of changes" parameter can be tweaked from the -default 80% (that is, unless more than 80% of the original -material is deleted, the broken pairs are merged back into a -single modification) by giving a second number to -B option, -like these: - -* -B50/60 (give 50% "break score" to diffcore-break, use 60% - for diffcore-merge-broken). - -* -B/60 (the same as above, since diffcore-break defaults to 50%). - -Note that earlier implementation left a broken pair as a separate -creation and deletion patches. This was an unnecessary hack and -the latest implementation always merges all the broken pairs -back into modifications, but the resulting patch output is -formatted differently for easier review in case of such -a complete rewrite by showing the entire contents of old version -prefixed with '-', followed by the entire contents of new -version prefixed with '+'. - - -diffcore-pickaxe: For Detecting Addition/Deletion of Specified String ---------------------------------------------------------------------- - -This transformation is used to find filepairs that represent -changes that touch a specified string, and is controlled by the --S option and the `\--pickaxe-all` option to the git-diff-* -commands. - -When diffcore-pickaxe is in use, it checks if there are -filepairs whose "original" side has the specified string and -whose "result" side does not. Such a filepair represents "the -string appeared in this changeset". It also checks for the -opposite case that loses the specified string. - -When `\--pickaxe-all` is not in effect, diffcore-pickaxe leaves -only such filepairs that touch the specified string in its -output. When `\--pickaxe-all` is used, diffcore-pickaxe leaves all -filepairs intact if there is such a filepair, or makes the -output empty otherwise. The latter behaviour is designed to -make reviewing of the changes in the context of the whole -changeset easier. - - -diffcore-order: For Sorting the Output Based on Filenames ---------------------------------------------------------- - -This is used to reorder the filepairs according to the user's -(or project's) taste, and is controlled by the -O option to the -git-diff-* commands. - -This takes a text file each of whose lines is a shell glob -pattern. Filepairs that match a glob pattern on an earlier line -in the file are output before ones that match a later line, and -filepairs that do not match any glob pattern are output last. - -As an example, a typical orderfile for the core git probably -would look like this: - ------------------------------------------------- -README -Makefile -Documentation -*.h -*.c -t ------------------------------------------------- diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt index 1afd0c6..8eb9de1 100644 --- a/Documentation/git-add.txt +++ b/Documentation/git-add.txt @@ -100,7 +100,7 @@ Configuration The optional configuration variable 'core.excludesfile' indicates a path to a file containing patterns of file names to exclude from git-add, similar to $GIT_DIR/info/exclude. Patterns in the exclude file are used in addition to -those in info/exclude. See link:repository-layout.html[repository layout]. +those in info/exclude. See linkgit:gitrepository-layout[5][repository layout]. EXAMPLES diff --git a/Documentation/git-update-server-info.txt b/Documentation/git-update-server-info.txt index 1cf89fd..b49abbf 100644 --- a/Documentation/git-update-server-info.txt +++ b/Documentation/git-update-server-info.txt @@ -30,8 +30,8 @@ OUTPUT ------ Currently the command updates the following files. Please see -link:repository-layout.html[repository-layout] for description -of what they are for: +linkgit:gitrepository-layout[5][repository-layout] for description of +what they are for: * objects/info/packs diff --git a/Documentation/git.txt b/Documentation/git.txt index dae1b40..f0d106a 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -364,7 +364,8 @@ For a more complete list of ways to spell object names, see File/Directory Structure ------------------------ -Please see the link:repository-layout.html[repository layout] document. +Please see the linkgit:gitrepository-layout[5][repository layout] +document. Read linkgit:githooks[5][hooks] for more details about each hook. diff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt index 5995a2e..d61d5c9 100644 --- a/Documentation/gitcore-tutorial.txt +++ b/Documentation/gitcore-tutorial.txt @@ -109,7 +109,7 @@ populating your tree. [NOTE] An advanced user may want to take a look at the -link:repository-layout.html[repository layout] document +linkgit:gitrepository-layout[5][repository layout] document after finishing this tutorial. You have now created your first git repository. Of course, since it's diff --git a/Documentation/gitdiffcore.txt b/Documentation/gitdiffcore.txt new file mode 100644 index 0000000..f68efed --- /dev/null +++ b/Documentation/gitdiffcore.txt @@ -0,0 +1,292 @@ +gitdiffcore(7) +============== + +NAME +---- +gitdiffcore - Tweaking diff output (June 2005) + +SYNOPSIS +-------- +git diff * + +DESCRIPTION +----------- + +The diff commands git-diff-index, git-diff-files, and git-diff-tree +can be told to manipulate differences they find in +unconventional ways before showing diff(1) output. The manipulation +is collectively called "diffcore transformation". This short note +describes what they are and how to use them to produce diff outputs +that are easier to understand than the conventional kind. + + +The chain of operation +---------------------- + +The git-diff-* family works by first comparing two sets of +files: + + - git-diff-index compares contents of a "tree" object and the + working directory (when '\--cached' flag is not used) or a + "tree" object and the index file (when '\--cached' flag is + used); + + - git-diff-files compares contents of the index file and the + working directory; + + - git-diff-tree compares contents of two "tree" objects; + +In all of these cases, the commands themselves compare +corresponding paths in the two sets of files. The result of +comparison is passed from these commands to what is internally +called "diffcore", in a format similar to what is output when +the -p option is not used. E.g. + +------------------------------------------------ +in-place edit :100644 100644 bcd1234... 0123456... M file0 +create :000000 100644 0000000... 1234567... A file4 +delete :100644 000000 1234567... 0000000... D file5 +unmerged :000000 000000 0000000... 0000000... U file6 +------------------------------------------------ + +The diffcore mechanism is fed a list of such comparison results +(each of which is called "filepair", although at this point each +of them talks about a single file), and transforms such a list +into another list. There are currently 6 such transformations: + +- diffcore-pathspec +- diffcore-break +- diffcore-rename +- diffcore-merge-broken +- diffcore-pickaxe +- diffcore-order + +These are applied in sequence. The set of filepairs git-diff-\* +commands find are used as the input to diffcore-pathspec, and +the output from diffcore-pathspec is used as the input to the +next transformation. The final result is then passed to the +output routine and generates either diff-raw format (see Output +format sections of the manual for git-diff-\* commands) or +diff-patch format. + + +diffcore-pathspec: For Ignoring Files Outside Our Consideration +--------------------------------------------------------------- + +The first transformation in the chain is diffcore-pathspec, and +is controlled by giving the pathname parameters to the +git-diff-* commands on the command line. The pathspec is used +to limit the world diff operates in. It removes the filepairs +outside the specified set of pathnames. E.g. If the input set +of filepairs included: + +------------------------------------------------ +:100644 100644 bcd1234... 0123456... M junkfile +------------------------------------------------ + +but the command invocation was "git-diff-files myfile", then the +junkfile entry would be removed from the list because only "myfile" +is under consideration. + +Implementation note. For performance reasons, git-diff-tree +uses the pathname parameters on the command line to cull set of +filepairs it feeds the diffcore mechanism itself, and does not +use diffcore-pathspec, but the end result is the same. + + +diffcore-break: For Splitting Up "Complete Rewrites" +---------------------------------------------------- + +The second transformation in the chain is diffcore-break, and is +controlled by the -B option to the git-diff-* commands. This is +used to detect a filepair that represents "complete rewrite" and +break such filepair into two filepairs that represent delete and +create. E.g. If the input contained this filepair: + +------------------------------------------------ +:100644 100644 bcd1234... 0123456... M file0 +------------------------------------------------ + +and if it detects that the file "file0" is completely rewritten, +it changes it to: + +------------------------------------------------ +:100644 000000 bcd1234... 0000000... D file0 +:000000 100644 0000000... 0123456... A file0 +------------------------------------------------ + +For the purpose of breaking a filepair, diffcore-break examines +the extent of changes between the contents of the files before +and after modification (i.e. the contents that have "bcd1234..." +and "0123456..." as their SHA1 content ID, in the above +example). The amount of deletion of original contents and +insertion of new material are added together, and if it exceeds +the "break score", the filepair is broken into two. The break +score defaults to 50% of the size of the smaller of the original +and the result (i.e. if the edit shrinks the file, the size of +the result is used; if the edit lengthens the file, the size of +the original is used), and can be customized by giving a number +after "-B" option (e.g. "-B75" to tell it to use 75%). + + +diffcore-rename: For Detection Renames and Copies +------------------------------------------------- + +This transformation is used to detect renames and copies, and is +controlled by the -M option (to detect renames) and the -C option +(to detect copies as well) to the git-diff-* commands. If the +input contained these filepairs: + +------------------------------------------------ +:100644 000000 0123456... 0000000... D fileX +:000000 100644 0000000... 0123456... A file0 +------------------------------------------------ + +and the contents of the deleted file fileX is similar enough to +the contents of the created file file0, then rename detection +merges these filepairs and creates: + +------------------------------------------------ +:100644 100644 0123456... 0123456... R100 fileX file0 +------------------------------------------------ + +When the "-C" option is used, the original contents of modified files, +and deleted files (and also unmodified files, if the +"\--find-copies-harder" option is used) are considered as candidates +of the source files in rename/copy operation. If the input were like +these filepairs, that talk about a modified file fileY and a newly +created file file0: + +------------------------------------------------ +:100644 100644 0123456... 1234567... M fileY +:000000 100644 0000000... bcd3456... A file0 +------------------------------------------------ + +the original contents of fileY and the resulting contents of +file0 are compared, and if they are similar enough, they are +changed to: + +------------------------------------------------ +:100644 100644 0123456... 1234567... M fileY +:100644 100644 0123456... bcd3456... C100 fileY file0 +------------------------------------------------ + +In both rename and copy detection, the same "extent of changes" +algorithm used in diffcore-break is used to determine if two +files are "similar enough", and can be customized to use +a similarity score different from the default of 50% by giving a +number after the "-M" or "-C" option (e.g. "-M8" to tell it to use +8/10 = 80%). + +Note. When the "-C" option is used with `\--find-copies-harder` +option, git-diff-\* commands feed unmodified filepairs to +diffcore mechanism as well as modified ones. This lets the copy +detector consider unmodified files as copy source candidates at +the expense of making it slower. Without `\--find-copies-harder`, +git-diff-\* commands can detect copies only if the file that was +copied happened to have been modified in the same changeset. + + +diffcore-merge-broken: For Putting "Complete Rewrites" Back Together +-------------------------------------------------------------------- + +This transformation is used to merge filepairs broken by +diffcore-break, and not transformed into rename/copy by +diffcore-rename, back into a single modification. This always +runs when diffcore-break is used. + +For the purpose of merging broken filepairs back, it uses a +different "extent of changes" computation from the ones used by +diffcore-break and diffcore-rename. It counts only the deletion +from the original, and does not count insertion. If you removed +only 10 lines from a 100-line document, even if you added 910 +new lines to make a new 1000-line document, you did not do a +complete rewrite. diffcore-break breaks such a case in order to +help diffcore-rename to consider such filepairs as candidate of +rename/copy detection, but if filepairs broken that way were not +matched with other filepairs to create rename/copy, then this +transformation merges them back into the original +"modification". + +The "extent of changes" parameter can be tweaked from the +default 80% (that is, unless more than 80% of the original +material is deleted, the broken pairs are merged back into a +single modification) by giving a second number to -B option, +like these: + +* -B50/60 (give 50% "break score" to diffcore-break, use 60% + for diffcore-merge-broken). + +* -B/60 (the same as above, since diffcore-break defaults to 50%). + +Note that earlier implementation left a broken pair as a separate +creation and deletion patches. This was an unnecessary hack and +the latest implementation always merges all the broken pairs +back into modifications, but the resulting patch output is +formatted differently for easier review in case of such +a complete rewrite by showing the entire contents of old version +prefixed with '-', followed by the entire contents of new +version prefixed with '+'. + + +diffcore-pickaxe: For Detecting Addition/Deletion of Specified String +--------------------------------------------------------------------- + +This transformation is used to find filepairs that represent +changes that touch a specified string, and is controlled by the +-S option and the `\--pickaxe-all` option to the git-diff-* +commands. + +When diffcore-pickaxe is in use, it checks if there are +filepairs whose "original" side has the specified string and +whose "result" side does not. Such a filepair represents "the +string appeared in this changeset". It also checks for the +opposite case that loses the specified string. + +When `\--pickaxe-all` is not in effect, diffcore-pickaxe leaves +only such filepairs that touch the specified string in its +output. When `\--pickaxe-all` is used, diffcore-pickaxe leaves all +filepairs intact if there is such a filepair, or makes the +output empty otherwise. The latter behaviour is designed to +make reviewing of the changes in the context of the whole +changeset easier. + + +diffcore-order: For Sorting the Output Based on Filenames +--------------------------------------------------------- + +This is used to reorder the filepairs according to the user's +(or project's) taste, and is controlled by the -O option to the +git-diff-* commands. + +This takes a text file each of whose lines is a shell glob +pattern. Filepairs that match a glob pattern on an earlier line +in the file are output before ones that match a later line, and +filepairs that do not match any glob pattern are output last. + +As an example, a typical orderfile for the core git probably +would look like this: + +------------------------------------------------ +README +Makefile +Documentation +*.h +*.c +t +------------------------------------------------ + +SEE ALSO +-------- +linkgit:git-diff[1], +linkgit:git-diff-files[1], +linkgit:git-diff-index[1], +linkgit:git-diff-tree[1], +linkgit:git-format-patch[1], +linkgit:git-log[1], +linkgit:gitglossary[7], +link:user-manual.html[The Git User's Manual] + +GIT +--- +Part of the linkgit:git[7] suite. diff --git a/Documentation/gitrepository-layout.txt b/Documentation/gitrepository-layout.txt new file mode 100644 index 0000000..9949093 --- /dev/null +++ b/Documentation/gitrepository-layout.txt @@ -0,0 +1,208 @@ +gitrepository-layout(5) +======================= + +NAME +---- +gitrepository-layout - Git Repository Layout + +SYNOPSIS +-------- +$GIT_DIR/* + +DESCRIPTION +----------- + +You may find these things in your git repository (`.git` +directory for a repository associated with your working tree, or +`.git` directory for a public 'bare' repository. It is +also possible to have a working tree where `.git` is a plain +ascii file containing `gitdir: `, i.e. the path to the +real git repository). + +objects:: + Object store associated with this repository. Usually + an object store is self sufficient (i.e. all the objects + that are referred to by an object found in it are also + found in it), but there are couple of ways to violate + it. ++ +. You could populate the repository by running a commit walker +without `-a` option. Depending on which options are given, you +could have only commit objects without associated blobs and +trees this way, for example. A repository with this kind of +incomplete object store is not suitable to be published to the +outside world but sometimes useful for private repository. +. You also could have an incomplete but locally usable repository +by cloning shallowly. See linkgit:git-clone[1]. +. You can be using `objects/info/alternates` mechanism, or +`$GIT_ALTERNATE_OBJECT_DIRECTORIES` mechanism to 'borrow' +objects from other object stores. A repository with this kind +of incomplete object store is not suitable to be published for +use with dumb transports but otherwise is OK as long as +`objects/info/alternates` points at the right object stores +it borrows from. + +objects/[0-9a-f][0-9a-f]:: + Traditionally, each object is stored in its own file. + They are split into 256 subdirectories using the first + two letters from its object name to keep the number of + directory entries `objects` directory itself needs to + hold. Objects found here are often called 'unpacked' + (or 'loose') objects. + +objects/pack:: + Packs (files that store many object in compressed form, + along with index files to allow them to be randomly + accessed) are found in this directory. + +objects/info:: + Additional information about the object store is + recorded in this directory. + +objects/info/packs:: + This file is to help dumb transports discover what packs + are available in this object store. Whenever a pack is + added or removed, `git update-server-info` should be run + to keep this file up-to-date if the repository is + published for dumb transports. `git repack` does this + by default. + +objects/info/alternates:: + This file records paths to alternate object stores that + this object store borrows objects from, one pathname per + line. Note that not only native Git tools use it locally, + but the HTTP fetcher also tries to use it remotely; this + will usually work if you have relative paths (relative + to the object database, not to the repository!) in your + alternates file, but it will not work if you use absolute + paths unless the absolute path in filesystem and web URL + is the same. See also 'objects/info/http-alternates'. + +objects/info/http-alternates:: + This file records URLs to alternate object stores that + this object store borrows objects from, to be used when + the repository is fetched over HTTP. + +refs:: + References are stored in subdirectories of this + directory. The `git prune` command knows to keep + objects reachable from refs found in this directory and + its subdirectories. + +refs/heads/`name`:: + records tip-of-the-tree commit objects of branch `name` + +refs/tags/`name`:: + records any object name (not necessarily a commit + object, or a tag object that points at a commit object). + +refs/remotes/`name`:: + records tip-of-the-tree commit objects of branches copied + from a remote repository. + +packed-refs:: + records the same information as refs/heads/, refs/tags/, + and friends record in a more efficient way. See + linkgit:git-pack-refs[1]. + +HEAD:: + A symref (see glossary) to the `refs/heads/` namespace + describing the currently active branch. It does not mean + much if the repository is not associated with any working tree + (i.e. a 'bare' repository), but a valid git repository + *must* have the HEAD file; some porcelains may use it to + guess the designated "default" branch of the repository + (usually 'master'). It is legal if the named branch + 'name' does not (yet) exist. In some legacy setups, it is + a symbolic link instead of a symref that points at the current + branch. ++ +HEAD can also record a specific commit directly, instead of +being a symref to point at the current branch. Such a state +is often called 'detached HEAD', and almost all commands work +identically as normal. See linkgit:git-checkout[1] for +details. + +branches:: + A slightly deprecated way to store shorthands to be used + to specify URL to `git fetch`, `git pull` and `git push` + commands is to store a file in `branches/` and + give 'name' to these commands in place of 'repository' + argument. + +hooks:: + Hooks are customization scripts used by various git + commands. A handful of sample hooks are installed when + `git init` is run, but all of them are disabled by + default. To enable, they need to be made executable. + Read linkgit:githooks[5][hooks] for more details about + each hook. + +index:: + The current index file for the repository. It is + usually not found in a bare repository. + +info:: + Additional information about the repository is recorded + in this directory. + +info/refs:: + This file helps dumb transports discover what refs are + available in this repository. If the repository is + published for dumb transports, this file should be + regenerated by `git update-server-info` every time a tag + or branch is created or modified. This is normally done + from the `hooks/update` hook, which is run by the + `git-receive-pack` command when you `git push` into the + repository. + +info/grafts:: + This file records fake commit ancestry information, to + pretend the set of parents a commit has is different + from how the commit was actually created. One record + per line describes a commit and its fake parents by + listing their 40-byte hexadecimal object names separated + by a space and terminated by a newline. + +info/exclude:: + This file, by convention among Porcelains, stores the + exclude pattern list. `.gitignore` is the per-directory + ignore file. `git status`, `git add`, `git rm` and `git + clean` look at it but the core git commands do not look + at it. See also: linkgit:gitignore[5]. + +remotes:: + Stores shorthands to be used to give URL and default + refnames to interact with remote repository to `git + fetch`, `git pull` and `git push` commands. + +logs:: + Records of changes made to refs are stored in this + directory. See the documentation on git-update-ref + for more information. + +logs/refs/heads/`name`:: + Records all changes made to the branch tip named `name`. + +logs/refs/tags/`name`:: + Records all changes made to the tag named `name`. + +shallow:: + This is similar to `info/grafts` but is internally used + and maintained by shallow clone mechanism. See `--depth` + option to linkgit:git-clone[1] and linkgit:git-fetch[1]. + +SEE ALSO +-------- +linkgit:git-init[1], +linkgit:git-clone[1], +linkgit:git-fetch[1], +linkgit:git-pack-refs[1], +linkgit:git-gc[1], +linkgit:git-checkout[1], +linkgit:gitglossary[7], +link:user-manual.html[The Git User's Manual] + +GIT +--- +Part of the linkgit:git[7] suite. diff --git a/Documentation/repository-layout.txt b/Documentation/repository-layout.txt deleted file mode 100644 index 7fd187b..0000000 --- a/Documentation/repository-layout.txt +++ /dev/null @@ -1,182 +0,0 @@ -git repository layout -===================== - -You may find these things in your git repository (`.git` -directory for a repository associated with your working tree, or -`'project'.git` directory for a public 'bare' repository. It is -also possible to have a working tree where `.git` is a plain -ascii file containing `gitdir: `, i.e. the path to the -real git repository). - -objects:: - Object store associated with this repository. Usually - an object store is self sufficient (i.e. all the objects - that are referred to by an object found in it are also - found in it), but there are couple of ways to violate - it. -+ -. You could populate the repository by running a commit walker -without `-a` option. Depending on which options are given, you -could have only commit objects without associated blobs and -trees this way, for example. A repository with this kind of -incomplete object store is not suitable to be published to the -outside world but sometimes useful for private repository. -. You also could have an incomplete but locally usable repository -by cloning shallowly. See linkgit:git-clone[1]. -. You can be using `objects/info/alternates` mechanism, or -`$GIT_ALTERNATE_OBJECT_DIRECTORIES` mechanism to 'borrow' -objects from other object stores. A repository with this kind -of incomplete object store is not suitable to be published for -use with dumb transports but otherwise is OK as long as -`objects/info/alternates` points at the right object stores -it borrows from. - -objects/[0-9a-f][0-9a-f]:: - Traditionally, each object is stored in its own file. - They are split into 256 subdirectories using the first - two letters from its object name to keep the number of - directory entries `objects` directory itself needs to - hold. Objects found here are often called 'unpacked' - (or 'loose') objects. - -objects/pack:: - Packs (files that store many object in compressed form, - along with index files to allow them to be randomly - accessed) are found in this directory. - -objects/info:: - Additional information about the object store is - recorded in this directory. - -objects/info/packs:: - This file is to help dumb transports discover what packs - are available in this object store. Whenever a pack is - added or removed, `git update-server-info` should be run - to keep this file up-to-date if the repository is - published for dumb transports. `git repack` does this - by default. - -objects/info/alternates:: - This file records paths to alternate object stores that - this object store borrows objects from, one pathname per - line. Note that not only native Git tools use it locally, - but the HTTP fetcher also tries to use it remotely; this - will usually work if you have relative paths (relative - to the object database, not to the repository!) in your - alternates file, but it will not work if you use absolute - paths unless the absolute path in filesystem and web URL - is the same. See also 'objects/info/http-alternates'. - -objects/info/http-alternates:: - This file records URLs to alternate object stores that - this object store borrows objects from, to be used when - the repository is fetched over HTTP. - -refs:: - References are stored in subdirectories of this - directory. The `git prune` command knows to keep - objects reachable from refs found in this directory and - its subdirectories. - -refs/heads/`name`:: - records tip-of-the-tree commit objects of branch `name` - -refs/tags/`name`:: - records any object name (not necessarily a commit - object, or a tag object that points at a commit object). - -refs/remotes/`name`:: - records tip-of-the-tree commit objects of branches copied - from a remote repository. - -packed-refs:: - records the same information as refs/heads/, refs/tags/, - and friends record in a more efficient way. See - linkgit:git-pack-refs[1]. - -HEAD:: - A symref (see glossary) to the `refs/heads/` namespace - describing the currently active branch. It does not mean - much if the repository is not associated with any working tree - (i.e. a 'bare' repository), but a valid git repository - *must* have the HEAD file; some porcelains may use it to - guess the designated "default" branch of the repository - (usually 'master'). It is legal if the named branch - 'name' does not (yet) exist. In some legacy setups, it is - a symbolic link instead of a symref that points at the current - branch. -+ -HEAD can also record a specific commit directly, instead of -being a symref to point at the current branch. Such a state -is often called 'detached HEAD', and almost all commands work -identically as normal. See linkgit:git-checkout[1] for -details. - -branches:: - A slightly deprecated way to store shorthands to be used - to specify URL to `git fetch`, `git pull` and `git push` - commands is to store a file in `branches/'name'` and - give 'name' to these commands in place of 'repository' - argument. - -hooks:: - Hooks are customization scripts used by various git - commands. A handful of sample hooks are installed when - `git init` is run, but all of them are disabled by - default. To enable, they need to be made executable. - Read linkgit:githooks[5][hooks] for more details about - each hook. - -index:: - The current index file for the repository. It is - usually not found in a bare repository. - -info:: - Additional information about the repository is recorded - in this directory. - -info/refs:: - This file helps dumb transports discover what refs are - available in this repository. If the repository is - published for dumb transports, this file should be - regenerated by `git update-server-info` every time a tag - or branch is created or modified. This is normally done - from the `hooks/update` hook, which is run by the - `git-receive-pack` command when you `git push` into the - repository. - -info/grafts:: - This file records fake commit ancestry information, to - pretend the set of parents a commit has is different - from how the commit was actually created. One record - per line describes a commit and its fake parents by - listing their 40-byte hexadecimal object names separated - by a space and terminated by a newline. - -info/exclude:: - This file, by convention among Porcelains, stores the - exclude pattern list. `.gitignore` is the per-directory - ignore file. `git status`, `git add`, `git rm` and `git - clean` look at it but the core git commands do not look - at it. See also: linkgit:gitignore[5]. - -remotes:: - Stores shorthands to be used to give URL and default - refnames to interact with remote repository to `git - fetch`, `git pull` and `git push` commands. - -logs:: - Records of changes made to refs are stored in this - directory. See the documentation on git-update-ref - for more information. - -logs/refs/heads/`name`:: - Records all changes made to the branch tip named `name`. - -logs/refs/tags/`name`:: - Records all changes made to the tag named `name`. - -shallow:: - This is similar to `info/grafts` but is internally used - and maintained by shallow clone mechanism. See `--depth` - option to linkgit:git-clone[1] and linkgit:git-fetch[1]. -- cgit v0.10.2-6-g49f6