diff options
| author | Shawn O. Pearce <spearce@spearce.org> | 2007-01-14 02:44:18 -0500 |
|---|---|---|
| committer | Shawn O. Pearce <spearce@spearce.org> | 2007-01-14 02:44:18 -0500 |
| commit | 1fcdd62adf81a172f45c7c6a58177212d500b9d9 (patch) | |
| tree | 94acde078fd78c3d214fe09d45e85ed346a2f2d4 /Documentation | |
| parent | 9938ffc53a15c755bbd3894c02492b940ea34c4c (diff) | |
| parent | 696b1b507f8ff9e80a2edc4eced59ca8cdda920e (diff) | |
| download | git-1fcdd62adf81a172f45c7c6a58177212d500b9d9.tar.gz git-1fcdd62adf81a172f45c7c6a58177212d500b9d9.tar.xz | |
Merge branch 'master' into sp/fast-import
I'm bringing master in early so that the OBJ_OFS_DELTA implementation
is available as part of the topic. This way git-fast-import can
learn about this new slightly smaller and faster packfile format,
and can generate them directly rather than needing to have them be
repacked with git-pack-objects.
Due to the API changes in master during the period of development
of git-fast-import, a few minor tweaks to fast-import.c are needed
to produce a working merge. I've done them here as part of the
merge to ensure bisection always works.
Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
Diffstat (limited to 'Documentation')
93 files changed, 4364 insertions, 1526 deletions
diff --git a/Documentation/Makefile b/Documentation/Makefile index 0d9ffb4ad..93c7024b4 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 90722c21f..646b6e733 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 <random@developer.example.org> +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 8196d787a..44b1ce4c6 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 ad03755d8..6a361a213 100644 --- a/Documentation/callouts.xsl +++ b/Documentation/callouts.xsl @@ -13,4 +13,18 @@ <xsl:apply-templates/> <xsl:text>.br </xsl:text> </xsl:template> + +<!-- sorry, this is not about callouts, but attempts to work around + spurious .sp at the tail of the line docbook stylesheets seem to add --> +<xsl:template match="simpara"> + <xsl:variable name="content"> + <xsl:apply-templates/> + </xsl:variable> + <xsl:value-of select="normalize-space($content)"/> + <xsl:if test="not(ancestor::authorblurb) and + not(ancestor::personblurb)"> + <xsl:text> </xsl:text> + </xsl:if> +</xsl:template> + </xsl:stylesheet> diff --git a/Documentation/config.txt b/Documentation/config.txt index ce722a2db..f7dba8977 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/<ref>" 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 <ref> is logged to the file + "$GIT_DIR/logs/<ref>", 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/<ref>" + 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). - -diff.color:: +branch.<name>.remote:: + When in branch <name>, it tells `git fetch` which remote to fetch. + If this option is not given, `git fetch` defaults to remote "origin". + +branch.<name>.merge:: + When in branch <name>, 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.<name>.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.<slot>:: + Use customized color for branch coloration. `<slot>` 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.<slot>:: +color.diff.<slot>:: Use customized color for diff colorization. `<slot>` 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.<slot>. + +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.<slot>:: + Use customized color for status colorization. `<slot>` 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.<slot>. 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.<name>.url:: + The URL of a remote repository. See gitlink:git-fetch[1] or + gitlink:git-push[1]. + +remote.<name>.fetch:: + The default set of "refspec" for gitlink:git-fetch[1]. See + gitlink:git-fetch[1]. + +remote.<name>.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 1185897f7..0cd33fb5b 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 d2b0bd38d..775bf4266 100644 --- a/Documentation/cvs-migration.txt +++ b/Documentation/cvs-migration.txt @@ -1,90 +1,87 @@ 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. - - * Offline work is supported: you can make multiple commits locally, - then submit them when you're ready. - - * Branching is fast and easy. +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: - * 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 clone foo.com:/pub/repo.git/ my-project +$ cd my-project +------------------------------------------------ -Importing a CVS archive ------------------------ +and hack away. The equivalent of `cvs update` is -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 +------------------------------------------------ +$ git pull origin +------------------------------------------------ -------------------------------------------- -$ git cvsimport -v -d <cvsroot> -C <destination> <module> -------------------------------------------- +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. -This puts a git archive of the named CVS module in the directory -<destination>, which will be created if necessary. The -v option makes -the conversion script very chatty. +[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. +================================ -The import checks out from CVS every revision of every file. Reportedly -cvsimport can average some twenty revisions per second, so for a -medium-sized project this should not take more than a couple of minutes. -Larger projects or remote repositories may take longer. +You can update the shared repository with your changes by first committing +your changes, and then using the gitlink:git-push[1] command: -The main trunk is stored in the git branch named `origin`, and additional -CVS branches are stored in git branches with the same names. The most -recent version of the main trunk is also left checked out on the `master` -branch, so you can start adding your own changes right away. +------------------------------------------------ +$ git push origin master +------------------------------------------------ -The import is incremental, so if you call it again next month it will -fetch any CVS updates that have been made in the meantime. For this to -work, you must not modify the imported branches; instead, create new -branches for your own changes, and merge in the imported branches as -necessary. +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. -Development Models ------------------- +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: -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. +------------ +$ git push origin +$ git push foo.com:/pub/project.git/ +------------ -For example, you can choose a single person to maintain the project's -primary public repository. Other developers then clone this repository -and each work in their own clone. When they have a series of changes that -they're happy with, they ask the maintainer to pull from the branch -containing the changes. The maintainer reviews their changes and pulls -them into the primary repository, which other developers pull from as -necessary to stay coordinated. The Linux kernel and other projects use -variants of this model. +as long as the shared repository does not have any branches +other than `master`. -With a small group, developers may just pull changes from each other's -repositories without the need for a central maintainer. +Setting Up a Shared Repository +------------------------------ -Emulating the CVS Development Model ------------------------------------ +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). -Start with an ordinary git working directory containing the project, and -remove the checked-out files, keeping just the bare .git directory: +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: ------------------------------------------------ -$ mv project/.git /pub/repo.git -$ rm -r project/ +$ 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 @@ -97,208 +94,78 @@ 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 +$ 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. -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: +Importing a CVS archive +----------------------- ------------------------------------------------- -$ git push origin master ------------------------------------------------- +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. Then cd to a checked out CVS working directory +of the project you are interested in and run gitlink:git-cvsimport[1]: -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. +------------------------------------------- +$ git cvsimport -C <destination> +------------------------------------------- -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: +This puts a git archive of the named CVS module in the directory +<destination>, which will be created if necessary. ------------- -$ git push origin -$ git push repo.shared.xz:/pub/scm/project.git/ ------------- +The import checks out from CVS every revision of every file. Reportedly +cvsimport can average some twenty revisions per second, so for a +medium-sized project this should not take more than a couple of minutes. +Larger projects or remote repositories may take longer. -as long as the shared repository does not have any branches -other than `master`. +The main trunk is stored in the git branch named `origin`, and additional +CVS branches are stored in git branches with the same names. The most +recent version of the main trunk is also left checked out on the `master` +branch, so you can start adding your own changes right away. -[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. -============ +The import is incremental, so if you call it again next month it will +fetch any CVS updates that have been made in the meantime. For this to +work, you must not modify the imported branches; instead, create new +branches for your own changes, and merge in the imported branches as +necessary. 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]. +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]. -CVS annotate ------------- +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. 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 +and each work in their own clone. When they have a series of changes that +they're happy with, they ask the maintainer to pull from the branch +containing the changes. The maintainer reviews their changes and pulls +them into the primary repository, which other developers pull from as +necessary to stay coordinated. The Linux kernel and other projects use +variants of this model. -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. +With a small group, developers may just pull changes from each other's +repositories without the need for a central maintainer. diff --git a/Documentation/diff-format.txt b/Documentation/diff-format.txt index 617d8f526..883c1bb0a 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/<path> -L b/<path> -pu <old> <new> -+ -For added files, `/dev/null` is used for <old>. For removed -files, `/dev/null` is used for <new> -+ -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: - - <old|new>-file:: are files GIT_EXTERNAL_DIFF can use to read the - contents of <old|new>, - <old|new>-hex:: are the 40-hexdigit SHA1 hashes, - <old|new>-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, <path>. - - -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 <number> index <hash>..<hash> <mode> -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 <hash>,<hash>..<hash> + mode <mode>,<mode>..<mode> + new file mode <mode> + deleted file mode <mode>,<mode> ++ +The `mode <mode>,<mode>..<mode>` line appears only if at least one of +the <mode> 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 +<tree-ish> 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: + + @@@ <from-file-range> <from-file-range> <to-file-range> @@@ ++ +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 b5d976359..da1cc60e9 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 b935c1808..4e83994c5 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. - -<<Basic Repository>> commands are needed by people who has a +<<Basic Repository>> 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 -<<Individual Developer (Participant)>> section as well. +the <<Individual Developer (Participant)>> section as well. -People who play <<Integrator>> role need to learn some more +People who play the <<Integrator>> role need to learn some more commands in addition to the above. <<Repository Administration>> 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 13f34d3ca..5b4d184a7 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=<depth>:: + Deepen the history of a 'shallow' repository created by + `git clone` with `--depth=<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 6342ea33e..95bea6637 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] [--] <file>... +'git-add' [-n] [-v] [-f] [--interactive] [--] <file>... 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 ------- <file>...:: - 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 <file> 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 910457d3b..53e81cb10 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=<dir>] [--utf8] [--binary] [--3way] +'git-am' [--signoff] [--dotest=<dir>] [--utf8 | --no-utf8] [--binary] [--3way] [--interactive] [--whitespace=<option>] <mbox>... 'git-am' [--skip | --resolved] @@ -29,8 +29,21 @@ OPTIONS Instead of `.dotest` directory, use <dir> as a working area to store extracted patches. ---utf8, --keep:: - Pass `-u` and `-k` flags to `git-mailinfo` (see +--keep:: + Pass `-k` flag to `git-mailinfo` (see gitlink:git-mailinfo[1]). + +--utf8:: + Pass `-u` flag to `git-mailinfo` (see gitlink:git-mailinfo[1]). + The proposed commit log message taken from the e-mail + are re-coded into UTF-8 encoding (configuration variable + `i18n.commitencoding` can be used to specify project's + preferred encoding if it is not UTF-8). ++ +This was optional in prior versions of git, but now it is the +default. You could use `--no-utf8` to override this. + +--no-utf8:: + Do not pass `-u` flag to `git-mailinfo` (see gitlink:git-mailinfo[1]). --binary:: diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt index 2ff74949a..33b93db50 100644 --- a/Documentation/git-apply.txt +++ b/Documentation/git-apply.txt @@ -10,9 +10,10 @@ SYNOPSIS -------- [verse] 'git-apply' [--stat] [--numstat] [--summary] [--check] [--index] [--apply] - [--no-add] [--index-info] [--allow-binary-replacement] [-z] [-pNUM] - [-CNUM] [--whitespace=<nowarn|warn|error|error-all|strip>] - [<patch>...] + [--no-add] [--index-info] [--allow-binary-replacement | --binary] + [-R | --reverse] [--reject] [-z] [-pNUM] [-CNUM] [--inaccurate-eof] + [--whitespace=<nowarn|warn|error|error-all|strip>] [--exclude=PATH] + [--cached] [--verbose] [<patch>...] DESCRIPTION ----------- @@ -32,8 +33,9 @@ OPTIONS --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. Turns - off "apply". + abbreviation, to make it more machine friendly. For + binary files, outputs two `-` instead of saying + `0 0`. Turns off "apply". --summary:: Instead of applying the patch, output a condensed @@ -55,6 +57,11 @@ OPTIONS up-to-date, it is flagged as an error. This flag also causes the index file to be updated. +--cached:: + Apply a patch without touching the working tree. Instead, take the + cached data, apply the patch, and store the result in the index, + without using the working tree. This implies '--index'. + --index-info:: Newer git-diff output has embedded 'index information' for each blob to help identify the original version that @@ -62,6 +69,16 @@ OPTIONS the original version of the blob is available locally, outputs information about them to the standard output. +-R, --reverse:: + Apply the patch in reverse. + +--reject:: + For atomicity, gitlink:git-apply[1] by default fails the whole patch and + does not touch the working tree when some of the hunks + do not apply. This option makes it apply + the parts of the patch that are applicable, and leave the + rejected hunks in corresponding *.rej files. + -z:: When showing the index information, do not munge paths, but use NUL terminated machine readable format. Without @@ -79,9 +96,19 @@ OPTIONS context exist they all must match. By default no context is ever ignored. +--unidiff-zero:: + By default, gitlink:git-apply[1] expects that the patch being + applied is a unified diff with at least one line of context. + This provides good safety measures, but breaks down when + applying a diff generated with --unified=0. To bypass these + checks use '--unidiff-zero'. ++ +Note, for the reasons stated above usage of context-free patches are +discouraged. + --apply:: - If you use any of the options marked ``Turns off - "apply"'' above, git-apply reads and outputs the + If you use any of the options marked "Turns off + 'apply'" above, gitlink:git-apply[1] reads and outputs the information you asked without actually applying the patch. Give this flag after those flags to also apply the patch. @@ -93,16 +120,16 @@ OPTIONS the result with this option, which would apply the deletion part but not addition part. ---allow-binary-replacement:: - When applying a patch, which is a git-enhanced patch - that was prepared to record the pre- and post-image object - name in full, and the path being patched exactly matches - the object the patch applies to (i.e. "index" line's - pre-image object name is what is in the working tree), - and the post-image object is available in the object - database, use the post-image object as the patch - result. This allows binary files to be patched in a - very limited way. +--allow-binary-replacement, --binary:: + Historically we did not allow binary patch applied + without an explicit permission from the user, and this + flag was the way to do so. Currently we always allow binary + patch application, so this is a no-op. + +--exclude=<path-pattern>:: + Don't apply changes to files matching the given path pattern. This can + be useful when importing patchsets, where you want to exclude certain + files or directories. --whitespace=<option>:: When applying a patch, detect a new or modified line @@ -110,7 +137,7 @@ OPTIONS line that solely consists of whitespaces). By default, the command outputs warning messages and applies the patch. - When `git-apply` is used for statistics and not applying a + When gitlink:git-apply[1] is used for statistics and not applying a patch, it defaults to `nowarn`. You can use different `<option>` to control this behavior: @@ -124,6 +151,17 @@ OPTIONS * `strip` outputs warnings for a few such errors, strips out the trailing whitespaces and applies the patch. +--inaccurate-eof:: + Under certain circumstances, some versions of diff do not correctly + detect a missing new-line at the end of the file. As a result, patches + created by such diff programs do not record incomplete lines + correctly. This option adds support for applying such patches by + working around this bug. + +--verbose:: + Report progress to stderr. By default, only a message about the + current patch being applied will be printed. This option will cause + additional information to be reported. Configuration ------------- diff --git a/Documentation/git-applymbox.txt b/Documentation/git-applymbox.txt index f74c6a49b..95dc65a58 100644 --- a/Documentation/git-applymbox.txt +++ b/Documentation/git-applymbox.txt @@ -42,13 +42,13 @@ OPTIONS and the current tree. -u:: - By default, the commit log message, author name and - author email are taken from the e-mail without any - charset conversion, after minimally decoding MIME - transfer encoding. This flag causes the resulting - commit to be encoded in utf-8 by transliterating them. - Note that the patch is always used as is without charset - conversion, even with this flag. + The commit log message, author name and author email are + taken from the e-mail, and after minimally decoding MIME + transfer encoding, re-coded in UTF-8 by transliterating + them. This used to be optional but now it is the default. ++ +Note that the patch is always used as-is without charset +conversion, even with this flag. -c .dotest/<num>:: When the patch contained in an e-mail does not cleanly diff --git a/Documentation/git-archive.txt b/Documentation/git-archive.txt new file mode 100644 index 000000000..031fcd519 --- /dev/null +++ b/Documentation/git-archive.txt @@ -0,0 +1,113 @@ +git-archive(1) +============== + +NAME +---- +git-archive - Creates a archive of the files in the named tree + + +SYNOPSIS +-------- +'git-archive' --format=<fmt> [--list] [--prefix=<prefix>/] [<extra>] + [--remote=<repo>] <tree-ish> [path...] + +DESCRIPTION +----------- +Creates an archive of the specified format containing the tree +structure for the named tree. If <prefix> is specified it is +prepended to the filenames in the archive. + +'git-archive' behaves differently when given a tree ID versus when +given a commit ID or tag ID. In the first case the current time is +used as modification time of each file in the archive. In the latter +case the commit time as recorded in the referenced commit object is +used instead. Additionally the commit ID is stored in a global +extended pax header if the tar format is used; it can be extracted +using 'git-get-tar-commit-id'. In ZIP files it is stored as a file +comment. + +OPTIONS +------- + +--format=<fmt>:: + Format of the resulting archive: 'tar', 'zip'... + +--list:: + Show all available formats. + +--prefix=<prefix>/:: + Prepend <prefix>/ to each filename in the archive. + +<extra>:: + This can be any options that the archiver backend understand. + See next section. + +--remote=<repo>:: + Instead of making a tar archive from local repository, + retrieve a tar archive from a remote repository. + +<tree-ish>:: + The tree or commit to produce an archive for. + +path:: + If one or more paths are specified, include only these in the + archive, otherwise include all files and subdirectories. + +BACKEND EXTRA OPTIONS +--------------------- + +zip +~~~ +-0:: + Store the files instead of deflating them. +-9:: + Highest and slowest compression level. You can specify any + number from 1 to 9 to adjust compression speed and ratio. + + +CONFIGURATION +------------- +By default, file and directories modes are set to 0666 or 0777 in tar +archives. It is possible to change this by setting the "umask" variable +in the repository configuration as follows : + +[tar] + umask = 002 ;# group friendly + +The special umask value "user" indicates that the user's current umask +will be used instead. The default value remains 0, which means world +readable/writable files and directories. + +EXAMPLES +-------- +git archive --format=tar --prefix=junk/ HEAD | (cd /var/tmp/ && tar xf -):: + + Create a tar archive that contains the contents of the + latest commit on the current branch, and extracts it in + `/var/tmp/junk` directory. + +git archive --format=tar --prefix=git-1.4.0/ v1.4.0 | gzip >git-1.4.0.tar.gz:: + + Create a compressed tarball for v1.4.0 release. + +git archive --format=tar --prefix=git-1.4.0/ v1.4.0{caret}\{tree\} | gzip >git-1.4.0.tar.gz:: + + Create a compressed tarball for v1.4.0 release, but without a + global extended pax header. + +git archive --format=zip --prefix=git-docs/ HEAD:Documentation/ > git-1.4.0-docs.zip:: + + Put everything in the current head's Documentation/ directory + into 'git-1.4.0-docs.zip', with the prefix 'git-docs/'. + +Author +------ +Written by Franck Bui-Huu and Rene Scharfe. + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite diff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt index bfed94591..bdfc66692 100644 --- a/Documentation/git-blame.txt +++ b/Documentation/git-blame.txt @@ -3,21 +3,45 @@ git-blame(1) NAME ---- -git-blame - Blame file lines on commits +git-blame - Show what revision and author last modified each line of a file SYNOPSIS -------- -git-blame file [options] file [revision] +[verse] +'git-blame' [-c] [-l] [-t] [-f] [-n] [-p] [-L n,m] [-S <revs-file>] + [-M] [-C] [-C] [--since=<date>] [<rev>] [--] <file> DESCRIPTION ----------- -Annotates each line in the given file with information from the commit -which introduced the line. Start annotation from the given revision. + +Annotates each line in the given file with information from the revision which +last modified the line. Optionally, start annotating from the given revision. + +Also it can limit the range of lines annotated. + +This report doesn't tell you anything about lines which have been deleted or +replaced; you need to use a tool such as gitlink:git-diff[1] or the "pickaxe" +interface briefly mentioned in the following paragraph. + +Apart from supporting file annotation, git also supports searching the +development history for when a code snippet occured in a change. This makes it +possible to track when a code snippet was added to a file, moved or copied +between files, and eventually deleted or replaced. It works by searching for +a text string in the diff. A small example: + +----------------------------------------------------------------------------- +$ git log --pretty=oneline -S'blame_usage' +5040f17eba15504bad66b14a645bddd9b015ebb7 blame -S <ancestry-file> +ea4c7f9bf69e781dd0cd88d2bccb2bf5cc15c9a7 git-blame: Make the output +----------------------------------------------------------------------------- OPTIONS ------- -c, --compatibility:: - Use the same output mode as git-annotate (Default: off). + Use the same output mode as gitlink:git-annotate[1] (Default: off). + +-L n,m:: + Annotate only the specified line range (lines count from 1). -l, --long:: Show long rev (Default: off). @@ -26,19 +50,118 @@ OPTIONS Show raw timestamp (Default: off). -S, --rev-file <revs-file>:: - Use revs from revs-file instead of calling git-rev-list. + Use revs from revs-file instead of calling gitlink:git-rev-list[1]. + +-f, --show-name:: + Show filename in the original commit. By default + filename is shown if there is any line that came from a + file with different name, due to rename detection. + +-n, --show-number:: + Show line number in the original commit (Default: off). + +-p, --porcelain:: + Show in a format designed for machine consumption. + +-M:: + Detect moving lines in the file as well. When a commit + moves a block of lines in a file (e.g. the original file + has A and then B, and the commit changes it to B and + then A), traditional 'blame' algorithm typically blames + the lines that were moved up (i.e. B) to the parent and + assigns blame to the lines that were moved down (i.e. A) + to the child commit. With this option, both groups of + lines are blamed on the parent. + +-C:: + In addition to `-M`, detect lines copied from other + files that were modified in the same commit. This is + useful when you reorganize your program and move code + around across files. When this option is given twice, + the command looks for copies from all other files in the + parent for the commit that creates the file in addition. -h, --help:: Show help message. +THE PORCELAIN FORMAT +-------------------- + +In this format, each line is output after a header; the +header at the minumum has the first line which has: + +- 40-byte SHA-1 of the commit the line is attributed to; +- the line number of the line in the original file; +- the line number of the line in the final file; +- on a line that starts a group of line from a different + commit than the previous one, the number of lines in this + group. On subsequent lines this field is absent. + +This header line is followed by the following information +at least once for each commit: + +- author name ("author"), email ("author-mail"), time + ("author-time"), and timezone ("author-tz"); similarly + for committer. +- filename in the commit the line is attributed to. +- the first line of the commit log message ("summary"). + +The contents of the actual line is output after the above +header, prefixed by a TAB. This is to allow adding more +header elements later. + + +SPECIFIYING RANGES +------------------ + +Unlike `git-blame` and `git-annotate` in older git, the extent +of annotation can be limited to both line ranges and revision +ranges. When you are interested in finding the origin for +ll. 40-60 for file `foo`, you can use `-L` option like this: + + git blame -L 40,60 foo + +Also you can use regular expression to specify the line range. + + git blame -L '/^sub hello {/,/^}$/' foo + +would limit the annotation to the body of `hello` subroutine. + +When you are not interested in changes older than the version +v2.6.18, or changes older than 3 weeks, you can use revision +range specifiers similar to `git-rev-list`: + + git blame v2.6.18.. -- foo + git blame --since=3.weeks -- foo + +When revision range specifiers are used to limit the annotation, +lines that have not changed since the range boundary (either the +commit v2.6.18 or the most recent commit that is more than 3 +weeks old in the above example) are blamed for that range +boundary commit. + +A particularly useful way is to see if an added file have lines +created by copy-and-paste from existing files. Sometimes this +indicates that the developer was being sloppy and did not +refactor the code properly. You can first find the commit that +introduced the file with: + + git log --diff-filter=A --pretty=short -- foo + +and then annotate the change between the commit and its +parents, using `commit{caret}!` notation: + + git blame -C -C -f $commit^! -- foo + + SEE ALSO -------- gitlink:git-annotate[1] AUTHOR ------ -Written by Fredrik Kuivinen <freku045@student.liu.se>. +Written by Junio C Hamano <junkio@cox.net> GIT --- diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index d43ef1dec..e872fc89f 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -8,23 +8,33 @@ git-branch - List, create, or delete branches. SYNOPSIS -------- [verse] -'git-branch' [-r] +'git-branch' [--color | --no-color] [-r | -a] [-v [--abbrev=<length>]] 'git-branch' [-l] [-f] <branchname> [<start-point>] -'git-branch' (-d | -D) <branchname>... +'git-branch' (-m | -M) [<oldbranch>] <newbranch> +'git-branch' (-d | -D) [-r] <branchname>... DESCRIPTION ----------- -With no arguments given (or just `-r`) a list of available branches +With no arguments given a list of existing branches will be shown, the current branch will be highlighted with an asterisk. +Option `-r` causes the remote-tracking branches to be listed, +and option `-a` shows both. In its second form, a new branch named <branchname> will be created. It will start out with a head equal to the one given as <start-point>. If no <start-point> is given, the branch will be created with a head equal to that of the currently checked out branch. +With a '-m' or '-M' option, <oldbranch> will be renamed to <newbranch>. +If <oldbranch> had a corresponding reflog, it is renamed to match +<newbranch>, and a reflog entry is created to remember the branch +renaming. If <newbranch> exists, -M must be used to force the rename +to happen. + With a `-d` or `-D` option, `<branchname>` will be deleted. You may specify more than one branch for deletion. If the branch currently -has a ref log then the ref log will also be deleted. +has a ref log then the ref log will also be deleted. Use -r together with -d +to delete remote-tracking branches. OPTIONS @@ -44,8 +54,31 @@ OPTIONS Force the creation of a new branch even if it means deleting a branch that already exists with the same name. +-m:: + Move/rename a branch and the corresponding reflog. + +-M:: + Move/rename a branch even if the new branchname already exists. + +--color:: + Color branches to highlight current, local, and remote branches. + +--no-color:: + Turn off branch colors, even when the configuration file gives the + default to color output. + -r:: - List only the "remote" branches. + List or delete (if used with -d) the remote-tracking branches. + +-a:: + List both remote-tracking branches and local branches. + +-v:: + Show sha1 and commit subjectline for each head. + +--abbrev=<length>:: + Alter minimum display length for sha1 in output listing, + default value is 7. <branchname>:: The name of the branch to create or delete. @@ -58,6 +91,12 @@ OPTIONS be given as a branch name, a commit-id, or a tag. If this option is omitted, the current branch is assumed. +<oldbranch>:: + The name of an existing branch to rename. + +<newbranch>:: + The new name for an existing branch. The same restrictions as for + <branchname> applies. Examples @@ -80,10 +119,12 @@ Delete unneeded branch:: ------------ $ git clone git://git.kernel.org/.../git.git my.git $ cd my.git -$ git branch -D todo <1> +$ git branch -d -r todo html man <1> +$ git branch -D test <2> ------------ + -<1> delete todo branch even if the "master" branch does not have all +<1> delete remote-tracking branches "todo", "html", "man" +<2> delete "test" branch even if the "master" branch does not have all commits from todo branch. diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt index bfa950ca1..875edb6b9 100644 --- a/Documentation/git-cherry-pick.txt +++ b/Documentation/git-cherry-pick.txt @@ -7,7 +7,7 @@ git-cherry-pick - Apply the change introduced by an existing commit SYNOPSIS -------- -'git-cherry-pick' [--edit] [-n] [-r] <commit> +'git-cherry-pick' [--edit] [-n] [-x] <commit> DESCRIPTION ----------- @@ -24,13 +24,22 @@ OPTIONS With this option, `git-cherry-pick` will let you edit the commit message prior committing. --r|--replay:: - Usually the command appends which commit was +-x:: + Cause the command to append which commit was cherry-picked after the original commit message when - making a commit. This option, '--replay', causes it to - use the original commit message intact. This is useful - when you are reordering the patches in your private tree - before publishing. + making a commit. Do not use this option if you are + cherry-picking from your private branch because the + information is useless to the recipient. If on the + other hand you are cherry-picking between two publicly + visible branches (e.g. backporting a fix to a + maintenance branch for an older release from a + development branch), adding this information can be + useful. + +-r|--replay:: + It used to be that the command defaulted to do `-x` + described above, and `-r` was to disable it. Now the + default is not to do `-x` so this option is a no-op. -n|--no-commit:: Usually the command automatically creates a commit with diff --git a/Documentation/git-cherry.txt b/Documentation/git-cherry.txt index 893baaa6f..27b67b81a 100644 --- a/Documentation/git-cherry.txt +++ b/Documentation/git-cherry.txt @@ -7,17 +7,33 @@ git-cherry - Find commits not merged upstream SYNOPSIS -------- -'git-cherry' [-v] <upstream> [<head>] +'git-cherry' [-v] <upstream> [<head>] [<limit>] DESCRIPTION ----------- The changeset (or "diff") of each commit between the fork-point and <head> is compared against each commit between the fork-point and <upstream>. -Every commit with a changeset that doesn't exist in the other branch -has its id (sha1) reported, prefixed by a symbol. Those existing only +Every commit that doesn't exist in the <upstream> branch +has its id (sha1) reported, prefixed by a symbol. The ones that have +equivalent change already in the <upstream> branch are prefixed with a minus (-) sign, and those -that only exist in the <head> branch are prefixed with a plus (+) symbol. +that only exist in the <head> branch are prefixed with a plus (+) symbol: + + __*__*__*__*__> <upstream> + / + fork-point + \__+__+__-__+__+__-__+__> <head> + + +If a <limit> has been given then the commits along the <head> branch up +to and including <limit> are not reported: + + __*__*__*__*__> <upstream> + / + fork-point + \__*__*__<limit>__-__+__> <head> + Because git-cherry compares the changeset rather than the commit id (sha1), you can use git-cherry to find out if a commit you made locally diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index f973c6431..a78207461 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -11,25 +11,25 @@ SYNOPSIS [verse] 'git-clone' [--template=<template_directory>] [-l [-s]] [-q] [-n] [--bare] [-o <name>] [-u <upload-pack>] [--reference <repository>] - [--use-separate-remote] <repository> [<directory>] + [--depth=<depth>] <repository> [<directory>] DESCRIPTION ----------- -Clones a repository into a newly created directory. All remote -branch heads are copied under `$GIT_DIR/refs/heads/`, except -that the remote `master` is also copied to `origin` branch. -In addition, `$GIT_DIR/remotes/origin` file is set up to have -this line: +Clones a repository into a newly created directory, creates +remote-tracking branches for each branch in the cloned repository +(visible using `git branch -r`), and creates and checks out an initial +branch equal to the cloned repository's currently active branch. - Pull: master:origin +After the clone, a plain `git fetch` without arguments will update +all the remote-tracking branches, and a `git pull` without +arguments will in addition merge the remote master branch into the +current master branch, if any. -This is to help the typical workflow of working off of the -remote `master` branch. Every time `git pull` without argument -is run, the progress on the remote `master` branch is tracked by -copying it into the local `origin` branch, and merged into the -branch you are currently working on. Remote branches other than -`master` are also added there to be tracked. +This default configuration is achieved by creating references to +the remote branch heads under `$GIT_DIR/refs/remotes/origin` and +by initializing `remote.origin.url` and `remote.origin.fetch` +configuration variables. OPTIONS @@ -71,16 +71,18 @@ OPTIONS Make a 'bare' GIT repository. That is, instead of creating `<directory>` and placing the administrative files in `<directory>/.git`, make the `<directory>` - itself the `$GIT_DIR`. This implies `-n` option. When - this option is used, neither the `origin` branch nor the - default `remotes/origin` file is created. - + itself the `$GIT_DIR`. This obviously implies the `-n` + because there is nowhere to check out the working tree. + Also the branch heads at the remote are copied directly + to corresponding local branch heads, without mapping + them to `refs/remotes/origin/`. When this option is + used, neither remote-tracking branches nor the related + configuration variables are created. + +--origin <name>:: -o <name>:: - Instead of using the branch name 'origin' to keep track - of the upstream repository, use <name> instead. Note - that the shorthand name stored in `remotes/origin` is - not affected, but the local branch name to pull the - remote `master` branch into is. + Instead of using the remote name 'origin' to keep track + of the upstream repository, use <name> instead. --upload-pack <upload-pack>:: -u <upload-pack>:: @@ -94,10 +96,14 @@ OPTIONS if unset the templates are taken from the installation defined default, typically `/usr/share/git-core/templates`. ---use-separate-remote:: - Save remotes heads under `$GIT_DIR/remotes/origin/` instead - of `$GIT_DIR/refs/heads/`. Only the master branch is saved - in the latter. +--depth=<depth>:: + Create a 'shallow' clone with a history truncated to the + specified number of revs. A shallow repository has + number of limitations (you cannot clone or fetch from + it, nor push from nor into it), but is adequate if you + want to only look at near the tip of a large project + with a long history, and would want to send in a fixes + as patches. <repository>:: The (possibly remote) repository to clone from. It can diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt index 41d1a1c4b..77ba96ed8 100644 --- a/Documentation/git-commit-tree.txt +++ b/Documentation/git-commit-tree.txt @@ -81,6 +81,11 @@ Your parents must have hated you!:: Your sysadmin must hate you!:: The password(5) name field is longer than a giant static buffer. +Discussion +---------- + +include::i18n.txt[] + See Also -------- gitlink:git-write-tree[1] diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index 517a86b23..b4528d72b 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -14,25 +14,42 @@ SYNOPSIS DESCRIPTION ----------- -Updates the index file for given paths, or all modified files if -'-a' is specified, and makes a commit object. The command specified -by either the VISUAL or EDITOR environment variables are used to edit -the commit log message. +Use 'git commit' when you want to record your changes into the repository +along with a log message describing what the commit is about. All changes +to be committed must be explicitly identified using one of the following +methods: -Several environment variable are used during commits. They are -documented in gitlink:git-commit-tree[1]. +1. by using gitlink:git-add[1] to incrementally "add" changes to the + next commit before using the 'commit' command (Note: even modified + files must be "added"); +2. by using gitlink:git-rm[1] to identify content removal for the next + commit, again before using the 'commit' command; + +3. by directly listing files containing changes to be committed as arguments + to the 'commit' command, in which cases only those files alone will be + considered for the commit; + +4. by using the -a switch with the 'commit' command to automatically "add" + changes from all known files i.e. files that have already been committed + before, and to automatically "rm" files that have been + removed from the working tree, and perform the actual commit. + +The gitlink:git-status[1] command can be used to obtain a +summary of what is included by any of the above for the next +commit by giving the same set of parameters you would give to +this command. + +If you make a commit and then found a mistake immediately after +that, you can recover from it with gitlink:git-reset[1]. -This command can run `commit-msg`, `pre-commit`, and -`post-commit` hooks. See link:hooks.html[hooks] for more -information. OPTIONS ------- -a|--all:: - Update all paths in the index file. This flag notices - files that have been modified and deleted, but new files - you have not told git about are not affected. + Tell the command to automatically stage files that have + been modified and deleted, but new files you have not + told git about are not affected. -c or -C <commit>:: Take existing commit object, and reuse the log message @@ -55,16 +72,9 @@ OPTIONS -s|--signoff:: Add Signed-off-by line at the end of the commit message. --v|--verify:: - Look for suspicious lines the commit introduces, and - abort committing if there is one. The definition of - 'suspicious lines' is currently the lines that has - trailing whitespaces, and the lines whose indentation - has a SP character immediately followed by a TAB - character. This is the default. - --n|--no-verify:: - The opposite of `--verify`. +--no-verify:: + This option bypasses the pre-commit hook. + See also link:hooks.html[hooks]. -e|--edit:: The message taken from file with `-F`, command line with @@ -95,69 +105,145 @@ but can be used to amend a merge commit. -- -i|--include:: - Instead of committing only the files specified on the - command line, update them in the index file and then - commit the whole index. This is the traditional - behavior. + Before making a commit out of staged contents so far, + stage the contents of paths given on the command line + as well. This is usually not what you want unless you + are concluding a conflicted merge. --o|--only:: - Commit only the files specified on the command line. - This format cannot be used during a merge, nor when the - index and the latest commit does not match on the - specified paths to avoid confusion. +-q|--quiet:: + Supress commit summary message. \--:: Do not interpret any more arguments as options. <file>...:: - Files to be committed. The meaning of these is - different between `--include` and `--only`. Without - either, it defaults `--only` semantics. + When files are given on the command line, the command + commits the contents of the named files, without + recording the changes already staged. The contents of + these files are also staged for the next commit on top + of what have been staged before. -If you make a commit and then found a mistake immediately after -that, you can recover from it with gitlink:git-reset[1]. - -Discussion +EXAMPLES +-------- +When recording your own work, the contents of modified files in +your working tree are temporarily stored to a staging area +called the "index" with gitlink:git-add[1]. Removal +of a file is staged with gitlink:git-rm[1]. After building the +state to be committed incrementally with these commands, `git +commit` (without any pathname parameter) is used to record what +has been staged so far. This is the most basic form of the +command. An example: + +------------ +$ edit hello.c +$ git rm goodbye.c +$ git add hello.c +$ git commit +------------ + +//////////// +We should fix 'git rm' to remove goodbye.c from both index and +working tree for the above example. +//////////// + +Instead of staging files after each individual change, you can +tell `git commit` to notice the changes to the files whose +contents are tracked in +your working tree and do corresponding `git add` and `git rm` +for you. That is, this example does the same as the earlier +example if there is no other change in your working tree: + +------------ +$ edit hello.c +$ rm goodbye.c +$ git commit -a +------------ + +The command `git commit -a` first looks at your working tree, +notices that you have modified hello.c and removed goodbye.c, +and performs necessary `git add` and `git rm` for you. + +After staging changes to many files, you can alter the order the +changes are recorded in, by giving pathnames to `git commit`. +When pathnames are given, the command makes a commit that +only records the changes made to the named paths: + +------------ +$ edit hello.c hello.h +$ git add hello.c hello.h +$ edit Makefile +$ git commit Makefile +------------ + +This makes a commit that records the modification to `Makefile`. +The changes staged for `hello.c` and `hello.h` are not included +in the resulting commit. However, their changes are not lost -- +they are still staged and merely held back. After the above +sequence, if you do: + +------------ +$ git commit +------------ + +this second commit would record the changes to `hello.c` and +`hello.h` as expected. + +After a merge (initiated by either gitlink:git-merge[1] or +gitlink:git-pull[1]) stops because of conflicts, cleanly merged +paths are already staged to be committed for you, and paths that +conflicted are left in unmerged state. You would have to first +check which paths are conflicting with gitlink:git-status[1] +and after fixing them manually in your working tree, you would +stage the result as usual with gitlink:git-add[1]: + +------------ +$ git status | grep unmerged +unmerged: hello.c +$ edit hello.c +$ git add hello.c +------------ + +After resolving conflicts and staging the result, `git ls-files -u` +would stop mentioning the conflicted path. When you are done, +run `git commit` to finally record the merge: + +------------ +$ git commit +------------ + +As with the case to record your own changes, you can use `-a` +option to save typing. One difference is that during a merge +resolution, you cannot use `git commit` with pathnames to +alter the order the changes are committed, because the merge +should be recorded as a single commit. In fact, the command +refuses to run when given pathnames (but see `-i` option). + + +DISCUSSION ---------- -`git commit` without _any_ parameter commits the tree structure -recorded by the current index file. This is a whole-tree commit -even the command is invoked from a subdirectory. - -`git commit --include paths...` is equivalent to - - git update-index --remove paths... - git commit - -That is, update the specified paths to the index and then commit -the whole tree. - -`git commit paths...` largely bypasses the index file and -commits only the changes made to the specified paths. It has -however several safety valves to prevent confusion. +include::i18n.txt[] -. It refuses to run during a merge (i.e. when - `$GIT_DIR/MERGE_HEAD` exists), and reminds trained git users - that the traditional semantics now needs -i flag. +ENVIRONMENT VARIABLES +--------------------- +The command specified by either the VISUAL or EDITOR environment +variables is used to edit the commit log message. -. It refuses to run if named `paths...` are different in HEAD - and the index (ditto about reminding). Added paths are OK. - This is because an earlier `git diff` (not `git diff HEAD`) - would have shown the differences since the last `git - update-index paths...` to the user, and an inexperienced user - may mistakenly think that the changes between the index and - the HEAD (i.e. earlier changes made before the last `git - update-index paths...` was done) are not being committed. - -. It reads HEAD commit into a temporary index file, updates the - specified `paths...` and makes a commit. At the same time, - the real index file is also updated with the same `paths...`. +HOOKS +----- +This command can run `commit-msg`, `pre-commit`, and +`post-commit` hooks. See link:hooks.html[hooks] for more +information. -`git commit --all` updates the index file with _all_ changes to -the working tree, and makes a whole-tree commit, regardless of -which subdirectory the command is invoked in. +SEE ALSO +-------- +gitlink:git-add[1], +gitlink:git-rm[1], +gitlink:git-mv[1], +gitlink:git-merge[1], +gitlink:git-commit-tree[1] Author ------ diff --git a/Documentation/git-count-objects.txt b/Documentation/git-count-objects.txt index 198ce77a8..c59df6438 100644 --- a/Documentation/git-count-objects.txt +++ b/Documentation/git-count-objects.txt @@ -20,8 +20,8 @@ OPTIONS -v:: In addition to the number of loose objects and disk space consumed, it reports the number of in-pack - objects, and number of objects that can be removed by - running `git-prune-packed`. + objects, number of packs, and number of objects that can be + removed by running `git-prune-packed`. Author diff --git a/Documentation/git-cvsimport.txt b/Documentation/git-cvsimport.txt index d21d66bfe..5c402de26 100644 --- a/Documentation/git-cvsimport.txt +++ b/Documentation/git-cvsimport.txt @@ -90,7 +90,8 @@ If you need to pass multiple options, separate them with a comma. Print a short usage message and exit. -z <fuzz>:: - Pass the timestamp fuzz factor to cvsps. + Pass the timestamp fuzz factor to cvsps, in seconds. If unset, + cvsps defaults to 300s. -s <subst>:: Substitute the character "/" in branch names with <subst> @@ -99,6 +100,18 @@ If you need to pass multiple options, separate them with a comma. CVS by default uses the unix username when writing its commit logs. Using this option and an author-conv-file in this format + +-a:: + Import all commits, including recent ones. cvsimport by default + skips commits that have a timestamp less than 10 minutes ago. + +-S <regex>:: + Skip paths matching the regex. + +-L <limit>:: + Limit the number of commits imported. Workaround for cases where + cvsimport leaks memory. + + --------- exon=Andreas Ericsson <ae@op5.se> diff --git a/Documentation/git-daemon.txt b/Documentation/git-daemon.txt index 0f7d274ea..993adc7c5 100644 --- a/Documentation/git-daemon.txt +++ b/Documentation/git-daemon.txt @@ -8,19 +8,21 @@ git-daemon - A really simple server for git repositories SYNOPSIS -------- [verse] -'git-daemon' [--verbose] [--syslog] [--inetd | --port=n] [--export-all] +'git-daemon' [--verbose] [--syslog] [--export-all] [--timeout=n] [--init-timeout=n] [--strict-paths] [--base-path=path] [--user-path | --user-path=path] - [--reuseaddr] [--detach] [--pid-file=file] [directory...] + [--interpolated-path=pathtemplate] + [--reuseaddr] [--detach] [--pid-file=file] + [--enable=service] [--disable=service] + [--allow-override=service] [--forbid-override=service] + [--inetd | [--listen=host_or_ipaddr] [--port=n] [--user=user [--group=group]] + [directory...] DESCRIPTION ----------- A really simple TCP git daemon that normally listens on port "DEFAULT_GIT_PORT" -aka 9418. It waits for a connection, and will just execute "git-upload-pack" -when it gets one. - -It's careful in that there's a magic request-line that gives the command and -what directory to upload, and it verifies that the directory is OK. +aka 9418. It waits for a connection asking for a service, and will serve +that service if it is enabled. It verifies that the directory has the magic file "git-daemon-export-ok", and it will refuse to export any git directory that hasn't explicitly been marked @@ -28,7 +30,14 @@ for export this way (unless the '--export-all' parameter is specified). If you pass some directory paths as 'git-daemon' arguments, you can further restrict the offers to a whitelist comprising of those. -This is ideally suited for read-only updates, i.e., pulling from git repositories. +By default, only `upload-pack` service is enabled, which serves +`git-fetch-pack` and `git-peek-remote` clients that are invoked +from `git-fetch`, `git-ls-remote`, and `git-clone`. + +This is ideally suited for read-only updates, i.e., pulling from +git repositories. + +An `upload-archive` also exists to serve `git-archive`. OPTIONS ------- @@ -45,6 +54,16 @@ OPTIONS 'git://example.com/hello.git', `git-daemon` will interpret the path as '/srv/git/hello.git'. +--interpolated-path=pathtemplate:: + To support virtual hosting, an interpolated path template can be + used to dynamically construct alternate paths. The template + supports %H for the target hostname as supplied by the client but + converted to all lowercase, %CH for the canonical hostname, + %IP for the server's IP address, %P for the port number, + and %D for the absolute path of the named repository. + After interpolation, the path is validated against the directory + whitelist. + --export-all:: Allow pulling from all directories that look like GIT repositories (have the 'objects' and 'refs' subdirectories), even if they @@ -52,9 +71,17 @@ OPTIONS --inetd:: Have the server run as an inetd service. Implies --syslog. + Incompatible with --port, --listen, --user and --group options. ---port:: - Listen on an alternative port. +--listen=host_or_ipaddr:: + Listen on an a specific IP address or hostname. IP addresses can + be either an IPv4 address or an IPV6 address if supported. If IPv6 + is not supported, then --listen=hostname is also not supported and + --listen must be given an IPv4 address. + Incompatible with '--inetd' option. + +--port=n:: + Listen on an alternative port. Incompatible with '--inetd' option. --init-timeout:: Timeout between the moment the connection is established and the @@ -93,11 +120,109 @@ OPTIONS --pid-file=file:: Save the process id in 'file'. +--user=user, --group=group:: + Change daemon's uid and gid before entering the service loop. + When only `--user` is given without `--group`, the + primary group ID for the user is used. The values of + the option are given to `getpwnam(3)` and `getgrnam(3)` + and numeric IDs are not supported. ++ +Giving these options is an error when used with `--inetd`; use +the facility of inet daemon to achieve the same before spawning +`git-daemon` if needed. + +--enable-service, --disable-service:: + Enable/disable the service site-wide per default. Note + that a service disabled site-wide can still be enabled + per repository if it is marked overridable and the + repository enables the service with an configuration + item. + +--allow-override, --forbid-override:: + Allow/forbid overriding the site-wide default with per + repository configuration. By default, all the services + are overridable. + <directory>:: A directory to add to the whitelist of allowed directories. Unless --strict-paths is specified this will also include subdirectories of each named directory. +SERVICES +-------- + +upload-pack:: + This serves `git-fetch-pack` and `git-peek-remote` + clients. It is enabled by default, but a repository can + disable it by setting `daemon.uploadpack` configuration + item to `false`. + +upload-archive:: + This serves `git-archive --remote`. + +EXAMPLES +-------- +We assume the following in /etc/services:: ++ +------------ +$ grep 9418 /etc/services +git 9418/tcp # Git Version Control System +------------ + +git-daemon as inetd server:: + To set up `git-daemon` as an inetd service that handles any + repository under the whitelisted set of directories, /pub/foo + and /pub/bar, place an entry like the following into + /etc/inetd all on one line: ++ +------------------------------------------------ + git stream tcp nowait nobody /usr/bin/git-daemon + git-daemon --inetd --verbose --export-all + /pub/foo /pub/bar +------------------------------------------------ + + +git-daemon as inetd server for virtual hosts:: + To set up `git-daemon` as an inetd service that handles + repositories for different virtual hosts, `www.example.com` + and `www.example.org`, place an entry like the following into + `/etc/inetd` all on one line: ++ +------------------------------------------------ + git stream tcp nowait nobody /usr/bin/git-daemon + git-daemon --inetd --verbose --export-all + --interpolated-path=/pub/%H%D + /pub/www.example.org/software + /pub/www.example.com/software + /software +------------------------------------------------ ++ +In this example, the root-level directory `/pub` will contain +a subdirectory for each virtual host name supported. +Further, both hosts advertise repositories simply as +`git://www.example.com/software/repo.git`. For pre-1.4.0 +clients, a symlink from `/software` into the appropriate +default repository could be made as well. + + +git-daemon as regular daemon for virtual hosts:: + To set up `git-daemon` as a regular, non-inetd service that + handles repositories for multiple virtual hosts based on + their IP addresses, start the daemon like this: ++ +------------------------------------------------ + git-daemon --verbose --export-all + --interpolated-path=/pub/%IP/%D + /pub/192.168.1.200/software + /pub/10.10.220.23/software +------------------------------------------------ ++ +In this example, the root-level directory `/pub` will contain +a subdirectory for each virtual host IP address supported. +Repositories can still be accessed by hostname though, assuming +they correspond to these IP addresses. + + Author ------ Written by Linus Torvalds <torvalds@osdl.org>, YOSHIFUJI Hideaki diff --git a/Documentation/git-diff-index.txt b/Documentation/git-diff-index.txt index 9cd43f105..2df581c2c 100644 --- a/Documentation/git-diff-index.txt +++ b/Documentation/git-diff-index.txt @@ -54,7 +54,7 @@ If '--cached' is specified, it allows you to ask: For example, let's say that you have worked on your working directory, updated some files in the index and are ready to commit. You want to see exactly -*what* you are going to commit is without having to write a new tree +*what* you are going to commit, without having to write a new tree object and compare it that way, and to do that, you just do git-diff-index --cached HEAD @@ -68,7 +68,7 @@ matches my working directory. But doing a "git-diff-index" does: -100644 blob 4161aecc6700a2eb579e842af0b7f22b98443f74 commit.c +100644 blob 4161aecc6700a2eb579e842af0b7f22b98443f74 git-commit.c -You can trivially see that the above is a rename. +You can see easily that the above is a rename. In fact, "git-diff-index --cached" *should* always be entirely equivalent to actually doing a "git-write-tree" and comparing that. Except this one is much diff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt index f7e8ff296..5d6e9dc75 100644 --- a/Documentation/git-diff-tree.txt +++ b/Documentation/git-diff-tree.txt @@ -73,10 +73,7 @@ separated with a single space are given. This flag causes "git-diff-tree --stdin" to also show the commit message before the differences. ---pretty[=(raw|medium|short)]:: - This is used to control "pretty printing" format of the - commit message. Without "=<style>", it defaults to - medium. +include::pretty-formats.txt[] --no-commit-id:: git-diff-tree outputs a line with the commit ID when diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt index 228c4d95b..8977877b2 100644 --- a/Documentation/git-diff.txt +++ b/Documentation/git-diff.txt @@ -8,36 +8,54 @@ git-diff - Show changes between commits, commit and working tree, etc SYNOPSIS -------- -'git-diff' [ --diff-options ] <tree-ish>{0,2} [<path>...] +'git-diff' [ --diff-options ] <commit>{0,2} [--] [<path>...] DESCRIPTION ----------- Show changes between two trees, a tree and the working tree, a tree and the index file, or the index file and the working tree. -The combination of what is compared with what is determined by -the number of trees given to the command. -* When no <tree-ish> is given, the working tree and the index - file are compared, using `git-diff-files`. +'git-diff' [--options] [--] [<path>...]:: -* When one <tree-ish> is given, the working tree and the named - tree are compared, using `git-diff-index`. The option - `--cached` can be given to compare the index file and - the named tree. + This form is to view the changes you made relative to + the index (staging area for the next commit). In other + words, the differences are what you _could_ tell git to + further add to the index but you still haven't. You can + stage these changes by using gitlink:git-add[1]. + +'git-diff' [--options] --cached [<commit>] [--] [<path>...]:: + + This form is to view the changes you staged for the next + commit relative to the named <commit>. Typically you + would want comparison with the latest commit, so if you + do not give <commit>, it defaults to HEAD. + +'git-diff' [--options] <commit> [--] [<path>...]:: + + This form is to view the changes you have in your + working tree relative to the named <commit>. You can + use HEAD to compare it with the latest commit, or a + branch name to compare with the tip of a different + branch. + +'git-diff' [--options] <commit> <commit> [--] [<path>...]:: + + This form is to view the changes between two <commit>, + for example, tips of two branches. + +Just in case if you are doing something exotic, it should be +noted that all of the <commit> in the above description can be +any <tree-ish>. -* When two <tree-ish>s are given, these two trees are compared - using `git-diff-tree`. OPTIONS ------- ---diff-options:: - '--diff-options' are passed to the `git-diff-files`, - `git-diff-index`, and `git-diff-tree` commands. See the - documentation for these commands for description. +include::diff-options.txt[] <path>...:: - The <path> arguments are also passed to `git-diff-\*` - commands. + The <paths> parameters, when given, are used to limit + the diff to the named paths (you can give directory + names and get diff for all files under them). EXAMPLES @@ -51,7 +69,7 @@ $ git diff --cached <2> $ git diff HEAD <3> ------------ + -<1> changes in the working tree since your last git-update-index. +<1> changes in the working tree not yet staged for the next commit. <2> changes between the index and your last commit; what you would be committing if you run "git commit" without "-a" option. <3> changes in the working tree since your last commit; what you diff --git a/Documentation/git-fetch-pack.txt b/Documentation/git-fetch-pack.txt index bff9aa693..3e6cd880b 100644 --- a/Documentation/git-fetch-pack.txt +++ b/Documentation/git-fetch-pack.txt @@ -32,7 +32,8 @@ OPTIONS -k:: Do not invoke 'git-unpack-objects' on received data, but create a single packfile out of it instead, and store it - in the object database. + in the object database. If provided twice then the pack is + locked against repacking. --exec=<git-upload-pack>:: Use this to specify the path to 'git-upload-pack' on the diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt new file mode 100644 index 000000000..2bf6aef73 --- /dev/null +++ b/Documentation/git-for-each-ref.txt @@ -0,0 +1,185 @@ +git-for-each-ref(1) +=================== + +NAME +---- +git-for-each-ref - Output information on each ref + +SYNOPSIS +-------- +'git-for-each-ref' [--count=<count>]\* [--shell|--perl|--python] [--sort=<key>]\* [--format=<format>] [<pattern>] + +DESCRIPTION +----------- + +Iterate over all refs that match `<pattern>` and show them +according to the given `<format>`, after sorting them according +to the given set of `<key>`. If `<max>` is given, stop after +showing that many refs. The interporated values in `<format>` +can optionally be quoted as string literals in the specified +host language allowing their direct evaluation in that language. + +OPTIONS +------- +<count>:: + By default the command shows all refs that match + `<pattern>`. This option makes it stop after showing + that many refs. + +<key>:: + A field name to sort on. Prefix `-` to sort in + descending order of the value. When unspecified, + `refname` is used. More than one sort keys can be + given. + +<format>:: + A string that interpolates `%(fieldname)` from the + object pointed at by a ref being shown. If `fieldname` + is prefixed with an asterisk (`*`) and the ref points + at a tag object, the value for the field in the object + tag refers is used. When unspecified, defaults to + `%(objectname) SPC %(objecttype) TAB %(refname)`. + It also interpolates `%%` to `%`, and `%xx` where `xx` + are hex digits interpolates to character with hex code + `xx`; for example `%00` interpolates to `\0` (NUL), + `%09` to `\t` (TAB) and `%0a` to `\n` (LF). + +<pattern>:: + If given, the name of the ref is matched against this + using fnmatch(3). Refs that do not match the pattern + are not shown. + +--shell, --perl, --python:: + If given, strings that substitute `%(fieldname)` + placeholders are quoted as string literals suitable for + the specified host language. This is meant to produce + a scriptlet that can directly be `eval`ed. + + +FIELD NAMES +----------- + +Various values from structured fields in referenced objects can +be used to interpolate into the resulting output, or as sort +keys. + +For all objects, the following names can be used: + +refname:: + The name of the ref (the part after $GIT_DIR/refs/). + +objecttype:: + The type of the object (`blob`, `tree`, `commit`, `tag`). + +objectsize:: + The size of the object (the same as `git-cat-file -s` reports). + +objectname:: + The object name (aka SHA-1). + +In addition to the above, for commit and tag objects, the header +field names (`tree`, `parent`, `object`, `type`, and `tag`) can +be used to specify the value in the header field. + +Fields that have name-email-date tuple as its value (`author`, +`committer`, and `tagger`) can be suffixed with `name`, `email`, +and `date` to extract the named component. + +The first line of the message in a commit and tag object is +`subject`, the remaining lines are `body`. The whole message +is `contents`. + +For sorting purposes, fields with numeric values sort in numeric +order (`objectsize`, `authordate`, `committerdate`, `taggerdate`). +All other fields are used to sort in their byte-value order. + +In any case, a field name that refers to a field inapplicable to +the object referred by the ref does not cause an error. It +returns an empty string instead. + + +EXAMPLES +-------- + +An example directly producing formatted text. Show the most recent +3 tagged commits:: + +------------ +#!/bin/sh + +git-for-each-ref --count=3 --sort='-*authordate' \ +--format='From: %(*authorname) %(*authoremail) +Subject: %(*subject) +Date: %(*authordate) +Ref: %(*refname) + +%(*body) +' 'refs/tags' +------------ + + +A simple example showing the use of shell eval on the output, +demonstrating the use of --shell. List the prefixes of all heads:: +------------ +#!/bin/sh + +git-for-each-ref --shell --format="ref=%(refname)" refs/heads | \ +while read entry +do + eval "$entry" + echo `dirname $ref` +done +------------ + + +A bit more elaborate report on tags, demonstrating that the format +may be an entire script:: +------------ +#!/bin/sh + +fmt=' + r=%(refname) + t=%(*objecttype) + T=${r#refs/tags/} + + o=%(*objectname) + n=%(*authorname) + e=%(*authoremail) + s=%(*subject) + d=%(*authordate) + b=%(*body) + + kind=Tag + if test "z$t" = z + then + # could be a lightweight tag + t=%(objecttype) + kind="Lightweight tag" + o=%(objectname) + n=%(authorname) + e=%(authoremail) + s=%(subject) + d=%(authordate) + b=%(body) + fi + echo "$kind $T points at a $t object $o" + if test "z$t" = zcommit + then + echo "The commit was authored by $n $e +at $d, and titled + + $s + +Its message reads as: +" + echo "$b" | sed -e "s/^/ /" + echo + fi +' + +eval=`git-for-each-ref --shell --format="$fmt" \ + --sort='*objecttype' \ + --sort=-taggerdate \ + refs/tags` +eval "$eval" +------------ diff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt new file mode 100644 index 000000000..73d78c15e --- /dev/null +++ b/Documentation/git-gc.txt @@ -0,0 +1,64 @@ +git-gc(1) +========= + +NAME +---- +git-gc - Cleanup unnecessary files and optimize the local repository + + +SYNOPSIS +-------- +'git-gc' + +DESCRIPTION +----------- +Runs a number of housekeeping tasks within the current repository, +such as compressing file revisions (to reduce disk space and increase +performance) and removing unreachable objects which may have been +created from prior invocations of gitlink:git-add[1]. + +Users are encouraged to run this task on a regular basis within +each repository to maintain good disk space utilization and good +operating performance. + +Configuration +------------- + +The optional configuration variable 'gc.reflogExpire' can be +set to indicate how long historical entries within each branch's +reflog should remain available in this repository. The setting is +expressed as a length of time, for example '90 days' or '3 months'. +It defaults to '90 days'. + +The optional configuration variable 'gc.reflogExpireUnreachable' +can be set to indicate how long historical reflog entries which +are not part of the current branch should remain available in +this repository. These types of entries are generally created as +a result of using `git commit \--amend` or `git rebase` and are the +commits prior to the amend or rebase occuring. Since these changes +are not part of the current project most users will want to expire +them sooner. This option defaults to '30 days'. + +The optional configuration variable 'gc.rerereresolved' indicates +how long records of conflicted merge you resolved earlier are +kept. This defaults to 60 days. + +The optional configuration variable 'gc.rerereunresolved' indicates +how long records of conflicted merge you have not resolved are +kept. This defaults to 15 days. + + +See Also +-------- +gitlink:git-prune[1] +gitlink:git-reflog[1] +gitlink:git-repack[1] +gitlink:git-rerere[1] + +Author +------ +Written by Shawn O. Pearce <spearce@spearce.org> + +GIT +--- +Part of the gitlink:git[7] suite diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt index 7545dd9a3..bfbece986 100644 --- a/Documentation/git-grep.txt +++ b/Documentation/git-grep.txt @@ -11,10 +11,10 @@ SYNOPSIS [verse] 'git-grep' [--cached] [-a | --text] [-I] [-i | --ignore-case] [-w | --word-regexp] - [-v | --invert-match] [--full-name] + [-v | --invert-match] [-h|-H] [--full-name] [-E | --extended-regexp] [-G | --basic-regexp] [-F | --fixed-strings] [-n] [-l | --files-with-matches] [-L | --files-without-match] - [-c | --count] + [-c | --count] [--all-match] [-A <post-context>] [-B <pre-context>] [-C <context>] [-f <file>] [-e] <pattern> [--and|--or|--not|(|)|-e <pattern>...] [<tree>...] @@ -47,6 +47,13 @@ OPTIONS -v | --invert-match:: Select non-matching lines. +-h | -H:: + By default, the command shows the filename for each + match. `-h` option is used to suppress this output. + `-H` is there for completeness and does not do anything + except it overrides `-h` given earlier on the command + line. + --full-name:: When run from a subdirectory, the command usually outputs paths relative to the current directory. This @@ -89,6 +96,11 @@ OPTIONS higher precedence than `--or`. `-e` has to be used for all patterns. +--all-match:: + When giving multiple pattern expressions combined with `--or`, + this flag is specified to limit the match to files that + have lines to match all of them. + `<tree>...`:: Search blobs in the trees for specified patterns. @@ -104,6 +116,10 @@ git grep -e \'#define\' --and \( -e MAX_PATH -e PATH_MAX \):: Looks for a line that has `#define` and either `MAX_PATH` or `PATH_MAX`. +git grep --all-match -e NODE -e Unexpected:: + Looks for a line that has `NODE` or `Unexpected` in + files that have lines that match both. + Author ------ Originally written by Linus Torvalds <torvalds@osdl.org>, later diff --git a/Documentation/git-http-push.txt b/Documentation/git-http-push.txt index 7e1f894a9..c2485c6e9 100644 --- a/Documentation/git-http-push.txt +++ b/Documentation/git-http-push.txt @@ -34,7 +34,7 @@ OPTIONS Report the list of objects being walked locally and the list of objects successfully sent to the remote repository. -<ref>...: +<ref>...:: The remote refs to update. diff --git a/Documentation/git-index-pack.txt b/Documentation/git-index-pack.txt index 71ce55727..2229ee86b 100644 --- a/Documentation/git-index-pack.txt +++ b/Documentation/git-index-pack.txt @@ -8,7 +8,8 @@ git-index-pack - Build pack index file for an existing packed archive SYNOPSIS -------- -'git-index-pack' [-o <index-file>] <pack-file> +'git-index-pack' [-v] [-o <index-file>] <pack-file> +'git-index-pack' --stdin [--fix-thin] [--keep] [-v] [-o <index-file>] [<pack-file>] DESCRIPTION @@ -21,6 +22,9 @@ objects/pack/ directory of a git repository. OPTIONS ------- +-v:: + Be verbose about what is going on, including progress status. + -o <index-file>:: Write the generated pack index into the specified file. Without this option the name of pack index @@ -29,6 +33,52 @@ OPTIONS fails if the name of packed archive does not end with .pack). +--stdin:: + When this flag is provided, the pack is read from stdin + instead and a copy is then written to <pack-file>. If + <pack-file> is not specified, the pack is written to + objects/pack/ directory of the current git repository with + a default name determined from the pack content. If + <pack-file> is not specified consider using --keep to + prevent a race condition between this process and + gitlink::git-repack[1] . + +--fix-thin:: + It is possible for gitlink:git-pack-objects[1] to build + "thin" pack, which records objects in deltified form based on + objects not included in the pack to reduce network traffic. + Those objects are expected to be present on the receiving end + and they must be included in the pack for that pack to be self + contained and indexable. Without this option any attempt to + index a thin pack will fail. This option only makes sense in + conjunction with --stdin. + +--keep:: + Before moving the index into its final destination + create an empty .keep file for the associated pack file. + This option is usually necessary with --stdin to prevent a + simultaneous gitlink:git-repack[1] process from deleting + the newly constructed pack and index before refs can be + updated to use objects contained in the pack. + +--keep='why':: + Like --keep create a .keep file before moving the index into + its final destination, but rather than creating an empty file + place 'why' followed by an LF into the .keep file. The 'why' + message can later be searched for within all .keep files to + locate any which have outlived their usefulness. + + +Note +---- + +Once the index has been created, the list of object names is sorted +and the SHA1 hash of that list is printed to stdout. If --stdin was +also used then this is prefixed by either "pack\t", or "keep\t" if a +new .keep file was successfully created. This is useful to remove a +.keep file used as a lock to prevent the race with gitlink:git-repack[1] +mentioned above. + Author ------ diff --git a/Documentation/git-init-db.txt b/Documentation/git-init-db.txt index 63cd5dab3..5412135d7 100644 --- a/Documentation/git-init-db.txt +++ b/Documentation/git-init-db.txt @@ -11,91 +11,9 @@ SYNOPSIS 'git-init-db' [--template=<template_directory>] [--shared[=<permissions>]] -OPTIONS -------- - --- - ---template=<template_directory>:: - -Provide the directory from which templates will be used. The default template -directory is `/usr/share/git-core/templates`. - -When specified, `<template_directory>` is used as the source of the template -files rather than the default. The template files include some directory -structure, some suggested "exclude patterns", and copies of non-executing -"hook" files. The suggested patterns and hook files are all modifiable and -extensible. - ---shared[={false|true|umask|group|all|world|everybody}]:: - -Specify that the git repository is to be shared amongst several users. This -allows users belonging to the same group to push into that -repository. When specified, the config variable "core.sharedRepository" is -set so that files and directories under `$GIT_DIR` are created with the -requested permissions. When not specified, git will use permissions reported -by umask(2). - -The option can have the following values, defaulting to 'group' if no value -is given: - - - 'umask' (or 'false'): Use permissions reported by umask(2). The default, - when `--shared` is not specified. - - - 'group' (or 'true'): Make the repository group-writable, (and g+sx, since - the git group may be not the primary group of all users). - - - 'all' (or 'world' or 'everybody'): Same as 'group', but make the repository - readable by all users. - --- - - DESCRIPTION ----------- -This command creates an empty git repository - basically a `.git` directory -with subdirectories for `objects`, `refs/heads`, `refs/tags`, and -template files. -An initial `HEAD` file that references the HEAD of the master branch -is also created. - -If the `$GIT_DIR` environment variable is set then it specifies a path -to use instead of `./.git` for the base of the repository. - -If the object storage directory is specified via the `$GIT_OBJECT_DIRECTORY` -environment variable then the sha1 directories are created underneath - -otherwise the default `$GIT_DIR/objects` directory is used. - -Running `git-init-db` in an existing repository is safe. It will not overwrite -things that are already there. The primary reason for rerunning `git-init-db` -is to pick up newly added templates. - - - -EXAMPLES --------- - -Start a new git repository for an existing code base:: -+ ----------------- -$ cd /path/to/my/codebase -$ git-init-db <1> -$ git-add . <2> ----------------- -+ -<1> prepare /path/to/my/codebase/.git directory -<2> add all existing file to the index - - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. -GIT ---- -Part of the gitlink:git[7] suite +This is a synonym for gitlink:git-init[1]. Please refer to the +documentation of that command. diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt new file mode 100644 index 000000000..596b567c9 --- /dev/null +++ b/Documentation/git-init.txt @@ -0,0 +1,111 @@ +git-init(1) +=========== + +NAME +---- +git-init - Creates an empty git repository + + +SYNOPSIS +-------- +'git-init' [--template=<template_directory>] [--shared[=<permissions>]] + + +OPTIONS +------- + +-- + +--template=<template_directory>:: + +Provide the directory from which templates will be used. The default template +directory is `/usr/share/git-core/templates`. + +When specified, `<template_directory>` is used as the source of the template +files rather than the default. The template files include some directory +structure, some suggested "exclude patterns", and copies of non-executing +"hook" files. The suggested patterns and hook files are all modifiable and +extensible. + +--shared[={false|true|umask|group|all|world|everybody}]:: + +Specify that the git repository is to be shared amongst several users. This +allows users belonging to the same group to push into that +repository. When specified, the config variable "core.sharedRepository" is +set so that files and directories under `$GIT_DIR` are created with the +requested permissions. When not specified, git will use permissions reported +by umask(2). + +The option can have the following values, defaulting to 'group' if no value +is given: + + - 'umask' (or 'false'): Use permissions reported by umask(2). The default, + when `--shared` is not specified. + + - 'group' (or 'true'): Make the repository group-writable, (and g+sx, since + the git group may be not the primary group of all users). + + - 'all' (or 'world' or 'everybody'): Same as 'group', but make the repository + readable by all users. + +By default, the configuration flag receive.denyNonFastforward is enabled +in shared repositories, so that you cannot force a non fast-forwarding push +into it. + +-- + + +DESCRIPTION +----------- +This command creates an empty git repository - basically a `.git` directory +with subdirectories for `objects`, `refs/heads`, `refs/tags`, and +template files. +An initial `HEAD` file that references the HEAD of the master branch +is also created. + +If the `$GIT_DIR` environment variable is set then it specifies a path +to use instead of `./.git` for the base of the repository. + +If the object storage directory is specified via the `$GIT_OBJECT_DIRECTORY` +environment variable then the sha1 directories are created underneath - +otherwise the default `$GIT_DIR/objects` directory is used. + +Running `git-init` in an existing repository is safe. It will not overwrite +things that are already there. The primary reason for rerunning `git-init` +is to pick up newly added templates. + +Note that `git-init` is the same as `git-init-db`. The command +was primarily meant to initialize the object database, but over +time it has become responsible for setting up the other aspects +of the repository, such as installing the default hooks and +setting the configuration variables. The old name is retained +for backward compatibility reasons. + + +EXAMPLES +-------- + +Start a new git repository for an existing code base:: ++ +---------------- +$ cd /path/to/my/codebase +$ git-init <1> +$ git-add . <2> +---------------- ++ +<1> prepare /path/to/my/codebase/.git directory +<2> add all existing file to the index + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt index c9ffff734..e9f746bbd 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -24,14 +24,16 @@ This manual page describes only the most frequently used options. OPTIONS ------- ---pretty=<format>:: - Controls the way the commit log is formatted. + +include::pretty-formats.txt[] --max-count=<n>:: Limits the number of commits to show. <since>..<until>:: - Show only commits between the named two commits. + Show only commits between the named two commits. When + either <since> or <until> is omitted, it defaults to + `HEAD`, i.e. the tip of the current branch. -p:: Show the change the commit introduces in a patch form. @@ -63,6 +65,12 @@ git log -r --name-status release..test:: in the "release" branch, along with the list of paths each commit modifies. +Discussion +---------- + +include::i18n.txt[] + + Author ------ Written by Linus Torvalds <torvalds@osdl.org> diff --git a/Documentation/git-ls-remote.txt b/Documentation/git-ls-remote.txt index ae4c1a250..c8a4c5a4d 100644 --- a/Documentation/git-ls-remote.txt +++ b/Documentation/git-ls-remote.txt @@ -3,16 +3,19 @@ git-ls-remote(1) NAME ---- -git-ls-remote - Look at references other repository has +git-ls-remote - List references in a remote repository SYNOPSIS -------- -'git-ls-remote' [--heads] [--tags] <repository> <refs>... +[verse] +'git-ls-remote' [--heads] [--tags] [-u <exec> | --upload-pack <exec>] + <repository> <refs>... DESCRIPTION ----------- -Displays the references other repository has. +Displays references available in a remote repository along with the associated +commit IDs. OPTIONS @@ -23,9 +26,16 @@ OPTIONS both, references stored in refs/heads and refs/tags are displayed. +-u <exec>, --upload-pack=<exec>:: + Specify the full path of gitlink:git-upload-pack[1] on the remote + host. This allows listing references from repositories accessed via + SSH and where the SSH deamon does not use the PATH configured by the + user. Also see the '--exec' option for gitlink:git-peek-remote[1]. + <repository>:: Location of the repository. The shorthand defined in - $GIT_DIR/branches/ can be used. + $GIT_DIR/branches/ can be used. Use "." (dot) to list references in + the local repository. <refs>...:: When unspecified, all references, after filtering done diff --git a/Documentation/git-mailinfo.txt b/Documentation/git-mailinfo.txt index ea0a06557..5088bbea8 100644 --- a/Documentation/git-mailinfo.txt +++ b/Documentation/git-mailinfo.txt @@ -33,15 +33,13 @@ OPTIONS format-patch --mbox' output. -u:: - By default, the commit log message, author name and - author email are taken from the e-mail without any - charset conversion, after minimally decoding MIME - transfer encoding. This flag causes the resulting - commit to be encoded in the encoding specified by - i18n.commitencoding configuration (defaults to utf-8) by - transliterating them. - Note that the patch is always used as is without charset - conversion, even with this flag. + The commit log message, author name and author email are + taken from the e-mail, and after minimally decoding MIME + transfer encoding, re-coded in UTF-8 by transliterating + them. This used to be optional but now it is the default. ++ +Note that the patch is always used as-is without charset +conversion, even with this flag. --encoding=<encoding>:: Similar to -u but if the local convention is different diff --git a/Documentation/git-merge-file.txt b/Documentation/git-merge-file.txt new file mode 100644 index 000000000..29d3faa55 --- /dev/null +++ b/Documentation/git-merge-file.txt @@ -0,0 +1,92 @@ +git-merge-file(1) +================= + +NAME +---- +git-merge-file - three-way file merge + + +SYNOPSIS +-------- +[verse] +'git-merge-file' [-L <current-name> [-L <base-name> [-L <other-name>]]] + [-p|--stdout] [-q|--quiet] <current-file> <base-file> <other-file> + + +DESCRIPTION +----------- +git-file-merge incorporates all changes that lead from the `<base-file>` +to `<other-file>` into `<current-file>`. The result ordinarily goes into +`<current-file>`. git-merge-file is useful for combining separate changes +to an original. Suppose `<base-file>` is the original, and both +`<current-file>` and `<other-file>` are modifications of `<base-file>`. +Then git-merge-file combines both changes. + +A conflict occurs if both `<current-file>` and `<other-file>` have changes +in a common segment of lines. If a conflict is found, git-merge-file +normally outputs a warning and brackets the conflict with <<<<<<< and +>>>>>>> lines. A typical conflict will look like this: + + <<<<<<< A + lines in file A + ======= + lines in file B + >>>>>>> B + +If there are conflicts, the user should edit the result and delete one of +the alternatives. + +The exit value of this program is negative on error, and the number of +conflicts otherwise. If the merge was clean, the exit value is 0. + +git-merge-file is designed to be a minimal clone of RCS merge, that is, it +implements all of RCS merge's functionality which is needed by +gitlink:git[1]. + + +OPTIONS +------- + +-L <label>:: + This option may be given up to three times, and + specifies labels to be used in place of the + corresponding file names in conflict reports. That is, + `git-merge-file -L x -L y -L z a b c` generates output that + looks like it came from files x, y and z instead of + from files a, b and c. + +-p:: + Send results to standard output instead of overwriting + `<current-file>`. + +-q:: + Quiet; do not warn about conflicts. + + +EXAMPLES +-------- + +git merge-file README.my README README.upstream:: + + combines the changes of README.my and README.upstream since README, + tries to merge them and writes the result into README.my. + +git merge-file -L a -L b -L c tmp/a123 tmp/b234 tmp/c345:: + + merges tmp/a123 and tmp/c345 with the base tmp/b234, but uses labels + `a` and `c` instead of `tmp/a123` and `tmp/c345`. + + +Author +------ +Written by Johannes Schindelin <johannes.schindelin@gmx.de> + + +Documentation +-------------- +Documentation by Johannes Schindelin and the git-list <git@vger.kernel.org>, +with parts copied from the original documentation of RCS merge. + +GIT +--- +Part of the gitlink:git[7] suite diff --git a/Documentation/git-merge-index.txt b/Documentation/git-merge-index.txt index 6cd060108..0cf505ea8 100644 --- a/Documentation/git-merge-index.txt +++ b/Documentation/git-merge-index.txt @@ -40,8 +40,8 @@ If "git-merge-index" is called with multiple <file>s (or -a) then it processes them in turn only stopping if merge returns a non-zero exit code. -Typically this is run with the a script calling the merge command from -the RCS package. +Typically this is run with the a script calling git's imitation of +the merge command from the RCS package. A sample script called "git-merge-one-file" is included in the distribution. diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt index bebf30ad3..0f79665ea 100644 --- a/Documentation/git-merge.txt +++ b/Documentation/git-merge.txt @@ -8,12 +8,13 @@ git-merge - Grand Unified Merge Driver SYNOPSIS -------- -'git-merge' [-n] [--no-commit] [-s <strategy>]... <msg> <head> <remote> <remote>... - +[verse] +'git-merge' [-n] [--no-commit] [--squash] [-s <strategy>]... + -m=<msg> <remote> <remote>... DESCRIPTION ----------- -This is the top-level user interface to the merge machinery +This is the top-level interface to the merge machinery which drives multiple merge strategy scripts. @@ -27,10 +28,11 @@ include::merge-options.txt[] to give a good default for automated `git-merge` invocations. <head>:: - our branch head commit. + Our branch head commit. This has to be `HEAD`, so new + syntax does not require it <remote>:: - other branch head merged into our branch. You need at + Other branch head merged into our branch. You need at least one <remote>. Specifying more than one <remote> obviously means you are trying an Octopus. diff --git a/Documentation/git-p4import.txt b/Documentation/git-p4import.txt index ee9e8fa90..6edb9f12b 100644 --- a/Documentation/git-p4import.txt +++ b/Documentation/git-p4import.txt @@ -93,7 +93,7 @@ perforce branch into a branch named "jammy", like so: ------------ $ mkdir -p /home/sean/import/jam $ cd /home/sean/import/jam -$ git init-db +$ git init $ git p4import //public/jam jammy ------------ diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt index 4991f88c9..fdc6f9728 100644 --- a/Documentation/git-pack-objects.txt +++ b/Documentation/git-pack-objects.txt @@ -9,9 +9,9 @@ git-pack-objects - Create a packed archive of objects SYNOPSIS -------- [verse] -'git-pack-objects' [-q] [--no-reuse-delta] [--non-empty] - [--local] [--incremental] [--window=N] [--depth=N] - {--stdout | base-name} < object-list +'git-pack-objects' [-q] [--no-reuse-delta] [--delta-base-offset] [--non-empty] + [--local] [--incremental] [--window=N] [--depth=N] [--all-progress] + [--revs [--unpacked | --all]*] [--stdout | base-name] < object-list DESCRIPTION @@ -47,17 +47,34 @@ base-name:: <base-name> to determine the name of the created file. When this option is used, the two files are written in <base-name>-<SHA1>.{pack,idx} files. <SHA1> is a hash - of object names (currently in random order so it does - not have any useful meaning) to make the resulting - filename reasonably unique, and written to the standard + of the sorted object names to make the resulting filename + based on the pack content, and written to the standard output of the command. --stdout:: Write the pack contents (what would have been written to .pack file) out to the standard output. ---window and --depth:: - These two options affects how the objects contained in +--revs:: + Read the revision arguments from the standard input, instead of + individual object names. The revision arguments are processed + the same way as gitlink:git-rev-list[1] with `--objects` flag + uses its `commit` arguments to build the list of objects it + outputs. The objects on the resulting list are packed. + +--unpacked:: + This implies `--revs`. When processing the list of + revision arguments read from the standard input, limit + the objects packed to those that are not already packed. + +--all:: + This implies `--revs`. In addition to the list of + revision arguments read from the standard input, pretend + as if all refs under `$GIT_DIR/refs` are specified to be + included. + +--window=[N], --depth=[N]:: + These two options affect how the objects contained in the pack are stored using delta compression. The objects are first internally sorted by type, size and optionally names and compared against the other objects @@ -66,6 +83,7 @@ base-name:: it too deep affects the performance on the unpacker side, because delta data needs to be applied that many times to get to the necessary object. + The default value for both --window and --depth is 10. --incremental:: This flag causes an object already in a pack ignored @@ -81,6 +99,23 @@ base-name:: Only create a packed archive if it would contain at least one object. +--progress:: + Progress status is reported on the standard error stream + by default when it is attached to a terminal, unless -q + is specified. This flag forces progress status even if + the standard error stream is not directed to a terminal. + +--all-progress:: + When --stdout is specified then progress report is + displayed during the object count and deltification phases + but inhibited during the write-out phase. The reason is + that in some cases the output stream is directly linked + to another command which may wish to display progress + status of its own as it processes incoming pack data. + This flag is like --progress except that it forces progress + report for the write-out phase as well even if --stdout is + used. + -q:: This flag makes the command not to report its progress on the standard error stream. @@ -92,6 +127,17 @@ base-name:: This flag tells the command not to reuse existing deltas but compute them from scratch. +--delta-base-offset:: + A packed archive can express base object of a delta as + either 20-byte object name or as an offset in the + stream, but older version of git does not understand the + latter. By default, git-pack-objects only uses the + former format for better compatibility. This option + allows the command to use the latter format for + compactness. Depending on the average delta chain + length, this option typically shrinks the resulting + packfile by 3-5 per-cent. + Author ------ @@ -103,6 +149,7 @@ Documentation by Junio C Hamano See Also -------- +gitlink:git-rev-list[1] gitlink:git-repack[1] gitlink:git-prune-packed[1] diff --git a/Documentation/git-pack-refs.txt b/Documentation/git-pack-refs.txt new file mode 100644 index 000000000..464269fbb --- /dev/null +++ b/Documentation/git-pack-refs.txt @@ -0,0 +1,55 @@ +git-pack-refs(1) +================ + +NAME +---- +git-pack-refs - Pack heads and tags for efficient repository access + +SYNOPSIS +-------- +'git-pack-refs' [--all] [--no-prune] + +DESCRIPTION +----------- + +Traditionally, tips of branches and tags (collectively known as +'refs') were stored one file per ref under `$GIT_DIR/refs` +directory. While many branch tips tend to be updated often, +most tags and some branch tips are never updated. When a +repository has hundreds or thousands of tags, this +one-file-per-ref format both wastes storage and hurts +performance. + +This command is used to solve the storage and performance +problem by stashing the refs in a single file, +`$GIT_DIR/packed-refs`. When a ref is missing from the +traditional `$GIT_DIR/refs` hierarchy, it is looked up in this +file and used if found. + +Subsequent updates to branches always creates new file under +`$GIT_DIR/refs` hierarchy. + +OPTIONS +------- + +\--all:: + +The command by default packs all tags and leaves branch tips +alone. This is because branches are expected to be actively +developed and packing their tips does not help performance. +This option causes branch tips to be packed as well. Useful for +a repository with many branches of historical interests. + +\--no-prune:: + +The command usually removes loose refs under `$GIT_DIR/refs` +hierarchy after packing them. This option tells it not to. + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +GIT +--- +Part of the gitlink:git[7] suite diff --git a/Documentation/git-prune-packed.txt b/Documentation/git-prune-packed.txt index 234882685..a79193fb0 100644 --- a/Documentation/git-prune-packed.txt +++ b/Documentation/git-prune-packed.txt @@ -9,7 +9,7 @@ residing in a pack file. SYNOPSIS -------- -'git-prune-packed' [-n] +'git-prune-packed' [-n] [-q] DESCRIPTION @@ -32,6 +32,9 @@ OPTIONS Don't actually remove any objects, only show those that would have been removed. +-q:: + Squelch the progress indicator. + Author ------ Written by Linus Torvalds <torvalds@osdl.org> diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt index 51577fcbe..13be99200 100644 --- a/Documentation/git-pull.txt +++ b/Documentation/git-pull.txt @@ -3,7 +3,7 @@ git-pull(1) NAME ---- -git-pull - Pull and merge from another repository +git-pull - Pull and merge from another repository or a local branch SYNOPSIS @@ -37,17 +37,27 @@ EXAMPLES -------- git pull, git pull origin:: - Fetch the default head from the repository you cloned - from and merge it into your current branch. - -git pull -s ours . obsolete:: - Merge local branch `obsolete` into the current branch, - using `ours` merge strategy. + Update the remote-tracking branches for the repository + you cloned from, then merge one of them into your + current branch. Normally the branch merged in is + the HEAD of the remote repository, but the choice is + determined by the branch.<name>.remote and + branch.<name>.merge options; see gitlink:git-repo-config[1] + for details. + +git pull origin next:: + Merge into the current branch the remote branch `next`; + leaves a copy of `next` temporarily in FETCH_HEAD, but + does not update any remote-tracking branches. git pull . fixes enhancements:: Bundle local branch `fixes` and `enhancements` on top of the current branch, making an Octopus merge. +git pull -s ours . obsolete:: + Merge local branch `obsolete` into the current branch, + using `ours` merge strategy. + git pull --no-commit . maint:: Merge local branch `maint` into the current branch, but do not make a commit automatically. This can be used @@ -61,48 +71,19 @@ release/version name would be acceptable. Command line pull of multiple branches from one repository:: + ------------------------------------------------ -$ cat .git/remotes/origin -URL: git://git.kernel.org/pub/scm/git/git.git -Pull: master:origin - $ git checkout master -$ git fetch origin master:origin +pu:pu maint:maint -$ git pull . origin +$ git fetch origin +pu:pu maint:tmp +$ git pull . tmp ------------------------------------------------ + -Here, a typical `.git/remotes/origin` file from a -`git-clone` operation is used in combination with -command line options to `git-fetch` to first update -multiple branches of the local repository and then -to merge the remote `origin` branch into the local -`master` branch. The local `pu` branch is updated -even if it does not result in a fast forward update. -Here, the pull can obtain its objects from the local -repository using `.`, as the previous `git-fetch` is -known to have already obtained and made available -all the necessary objects. - - -Pull of multiple branches from one repository using `.git/remotes` file:: +This updates (or creates, as necessary) branches `pu` and `tmp` +in the local repository by fetching from the branches +(respectively) `pu` and `maint` from the remote repository. + ------------------------------------------------- -$ cat .git/remotes/origin -URL: git://git.kernel.org/pub/scm/git/git.git -Pull: master:origin -Pull: +pu:pu -Pull: maint:maint - -$ git checkout master -$ git pull origin ------------------------------------------------- +The `pu` branch will be updated even if it is does not +fast-forward; the others will not be. + -Here, a typical `.git/remotes/origin` file from a -`git-clone` operation has been hand-modified to include -the branch-mapping of additional remote and local -heads directly. A single `git-pull` operation while -in the `master` branch will fetch multiple heads and -merge the remote `origin` head into the current, -local `master` branch. +The final command then merges the newly fetched `tmp` into master. If you tried a pull which resulted in a complex conflicts and @@ -112,7 +93,7 @@ gitlink:git-reset[1]. SEE ALSO -------- -gitlink:git-fetch[1], gitlink:git-merge[1] +gitlink:git-fetch[1], gitlink:git-merge[1], gitlink:git-repo-config[1] Author diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index d4ae99fa5..197f4b512 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -49,12 +49,14 @@ corresponding remotes file---see below), then all the refs that exist both on the local side and on the remote side are updated. + -Some short-cut notations are also supported. +`tag <tag>` means the same as `refs/tags/<tag>:refs/tags/<tag>`. + -* `tag <tag>` means the same as `refs/tags/<tag>:refs/tags/<tag>`. -* A parameter <ref> without a colon is equivalent to - <ref>`:`<ref>, hence updates <ref> in the destination from <ref> - in the source. +A parameter <ref> without a colon is equivalent to +<ref>`:`<ref>, hence updates <ref> in the destination from <ref> +in the source. ++ +Pushing an empty <src> allows you to delete the <dst> ref from +the remote repository. \--all:: Instead of naming each ref to push, specifies that all @@ -75,7 +77,8 @@ include::urls.txt[] Author ------ -Written by Junio C Hamano <junkio@cox.net> +Written by Junio C Hamano <junkio@cox.net>, later rewritten in C +by Linus Torvalds <torvalds@osdl.org> Documentation -------------- diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt index 11bd9c0ad..0ff2890c7 100644 --- a/Documentation/git-read-tree.txt +++ b/Documentation/git-read-tree.txt @@ -8,7 +8,7 @@ git-read-tree - Reads tree information into the index SYNOPSIS -------- -'git-read-tree' (<tree-ish> | [[-m [--aggressive] | --reset | --prefix=<prefix>] [-u | -i]] <tree-ish1> [<tree-ish2> [<tree-ish3>]]) +'git-read-tree' (<tree-ish> | [[-m [--aggressive] | --reset | --prefix=<prefix>] [-u | -i]] [--exclude-per-directory=<gitignore>] <tree-ish1> [<tree-ish2> [<tree-ish3>]]) DESCRIPTION @@ -71,6 +71,20 @@ OPTIONS directory. Note that the `<prefix>/` value must end with a slash. +--exclude-per-directory=<gitignore>:: + When running the command with `-u` and `-m` options, the + merge result may need to overwrite paths that are not + tracked in the current branch. The command usually + refuses to proceed with the merge to avoid losing such a + path. However this safety valve sometimes gets in the + way. For example, it often happens that the other + branch added a file that used to be a generated file in + your branch, and the safety valve triggers when you try + to switch to that branch after you ran `make` but before + running `make clean` to remove the generated file. This + option tells the command to read per-directory exclude + file (usually '.gitignore') and allows such an untracked + but explicitly ignored file to be overwritten. <tree-ish#>:: The id of the tree object(s) to be read/merged. diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index 9d7bcaa38..03e867a40 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -7,7 +7,7 @@ git-rebase - Rebase local commits to a new head SYNOPSIS -------- -'git-rebase' [--merge] [--onto <newbase>] <upstream> [<branch>] +'git-rebase' [-v] [--merge] [--onto <newbase>] <upstream> [<branch>] 'git-rebase' --continue | --skip | --abort @@ -51,20 +51,69 @@ would be: D---E---F---G master ------------ -While, starting from the same point, the result of either of the following -commands: +The latter form is just a short-hand of `git checkout topic` +followed by `git rebase master`. - git-rebase --onto master~1 master - git-rebase --onto master~1 master topic +Here is how you would transplant a topic branch based on one +branch to another, to pretend that you forked the topic branch +from the latter branch, using `rebase --onto`. -would be: +First let's assume your 'topic' is based on branch 'next'. +For example feature developed in 'topic' depends on some +functionality which is found in 'next'. ------------ - A'--B'--C' topic - / - D---E---F---G master + o---o---o---o---o master + \ + o---o---o---o---o next + \ + o---o---o topic +------------ + +We would want to make 'topic' forked from branch 'master', +for example because the functionality 'topic' branch depend on +got merged into more stable 'master' branch, like this: + +------------ + o---o---o---o---o master + | \ + | o'--o'--o' topic + \ + o---o---o---o---o next +------------ + +We can get this using the following command: + + git-rebase --onto master next topic + + +Another example of --onto option is to rebase part of a +branch. If we have the following situation: + +------------ + H---I---J topicB + / + E---F---G topicA + / + A---B---C---D master ------------ +then the command + + git-rebase --onto master topicA topicB + +would result in: + +------------ + H'--I'--J' topicB + / + | E---F---G topicA + |/ + A---B---C---D master +------------ + +This is useful when topicB does not depend on topicA. + In case of conflict, git-rebase will stop at the first problematic commit and leave conflict markers in the tree. You can use git diff to locate the markers (<<<<<<) and make edits to resolve the conflict. For each @@ -121,6 +170,9 @@ OPTIONS is used instead (`git-merge-recursive` when merging a single head, `git-merge-octopus` otherwise). This implies --merge. +-v, \--verbose:: + Display a diffstat of what changed upstream since the last rebase. + include::merge-strategies.txt[] NOTES diff --git a/Documentation/git-receive-pack.txt b/Documentation/git-receive-pack.txt index f9457d45e..0dfadc2a3 100644 --- a/Documentation/git-receive-pack.txt +++ b/Documentation/git-receive-pack.txt @@ -73,6 +73,8 @@ packed and is served via a dumb transport. There are other real-world examples of using update and post-update hooks found in the Documentation/howto directory. +git-receive-pack honours the receive.denyNonFastforwards flag, which +tells it if updates to a ref should be denied if they are not fast-forwards. OPTIONS ------- diff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt new file mode 100644 index 000000000..55a24d326 --- /dev/null +++ b/Documentation/git-reflog.txt @@ -0,0 +1,59 @@ +git-reflog(1) +============= + +NAME +---- +git-reflog - Manage reflog information + + +SYNOPSIS +-------- +[verse] +'git-reflog' expire [--dry-run] + [--expire=<time>] [--expire-unreachable=<time>] [--all] <refs>... + + +DESCRIPTION +----------- + +Reflog is a mechanism to record when the tip of branches are +updated. This command is to manage the information recorded in it. + +The subcommand "expire" is used to prune older reflog entries. +Entries older than `expire` time, or entries older than +`expire-unreachable` time and are not reachable from the current +tip, are removed from the reflog. This is typically not used +directly by the end users -- instead, see gitlink:git-gc[1]. + + + +OPTIONS +------- + +--expire=<time>:: + Entries older than this time are pruned. Without the + option it is taken from configuration `gc.reflogExpire`, + which in turn defaults to 90 days. + +--expire-unreachable=<time>:: + Entries older than this time and are not reachable from + the current tip of the branch are pruned. Without the + option it is taken from configuration + `gc.reflogExpireUnreachable`, which in turn defaults to + 30 days. + +--all:: + Instead of listing <refs> explicitly, prune all refs. + +Author +------ +Written by Junio C Hamano <junkio@cox.net> + +Documentation +-------------- +Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt new file mode 100644 index 000000000..5b93a8c8b --- /dev/null +++ b/Documentation/git-remote.txt @@ -0,0 +1,76 @@ +git-remote(1) +============ + +NAME +---- +git-remote - manage set of tracked repositories + + +SYNOPSIS +-------- +[verse] +'git-remote' +'git-remote' add <name> <url> +'git-remote' show <name> + +DESCRIPTION +----------- + +Manage the set of repositories ("remotes") whose branches you track. + +With no arguments, shows a list of existing remotes. + +In the second form, adds a remote named <name> for the repository at +<url>. The command `git fetch <name>` can then be used to create and +update remote-tracking branches <name>/<branch>. + +In the third form, gives some information about the remote <name>. + +The remote configuration is achieved using the `remote.origin.url` and +`remote.origin.fetch` configuration variables. (See +gitlink:git-repo-config[1]). + +Examples +-------- + +Add a new remote, fetch, and check out a branch from it: + +------------ +$ git remote +origin +$ git branch -r +origin/master +$ git remote add linux-nfs git://linux-nfs.org/pub/nfs-2.6.git +$ git remote +linux-nfs +origin +$ git fetch +* refs/remotes/linux-nfs/master: storing branch 'master' ... + commit: bf81b46 +$ git branch -r +origin/master +linux-nfs/master +$ git checkout -b nfs linux-nfs/master +... +------------ + +See Also +-------- +gitlink:git-fetch[1] +gitlink:git-branch[1] +gitlink:git-repo-config[1] + +Author +------ +Written by Junio Hamano + + +Documentation +-------------- +Documentation by J. Bruce Fields and the git-list <git@vger.kernel.org>. + + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-repack.txt b/Documentation/git-repack.txt index 951622774..0fa47e3b0 100644 --- a/Documentation/git-repack.txt +++ b/Documentation/git-repack.txt @@ -9,7 +9,7 @@ objects into pack files. SYNOPSIS -------- -'git-repack' [-a] [-d] [-f] [-l] [-n] [-q] +'git-repack' [-a] [-d] [-f] [-l] [-n] [-q] [--window=N] [--depth=N] DESCRIPTION ----------- @@ -56,6 +56,31 @@ OPTIONS Do not update the server information with `git update-server-info`. +--window=[N], --depth=[N]:: + These two options affect how the objects contained in the pack are + stored using delta compression. The objects are first internally + sorted by type, size and optionally names and compared against the + other objects within `--window` to see if using delta compression saves + space. `--depth` limits the maximum delta depth; making it too deep + affects the performance on the unpacker side, because delta data needs + to be applied that many times to get to the necessary object. + The default value for both --window and --depth is 10. + + +Configuration +------------- + +When configuration variable `repack.UseDeltaBaseOffset` is set +for the repository, the command passes `--delta-base-offset` +option to `git-pack-objects`; this typically results in slightly +smaller packs, but the generated packs are incompatible with +versions of git older than (and including) v1.4.3; do not set +the variable in a repository that older version of git needs to +be able to read (this includes repositories from which packs can +be copied out over http or rsync, and people who obtained packs +that way can try to use older git with it). + + Author ------ Written by Linus Torvalds <torvalds@osdl.org> diff --git a/Documentation/git-repo-config.txt b/Documentation/git-repo-config.txt index b03d66f61..c55a8ba0d 100644 --- a/Documentation/git-repo-config.txt +++ b/Documentation/git-repo-config.txt @@ -3,19 +3,20 @@ git-repo-config(1) NAME ---- -git-repo-config - Get and set options in .git/config +git-repo-config - Get and set repository or global options. SYNOPSIS -------- [verse] -'git-repo-config' [type] name [value [value_regex]] -'git-repo-config' [type] --replace-all name [value [value_regex]] -'git-repo-config' [type] --get name [value_regex] -'git-repo-config' [type] --get-all name [value_regex] -'git-repo-config' [type] --unset name [value_regex] -'git-repo-config' [type] --unset-all name [value_regex] -'git-repo-config' -l | --list +'git-repo-config' [--global] [type] name [value [value_regex]] +'git-repo-config' [--global] [type] --add name value +'git-repo-config' [--global] [type] --replace-all name [value [value_regex]] +'git-repo-config' [--global] [type] --get name [value_regex] +'git-repo-config' [--global] [type] --get-all name [value_regex] +'git-repo-config' [--global] [type] --unset name [value_regex] +'git-repo-config' [--global] [type] --unset-all name [value_regex] +'git-repo-config' [--global] -l | --list DESCRIPTION ----------- @@ -23,7 +24,8 @@ You can query/set/replace/unset options with this command. The name is actually the section and the key separated by a dot, and the value will be escaped. -If you want to set/unset an option which can occur on multiple +Multiple lines can be added to an option by using the '--add' option. +If you want to update or unset an option which can occur on multiple lines, a POSIX regexp `value_regex` needs to be given. Only the existing values that match the regexp are updated or unset. If you want to handle the lines that do *not* match the regex, just @@ -41,8 +43,9 @@ This command will fail if: . Can not write to .git/config, . no section was provided, . the section or key is invalid, -. you try to unset an option which does not exist, or -. you try to unset/set an option for which multiple lines match. +. you try to unset an option which does not exist, +. you try to unset/set an option for which multiple lines match, or +. you use --global option without $HOME being properly set. OPTIONS @@ -52,9 +55,14 @@ OPTIONS Default behavior is to replace at most one line. This replaces all lines matching the key (and optionally the value_regex). +--add:: + Adds a new line to the option without altering any existing + values. This is the same as providing '^$' as the value_regex. + --get:: Get the value for a given key (optionally filtered by a regex - matching the value). + matching the value). Returns error code 1 if the key was not + found and error code 2 if multiple key values were found. --get-all:: Like get, but does not fail if the number of values for the key @@ -63,14 +71,26 @@ OPTIONS --get-regexp:: Like --get-all, but interprets the name as a regular expression. +--global:: + Use global ~/.gitconfig file rather than the repository .git/config. + --unset:: - Remove the line matching the key from .git/config. + Remove the line matching the key from config file. --unset-all:: - Remove all matching lines from .git/config. + Remove all matching lines from config file. -l, --list:: - List all variables set in .git/config. + List all variables set in config file. + +--bool:: + git-repo-config will ensure that the output is "true" or "false" + +--int:: + git-repo-config will ensure that the output is a simple + decimal number. An optional value suffix of 'k', 'm', or 'g' + in the config file will cause the value to be multiplied + by 1024, 1048576, or 1073741824 prior to output. ENVIRONMENT @@ -78,6 +98,7 @@ ENVIRONMENT GIT_CONFIG:: Take the configuration from the given file instead of .git/config. + Using the "--global" option forces this to ~/.gitconfig. GIT_CONFIG_LOCAL:: Currently the same as $GIT_CONFIG; when Git will support global @@ -182,6 +203,12 @@ To actually match only values with an exclamation mark, you have to % git repo-config section.key value '[!]' ------------ +To add a new proxy, without altering any of the existing ones, use + +------------ +% git repo-config core.gitproxy '"proxy" for example.com' +------------ + include::config.txt[] diff --git a/Documentation/git-rerere.txt b/Documentation/git-rerere.txt index 8b6b65123..b57a72bdd 100644 --- a/Documentation/git-rerere.txt +++ b/Documentation/git-rerere.txt @@ -7,8 +7,7 @@ git-rerere - Reuse recorded resolve SYNOPSIS -------- -'git-rerere' - +'git-rerere' [clear|diff|status|gc] DESCRIPTION ----------- @@ -27,6 +26,42 @@ results and applying the previously recorded hand resolution. You need to create `$GIT_DIR/rr-cache` directory to enable this command. + +COMMANDS +-------- + +Normally, git-rerere is run without arguments or user-intervention. +However, it has several commands that allow it to interact with +its working state. + +'clear':: + +This resets the metadata used by rerere if a merge resolution is to be +is aborted. Calling gitlink:git-am[1] --skip or gitlink:git-rebase[1] +[--skip|--abort] will automatcally invoke this command. + +'diff':: + +This displays diffs for the current state of the resolution. It is +useful for tracking what has changed while the user is resolving +conflicts. Additional arguments are passed directly to the system +diff(1) command installed in PATH. + +'status':: + +Like diff, but this only prints the filenames that will be tracked +for resolutions. + +'gc':: + +This command is used to prune records of conflicted merge that +occurred long time ago. By default, conflicts older than 15 +days that you have not recorded their resolution, and conflicts +older than 60 days, are pruned. These are controlled with +`gc.rerereunresolved` and `gc.rerereresolved` configuration +variables. + + DISCUSSION ---------- diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt index 73a0ffc41..4f424782e 100644 --- a/Documentation/git-reset.txt +++ b/Documentation/git-reset.txt @@ -7,7 +7,9 @@ git-reset - Reset current HEAD to the specified state SYNOPSIS -------- -'git-reset' [--mixed | --soft | --hard] [<commit-ish>] +[verse] +'git-reset' [--mixed | --soft | --hard] [<commit>] +'git-reset' [--mixed] <commit> [--] <paths>... DESCRIPTION ----------- @@ -21,6 +23,10 @@ the undo in the history. If you want to undo a commit other than the latest on a branch, gitlink:git-revert[1] is your friend. +The second form with 'paths' is used to revert selected paths in +the index from a given commit, without moving HEAD. + + OPTIONS ------- --mixed:: @@ -31,15 +37,15 @@ OPTIONS --soft:: Does not touch the index file nor the working tree at all, but requires them to be in a good order. This leaves all your changed - files "Updated but not checked in", as gitlink:git-status[1] would + files "Added but not yet committed", as gitlink:git-status[1] would put it. --hard:: Matches the working tree and index to that of the tree being switched to. Any changes to tracked files in the working tree - since <commit-ish> are lost. + since <commit> are lost. -<commit-ish>:: +<commit>:: Commit to make the current HEAD. Examples diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt index dd9fff16d..86c94e7df 100644 --- a/Documentation/git-rev-list.txt +++ b/Documentation/git-rev-list.txt @@ -10,6 +10,7 @@ SYNOPSIS -------- [verse] 'git-rev-list' [ \--max-count=number ] + [ \--skip=number ] [ \--max-age=timestamp ] [ \--min-age=timestamp ] [ \--sparse ] @@ -17,8 +18,11 @@ SYNOPSIS [ \--remove-empty ] [ \--not ] [ \--all ] + [ \--stdin ] [ \--topo-order ] [ \--parents ] + [ \--encoding[=<encoding>] ] + [ \--(author|committer|grep)=<pattern> ] [ [\--objects | \--objects-edge] [ \--unpacked ] ] [ \--pretty | \--header ] [ \--bisect ] @@ -27,116 +31,258 @@ SYNOPSIS DESCRIPTION ----------- + Lists commit objects in reverse chronological order starting at the given commit(s), taking ancestry relationship into account. This is useful to produce human-readable log output. -Commits which are stated with a preceding '{caret}' cause listing to stop at -that point. Their parents are implied. "git-rev-list foo bar {caret}baz" thus +Commits which are stated with a preceding '{caret}' cause listing to +stop at that point. Their parents are implied. Thus the following +command: + +----------------------------------------------------------------------- + $ git-rev-list foo bar ^baz +----------------------------------------------------------------------- + means "list all the commits which are included in 'foo' and 'bar', but not in 'baz'". -A special notation <commit1>..<commit2> can be used as a -short-hand for {caret}<commit1> <commit2>. +A special notation "'<commit1>'..'<commit2>'" can be used as a +short-hand for "{caret}'<commit1>' '<commit2>'". For example, either of +the following may be used interchangeably: -Another special notation is <commit1>...<commit2> which is useful for -merges. The resulting set of commits is the symmetric difference +----------------------------------------------------------------------- + $ git-rev-list origin..HEAD + $ git-rev-list HEAD ^origin +----------------------------------------------------------------------- + +Another special notation is "'<commit1>'...'<commit2>'" which is useful +for merges. The resulting set of commits is the symmetric difference between the two operands. The following two commands are equivalent: ------------- -$ git-rev-list A B --not $(git-merge-base --all A B) -$ git-rev-list A...B ------------- +----------------------------------------------------------------------- + $ git-rev-list A B --not $(git-merge-base --all A B) + $ git-rev-list A...B +----------------------------------------------------------------------- + +gitlink:git-rev-list[1] is a very essential git program, since it +provides the ability to build and traverse commit ancestry graphs. For +this reason, it has a lot of different options that enables it to be +used by commands as different as gitlink:git-bisect[1] and +gitlink:git-repack[1]. OPTIONS ------- ---pretty:: - Print the contents of the commit changesets in human-readable form. + +Commit Formatting +~~~~~~~~~~~~~~~~~ + +Using these options, gitlink:git-rev-list[1] will act similar to the +more specialized family of commit log tools: gitlink:git-log[1], +gitlink:git-show[1], and gitlink:git-whatchanged[1] + +include::pretty-formats.txt[] + +--relative-date:: + + Show dates relative to the current time, e.g. "2 hours ago". + Only takes effect for dates shown in human-readable format, such + as when using "--pretty". --header:: - Print the contents of the commit in raw-format; each - record is separated with a NUL character. + + Print the contents of the commit in raw-format; each record is + separated with a NUL character. --parents:: + Print the parents of the commit. ---objects:: - Print the object IDs of any object referenced by the listed commits. - 'git-rev-list --objects foo ^bar' thus means "send me all object IDs - which I need to download if I have the commit object 'bar', but - not 'foo'". +Diff Formatting +~~~~~~~~~~~~~~~ ---objects-edge:: - Similar to `--objects`, but also print the IDs of - excluded commits prefixed with a `-` character. This is - used by `git-pack-objects` to build 'thin' pack, which - records objects in deltified form based on objects - contained in these excluded commits to reduce network - traffic. +Below are listed options that control the formatting of diff output. +Some of them are specific to gitlink:git-rev-list[1], however other diff +options may be given. See gitlink:git-diff-files[1] for more options. ---unpacked:: - Only useful with `--objects`; print the object IDs that - are not in packs. +-c:: + + This flag changes the way a merge commit is displayed. It shows + the differences from each of the parents to the merge result + simultaneously instead of showing pairwise diff between a parent + and the result one at a time. Furthermore, it lists only files + which were modified from all parents. + +--cc:: + + This flag implies the '-c' options and further compresses the + patch output by omitting hunks that show differences from only + one parent, or show the same change from all but one parent for + an Octopus merge. + +-r:: + + Show recursive diffs. + +-t:: + + Show the tree objects in the diff output. This implies '-r'. + +Commit Limiting +~~~~~~~~~~~~~~~ + +Besides specifying a range of commits that should be listed using the +special notations explained in the description, additional commit +limiting may be applied. + +-- + +-n 'number', --max-count='number':: ---bisect:: - Limit output to the one commit object which is roughly halfway - between the included and excluded commits. Thus, if 'git-rev-list - --bisect foo {caret}bar {caret}baz' outputs 'midpoint', the output - of 'git-rev-list foo {caret}midpoint' and 'git-rev-list midpoint - {caret}bar {caret}baz' would be of roughly the same length. - Finding the change - which introduces a regression is thus reduced to a binary search: - repeatedly generate and test new 'midpoint's until the commit chain - is of length one. - ---max-count:: Limit the number of commits output. ---max-age=timestamp, --min-age=timestamp:: +--skip='number':: + + Skip 'number' commits before starting to show the commit output. + +--since='date', --after='date':: + + Show commits more recent than a specific date. + +--until='date', --before='date':: + + Show commits older than a specific date. + +--max-age='timestamp', --min-age='timestamp':: + Limit the commits output to specified time range. ---sparse:: - When optional paths are given, the command outputs only - the commits that changes at least one of them, and also - ignores merges that do not touch the given paths. This - flag makes the command output all eligible commits - (still subject to count and age limitation), but apply - merge simplification nevertheless. +--author='pattern', --committer='pattern':: + + Limit the commits output to ones with author/committer + header lines that match the specified pattern. + +--grep='pattern':: + + Limit the commits output to ones with log message that + matches the specified pattern. --remove-empty:: + Stop when a given path disappears from the tree. --no-merges:: + Do not print commits with more than one parent. --not:: - Reverses the meaning of the '{caret}' prefix (or lack - thereof) for all following revision specifiers, up to - the next `--not`. + + Reverses the meaning of the '{caret}' prefix (or lack thereof) + for all following revision specifiers, up to the next '--not'. --all:: - Pretend as if all the refs in `$GIT_DIR/refs/` are - listed on the command line as <commit>. ---topo-order:: - By default, the commits are shown in reverse - chronological order. This option makes them appear in - topological order (i.e. descendant commits are shown - before their parents). + Pretend as if all the refs in `$GIT_DIR/refs/` are listed on the + command line as '<commit>'. + +--stdin:: + + In addition to the '<commit>' listed on the command + line, read them from the standard input. --merge:: + After a failed merge, show refs that touch files having a conflict and don't exist on all heads to merge. +--boundary:: + + Output uninteresting commits at the boundary, which are usually + not shown. + +--dense, --sparse:: + +When optional paths are given, the default behaviour ('--dense') is to +only output commits that changes at least one of them, and also ignore +merges that do not touch the given paths. + +Use the '--sparse' flag to makes the command output all eligible commits +(still subject to count and age limitation), but apply merge +simplification nevertheless. + +--bisect:: + +Limit output to the one commit object which is roughly halfway between +the included and excluded commits. Thus, if + +----------------------------------------------------------------------- + $ git-rev-list --bisect foo ^bar ^baz +----------------------------------------------------------------------- + +outputs 'midpoint', the output of the two commands + +----------------------------------------------------------------------- + $ git-rev-list foo ^midpoint + $ git-rev-list midpoint ^bar ^baz +----------------------------------------------------------------------- + +would be of roughly the same length. Finding the change which +introduces a regression is thus reduced to a binary search: repeatedly +generate and test new 'midpoint's until the commit chain is of length +one. + +-- + +Commit Ordering +~~~~~~~~~~~~~~~ + +By default, the commits are shown in reverse chronological order. + +--topo-order:: + + This option makes them appear in topological order (i.e. + descendant commits are shown before their parents). + +--date-order:: + + This option is similar to '--topo-order' in the sense that no + parent comes before all of its children, but otherwise things + are still ordered in the commit timestamp order. + +Object Traversal +~~~~~~~~~~~~~~~~ + +These options are mostly targeted for packing of git repositories. + +--objects:: + + Print the object IDs of any object referenced by the listed + commits. 'git-rev-list --objects foo ^bar' thus means "send me + all object IDs which I need to download if I have the commit + object 'bar', but not 'foo'". + +--objects-edge:: + + Similar to '--objects', but also print the IDs of excluded + commits prefixed with a "-" character. This is used by + gitlink:git-pack-objects[1] to build "thin" pack, which records + objects in deltified form based on objects contained in these + excluded commits to reduce network traffic. + +--unpacked:: + + Only useful with '--objects'; print the object IDs that are not + in packs. + Author ------ Written by Linus Torvalds <torvalds@osdl.org> Documentation -------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. +Documentation by David Greaves, Junio C Hamano, Jonas Fonseca +and the git-list <git@vger.kernel.org>. GIT --- Part of the gitlink:git[7] suite - diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index b761b4b96..4eaf5a0d1 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -111,7 +111,9 @@ SPECIFYING REVISIONS A revision parameter typically, but not necessarily, names a commit object. They use what is called an 'extended SHA1' -syntax. +syntax. Here are various ways to spell object names. The +ones listed near the end of this list are to name trees and +blobs contained in a commit. * The full SHA1 object name (40-byte hexadecimal string), or a substring of such that is unique within the repository. @@ -119,12 +121,31 @@ syntax. name the same commit object if there are no other object in your repository whose object name starts with dae86e. +* An output from `git-describe`; i.e. a closest tag, followed by a + dash, a `g`, and an abbreviated object name. + * A symbolic ref name. E.g. 'master' typically means the commit object referenced by $GIT_DIR/refs/heads/master. If you happen to have both heads/master and tags/master, you can explicitly say 'heads/master' to tell git which one you mean. + When ambiguous, a `<name>` is disambiguated by taking the + first match in the following rules: + + . if `$GIT_DIR/<name>` exists, that is what you mean (this is usually + useful only for `HEAD`, `FETCH_HEAD` and `MERGE_HEAD`); + + . otherwise, `$GIT_DIR/refs/<name>` if exists; + + . otherwise, `$GIT_DIR/refs/tags/<name>` if exists; + + . otherwise, `$GIT_DIR/refs/heads/<name>` if exists; -* A suffix '@' followed by a date specification enclosed in a brace + . otherwise, `$GIT_DIR/refs/remotes/<name>` if exists; + + . otherwise, `$GIT_DIR/refs/remotes/<name>/HEAD` if exists. + +* A ref followed by the suffix '@' with a date specification + enclosed in a brace pair (e.g. '\{yesterday\}', '\{1 month 2 weeks 3 days 1 hour 1 second ago\}' or '\{1979-02-26 18:30:00\}') to specify the value of the ref at a prior point in time. This suffix may only be @@ -138,11 +159,12 @@ syntax. 'rev{caret}0' means the commit itself and is used when 'rev' is the object name of a tag object that refers to a commit object. -* A suffix '~<n>' to a revision parameter means the commit +* A suffix '{tilde}<n>' to a revision parameter means the commit object that is the <n>th generation grand-parent of the named commit object, following only the first parent. I.e. rev~3 is - equivalent to rev{caret}{caret}{caret} which is equivalent to\ - rev{caret}1{caret}1{caret}1. + equivalent to rev{caret}{caret}{caret} which is equivalent to + rev{caret}1{caret}1{caret}1. See below for a illustration of + the usage of this form. * A suffix '{caret}' followed by an object type name enclosed in brace pair (e.g. `v0.99.8{caret}\{commit\}`) means the object @@ -156,6 +178,15 @@ syntax. and dereference the tag recursively until a non-tag object is found. +* A suffix ':' followed by a path; this names the blob or tree + at the given path in the tree-ish object named by the part + before the colon. + +* A colon, optionally followed by a stage number (0 to 3) and a + colon, followed by a path; this names a blob object in the + index at the given path. Missing stage number (and the colon + that follows it) names an stage 0 entry. + Here is an illustration, by Jon Loeliger. Both node B and C are a commit parents of commit node A. Parent commits are ordered left-to-right. @@ -208,14 +239,21 @@ of `r1` and `r2` and is defined as It it the set of commits that are reachable from either one of `r1` or `r2` but not from both. -Here are a few examples: +Two other shorthands for naming a set that is formed by a commit +and its parent commits exists. `r1{caret}@` notation means all +parents of `r1`. `r1{caret}!` includes commit `r1` but excludes +its all parents. + +Here are a handful examples: D A B D D F A B C D F - ^A G B D + ^A G B D ^A F B C F G...I C D F G I - ^B G I C D F G I + ^B G I C D F G I + F^@ A B C + F^! H D F H Author ------ diff --git a/Documentation/git-rm.txt b/Documentation/git-rm.txt index 66fc478f5..3a8f279e1 100644 --- a/Documentation/git-rm.txt +++ b/Documentation/git-rm.txt @@ -7,51 +7,54 @@ git-rm - Remove files from the working tree and from the index SYNOPSIS -------- -'git-rm' [-f] [-n] [-v] [--] <file>... +'git-rm' [-f] [-n] [-r] [--cached] [--] <file>... DESCRIPTION ----------- -A convenience wrapper for git-update-index --remove. For those coming -from cvs, git-rm provides an operation similar to "cvs rm" or "cvs -remove". +Remove files from the working tree and from the index. The +files have to be identical to the tip of the branch, and no +updates to its contents must have been placed in the staging +area (aka index). OPTIONS ------- <file>...:: - Files to remove from the index and optionally, from the - working tree as well. + Files to remove. Fileglobs (e.g. `*.c`) can be given to + remove all matching files. Also a leading directory name + (e.g. `dir` to add `dir/file1` and `dir/file2`) can be + given to remove all files in the directory, recursively, + but this requires `-r` option to be given for safety. -f:: - Remove files from the working tree as well as from the index. + Override the up-to-date check. -n:: Don't actually remove the file(s), just show if they exist in the index. --v:: - Be verbose. +-r:: + Allow recursive removal when a leading directory name is + given. \--:: 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). +\--cached:: + This option can be used to tell the command to remove + the paths only from the index, leaving working tree + files. + DISCUSSION ---------- -The list of <file> given to the command is fed to `git-ls-files` -command to list files that are 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 remove all files in it and its subdirectories (the - directories themselves are never removed from the working tree); - -. Giving the name of a file that is not in the index does not - remove that file. +The list of <file> given to the command can be exact pathnames, +file glob patterns, or leading directory name. The command +removes only the paths that is known to git. Giving the name of +a file that you have not told git about does not remove that file. EXAMPLES @@ -69,10 +72,10 @@ subdirectories of `Documentation/` directory. git-rm -f git-*.sh:: Remove all git-*.sh scripts that are in the index. The files - are removed from the index, and (because of the -f option), - from the working tree as well. Because this example lets the - shell expand the asterisk (i.e. you are listing the files - explicitly), it does not remove `subdir/git-foo.sh`. + are removed from the index, and from the working + tree. Because this example lets the shell expand the + asterisk (i.e. you are listing the files explicitly), it + does not remove `subdir/git-foo.sh`. See Also -------- diff --git a/Documentation/git-runstatus.txt b/Documentation/git-runstatus.txt new file mode 100644 index 000000000..89d7b9273 --- /dev/null +++ b/Documentation/git-runstatus.txt @@ -0,0 +1,69 @@ +git-runstatus(1) +================ + +NAME +---- +git-runstatus - A helper for git-status and git-commit + + +SYNOPSIS +-------- +'git-runstatus' [--color|--nocolor] [--amend] [--verbose] [--untracked] + + +DESCRIPTION +----------- +Examines paths in the working tree that has changes unrecorded +to the index file, and changes between the index file and the +current HEAD commit. The former paths are what you _could_ +commit by running 'git-update-index' before running 'git +commit', and the latter paths are what you _would_ commit by +running 'git commit'. + +If there is no path that is different between the index file and +the current HEAD commit, the command exits with non-zero status. + +Note that this is _not_ the user level command you would want to +run from the command line. Use 'git-status' instead. + + +OPTIONS +------- +--color:: + Show colored status, highlighting modified file names. + +--nocolor:: + Turn off coloring. + +--amend:: + Show status based on HEAD^1, not HEAD, i.e. show what + 'git-commit --amend' would do. + +--verbose:: + Show unified diff of all file changes. + +--untracked:: + Show files in untracked directories, too. Without this + option only its name and a trailing slash are displayed + for each untracked directory. + + +OUTPUT +------ +The output from this command is designed to be used as a commit +template comments, and all the output lines are prefixed with '#'. + + +Author +------ +Originally written by Linus Torvalds <torvalds@osdl.org> as part +of git-commit, and later rewritten in C by Jeff King. + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt index 481b3f50e..4c8d907bd 100644 --- a/Documentation/git-send-email.txt +++ b/Documentation/git-send-email.txt @@ -66,8 +66,13 @@ The options available are: all that is output. --smtp-server:: - If set, specifies the outgoing SMTP server to use. Defaults to - localhost. + If set, specifies the outgoing SMTP server to use. A full + pathname of a sendmail-like program can be specified instead; + the program must support the `-i` option. Default value can + be specified by the 'sendemail.smtpserver' configuration + option; the built-in default is `/usr/sbin/sendmail` or + `/usr/lib/sendmail` if such program is available, or + `localhost` otherwise. --subject:: Specify the initial subject of the email thread. diff --git a/Documentation/git-send-pack.txt b/Documentation/git-send-pack.txt index 9e67f1730..5376f6854 100644 --- a/Documentation/git-send-pack.txt +++ b/Documentation/git-send-pack.txt @@ -43,7 +43,7 @@ OPTIONS <directory>:: The repository to update. -<ref>...: +<ref>...:: The remote refs to update. diff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt index 7486ebe78..95fa9010c 100644 --- a/Documentation/git-shortlog.txt +++ b/Documentation/git-shortlog.txt @@ -7,16 +7,30 @@ git-shortlog - Summarize 'git log' output SYNOPSIS -------- -git-log --pretty=short | 'git-shortlog' +git-log --pretty=short | 'git-shortlog' [-h] [-n] [-s] +git-shortlog [-n|--number] [-s|--summary] [<committish>...] DESCRIPTION ----------- Summarizes 'git log' output in a format suitable for inclusion -in release announcements. Each commit will be grouped by author +in release announcements. Each commit will be grouped by author and the first line of the commit message will be shown. Additionally, "[PATCH]" will be stripped from the commit description. +OPTIONS +------- + +-h:: + Print a short usage message and exit. + +-n:: + Sort output according to the number of commits per author instead + of author alphabetic order. + +-s:: + Supress commit description and provide a commit count summary only. + FILES ----- '.mailmap':: diff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt index a2445a48f..912e15bcb 100644 --- a/Documentation/git-show-branch.txt +++ b/Documentation/git-show-branch.txt @@ -8,9 +8,10 @@ git-show-branch - Show branches and their commits SYNOPSIS -------- [verse] -'git-show-branch' [--all] [--heads] [--tags] [--topo-order] [--current] +'git-show-branch' [--all] [--remotes] [--topo-order] [--current] [--more=<n> | --list | --independent | --merge-base] - [--no-name | --sha1-name] [<rev> | <glob>]... + [--no-name | --sha1-name] [--topics] [<rev> | <glob>]... +'git-show-branch' --reflog[=<n>] <ref> DESCRIPTION ----------- @@ -37,9 +38,11 @@ OPTIONS branches under $GIT_DIR/refs/heads/topic, giving `topic/*` would show all of them. ---all --heads --tags:: - Show all refs under $GIT_DIR/refs, $GIT_DIR/refs/heads, - and $GIT_DIR/refs/tags, respectively. +-r|--remotes:: + Show the remote-tracking branches. + +-a|--all:: + Show both remote-tracking branches and local branches. --current:: With this option, the command includes the current @@ -86,6 +89,18 @@ OPTIONS of "master"), name them with the unique prefix of their object names. +--topics:: + Shows only commits that are NOT on the first branch given. + This helps track topic branches by hiding any commit that + is already in the main line of development. When given + "git show-branch --topics master topic1 topic2", this + will show the revisions given by "git rev-list {caret}master + topic1 topic2" + +--reflog[=<n>] <ref>:: + Shows <n> most recent ref-log entries for the given ref. + + Note that --more, --list, --independent and --merge-base options are mutually exclusive. diff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt new file mode 100644 index 000000000..5973a8251 --- /dev/null +++ b/Documentation/git-show-ref.txt @@ -0,0 +1,156 @@ +git-show-ref(1) +=============== + +NAME +---- +git-show-ref - List references in a local repository + +SYNOPSIS +-------- +[verse] +'git-show-ref' [-q|--quiet] [--verify] [-h|--head] [-d|--dereference] + [-s|--hash] [--abbrev] [--tags] [--heads] [--] <pattern>... + +DESCRIPTION +----------- + +Displays references available in a local repository along with the associated +commit IDs. Results can be filtered using a pattern and tags can be +dereferenced into object IDs. Additionally, it can be used to test whether a +particular ref exists. + +Use of this utility is encouraged in favor of directly accessing files under +in the `.git` directory. + +OPTIONS +------- + +-h, --head:: + + Show the HEAD reference. + +--tags, --heads:: + + Limit to only "refs/heads" and "refs/tags", respectively. These + options are not mutually exclusive; when given both, references stored + in "refs/heads" and "refs/tags" are displayed. + +-d, --dereference:: + + Dereference tags into object IDs as well. They will be shown with "^{}" + appended. + +-s, --hash:: + + Only show the SHA1 hash, not the reference name. When also using + --dereference the dereferenced tag will still be shown after the SHA1. + +--verify:: + + Enable stricter reference checking by requiring an exact ref path. + Aside from returning an error code of 1, it will also print an error + message if '--quiet' was not specified. + +--abbrev, --abbrev=len:: + + Abbreviate the object name. When using `--hash`, you do + not have to say `--hash --abbrev`; `--hash=len` would do. + +-q, --quiet:: + + Do not print any results to stdout. When combined with '--verify' this + can be used to silently check if a reference exists. + +<pattern>:: + + Show references matching one or more patterns. + +OUTPUT +------ + +The output is in the format: '<SHA-1 ID>' '<space>' '<reference name>'. + +----------------------------------------------------------------------------- +$ git show-ref --head --dereference +832e76a9899f560a90ffd62ae2ce83bbeff58f54 HEAD +832e76a9899f560a90ffd62ae2ce83bbeff58f54 refs/heads/master +832e76a9899f560a90ffd62ae2ce83bbeff58f54 refs/heads/origin +3521017556c5de4159da4615a39fa4d5d2c279b5 refs/tags/v0.99.9c +6ddc0964034342519a87fe013781abf31c6db6ad refs/tags/v0.99.9c^{} +055e4ae3ae6eb344cbabf2a5256a49ea66040131 refs/tags/v1.0rc4 +423325a2d24638ddcc82ce47be5e40be550f4507 refs/tags/v1.0rc4^{} +... +----------------------------------------------------------------------------- + +When using --hash (and not --dereference) the output format is: '<SHA-1 ID>' + +----------------------------------------------------------------------------- +$ git show-ref --heads --hash +2e3ba0114a1f52b47df29743d6915d056be13278 +185008ae97960c8d551adcd9e23565194651b5d1 +03adf42c988195b50e1a1935ba5fcbc39b2b029b +... +----------------------------------------------------------------------------- + +EXAMPLE +------- + +To show all references called "master", whether tags or heads or anything +else, and regardless of how deep in the reference naming hierarchy they are, +use: + +----------------------------------------------------------------------------- + git show-ref master +----------------------------------------------------------------------------- + +This will show "refs/heads/master" but also "refs/remote/other-repo/master", +if such references exists. + +When using the '--verify' flag, the command requires an exact path: + +----------------------------------------------------------------------------- + git show-ref --verify refs/heads/master +----------------------------------------------------------------------------- + +will only match the exact branch called "master". + +If nothing matches, gitlink:git-show-ref[1] will return an error code of 1, +and in the case of verification, it will show an error message. + +For scripting, you can ask it to be quiet with the "--quiet" flag, which +allows you to do things like + +----------------------------------------------------------------------------- + git-show-ref --quiet --verify -- "refs/heads/$headname" || + echo "$headname is not a valid branch" +----------------------------------------------------------------------------- + +to check whether a particular branch exists or not (notice how we don't +actually want to show any results, and we want to use the full refname for it +in order to not trigger the problem with ambiguous partial matches). + +To show only tags, or only proper branch heads, use "--tags" and/or "--heads" +respectively (using both means that it shows tags and heads, but not other +random references under the refs/ subdirectory). + +To do automatic tag object dereferencing, use the "-d" or "--dereference" +flag, so you can do + +----------------------------------------------------------------------------- + git show-ref --tags --dereference +----------------------------------------------------------------------------- + +to get a listing of all tags together with what they dereference. + +SEE ALSO +-------- +gitlink:git-ls-remote[1], gitlink:git-peek-remote[1] + +AUTHORS +------- +Written by Linus Torvalds <torvalds@osdl.org>. +Man page by Jonas Fonseca <fonseca@diku.dk>. + +GIT +--- +Part of the gitlink:git[7] suite diff --git a/Documentation/git-show.txt b/Documentation/git-show.txt index 2b4df3f96..c210b9af6 100644 --- a/Documentation/git-show.txt +++ b/Documentation/git-show.txt @@ -3,38 +3,68 @@ git-show(1) NAME ---- -git-show - Show one commit with difference it introduces +git-show - Show various types of objects SYNOPSIS -------- -'git-show' <option>... +'git-show' [options] <object>... DESCRIPTION ----------- -Shows commit log and textual diff for a single commit. The -command internally invokes 'git-rev-list' piped to -'git-diff-tree', and takes command line options for both of -these commands. It also presents the merge commit in a special -format as produced by 'git-diff-tree --cc'. +Shows one or more objects (blobs, trees, tags and commits). + +For commits it shows the log message and textual diff. It also +presents the merge commit in a special format as produced by +'git-diff-tree --cc'. + +For tags, it shows the tag message and the referenced objects. + +For trees, it shows the names (equivalent to gitlink:git-ls-tree[1] +with \--name-only). + +For plain blobs, it shows the plain contents. This manual page describes only the most frequently used options. OPTIONS ------- -<commitid>:: - ID of the commit to show. +<object>:: + The name of the object to show. + +include::pretty-formats.txt[] + + +EXAMPLES +-------- + +git show v1.0.0:: + Shows the tag `v1.0.0`, along with the object the tags + points at. + +git show v1.0.0^{tree}:: + Shows the tree pointed to by the tag `v1.0.0`. + +git show next~10:Documentation/README + Shows the contents of the file `Documentation/README` as + they were current in the 10th last commit of the branch + `next`. + +git show master:Makefile master:t/Makefile + Concatenates the contents of said Makefiles in the head + of the branch `master`. + +Discussion +---------- ---pretty=<format>:: - Controls the output format for the commit logs. - <format> can be one of 'raw', 'medium', 'short', 'full', - and 'oneline'. +include::i18n.txt[] Author ------ Written by Linus Torvalds <torvalds@osdl.org> and -Junio C Hamano <junkio@cox.net> +Junio C Hamano <junkio@cox.net>. Significantly enhanced by +Johannes Schindelin <Johannes.Schindelin@gmx.de>. Documentation diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt index 7d8680984..9ed721118 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -3,7 +3,7 @@ git-svn(1) NAME ---- -git-svn - bidirectional operation between a single Subversion branch and git +git-svn - bidirectional operation between Subversion and git SYNOPSIS -------- @@ -11,49 +11,84 @@ SYNOPSIS DESCRIPTION ----------- -git-svn is a simple conduit for changesets between a single Subversion -branch and git. +git-svn is a simple conduit for changesets between Subversion and git. +It is not to be confused with gitlink:git-svnimport[1], which is +read-only and geared towards tracking multiple branches. -git-svn is not to be confused with git-svnimport. The were designed -with very different goals in mind. - -git-svn is designed for an individual developer who wants a +git-svn was originally designed for an individual developer who wants a bidirectional flow of changesets between a single branch in Subversion -and an arbitrary number of branches in git. git-svnimport is designed -for read-only operation on repositories that match a particular layout -(albeit the recommended one by SVN developers). - -For importing svn, git-svnimport is potentially more powerful when -operating on repositories organized under the recommended -trunk/branch/tags structure, and should be faster, too. +and an arbitrary number of branches in git. Since its inception, +git-svn has gained the ability to track multiple branches in a manner +similar to git-svnimport; but it cannot (yet) automatically detect new +branches and tags like git-svnimport does. -git-svn mostly ignores the very limited view of branching that -Subversion has. This allows git-svn to be much easier to use, -especially on repositories that are not organized in a manner that -git-svnimport is designed for. +git-svn is especially useful when it comes to tracking repositories +not organized in the way Subversion developers recommend (trunk, +branches, tags directories). COMMANDS -------- -init:: +-- + +'init':: Creates an empty git repository with additional metadata directories for git-svn. The Subversion URL must be specified - as a command-line argument. - -fetch:: - Fetch unfetched revisions from the Subversion URL we are - tracking. refs/remotes/git-svn will be updated to the - latest revision. - - Note: You should never attempt to modify the remotes/git-svn - branch outside of git-svn. Instead, create a branch from - remotes/git-svn and work on that branch. Use the 'commit' - command (see below) to write git commits back to - remotes/git-svn. - - See 'Additional Fetch Arguments' if you are interested in - manually joining branches on commit. - -commit:: + as a command-line argument. Optionally, the target directory + to operate on can be specified as a second argument. Normally + this command initializes the current directory. + +'fetch':: + +Fetch unfetched revisions from the Subversion URL we are +tracking. refs/remotes/git-svn will be updated to the +latest revision. + +Note: You should never attempt to modify the remotes/git-svn +branch outside of git-svn. Instead, create a branch from +remotes/git-svn and work on that branch. Use the 'dcommit' +command (see below) to write git commits back to +remotes/git-svn. + +See '<<fetch-args,Additional Fetch Arguments>>' if you are interested in +manually joining branches on commit. + +'dcommit':: + Commit each diff from a specified head directly to the SVN + repository, and then rebase or reset (depending on whether or + not there is a diff between SVN and head). This will create + a revision in SVN for each commit in git. + It is recommended that you run git-svn fetch and rebase (not + pull or merge) your commits against the latest changes in the + SVN repository. + An optional command-line argument may be specified as an + alternative to HEAD. + This is advantageous over 'set-tree' (below) because it produces + cleaner, more linear history. + +'log':: + This should make it easy to look up svn log messages when svn + users refer to -r/--revision numbers. + + The following features from `svn log' are supported: + + --revision=<n>[:<n>] - is supported, non-numeric args are not: + HEAD, NEXT, BASE, PREV, etc ... + -v/--verbose - it's not completely compatible with + the --verbose output in svn log, but + reasonably close. + --limit=<n> - is NOT the same as --max-count, + doesn't count merged/excluded commits + --incremental - supported + + New features: + + --show-commit - shows the git commit sha1, as well + --oneline - our version of --pretty=oneline + + Any other arguments are passed directly to `git log' + +'set-tree':: + You should consider using 'dcommit' instead of this command. Commit specified commit or tree objects to SVN. This relies on your imported fetch data being up-to-date. This makes absolutely no attempts to do patching when committing to SVN, it @@ -61,9 +96,9 @@ commit:: commit. All merging is assumed to have taken place independently of git-svn functions. -rebuild:: +'rebuild':: Not a part of daily usage, but this is a useful command if - you've just cloned a repository (using git-clone) that was + you've just cloned a repository (using gitlink:git-clone[1]) that was tracked with git-svn. Unfortunately, git-clone does not clone git-svn metadata and the svn working tree that git-svn uses for its operations. This rebuilds the metadata so git-svn can @@ -71,176 +106,344 @@ rebuild:: specified at the command-line if the directory/repository you're tracking has moved or changed protocols. -show-ignore:: +'show-ignore':: Recursively finds and lists the svn:ignore property on directories. The output is suitable for appending to the $GIT_DIR/info/exclude file. +'commit-diff':: + Commits the diff of two tree-ish arguments from the + command-line. This command is intended for interopability with + git-svnimport and does not rely on being inside an git-svn + init-ed repository. This command takes three arguments, (a) the + original tree to diff against, (b) the new tree result, (c) the + URL of the target Subversion repository. The final argument + (URL) may be omitted if you are working from a git-svn-aware + repository (that has been init-ed with git-svn). + The -r<revision> option is required for this. + +'graft-branches':: + This command attempts to detect merges/branches from already + imported history. Techniques used currently include regexes, + file copies, and tree-matches). This command generates (or + modifies) the $GIT_DIR/info/grafts file. This command is + considered experimental, and inherently flawed because + merge-tracking in SVN is inherently flawed and inconsistent + across different repositories. + +'multi-init':: + This command supports git-svnimport-like command-line syntax for + importing repositories that are layed out as recommended by the + SVN folks. This is a bit more tolerant than the git-svnimport + command-line syntax and doesn't require the user to figure out + where the repository URL ends and where the repository path + begins. + +-T<trunk_subdir>:: +--trunk=<trunk_subdir>:: +-t<tags_subdir>:: +--tags=<tags_subdir>:: +-b<branches_subdir>:: +--branches=<branches_subdir>:: + These are the command-line options for multi-init. Each of + these flags can point to a relative repository path + (--tags=project/tags') or a full url + (--tags=https://foo.org/project/tags) + +--prefix=<prefix> + This allows one to specify a prefix which is prepended to the + names of remotes. The prefix does not automatically include a + trailing slash, so be sure you include one in the argument if + that is what you want. This is useful if you wish to track + multiple projects that share a common repository. + +'multi-fetch':: + This runs fetch on all known SVN branches we're tracking. This + will NOT discover new branches (unlike git-svnimport), so + multi-init will need to be re-run (it's idempotent). + +-- + OPTIONS ------- +-- + +--shared:: +--template=<template_directory>:: + Only used with the 'init' command. + These are passed directly to gitlink:git-init[1]. + -r <ARG>:: --revision <ARG>:: - Only used with the 'fetch' command. - Takes any valid -r<argument> svn would accept and passes it - directly to svn. -r<ARG1>:<ARG2> ranges and "{" DATE "}" syntax - is also supported. This is passed directly to svn, see svn - documentation for more details. +Only used with the 'fetch' command. + +Takes any valid -r<argument> svn would accept and passes it +directly to svn. -r<ARG1>:<ARG2> ranges and "{" DATE "}" syntax +is also supported. This is passed directly to svn, see svn +documentation for more details. - This can allow you to make partial mirrors when running fetch. +This can allow you to make partial mirrors when running fetch. -:: --stdin:: - Only used with the 'commit' command. - Read a list of commits from stdin and commit them in reverse - order. Only the leading sha1 is read from each line, so - git-rev-list --pretty=oneline output can be used. +Only used with the 'set-tree' command. + +Read a list of commits from stdin and commit them in reverse +order. Only the leading sha1 is read from each line, so +git-rev-list --pretty=oneline output can be used. --rmdir:: - Only used with the 'commit' command. - Remove directories from the SVN tree if there are no files left - behind. SVN can version empty directories, and they are not - removed by default if there are no files left in them. git - cannot version empty directories. Enabling this flag will make - the commit to SVN act like git. +Only used with the 'dcommit', 'set-tree' and 'commit-diff' commands. + +Remove directories from the SVN tree if there are no files left +behind. SVN can version empty directories, and they are not +removed by default if there are no files left in them. git +cannot version empty directories. Enabling this flag will make +the commit to SVN act like git. - repo-config key: svn.rmdir +repo-config key: svn.rmdir -e:: --edit:: - Only used with the 'commit' command. - Edit the commit message before committing to SVN. This is off by - default for objects that are commits, and forced on when committing - tree objects. +Only used with the 'dcommit', 'set-tree' and 'commit-diff' commands. + +Edit the commit message before committing to SVN. This is off by +default for objects that are commits, and forced on when committing +tree objects. - repo-config key: svn.edit +repo-config key: svn.edit -l<num>:: --find-copies-harder:: - Both of these are only used with the 'commit' command. - They are both passed directly to git-diff-tree see - git-diff-tree(1) for more information. +Only used with the 'dcommit', 'set-tree' and 'commit-diff' commands. - repo-config key: svn.l - repo-config key: svn.findcopiesharder +They are both passed directly to git-diff-tree see +gitlink:git-diff-tree[1] for more information. + +[verse] +repo-config key: svn.l +repo-config key: svn.findcopiesharder -A<filename>:: --authors-file=<filename>:: - Syntax is compatible with the files used by git-svnimport and - git-cvsimport: +Syntax is compatible with the files used by git-svnimport and +git-cvsimport: ------------------------------------------------------------------------ -loginname = Joe User <user@example.com> + loginname = Joe User <user@example.com> ------------------------------------------------------------------------ - If this option is specified and git-svn encounters an SVN - committer name that does not exist in the authors-file, git-svn - will abort operation. The user will then have to add the - appropriate entry. Re-running the previous git-svn command - after the authors-file is modified should continue operation. +If this option is specified and git-svn encounters an SVN +committer name that does not exist in the authors-file, git-svn +will abort operation. The user will then have to add the +appropriate entry. Re-running the previous git-svn command +after the authors-file is modified should continue operation. + +repo-config key: svn.authorsfile + +-q:: +--quiet:: + Make git-svn less verbose. + +--repack[=<n>]:: +--repack-flags=<flags> + These should help keep disk usage sane for large fetches + with many revisions. + + --repack takes an optional argument for the number of revisions + to fetch before repacking. This defaults to repacking every + 1000 commits fetched if no argument is specified. + + --repack-flags are passed directly to gitlink:git-repack[1]. + +repo-config key: svn.repack +repo-config key: svn.repackflags - repo-config key: svn.authors-file +-m:: +--merge:: +-s<strategy>:: +--strategy=<strategy>:: + +These are only used with the 'dcommit' command. + +Passed directly to git-rebase when using 'dcommit' if a +'git-reset' cannot be used (see dcommit). + +-n:: +--dry-run:: + +This is only used with the 'dcommit' command. + +Print out the series of git arguments that would show +which diffs would be committed to SVN. + +-- ADVANCED OPTIONS ---------------- +-- + -b<refname>:: --branch <refname>:: - Used with 'fetch' or 'commit'. +Used with 'fetch', 'dcommit' or 'set-tree'. - This can be used to join arbitrary git branches to remotes/git-svn - on new commits where the tree object is equivalent. +This can be used to join arbitrary git branches to remotes/git-svn +on new commits where the tree object is equivalent. - When used with different GIT_SVN_ID values, tags and branches in - SVN can be tracked this way, as can some merges where the heads - end up having completely equivalent content. This can even be - used to track branches across multiple SVN _repositories_. +When used with different GIT_SVN_ID values, tags and branches in +SVN can be tracked this way, as can some merges where the heads +end up having completely equivalent content. This can even be +used to track branches across multiple SVN _repositories_. - This option may be specified multiple times, once for each - branch. +This option may be specified multiple times, once for each +branch. - repo-config key: svn.branch +repo-config key: svn.branch -i<GIT_SVN_ID>:: --id <GIT_SVN_ID>:: - This sets GIT_SVN_ID (instead of using the environment). See - the section on "Tracking Multiple Repositories or Branches" for - more information on using GIT_SVN_ID. + +This sets GIT_SVN_ID (instead of using the environment). See the +section on +'<<tracking-multiple-repos,Tracking Multiple Repositories or Branches>>' +for more information on using GIT_SVN_ID. + +--follow-parent:: + This is especially helpful when we're tracking a directory + that has been moved around within the repository, or if we + started tracking a branch and never tracked the trunk it was + descended from. + +repo-config key: svn.followparent + +--no-metadata:: + This gets rid of the git-svn-id: lines at the end of every commit. + + With this, you lose the ability to use the rebuild command. If + you ever lose your .git/svn/git-svn/.rev_db file, you won't be + able to fetch again, either. This is fine for one-shot imports. + + The 'git-svn log' command will not work on repositories using this, + either. + +repo-config key: svn.nometadata + +-- COMPATIBILITY OPTIONS --------------------- ---upgrade:: - Only used with the 'rebuild' command. +-- - Run this if you used an old version of git-svn that used - "git-svn-HEAD" instead of "remotes/git-svn" as the branch - for tracking the remote. +--upgrade:: +Only used with the 'rebuild' command. ---no-ignore-externals:: - Only used with the 'fetch' and 'rebuild' command. +Run this if you used an old version of git-svn that used +"git-svn-HEAD" instead of "remotes/git-svn" as the branch +for tracking the remote. - By default, git-svn passes --ignore-externals to svn to avoid - fetching svn:external trees into git. Pass this flag to enable - externals tracking directly via git. +--ignore-nodate:: +Only used with the 'fetch' command. - Versions of svn that do not support --ignore-externals are - automatically detected and this flag will be automatically - enabled for them. +By default git-svn will crash if it tries to import a revision +from SVN which has '(no date)' listed as the date of the revision. +This is repository corruption on SVN's part, plain and simple. +But sometimes you really need those revisions anyway. - Otherwise, do not enable this flag unless you know what you're - doing. +If supplied git-svn will convert '(no date)' entries to the UNIX +epoch (midnight on Jan. 1, 1970). Yes, that's probably very wrong. +SVN was very wrong. - repo-config key: svn.noignoreexternals +-- Basic Examples ~~~~~~~~~~~~~~ -Tracking and contributing to an Subversion managed-project: +Tracking and contributing to a the trunk of a Subversion-managed project: ------------------------------------------------------------------------ -# Initialize a tree (like git init-db): +# Initialize a repo (like git init): git-svn init http://svn.foo.org/project/trunk # Fetch remote revisions: git-svn fetch # Create your own branch to hack on: git checkout -b my-branch remotes/git-svn -# Commit only the git commits you want to SVN: - git-svn commit <tree-ish> [<tree-ish_2> ...] -# Commit all the git commits from my-branch that don't exist in SVN: - git-svn commit remotes/git-svn..my-branch -# Something is committed to SVN, pull the latest into your branch: - git-svn fetch && git pull . remotes/git-svn +# Do some work, and then commit your new changes to SVN, as well as +# automatically updating your working HEAD: + git-svn dcommit +# Something is committed to SVN, rebase the latest into your branch: + git-svn fetch && git rebase remotes/git-svn # Append svn:ignore settings to the default git exclude file: git-svn show-ignore >> .git/info/exclude ------------------------------------------------------------------------ +Tracking and contributing to an entire Subversion-managed project +(complete with a trunk, tags and branches): +See also: +'<<tracking-multiple-repos,Tracking Multiple Repositories or Branches>>' + +------------------------------------------------------------------------ +# Initialize a repo (like git init): + git-svn multi-init http://svn.foo.org/project \ + -T trunk -b branches -t tags +# Fetch remote revisions: + git-svn multi-fetch +# Create your own branch of trunk to hack on: + git checkout -b my-trunk remotes/trunk +# Do some work, and then commit your new changes to SVN, as well as +# automatically updating your working HEAD: + git-svn dcommit -i trunk +# Something has been committed to trunk, rebase the latest into your branch: + git-svn multi-fetch && git rebase remotes/trunk +# Append svn:ignore settings of trunk to the default git exclude file: + git-svn show-ignore -i trunk >> .git/info/exclude +# Check for new branches and tags (no arguments are needed): + git-svn multi-init +------------------------------------------------------------------------ + +REBASE VS. PULL/MERGE +--------------------- + +Originally, git-svn recommended that the remotes/git-svn branch be +pulled or merged from. This is because the author favored +'git-svn set-tree B' to commit a single head rather than the +'git-svn set-tree A..B' notation to commit multiple commits. + +If you use 'git-svn set-tree A..B' to commit several diffs and you do +not have the latest remotes/git-svn merged into my-branch, you should +use 'git rebase' to update your work branch instead of 'git pull' or +'git merge'. 'pull/merge' can cause non-linear history to be flattened +when committing into SVN, which can lead to merge commits reversing +previous commits in SVN. + DESIGN PHILOSOPHY ----------------- Merge tracking in Subversion is lacking and doing branched development -with Subversion is cumbersome as a result. git-svn completely forgoes -any automated merge/branch tracking on the Subversion side and leaves it -entirely up to the user on the git side. It's simply not worth it to do -a useful translation when the original signal is weak. +with Subversion is cumbersome as a result. git-svn does not do +automated merge/branch tracking by default and leaves it entirely up to +the user on the git side. +[[tracking-multiple-repos]] TRACKING MULTIPLE REPOSITORIES OR BRANCHES ------------------------------------------ -This is for advanced users, most users should ignore this section. - Because git-svn does not care about relationships between different branches or directories in a Subversion repository, git-svn has a simple hack to allow it to track an arbitrary number of related _or_ unrelated -SVN repositories via one git repository. Simply set the GIT_SVN_ID -environment variable to a name other other than "git-svn" (the default) -and git-svn will ignore the contents of the $GIT_DIR/git-svn directory -and instead do all of its work in $GIT_DIR/$GIT_SVN_ID for that -invocation. The interface branch will be remotes/$GIT_SVN_ID, instead of -remotes/git-svn. Any remotes/$GIT_SVN_ID branch should never be modified -by the user outside of git-svn commands. - +SVN repositories via one git repository. Simply use the --id/-i flag or +set the GIT_SVN_ID environment variable to a name other other than +"git-svn" (the default) and git-svn will ignore the contents of the +$GIT_DIR/svn/git-svn directory and instead do all of its work in +$GIT_DIR/svn/$GIT_SVN_ID for that invocation. The interface branch will +be remotes/$GIT_SVN_ID, instead of remotes/git-svn. Any +remotes/$GIT_SVN_ID branch should never be modified by the user outside +of git-svn commands. + +[[fetch-args]] ADDITIONAL FETCH ARGUMENTS -------------------------- This is for advanced users, most users should ignore this section. @@ -251,58 +454,33 @@ optionally be specified in the form of sha1 hex sums at the command-line. Unfetched SVN revisions may also be tied to particular git commits with the following syntax: +------------------------------------------------ svn_revision_number=git_commit_sha1 +------------------------------------------------ -This allows you to tie unfetched SVN revision 375 to your current HEAD:: +This allows you to tie unfetched SVN revision 375 to your current HEAD: - `git-svn fetch 375=$(git-rev-parse HEAD)` +------------------------------------------------ + git-svn fetch 375=$(git-rev-parse HEAD) +------------------------------------------------ -Advanced Example: Tracking a Reorganized Repository -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If you're tracking a directory that has moved, or otherwise been branched or tagged off of another directory in the repository and you -care about the full history of the project, then you can read this -section. - -This is how Yann Dirson tracked the trunk of the ufoai directory when -the /trunk directory of his repository was moved to /ufoai/trunk and -he needed to continue tracking /ufoai/trunk where /trunk left off. +care about the full history of the project, then you can use +the --follow-parent option. ------------------------------------------------------------------------- - # This log message shows when the repository was reorganized: - r166 | ydirson | 2006-03-02 01:36:55 +0100 (Thu, 02 Mar 2006) | 1 line - Changed paths: - D /trunk - A /ufoai/trunk (from /trunk:165) - - # First we start tracking the old revisions: - GIT_SVN_ID=git-oldsvn git-svn init \ - https://svn.sourceforge.net/svnroot/ufoai/trunk - GIT_SVN_ID=git-oldsvn git-svn fetch -r1:165 - - # And now, we continue tracking the new revisions: - GIT_SVN_ID=git-newsvn git-svn init \ - https://svn.sourceforge.net/svnroot/ufoai/ufoai/trunk - GIT_SVN_ID=git-newsvn git-svn fetch \ - 166=`git-rev-parse refs/remotes/git-oldsvn` ------------------------------------------------------------------------- +------------------------------------------------ + git-svn fetch --follow-parent +------------------------------------------------ BUGS ---- -If somebody commits a conflicting changeset to SVN at a bad moment -(right before you commit) causing a conflict and your commit to fail, -your svn working tree ($GIT_DIR/git-svn/tree) may be dirtied. The -easiest thing to do is probably just to rm -rf $GIT_DIR/git-svn/tree and -run 'rebuild'. We ignore all SVN properties except svn:executable. Too difficult to map them since we rely heavily on git write-tree being _exactly_ the same on both the SVN and git working trees and I prefer not to clutter working trees with metadata files. -svn:keywords can't be ignored in Subversion (at least I don't know of -a way to ignore them). - Renamed and copied directories are not detected by git and hence not tracked when committing to SVN. I do not plan on adding support for this as it's quite difficult and time-consuming to get working for all @@ -310,6 +488,10 @@ the possible corner cases (git doesn't do it, either). Renamed and copied files are fully supported if they're similar enough for git to detect them. +SEE ALSO +-------- +gitlink:git-rebase[1] + Author ------ Written by Eric Wong <normalperson@yhbt.net>. diff --git a/Documentation/git-svnimport.txt b/Documentation/git-svnimport.txt index b1b87c2fc..b166cf332 100644 --- a/Documentation/git-svnimport.txt +++ b/Documentation/git-svnimport.txt @@ -15,6 +15,7 @@ SYNOPSIS [ -b branch_subdir ] [ -T trunk_subdir ] [ -t tag_subdir ] [ -s start_chg ] [ -m ] [ -r ] [ -M regex ] [ -I <ignorefile_name> ] [ -A <author_file> ] + [ -R <repack_each_revs>] [ -P <path_from_trunk> ] <SVN_repository_URL> [ <path> ] @@ -103,9 +104,25 @@ repository without -A. -l <max_rev>:: Specify a maximum revision number to pull. ++ +Formerly, this option controlled how many revisions to pull, +due to SVN memory leaks. (These have been worked around.) + +-R <repack_each_revs>:: + Specify how often git repository should be repacked. ++ +The default value is 1000. git-svnimport will do import in chunks of 1000 +revisions, after each chunk git repository will be repacked. To disable +this behavior specify some big value here which is mote than number of +revisions to import. - Formerly, this option controlled how many revisions to pull, - due to SVN memory leaks. (These have been worked around.) +-P <path_from_trunk>:: + Partial import of the SVN tree. ++ +By default, the whole tree on the SVN trunk (/trunk) is imported. +'-P my/proj' will import starting only from '/trunk/my/proj'. +This option is useful when you want to import one project from a +svn repo which hosts multiple projects under the same trunk. -v:: Verbosity: let 'svnimport' report what it is doing. diff --git a/Documentation/git-symbolic-ref.txt b/Documentation/git-symbolic-ref.txt index 68ac6a65d..4bc35a1d4 100644 --- a/Documentation/git-symbolic-ref.txt +++ b/Documentation/git-symbolic-ref.txt @@ -19,29 +19,22 @@ argument to see on which branch your working tree is on. Give two arguments, create or update a symbolic ref <name> to point at the given branch <ref>. -Traditionally, `.git/HEAD` is a symlink pointing at -`refs/heads/master`. When we want to switch to another branch, -we did `ln -sf refs/heads/newbranch .git/HEAD`, and when we want +A symbolic ref is a regular file that stores a string that +begins with `ref: refs/`. For example, your `.git/HEAD` is +a regular file whose contents is `ref: refs/heads/master`. + +NOTES +----- +In the past, `.git/HEAD` was a symbolic link pointing at +`refs/heads/master`. When we wanted to switch to another branch, +we did `ln -sf refs/heads/newbranch .git/HEAD`, and when we wanted to find out which branch we are on, we did `readlink .git/HEAD`. This was fine, and internally that is what still happens by default, but on platforms that do not have working symlinks, or that do not have the `readlink(1)` command, this was a bit cumbersome. On some platforms, `ln -sf` does not even work as -advertised (horrors). - -A symbolic ref can be a regular file that stores a string that -begins with `ref: refs/`. For example, your `.git/HEAD` *can* -be a regular file whose contents is `ref: refs/heads/master`. -This can be used on a filesystem that does not support symbolic -links. Instead of doing `readlink .git/HEAD`, `git-symbolic-ref -HEAD` can be used to find out which branch we are on. To point -the HEAD to `newbranch`, instead of `ln -sf refs/heads/newbranch -.git/HEAD`, `git-symbolic-ref HEAD refs/heads/newbranch` can be -used. - -Currently, .git/HEAD uses a regular file symbolic ref on Cygwin, -and everywhere else it is implemented as a symlink. This can be -changed at compilation time. +advertised (horrors). Therefore symbolic links are now deprecated +and symbolic refs are used by default. Author ------ diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt index 45476c2e4..80bece077 100644 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@ -9,7 +9,8 @@ git-tag - Create a tag object signed with GPG SYNOPSIS -------- [verse] -'git-tag' [-a | -s | -u <key-id>] [-f | -d] [-m <msg>] <name> [<head>] +'git-tag' [-a | -s | -u <key-id>] [-f | -d | -v] [-m <msg> | -F <file>] + <name> [<head>] 'git-tag' -l [<pattern>] DESCRIPTION @@ -34,6 +35,8 @@ GnuPG key for signing. `-d <tag>` deletes the tag. +`-v <tag>` verifies the gpg signature of the tag. + `-l <pattern>` lists tags that match the given pattern (or all if no pattern is given). @@ -54,12 +57,18 @@ OPTIONS -d:: Delete an existing tag with the given name +-v:: + Verify the gpg signature of given the tag + -l <pattern>:: List tags that match the given pattern (or all if no pattern is given). -m <msg>:: Use the given tag message (instead of prompting) +-F <file>:: + Take the tag message from the given file. Use '-' to + read the message from the standard input. Author ------ diff --git a/Documentation/git-tar-tree.txt b/Documentation/git-tar-tree.txt index 1e1c7fa85..74a6fddd9 100644 --- a/Documentation/git-tar-tree.txt +++ b/Documentation/git-tar-tree.txt @@ -12,6 +12,9 @@ SYNOPSIS DESCRIPTION ----------- +THIS COMMAND IS DEPRECATED. Use `git-archive` with `--format=tar` +option instead. + Creates a tar archive containing the tree structure for the named tree. When <base> is specified it is added as a leading path to the files in the generated tar archive. diff --git a/Documentation/git-unpack-objects.txt b/Documentation/git-unpack-objects.txt index c20b38b08..ff6184b0f 100644 --- a/Documentation/git-unpack-objects.txt +++ b/Documentation/git-unpack-objects.txt @@ -8,7 +8,7 @@ git-unpack-objects - Unpack objects from a packed archive SYNOPSIS -------- -'git-unpack-objects' [-n] [-q] <pack-file +'git-unpack-objects' [-n] [-q] [-r] <pack-file DESCRIPTION @@ -34,6 +34,12 @@ OPTIONS The command usually shows percentage progress. This flag suppresses it. +-r:: + When unpacking a corrupt packfile, the command dies at + the first corruption. This flag tells it to keep going + and make the best effort to recover as many objects as + possible. + Author ------ diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt index 3ae6e7457..0e0a3af1b 100644 --- a/Documentation/git-update-index.txt +++ b/Documentation/git-update-index.txt @@ -15,7 +15,7 @@ SYNOPSIS [--cacheinfo <mode> <object> <file>]\* [--chmod=(+|-)x] [--assume-unchanged | --no-assume-unchanged] - [--really-refresh] [--unresolve] [--again] + [--really-refresh] [--unresolve] [--again | -g] [--info-only] [--index-info] [-z] [--stdin] [--verbose] @@ -80,7 +80,7 @@ OPTIONS filesystem that has very slow lstat(2) system call (e.g. cifs). ---again:: +--again, -g:: Runs `git-update-index` itself on the paths whose index entries are different from those from the `HEAD` commit. @@ -216,8 +216,8 @@ $ git ls-files -s ------------ -Using "assume unchanged" bit ----------------------------- +Using ``assume unchanged'' bit +------------------------------ Many operations in git depend on your filesystem to have an efficient `lstat(2)` implementation, so that `st_mtime` diff --git a/Documentation/git-update-ref.txt b/Documentation/git-update-ref.txt index e062030e9..71bcb7954 100644 --- a/Documentation/git-update-ref.txt +++ b/Documentation/git-update-ref.txt @@ -7,7 +7,7 @@ git-update-ref - update the object name stored in a ref safely SYNOPSIS -------- -'git-update-ref' [-m <reason>] <ref> <newvalue> [<oldvalue>] +'git-update-ref' [-m <reason>] (-d <ref> <oldvalue> | <ref> <newvalue> [<oldvalue>]) DESCRIPTION ----------- @@ -20,7 +20,9 @@ possibly dereferencing the symbolic refs, after verifying that the current value of the <ref> matches <oldvalue>. E.g. `git-update-ref refs/heads/master <newvalue> <oldvalue>` updates the master branch head to <newvalue> only if its current -value is <oldvalue>. +value is <oldvalue>. You can specify 40 "0" or an empty string +as <oldvalue> to make sure that the ref you are creating does +not exist. It also allows a "ref" file to be a symbolic pointer to another ref file by starting with the four-byte header sequence of @@ -49,6 +51,10 @@ for reading but not for writing (so we'll never write through a ref symlink to some other tree, if you have copied a whole archive by creating a symlink tree). +With `-d` flag, it deletes the named <ref> after verifying it +still contains <oldvalue>. + + Logging Updates --------------- If config parameter "core.logAllRefUpdates" is true or the file diff --git a/Documentation/git-upload-archive.txt b/Documentation/git-upload-archive.txt new file mode 100644 index 000000000..388bb53d2 --- /dev/null +++ b/Documentation/git-upload-archive.txt @@ -0,0 +1,37 @@ +git-upload-archive(1) +==================== + +NAME +---- +git-upload-archive - Send archive + + +SYNOPSIS +-------- +'git-upload-archive' <directory> + +DESCRIPTION +----------- +Invoked by 'git-archive --remote' and sends a generated archive to the +other end over the git protocol. + +This command is usually not invoked directly by the end user. The UI +for the protocol is on the 'git-archive' side, and the program pair +is meant to be used to get an archive from a remote repository. + +OPTIONS +------- +<directory>:: + The repository to get a tar archive from. + +Author +------ +Written by Franck Bui-Huu. + +Documentation +-------------- +Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the gitlink:git[7] suite diff --git a/Documentation/git-upload-tar.txt b/Documentation/git-upload-tar.txt deleted file mode 100644 index 394af6201..000000000 --- a/Documentation/git-upload-tar.txt +++ /dev/null @@ -1,39 +0,0 @@ -git-upload-tar(1) -================= - -NAME ----- -git-upload-tar - Send tar archive - - -SYNOPSIS --------- -'git-upload-tar' <directory> - -DESCRIPTION ------------ -Invoked by 'git-tar-tree --remote' and sends a generated tar archive -to the other end over the git protocol. - -This command is usually not invoked directly by the end user. -The UI for the protocol is on the 'git-tar-tree' side, and the -program pair is meant to be used to get a tar archive from a -remote repository. - - -OPTIONS -------- -<directory>:: - The repository to get a tar archive from. - -Author ------- -Written by Junio C Hamano <junio@kernel.org> - -Documentation --------------- -Documentation by Junio C Hamano. - -GIT ---- -Part of the gitlink:git[7] suite diff --git a/Documentation/git.txt b/Documentation/git.txt index 3de5fa9c8..f89d745ef 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -8,8 +8,9 @@ git - the stupid content tracker SYNOPSIS -------- +[verse] 'git' [--version] [--exec-path[=GIT_EXEC_PATH]] [-p|--paginate] - [--bare] [--git-dir=GIT_DIR] [--help] COMMAND [ARGS] + [--bare] [--git-dir=GIT_DIR] [--help] COMMAND [ARGS] DESCRIPTION ----------- @@ -71,186 +72,6 @@ GIT COMMANDS We divide git into high level ("porcelain") commands and low level ("plumbing") commands. -Low-level commands (plumbing) ------------------------------ - -Although git includes its -own porcelain layer, its low-level commands are sufficient to support -development of alternative porcelains. Developers of such porcelains -might start by reading about gitlink:git-update-index[1] and -gitlink:git-read-tree[1]. - -We divide the low-level commands into commands that manipulate objects (in -the repository, index, and working tree), commands that interrogate and -compare objects, and commands that move objects and references between -repositories. - -Manipulation commands -~~~~~~~~~~~~~~~~~~~~~ -gitlink:git-apply[1]:: - Reads a "diff -up1" or git generated patch file and - applies it to the working tree. - -gitlink:git-checkout-index[1]:: - Copy files from the index to the working tree. - -gitlink:git-commit-tree[1]:: - Creates a new commit object. - -gitlink:git-hash-object[1]:: - Computes the object ID from a file. - -gitlink:git-index-pack[1]:: - Build pack idx file for an existing packed archive. - -gitlink:git-init-db[1]:: - Creates an empty git object database, or reinitialize an - existing one. - -gitlink:git-merge-index[1]:: - Runs a merge for files needing merging. - -gitlink:git-mktag[1]:: - Creates a tag object. - -gitlink:git-mktree[1]:: - Build a tree-object from ls-tree formatted text. - -gitlink:git-pack-objects[1]:: - Creates a packed archive of objects. - -gitlink:git-prune-packed[1]:: - Remove extra objects that are already in pack files. - -gitlink:git-read-tree[1]:: - Reads tree information into the index. - -gitlink:git-repo-config[1]:: - Get and set options in .git/config. - -gitlink:git-unpack-objects[1]:: - Unpacks objects out of a packed archive. - -gitlink:git-update-index[1]:: - Registers files in the working tree to the index. - -gitlink:git-write-tree[1]:: - Creates a tree from the index. - - -Interrogation commands -~~~~~~~~~~~~~~~~~~~~~~ - -gitlink:git-cat-file[1]:: - Provide content or type/size information for repository objects. - -gitlink:git-describe[1]:: - Show the most recent tag that is reachable from a commit. - -gitlink:git-diff-index[1]:: - Compares content and mode of blobs between the index and repository. - -gitlink:git-diff-files[1]:: - Compares files in the working tree and the index. - -gitlink:git-diff-stages[1]:: - Compares two "merge stages" in the index. - -gitlink:git-diff-tree[1]:: - Compares the content and mode of blobs found via two tree objects. - -gitlink:git-fsck-objects[1]:: - Verifies the connectivity and validity of the objects in the database. - -gitlink:git-ls-files[1]:: - Information about files in the index and the working tree. - -gitlink:git-ls-tree[1]:: - Displays a tree object in human readable form. - -gitlink:git-merge-base[1]:: - Finds as good common ancestors as possible for a merge. - -gitlink:git-name-rev[1]:: - Find symbolic names for given revs. - -gitlink:git-pack-redundant[1]:: - Find redundant pack files. - -gitlink:git-rev-list[1]:: - Lists commit objects in reverse chronological order. - -gitlink:git-show-index[1]:: - Displays contents of a pack idx file. - -gitlink:git-tar-tree[1]:: - Creates a tar archive of the files in the named tree object. - -gitlink:git-unpack-file[1]:: - Creates a temporary file with a blob's contents. - -gitlink:git-var[1]:: - Displays a git logical variable. - -gitlink:git-verify-pack[1]:: - Validates packed git archive files. - -In general, the interrogate commands do not touch the files in -the working tree. - - -Synching repositories -~~~~~~~~~~~~~~~~~~~~~ - -gitlink:git-fetch-pack[1]:: - Updates from a remote repository (engine for ssh and - local transport). - -gitlink:git-http-fetch[1]:: - Downloads a remote git repository via HTTP by walking - commit chain. - -gitlink:git-local-fetch[1]:: - Duplicates another git repository on a local system by - walking commit chain. - -gitlink:git-peek-remote[1]:: - Lists references on a remote repository using - upload-pack protocol (engine for ssh and local - transport). - -gitlink:git-receive-pack[1]:: - Invoked by 'git-send-pack' to receive what is pushed to it. - -gitlink:git-send-pack[1]:: - Pushes to a remote repository, intelligently. - -gitlink:git-http-push[1]:: - Push missing objects using HTTP/DAV. - -gitlink:git-shell[1]:: - Restricted shell for GIT-only SSH access. - -gitlink:git-ssh-fetch[1]:: - Pulls from a remote repository over ssh connection by - walking commit chain. - -gitlink:git-ssh-upload[1]:: - Helper "server-side" program used by git-ssh-fetch. - -gitlink:git-update-server-info[1]:: - Updates auxiliary information on a dumb server to help - clients discover references and packs on it. - -gitlink:git-upload-pack[1]:: - Invoked by 'git-fetch-pack' to push - what are asked for. - -gitlink:git-upload-tar[1]:: - Invoked by 'git-tar-tree --remote' to return the tar - archive the other end asked for. - - High-level commands (porcelain) ------------------------------- @@ -269,6 +90,9 @@ gitlink:git-am[1]:: gitlink:git-applymbox[1]:: Apply patches from a mailbox, original version by Linus. +gitlink:git-archive[1]:: + Creates an archive of files from a named tree. + gitlink:git-bisect[1]:: Find the change that introduced a bug by binary search. @@ -302,6 +126,9 @@ gitlink:git-format-patch[1]:: gitlink:git-grep[1]:: Print lines matching a pattern. +gitlink:gitk[1]:: + The git repository browser. + gitlink:git-log[1]:: Shows commit logs. @@ -314,8 +141,11 @@ gitlink:git-merge[1]:: gitlink:git-mv[1]:: Move or rename a file, a directory, or a symlink. +gitlink:git-pack-refs[1]:: + Pack heads and tags for efficient repository access. + gitlink:git-pull[1]:: - Fetch from and merge with a remote repository. + Fetch from and merge with a remote repository or a local branch. gitlink:git-push[1]:: Update remote refs along with associated objects. @@ -382,6 +212,9 @@ gitlink:git-cvsexportcommit[1]:: gitlink:git-cvsserver[1]:: A CVS server emulator for git. +gitlink:git-gc[1]:: + Cleanup unnecessary files and optimize the local repository. + gitlink:git-lost-found[1]:: Recover lost refs that luckily have not yet been pruned. @@ -394,6 +227,9 @@ gitlink:git-prune[1]:: gitlink:git-quiltimport[1]:: Applies a quilt patchset onto the current branch. +gitlink:git-reflog[1]:: + Manage reflog information. + gitlink:git-relink[1]:: Hardlink common objects in local repositories. @@ -422,7 +258,7 @@ gitlink:git-annotate[1]:: Annotate file lines with commit info. gitlink:git-blame[1]:: - Blame file lines on commits. + Find out where each line in a file came from. gitlink:git-check-ref-format[1]:: Make sure ref name is well formed. @@ -472,6 +308,9 @@ gitlink:git-request-pull[1]:: gitlink:git-rev-parse[1]:: Pick out and massage parameters. +gitlink:git-runstatus[1]:: + A helper for git-status and git-commit. + gitlink:git-send-email[1]:: Send patch e-mails out of "format-patch --mbox" output. @@ -482,11 +321,192 @@ gitlink:git-stripspace[1]:: Filter out empty lines. -Commands not yet documented ---------------------------- +Low-level commands (plumbing) +----------------------------- -gitlink:gitk[1]:: - The gitk repository browser. +Although git includes its +own porcelain layer, its low-level commands are sufficient to support +development of alternative porcelains. Developers of such porcelains +might start by reading about gitlink:git-update-index[1] and +gitlink:git-read-tree[1]. + +We divide the low-level commands into commands that manipulate objects (in +the repository, index, and working tree), commands that interrogate and +compare objects, and commands that move objects and references between +repositories. + +Manipulation commands +~~~~~~~~~~~~~~~~~~~~~ +gitlink:git-apply[1]:: + Reads a "diff -up1" or git generated patch file and + applies it to the working tree. + +gitlink:git-checkout-index[1]:: + Copy files from the index to the working tree. + +gitlink:git-commit-tree[1]:: + Creates a new commit object. + +gitlink:git-hash-object[1]:: + Computes the object ID from a file. + +gitlink:git-index-pack[1]:: + Build pack idx file for an existing packed archive. + +gitlink:git-init[1]:: + Creates an empty git repository, or reinitialize an + existing one. + +gitlink:git-merge-file[1]:: + Runs a threeway merge. + +gitlink:git-merge-index[1]:: + Runs a merge for files needing merging. + +gitlink:git-mktag[1]:: + Creates a tag object. + +gitlink:git-mktree[1]:: + Build a tree-object from ls-tree formatted text. + +gitlink:git-pack-objects[1]:: + Creates a packed archive of objects. + +gitlink:git-prune-packed[1]:: + Remove extra objects that are already in pack files. + +gitlink:git-read-tree[1]:: + Reads tree information into the index. + +gitlink:git-repo-config[1]:: + Get and set options in .git/config. + +gitlink:git-unpack-objects[1]:: + Unpacks objects out of a packed archive. + +gitlink:git-update-index[1]:: + Registers files in the working tree to the index. + +gitlink:git-write-tree[1]:: + Creates a tree from the index. + + +Interrogation commands +~~~~~~~~~~~~~~~~~~~~~~ + +gitlink:git-cat-file[1]:: + Provide content or type/size information for repository objects. + +gitlink:git-describe[1]:: + Show the most recent tag that is reachable from a commit. + +gitlink:git-diff-index[1]:: + Compares content and mode of blobs between the index and repository. + +gitlink:git-diff-files[1]:: + Compares files in the working tree and the index. + +gitlink:git-diff-stages[1]:: + Compares two "merge stages" in the index. + +gitlink:git-diff-tree[1]:: + Compares the content and mode of blobs found via two tree objects. + +gitlink:git-for-each-ref[1]:: + Output information on each ref. + +gitlink:git-fsck-objects[1]:: + Verifies the connectivity and validity of the objects in the database. + +gitlink:git-ls-files[1]:: + Information about files in the index and the working tree. + +gitlink:git-ls-tree[1]:: + Displays a tree object in human readable form. + +gitlink:git-merge-base[1]:: + Finds as good common ancestors as possible for a merge. + +gitlink:git-name-rev[1]:: + Find symbolic names for given revs. + +gitlink:git-pack-redundant[1]:: + Find redundant pack files. + +gitlink:git-rev-list[1]:: + Lists commit objects in reverse chronological order. + +gitlink:git-show-index[1]:: + Displays contents of a pack idx file. + +gitlink:git-show-ref[1]:: + List references in a local repository. + +gitlink:git-tar-tree[1]:: + Creates a tar archive of the files in the named tree object. + +gitlink:git-unpack-file[1]:: + Creates a temporary file with a blob's contents. + +gitlink:git-var[1]:: + Displays a git logical variable. + +gitlink:git-verify-pack[1]:: + Validates packed git archive files. + +In general, the interrogate commands do not touch the files in +the working tree. + + +Synching repositories +~~~~~~~~~~~~~~~~~~~~~ + +gitlink:git-fetch-pack[1]:: + Updates from a remote repository (engine for ssh and + local transport). + +gitlink:git-http-fetch[1]:: + Downloads a remote git repository via HTTP by walking + commit chain. + +gitlink:git-local-fetch[1]:: + Duplicates another git repository on a local system by + walking commit chain. + +gitlink:git-peek-remote[1]:: + Lists references on a remote repository using + upload-pack protocol (engine for ssh and local + transport). + +gitlink:git-receive-pack[1]:: + Invoked by 'git-send-pack' to receive what is pushed to it. + +gitlink:git-send-pack[1]:: + Pushes to a remote repository, intelligently. + +gitlink:git-http-push[1]:: + Push missing objects using HTTP/DAV. + +gitlink:git-shell[1]:: + Restricted shell for GIT-only SSH access. + +gitlink:git-ssh-fetch[1]:: + Pulls from a remote repository over ssh connection by + walking commit chain. + +gitlink:git-ssh-upload[1]:: + Helper "server-side" program used by git-ssh-fetch. + +gitlink:git-update-server-info[1]:: + Updates auxiliary information on a dumb server to help + clients discover references and packs on it. + +gitlink:git-upload-archive[1]:: + Invoked by 'git-archive' to send a generated archive. + +gitlink:git-upload-pack[1]:: + Invoked by 'git-fetch-pack' to push + what are asked for. Configuration Mechanism @@ -563,6 +583,9 @@ HEAD:: a valid head 'name' (i.e. the contents of `$GIT_DIR/refs/heads/<head>`). +For a more complete list of ways to spell object names, see +"SPECIFYING REVISIONS" section in gitlink:git-rev-parse[1]. + File/Directory Structure ------------------------ @@ -625,11 +648,35 @@ git Commits git Diffs ~~~~~~~~~ 'GIT_DIFF_OPTS':: + Only valid setting is "--unified=??" or "-u??" to set the + number of context lines shown when a unified diff is created. + This takes precedence over any "-U" or "--unified" option + value passed on the git diff command line. + 'GIT_EXTERNAL_DIFF':: - see the "generating patches" section in : - gitlink:git-diff-index[1]; - gitlink:git-diff-files[1]; - gitlink:git-diff-tree[1] + 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: + + <old|new>-file:: are files GIT_EXTERNAL_DIFF can use to read the + contents of <old|new>, + <old|new>-hex:: are the 40-hexdigit SHA1 hashes, + <old|new>-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, <path>. other ~~~~~ @@ -637,9 +684,18 @@ other This environment variable overrides `$PAGER`. 'GIT_TRACE':: - If this variable is set git will print `trace:` messages on + If this variable is set to "1", "2" or "true" (comparison + is case insensitive), git will print `trace:` messages on stderr telling about alias expansion, built-in command execution and external command execution. + If this variable is set to an integer value greater than 1 + and lower than 10 (strictly) then git will interpret this + value as an open file descriptor and will try to write the + trace messages into this file descriptor. + Alternatively, if this variable is set to an absolute path + (starting with a '/' character), git will interpret this + as a file path and will try to write the trace messages + into it. Discussion[[Discussion]] ------------------------ diff --git a/Documentation/gitk.txt b/Documentation/gitk.txt index cb482bf98..f1aeb07f6 100644 --- a/Documentation/gitk.txt +++ b/Documentation/gitk.txt @@ -3,26 +3,56 @@ gitk(1) NAME ---- -gitk - Some git command not yet documented. - +gitk - git repository browser SYNOPSIS -------- -'gitk' [ --option ] <args>... +'gitk' [<option>...] [<revs>] [--] [<path>...] DESCRIPTION ----------- -Does something not yet documented. +Displays changes in a repository or a selected set of commits. This includes +visualizing the commit graph, showing information related to each commit, and +the files in the trees of each revision. +Historically, gitk was the first repository browser. It's written in tcl/tk +and started off in a separate repository but was later merged into the main +git repository. OPTIONS ------- ---option:: - Some option not yet documented. +To control which revisions to shown, the command takes options applicable to +the gitlink:git-rev-list[1] command. This manual page describes only the most +frequently used options. + +-n <number>, --max-count=<number>:: + + Limits the number of commits to show. + +--since=<date>:: + + Show commits more recent than a specific date. + +--until=<date>:: + + Show commits older than a specific date. + +--all:: + + Show all branches. -<args>...:: - Some argument not yet documented. +<revs>:: + Limit the revisions to show. This can be either a single revision + meaning show from the given revision and back, or it can be a range in + the form "'<from>'..'<to>'" to show all revisions between '<from>' and + back to '<to>'. Note, more advanced revision selection can be applied. + +<path>:: + + Limit commits to the ones touching files in the given paths. Note, to + avoid ambiguity wrt. revision names use "--" to separate the paths + from any preceeding options. Examples -------- @@ -37,13 +67,32 @@ gitk --since="2 weeks ago" \-- gitk:: The "--" is necessary to avoid confusion with the *branch* named 'gitk' +gitk --max-count=100 --all -- Makefile:: + + Show at most 100 changes made to the file 'Makefile'. Instead of only + looking for changes in the current branch look in all branches. + +See Also +-------- +'qgit(1)':: + A repository browser written in C++ using Qt. + +'gitview(1)':: + A repository browser written in Python using Gtk. It's based on + 'bzrk(1)' and distributed in the contrib area of the git repository. + +'tig(1)':: + A minimal repository browser and git tool output highlighter written + in C using Ncurses. + Author ------ -Written by Paul Mackerras <paulus@samba.org> +Written by Paul Mackerras <paulus@samba.org>. Documentation -------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. +Documentation by Junio C Hamano, Jonas Fonseca, and the git-list +<git@vger.kernel.org>. GIT --- diff --git a/Documentation/glossary.txt b/Documentation/glossary.txt index 14449ca8b..bc917bbac 100644 --- a/Documentation/glossary.txt +++ b/Documentation/glossary.txt @@ -179,7 +179,7 @@ object name:: character hexadecimal encoding of the hash of the object (possibly followed by a white space). -object type: +object type:: One of the identifiers "commit","tree","tag" and "blob" describing the type of an object. @@ -188,11 +188,12 @@ octopus:: predator. origin:: - The default upstream tracking branch. Most projects have at + The default upstream repository. Most projects have at least one upstream project which they track. By default 'origin' is used for that purpose. New upstream updates - will be fetched into this branch; you should never commit - to it yourself. + will be fetched into remote tracking branches named + origin/name-of-upstream-branch, which you can see using + "git branch -r". pack:: A set of objects which have been compressed into one file (to save @@ -234,8 +235,11 @@ push:: local head, the push fails. reachable:: - An object is reachable from a ref/commit/tree/tag, if there is a - chain leading from the latter to the former. + All of the ancestors of a given commit are said to be reachable from + that commit. More generally, one object is reachable from another if + we can reach the one from the other by a chain that follows tags to + whatever they tag, commits to their parents or trees, and trees to the + trees or blobs that they contain. rebase:: To clean a branch by starting from the head of the main line of @@ -255,7 +259,7 @@ refspec:: means "grab the master branch head from the $URL and store it as my origin branch head". And `git push $URL refs/heads/master:refs/heads/to-upstream` - means "publish my master branch head as to-upstream master head + means "publish my master branch head as to-upstream branch at $URL". See also gitlink:git-push[1] repository:: @@ -282,6 +286,13 @@ SCM:: SHA1:: Synonym for object name. +symref:: + Symbolic reference: instead of containing the SHA1 id itself, it + is of the format 'ref: refs/some/thing' and when referenced, it + recursively dereferences to this reference. 'HEAD' is a prime + example of a symref. Symbolic references are manipulated with + the gitlink:git-symbolic-ref[1] command. + topic branch:: A regular git branch that is used by a developer to identify a conceptual line of development. Since branches @@ -324,7 +335,7 @@ tag:: A tag is most typically used to mark a particular point in the commit ancestry chain. -unmerged index: +unmerged index:: An index which contains unmerged index entries. working tree:: diff --git a/Documentation/hooks.txt b/Documentation/hooks.txt index 898b4aaf8..e3b76f96e 100644 --- a/Documentation/hooks.txt +++ b/Documentation/hooks.txt @@ -3,10 +3,9 @@ Hooks used by git Hooks are little scripts you can place in `$GIT_DIR/hooks` directory to trigger action at certain points. When -`git-init-db` is run, a handful example hooks are copied in the +`git-init` is run, a handful example hooks are copied in the `hooks` directory of the new repository, but by default they are -all disabled. To enable a hook, make it executable with `chmod -+x`. +all disabled. To enable a hook, make it executable with `chmod +x`. This document describes the currently defined hooks. @@ -16,16 +15,16 @@ applypatch-msg This hook is invoked by `git-applypatch` script, which is typically invoked by `git-applymbox`. It takes a single parameter, the name of the file that holds the proposed commit -log message. Exiting with non-zero status causes the -'git-applypatch' to abort before applying the patch. +log message. Exiting with non-zero status causes +`git-applypatch` to abort before applying the patch. The hook is allowed to edit the message file in place, and can be used to normalize the message into some project standard format (if the project has one). It can also be used to refuse the commit after inspecting the message file. -The default applypatch-msg hook, when enabled, runs the -commit-msg hook, if the latter is enabled. +The default 'applypatch-msg' hook, when enabled, runs the +'commit-msg' hook, if the latter is enabled. pre-applypatch -------------- @@ -39,8 +38,8 @@ after application of the patch not committed. It can be used to inspect the current working tree and refuse to make a commit if it does not pass certain test. -The default pre-applypatch hook, when enabled, runs the -pre-commit hook, if the latter is enabled. +The default 'pre-applypatch' hook, when enabled, runs the +'pre-commit' hook, if the latter is enabled. post-applypatch --------------- @@ -61,9 +60,9 @@ invoked before obtaining the proposed commit log message and making a commit. Exiting with non-zero status from this script causes the `git-commit` to abort. -The default pre-commit hook, when enabled, catches introduction +The default 'pre-commit' hook, when enabled, catches introduction of lines with trailing whitespaces and aborts the commit when -a such line is found. +such a line is found. commit-msg ---------- @@ -79,8 +78,8 @@ be used to normalize the message into some project standard format (if the project has one). It can also be used to refuse the commit after inspecting the message file. -The default commit-msg hook, when enabled, detects duplicate -Signed-off-by: lines, and aborts the commit when one is found. +The default 'commit-msg' hook, when enabled, detects duplicate +"Signed-off-by" lines, and aborts the commit if one is found. post-commit ----------- @@ -91,23 +90,24 @@ parameter, and is invoked after a commit is made. This hook is meant primarily for notification, and cannot affect the outcome of `git-commit`. -The default post-commit hook, when enabled, demonstrates how to +The default 'post-commit' hook, when enabled, demonstrates how to send out a commit notification e-mail. update ------ This hook is invoked by `git-receive-pack` on the remote repository, -which is happens when a `git push` is done on a local repository. +which happens when a `git push` is done on a local repository. Just before updating the ref on the remote repository, the update hook is invoked. Its exit status determines the success or failure of the ref update. The hook executes once for each ref to be updated, and takes three parameters: - - the name of the ref being updated, - - the old object name stored in the ref, - - and the new objectname to be stored in the ref. + + - the name of the ref being updated, + - the old object name stored in the ref, + - and the new objectname to be stored in the ref. A zero exit from the update hook allows the ref to be updated. Exiting with a non-zero status prevents `git-receive-pack` @@ -126,16 +126,16 @@ Another use suggested on the mailing list is to use this hook to implement access control which is finer grained than the one based on filesystem group. -The standard output of this hook is sent to /dev/null; if you -want to report something to the git-send-pack on the other end, -you can redirect your output to your stderr. +The standard output of this hook is sent to `stderr`, so if you +want to report something to the `git-send-pack` on the other end, +you can simply `echo` your messages. post-update ----------- This hook is invoked by `git-receive-pack` on the remote repository, -which is happens when a `git push` is done on a local repository. +which happens when a `git push` is done on a local repository. It executes on the remote repository once after all the refs have been updated. @@ -145,16 +145,16 @@ name of ref that was actually updated. This hook is meant primarily for notification, and cannot affect the outcome of `git-receive-pack`. -The post-update hook can tell what are the heads that were pushed, +The 'post-update' hook can tell what are the heads that were pushed, but it does not know what their original and updated values are, so it is a poor place to do log old..new. -The default post-update hook, when enabled, runs +When enabled, the default 'post-update' hook runs `git-update-server-info` to keep the information used by dumb -transports (e.g., http) up-to-date. If you are publishing -a git repository that is accessible via http, you should +transports (e.g., HTTP) up-to-date. If you are publishing +a git repository that is accessible via HTTP, you should probably enable this hook. -The standard output of this hook is sent to /dev/null; if you -want to report something to the git-send-pack on the other end, -you can redirect your output to your stderr. +The standard output of this hook is sent to `/dev/null`; if you +want to report something to the `git-send-pack` on the other end, +you can redirect your output to your `stderr`. diff --git a/Documentation/howto/setup-git-server-over-http.txt b/Documentation/howto/setup-git-server-over-http.txt index ba191569a..a202f3a46 100644 --- a/Documentation/howto/setup-git-server-over-http.txt +++ b/Documentation/howto/setup-git-server-over-http.txt @@ -70,7 +70,7 @@ DocumentRoot /where/ever/httpd.conf" to find your root: Initialize a bare repository $ cd my-new-repo.git - $ git --bare init-db + $ git --bare init Change the ownership to your web-server's credentials. Use "grep ^User diff --git a/Documentation/i18n.txt b/Documentation/i18n.txt new file mode 100644 index 000000000..b4cbb3830 --- /dev/null +++ b/Documentation/i18n.txt @@ -0,0 +1,57 @@ +At the core level, git is character encoding agnostic. + + - The pathnames recorded in the index and in the tree objects + are treated as uninterpreted sequences of non-NUL bytes. + What readdir(2) returns are what are recorded and compared + with the data git keeps track of, which in turn are expected + to be what lstat(2) and creat(2) accepts. There is no such + thing as pathname encoding translation. + + - The contents of the blob objects are uninterpreted sequence + of bytes. There is no encoding translation at the core + level. + + - The commit log messages are uninterpreted sequence of non-NUL + bytes. + +Although we encourage that the commit log messages are encoded +in UTF-8, both the core and git Porcelain are designed not to +force UTF-8 on projects. If all participants of a particular +project find it more convenient to use legacy encodings, git +does not forbid it. However, there are a few things to keep in +mind. + +. `git-commit-tree` (hence, `git-commit` which uses it) issues + an warning if the commit log message given to it does not look + like a valid UTF-8 string, unless you explicitly say your + project uses a legacy encoding. The way to say this is to + have core.commitencoding in `.git/config` file, like this: ++ +------------ +[core] + commitencoding = ISO-8859-1 +------------ ++ +Commit objects created with the above setting record the value +of `core.commitencoding` in its `encoding` header. This is to +help other people who look at them later. Lack of this header +implies that the commit log message is encoded in UTF-8. + +. `git-log`, `git-show` and friends looks at the `encoding` + header of a commit object, and tries to re-code the log + message into UTF-8 unless otherwise specified. You can + specify the desired output encoding with + `core.logoutputencoding` in `.git/config` file, like this: ++ +------------ +[core] + logoutputencoding = ISO-8859-1 +------------ ++ +If you do not have this configuration variable, the value of +`core.commitencoding` is used instead. + +Note that we deliberately chose not to re-code the commit log +message when a commit is made to force UTF-8 at the commit +object level, because re-coding to UTF-8 is not necessarily a +reversible operation. diff --git a/Documentation/install-doc-quick.sh b/Documentation/install-doc-quick.sh new file mode 100755 index 000000000..a64054948 --- /dev/null +++ b/Documentation/install-doc-quick.sh @@ -0,0 +1,31 @@ +#!/bin/sh +# This requires a branch named in $head +# (usually 'man' or 'html', provided by the git.git repository) +set -e +head="$1" +mandir="$2" +SUBDIRECTORY_OK=t +USAGE='<refname> <target directory>' +. git-sh-setup +export GIT_DIR + +test -z "$mandir" && usage +if ! git-rev-parse --verify "$head^0" >/dev/null; then + echo >&2 "head: $head does not exist in the current repository" + usage +fi + +GIT_INDEX_FILE=`pwd`/.quick-doc.index +export GIT_INDEX_FILE +rm -f "$GIT_INDEX_FILE" +git-read-tree $head +git-checkout-index -a -f --prefix="$mandir"/ + +if test -n "$GZ"; then + cd "$mandir" + for i in `git-ls-tree -r --name-only $head` + do + gzip < $i > $i.gz && rm $i + done +fi +rm -f "$GIT_INDEX_FILE" diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt new file mode 100644 index 000000000..fb0b0b958 --- /dev/null +++ b/Documentation/pretty-formats.txt @@ -0,0 +1,85 @@ +--pretty[='<format>']:: + + Pretty-prints the details of a commit. `--pretty` + without an explicit `=<format>` defaults to 'medium'. + If the commit is a merge, and if the pretty-format + is not 'oneline', 'email' or 'raw', an additional line is + inserted before the 'Author:' line. This line begins with + "Merge: " and the sha1s of ancestral commits are printed, + separated by spaces. Note that the listed commits may not + necessarily be the list of the *direct* parent commits if you + have limited your view of history: for example, if you are + only interested in changes related to a certain directory or + file. Here are some additional details for each format: + + * 'oneline' + + <sha1> <title line> ++ +This is designed to be as compact as possible. + + * 'short' + + commit <sha1> + Author: <author> + + <title line> + + * 'medium' + + commit <sha1> + Author: <author> + Date: <date> + + <title line> + + <full commit message> + + * 'full' + + commit <sha1> + Author: <author> + Commit: <committer> + + <title line> + + <full commit message> + + * 'fuller' + + commit <sha1> + Author: <author> + AuthorDate: <date & time> + Commit: <committer> + CommitDate: <date & time> + + <title line> + + <full commit message> + + + * 'email' + + From <sha1> <date> + From: <author> + Date: <date & time> + Subject: [PATCH] <title line> + + full commit message> + + + * 'raw' ++ +The 'raw' format shows the entire commit exactly as +stored in the commit object. Notably, the SHA1s are +displayed in full, regardless of whether --abbrev or +--no-abbrev are used, and 'parents' information show the +true parent commits, without taking grafts nor history +simplification into account. + +--encoding[=<encoding>]:: + The commit objects record the encoding used for the log message + in their encoding header; this option can be used to tell the + command to re-code the commit log message in the encoding + preferred by the user. For non plumbing commands this + defaults to UTF-8. diff --git a/Documentation/pull-fetch-param.txt b/Documentation/pull-fetch-param.txt index e852f41a3..8d4e950ab 100644 --- a/Documentation/pull-fetch-param.txt +++ b/Documentation/pull-fetch-param.txt @@ -39,10 +39,6 @@ checkout -b my-B remote-B`). Run `git fetch` to keep track of the progress of the remote side, and when you see something new on the remote branch, merge it into your development branch with `git pull . remote-B`, while you are on `my-B` branch. -The common `Pull: master:origin` mapping of a remote `master` -branch to a local `origin` branch, which is then merged to a -local development branch, again typically named `master`, is made -when you run `git clone` for you to follow this pattern. + [NOTE] There is a difference between listing multiple <refspec> diff --git a/Documentation/repository-layout.txt b/Documentation/repository-layout.txt index 275d18bb5..0fdd36614 100644 --- a/Documentation/repository-layout.txt +++ b/Documentation/repository-layout.txt @@ -52,9 +52,20 @@ objects/info/packs:: by default. objects/info/alternates:: - This file records absolute filesystem paths of alternate - object stores that this object store borrows objects - from, one pathname per line. + This file records paths to alternate object stores that + this object store borrows objects from, one pathname per + line. Note that not only native Git tools use it locally, + but the HTTP fetcher also tries to use it remotely; this + will usually work if you have relative paths (relative + to the object database, not to the repository!) in your + alternates file, but it will not work if you use absolute + paths unless the absolute path in filesystem and web URL + is the same. See also 'objects/info/http-alternates'. + +objects/info/http-alternates:: + This file records URLs to alternate object stores that + this object store borrows objects from, to be used when + the repository is fetched over HTTP. refs:: References are stored in subdirectories of this @@ -70,12 +81,16 @@ refs/tags/`name`:: object, or a tag object that points at a commit object). HEAD:: - A symlink of the form `refs/heads/'name'` to point at - the current branch, if exists. It does not mean much if - the repository is not associated with any working tree + A symref (see glossary) to the `refs/heads/` namespace + describing the currently active branch. It does not mean + much if the repository is not associated with any working tree (i.e. a 'bare' repository), but a valid git repository - *must* have such a symlink here. It is legal if the - named branch 'name' does not (yet) exist. + *must* have the HEAD file; some porcelains may use it to + guess the designated "default" branch of the repository + (usually 'master'). It is legal if the named branch + 'name' does not (yet) exist. In some legacy setups, it is + a symbolic link instead of a symref that points at the current + branch. branches:: A slightly deprecated way to store shorthands to be used @@ -87,7 +102,7 @@ branches:: hooks:: Hooks are customization scripts used by various git commands. A handful of sample hooks are installed when - `git init-db` is run, but all of them are disabled by + `git init` is run, but all of them are disabled by default. To enable, they need to be made executable. Read link:hooks.html[hooks] for more details about each hook. diff --git a/Documentation/technical/racy-git.txt b/Documentation/technical/racy-git.txt index 7597d0414..5030d9f2f 100644 --- a/Documentation/technical/racy-git.txt +++ b/Documentation/technical/racy-git.txt @@ -4,7 +4,7 @@ Use of index and Racy git problem Background ---------- -The index is one of the most important data structure in git. +The index is one of the most important data structures in git. It represents a virtual working tree state by recording list of paths and their object names and serves as a staging area to write out the next tree object to be committed. The state is @@ -16,7 +16,7 @@ virtual working tree state in the index and the files in the working tree. The most obvious case is when the user asks `git diff` (or its low level implementation, `git diff-files`) or `git-ls-files --modified`. In addition, git internally checks -if the files in the working tree is different from what are +if the files in the working tree are different from what are recorded in the index to avoid stomping on local changes in them during patch application, switching branches, and merging. @@ -24,9 +24,9 @@ In order to speed up this comparison between the files in the working tree and the index entries, the index entries record the information obtained from the filesystem via `lstat(2)` system call when they were last updated. When checking if they differ, -git first runs `lstat(2)` on the files and compare the result +git first runs `lstat(2)` on the files and compares the result with this information (this is what was originally done by the -`ce_match_stat()` function, which the current code does in +`ce_match_stat()` function, but the current code does it in `ce_match_stat_basic()` function). If some of these "cached stat information" fields do not match, git can tell that the files are modified without even looking at their contents. @@ -53,8 +53,9 @@ Racy git There is one slight problem with the optimization based on the cached stat information. Consider this sequence: + : modify 'foo' $ git update-index 'foo' - : modify 'foo' in-place without changing its size + : modify 'foo' again, in-place, without changing its size The first `update-index` computes the object name of the contents of file `foo` and updates the index entry for `foo` @@ -62,7 +63,8 @@ along with the `struct stat` information. If the modification that follows it happens very fast so that the file's `st_mtime` timestamp does not change, after this sequence, the cached stat information the index entry records still exactly match what you -can obtain from the filesystem, but the file `foo` is modified. +would see in the filesystem, even though the file `foo` is now +different. This way, git can incorrectly think files in the working tree are unmodified even though they actually are. This is called the "racy git" problem (discovered by Pasky), and the entries @@ -87,7 +89,7 @@ the stat information from updated paths, `st_mtime` timestamp of it is usually the same as or newer than any of the paths the index contains. And no matter how quick the modification that follows `git update-index foo` finishes, the resulting -`st_mtime` timestamp on `foo` cannot get the timestamp earlier +`st_mtime` timestamp on `foo` cannot get a value earlier than the index file. Therefore, index entries that can be racily clean are limited to the ones that have the same timestamp as the index file itself. @@ -111,7 +113,7 @@ value, and falsely clean entry `foo` would not be caught by the timestamp comparison check done with the former logic anymore. The latter makes sure that the cached stat information for `foo` would never match with the file in the working tree, so later -checks by `ce_match_stat_basic()` would report the index entry +checks by `ce_match_stat_basic()` would report that the index entry does not match the file and git does not have to fall back on more expensive `ce_modified_check_fs()`. @@ -155,17 +157,16 @@ of the cached stat information. Avoiding runtime penalty ------------------------ -In order to avoid the above runtime penalty, the recent "master" -branch (post 1.4.2) has a code that makes sure the index file -gets timestamp newer than the youngest files in the index when +In order to avoid the above runtime penalty, post 1.4.2 git used +to have a code that made sure the index file +got timestamp newer than the youngest files in the index when there are many young files with the same timestamp as the resulting index file would otherwise would have by waiting before finishing writing the index file out. -I suspect that in practice the situation where many paths in the -index are all racily clean is quite rare. The only code paths -that can record recent timestamp for large number of paths I -know of are: +I suspected that in practice the situation where many paths in the +index are all racily clean was quite rare. The only code paths +that can record recent timestamp for large number of paths are: . Initial `git add .` of a large project. @@ -188,6 +189,7 @@ youngest file in the working tree. This means that in these cases there actually will not be any racily clean entry in the resulting index. -So in summary I think we should not worry about avoiding the -runtime penalty and get rid of the "wait before finishing -writing" code out. +Based on this discussion, the current code does not use the +"workaround" to avoid the runtime penalty that does not exist in +practice anymore. This was done with commit 0fc82cff on Aug 15, +2006. diff --git a/Documentation/technical/send-pack-pipeline.txt b/Documentation/technical/send-pack-pipeline.txt new file mode 100644 index 000000000..681efe421 --- /dev/null +++ b/Documentation/technical/send-pack-pipeline.txt @@ -0,0 +1,63 @@ +git-send-pack +============= + +Overall operation +----------------- + +. Connects to the remote side and invokes git-receive-pack. + +. Learns what refs the remote has and what commit they point at. + Matches them to the refspecs we are pushing. + +. Checks if there are non-fast-forwards. Unlike fetch-pack, + the repository send-pack runs in is supposed to be a superset + of the recipient in fast-forward cases, so there is no need + for want/have exchanges, and fast-forward check can be done + locally. Tell the result to the other end. + +. Calls pack_objects() which generates a packfile and sends it + over to the other end. + +. If the remote side is new enough (v1.1.0 or later), wait for + the unpack and hook status from the other end. + +. Exit with appropriate error codes. + + +Pack_objects pipeline +--------------------- + +This function gets one file descriptor (`fd`) which is either a +socket (over the network) or a pipe (local). What's written to +this fd goes to git-receive-pack to be unpacked. + + send-pack ---> fd ---> receive-pack + +The function pack_objects creates a pipe and then forks. The +forked child execs pack-objects with --revs to receive revision +parameters from its standard input. This process will write the +packfile to the other end. + + send-pack + | + pack_objects() ---> fd ---> receive-pack + | ^ (pipe) + v | + (child) + +The child dup2's to arrange its standard output to go back to +the other end, and read its standard input to come from the +pipe. After that it exec's pack-objects. On the other hand, +the parent process, before starting to feed the child pipeline, +closes the reading side of the pipe and fd to receive-pack. + + send-pack + | + pack_objects(parent) + | + v [0] + pack-objects [0] ---> receive-pack + + +[jc: the pipeline was much more complex and needed documentation before + I understood an earlier bug, but now it is trivial and straightforward.] diff --git a/Documentation/tutorial-2.txt b/Documentation/tutorial-2.txt index 2f4fe1217..f48894c9a 100644 --- a/Documentation/tutorial-2.txt +++ b/Documentation/tutorial-2.txt @@ -17,18 +17,19 @@ Let's start a new project and create a small amount of history: ------------------------------------------------ $ mkdir test-project $ cd test-project -$ git init-db -defaulting to local storage area +$ git init +Initialized empty Git repository in .git/ $ echo 'hello world' > file.txt $ git add . $ git commit -a -m "initial commit" -Committing initial tree 92b8b694ffb1675e5975148e1121810081dbdffe +Created initial commit 54196cc2703dc165cbd373a65a4dcf22d50ae7f7 + create mode 100644 file.txt $ echo 'hello world!' >file.txt $ git commit -a -m "add emphasis" +Created commit c4d59f390b9cfd4318117afde11d601c1085f241 ------------------------------------------------ -What are the 40 digits of hex that git responded to the first commit -with? +What are the 40 digits of hex that git responded to the commit with? We saw in part one of the tutorial that commits have names like this. It turns out that every object in the git history is stored under @@ -38,13 +39,25 @@ the same data twice (since identical data is given an identical SHA1 name), and that the contents of a git object will never change (since that would change the object's name as well). +It is expected that the content of the commit object you created while +following the example above generates a different SHA1 hash than +the one shown above because the commit object records the time when +it was created and the name of the person performing the commit. + We can ask git about this particular object with the cat-file -command--just cut-and-paste from the reply to the initial commit, to -save yourself typing all 40 hex digits: +command. Don't copy the 40 hex digits from this example but use those +from your own version. Note that you can shorten it to only a few +characters to save yourself typing all 40 hex digits: ------------------------------------------------ -$ git cat-file -t 92b8b694ffb1675e5975148e1121810081dbdffe -tree +$ git-cat-file -t 54196cc2 +commit +$ git-cat-file commit 54196cc2 +tree 92b8b694ffb1675e5975148e1121810081dbdffe +author J. Bruce Fields <bfields@puzzle.fieldses.org> 1143414668 -0500 +committer J. Bruce Fields <bfields@puzzle.fieldses.org> 1143414668 -0500 + +initial commit ------------------------------------------------ A tree can refer to one or more "blob" objects, each corresponding to @@ -101,8 +114,7 @@ $ find .git/objects/ and the contents of these files is just the compressed data plus a header identifying their length and their type. The type is either a -blob, a tree, a commit, or a tag. We've seen a blob and a tree now, -so next we should look at a commit. +blob, a tree, a commit, or a tag. The simplest commit to find is the HEAD commit, which we can find from .git/HEAD: @@ -341,23 +353,23 @@ situation: ------------------------------------------------ $ git status # -# Updated but not checked in: +# Added but not yet committed: # (will commit) # # new file: closing.txt # # -# Changed but not updated: -# (use git-update-index to mark for commit) +# Changed but not added: +# (use "git add file1 file2" to include for commit) # # modified: file.txt # ------------------------------------------------ Since the current state of closing.txt is cached in the index file, -it is listed as "updated but not checked in". Since file.txt has +it is listed as "added but not yet committed". Since file.txt has changes in the working directory that aren't reflected in the index, -it is marked "changed but not updated". At this point, running "git +it is marked "changed but not added". At this point, running "git commit" would create a commit that added closing.txt (with its new contents), but that didn't modify file.txt. @@ -368,7 +380,7 @@ in the index file is identical to the one in the working directory. In addition to being the staging area for new commits, the index file is also populated from the object database when checking out a branch, and is used to hold the trees involved in a merge operation. -See the link:core-tutorial.txt[core tutorial] and the relevant man +See the link:core-tutorial.html[core tutorial] and the relevant man pages for details. What next? diff --git a/Documentation/tutorial.txt b/Documentation/tutorial.txt index 554ee0af9..d2bf0b905 100644 --- a/Documentation/tutorial.txt +++ b/Documentation/tutorial.txt @@ -11,6 +11,18 @@ diff" with: $ man git-diff ------------------------------------------------ +It is a good idea to introduce yourself to git before doing any +operation. The easiest way to do so is: + +------------------------------------------------ +$ cat >~/.gitconfig <<\EOF +[user] + name = Your Name Comes Here + email = you@yourdomain.example.com +EOF +------------------------------------------------ + + Importing a new project ----------------------- @@ -20,18 +32,18 @@ can place it under git revision control as follows. ------------------------------------------------ $ tar xzf project.tar.gz $ cd project -$ git init-db +$ git init ------------------------------------------------ Git will reply ------------------------------------------------ -defaulting to local storage area +Initialized empty Git repository in .git/ ------------------------------------------------ You've now initialized the working directory--you may notice a new directory created, named ".git". Tell git that you want it to track -every file under the current directory with +every file under the current directory (note the '.') with: ------------------------------------------------ $ git add . @@ -40,42 +52,90 @@ $ git add . Finally, ------------------------------------------------ -$ git commit -a +$ git commit ------------------------------------------------ will prompt you for a commit message, then record the current state of all the files to the repository. +Making changes +-------------- + Try modifying some files, then run ------------------------------------------------ $ git diff ------------------------------------------------ -to review your changes. When you're done, +to review your changes. When you're done, tell git that you +want the updated contents of these files in the commit and then +make a commit, like this: + +------------------------------------------------ +$ git add file1 file2 file3 +$ git commit +------------------------------------------------ + +This will again prompt your for a message describing the change, and then +record the new versions of the files you listed. + +Alternatively, instead of running `git add` beforehand, you can use ------------------------------------------------ $ git commit -a ------------------------------------------------ -will again prompt your for a message describing the change, and then -record the new versions of the modified files. +which will automatically notice modified (but not new) files. A note on commit messages: Though not required, it's a good idea to begin the commit message with a single short (less than 50 character) line summarizing the change, followed by a blank line and then a more thorough description. Tools that turn commits into email, for -example, use the first line on the Subject line and the rest of the +example, use the first line on the Subject: line and the rest of the commit in the body. -To add a new file, first create the file, then ------------------------------------------------- -$ git add path/to/new/file ------------------------------------------------- +Git tracks content not files +---------------------------- + +With git you have to explicitly "add" all the changed _content_ you +want to commit together. This can be done in a few different ways: + +1) By using 'git add <file_spec>...' + + This can be performed multiple times before a commit. Note that this + is not only for adding new files. Even modified files must be + added to the set of changes about to be committed. The "git status" + command gives you a summary of what is included so far for the + next commit. When done you should use the 'git commit' command to + make it real. + + Note: don't forget to 'add' a file again if you modified it after the + first 'add' and before 'commit'. Otherwise only the previous added + state of that file will be committed. This is because git tracks + content, so what you're really 'add'ing to the commit is the *content* + of the file in the state it is in when you 'add' it. + +2) By using 'git commit -a' directly + + This is a quick way to automatically 'add' the content from all files + that were modified since the previous commit, and perform the actual + commit without having to separately 'add' them beforehand. This will + not add content from new files i.e. files that were never added before. + Those files still have to be added explicitly before performing a + commit. + +But here's a twist. If you do 'git commit <file1> <file2> ...' then only +the changes belonging to those explicitly specified files will be +committed, entirely bypassing the current "added" changes. Those "added" +changes will still remain available for a subsequent commit though. + +However, for normal usage you only have to remember 'git add' + 'git commit' +and/or 'git commit -a'. -then commit as usual. No special command is required when removing a -file; just remove it, then commit. + +Viewing the changelog +--------------------- At any point you can view the history of your changes using @@ -89,6 +149,13 @@ If you also want to see complete diffs at each step, use $ git log -p ------------------------------------------------ +Often the overview of the change is useful to get a feel of +each step + +------------------------------------------------ +$ git log --stat --summary +------------------------------------------------ + Managing branches ----------------- @@ -141,7 +208,7 @@ $ git commit -a ------------------------------------------------ at this point the two branches have diverged, with different changes -made in each. To merge the changes made in the two branches, run +made in each. To merge the changes made in experimental into master, run ------------------------------------------------ $ git pull . experimental @@ -169,6 +236,15 @@ $ gitk will show a nice graphical representation of the resulting history. +At this point you could delete the experimental branch with + +------------------------------------------------ +$ git branch -d experimental +------------------------------------------------ + +This command ensures that the changes in the experimental branch are +already in the current branch. + If you develop on a branch crazy-idea, then regret it, you can always delete the branch with @@ -209,29 +285,28 @@ at /home/bob/myrepo. She does this with: ------------------------------------------------ $ cd /home/alice/project -$ git pull /home/bob/myrepo +$ git pull /home/bob/myrepo master ------------------------------------------------ -This actually pulls changes from the branch in Bob's repository named -"master". Alice could request a different branch by adding the name -of the branch to the end of the git pull command line. +This merges the changes from Bob's "master" branch into Alice's +current branch. If Alice has made her own changes in the meantime, +then she may need to manually fix any conflicts. (Note that the +"master" argument in the above command is actually unnecessary, as it +is the default.) -This merges Bob's changes into her repository; "git log" will -now show the new commits. If Alice has made her own changes in the -meantime, then Bob's changes will be merged in, and she will need to -manually fix any conflicts. +The "pull" command thus performs two operations: it fetches changes +from a remote branch, then merges them into the current branch. -A more cautious Alice might wish to examine Bob's changes before -pulling them. She can do this by creating a temporary branch just -for the purpose of studying Bob's changes: +You can perform the first operation alone using the "git fetch" +command. For example, Alice could create a temporary branch just to +track Bob's changes, without merging them with her own, using: ------------------------------------- $ git fetch /home/bob/myrepo master:bob-incoming ------------------------------------- which fetches the changes from Bob's master branch into a new branch -named bob-incoming. (Unlike git pull, git fetch just fetches a copy -of Bob's line of development without doing any merging). Then +named bob-incoming. Then ------------------------------------- $ git log -p master..bob-incoming @@ -240,8 +315,8 @@ $ git log -p master..bob-incoming shows a list of all the changes that Bob made since he branched from Alice's master branch. -After examining those changes, and possibly fixing things, Alice can -pull the changes into her master branch: +After examining those changes, and possibly fixing things, Alice +could pull the changes into her master branch: ------------------------------------- $ git checkout master @@ -251,6 +326,18 @@ $ git pull . bob-incoming The last command is a pull from the "bob-incoming" branch in Alice's own repository. +Alice could also perform both steps at once with: + +------------------------------------- +$ git pull /home/bob/myrepo master:bob-incoming +------------------------------------- + +This is just like the "git pull /home/bob/myrepo master" that we saw +before, except that it also stores the unmerged changes from bob's +master branch in bob-incoming before merging them into Alice's +current branch. Note that git pull always merges into the current +branch, regardless of what else is given on the commandline. + Later, Bob can update his repo with Alice's latest changes using ------------------------------------- @@ -259,20 +346,25 @@ $ git pull Note that he doesn't need to give the path to Alice's repository; when Bob cloned Alice's repository, git stored the location of her -repository in the file .git/remotes/origin, and that location is used -as the default for pulls. - -Bob may also notice a branch in his repository that he didn't create: +repository in the repository configuration, and that location is +used for pulls: ------------------------------------- -$ git branch -* master - origin +$ git repo-config --get remote.origin.url +/home/bob/myrepo ------------------------------------- -The "origin" branch, which was created automatically by "git clone", -is a pristine copy of Alice's master branch; Bob should never commit -to it. +(The complete configuration created by git-clone is visible using +"git repo-config -l", and the gitlink:git-repo-config[1] man page +explains the meaning of each option.) + +Git also keeps a pristine copy of Alice's master branch under the +name "origin/master": + +------------------------------------- +$ git branch -r + origin/master +------------------------------------- If Bob later decides to work from a different host, he can still perform clones and pulls using the ssh protocol: @@ -312,7 +404,7 @@ commit. $ git show c82a22c39cbc32576f64f5c6b3f24b99ea8149c7 ------------------------------------- -But there other ways to refer to commits. You can use any initial +But there are other ways to refer to commits. You can use any initial part of the name that is long enough to uniquely identify the commit: ------------------------------------- @@ -322,8 +414,8 @@ $ git show HEAD # the tip of the current branch $ git show experimental # the tip of the "experimental" branch ------------------------------------- -Every commit has at least one "parent" commit, which points to the -previous state of the project: +Every commit usually has one "parent" commit +which points to the previous state of the project: ------------------------------------- $ git show HEAD^ # to see the parent of HEAD @@ -441,10 +533,10 @@ of the file: $ git diff v2.5:Makefile HEAD:Makefile.in ------------------------------------- -You can also use "git cat-file -p" to see any such file: +You can also use "git show" to see any such file: ------------------------------------- -$ git cat-file -p v2.5:Makefile +$ git show v2.5:Makefile ------------------------------------- Next Steps diff --git a/Documentation/urls.txt b/Documentation/urls.txt index 26ecba53f..745f9677d 100644 --- a/Documentation/urls.txt +++ b/Documentation/urls.txt @@ -40,10 +40,13 @@ In addition to the above, as a short-hand, the name of a file in `$GIT_DIR/remotes` directory can be given; the named file should be in the following format: +------------ URL: one of the above URL format Push: <refspec> Pull: <refspec> +------------ + Then such a short-hand is specified in place of <repository> without <refspec> parameters on the command line, <refspec> specified on `Push:` lines or `Pull:` @@ -51,6 +54,17 @@ lines are used for `git-push` and `git-fetch`/`git-pull`, respectively. Multiple `Push:` and `Pull:` lines may be specified for additional branch mappings. +Or, equivalently, in the `$GIT_DIR/config` (note the use +of `fetch` instead of `Pull:`): + +------------ + [remote "<remote>"] + url = <url> + push = <refspec> + fetch = <refspec> + +------------ + The name of a file in `$GIT_DIR/branches` directory can be specified as an older notation short-hand; the named file should contain a single line, a URL in one of the @@ -60,10 +74,15 @@ name of remote head (URL fragment notation). without the fragment is equivalent to have this in the corresponding file in the `$GIT_DIR/remotes/` directory. +------------ URL: <url> Pull: refs/heads/master:<remote> +------------ + while having `<url>#<head>` is equivalent to +------------ URL: <url> Pull: refs/heads/<head>:<remote> +------------ |