diff options
Diffstat (limited to 'third_party/git/Documentation/user-manual.txt')
| -rw-r--r-- | third_party/git/Documentation/user-manual.txt | 381 |
1 files changed, 247 insertions, 134 deletions
diff --git a/third_party/git/Documentation/user-manual.txt b/third_party/git/Documentation/user-manual.txt index 833652983fa6..8bce75b2cf2b 100644 --- a/third_party/git/Documentation/user-manual.txt +++ b/third_party/git/Documentation/user-manual.txt @@ -1,4 +1,5 @@ -= Git User Manual +Git User Manual +=============== Git is a fast distributed revision control system. @@ -40,10 +41,12 @@ complete. [[repositories-and-branches]] -== Repositories and Branches +Repositories and Branches +========================= [[how-to-get-a-git-repository]] -=== How to get a Git repository +How to get a Git repository +--------------------------- It will be useful to have a Git repository to experiment with as you read this manual. @@ -70,7 +73,8 @@ top-level directory named `.git`, which contains all the information about the history of the project. [[how-to-check-out]] -=== How to check out a different version of a project +How to check out a different version of a project +------------------------------------------------- Git is best thought of as a tool for storing the history of a collection of files. It stores the history as a compressed collection of @@ -147,7 +151,8 @@ with no way to find the history it used to point to; so use this command carefully. [[understanding-commits]] -=== Understanding History: Commits +Understanding History: Commits +------------------------------ Every change in the history of a project is represented by a commit. The linkgit:git-show[1] command shows the most recent commit on the @@ -197,7 +202,8 @@ history, including file data and directory contents, is stored in an object with a name that is a hash of its contents. [[understanding-reachability]] -==== Understanding history: commits, parents, and reachability +Understanding history: commits, parents, and reachability +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Every commit (except the very first commit in a project) also has a parent commit which shows what happened before this commit. @@ -221,7 +227,8 @@ that Y is a descendant of X, or that there is a chain of parents leading from commit Y to commit X. [[history-diagrams]] -==== Understanding history: History diagrams +Understanding history: History diagrams +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ We will sometimes represent Git history using diagrams like the one below. Commits are shown as "o", and the links between them with @@ -240,7 +247,8 @@ If we need to talk about a particular commit, the character "o" may be replaced with another letter or number. [[what-is-a-branch]] -==== Understanding history: What is a branch? +Understanding history: What is a branch? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ When we need to be precise, we will use the word "branch" to mean a line of development, and "branch head" (or just "head") to mean a reference @@ -253,7 +261,8 @@ However, when no confusion will result, we often just use the term "branch" both for branches and for branch heads. [[manipulating-branches]] -=== Manipulating branches +Manipulating branches +--------------------- Creating, deleting, and modifying branches is quick and easy; here's a summary of the commands: @@ -290,7 +299,8 @@ ref: refs/heads/master ------------------------------------------------ [[detached-head]] -=== Examining an old version without creating a new branch +Examining an old version without creating a new branch +------------------------------------------------------ The `git switch` command normally expects a branch head, but will also accept an arbitrary commit when invoked with --detach; for example, @@ -330,7 +340,8 @@ make up a name for the new branch. You can still create a new branch (or tag) for this version later if you decide to. [[examining-remote-branches]] -=== Examining branches from a remote repository +Examining branches from a remote repository +------------------------------------------- The "master" branch that was created at the time you cloned is a copy of the HEAD in the repository that you cloned from. That repository @@ -372,7 +383,8 @@ Note that the name "origin" is just the name that Git uses by default to refer to the repository that you cloned from. [[how-git-stores-references]] -=== Naming branches, tags, and other references +Naming branches, tags, and other references +------------------------------------------- Branches, remote-tracking branches, and tags are all references to commits. All references are named with a slash-separated path name @@ -401,7 +413,8 @@ references with the same shorthand name, see the "SPECIFYING REVISIONS" section of linkgit:gitrevisions[7]. [[Updating-a-repository-With-git-fetch]] -=== Updating a repository with git fetch +Updating a repository with git fetch +------------------------------------ After you clone a repository and commit a few changes of your own, you may wish to check the original repository for updates. @@ -412,7 +425,8 @@ repository. It will not touch any of your own branches--not even the "master" branch that was created for you on clone. [[fetching-branches]] -=== Fetching branches from other repositories +Fetching branches from other repositories +----------------------------------------- You can also track branches from repositories other than the one you cloned from, using linkgit:git-remote[1]: @@ -460,7 +474,8 @@ text editor. (See the "CONFIGURATION FILE" section of linkgit:git-config[1] for details.) [[exploring-git-history]] -== Exploring Git history +Exploring Git history +===================== Git is best thought of as a tool for storing the history of a collection of files. It does this by storing compressed snapshots of @@ -474,7 +489,8 @@ We start with one specialized tool that is useful for finding the commit that introduced a bug into a project. [[using-bisect]] -=== How to use bisect to find a regression +How to use bisect to find a regression +-------------------------------------- Suppose version 2.6.18 of your project worked, but the version at "master" crashes. Sometimes the best way to find the cause of such a @@ -556,7 +572,8 @@ linkgit:git-bisect[1] for more information about this and other `git bisect` features. [[naming-commits]] -=== Naming commits +Naming commits +-------------- We have seen several ways of naming commits already: @@ -620,7 +637,8 @@ e05db0fd4f31dde7005f075a84f96b360d05984b ------------------------------------------------- [[creating-tags]] -=== Creating tags +Creating tags +------------- We can also create a tag to refer to a particular commit; after running @@ -637,7 +655,8 @@ should create a tag object instead; see the linkgit:git-tag[1] man page for details. [[browsing-revisions]] -=== Browsing revisions +Browsing revisions +------------------ The linkgit:git-log[1] command can show lists of commits. On its own, it shows all commits reachable from the parent commit; but you @@ -678,7 +697,8 @@ multiple independent lines of development, the particular order that commits are listed in may be somewhat arbitrary. [[generating-diffs]] -=== Generating diffs +Generating diffs +---------------- You can generate diffs between any two versions using linkgit:git-diff[1]: @@ -706,7 +726,8 @@ will generate a file with a patch for each commit reachable from test but not from master. [[viewing-old-file-versions]] -=== Viewing old file versions +Viewing old file versions +------------------------- You can always view an old version of a file by just checking out the correct revision first. But sometimes it is more convenient to be @@ -721,10 +742,12 @@ Before the colon may be anything that names a commit, and after it may be any path to a file tracked by Git. [[history-examples]] -=== Examples +Examples +-------- [[counting-commits-on-a-branch]] -==== Counting the number of commits on a branch +Counting the number of commits on a branch +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Suppose you want to know how many commits you've made on `mybranch` since it diverged from `origin`: @@ -742,7 +765,8 @@ $ git rev-list origin..mybranch | wc -l ------------------------------------------------- [[checking-for-equal-branches]] -==== Check whether two branches point at the same history +Check whether two branches point at the same history +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Suppose you want to check whether two branches point at the same point in history. @@ -774,7 +798,8 @@ $ git log origin...master will return no commits when the two branches are equal. [[finding-tagged-descendants]] -==== Find first tagged version including a given fix +Find first tagged version including a given fix +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Suppose you know that the commit e05db0fd fixed a certain problem. You'd like to find the earliest tagged release that contains that @@ -858,7 +883,8 @@ shows that e05db0fd is reachable from itself, from v1.5.0-rc1, and from v1.5.0-rc2, and not from v1.5.0-rc0. [[showing-commits-unique-to-a-branch]] -==== Showing commits unique to a given branch +Showing commits unique to a given branch +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Suppose you would like to see all the commits reachable from the branch head named `master` but not from any other head in your repository. @@ -905,7 +931,8 @@ $ gitk $( git show-ref --heads ) --not $( git show-ref --tags ) syntax such as `--not`.) [[making-a-release]] -==== Creating a changelog and tarball for a software release +Creating a changelog and tarball for a software release +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The linkgit:git-archive[1] command can create a tar or zip archive from any version of a project; for example: @@ -956,7 +983,8 @@ and then he just cut-and-pastes the output commands after verifying that they look OK. [[Finding-commits-With-given-Content]] -==== Finding commits referencing a file with given content +Finding commits referencing a file with given content +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Somebody hands you a copy of a file, and asks which commits modified a file such that it contained the given content either before or after the @@ -972,10 +1000,12 @@ student. The linkgit:git-log[1], linkgit:git-diff-tree[1], and linkgit:git-hash-object[1] man pages may prove helpful. [[Developing-With-git]] -== Developing with Git +Developing with Git +=================== [[telling-git-your-name]] -=== Telling Git your name +Telling Git your name +--------------------- Before creating any commits, you should introduce yourself to Git. The easiest way to do so is to use linkgit:git-config[1]: @@ -1000,7 +1030,8 @@ also edit it with your favorite editor. [[creating-a-new-repository]] -=== Creating a new repository +Creating a new repository +------------------------- Creating a new repository from scratch is very easy: @@ -1021,7 +1052,8 @@ $ git commit ------------------------------------------------- [[how-to-make-a-commit]] -=== How to make a commit +How to make a commit +-------------------- Creating a new commit takes three steps: @@ -1116,7 +1148,8 @@ for inclusion in the index (by right-clicking on the diff hunk and choosing "Stage Hunk For Commit"). [[creating-good-commit-messages]] -=== Creating good commit messages +Creating good commit messages +----------------------------- Though not required, it's a good idea to begin the commit message with a single short (less than 50 character) line summarizing the @@ -1129,7 +1162,8 @@ rest of the commit in the body. [[ignoring-files]] -=== Ignoring files +Ignoring files +-------------- A project will often generate files that you do 'not' want to track with Git. This typically includes files generated by a build process or temporary @@ -1171,7 +1205,8 @@ Some Git commands can also take exclude patterns directly on the command line. See linkgit:gitignore[5] for the details. [[how-to-merge]] -=== How to merge +How to merge +------------ You can rejoin two diverging branches of development using linkgit:git-merge[1]: @@ -1219,7 +1254,8 @@ has two parents, one pointing to the top of the current branch, and one to the top of the other branch. [[resolving-a-merge]] -=== Resolving a merge +Resolving a merge +----------------- When a merge isn't resolved automatically, Git leaves the index and the working tree in a special state that gives you all the @@ -1261,7 +1297,8 @@ The above is all you need to know to resolve a simple merge. But Git also provides more information to help resolve conflicts: [[conflict-resolution]] -==== Getting conflict-resolution help during a merge +Getting conflict-resolution help during a merge +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ All of the changes that Git was able to merge automatically are already added to the index file, so linkgit:git-diff[1] shows only @@ -1364,7 +1401,8 @@ the different stages of that file will be "collapsed", after which `git diff` will (by default) no longer show diffs for that file. [[undoing-a-merge]] -=== Undoing a merge +Undoing a merge +--------------- If you get stuck and decide to just give up and throw the whole mess away, you can always return to the pre-merge state with @@ -1385,7 +1423,8 @@ itself have been merged into another branch, as doing so may confuse further merges. [[fast-forwards]] -=== Fast-forward merges +Fast-forward merges +------------------- There is one special case not mentioned above, which is treated differently. Normally, a merge results in a merge commit, with two @@ -1399,7 +1438,8 @@ to point at the head of the merged-in branch, without any new commits being created. [[fixing-mistakes]] -=== Fixing mistakes +Fixing mistakes +--------------- If you've messed up the working tree, but haven't yet committed your mistake, you can return the entire working tree to the last committed @@ -1423,7 +1463,8 @@ fundamentally different ways to fix the problem: a branch that has had its history changed. [[reverting-a-commit]] -==== Fixing a mistake with a new commit +Fixing a mistake with a new commit +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Creating a new commit that reverts an earlier change is very easy; just pass the linkgit:git-revert[1] command a reference to the bad @@ -1449,7 +1490,8 @@ conflicts manually, just as in the case of <<resolving-a-merge, resolving a merge>>. [[fixing-a-mistake-by-rewriting-history]] -==== Fixing a mistake by rewriting history +Fixing a mistake by rewriting history +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If the problematic commit is the most recent commit, and you have not yet made that commit public, then you may just @@ -1476,7 +1518,8 @@ this is an advanced topic to be left for <<cleaning-up-history,another chapter>>. [[checkout-of-path]] -==== Checking out an old version of a file +Checking out an old version of a file +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In the process of undoing a previous bad change, you may find it useful to check out an older version of a particular file using @@ -1500,7 +1543,8 @@ $ git show HEAD^:path/to/file which will display the given version of the file. [[interrupted-work]] -==== Temporarily setting aside work in progress +Temporarily setting aside work in progress +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ While you are in the middle of working on something complicated, you find an unrelated but obvious and trivial bug. You would like to fix it @@ -1531,7 +1575,8 @@ $ git stash pop [[ensuring-good-performance]] -=== Ensuring good performance +Ensuring good performance +------------------------- On large repositories, Git depends on compression to keep the history information from taking up too much space on disk or in memory. Some @@ -1542,10 +1587,12 @@ to avoid automatic compression kicking in when it is not convenient. [[ensuring-reliability]] -=== Ensuring reliability +Ensuring reliability +-------------------- [[checking-for-corruption]] -==== Checking the repository for corruption +Checking the repository for corruption +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The linkgit:git-fsck[1] command runs a number of self-consistency checks on the repository, and reports on any problems. This may take some @@ -1571,10 +1618,12 @@ You can run `git fsck --no-dangling` to suppress these messages, and still view real errors. [[recovering-lost-changes]] -==== Recovering lost changes +Recovering lost changes +~~~~~~~~~~~~~~~~~~~~~~~ [[reflogs]] -===== Reflogs +Reflogs +^^^^^^^ Say you modify a branch with <<fixing-mistakes,`git reset --hard`>>, and then realize that the branch was the only reference you had to @@ -1621,7 +1670,8 @@ same project, the reflog history is not shared: it tells you only about how the branches in your local repository have changed over time. [[dangling-object-recovery]] -===== Examining dangling objects +Examining dangling objects +^^^^^^^^^^^^^^^^^^^^^^^^^^ In some situations the reflog may not be able to save you. For example, suppose you delete a branch, then realize you need the history it @@ -1665,10 +1715,12 @@ dangling objects can arise in other situations. [[sharing-development]] -== Sharing development with others +Sharing development with others +=============================== [[getting-updates-With-git-pull]] -=== Getting updates with git pull +Getting updates with git pull +----------------------------- After you clone a repository and commit a few changes of your own, you may wish to check the original repository for updates and merge them @@ -1731,7 +1783,8 @@ $ git merge branch are roughly equivalent. [[submitting-patches]] -=== Submitting patches to a project +Submitting patches to a project +------------------------------- If you just have a few changes, the simplest way to submit them may just be to send them as patches in email: @@ -1759,7 +1812,8 @@ Consult the mailing list for your project first to determine their requirements for submitting patches. [[importing-patches]] -=== Importing patches to a project +Importing patches to a project +------------------------------ Git also provides a tool called linkgit:git-am[1] (am stands for "apply mailbox"), for importing such an emailed series of patches. @@ -1791,7 +1845,8 @@ the original mailbox, with authorship and commit log message each taken from the message containing each patch. [[public-repositories]] -=== Public Git repositories +Public Git repositories +----------------------- Another way to submit changes to a project is to tell the maintainer of that project to pull the changes from your repository using @@ -1831,22 +1886,21 @@ pull from that repository. So the flow of changes, in a situation where there is one other developer with a public repository, looks like this: -.... - you push -your personal repo ------------------> your public repo - ^ | - | | - | you pull | they pull - | | - | | - | they push V -their public repo <------------------- their repo -.... + you push + your personal repo ------------------> your public repo + ^ | + | | + | you pull | they pull + | | + | | + | they push V + their public repo <------------------- their repo We explain how to do this in the following sections. [[setting-up-a-public-repository]] -==== Setting up a public repository +Setting up a public repository +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Assume your personal repository is in the directory `~/proj`. We first create a new clone of the repository and tell `git daemon` that it @@ -1866,7 +1920,8 @@ public repository. You can use scp, rsync, or whatever is most convenient. [[exporting-via-git]] -==== Exporting a Git repository via the Git protocol +Exporting a Git repository via the Git protocol +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This is the preferred method. @@ -1887,7 +1942,8 @@ linkgit:git-daemon[1] man page for details. (See especially the examples section.) [[exporting-via-http]] -==== Exporting a git repository via HTTP +Exporting a git repository via HTTP +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The Git protocol gives better performance and reliability, but on a host with a web server set up, HTTP exports may be simpler to set up. @@ -1919,7 +1975,8 @@ for a slightly more sophisticated setup using WebDAV which also allows pushing over HTTP.) [[pushing-changes-to-a-public-repository]] -==== Pushing changes to a public repository +Pushing changes to a public repository +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Note that the two techniques outlined above (exporting via <<exporting-via-http,http>> or <<exporting-via-git,git>>) allow other @@ -1978,7 +2035,8 @@ See the explanations of the `remote.<name>.url`, linkgit:git-config[1] for details. [[forcing-push]] -==== What to do when a push fails +What to do when a push fails +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If a push would not result in a <<fast-forwards,fast-forward>> of the remote branch, then it will fail with an error like: @@ -2032,7 +2090,8 @@ pull, or by a fetch followed by a rebase; see the linkgit:gitcvs-migration[7] for more. [[setting-up-a-shared-repository]] -==== Setting up a shared repository +Setting up a shared repository +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Another way to collaborate is by using a model similar to that commonly used in CVS, where several developers with special rights @@ -2062,7 +2121,8 @@ advantages over the central shared repository: "out". [[setting-up-gitweb]] -==== Allowing web browsing of a repository +Allowing web browsing of a repository +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The gitweb cgi script provides users an easy way to browse your project's revisions, file contents and logs without having to install @@ -2078,7 +2138,8 @@ linkgit:gitweb[1] for instructions on details setting up a permanent installation with a CGI or Perl capable server. [[how-to-get-a-git-repository-with-minimal-history]] -=== How to get a Git repository with minimal history +How to get a Git repository with minimal history +------------------------------------------------ A <<def_shallow_clone,shallow clone>>, with its truncated history, is useful when one is interested only in recent history @@ -2097,10 +2158,12 @@ have to result in huge conflicts. This limitation may make such a repository unsuitable to be used in merge based workflows. [[sharing-development-examples]] -=== Examples +Examples +-------- [[maintaining-topic-branches]] -==== Maintaining topic branches for a Linux subsystem maintainer +Maintaining topic branches for a Linux subsystem maintainer +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This describes how Tony Luck uses Git in his role as maintainer of the IA64 architecture for the Linux kernel. @@ -2396,7 +2459,8 @@ done [[cleaning-up-history]] -== Rewriting history and maintaining patch series +Rewriting history and maintaining patch series +============================================== Normally commits are only added to a project, never taken away or replaced. Git is designed with this assumption, and violating it will @@ -2406,7 +2470,8 @@ However, there is a situation in which it can be useful to violate this assumption. [[patch-series]] -=== Creating the perfect patch series +Creating the perfect patch series +--------------------------------- Suppose you are a contributor to a large project, and you want to add a complicated feature, and to present it to the other developers in a way @@ -2438,7 +2503,8 @@ use them, and then explain some of the problems that can arise because you are rewriting history. [[using-git-rebase]] -=== Keeping a patch series up to date using git rebase +Keeping a patch series up to date using git rebase +-------------------------------------------------- Suppose that you create a branch `mywork` on a remote-tracking branch `origin`, and create some commits on top of it: @@ -2525,7 +2591,8 @@ the rebase. See <<interactive-rebase>> for details, and <<reordering-patch-series>> for alternatives. [[rewriting-one-commit]] -=== Rewriting a single commit +Rewriting a single commit +------------------------- We saw in <<fixing-a-mistake-by-rewriting-history>> that you can replace the most recent commit using @@ -2543,7 +2610,8 @@ If you need to amend commits from deeper in your history, you can use <<interactive-rebase,interactive rebase's `edit` instruction>>. [[reordering-patch-series]] -=== Reordering or selecting from a patch series +Reordering or selecting from a patch series +------------------------------------------- Sometimes you want to edit a commit deeper in your history. One approach is to use `git format-patch` to create a series of patches @@ -2562,7 +2630,8 @@ $ git am *.patch ------------------------------------------------- [[interactive-rebase]] -=== Using interactive rebases +Using interactive rebases +------------------------- You can also edit a patch series with an interactive rebase. This is the same as <<reordering-patch-series,reordering a patch series using @@ -2619,14 +2688,16 @@ For a more detailed discussion of the procedure and additional tips, see the "INTERACTIVE MODE" section of linkgit:git-rebase[1]. [[patch-series-tools]] -=== Other tools +Other tools +----------- There are numerous other tools, such as StGit, which exist for the purpose of maintaining a patch series. These are outside of the scope of this manual. [[problems-With-rewriting-history]] -=== Problems with rewriting history +Problems with rewriting history +------------------------------- The primary problem with rewriting the history of a branch has to do with merging. Suppose somebody fetches your branch and merges it into @@ -2674,7 +2745,8 @@ For true distributed development that supports proper merging, published branches should never be rewritten. [[bisect-merges]] -=== Why bisecting merge commits can be harder than bisecting linear history +Why bisecting merge commits can be harder than bisecting linear history +----------------------------------------------------------------------- The linkgit:git-bisect[1] command correctly handles history that includes merge commits. However, when the commit that it finds is a @@ -2739,10 +2811,12 @@ linear by rebasing against the latest upstream version before publishing. [[advanced-branch-management]] -== Advanced branch management +Advanced branch management +========================== [[fetching-individual-branches]] -=== Fetching individual branches +Fetching individual branches +---------------------------- Instead of using linkgit:git-remote[1], you can also choose just to update one branch at a time, and to store it locally under an @@ -2770,7 +2844,8 @@ already have a branch named example-master, it will attempt to master branch. In more detail: [[fetch-fast-forwards]] -=== git fetch and fast-forwards +git fetch and fast-forwards +--------------------------- In the previous example, when updating an existing branch, `git fetch` checks to make sure that the most recent commit on the remote @@ -2807,7 +2882,8 @@ unless you've already created a reference of your own pointing to them. [[forcing-fetch]] -=== Forcing git fetch to do non-fast-forward updates +Forcing git fetch to do non-fast-forward updates +------------------------------------------------ If git fetch fails because the new head of a branch is not a descendant of the old head, you may force the update with: @@ -2827,7 +2903,8 @@ Be aware that commits that the old version of example/master pointed at may be lost, as we saw in the previous section. [[remote-branch-configuration]] -=== Configuring remote-tracking branches +Configuring remote-tracking branches +------------------------------------ We saw above that `origin` is just a shortcut to refer to the repository that you originally cloned from. This information is @@ -2878,7 +2955,8 @@ the refspec syntax. [[git-concepts]] -== Git concepts +Git concepts +============ Git is built on a small number of simple but powerful ideas. While it is possible to get things done without understanding them, you will find @@ -2888,7 +2966,8 @@ We start with the most important, the <<def_object_database,object database>> and the <<def_index,index>>. [[the-object-database]] -=== The Object Database +The Object Database +------------------- We already saw in <<understanding-commits>> that all commits are stored @@ -2932,7 +3011,8 @@ There are four different types of objects: "blob", "tree", "commit", and The object types in some more detail: [[commit-object]] -==== Commit Object +Commit Object +~~~~~~~~~~~~~ The "commit" object links a physical state of a tree with a description of how we got there and why. Use the `--pretty=raw` option to @@ -2984,7 +3064,8 @@ commit whose parent is normally the current HEAD, and whose tree is taken from the content currently stored in the index. [[tree-object]] -==== Tree Object +Tree Object +~~~~~~~~~~~ The ever-versatile linkgit:git-show[1] command can also be used to examine tree objects, but linkgit:git-ls-tree[1] will give you more @@ -3023,7 +3104,8 @@ Note that the files all have mode 644 or 755: Git actually only pays attention to the executable bit. [[blob-object]] -==== Blob Object +Blob Object +~~~~~~~~~~~ You can use linkgit:git-show[1] to examine the contents of a blob; take, for example, the blob in the entry for `COPYING` from the tree above: @@ -3052,7 +3134,8 @@ sometimes be useful for browsing the contents of a tree that is not currently checked out. [[trust]] -==== Trust +Trust +~~~~~ If you receive the SHA-1 name of a blob from one source, and its contents from another (possibly untrusted) source, you can still trust that those @@ -3081,7 +3164,8 @@ like GPG/PGP. To assist in this, Git also provides the tag object... [[tag-object]] -==== Tag Object +Tag Object +~~~~~~~~~~ A tag object contains an object, object type, tag name, the name of the person ("tagger") who created the tag, and a message, which may contain @@ -3110,7 +3194,8 @@ objects. (Note that linkgit:git-tag[1] can also be used to create references whose names begin with `refs/tags/`). [[pack-files]] -==== How Git stores objects efficiently: pack files +How Git stores objects efficiently: pack files +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Newly created objects are initially created in a file named after the object's SHA-1 hash (stored in `.git/objects`). @@ -3168,7 +3253,8 @@ The linkgit:git-gc[1] command performs packing, pruning, and more for you, so is normally the only high-level command you need. [[dangling-objects]] -==== Dangling objects +Dangling objects +~~~~~~~~~~~~~~~~ The linkgit:git-fsck[1] command will sometimes complain about dangling objects. They are not a problem. @@ -3248,7 +3334,8 @@ don't want to do that while the filesystem is mounted. accesses to a repository but you might receive confusing or scary messages.) [[recovering-from-repository-corruption]] -==== Recovering from repository corruption +Recovering from repository corruption +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ By design, Git treats data trusted to it with caution. However, even in the absence of bugs in Git itself, it is still possible that hardware or @@ -3365,7 +3452,8 @@ whole thing. It's up to you--Git does *have* a lot of information, it is just missing one particular blob version. [[the-index]] -=== The index +The index +--------- The index is a binary file (generally kept in `.git/index`) containing a sorted list of path names, each with permissions and the SHA-1 of a blob @@ -3423,7 +3511,8 @@ If you blow the index away entirely, you generally haven't lost any information as long as you have the name of the tree that it described. [[submodules]] -== Submodules +Submodules +========== Large projects are often composed of smaller, self-contained modules. For example, an embedded Linux distribution's source tree would include every @@ -3609,8 +3698,8 @@ $ git push You have to run `git submodule update` after `git pull` if you want to update submodules, too. -[[pitfalls-with-submodules]] -=== Pitfalls with submodules +Pitfalls with submodules +------------------------ Always publish the submodule change before publishing the change to the superproject that references it. If you forget to publish the submodule change, @@ -3679,7 +3768,8 @@ submodule update` will not overwrite them. Instead, you get the usual warning about not being able switch from a dirty branch. [[low-level-operations]] -== Low-level Git operations +Low-level Git operations +======================== Many of the higher-level commands were originally implemented as shell scripts using a smaller core of low-level Git commands. These can still @@ -3687,7 +3777,8 @@ be useful when doing unusual things with Git, or just as a way to understand its inner workings. [[object-manipulation]] -=== Object access and manipulation +Object access and manipulation +------------------------------ The linkgit:git-cat-file[1] command can show the contents of any object, though the higher-level linkgit:git-show[1] is usually more useful. @@ -3704,7 +3795,8 @@ verified by linkgit:git-verify-tag[1], though it is normally simpler to use linkgit:git-tag[1] for both. [[the-workflow]] -=== The Workflow +The Workflow +------------ High-level operations such as linkgit:git-commit[1] and linkgit:git-restore[1] work by moving data @@ -3719,7 +3811,8 @@ the database or the working directory. Thus there are four main combinations: [[working-directory-to-index]] -==== working directory -> index +working directory -> index +~~~~~~~~~~~~~~~~~~~~~~~~~~ The linkgit:git-update-index[1] command updates the index with information from the working directory. You generally update the @@ -3755,7 +3848,8 @@ The previously introduced linkgit:git-add[1] is just a wrapper for linkgit:git-update-index[1]. [[index-to-object-database]] -==== index -> object database +index -> object database +~~~~~~~~~~~~~~~~~~~~~~~~ You write your current index file to a "tree" object with the program @@ -3770,7 +3864,8 @@ use that tree to re-generate the index at any time by going in the other direction: [[object-database-to-index]] -==== object database -> index +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 @@ -3786,7 +3881,8 @@ earlier. However, that is only your 'index' file: your working directory contents have not been modified. [[index-to-working-directory]] -==== index -> working directory +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 @@ -3815,7 +3911,8 @@ Finally, there are a few odds and ends which are not purely moving from one representation to the other: [[tying-it-all-together]] -==== Tying it all together +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 @@ -3889,7 +3986,8 @@ Here is a picture that illustrates how various pieces fit together: [[examining-the-data]] -=== Examining the data +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 @@ -3924,7 +4022,8 @@ $ git cat-file commit HEAD to see what the top commit was. [[merging-multiple-trees]] -=== Merging multiple trees +Merging multiple trees +---------------------- Git can help you perform a three-way merge, which can in turn be used for a many-way merge by repeating the merge procedure several @@ -3974,7 +4073,8 @@ index file, and you can just write the result out with [[merging-multiple-trees-2]] -=== Merging multiple trees, continued +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 @@ -4044,13 +4144,15 @@ $ git merge-index git-merge-one-file hello.c and that is what higher level `git merge -s resolve` is implemented with. [[hacking-git]] -== Hacking Git +Hacking Git +=========== This chapter covers internal details of the Git implementation which probably only Git developers need to understand. [[object-details]] -=== Object storage format +Object storage format +--------------------- All objects have a statically determined "type" which identifies the format of the object (i.e. how it is used, and how it can refer to other @@ -4080,7 +4182,8 @@ of all objects, and verifies their internal consistency (in addition to just verifying their superficial consistency through the hash). [[birdview-on-the-source-code]] -=== A birds-eye view of Git's source code +A birds-eye view of Git's source code +------------------------------------- It is not always easy for new developers to find their way through Git's source code. This section gives you a little guidance to show where to @@ -4289,22 +4392,25 @@ You see, Git is actually the best tool to find out about the source of Git itself! [[glossary]] -== Git Glossary +Git Glossary +============ [[git-explained]] -=== Git explained +Git explained +------------- include::glossary-content.txt[] [[git-quick-start]] -[appendix] -== Git Quick Reference +Appendix A: Git Quick Reference +=============================== This is a quick summary of the major commands; the previous chapters explain how these work in more detail. [[quick-creating-a-new-repository]] -=== Creating a new repository +Creating a new repository +------------------------- From a tarball: @@ -4325,7 +4431,8 @@ $ cd project ----------------------------------------------- [[managing-branches]] -=== Managing branches +Managing branches +----------------- ----------------------------------------------- $ git branch # list all local branches in this repo @@ -4389,7 +4496,8 @@ $ git branch -r # list all remote branches [[exploring-history]] -=== Exploring history +Exploring history +----------------- ----------------------------------------------- $ gitk # visualize and browse history @@ -4424,7 +4532,8 @@ $ git bisect bad # if this revision is bad. ----------------------------------------------- [[making-changes]] -=== Making changes +Making changes +-------------- Make sure Git knows who to blame: @@ -4454,7 +4563,8 @@ $ git commit -a # use latest content of all tracked files ----------------------------------------------- [[merging]] -=== Merging +Merging +------- ----------------------------------------------- $ git merge test # merge branch "test" into the current branch @@ -4464,7 +4574,8 @@ $ git pull . test # equivalent to git merge test ----------------------------------------------- [[sharing-your-changes]] -=== Sharing your changes +Sharing your changes +-------------------- Importing or exporting patches: @@ -4509,7 +4620,8 @@ $ git push example test ----------------------------------------------- [[repository-maintenance]] -=== Repository maintenance +Repository maintenance +---------------------- Check for corruption: @@ -4525,11 +4637,12 @@ $ git gc [[todo]] -[appendix] -== Notes and todo list for this manual +Appendix B: Notes and todo list for this manual +=============================================== [[todo-list]] -=== Todo list +Todo list +--------- This is a work in progress. @@ -4574,5 +4687,5 @@ Write a chapter on using plumbing and writing scripts. Alternates, clone -reference, etc. More on recovery from repository corruption. See: - https://lore.kernel.org/git/Pine.LNX.4.64.0702272039540.12485@woody.linux-foundation.org/ - https://lore.kernel.org/git/Pine.LNX.4.64.0702141033400.3604@woody.linux-foundation.org/ + http://marc.info/?l=git&m=117263864820799&w=2 + http://marc.info/?l=git&m=117147855503798&w=2 |