From 4f9a60570b88fc1b9076ae2f5cfecf43bce0c87c Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Wed, 17 Jan 2007 20:25:16 +0000 Subject: [PATCH] Autogenerated HTML docs for v1.5.0-rc1-g556b --- core-intro.txt | 590 +++++++++++++++++++++++++++++++++++++++++ git-add.html | 6 +- git-add.txt | 4 +- git-checkout.html | 49 +++- git-checkout.txt | 54 +++- git-format-patch.html | 23 +- git-format-patch.txt | 17 +- git.html | 8 +- git.txt | 2 +- glossary.html | 17 +- glossary.txt | 12 + repository-layout.html | 44 ++- repository-layout.txt | 25 +- 13 files changed, 829 insertions(+), 22 deletions(-) create mode 100644 core-intro.txt diff --git a/core-intro.txt b/core-intro.txt new file mode 100644 index 000000000..0458dc3d0 --- /dev/null +++ b/core-intro.txt @@ -0,0 +1,590 @@ +//////////////////////////////////////////////////////////////// + + GIT - the stupid content tracker + +//////////////////////////////////////////////////////////////// + +"git" can mean anything, depending on your mood. + + - random three-letter combination that is pronounceable, and not + actually used by any common UNIX command. The fact that it is a + mispronunciation of "get" may or may not be relevant. + - stupid. contemptible and despicable. simple. Take your pick from the + dictionary of slang. + - "global information tracker": you're in a good mood, and it actually + works for you. Angels sing, and a light suddenly fills the room. + - "goddamn idiotic truckload of sh*t": when it breaks + +This is a (not so) stupid but extremely fast directory content manager. +It doesn't do a whole lot at its core, but what it 'does' do is track +directory contents efficiently. + +There are two object abstractions: the "object database", and the +"current directory cache" aka "index". + +The Object Database +~~~~~~~~~~~~~~~~~~~ +The object database is literally just a content-addressable collection +of objects. All objects are named by their content, which is +approximated by the SHA1 hash of the object itself. Objects may refer +to other objects (by referencing their SHA1 hash), and so you can +build up a hierarchy of objects. + +All objects have a statically determined "type" aka "tag", which is +determined at object creation time, and which identifies the format of +the object (i.e. how it is used, and how it can refer to other +objects). There are currently four different object types: "blob", +"tree", "commit" and "tag". + +A "blob" object cannot refer to any other object, and is, like the type +implies, a pure storage object containing some user data. It is used to +actually store the file data, i.e. a blob object is associated with some +particular version of some file. + +A "tree" object is an object that ties one or more "blob" objects into a +directory structure. In addition, a tree object can refer to other tree +objects, thus creating a directory hierarchy. + +A "commit" object ties such directory hierarchies together into +a DAG of revisions - each "commit" is associated with exactly one tree +(the directory hierarchy at the time of the commit). In addition, a +"commit" refers to one or more "parent" commit objects that describe the +history of how we arrived at that directory hierarchy. + +As a special case, a commit object with no parents is called the "root" +object, and is the point of an initial project commit. Each project +must have at least one root, and while you can tie several different +root objects together into one project by creating a commit object which +has two or more separate roots as its ultimate parents, that's probably +just going to confuse people. So aim for the notion of "one root object +per project", even if git itself does not enforce that. + +A "tag" object symbolically identifies and can be used to sign other +objects. It contains the identifier and type of another object, a +symbolic name (of course!) and, optionally, a signature. + +Regardless of object type, all objects share the following +characteristics: they are all deflated with zlib, and have a header +that not only specifies their type, but also provides size information +about the data in the object. It's worth noting that the SHA1 hash +that is used to name the object is the hash of the original data +plus this header, so `sha1sum` 'file' does not match the object name +for 'file'. +(Historical note: in the dawn of the age of git the hash +was the sha1 of the 'compressed' object.) + +As a result, the general consistency of an object can always be tested +independently of the contents or the type of the object: all objects can +be validated by verifying that (a) their hashes match the content of the +file and (b) the object successfully inflates to a stream of bytes that +forms a sequence of + + + + . + +The structured objects can further have their structure and +connectivity to other objects verified. This is generally done with +the `git-fsck-objects` program, which generates a full dependency graph +of all objects, and verifies their internal consistency (in addition +to just verifying their superficial consistency through the hash). + +The object types in some more detail: + +Blob Object +~~~~~~~~~~~ +A "blob" object is nothing but a binary blob of data, and doesn't +refer to anything else. There is no signature or any other +verification of the data, so while the object is consistent (it 'is' +indexed by its sha1 hash, so the data itself is certainly correct), it +has absolutely no other attributes. No name associations, no +permissions. It is purely a blob of data (i.e. normally "file +contents"). + +In particular, since the blob is entirely defined by its data, if two +files in a directory tree (or in multiple different versions of the +repository) have the same contents, they will share the same blob +object. The object is totally independent of its location in the +directory tree, and renaming a file does not change the object that +file is associated with in any way. + +A blob is typically created when gitlink:git-update-index[1] +is run, and its data can be accessed by gitlink:git-cat-file[1]. + +Tree Object +~~~~~~~~~~~ +The next hierarchical object type is the "tree" object. A tree object +is a list of mode/name/blob data, sorted by name. Alternatively, the +mode data may specify a directory mode, in which case instead of +naming a blob, that name is associated with another TREE object. + +Like the "blob" object, a tree object is uniquely determined by the +set contents, and so two separate but identical trees will always +share the exact same object. This is true at all levels, i.e. it's +true for a "leaf" tree (which does not refer to any other trees, only +blobs) as well as for a whole subdirectory. + +For that reason a "tree" object is just a pure data abstraction: it +has no history, no signatures, no verification of validity, except +that since the contents are again protected by the hash itself, we can +trust that the tree is immutable and its contents never change. + +So you can trust the contents of a tree to be valid, the same way you +can trust the contents of a blob, but you don't know where those +contents 'came' from. + +Side note on trees: since a "tree" object is a sorted list of +"filename+content", you can create a diff between two trees without +actually having to unpack two trees. Just ignore all common parts, +and your diff will look right. In other words, you can effectively +(and efficiently) tell the difference between any two random trees by +O(n) where "n" is the size of the difference, rather than the size of +the tree. + +Side note 2 on trees: since the name of a "blob" depends entirely and +exclusively on its contents (i.e. there are no names or permissions +involved), you can see trivial renames or permission changes by +noticing that the blob stayed the same. However, renames with data +changes need a smarter "diff" implementation. + +A tree is created with gitlink:git-write-tree[1] and +its data can be accessed by gitlink:git-ls-tree[1]. +Two trees can be compared with gitlink:git-diff-tree[1]. + +Commit Object +~~~~~~~~~~~~~ +The "commit" object is an object that introduces the notion of +history into the picture. In contrast to the other objects, it +doesn't just describe the physical state of a tree, it describes how +we got there, and why. + +A "commit" is defined by the tree-object that it results in, the +parent commits (zero, one or more) that led up to that point, and a +comment on what happened. Again, a commit is not trusted per se: +the contents are well-defined and "safe" due to the cryptographically +strong signatures at all levels, but there is no reason to believe +that the tree is "good" or that the merge information makes sense. +The parents do not have to actually have any relationship with the +result, for example. + +Note on commits: unlike real SCM's, commits do not contain +rename information or file mode change information. All of that is +implicit in the trees involved (the result tree, and the result trees +of the parents), and describing that makes no sense in this idiotic +file manager. + +A commit is created with gitlink:git-commit-tree[1] and +its data can be accessed by gitlink:git-cat-file[1]. + +Trust +~~~~~ +An aside on the notion of "trust". Trust is really outside the scope +of "git", but it's worth noting a few things. First off, since +everything is hashed with SHA1, you 'can' trust that an object is +intact and has not been messed with by external sources. So the name +of an object uniquely identifies a known state - just not a state that +you may want to trust. + +Furthermore, since the SHA1 signature of a commit refers to the +SHA1 signatures of the tree it is associated with and the signatures +of the parent, a single named commit specifies uniquely a whole set +of history, with full contents. You can't later fake any step of the +way once you have the name of a commit. + +So to introduce some real trust in the system, the only thing you need +to do is to digitally sign just 'one' special note, which includes the +name of a top-level commit. Your digital signature shows others +that you trust that commit, and the immutability of the history of +commits tells others that they can trust the whole history. + +In other words, you can easily validate a whole archive by just +sending out a single email that tells the people the name (SHA1 hash) +of the top commit, and digitally sign that email using something +like GPG/PGP. + +To assist in this, git also provides the tag object... + +Tag Object +~~~~~~~~~~ +Git provides the "tag" object to simplify creating, managing and +exchanging symbolic and signed tokens. The "tag" object at its +simplest simply symbolically identifies another object by containing +the sha1, type and symbolic name. + +However it can optionally contain additional signature information +(which git doesn't care about as long as there's less than 8k of +it). This can then be verified externally to git. + +Note that despite the tag features, "git" itself only handles content +integrity; the trust framework (and signature provision and +verification) has to come from outside. + +A tag is created with gitlink:git-mktag[1], +its data can be accessed by gitlink:git-cat-file[1], +and the signature can be verified by +gitlink:git-verify-tag[1]. + + +The "index" aka "Current Directory Cache" +----------------------------------------- +The index is a simple binary file, which contains an efficient +representation of a virtual directory content at some random time. It +does so by a simple array that associates a set of names, dates, +permissions and content (aka "blob") objects together. The cache is +always kept ordered by name, and names are unique (with a few very +specific rules) at any point in time, but the cache has no long-term +meaning, and can be partially updated at any time. + +In particular, the index certainly does not need to be consistent with +the current directory contents (in fact, most operations will depend on +different ways to make the index 'not' be consistent with the directory +hierarchy), but it has three very important attributes: + +'(a) it can re-generate the full state it caches (not just the +directory structure: it contains pointers to the "blob" objects so +that it can regenerate the data too)' + +As a special case, there is a clear and unambiguous one-way mapping +from a current directory cache to a "tree object", which can be +efficiently created from just the current directory cache without +actually looking at any other data. So a directory cache at any one +time uniquely specifies one and only one "tree" object (but has +additional data to make it easy to match up that tree object with what +has happened in the directory) + +'(b) it has efficient methods for finding inconsistencies between that +cached state ("tree object waiting to be instantiated") and the +current state.' + +'(c) it can additionally efficiently represent information about merge +conflicts between different tree objects, allowing each pathname to be +associated with sufficient information about the trees involved that +you can create a three-way merge between them.' + +Those are the three ONLY things that the directory cache does. It's a +cache, and the normal operation is to re-generate it completely from a +known tree object, or update/compare it with a live tree that is being +developed. If you blow the directory cache away entirely, you generally +haven't lost any information as long as you have the name of the tree +that it described. + +At the same time, the index is at the same time also the +staging area for creating new trees, and creating a new tree always +involves a controlled modification of the index file. In particular, +the index file can have the representation of an intermediate tree that +has not yet been instantiated. So the index can be thought of as a +write-back cache, which can contain dirty information that has not yet +been written back to the backing store. + + + +The Workflow +------------ +Generally, all "git" operations work on the index file. Some operations +work *purely* on the index file (showing the current state of the +index), but most operations move data to and from the index file. Either +from the database or from the working directory. Thus there are four +main combinations: + +1) working directory -> index +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You update the index with information from the working directory with +the gitlink:git-update-index[1] command. You +generally update the index information by just specifying the filename +you want to update, like so: + + git-update-index filename + +but to avoid common mistakes with filename globbing etc, the command +will not normally add totally new entries or remove old entries, +i.e. it will normally just update existing cache entries. + +To tell git that yes, you really do realize that certain files no +longer exist, or that new files should be added, you +should use the `--remove` and `--add` flags respectively. + +NOTE! A `--remove` flag does 'not' mean that subsequent filenames will +necessarily be removed: if the files still exist in your directory +structure, the index will be updated with their new status, not +removed. The only thing `--remove` means is that update-cache will be +considering a removed file to be a valid thing, and if the file really +does not exist any more, it will update the index accordingly. + +As a special case, you can also do `git-update-index --refresh`, which +will refresh the "stat" information of each index to match the current +stat information. It will 'not' update the object status itself, and +it will only update the fields that are used to quickly test whether +an object still matches its old backing store object. + +2) index -> object database +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You write your current index file to a "tree" object with the program + + git-write-tree + +that doesn't come with any options - it will just write out the +current index into the set of tree objects that describe that state, +and it will return the name of the resulting top-level tree. You can +use that tree to re-generate the index at any time by going in the +other direction: + +3) object database -> index +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You read a "tree" file from the object database, and use that to +populate (and overwrite - don't do this if your index contains any +unsaved state that you might want to restore later!) your current +index. Normal operation is just + + git-read-tree + +and your index file will now be equivalent to the tree that you saved +earlier. However, that is only your 'index' file: your working +directory contents have not been modified. + +4) index -> working directory +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You update your working directory from the index by "checking out" +files. This is not a very common operation, since normally you'd just +keep your files updated, and rather than write to your working +directory, you'd tell the index files about the changes in your +working directory (i.e. `git-update-index`). + +However, if you decide to jump to a new version, or check out somebody +else's version, or just restore a previous tree, you'd populate your +index file with read-tree, and then you need to check out the result +with + + git-checkout-index filename + +or, if you want to check out all of the index, use `-a`. + +NOTE! git-checkout-index normally refuses to overwrite old files, so +if you have an old version of the tree already checked out, you will +need to use the "-f" flag ('before' the "-a" flag or the filename) to +'force' the checkout. + + +Finally, there are a few odds and ends which are not purely moving +from one representation to the other: + +5) Tying it all together +~~~~~~~~~~~~~~~~~~~~~~~~ +To commit a tree you have instantiated with "git-write-tree", you'd +create a "commit" object that refers to that tree and the history +behind it - most notably the "parent" commits that preceded it in +history. + +Normally a "commit" has one parent: the previous state of the tree +before a certain change was made. However, sometimes it can have two +or more parent commits, in which case we call it a "merge", due to the +fact that such a commit brings together ("merges") two or more +previous states represented by other commits. + +In other words, while a "tree" represents a particular directory state +of a working directory, a "commit" represents that state in "time", +and explains how we got there. + +You create a commit object by giving it the tree that describes the +state at the time of the commit, and a list of parents: + + git-commit-tree -p [-p ..] + +and then giving the reason for the commit on stdin (either through +redirection from a pipe or file, or by just typing it at the tty). + +git-commit-tree will return the name of the object that represents +that commit, and you should save it away for later use. Normally, +you'd commit a new `HEAD` state, and while git doesn't care where you +save the note about that state, in practice we tend to just write the +result to the file pointed at by `.git/HEAD`, so that we can always see +what the last committed state was. + +Here is an ASCII art by Jon Loeliger that illustrates how +various pieces fit together. + +------------ + + commit-tree + commit obj + +----+ + | | + | | + V V + +-----------+ + | Object DB | + | Backing | + | Store | + +-----------+ + ^ + write-tree | | + tree obj | | + | | read-tree + | | tree obj + V + +-----------+ + | Index | + | "cache" | + +-----------+ + update-index ^ + blob obj | | + | | + checkout-index -u | | checkout-index + stat | | blob obj + V + +-----------+ + | Working | + | Directory | + +-----------+ + +------------ + + +6) Examining the data +~~~~~~~~~~~~~~~~~~~~~ + +You can examine the data represented in the object database and the +index with various helper tools. For every object, you can use +gitlink:git-cat-file[1] to examine details about the +object: + + git-cat-file -t + +shows the type of the object, and once you have the type (which is +usually implicit in where you find the object), you can use + + git-cat-file blob|tree|commit|tag + +to show its contents. NOTE! Trees have binary content, and as a result +there is a special helper for showing that content, called +`git-ls-tree`, which turns the binary content into a more easily +readable form. + +It's especially instructive to look at "commit" objects, since those +tend to be small and fairly self-explanatory. In particular, if you +follow the convention of having the top commit name in `.git/HEAD`, +you can do + + git-cat-file commit HEAD + +to see what the top commit was. + +7) Merging multiple trees +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Git helps you do a three-way merge, which you can expand to n-way by +repeating the merge procedure arbitrary times until you finally +"commit" the state. The normal situation is that you'd only do one +three-way merge (two parents), and commit it, but if you like to, you +can do multiple parents in one go. + +To do a three-way merge, you need the two sets of "commit" objects +that you want to merge, use those to find the closest common parent (a +third "commit" object), and then use those commit objects to find the +state of the directory ("tree" object) at these points. + +To get the "base" for the merge, you first look up the common parent +of two commits with + + git-merge-base + +which will return you the commit they are both based on. You should +now look up the "tree" objects of those commits, which you can easily +do with (for example) + + git-cat-file commit | head -1 + +since the tree object information is always the first line in a commit +object. + +Once you know the three trees you are going to merge (the one +"original" tree, aka the common case, and the two "result" trees, aka +the branches you want to merge), you do a "merge" read into the +index. This will complain if it has to throw away your old index contents, so you should +make sure that you've committed those - in fact you would normally +always do a merge against your last commit (which should thus match +what you have in your current index anyway). + +To do the merge, do + + git-read-tree -m -u + +which will do all trivial merge operations for you directly in the +index file, and you can just write the result out with +`git-write-tree`. + +Historical note. We did not have `-u` facility when this +section was first written, so we used to warn that +the merge is done in the index file, not in your +working tree, and your working tree will not match your +index after this step. +This is no longer true. The above command, thanks to `-u` +option, updates your working tree with the merge results for +paths that have been trivially merged. + + +8) Merging multiple trees, continued +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Sadly, many merges aren't trivial. If there are files that have +been added.moved or removed, or if both branches have modified the +same file, you will be left with an index tree that contains "merge +entries" in it. Such an index tree can 'NOT' be written out to a tree +object, and you will have to resolve any such merge clashes using +other tools before you can write out the result. + +You can examine such index state with `git-ls-files --unmerged` +command. An example: + +------------------------------------------------ +$ git-read-tree -m $orig HEAD $target +$ git-ls-files --unmerged +100644 263414f423d0e4d70dae8fe53fa34614ff3e2860 1 hello.c +100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 2 hello.c +100644 cc44c73eb783565da5831b4d820c962954019b69 3 hello.c +------------------------------------------------ + +Each line of the `git-ls-files --unmerged` output begins with +the blob mode bits, blob SHA1, 'stage number', and the +filename. The 'stage number' is git's way to say which tree it +came from: stage 1 corresponds to `$orig` tree, stage 2 `HEAD` +tree, and stage3 `$target` tree. + +Earlier we said that trivial merges are done inside +`git-read-tree -m`. For example, if the file did not change +from `$orig` to `HEAD` nor `$target`, or if the file changed +from `$orig` to `HEAD` and `$orig` to `$target` the same way, +obviously the final outcome is what is in `HEAD`. What the +above example shows is that file `hello.c` was changed from +`$orig` to `HEAD` and `$orig` to `$target` in a different way. +You could resolve this by running your favorite 3-way merge +program, e.g. `diff3` or `merge`, on the blob objects from +these three stages yourself, like this: + +------------------------------------------------ +$ git-cat-file blob 263414f... >hello.c~1 +$ git-cat-file blob 06fa6a2... >hello.c~2 +$ git-cat-file blob cc44c73... >hello.c~3 +$ merge hello.c~2 hello.c~1 hello.c~3 +------------------------------------------------ + +This would leave the merge result in `hello.c~2` file, along +with conflict markers if there are conflicts. After verifying +the merge result makes sense, you can tell git what the final +merge result for this file is by: + + mv -f hello.c~2 hello.c + git-update-index hello.c + +When a path is in unmerged state, running `git-update-index` for +that path tells git to mark the path resolved. + +The above is the description of a git merge at the lowest level, +to help you understand what conceptually happens under the hood. +In practice, nobody, not even git itself, uses three `git-cat-file` +for this. There is `git-merge-index` program that extracts the +stages to temporary files and calls a "merge" script on it: + + git-merge-index git-merge-one-file hello.c + +and that is what higher level `git resolve` is implemented with. diff --git a/git-add.html b/git-add.html index 2371316bf..82cee8add 100644 --- a/git-add.html +++ b/git-add.html @@ -272,7 +272,7 @@ git-add(1) Manual Page

