X-Git-Url: https://asedeno.scripts.mit.edu/gitweb/?a=blobdiff_plain;f=Documentation%2Fuser-manual.txt;h=2e8c050bb126f8efaf292c111a233dd75a5ef814;hb=a115daff12d8d26975ff15a4278a212df2c8c70b;hp=773ed36640b3b40263241372a16803f6d4007945;hpb=99eaefdd32f25a6b76b2bd52bb253e19a4a3cad4;p=git.git diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index 773ed3664..2e8c050bb 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -27,7 +27,7 @@ $ man git-clone See also <> for a brief overview of git commands, without any explanation. -Also, see <> for ways that you can help make this manual more +Finally, see <> for ways that you can help make this manual more complete. @@ -42,10 +42,9 @@ How to get a git repository It will be useful to have a git repository to experiment with as you read this manual. -The best way to get one is by using the gitlink:git-clone[1] command -to download a copy of an existing repository for a project that you -are interested in. If you don't already have a project in mind, here -are some interesting examples: +The best way to get one is by using the gitlink:git-clone[1] command to +download a copy of an existing repository. If you don't already have a +project in mind, here are some interesting examples: ------------------------------------------------ # git itself (approx. 10MB download): @@ -63,21 +62,18 @@ directory, you will see that it contains a copy of the project files, together with a special top-level directory named ".git", which contains all the information about the history of the project. -In most of the following, examples will be taken from one of the two -repositories above. - [[how-to-check-out]] 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 interrelated snapshots (versions) of the project's -contents. +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 +interrelated snapshots of the project's contents. In git each such +version is called a <>. A single git repository may contain multiple branches. It keeps track of them by keeping a list of <> which reference the -latest version on each branch; the gitlink:git-branch[1] command shows +latest commit on each branch; the gitlink:git-branch[1] command shows you the list of branch heads: ------------------------------------------------ @@ -149,32 +145,27 @@ current branch: ------------------------------------------------ $ git show -commit 2b5f6dcce5bf94b9b119e9ed8d537098ec61c3d2 -Author: Jamal Hadi Salim -Date: Sat Dec 2 22:22:25 2006 -0800 - - [XFRM]: Fix aevent structuring to be more complete. - - aevents can not uniquely identify an SA. We break the ABI with this - patch, but consensus is that since it is not yet utilized by any - (known) application then it is fine (better do it now than later). - - Signed-off-by: Jamal Hadi Salim - Signed-off-by: David S. Miller - -diff --git a/Documentation/networking/xfrm_sync.txt b/Documentation/networking/xfrm_sync.txt -index 8be626f..d7aac9d 100644 ---- a/Documentation/networking/xfrm_sync.txt -+++ b/Documentation/networking/xfrm_sync.txt -@@ -47,10 +47,13 @@ aevent_id structure looks like: +commit 17cf781661e6d38f737f15f53ab552f1e95960d7 +Author: Linus Torvalds +Date: Tue Apr 19 14:11:06 2005 -0700 + + Remove duplicate getenv(DB_ENVIRONMENT) call + + Noted by Tony Luck. + +diff --git a/init-db.c b/init-db.c +index 65898fa..b002dc6 100644 +--- a/init-db.c ++++ b/init-db.c +@@ -7,7 +7,7 @@ - struct xfrm_aevent_id { - struct xfrm_usersa_id sa_id; -+ xfrm_address_t saddr; - __u32 flags; -+ __u32 reqid; - }; -... + int main(int argc, char **argv) + { +- char *sha1_dir = getenv(DB_ENVIRONMENT), *path; ++ char *sha1_dir, *path; + int len, i; + + if (mkdir(".git", 0755) < 0) { ------------------------------------------------ As you can see, a commit shows who made the latest change, what they @@ -830,6 +821,54 @@ available Which shows that e05db0fd is reachable from itself, from v1.5.0-rc1, and from v1.5.0-rc2, but not from v1.5.0-rc0. +[[showing-commits-unique-to-a-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. + +We can list all the heads in this repository with +gitlink:git-show-ref[1]: + +------------------------------------------------- +$ git show-ref --heads +bf62196b5e363d73353a9dcf094c59595f3153b7 refs/heads/core-tutorial +db768d5504c1bb46f63ee9d6e1772bd047e05bf9 refs/heads/maint +a07157ac624b2524a059a3414e99f6f44bebc1e7 refs/heads/master +24dbc180ea14dc1aebe09f14c8ecf32010690627 refs/heads/tutorial-2 +1e87486ae06626c2f31eaa63d26fc0fd646c8af2 refs/heads/tutorial-fixes +------------------------------------------------- + +We can get just the branch-head names, and remove "master", with +the help of the standard utilities cut and grep: + +------------------------------------------------- +$ git show-ref --heads | cut -d' ' -f2 | grep -v '^refs/heads/master' +refs/heads/core-tutorial +refs/heads/maint +refs/heads/tutorial-2 +refs/heads/tutorial-fixes +------------------------------------------------- + +And then we can ask to see all the commits reachable from master +but not from these other heads: + +------------------------------------------------- +$ gitk master --not $( git show-ref --heads | cut -d' ' -f2 | + grep -v '^refs/heads/master' ) +------------------------------------------------- + +Obviously, endless variations are possible; for example, to see all +commits reachable from some head but not from any tag in the repository: + +------------------------------------------------- +$ gitk $( git show-ref --heads ) --not $( git show-ref --tags ) +------------------------------------------------- + +(See gitlink:git-rev-parse[1] for explanations of commit-selecting +syntax such as `--not`.) + [[making-a-release]] Creating a changelog and tarball for a software release ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -842,7 +881,7 @@ $ git archive --format=tar --prefix=project/ HEAD | gzip >latest.tar.gz ------------------------------------------------- will use HEAD to produce a tar archive in which each filename is -preceded by "prefix/". +preceded by "project/". If you're releasing a new version of a software project, you may want to simultaneously make a changelog to include in the release @@ -873,6 +912,23 @@ echo "git diff --stat --summary -M v$last v$new > ../diffstat-$new" and then he just cut-and-pastes the output commands after verifying that they look OK. +[[Finding-comments-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 +commit. You can find out with this: + +------------------------------------------------- +$ git log --raw -r --abbrev=40 --pretty=oneline -- filename | + grep -B 1 `git hash-object filename` +------------------------------------------------- + +Figuring out why this works is left as an exercise to the (advanced) +student. The gitlink:git-log[1], gitlink:git-diff-tree[1], and +gitlink:git-hash-object[1] man pages may prove helpful. + [[Developing-with-git]] Developing with git =================== @@ -1025,6 +1081,48 @@ description. Tools that turn commits into email, for example, use the first line on the Subject line and the rest of the commit in the body. +[[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 +backup files made by your editor. Of course, 'not' tracking files with git +is just a matter of 'not' calling "`git add`" on them. But it quickly becomes +annoying to have these untracked files lying around; e.g. they make +"`git add .`" and "`git commit -a`" practically useless, and they keep +showing up in the output of "`git status`". + +You can tell git to ignore certain files by creating a file called .gitignore +in the top level of your working directory, with contents such as: + +------------------------------------------------- +# Lines starting with '#' are considered comments. +# Ignore any file named foo.txt. +foo.txt +# Ignore (generated) html files, +*.html +# except foo.html which is maintained by hand. +!foo.html +# Ignore objects and archives. +*.[oa] +------------------------------------------------- + +See gitlink:gitignore[5] for a detailed explanation of the syntax. You can +also place .gitignore files in other directories in your working tree, and they +will apply to those directories and their subdirectories. The `.gitignore` +files can be added to your repository like any other files (just run `git add +.gitignore` and `git commit`, as usual), which is convenient when the exclude +patterns (such as patterns matching build output files) would also make sense +for other users who clone your repository. + +If you wish the exclude patterns to affect only certain repositories +(instead of every repository for a given project), you may instead put +them in a file in your repository named .git/info/exclude, or in any file +specified by the `core.excludesfile` configuration variable. Some git +commands can also take exclude patterns directly on the command line. +See gitlink:gitignore[5] for the details. + [[how-to-merge]] How to merge ------------ @@ -1394,9 +1492,9 @@ dangling tree b24c2473f1fd3d91352a624795be026d64c8841f ------------------------------------------------- Dangling objects are not a problem. At worst they may take up a little -extra disk space. They can sometimes provide a last-resort method of -recovery lost work--see <> for details. However, if -you want, you may remove them with gitlink:git-prune[1] or the --prune +extra disk space. They can sometimes provide a last-resort method for +recovering lost work--see <> for details. However, if +you wish, you can remove them with gitlink:git-prune[1] or the --prune option to gitlink:git-gc[1]: ------------------------------------------------- @@ -1549,7 +1647,7 @@ automatically set the default remote branch to pull from at the time that a branch is created: ------------------------------------------------- -$ git checkout --track -b origin/maint maint +$ git checkout --track -b maint origin/maint ------------------------------------------------- In addition to saving you keystrokes, "git pull" also helps you by @@ -1626,31 +1724,40 @@ The final result will be a series of commits, one for each patch in the original mailbox, with authorship and commit log message each taken from the message containing each patch. -[[setting-up-a-public-repository]] -Setting up a public repository ------------------------------- +[[public-repositories]] +Public git repositories +----------------------- -Another way to submit changes to a project is to simply tell the -maintainer of that project to pull from your repository, exactly as -you did in the section "<>". +Another way to submit changes to a project is to tell the maintainer +of that project to pull the changes from your repository using +gitlink:git-pull[1]. In the section "<>" we described this as a way to get +updates from the "main" repository, but it works just as well in the +other direction. -If you and maintainer both have accounts on the same machine, then -then you can just pull changes from each other's repositories -directly; note that all of the commands (gitlink:git-clone[1], -git-fetch[1], git-pull[1], etc.) that accept a URL as an argument -will also accept a local directory name; so, for example, you can -use +If you and the maintainer both have accounts on the same machine, then +you can just pull changes from each other's repositories directly; +commands that accept repository URLs as arguments will also accept a +local directory name: ------------------------------------------------- $ git clone /path/to/repository $ git pull /path/to/other/repository ------------------------------------------------- -If this sort of setup is inconvenient or impossible, another (more -common) option is to set up a public repository on a public server. -This also allows you to cleanly separate private work in progress -from publicly visible work. +or an ssh url: + +------------------------------------------------- +$ git clone ssh://yourhost/~you/repository +------------------------------------------------- + +For projects with few developers, or for synchronizing a few private +repositories, this may be all you need. + +However, the more common way to do this is to maintain a separate public +repository (usually on a different host) for others to pull changes +from. This is usually more convenient, and allows you to cleanly +separate private work in progress from publicly visible work. You will continue to do your day-to-day work in your personal repository, but periodically "push" changes from your personal @@ -1669,32 +1776,54 @@ like this: | they push V their public repo <------------------- their repo -Now, assume your personal repository is in the directory ~/proj. We -first create a new clone of the repository: +We explain how to do this in the following sections. + +[[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 +is meant to be public: ------------------------------------------------- $ git clone --bare ~/proj proj.git +$ touch proj.git/git-daemon-export-ok ------------------------------------------------- The resulting directory proj.git contains a "bare" git repository--it is -just the contents of the ".git" directory, without a checked-out copy of -a working directory. +just the contents of the ".git" directory, without any files checked out +around it. Next, copy proj.git to the server where you plan to host the public repository. You can use scp, rsync, or whatever is most convenient. -If somebody else maintains the public server, they may already have -set up a git service for you, and you may skip to the section +[[exporting-via-git]] +Exporting a git repository via the git protocol +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This is the preferred method. + +If someone else administers the server, they should tell you what +directory to put the repository in, and what git:// url it will appear +at. You can then skip to the section "<>", below. -Otherwise, the following sections explain how to export your newly -created public repository: +Otherwise, all you need to do is start gitlink:git-daemon[1]; it will +listen on port 9418. By default, it will allow access to any directory +that looks like a git directory and contains the magic file +git-daemon-export-ok. Passing some directory paths as git-daemon +arguments will further restrict the exports to those paths. + +You can also run git-daemon as an inetd service; see the +gitlink:git-daemon[1] man page for details. (See especially the +examples section.) [[exporting-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. @@ -1712,7 +1841,7 @@ $ chmod a+x hooks/post-update (For an explanation of the last two lines, see gitlink:git-update-server-info[1], and the documentation -link:hooks.txt[Hooks used by git].) +link:hooks.html[Hooks used by git].) Advertise the url of proj.git. Anybody else should then be able to clone or pull from that url, for example with a commandline like: @@ -1726,20 +1855,11 @@ link:howto/setup-git-server-over-http.txt[setup-git-server-over-http] for a slightly more sophisticated setup using WebDAV which also allows pushing over http.) -[[exporting-via-git]] -Exporting a git repository via the git protocol ------------------------------------------------ - -This is the preferred method. - -For now, we refer you to the gitlink:git-daemon[1] man page for -instructions. (See especially the examples section.) - [[pushing-changes-to-a-public-repository]] Pushing changes to a public repository --------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Note that the two techniques outline above (exporting via +Note that the two techniques outlined above (exporting via <> or <>) allow other maintainers to fetch your latest changes, but they do not allow write access, which you will need to update the public repository with the @@ -1769,6 +1889,12 @@ proceeding the branch name by a plus sign: $ git push ssh://yourserver.com/~you/proj.git +master ------------------------------------------------- +Note that the target of a "push" is normally a +<> repository. You can also push to a +repository that has a checked-out working tree, but the working tree +will not be updated by the push. This may lead to unexpected results if +the branch you push to is the currently checked-out branch! + As with git-fetch, you may also set up configuration options to save typing; so, for example, after @@ -1791,17 +1917,38 @@ details. [[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 all push to and pull from a single shared repository. See -link:cvs-migration.txt[git for CVS users] for instructions on how to +link:cvs-migration.html[git for CVS users] for instructions on how to set this up. +However, while there is nothing wrong with git's support for shared +repositories, this mode of operation is not generally recommended, +simply because the mode of collaboration that git supports--by +exchanging patches and pulling from public repositories--has so many +advantages over the central shared repository: + + - Git's ability to quickly import and merge patches allows a + single maintainer to process incoming changes even at very + high rates. And when that becomes too much, git-pull provides + an easy way for that maintainer to delegate this job to other + maintainers while still allowing optional review of incoming + changes. + - Since every developer's repository has the same complete copy + of the project history, no repository is special, and it is + trivial for another developer to take over maintenance of a + project, either by mutual agreement, or because a maintainer + becomes unresponsive or difficult to work with. + - The lack of a central group of "committers" means there is + less need for formal decisions about who is "in" and who is + "out". + [[setting-up-gitweb]] -Allow 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 files and history without having to install git; see the file @@ -1843,7 +1990,8 @@ $ cd work Linus's tree will be stored in the remote branch named origin/master, and can be updated using gitlink:git-fetch[1]; you can track other public trees using gitlink:git-remote[1] to set up a "remote" and -git-fetch[1] to keep them up-to-date; see <>. +gitlink:git-fetch[1] to keep them up-to-date; see +<>. Now create the branches in which you are going to work; these start out at the current tip of origin/master branch, and should be set up (using @@ -2592,8 +2740,8 @@ 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 + + + + . +forms a sequence of {plus} {plus} {plus} {plus} . The structured objects can further have their structure and connectivity to other objects verified. This is generally done with @@ -3505,11 +3653,11 @@ itself! include::glossary.txt[] [[git-quick-start]] -Appendix A: Git Quick Start -=========================== +Appendix A: Git Quick Reference +=============================== -This is a quick summary of the major commands; the following chapters -will explain how these work in more detail. +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 @@ -3758,8 +3906,6 @@ Think about how to create a clear chapter dependency graph that will allow people to get to important topics without necessarily reading everything in between. -Say something about .gitignore. - Scan Documentation/ for other stuff left out; in particular: howto's some of technical/? @@ -3789,3 +3935,7 @@ CVS, Subversion, and just imports of series of release tarballs. More details on gitweb? Write a chapter on using plumbing and writing scripts. + +Alternates, clone -reference, etc. + +git unpack-objects -r for recovery