diff options
Diffstat (limited to 'Documentation/user-manual.txt')
| -rw-r--r-- | Documentation/user-manual.txt | 130 |
1 files changed, 73 insertions, 57 deletions
diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index 85651b57ae..52c8523c7d 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -782,7 +782,7 @@ e05db0fd4f31dde7005f075a84f96b360d05984b Or you could recall that the ... operator selects all commits contained reachable from either one reference or the other but not -both: so +both; so ------------------------------------------------- $ git log origin...master @@ -931,11 +931,20 @@ The linkgit:git-archive[1] command can create a tar or zip archive from any version of a project; for example: ------------------------------------------------- -$ git archive --format=tar --prefix=project/ HEAD | gzip >latest.tar.gz +$ git archive -o latest.tar.gz --prefix=project/ HEAD ------------------------------------------------- -will use HEAD to produce a tar archive in which each filename is -preceded by "project/". +will use HEAD to produce a gzipped tar archive in which each filename +is preceded by `project/`. The output file format is inferred from +the output file extension if possible, see linkgit:git-archive[1] for +details. + +Versions of Git older than 1.7.7 don't know about the 'tar.gz' format, +you'll need to use gzip explicitly: + +------------------------------------------------- +$ git archive --format=tar --prefix=project/ HEAD | gzip >latest.tar.gz +------------------------------------------------- If you're releasing a new version of a software project, you may want to simultaneously make a changelog to include in the release @@ -991,9 +1000,16 @@ Developing with git Telling git your name --------------------- -Before creating any commits, you should introduce yourself to git. The -easiest way to do so is to make sure the following lines appear in a -file named .gitconfig in your home directory: +Before creating any commits, you should introduce yourself to Git. +The easiest way to do so is to use linkgit:git-config[1]: + +------------------------------------------------ +$ git config --global user.name 'Your Name Comes Here' +$ git config --global user.email 'you@yourdomain.example.com' +------------------------------------------------ + +Which will add the following to a file named `.gitconfig` in your +home directory: ------------------------------------------------ [user] @@ -1001,8 +1017,9 @@ file named .gitconfig in your home directory: email = you@yourdomain.example.com ------------------------------------------------ -(See the "CONFIGURATION FILE" section of linkgit:git-config[1] for -details on the configuration file.) +See the "CONFIGURATION FILE" section of linkgit:git-config[1] for +details on the configuration file. The file is plain text, so you can +also edit it with your favorite editor. [[creating-a-new-repository]] @@ -1561,18 +1578,12 @@ $ git stash pop 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. - -This compression is not performed automatically. Therefore you -should occasionally run linkgit:git-gc[1]: - -------------------------------------------------- -$ git gc -------------------------------------------------- - -to recompress the archive. This can be very time-consuming, so -you may prefer to run `git gc` when you are not doing other work. +On large repositories, Git depends on compression to keep the history +information from taking up too much space on disk or in memory. Some +git commands may automatically run linkgit:git-gc[1], so you don't +have to worry about running it manually. However, compressing a large +repository may take a while, so you may want to call `gc` explicitly +to avoid automatic compression kicking in when it is not convenient. [[ensuring-reliability]] @@ -1787,6 +1798,13 @@ $ git format-patch origin will produce a numbered series of files in the current directory, one for each patch in the current branch but not in origin/HEAD. +`git format-patch` can include an initial "cover letter". You can insert +commentary on individual patches after the three dash line which +`format-patch` places after the commit message but before the patch +itself. If you use `git notes` to track your cover letter material, +`git format-patch --notes` will include the commit's notes in a similar +manner. + You can then import these into your mail client and send them by hand. However, if you have a lot to send at once, you may prefer to use the linkgit:git-send-email[1] script to automate the process. @@ -1924,11 +1942,11 @@ 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. +host with a web server set up, HTTP exports may be simpler to set up. All you need to do is place the newly created bare git repository in a directory that is exported by the web server, and make some @@ -1954,7 +1972,7 @@ $ git clone http://yourserver.com/~you/proj.git (See also 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.) +allows pushing over HTTP.) [[pushing-changes-to-a-public-repository]] Pushing changes to a public repository @@ -1991,16 +2009,21 @@ 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 +save typing; so, for example: + +------------------------------------------------- +$ git remote add public-repo ssh://yourserver.com/~you/proj.git +------------------------------------------------- + +adds the following to `.git/config`: ------------------------------------------------- -$ cat >>.git/config <<EOF [remote "public-repo"] - url = ssh://yourserver.com/~you/proj.git -EOF + url = yourserver.com:proj.git + fetch = +refs/heads/*:refs/remotes/example/* ------------------------------------------------- -you should be able to perform the above push with just +which lets you do the same push with just ------------------------------------------------- $ git push public-repo master @@ -2039,6 +2062,13 @@ branch name with a plus sign: $ git push ssh://yourserver.com/~you/proj.git +master ------------------------------------------------- +Note the addition of the `+` sign. Alternatively, you can use the +`-f` flag to force the remote update, as in: + +------------------------------------------------- +$ git push -f ssh://yourserver.com/~you/proj.git master +------------------------------------------------- + Normally whenever a branch head in a public repository is modified, it is modified to point to a descendant of the commit that it pointed to before. By forcing a push in this situation, you break that convention. @@ -2843,48 +2873,34 @@ branch.master.merge=refs/heads/master If there are other repositories that you also use frequently, you can create similar configuration options to save typing; for example, -after ------------------------------------------------- -$ git config remote.example.url git://example.com/proj.git +$ git remote add example git://example.com/proj.git ------------------------------------------------- -then the following two commands will do the same thing: +adds the following to `.git/config`: ------------------------------------------------- -$ git fetch git://example.com/proj.git master:refs/remotes/example/master -$ git fetch example master:refs/remotes/example/master +[remote "example"] + url = git://example.com/proj.git + fetch = +refs/heads/*:refs/remotes/example/* ------------------------------------------------- -Even better, if you add one more option: +Also note that the above configuration can be performed by directly +editing the file `.git/config` instead of using linkgit:git-remote[1]. -------------------------------------------------- -$ git config remote.example.fetch master:refs/remotes/example/master -------------------------------------------------- - -then the following commands will all do the same thing: +After configuring the remote, the following three commands will do the +same thing: ------------------------------------------------- -$ git fetch git://example.com/proj.git master:refs/remotes/example/master -$ git fetch example master:refs/remotes/example/master +$ git fetch git://example.com/proj.git +refs/heads/*:refs/remotes/example/* +$ git fetch example +refs/heads/*:refs/remotes/example/* $ git fetch example ------------------------------------------------- -You can also add a "+" to force the update each time: - -------------------------------------------------- -$ git config remote.example.fetch +master:refs/remotes/example/master -------------------------------------------------- - -Don't do this unless you're sure you won't mind "git fetch" possibly -throwing away commits on 'example/master'. - -Also note that all of the above configuration can be performed by -directly editing the file .git/config instead of using -linkgit:git-config[1]. - See linkgit:git-config[1] for more details on the configuration -options mentioned above. +options mentioned above and linkgit:git-fetch[1] for more details on +the refspec syntax. [[git-concepts]] @@ -3389,7 +3405,7 @@ $ git log --raw --all ------------------------------------------------ and just looked for the sha of the missing object (4b9458b..) in that -whole thing. It's up to you - git does *have* a lot of information, it is +whole thing. It's up to you--Git does *have* a lot of information, it is just missing one particular blob version. [[the-index]] |