SYNOPSIS

-

git-add [-n] [-v] [-f] [--interactive] [--] <file>…

+

git-add [-n] [-v] [-f] [--interactive | -i] [--] <file>…

DESCRIPTION

@@ -334,7 +334,7 @@ commit.

---interactive +\i, --interactive

@@ -536,7 +536,7 @@ diff

diff --git a/git-add.txt b/git-add.txt index a5051aad6..b73a99d61 100644 --- a/git-add.txt +++ b/git-add.txt @@ -7,7 +7,7 @@ git-add - Add file contents to the changeset to be committed next SYNOPSIS -------- -'git-add' [-n] [-v] [-f] [--interactive] [--] ... +'git-add' [-n] [-v] [-f] [--interactive | -i] [--] ... DESCRIPTION ----------- @@ -52,7 +52,7 @@ OPTIONS -f:: Allow adding otherwise ignored files. -\--interactive:: +\i, \--interactive:: Add modified contents in the working tree interactively to the index. diff --git a/git-checkout.html b/git-checkout.html index 34a981b2b..4b8c211f8 100644 --- a/git-checkout.html +++ b/git-checkout.html @@ -274,7 +274,7 @@ git-checkout(1) Manual Page
git-checkout [-f] [-b <new_branch> [-l]] [-m] [<branch>] -git-checkout [-m] [<branch>] <paths>…
+git-checkout [<branch>] <paths>…

