diff --git a/.gitignore b/.gitignore index 8ddccd7dac..a9dc462cb5 100644 --- a/.gitignore +++ b/.gitignore @@ -2,13 +2,16 @@ GIT-CFLAGS GIT-VERSION-FILE git git-add +git-add--interactive git-am git-annotate git-apply git-applymbox git-applypatch git-archimport +git-archive git-bisect +git-blame git-branch git-cat-file git-check-ref-format @@ -37,8 +40,10 @@ git-fetch git-fetch-pack git-findtags git-fmt-merge-msg +git-for-each-ref git-format-patch git-fsck-objects +git-gc git-get-tar-commit-id git-grep git-hash-object @@ -46,6 +51,7 @@ git-http-fetch git-http-push git-imap-send git-index-pack +git-init git-init-db git-instaweb git-local-fetch @@ -59,10 +65,12 @@ git-mailsplit git-merge git-merge-base git-merge-index +git-merge-file git-merge-tree git-merge-octopus git-merge-one-file git-merge-ours +git-merge-recur git-merge-recursive git-merge-resolve git-merge-stupid @@ -72,6 +80,7 @@ git-name-rev git-mv git-pack-redundant git-pack-objects +git-pack-refs git-parse-remote git-patch-id git-peek-remote @@ -83,7 +92,9 @@ git-quiltimport git-read-tree git-rebase git-receive-pack +git-reflog git-relink +git-remote git-repack git-repo-config git-request-pull @@ -94,6 +105,7 @@ git-rev-list git-rev-parse git-revert git-rm +git-runstatus git-send-email git-send-pack git-sh-setup @@ -102,6 +114,7 @@ git-shortlog git-show git-show-branch git-show-index +git-show-ref git-ssh-fetch git-ssh-pull git-ssh-push @@ -118,8 +131,8 @@ git-unpack-objects git-update-index git-update-ref git-update-server-info +git-upload-archive git-upload-pack -git-upload-tar git-var git-verify-pack git-verify-tag @@ -140,9 +153,9 @@ git-core.spec *.py[co] config.mak autom4te.cache +config.cache config.log config.status config.mak.autogen config.mak.append configure -git-blame diff --git a/.mailmap b/.mailmap new file mode 100644 index 0000000000..2c658f42f5 --- /dev/null +++ b/.mailmap @@ -0,0 +1,37 @@ +# +# This list is used by git-shortlog to fix a few botched name translations +# in the git archive, either because the author's full name was messed up +# and/or not always written the same way, making contributions from the +# same person appearing not to be so. +# + +Aneesh Kumar K.V +Chris Shoemaker +Daniel Barkalow +David Kågedal +Fredrik Kuivinen +H. Peter Anvin +H. Peter Anvin +H. Peter Anvin +Horst H. von Brand +Joachim Berdal Haga +Jon Loeliger +Jon Seymour +Karl Hasselström +Kent Engstrom +Lars Doelle +Lars Doelle +Lukas Sandström +Martin Langhoff +Nguyễn Thái Ngọc Duy +Ramsay Allan Jones +René Scharfe +Robert Fitzsimons +Santi Béjar +Sean Estabrooks +Shawn O. Pearce +Tony Luck +Ville Skyttä +YOSHIFUJI Hideaki +anonymous +anonymous diff --git a/Documentation/Makefile b/Documentation/Makefile index 0d9ffb4ad9..93c7024b48 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -32,6 +32,9 @@ man7dir=$(mandir)/man7 # DESTDIR= INSTALL?=install +DOC_REF = origin/man + +-include ../config.mak.autogen # # Please note that there is a minor bug in asciidoc. @@ -54,8 +57,8 @@ man7: $(DOC_MAN7) install: man $(INSTALL) -d -m755 $(DESTDIR)$(man1dir) $(DESTDIR)$(man7dir) - $(INSTALL) $(DOC_MAN1) $(DESTDIR)$(man1dir) - $(INSTALL) $(DOC_MAN7) $(DESTDIR)$(man7dir) + $(INSTALL) -m644 $(DOC_MAN1) $(DESTDIR)$(man1dir) + $(INSTALL) -m644 $(DOC_MAN7) $(DESTDIR)$(man7dir) # @@ -105,8 +108,11 @@ WEBDOC_DEST = /pub/software/scm/git/docs $(patsubst %.txt,%.html,$(wildcard howto/*.txt)): %.html : %.txt rm -f $@+ $@ - sed -e '1,/^$$/d' $? | asciidoc -b xhtml11 - >$@+ + sed -e '1,/^$$/d' $< | asciidoc -b xhtml11 - >$@+ mv $@+ $@ install-webdoc : html sh ./install-webdoc.sh $(WEBDOC_DEST) + +quick-install: + sh ./install-doc-quick.sh $(DOC_REF) $(mandir) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 90722c21fa..646b6e7331 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -101,8 +101,13 @@ send it "To:" the mailing list, and optionally "cc:" him. If it is trivially correct or after the list reached a consensus, send it "To:" the maintainer and optionally "cc:" the list. +Also note that your maintainer does not actively involve himself in +maintaining what are in contrib/ hierarchy. When you send fixes and +enhancements to them, do not forget to "cc: " the person who primarily +worked on that hierarchy in contrib/. -(6) Sign your work + +(4) Sign your work To improve tracking of who did what, we've borrowed the "sign-off" procedure from the Linux kernel project on patches @@ -144,6 +149,9 @@ then you just add a line saying Signed-off-by: Random J Developer +This line can be automatically added by git if you run the git-commit +command with the -s option. + Some people also put extra tags at the end. They'll just be ignored for now, but you can do this to mark internal company procedures or just point out some special detail about the sign-off. diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf index 8196d787ab..44b1ce4c6b 100644 --- a/Documentation/asciidoc.conf +++ b/Documentation/asciidoc.conf @@ -11,6 +11,7 @@ caret=^ startsb=[ endsb=] +tilde=~ ifdef::backend-docbook[] [gitlink-inlinemacro] diff --git a/Documentation/callouts.xsl b/Documentation/callouts.xsl index ad03755d8f..6a361a2136 100644 --- a/Documentation/callouts.xsl +++ b/Documentation/callouts.xsl @@ -13,4 +13,18 @@ .br + + + + + + + + + + + + diff --git a/Documentation/config.txt b/Documentation/config.txt index ce722a2db0..f7dba8977f 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -31,6 +31,11 @@ Example external = "/usr/local/bin/gnu-diff -u" renames = true + [branch "devel"] + remote = origin + merge = refs/heads/devel + + Variables ~~~~~~~~~ @@ -71,12 +76,19 @@ core.preferSymlinkRefs:: expect HEAD to be a symbolic link. core.logAllRefUpdates:: - If true, `git-update-ref` will append a line to - "$GIT_DIR/logs/" listing the new SHA1 and the date/time - of the update. If the file does not exist it will be - created automatically. This information can be used to - determine what commit was the tip of a branch "2 days ago". - This value is false by default (no logging). + Updates to a ref is logged to the file + "$GIT_DIR/logs/", by appending the new and old + SHA1, the date/time and the reason of the update, but + only when the file exists. If this configuration + variable is set to true, missing "$GIT_DIR/logs/" + file is automatically created for branch heads. ++ +This information can be used to determine what commit +was the tip of a branch "2 days ago". ++ +This value is true by default in a repository that has +a working directory associated with it, and false by +default in a bare repository. core.repositoryFormatVersion:: Internal variable identifying the repository format and layout @@ -88,7 +100,7 @@ core.sharedRepository:: group-writable). When 'all' (or 'world' or 'everybody'), the repository will be readable by all users, additionally to being group-shareable. When 'umask' (or 'false'), git will use permissions - reported by umask(2). See gitlink:git-init-db[1]. False by default. + reported by umask(2). See gitlink:git-init[1]. False by default. core.warnAmbiguousRefs:: If true, git will warn you if the ref name you passed it is ambiguous @@ -106,6 +118,34 @@ core.legacyheaders:: database directly (where the "http://" and "rsync://" protocols count as direct access). +core.packedGitWindowSize:: + Number of bytes of a pack file to map into memory in a + single mapping operation. Larger window sizes may allow + your system to process a smaller number of large pack files + more quickly. Smaller window sizes will negatively affect + performance due to increased calls to the operating system's + memory manager, but may improve performance when accessing + a large number of large pack files. ++ +Default is 1 MiB if NO_MMAP was set at compile time, otherwise 32 +MiB on 32 bit platforms and 1 GiB on 64 bit platforms. This should +be reasonable for all users/operating systems. You probably do +not need to adjust this value. ++ +Common unit suffixes of 'k', 'm', or 'g' are supported. + +core.packedGitLimit:: + Maximum number of bytes to map simultaneously into memory + from pack files. If Git needs to access more than this many + bytes at once to complete an operation it will unmap existing + regions to reclaim virtual address space within the process. ++ +Default is 256 MiB on 32 bit platforms and 8 GiB on 64 bit platforms. +This should be reasonable for all users/operating systems, except on +the largest projects. You probably do not need to adjust this value. ++ +Common unit suffixes of 'k', 'm', or 'g' are supported. + alias.*:: Command aliases for the gitlink:git[1] command wrapper - e.g. after defining "alias.last = cat-file commit HEAD", the invocation @@ -119,25 +159,65 @@ apply.whitespace:: Tells `git-apply` how to handle whitespaces, in the same way as the '--whitespace' option. See gitlink:git-apply[1]. -pager.color:: - A boolean to enable/disable colored output when the pager is in - use (default is true). +branch..remote:: + When in branch , it tells `git fetch` which remote to fetch. + If this option is not given, `git fetch` defaults to remote "origin". -diff.color:: +branch..merge:: + When in branch , it tells `git fetch` the default refspec to + be marked for merging in FETCH_HEAD. The value has exactly to match + a remote part of one of the refspecs which are fetched from the remote + given by "branch..remote". + The merge information is used by `git pull` (which at first calls + `git fetch`) to lookup the default branch for merging. Without + this option, `git pull` defaults to merge the first refspec fetched. + Specify multiple values to get an octopus merge. + +color.branch:: + A boolean to enable/disable color in the output of + gitlink:git-branch[1]. May be set to `true` (or `always`), + `false` (or `never`) or `auto`, in which case colors are used + only when the output is to a terminal. Defaults to false. + +color.branch.:: + Use customized color for branch coloration. `` is one of + `current` (the current branch), `local` (a local branch), + `remote` (a tracking branch in refs/remotes/), `plain` (other + refs), or `reset` (the normal terminal color). The value for + these configuration variables can be one of: `normal`, `bold`, + `dim`, `ul`, `blink`, `reverse`, `reset`, `black`, `red`, + `green`, `yellow`, `blue`, `magenta`, `cyan`, or `white`. + +color.diff:: When true (or `always`), always use colors in patch. When false (or `never`), never. When set to `auto`, use colors only when the output is to the terminal. -diff.color.:: +color.diff.:: Use customized color for diff colorization. `` specifies which part of the patch to use the specified color, and is one of `plain` (context text), `meta` (metainformation), `frag` (hunk header), `old` (removed - lines), or `new` (added lines). The value for these - configuration variables can be one of: `normal`, `bold`, - `dim`, `ul`, `blink`, `reverse`, `reset`, `black`, - `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, or - `white`. + lines), or `new` (added lines). The values of these + variables may be specified as in color.branch.. + +color.pager:: + A boolean to enable/disable colored output when the pager is in + use (default is true). + +color.status:: + A boolean to enable/disable color in the output of + gitlink:git-status[1]. May be set to `true` (or `always`), + `false` (or `never`) or `auto`, in which case colors are used + only when the output is to a terminal. Defaults to false. + +color.status.:: + Use customized color for status colorization. `` is + one of `header` (the header text of the status message), + `added` or `updated` (files which are added but not committed), + `changed` (files which are changed but not added in the index), + or `untracked` (files which are not tracked by git). The values of + these variables may be specified as in color.branch.. diff.renameLimit:: The number of files to consider when performing the copy/rename @@ -152,6 +232,25 @@ format.headers:: Additional email headers to include in a patch to be submitted by mail. See gitlink:git-format-patch[1]. +gc.reflogexpire:: + `git reflog expire` removes reflog entries older than + this time; defaults to 90 days. + +gc.reflogexpireunreachable:: + `git reflog expire` removes reflog entries older than + this time and are not reachable from the current tip; + defaults to 30 days. + +gc.rerereresolved:: + Records of conflicted merge you resolved earlier are + kept for this many days when `git rerere gc` is run. + The default is 60 days. See gitlink:git-rerere[1]. + +gc.rerereunresolved:: + Records of conflicted merge you have not resolved are + kept for this many days when `git rerere gc` is run. + The default is 15 days. See gitlink:git-rerere[1]. + gitcvs.enabled:: Whether the cvs pserver interface is enabled for this repository. See gitlink:git-cvsserver[1]. @@ -195,6 +294,12 @@ http.lowSpeedLimit, http.lowSpeedTime:: Can be overridden by the 'GIT_HTTP_LOW_SPEED_LIMIT' and 'GIT_HTTP_LOW_SPEED_TIME' environment variables. +http.noEPSV:: + A boolean which disables using of EPSV ftp command by curl. + This can helpful with some "poor" ftp servers which doesn't + support EPSV mode. Can be overridden by the 'GIT_CURL_FTP_NO_EPSV' + environment variable. Default is false (curl will use EPSV). + i18n.commitEncoding:: Character encoding the commit messages are stored in; git itself does not care per se, but this information is necessary e.g. when @@ -202,6 +307,16 @@ i18n.commitEncoding:: browser (and possibly at other places in the future or in other porcelains). See e.g. gitlink:git-mailinfo[1]. Defaults to 'utf-8'. +i18n.logOutputEncoding:: + Character encoding the commit messages are converted to when + running `git-log` and friends. + +log.showroot:: + If true, the initial commit will be shown as a big creation event. + This is equivalent to a diff against an empty tree. + Tools like gitlink:git-log[1] or gitlink:git-whatchanged[1], which + normally hide the root commit will now show it. True by default. + merge.summary:: Whether to include summaries of merged commits in newly created merge commit messages. False by default. @@ -217,6 +332,22 @@ pull.octopus:: pull.twohead:: The default merge strategy to use when pulling a single branch. +remote..url:: + The URL of a remote repository. See gitlink:git-fetch[1] or + gitlink:git-push[1]. + +remote..fetch:: + The default set of "refspec" for gitlink:git-fetch[1]. See + gitlink:git-fetch[1]. + +remote..push:: + The default set of "refspec" for gitlink:git-push[1]. See + gitlink:git-push[1]. + +repack.usedeltabaseoffset:: + Allow gitlink:git-repack[1] to create packs that uses + delta-base offset. Defaults to false. + show.difftree:: The default gitlink:git-diff-tree[1] arguments to be used for gitlink:git-show[1]. @@ -253,3 +384,19 @@ whatchanged.difftree:: imap:: The configuration variables in the 'imap' section are described in gitlink:git-imap-send[1]. + +receive.unpackLimit:: + If the number of objects received in a push is below this + limit then the objects will be unpacked into loose object + files. However if the number of received objects equals or + exceeds this limit then the received pack will be stored as + a pack, after adding any missing delta bases. Storing the + pack from a push can make the push operation complete faster, + especially on slow filesystems. + +receive.denyNonFastForwards:: + If set to true, git-receive-pack will deny a ref update which is + not a fast forward. Use this to prevent such an update via a push, + even if that push is forced. This configuration variable is + set when initializing a shared repository. + diff --git a/Documentation/core-tutorial.txt b/Documentation/core-tutorial.txt index 1185897f70..0cd33fb5b7 100644 --- a/Documentation/core-tutorial.txt +++ b/Documentation/core-tutorial.txt @@ -46,18 +46,18 @@ to import into git. For our first example, we're going to start a totally new repository from scratch, with no pre-existing files, and we'll call it `git-tutorial`. To start up, create a subdirectory for it, change into that -subdirectory, and initialize the git infrastructure with `git-init-db`: +subdirectory, and initialize the git infrastructure with `git-init`: ------------------------------------------------ $ mkdir git-tutorial $ cd git-tutorial -$ git-init-db +$ git-init ------------------------------------------------ to which git will reply ---------------- -defaulting to local storage area +Initialized empty Git repository in .git/ ---------------- which is just git's way of saying that you haven't been doing anything @@ -336,17 +336,9 @@ $ commit=$(echo 'Initial commit' | git-commit-tree $tree) $ git-update-ref HEAD $commit ------------------------------------------------ -which will say: - ----------------- -Committing initial tree 8988da15d077d4829fc51d8544c097def6644dbb ----------------- - -just to warn you about the fact that it created a totally new commit -that is not related to anything else. Normally you do this only *once* -for a project ever, and all later commits will be parented on top of an -earlier commit, and you'll never see this "Committing initial tree" -message ever again. +In this case this creates a totally new commit that is not related to +anything else. Normally you do this only *once* for a project ever, and +all later commits will be parented on top of an earlier commit. Again, normally you'd never actually do this by hand. There is a helpful script called `git commit` that will do all of this for you. So @@ -1379,11 +1371,11 @@ $ mkdir my-git.git ------------ Then, make that directory into a git repository by running -`git init-db`, but this time, since its name is not the usual +`git init`, but this time, since its name is not the usual `.git`, we do things slightly differently: ------------ -$ GIT_DIR=my-git.git git-init-db +$ GIT_DIR=my-git.git git-init ------------ Make sure this directory is available for others you want your @@ -1519,7 +1511,7 @@ A recommended workflow for a "project lead" goes like this: + If other people are pulling from your repository over dumb transport protocols (HTTP), you need to keep this repository -'dumb transport friendly'. After `git init-db`, +'dumb transport friendly'. After `git init`, `$GIT_DIR/hooks/post-update` copied from the standard templates would contain a call to `git-update-server-info` but the `post-update` hook itself is disabled by default -- enable it @@ -1620,7 +1612,7 @@ suggested in the previous section may be new to you. You do not have to worry. git supports "shared public repository" style of cooperation you are probably more familiar with as well. -See link:cvs-migration.txt[git for CVS users] for the details. +See link:cvs-migration.html[git for CVS users] for the details. Bundling your work together --------------------------- diff --git a/Documentation/cvs-migration.txt b/Documentation/cvs-migration.txt index d2b0bd38de..775bf4266a 100644 --- a/Documentation/cvs-migration.txt +++ b/Documentation/cvs-migration.txt @@ -1,43 +1,119 @@ git for CVS users ================= -So you're a CVS user. That's OK, it's a treatable condition. The job of -this document is to put you on the road to recovery, by helping you -convert an existing cvs repository to git, and by showing you how to use a -git repository in a cvs-like fashion. +Git differs from CVS in that every working tree contains a repository with +a full copy of the project history, and no repository is inherently more +important than any other. However, you can emulate the CVS model by +designating a single shared repository which people can synchronize with; +this document explains how to do that. Some basic familiarity with git is required. This link:tutorial.html[tutorial introduction to git] should be sufficient. -First, note some ways that git differs from CVS: +Developing against a shared repository +-------------------------------------- - * Commits are atomic and project-wide, not per-file as in CVS. +Suppose a shared repository is set up in /pub/repo.git on the host +foo.com. Then as an individual committer you can clone the shared +repository over ssh with: - * Offline work is supported: you can make multiple commits locally, - then submit them when you're ready. +------------------------------------------------ +$ git clone foo.com:/pub/repo.git/ my-project +$ cd my-project +------------------------------------------------ - * Branching is fast and easy. +and hack away. The equivalent of `cvs update` is - * Every working tree contains a repository with a full copy of the - project history, and no repository is inherently more important than - any other. However, you can emulate the CVS model by designating a - single shared repository which people can synchronize with; see below - for details. +------------------------------------------------ +$ git pull origin +------------------------------------------------ + +which merges in any work that others might have done since the clone +operation. If there are uncommitted changes in your working tree, commit +them first before running git pull. + +[NOTE] +================================ +The `pull` command knows where to get updates from because of certain +configuration variables that were set by the first `git clone` +command; see `git repo-config -l` and the gitlink:git-repo-config[1] man +page for details. +================================ + +You can update the shared repository with your changes by first committing +your changes, and then using the gitlink:git-push[1] command: + +------------------------------------------------ +$ git push origin master +------------------------------------------------ + +to "push" those commits to the shared repository. If someone else has +updated the repository more recently, `git push`, like `cvs commit`, will +complain, in which case you must pull any changes before attempting the +push again. + +In the `git push` command above we specify the name of the remote branch +to update (`master`). If we leave that out, `git push` tries to update +any branches in the remote repository that have the same name as a branch +in the local repository. So the last `push` can be done with either of: + +------------ +$ git push origin +$ git push foo.com:/pub/project.git/ +------------ + +as long as the shared repository does not have any branches +other than `master`. + +Setting Up a Shared Repository +------------------------------ + +We assume you have already created a git repository for your project, +possibly created from scratch or from a tarball (see the +link:tutorial.html[tutorial]), or imported from an already existing CVS +repository (see the next section). + +Assume your existing repo is at /home/alice/myproject. Create a new "bare" +repository (a repository without a working tree) and fetch your project into +it: + +------------------------------------------------ +$ mkdir /pub/my-repo.git +$ cd /pub/my-repo.git +$ git --bare init --shared +$ git --bare fetch /home/alice/myproject master:master +------------------------------------------------ + +Next, give every team member read/write access to this repository. One +easy way to do this is to give all the team members ssh access to the +machine where the repository is hosted. If you don't want to give them a +full shell on the machine, there is a restricted shell which only allows +users to do git pushes and pulls; see gitlink:git-shell[1]. + +Put all the committers in the same group, and make the repository +writable by that group: + +------------------------------------------------ +$ chgrp -R $group /pub/my-repo.git +------------------------------------------------ + +Make sure committers have a umask of at most 027, so that the directories +they create are writable and searchable by other group members. Importing a CVS archive ----------------------- First, install version 2.1 or higher of cvsps from link:http://www.cobite.com/cvsps/[http://www.cobite.com/cvsps/] and make -sure it is in your path. The magic command line is then +sure it is in your path. Then cd to a checked out CVS working directory +of the project you are interested in and run gitlink:git-cvsimport[1]: ------------------------------------------- -$ git cvsimport -v -d -C +$ git cvsimport -C ------------------------------------------- This puts a git archive of the named CVS module in the directory -, which will be created if necessary. The -v option makes -the conversion script very chatty. +, which will be created if necessary. The import checks out from CVS every revision of every file. Reportedly cvsimport can average some twenty revisions per second, so for a @@ -55,14 +131,32 @@ work, you must not modify the imported branches; instead, create new branches for your own changes, and merge in the imported branches as necessary. -Development Models ------------------- +Advanced Shared Repository Management +------------------------------------- + +Git allows you to specify scripts called "hooks" to be run at certain +points. You can use these, for example, to send all commits to the shared +repository to a mailing list. See link:hooks.html[Hooks used by git]. + +You can enforce finer grained permissions using update hooks. See +link:howto/update-hook-example.txt[Controlling access to branches using +update hooks]. + +Providing CVS Access to a git Repository +---------------------------------------- + +It is also possible to provide true CVS access to a git repository, so +that developers can still use CVS; see gitlink:git-cvsserver[1] for +details. + +Alternative Development Models +------------------------------ CVS users are accustomed to giving a group of developers commit access to -a common repository. In the next section we'll explain how to do this -with git. However, the distributed nature of git allows other development -models, and you may want to first consider whether one of them might be a -better fit for your project. +a common repository. As we've seen, this is also possible with git. +However, the distributed nature of git allows other development models, +and you may want to first consider whether one of them might be a better +fit for your project. For example, you can choose a single person to maintain the project's primary public repository. Other developers then clone this repository @@ -75,230 +169,3 @@ variants of this model. With a small group, developers may just pull changes from each other's repositories without the need for a central maintainer. - -Emulating the CVS Development Model ------------------------------------ - -Start with an ordinary git working directory containing the project, and -remove the checked-out files, keeping just the bare .git directory: - ------------------------------------------------- -$ mv project/.git /pub/repo.git -$ rm -r project/ ------------------------------------------------- - -Next, give every team member read/write access to this repository. One -easy way to do this is to give all the team members ssh access to the -machine where the repository is hosted. If you don't want to give them a -full shell on the machine, there is a restricted shell which only allows -users to do git pushes and pulls; see gitlink:git-shell[1]. - -Put all the committers in the same group, and make the repository -writable by that group: - ------------------------------------------------- -$ chgrp -R $group repo.git -$ find repo.git -mindepth 1 -type d |xargs chmod ug+rwx,g+s -$ GIT_DIR=repo.git git repo-config core.sharedrepository true ------------------------------------------------- - -Make sure committers have a umask of at most 027, so that the directories -they create are writable and searchable by other group members. - -Suppose this repository is now set up in /pub/repo.git on the host -foo.com. Then as an individual committer you can clone the shared -repository: - ------------------------------------------------- -$ git clone foo.com:/pub/repo.git/ my-project -$ cd my-project ------------------------------------------------- - -and hack away. The equivalent of `cvs update` is - ------------------------------------------------- -$ git pull origin ------------------------------------------------- - -which merges in any work that others might have done since the clone -operation. - -[NOTE] -================================ -The first `git clone` places the following in the -`my-project/.git/remotes/origin` file, and that's why the previous step -and the next step both work. ------------- -URL: foo.com:/pub/project.git/ my-project -Pull: master:origin ------------- -================================ - -You can update the shared repository with your changes using: - ------------------------------------------------- -$ git push origin master ------------------------------------------------- - -If someone else has updated the repository more recently, `git push`, like -`cvs commit`, will complain, in which case you must pull any changes -before attempting the push again. - -In the `git push` command above we specify the name of the remote branch -to update (`master`). If we leave that out, `git push` tries to update -any branches in the remote repository that have the same name as a branch -in the local repository. So the last `push` can be done with either of: - ------------- -$ git push origin -$ git push repo.shared.xz:/pub/scm/project.git/ ------------- - -as long as the shared repository does not have any branches -other than `master`. - -[NOTE] -============ -Because of this behavior, if the shared repository and the developer's -repository both have branches named `origin`, then a push like the above -attempts to update the `origin` branch in the shared repository from the -developer's `origin` branch. The results may be unexpected, so it's -usually best to remove any branch named `origin` from the shared -repository. -============ - -Advanced Shared Repository Management -------------------------------------- - -Git allows you to specify scripts called "hooks" to be run at certain -points. You can use these, for example, to send all commits to the shared -repository to a mailing list. See link:hooks.txt[Hooks used by git]. - -You can enforce finer grained permissions using update hooks. See -link:howto/update-hook-example.txt[Controlling access to branches using -update hooks]. - -CVS annotate ------------- - -So, something has gone wrong, and you don't know whom to blame, and -you're an ex-CVS user and used to do "cvs annotate" to see who caused -the breakage. You're looking for the "git annotate", and it's just -claiming not to find such a script. You're annoyed. - -Yes, that's right. Core git doesn't do "annotate", although it's -technically possible, and there are at least two specialized scripts out -there that can be used to get equivalent information (see the git -mailing list archives for details). - -git has a couple of alternatives, though, that you may find sufficient -or even superior depending on your use. One is called "git-whatchanged" -(for obvious reasons) and the other one is called "pickaxe" ("a tool for -the software archaeologist"). - -The "git-whatchanged" script is a truly trivial script that can give you -a good overview of what has changed in a file or a directory (or an -arbitrary list of files or directories). The "pickaxe" support is an -additional layer that can be used to further specify exactly what you're -looking for, if you already know the specific area that changed. - -Let's step back a bit and think about the reason why you would -want to do "cvs annotate a-file.c" to begin with. - -You would use "cvs annotate" on a file when you have trouble -with a function (or even a single "if" statement in a function) -that happens to be defined in the file, which does not do what -you want it to do. And you would want to find out why it was -written that way, because you are about to modify it to suit -your needs, and at the same time you do not want to break its -current callers. For that, you are trying to find out why the -original author did things that way in the original context. - -Many times, it may be enough to see the commit log messages of -commits that touch the file in question, possibly along with the -patches themselves, like this: - - $ git-whatchanged -p a-file.c - -This will show log messages and patches for each commit that -touches a-file. - -This, however, may not be very useful when this file has many -modifications that are not related to the piece of code you are -interested in. You would see many log messages and patches that -do not have anything to do with the piece of code you are -interested in. As an example, assuming that you have this piece -of code that you are interested in in the HEAD version: - - if (frotz) { - nitfol(); - } - -you would use git-rev-list and git-diff-tree like this: - - $ git-rev-list HEAD | - git-diff-tree --stdin -v -p -S'if (frotz) { - nitfol(); - }' - -We have already talked about the "\--stdin" form of git-diff-tree -command that reads the list of commits and compares each commit -with its parents (otherwise you should go back and read the tutorial). -The git-whatchanged command internally runs -the equivalent of the above command, and can be used like this: - - $ git-whatchanged -p -S'if (frotz) { - nitfol(); - }' - -When the -S option is used, git-diff-tree command outputs -differences between two commits only if one tree has the -specified string in a file and the corresponding file in the -other tree does not. The above example looks for a commit that -has the "if" statement in it in a file, but its parent commit -does not have it in the same shape in the corresponding file (or -the other way around, where the parent has it and the commit -does not), and the differences between them are shown, along -with the commit message (thanks to the -v flag). It does not -show anything for commits that do not touch this "if" statement. - -Also, in the original context, the same statement might have -appeared at first in a different file and later the file was -renamed to "a-file.c". CVS annotate would not help you to go -back across such a rename, but git would still help you in such -a situation. For that, you can give the -C flag to -git-diff-tree, like this: - - $ git-whatchanged -p -C -S'if (frotz) { - nitfol(); - }' - -When the -C flag is used, file renames and copies are followed. -So if the "if" statement in question happens to be in "a-file.c" -in the current HEAD commit, even if the file was originally -called "o-file.c" and then renamed in an earlier commit, or if -the file was created by copying an existing "o-file.c" in an -earlier commit, you will not lose track. If the "if" statement -did not change across such a rename or copy, then the commit that -does rename or copy would not show in the output, and if the -"if" statement was modified while the file was still called -"o-file.c", it would find the commit that changed the statement -when it was in "o-file.c". - -NOTE: The current version of "git-diff-tree -C" is not eager - enough to find copies, and it will miss the fact that a-file.c - was created by copying o-file.c unless o-file.c was somehow - changed in the same commit. - -You can use the --pickaxe-all flag in addition to the -S flag. -This causes the differences from all the files contained in -those two commits, not just the differences between the files -that contain this changed "if" statement: - - $ git-whatchanged -p -C -S'if (frotz) { - nitfol(); - }' --pickaxe-all - -NOTE: This option is called "--pickaxe-all" because -S - option is internally called "pickaxe", a tool for software - archaeologists. diff --git a/Documentation/diff-format.txt b/Documentation/diff-format.txt index 617d8f526f..883c1bb0a6 100644 --- a/Documentation/diff-format.txt +++ b/Documentation/diff-format.txt @@ -65,62 +65,17 @@ Generating patches with -p When "git-diff-index", "git-diff-tree", or "git-diff-files" are run with a '-p' option, they do not produce the output described above; -instead they produce a patch file. +instead they produce a patch file. You can customize the creation +of such patches via the GIT_EXTERNAL_DIFF and the GIT_DIFF_OPTS +environment variables. -The patch generation can be customized at two levels. - -1. When the environment variable 'GIT_EXTERNAL_DIFF' is not set, - these commands internally invoke "diff" like this: - - diff -L a/ -L b/ -pu -+ -For added files, `/dev/null` is used for . For removed -files, `/dev/null` is used for -+ -The "diff" formatting options can be customized via the -environment variable 'GIT_DIFF_OPTS'. For example, if you -prefer context diff: - - GIT_DIFF_OPTS=-c git-diff-index -p HEAD - - -2. When the environment variable 'GIT_EXTERNAL_DIFF' is set, the - program named by it is called, instead of the diff invocation - described above. -+ -For a path that is added, removed, or modified, -'GIT_EXTERNAL_DIFF' is called with 7 parameters: - - path old-file old-hex old-mode new-file new-hex new-mode -+ -where: - - -file:: are files GIT_EXTERNAL_DIFF can use to read the - contents of , - -hex:: are the 40-hexdigit SHA1 hashes, - -mode:: are the octal representation of the file modes. - -+ -The file parameters can point at the user's working file -(e.g. `new-file` in "git-diff-files"), `/dev/null` (e.g. `old-file` -when a new file is added), or a temporary file (e.g. `old-file` in the -index). 'GIT_EXTERNAL_DIFF' should not worry about unlinking the -temporary file --- it is removed when 'GIT_EXTERNAL_DIFF' exits. - -For a path that is unmerged, 'GIT_EXTERNAL_DIFF' is called with 1 -parameter, . - - -git specific extension to diff format -------------------------------------- - -What -p option produces is slightly different from the -traditional diff format. +What the -p option produces is slightly different from the traditional +diff format. 1. It is preceded with a "git diff" header, that looks like this: - diff --git a/file1 b/file2 + diff --git a/file1 b/file2 + The `a/` and `b/` filenames are the same unless rename/copy is involved. Especially, even for a creation or a deletion, @@ -144,8 +99,10 @@ the file that rename/copy produces, respectively. dissimilarity index index .. -3. TAB, LF, and backslash characters in pathnames are - represented as `\t`, `\n`, and `\\`, respectively. +3. TAB, LF, double quote and backslash characters in pathnames + are represented as `\t`, `\n`, `\"` and `\\`, respectively. + If there is need for such substitution then the whole + pathname is put in double quotes. combined diff format @@ -156,31 +113,91 @@ to produce 'combined diff', which looks like this: ------------ diff --combined describe.c -@@@ +98,7 @@@ - return (a_date > b_date) ? -1 : (a_date == b_date) ? 0 : 1; +index fabadb8,cc95eb0..4866510 +--- a/describe.c ++++ b/describe.c +@@@ -98,20 -98,12 +98,20 @@@ + return (a_date > b_date) ? -1 : (a_date == b_date) ? 0 : 1; } - + - static void describe(char *arg) -static void describe(struct commit *cmit, int last_one) ++static void describe(char *arg, int last_one) { - + unsigned char sha1[20]; - + struct commit *cmit; + + unsigned char sha1[20]; + + struct commit *cmit; + struct commit_list *list; + static int initialized = 0; + struct commit_name *n; + + + if (get_sha1(arg, sha1) < 0) + + usage(describe_usage); + + cmit = lookup_commit_reference(sha1); + + if (!cmit) + + usage(describe_usage); + + + if (!initialized) { + initialized = 1; + for_each_ref(get_name); ------------ +1. It is preceded with a "git diff" header, that looks like + this (when '-c' option is used): + + diff --combined file ++ +or like this (when '--cc' option is used): + + diff --c file + +2. It is followed by one or more extended header lines + (this example shows a merge with two parents): + + index ,.. + mode ,.. + new file mode + deleted file mode , ++ +The `mode ,..` line appears only if at least one of +the is diferent from the rest. Extended headers with +information about detected contents movement (renames and +copying detection) are designed to work with diff of two + and are not used by combined diff format. + +3. It is followed by two-line from-file/to-file header + + --- a/file + +++ b/file ++ +Similar to two-line header for traditional 'unified' diff +format, `/dev/null` is used to signal created or deleted +files. + +4. Chunk header format is modified to prevent people from + accidentally feeding it to `patch -p1`. Combined diff format + was created for review of merge commit changes, and was not + meant for apply. The change is similar to the change in the + extended 'index' header: + + @@@ @@@ ++ +There are (number of parents + 1) `@` characters in the chunk +header for combined diff format. + Unlike the traditional 'unified' diff format, which shows two files A and B with a single column that has `-` (minus -- appears in A but removed in B), `+` (plus -- missing in A but -added to B), or ` ` (space -- unchanged) prefix, this format +added to B), or `" "` (space -- unchanged) prefix, this format compares two or more files file1, file2,... with one file X, and shows how X differs from each of fileN. One column for each of fileN is prepended to the output line to note how X's line is different from it. A `-` character in the column N means that the line appears in -fileN but it does not appear in the last file. A `+` character +fileN but it does not appear in the result. A `+` character in the column N means that the line appears in the last file, -and fileN does not have that line. +and fileN does not have that line (in other words, the line was +added, from the point of view of that parent). In the above example output, the function signature was changed from both files (hence two `-` removals from both file1 and diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index b5d9763594..da1cc60e97 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -10,8 +10,23 @@ --patch-with-raw:: Synonym for "-p --raw". ---stat:: - Generate a diffstat. +--stat[=width[,name-width]]:: + Generate a diffstat. You can override the default + output width for 80-column terminal by "--stat=width". + The width of the filename part can be controlled by + giving another width to it separated by a comma. + +--numstat:: + Similar to \--stat, but shows number of added and + deleted lines in decimal notation and pathname without + abbreviation, to make it more machine friendly. For + binary files, outputs two `-` instead of saying + `0 0`. + +--shortstat:: + Output only the last line of the --stat format containing total + number of modified files, as well as number of added and deleted + lines. --summary:: Output a condensed summary of extended header information @@ -121,5 +136,21 @@ -a:: Shorthand for "--text". +--ignore-space-change:: + Ignore changes in amount of white space. This ignores white + space at line end, and consider all other sequences of one or + more white space characters to be equivalent. + +-b:: + Shorthand for "--ignore-space-change". + +--ignore-all-space:: + Ignore white space when comparing lines. This ignores + difference even if one line has white space where the other + line has none. + +-w:: + Shorthand for "--ignore-all-space". + For more detailed explanation on these common options, see also link:diffcore.html[diffcore documentation]. diff --git a/Documentation/everyday.txt b/Documentation/everyday.txt index b935c18088..4e83994c58 100644 --- a/Documentation/everyday.txt +++ b/Documentation/everyday.txt @@ -1,22 +1,7 @@ Everyday GIT With 20 Commands Or So =================================== -GIT suite has over 100 commands, and the manual page for each of -them discusses what the command does and how it is used in -detail, but until you know what command should be used in order -to achieve what you want to do, you cannot tell which manual -page to look at, and if you know that already you do not need -the manual. - -Does that mean you need to know all of them before you can use -git? Not at all. Depending on the role you play, the set of -commands you need to know is slightly different, but in any case -what you need to learn is far smaller than the full set of -commands to carry out your day-to-day work. This document is to -serve as a cheat-sheet and a set of pointers for people playing -various roles. - -<> commands are needed by people who has a +<> commands are needed by people who have a repository --- that is everybody, because every working tree of git is a repository. @@ -25,31 +10,33 @@ essential for anybody who makes a commit, even for somebody who works alone. If you work with other people, you will need commands listed in -<> section as well. +the <> section as well. -People who play <> role need to learn some more +People who play the <> role need to learn some more commands in addition to the above. <> commands are for system -administrators who are responsible to care and feed git -repositories to support developers. +administrators who are responsible for the care and feeding +of git repositories. Basic Repository[[Basic Repository]] ------------------------------------ -Everybody uses these commands to feed and care git repositories. +Everybody uses these commands to maintain git repositories. - * gitlink:git-init-db[1] or gitlink:git-clone[1] to create a + * gitlink:git-init[1] or gitlink:git-clone[1] to create a new repository. - * gitlink:git-fsck-objects[1] to validate the repository. + * gitlink:git-fsck-objects[1] to check the repository for errors. - * gitlink:git-prune[1] to garbage collect cruft in the - repository. + * gitlink:git-prune[1] to remove unused objects in the repository. * gitlink:git-repack[1] to pack loose objects for efficiency. + * gitlink:git-gc[1] to do common housekeeping tasks such as + repack and prune. + Examples ~~~~~~~~ @@ -57,19 +44,19 @@ Check health and remove cruft.:: + ------------ $ git fsck-objects <1> -$ git prune $ git count-objects <2> $ git repack <3> -$ git prune <4> +$ git gc <4> ------------ + -<1> running without "--full" is usually cheap and assures the +<1> running without `\--full` is usually cheap and assures the repository health reasonably well. <2> check how many loose objects there are and how much disk space is wasted by not repacking. -<3> without "-a" repacks incrementally. repacking every 4-5MB +<3> without `-a` repacks incrementally. repacking every 4-5MB of loose objects accumulation may be a good rule of thumb. -<4> after repack, prune removes the duplicate loose objects. +<4> it is easier to use `git gc` than individual housekeeping commands +such as `prune` and `repack`. This runs `repack -a -d`. Repack a small project into single pack.:: + @@ -78,8 +65,8 @@ $ git repack -a -d <1> $ git prune ------------ + -<1> pack all the objects reachable from the refs into one pack -and remove unneeded other packs +<1> pack all the objects reachable from the refs into one pack, +then remove the other packs. Individual Developer (Standalone)[[Individual Developer (Standalone)]] @@ -93,14 +80,10 @@ following commands. * gitlink:git-log[1] to see what happened. - * gitlink:git-whatchanged[1] to find out where things have - come from. - * gitlink:git-checkout[1] and gitlink:git-branch[1] to switch branches. - * gitlink:git-add[1] and gitlink:git-update-index[1] to manage - the index file. + * gitlink:git-add[1] to manage the index file. * gitlink:git-diff[1] and gitlink:git-status[1] to see what you are in the middle of doing. @@ -110,8 +93,7 @@ following commands. * gitlink:git-reset[1] and gitlink:git-checkout[1] (with pathname parameters) to undo changes. - * gitlink:git-pull[1] with "." as the remote to merge between - local branches. + * gitlink:git-merge[1] to merge between local branches. * gitlink:git-rebase[1] to maintain topic branches. @@ -120,12 +102,12 @@ following commands. Examples ~~~~~~~~ -Extract a tarball and create a working tree and a new repository to keep track of it.:: +Use a tarball as a starting point for a new repository.:: + ------------ $ tar zxf frotz.tar.gz $ cd frotz -$ git-init-db +$ git-init $ git add . <1> $ git commit -m 'import of frotz source tree.' $ git tag v2.43 <2> @@ -142,7 +124,7 @@ $ edit/compile/test $ git checkout -- curses/ux_audio_oss.c <2> $ git add curses/ux_audio_alsa.c <3> $ edit/compile/test -$ git diff <4> +$ git diff HEAD <4> $ git commit -a -s <5> $ edit/compile/test $ git reset --soft HEAD^ <6> @@ -150,15 +132,15 @@ $ edit/compile/test $ git diff ORIG_HEAD <7> $ git commit -a -c ORIG_HEAD <8> $ git checkout master <9> -$ git pull . alsa-audio <10> +$ git merge alsa-audio <10> $ git log --since='3 days ago' <11> $ git log v2.43.. curses/ <12> ------------ + <1> create a new topic branch. -<2> revert your botched changes in "curses/ux_audio_oss.c". +<2> revert your botched changes in `curses/ux_audio_oss.c`. <3> you need to tell git if you added a new file; removal and -modification will be caught if you do "commit -a" later. +modification will be caught if you do `git commit -a` later. <4> to see what changes you are committing. <5> commit everything as you have tested, with your sign-off. <6> take the last commit back, keeping what is in the working tree. @@ -166,11 +148,13 @@ modification will be caught if you do "commit -a" later. <8> redo the commit undone in the previous step, using the message you originally wrote. <9> switch to the master branch. -<10> merge a topic branch into your master branch +<10> merge a topic branch into your master branch. You can also use +`git pull . alsa-audio`, i.e. pull from the local repository. <11> review commit logs; other forms to limit output can be -combined and include --max-count=10 (show 10 commits), --until='2005-12-10'. -<12> view only the changes that touch what's in curses/ -directory, since v2.43 tag. +combined and include `\--max-count=10` (show 10 commits), +`\--until=2005-12-10`, etc. +<12> view only the changes that touch what's in `curses/` +directory, since `v2.43` tag. Individual Developer (Participant)[[Individual Developer (Participant)]] @@ -203,7 +187,7 @@ $ cd my2.6 $ edit/compile/test; git commit -a -s <1> $ git format-patch origin <2> $ git pull <3> -$ git whatchanged -p ORIG_HEAD.. arch/i386 include/asm-i386 <4> +$ git log -p ORIG_HEAD.. arch/i386 include/asm-i386 <4> $ git pull git://git.kernel.org/pub/.../jgarzik/libata-dev.git ALL <5> $ git reset --hard ORIG_HEAD <6> $ git prune <7> @@ -212,7 +196,7 @@ $ git fetch --tags <8> + <1> repeat as needed. <2> extract patches from your branch for e-mail submission. -<3> "pull" fetches from "origin" by default and merges into the +<3> `git pull` fetches from `origin` by default and merges into the current branch. <4> immediately after pulling, look at the changes done upstream since last time we checked, only in the @@ -220,37 +204,41 @@ area we are interested in. <5> fetch from a specific branch from a specific repository and merge. <6> revert the pull. <7> garbage collect leftover objects from reverted pull. -<8> from time to time, obtain official tags from the "origin" -and store them under .git/refs/tags/. +<8> from time to time, obtain official tags from the `origin` +and store them under `.git/refs/tags/`. Push into another repository.:: + ------------ -satellite$ git clone mothership:frotz/.git frotz <1> +satellite$ git clone mothership:frotz frotz <1> satellite$ cd frotz -satellite$ cat .git/remotes/origin <2> -URL: mothership:frotz/.git -Pull: master:origin -satellite$ echo 'Push: master:satellite' >>.git/remotes/origin <3> +satellite$ git repo-config --get-regexp '^(remote|branch)\.' <2> +remote.origin.url mothership:frotz +remote.origin.fetch refs/heads/*:refs/remotes/origin/* +branch.master.remote origin +branch.master.merge refs/heads/master +satellite$ git repo-config remote.origin.push \ + master:refs/remotes/satellite/master <3> satellite$ edit/compile/test/commit satellite$ git push origin <4> mothership$ cd frotz mothership$ git checkout master -mothership$ git pull . satellite <5> +mothership$ git merge satellite/master <5> ------------ + <1> mothership machine has a frotz repository under your home directory; clone from it to start a repository on the satellite machine. -<2> clone creates this file by default. It arranges "git pull" -to fetch and store the master branch head of mothership machine -to local "origin" branch. -<3> arrange "git push" to push local "master" branch to -"satellite" branch of the mothership machine. -<4> push will stash our work away on "satellite" branch on the -mothership machine. You could use this as a back-up method. +<2> clone sets these configuration variables by default. +It arranges `git pull` to fetch and store the branches of mothership +machine to local `remotes/origin/*` tracking branches. +<3> arrange `git push` to push local `master` branch to +`remotes/satellite/master` branch of the mothership machine. +<4> push will stash our work away on `remotes/satellite/master` +tracking branch on the mothership machine. You could use this as +a back-up method. <5> on mothership machine, merge the work done on the satellite machine into the master branch. @@ -266,7 +254,7 @@ $ git format-patch -k -m --stdout v2.6.14..private2.6.14 | + <1> create a private branch based on a well known (but somewhat behind) tag. -<2> forward port all changes in private2.6.14 branch to master branch +<2> forward port all changes in `private2.6.14` branch to `master` branch without a formal "merging". @@ -303,13 +291,13 @@ $ mailx <3> & s 2 3 4 5 ./+to-apply & s 7 8 ./+hold-linus & q -$ git checkout master +$ git checkout -b topic/one master $ git am -3 -i -s -u ./+to-apply <4> $ compile/test $ git checkout -b hold/linus && git am -3 -i -s -u ./+hold-linus <5> $ git checkout topic/one && git rebase master <6> -$ git checkout pu && git reset --hard master <7> -$ git pull . topic/one topic/two && git pull . hold/linus <8> +$ git checkout pu && git reset --hard next <7> +$ git merge topic/one topic/two && git merge hold/linus <8> $ git checkout maint $ git cherry-pick master~4 <9> $ compile/test @@ -326,29 +314,32 @@ they are. that are not quite ready. <4> apply them, interactively, with my sign-offs. <5> create topic branch as needed and apply, again with my -sign-offs. +sign-offs. <6> rebase internal topic branch that has not been merged to the master, nor exposed as a part of a stable branch. -<7> restart "pu" every time from the master. +<7> restart `pu` every time from the next. <8> and bundle topic branches still cooking. <9> backport a critical fix. <10> create a signed tag. <11> make sure I did not accidentally rewind master beyond what I -already pushed out. "ko" shorthand points at the repository I have +already pushed out. `ko` shorthand points at the repository I have at kernel.org, and looks like this: + ------------ $ cat .git/remotes/ko URL: kernel.org:/pub/scm/git/git.git Pull: master:refs/tags/ko-master +Pull: next:refs/tags/ko-next Pull: maint:refs/tags/ko-maint Push: master +Push: next Push: +pu Push: maint ------------ + -In the output from "git show-branch", "master" should have -everything "ko-master" has. +In the output from `git show-branch`, `master` should have +everything `ko-master` has, and `next` should have +everything `ko-next` has. <12> push out the bleeding edge. <13> push the tag out, too. @@ -372,12 +363,19 @@ example of managing a shared central repository. Examples ~~~~~~~~ +We assume the following in /etc/services:: ++ +------------ +$ grep 9418 /etc/services +git 9418/tcp # Git Version Control System +------------ + Run git-daemon to serve /pub/scm from inetd.:: + ------------ $ grep git /etc/inetd.conf git stream tcp nowait nobody \ - /usr/bin/git-daemon git-daemon --inetd --syslog --export-all /pub/scm + /usr/bin/git-daemon git-daemon --inetd --export-all /pub/scm ------------ + The actual configuration line should be on one line. @@ -397,7 +395,7 @@ service git wait = no user = nobody server = /usr/bin/git-daemon - server_args = --inetd --syslog --export-all --base-path=/pub/scm + server_args = --inetd --export-all --base-path=/pub/scm log_on_failure += USERID } ------------ @@ -418,7 +416,7 @@ $ grep git /etc/shells <2> ------------ + <1> log-in shell is set to /usr/bin/git-shell, which does not -allow anything but "git push" and "git pull". The users should +allow anything but `git push` and `git pull`. The users should get an ssh access to the machine. <2> in many distributions /etc/shells needs to list what is used as the login shell. diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt index 13f34d3ca2..5b4d184a73 100644 --- a/Documentation/fetch-options.txt +++ b/Documentation/fetch-options.txt @@ -36,6 +36,13 @@ -u, \--update-head-ok:: By default `git-fetch` refuses to update the head which corresponds to the current branch. This flag disables the - check. Note that fetching into the current branch will not - update the index and working directory, so use it with care. + check. This is purely for the internal use for `git-pull` + to communicate with `git-fetch`, and unless you are + implementing your own Porcelain you are not supposed to + use it. + +\--depth=:: + Deepen the history of a 'shallow' repository created by + `git clone` with `--depth=` option (see gitlink:git-clone[1]) + by the specified number of commits. diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt index 6342ea33e4..95bea66374 100644 --- a/Documentation/git-add.txt +++ b/Documentation/git-add.txt @@ -3,24 +3,45 @@ git-add(1) NAME ---- -git-add - Add files to the index file +git-add - Add file contents to the changeset to be committed next SYNOPSIS -------- -'git-add' [-n] [-v] [--] ... +'git-add' [-n] [-v] [-f] [--interactive] [--] ... DESCRIPTION ----------- -A simple wrapper for git-update-index to add files to the index, -for people used to do "cvs add". +All the changed file contents to be committed together in a single set +of changes must be "added" with the 'add' command before using the +'commit' command. This is not only for adding new files. Even modified +files must be added to the set of changes about to be committed. + +This command can be performed multiple times before a commit. The added +content corresponds to the state of specified file(s) at the time the +'add' command is used. This means the 'commit' command will not consider +subsequent changes to already added content if it is not added again before +the commit. + +The 'git status' command can be used to obtain a summary of what is included +for the next commit. + +This command can be used to add ignored files with `-f` (force) +option, but they have to be +explicitly and exactly specified from the command line. File globbing +and recursive behaviour do not add ignored files. + +Please see gitlink:git-commit[1] for alternative ways to add content to a +commit. -It only adds non-ignored files, to add ignored files use -"git update-index --add". OPTIONS ------- ...:: - Files to add to the index (see gitlink:git-ls-files[1]). + Files to add content from. Fileglobs (e.g. `*.c`) can + be given to add all matching files. Also a + leading directory name (e.g. `dir` to add `dir/file1` + and `dir/file2`) can be given to add all files in the + directory, recursively. -n:: Don't actually add the file(s), just show if they exist. @@ -28,33 +49,25 @@ OPTIONS -v:: Be verbose. +-f:: + Allow adding otherwise ignored files. + +\--interactive:: + Add modified contents in the working tree interactively to + the index. + \--:: This option can be used to separate command-line options from the list of files, (useful when filenames might be mistaken for command-line options). -DISCUSSION ----------- - -The list of given to the command is fed to `git-ls-files` -command to list files that are not registered in the index and -are not ignored/excluded by `$GIT_DIR/info/exclude` file or -`.gitignore` file in each directory. This means two things: - -. You can put the name of a directory on the command line, and - the command will add all files in it and its subdirectories; - -. Giving the name of a file that is already in index does not - run `git-update-index` on that path. - - EXAMPLES -------- git-add Documentation/\\*.txt:: - Adds all `\*.txt` files that are not in the index under - `Documentation` directory and its subdirectories. + Adds content from all `\*.txt` files under `Documentation` + directory and its subdirectories. + Note that the asterisk `\*` is quoted from the shell in this example; this lets the command to include the files from @@ -62,15 +75,131 @@ subdirectories of `Documentation/` directory. git-add git-*.sh:: - Adds all git-*.sh scripts that are not in the index. + Considers adding content from all git-*.sh scripts. Because this example lets shell expand the asterisk (i.e. you are listing the files explicitly), it does not - add `subdir/git-foo.sh` to the index. + consider `subdir/git-foo.sh`. + +Interactive mode +---------------- +When the command enters the interactive mode, it shows the +output of the 'status' subcommand, and then goes into ints +interactive command loop. + +The command loop shows the list of subcommands available, and +gives a prompt "What now> ". In general, when the prompt ends +with a single '>', you can pick only one of the choices given +and type return, like this: + +------------ + *** Commands *** + 1: status 2: update 3: revert 4: add untracked + 5: patch 6: diff 7: quit 8: help + What now> 1 +------------ + +You also could say "s" or "sta" or "status" above as long as the +choice is unique. + +The main command loop has 6 subcommands (plus help and quit). + +status:: + + This shows the change between HEAD and index (i.e. what will be + committed if you say "git commit"), and between index and + working tree files (i.e. what you could stage further before + "git commit" using "git-add") for each path. A sample output + looks like this: ++ +------------ + staged unstaged path + 1: binary nothing foo.png + 2: +403/-35 +1/-1 git-add--interactive.perl +------------ ++ +It shows that foo.png has differences from HEAD (but that is +binary so line count cannot be shown) and there is no +difference between indexed copy and the working tree +version (if the working tree version were also different, +'binary' would have been shown in place of 'nothing'). The +other file, git-add--interactive.perl, has 403 lines added +and 35 lines deleted if you commit what is in the index, but +working tree file has further modifications (one addition and +one deletion). + +update:: + + This shows the status information and gives prompt + "Update>>". When the prompt ends with double '>>', you can + make more than one selection, concatenated with whitespace or + comma. Also you can say ranges. E.g. "2-5 7,9" to choose + 2,3,4,5,7,9 from the list. You can say '*' to choose + everything. ++ +What you chose are then highlighted with '*', +like this: ++ +------------ + staged unstaged path + 1: binary nothing foo.png +* 2: +403/-35 +1/-1 git-add--interactive.perl +------------ ++ +To remove selection, prefix the input with `-` +like this: ++ +------------ +Update>> -2 +------------ ++ +After making the selection, answer with an empty line to stage the +contents of working tree files for selected paths in the index. + +revert:: + + This has a very similar UI to 'update', and the staged + information for selected paths are reverted to that of the + HEAD version. Reverting new paths makes them untracked. + +add untracked:: + + This has a very similar UI to 'update' and + 'revert', and lets you add untracked paths to the index. + +patch:: + + This lets you choose one path out of 'status' like selection. + After choosing the path, it presents diff between the index + and the working tree file and asks you if you want to stage + the change of each hunk. You can say: + + y - add the change from that hunk to index + n - do not add the change from that hunk to index + a - add the change from that hunk and all the rest to index + d - do not the change from that hunk nor any of the rest to index + j - do not decide on this hunk now, and view the next + undecided hunk + J - do not decide on this hunk now, and view the next hunk + k - do not decide on this hunk now, and view the previous + undecided hunk + K - do not decide on this hunk now, and view the previous hunk ++ +After deciding the fate for all hunks, if there is any hunk +that was chosen, the index is updated with the selected hunks. + +diff:: + + This lets you review what will be committed (i.e. between + HEAD and index). + See Also -------- +gitlink:git-status[1] gitlink:git-rm[1] -gitlink:git-ls-files[1] +gitlink:git-mv[1] +gitlink:git-commit[1] +gitlink:git-update-index[1] Author ------ diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt index 910457d3b3..53e81cb103 100644 --- a/Documentation/git-am.txt +++ b/Documentation/git-am.txt @@ -9,7 +9,7 @@ git-am - Apply a series of patches in a mailbox SYNOPSIS -------- [verse] -'git-am' [--signoff] [--dotest=] [--utf8] [--binary] [--3way] +'git-am' [--signoff] [--dotest=] [--utf8 | --no-utf8] [--binary] [--3way] [--interactive] [--whitespace=