From b684f830cc071c99ede9861c84e3b1e54549f6c7 Mon Sep 17 00:00:00 2001 From: "J. Bruce Fields" Date: Mon, 8 Jan 2007 23:42:36 -0500 Subject: [PATCH] Documentation: reorder development section, todo's Update todo's. Split out "sharing development" section into a separate chapter, reorder. Signed-off-by: "J. Bruce Fields" --- Documentation/user-manual.txt | 627 +++++++++++++++++----------------- 1 file changed, 315 insertions(+), 312 deletions(-) diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index a2fd5d2756..5433d624d7 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -1024,305 +1024,6 @@ already contained in the other--then git just performs a moved forward to point at the head of the merged-in branch, without any new commits being created. -Ensuring good performance -------------------------- - -On large repositories, git depends on compression to keep the history -information from taking up to much space on disk or in memory. - -This compression is not performed automatically. Therefore you -should occasionally run - -------------------------------------------------- -$ git gc -------------------------------------------------- - -to recompress the archive and to prune any commits which are no -longer referred to anywhere. This can be very time-consuming, and -you should not modify the repository while it is working, so you -should run it while you are not working. - -Sharing development with others -------------------------------- - -[[getting-updates-with-git-pull]] -Getting updates with git pull -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -After you clone a repository and make a few changes of your own, you -may wish to check the original repository for updates and merge them -into your own work. - -We have already seen <> with gitlink:git-fetch[1], -and how to merge two branches. So you can merge in changes from the -original repository's master branch with: - -------------------------------------------------- -$ git fetch -$ git merge origin/master -------------------------------------------------- - -However, the gitlink:git-pull[1] command provides a way to do this in -one step: - -------------------------------------------------- -$ git pull origin master -------------------------------------------------- - -In fact, "origin" is normally the default repository to pull from, -and the default branch is normally the HEAD of the remote repository, -so often you can accomplish the above with just - -------------------------------------------------- -$ git pull -------------------------------------------------- - -See the descriptions of the branch..remote and -branch..merge options in gitlink:git-repo-config[1] to learn -how to control these defaults depending on the current branch. - -In addition to saving you keystrokes, "git pull" also helps you by -producing a default commit message documenting the branch and -repository that you pulled from. - -(But note that no such commit will be created in the case of a -<>; instead, your branch will just be -updated to point to the latest commit from the upstream branch). - -The git-pull command can also be given "." as the "remote" repository, in -which case it just merges in a branch from the current repository; so -the commands - -------------------------------------------------- -$ git pull . branch -$ git merge branch -------------------------------------------------- - -are roughly equivalent. The former is actually very commonly used. - -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: - -First, use gitlink:git-format-patches[1]; for example: - -------------------------------------------------- -$ git format-patches 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. - -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 gitlink:git-send-email[1] script to automate the process. -Consult the mailing list for your project first to determine how they -prefer such patches be handled. - -Importing patches to a project -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Git also provides a tool called gitlink:git-am[1] (am stands for -"apply mailbox"), for importing such an emailed series of patches. -Just save all of the patch-containing messages, in order, into a -single mailbox file, say "patches.mbox", then run - -------------------------------------------------- -$ git am patches.mbox -------------------------------------------------- - -Git will apply each patch in order; if any conflicts are found, it -will stop, and you can fix the conflicts as described in -"<>". Once the index is updated -with the results of the conflict resolution, instead of creating a -new commit, just run - -------------------------------------------------- -$ git am --resolved -------------------------------------------------- - -and git will create the commit for you and continue applying the -remaining patches from the mailbox. - -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 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -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 "<>". - -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 command (gitlink:git-clone[1], -git-fetch[1], git-pull[1], etc.) which accept a URL as an argument -will also accept a local file patch; so, for example, you can -use - -------------------------------------------------- -$ 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. - -You will continue to do your day-to-day work in your personal -repository, but periodically "push" changes from your personal -repository into your public repository, allowing other developers to -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 - -Now, assume your personal repository is in the directory ~/proj. We -first create a new clone of the repository: - -------------------------------------------------- -$ git clone --bare proj-clone.git -------------------------------------------------- - -The resulting directory proj-clone.git will contains a "bare" git -repository--it is just the contents of the ".git" directory, without -a checked-out copy of a working directory. - -Next, copy proj-clone.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 -"<>", below. - -Otherwise, the following sections explain how to export your newly -created public repository: - -[[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. - -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 -adjustments to give web clients some extra information they need: - -------------------------------------------------- -$ mv proj.git /home/you/public_html/proj.git -$ cd proj.git -$ git update-server-info -$ 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].) - -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: - -------------------------------------------------- -$ 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.) - -[[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 -<> 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 -latest changes created in your private repository. - -The simplest way to do this is using gitlink:git-push[1] and ssh; to -update the remote branch named "master" with the latest state of your -branch named "master", run - -------------------------------------------------- -$ git push ssh://yourserver.com/~you/proj.git master:master -------------------------------------------------- - -or just - -------------------------------------------------- -$ git push ssh://yourserver.com/~you/proj.git master -------------------------------------------------- - -As with git-fetch, git-push will complain if this does not result in -a <>. Normally this is a sign of -something wrong. However, if you are sure you know what you're -doing, you may force git-push to perform the update anyway by -proceeding the branch name by a plus sign: - -------------------------------------------------- -$ git push ssh://yourserver.com/~you/proj.git +master -------------------------------------------------- - -As with git-fetch, you may also set up configuration options to -save typing; so, for example, after - -------------------------------------------------- -$ cat >.git/config <.url, branch..remote, -and remote..push options in gitlink:git-repo-config[1] for -details. - -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 -set this up. - Fixing mistakes --------------- @@ -1426,6 +1127,316 @@ $ git show HEAD^ path/to/file which will display the given version of the file. +Ensuring good performance +------------------------- + +On large repositories, git depends on compression to keep the history +information from taking up to much space on disk or in memory. + +This compression is not performed automatically. Therefore you +should occasionally run + +------------------------------------------------- +$ git gc +------------------------------------------------- + +to recompress the archive and to prune any commits which are no +longer referred to anywhere. This can be very time-consuming, and +you should not modify the repository while it is working, so you +should run it while you are not working. + +Sharing development with others +=============================== + +[[getting-updates-with-git-pull]] +Getting updates with git pull +----------------------------- + +After you clone a repository and make a few changes of your own, you +may wish to check the original repository for updates and merge them +into your own work. + +We have already seen <> with gitlink:git-fetch[1], +and how to merge two branches. So you can merge in changes from the +original repository's master branch with: + +------------------------------------------------- +$ git fetch +$ git merge origin/master +------------------------------------------------- + +However, the gitlink:git-pull[1] command provides a way to do this in +one step: + +------------------------------------------------- +$ git pull origin master +------------------------------------------------- + +In fact, "origin" is normally the default repository to pull from, +and the default branch is normally the HEAD of the remote repository, +so often you can accomplish the above with just + +------------------------------------------------- +$ git pull +------------------------------------------------- + +See the descriptions of the branch..remote and +branch..merge options in gitlink:git-repo-config[1] to learn +how to control these defaults depending on the current branch. + +In addition to saving you keystrokes, "git pull" also helps you by +producing a default commit message documenting the branch and +repository that you pulled from. + +(But note that no such commit will be created in the case of a +<>; instead, your branch will just be +updated to point to the latest commit from the upstream branch). + +The git-pull command can also be given "." as the "remote" repository, in +which case it just merges in a branch from the current repository; so +the commands + +------------------------------------------------- +$ git pull . branch +$ git merge branch +------------------------------------------------- + +are roughly equivalent. The former is actually very commonly used. + +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: + +First, use gitlink:git-format-patches[1]; for example: + +------------------------------------------------- +$ git format-patches 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. + +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 gitlink:git-send-email[1] script to automate the process. +Consult the mailing list for your project first to determine how they +prefer such patches be handled. + +Importing patches to a project +------------------------------ + +Git also provides a tool called gitlink:git-am[1] (am stands for +"apply mailbox"), for importing such an emailed series of patches. +Just save all of the patch-containing messages, in order, into a +single mailbox file, say "patches.mbox", then run + +------------------------------------------------- +$ git am patches.mbox +------------------------------------------------- + +Git will apply each patch in order; if any conflicts are found, it +will stop, and you can fix the conflicts as described in +"<>". Once the index is updated +with the results of the conflict resolution, instead of creating a +new commit, just run + +------------------------------------------------- +$ git am --resolved +------------------------------------------------- + +and git will create the commit for you and continue applying the +remaining patches from the mailbox. + +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 +------------------------------ + +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 "<>". + +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 command (gitlink:git-clone[1], +git-fetch[1], git-pull[1], etc.) which accept a URL as an argument +will also accept a local file patch; so, for example, you can +use + +------------------------------------------------- +$ 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. + +You will continue to do your day-to-day work in your personal +repository, but periodically "push" changes from your personal +repository into your public repository, allowing other developers to +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 + +Now, assume your personal repository is in the directory ~/proj. We +first create a new clone of the repository: + +------------------------------------------------- +$ git clone --bare proj-clone.git +------------------------------------------------- + +The resulting directory proj-clone.git will contains a "bare" git +repository--it is just the contents of the ".git" directory, without +a checked-out copy of a working directory. + +Next, copy proj-clone.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 +"<>", below. + +Otherwise, the following sections explain how to export your newly +created public repository: + +[[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. + +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 +adjustments to give web clients some extra information they need: + +------------------------------------------------- +$ mv proj.git /home/you/public_html/proj.git +$ cd proj.git +$ git update-server-info +$ 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].) + +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: + +------------------------------------------------- +$ 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.) + +[[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 +<> 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 +latest changes created in your private repository. + +The simplest way to do this is using gitlink:git-push[1] and ssh; to +update the remote branch named "master" with the latest state of your +branch named "master", run + +------------------------------------------------- +$ git push ssh://yourserver.com/~you/proj.git master:master +------------------------------------------------- + +or just + +------------------------------------------------- +$ git push ssh://yourserver.com/~you/proj.git master +------------------------------------------------- + +As with git-fetch, git-push will complain if this does not result in +a <>. Normally this is a sign of +something wrong. However, if you are sure you know what you're +doing, you may force git-push to perform the update anyway by +proceeding the branch name by a plus sign: + +------------------------------------------------- +$ git push ssh://yourserver.com/~you/proj.git +master +------------------------------------------------- + +As with git-fetch, you may also set up configuration options to +save typing; so, for example, after + +------------------------------------------------- +$ cat >.git/config <.url, branch..remote, +and remote..push options in gitlink:git-repo-config[1] for +details. + +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 +set this up. + +Allow web browsing of a repository +---------------------------------- + +TODO: Brief setup-instructions for gitweb + +Examples +-------- + +TODO: topic branches, typical roles as in everyday.txt, ? + + Working with other version control systems ========================================== @@ -1623,10 +1634,8 @@ Scan email archives for other stuff left out Scan man pages to see if any assume more background than this manual provides. -Mention of gitweb. - -Update git fetch discussion to use "git remote" setup. That will -make things simpler. Maybe wait till git remote is done. +Update git fetch discussion to use "git remote", move most of branch +discussion till later. Can also simplify beginning by suggesting disconnected head instead of temporary branch creation. @@ -1636,18 +1645,12 @@ section: diff -1, -2, -3, --ours, --theirs :1:/path notation. The "git ls-files --unmerged --stage" thing is sorta useful too, actually. And note gitk --merge. Also what's easiest way to see common merge base? -Add more good examples. Entire sections of just cookbook examples might be a -good idea; maybe make an "advanced examples" section a standard end-of-chapter -section? +Add more good examples. Entire sections of just cookbook examples might +be a good idea; maybe make an "advanced examples" section a standard +end-of-chapter section? Include cross-references to the glossary, where appropriate. -Update for detached-head. - -Update for git-remote. Even if the command isn't there yet, I think we should -probably just document the repository configuration necessary to set it up, as -the default way to keep a repository up-to-date. - To document: reflogs, git reflog expire shallow clones?? See draft 1.5.0 release notes for some documentation.