DESCRIPTION

@@ -353,11 +353,54 @@ and mark the resolved paths with git update-index.

Branch to checkout; may be any object ID that resolves to a - commit. Defaults to HEAD. + commit. Defaults to HEAD.

+

When this parameter names a non-branch (but still a valid commit object), +your HEAD becomes detached.

+

Detached HEAD

+
+

It is sometimes useful to be able to checkout a commit that is +not at the tip of one of your branches. The most obvious +example is to check out the commit at a tagged official release +point, like this:

+
+
+
$ git checkout v2.6.18
+
+

Earlier versions of git did not allow this and asked you to +create a temporary branch using -b option, but starting from +version 1.5.0, the above command detaches your HEAD from the +current branch and directly point at the commit named by the tag +(v2.6.18 in the above example).

+

You can use usual git commands while in this state. You can use +git-reset --hard $othercommit to further move around, for +example. You can make changes and create a new commit on top of +a detached HEAD. You can even create a merge by using git +merge $othercommit.

+

The state you are in while your HEAD is detached is not recorded +by any branch (which is natural --- you are not on any branch). +What this means is that you can discard your temporary commits +and merges by switching back to an existing branch (e.g. git +checkout master), and a later git prune or git gc would +garbage-collect them.

+

The command would refuse to switch back to make sure that you do +not discard your temporary state by mistake when your detached +HEAD is not pointed at by any existing ref. If you did want to +save your state (e.g. "I was interested in the fifth commit from +the top of master branch", or "I made two commits to fix minor +bugs while on a detached HEAD" — and if you do not want to lose +these facts), you can create a new branch and switch to it with +git checkout -b newbranch so that you can keep building on +that state, or tag it first so that you can come back to it +later and switch to the branch you wanted to switch to with git +tag that_state; git checkout master. On the other hand, if you +did want to discard the temporary state, you can give -f +option (e.g. git checkout -f master) to override this +behaviour.

+

EXAMPLES

    @@ -466,7 +509,7 @@ $ git update-index frotz
diff --git a/git-checkout.txt b/git-checkout.txt index fbdbadc74..c44a4a800 100644 --- a/git-checkout.txt +++ b/git-checkout.txt @@ -9,7 +9,7 @@ SYNOPSIS -------- [verse] 'git-checkout' [-f] [-b [-l]] [-m] [] -'git-checkout' [-m] [] ... +'git-checkout' [] ... DESCRIPTION ----------- @@ -63,7 +63,57 @@ and mark the resolved paths with `git update-index`. :: Branch to checkout; may be any object ID that resolves to a - commit. Defaults to HEAD. + commit. Defaults to HEAD. ++ +When this parameter names a non-branch (but still a valid commit object), +your HEAD becomes 'detached'. + + +Detached HEAD +------------- + +It is sometimes useful to be able to 'checkout' a commit that is +not at the tip of one of your branches. The most obvious +example is to check out the commit at a tagged official release +point, like this: + +------------ +$ git checkout v2.6.18 +------------ + +Earlier versions of git did not allow this and asked you to +create a temporary branch using `-b` option, but starting from +version 1.5.0, the above command 'detaches' your HEAD from the +current branch and directly point at the commit named by the tag +(`v2.6.18` in the above example). + +You can use usual git commands while in this state. You can use +`git-reset --hard $othercommit` to further move around, for +example. You can make changes and create a new commit on top of +a detached HEAD. You can even create a merge by using `git +merge $othercommit`. + +The state you are in while your HEAD is detached is not recorded +by any branch (which is natural --- you are not on any branch). +What this means is that you can discard your temporary commits +and merges by switching back to an existing branch (e.g. `git +checkout master`), and a later `git prune` or `git gc` would +garbage-collect them. + +The command would refuse to switch back to make sure that you do +not discard your temporary state by mistake when your detached +HEAD is not pointed at by any existing ref. If you did want to +save your state (e.g. "I was interested in the fifth commit from +the top of 'master' branch", or "I made two commits to fix minor +bugs while on a detached HEAD" -- and if you do not want to lose +these facts), you can create a new branch and switch to it with +`git checkout -b newbranch` so that you can keep building on +that state, or tag it first so that you can come back to it +later and switch to the branch you wanted to switch to with `git +tag that_state; git checkout master`. On the other hand, if you +did want to discard the temporary state, you can give `-f` +option (e.g. `git checkout -f master`) to override this +behaviour. EXAMPLES diff --git a/git-format-patch.html b/git-format-patch.html index 5442377a8..a5104ce5a 100644 --- a/git-format-patch.html +++ b/git-format-patch.html @@ -275,7 +275,7 @@ git-format-patch(1) Manual Page
git-format-patch [-n | -k] [-o <dir> | --stdout] [--attach] [--thread] [-s | --signoff] [--diff-options] [--start-number <n>] - [--in-reply-to=Message-Id] + [--in-reply-to=Message-Id] [--suffix=.<sfx>] <since>[..<until>]

DESCRIPTION

@@ -382,6 +382,20 @@ reference.

provide a new patch series.

+
+--suffix=.<sfx> +
+
+

+ Instead of using .txt as the suffix for generated + filenames, use specifed suffix. A common alternative is + --suffix=.patch. +

+

Note that you would need to include the leading dot . if you +want a filename like 0001-description-of-my-change.patch, and +the first letter does not have to be a dot. Leaving it empty would +not add any suffix.

+

CONFIGURATION

@@ -392,6 +406,11 @@ message in the repository configuration as follows:

headers = "Organization: git-foo\n"
+

You can specify default suffix used:

+
+
+
suffix = .patch
+

EXAMPLES

@@ -450,7 +469,7 @@ git-format-patch -M -B origin
diff --git a/git-format-patch.txt b/git-format-patch.txt index 67425dc03..23acb4752 100644 --- a/git-format-patch.txt +++ b/git-format-patch.txt @@ -11,7 +11,7 @@ SYNOPSIS [verse] 'git-format-patch' [-n | -k] [-o | --stdout] [--attach] [--thread] [-s | --signoff] [--diff-options] [--start-number ] - [--in-reply-to=Message-Id] + [--in-reply-to=Message-Id] [--suffix=.] [..] DESCRIPTION @@ -78,6 +78,16 @@ OPTIONS reply to the given Message-Id, which avoids breaking threads to provide a new patch series. +--suffix=.:: + Instead of using `.txt` as the suffix for generated + filenames, use specifed suffix. A common alternative is + `--suffix=.patch`. ++ +Note that you would need to include the leading dot `.` if you +want a filename like `0001-description-of-my-change.patch`, and +the first letter does not have to be a dot. Leaving it empty would +not add any suffix. + CONFIGURATION ------------- You can specify extra mail header lines to be added to each @@ -86,6 +96,11 @@ message in the repository configuration as follows: [format] headers = "Organization: git-foo\n" +You can specify default suffix used: + +[format] + suffix = .patch + EXAMPLES -------- diff --git a/git.html b/git.html index 901b19faa..d7710c40a 100644 --- a/git.html +++ b/git.html @@ -1760,9 +1760,9 @@ stupid. contemptible and despicable. simple. Take your pick from the

-

This is a stupid (but extremely fast) directory content manager. It -doesn't do a whole lot, but what it does do is track directory -contents efficiently.

+

This is a (not so) stupid but extremely fast directory content manager. +It doesn't do a whole lot at its core, but what it does do is track +directory contents efficiently.

There are two object abstractions: the "object database", and the "current directory cache" aka "index".

The Object Database

@@ -2285,7 +2285,7 @@ contributors on the git-list <git@vger.kernel.org>.

diff --git a/git.txt b/git.txt index 6a82803f3..a0bcef71d 100644 --- a/git.txt +++ b/git.txt @@ -699,7 +699,7 @@ other Discussion[[Discussion]] ------------------------ -include::README[] +include::core-intro.txt[] Authors ------- diff --git a/glossary.html b/glossary.html index 06658c055..ddae7d4c8 100644 --- a/glossary.html +++ b/glossary.html @@ -864,6 +864,21 @@ div.exampleblock-content {

+shallow repository +
+
+

+ A shallow repository has an incomplete + history some of whose commits have parents cauterized away (in other + words, git is told to pretend that these commits do not have the + parents, even though they are recorded in the commit object). This is sometimes useful when you are interested only in the + recent history of a project even though the real history recorded in the + upstream is much larger. A shallow repository + is created by giving —depth option to git-clone(1), and its + history can be later deepened with git-fetch(1). +

+
+
symref
@@ -984,7 +999,7 @@ the git-list <git@vger.kernel.org>.

diff --git a/glossary.txt b/glossary.txt index bc917bbac..d20eb6270 100644 --- a/glossary.txt +++ b/glossary.txt @@ -286,6 +286,18 @@ SCM:: SHA1:: Synonym for object name. +shallow repository:: + A shallow repository has an incomplete history some of + whose commits have parents cauterized away (in other + words, git is told to pretend that these commits do not + have the parents, even though they are recorded in the + commit object). This is sometimes useful when you are + interested only in the recent history of a project even + though the real history recorded in the upstream is + much larger. A shallow repository is created by giving + `--depth` option to gitlink:git-clone[1], and its + history can be later deepened with gitlink:git-fetch[1]. + symref:: Symbolic reference: instead of containing the SHA1 id itself, it is of the format 'ref: refs/some/thing' and when referenced, it diff --git a/repository-layout.html b/repository-layout.html index 106c4dc18..d7816df9c 100644 --- a/repository-layout.html +++ b/repository-layout.html @@ -291,6 +291,12 @@ outside world but sometimes useful for private repository.

  • +You also could have an incomplete but locally usable repository +by cloning shallowly. See 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 @@ -312,7 +318,7 @@ objects/[0-9a-f][0-9a-f] 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 - objects. + (or loose) objects.

    • @@ -402,6 +408,25 @@ refs/tags/name

    +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 + git-pack-refs(1). +

    +
    +
    HEAD
    @@ -417,6 +442,11 @@ HEAD 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 git-checkout(1) for +details.

    branches @@ -538,12 +568,22 @@ 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 git-clone(1) and git-fetch(1). +

    +
    diff --git a/repository-layout.txt b/repository-layout.txt index 0fdd36614..863cb6710 100644 --- a/repository-layout.txt +++ b/repository-layout.txt @@ -18,6 +18,8 @@ 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 gitlink: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 @@ -32,7 +34,7 @@ objects/[0-9a-f][0-9a-f]:: 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' - objects. + (or 'loose') objects. objects/pack:: Packs (files that store many object in compressed form, @@ -80,6 +82,15 @@ 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 + gitlink:git-pack-refs[1]. + HEAD:: A symref (see glossary) to the `refs/heads/` namespace describing the currently active branch. It does not mean @@ -91,6 +102,12 @@ HEAD:: '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 gitlink:git-checkout[1] for +details. branches:: A slightly deprecated way to store shorthands to be used @@ -156,3 +173,9 @@ logs/refs/heads/`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 gitlink:git-clone[1] and gitlink:git-fetch[1]. + -- 2.26.2