diff options
59 files changed, 1114 insertions, 544 deletions
diff --git a/Documentation/config.txt b/Documentation/config.txt index b24d9dff62..b4aae0d0ae 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -173,6 +173,21 @@ branch.<name>.merge:: 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 @@ -183,11 +198,8 @@ color.diff.<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 @@ -205,7 +217,7 @@ color.status.<slot>:: `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.diff.<slot>. + these variables may be specified as in color.branch.<slot>. diff.renameLimit:: The number of files to consider when performing the copy/rename diff --git a/Documentation/cvs-migration.txt b/Documentation/cvs-migration.txt index b657f4589f..8e09beaa79 100644 --- a/Documentation/cvs-migration.txt +++ b/Documentation/cvs-migration.txt @@ -34,13 +34,10 @@ them first before running git pull. [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/ -Pull: refs/heads/master:refs/remotes/origin/master ------------- +The `pull` command knows where to get updates from because of certain +configuration variables that were set by the first `git clone` +command; see `git repo-config -l` and the gitlink:git-repo-config[1] man +page for details. ================================ You can update the shared repository with your changes by first committing diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt index 13f34d3ca2..5b4d184a73 100644 --- a/Documentation/fetch-options.txt +++ b/Documentation/fetch-options.txt @@ -36,6 +36,13 @@ -u, \--update-head-ok:: By default `git-fetch` refuses to update the head which corresponds to the current branch. This flag disables the - check. Note that fetching into the current branch will not - update the index and working directory, so use it with care. + check. This is purely for the internal use for `git-pull` + to communicate with `git-fetch`, and unless you are + implementing your own Porcelain you are not supposed to + use it. + +\--depth=<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-branch.txt b/Documentation/git-branch.txt index c464bd2fda..e872fc89fc 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -8,7 +8,7 @@ git-branch - List, create, or delete branches. SYNOPSIS -------- [verse] -'git-branch' [-r | -a] [-v [--abbrev=<length>]] +'git-branch' [--color | --no-color] [-r | -a] [-v [--abbrev=<length>]] 'git-branch' [-l] [-f] <branchname> [<start-point>] 'git-branch' (-m | -M) [<oldbranch>] <newbranch> 'git-branch' (-d | -D) [-r] <branchname>... @@ -60,6 +60,13 @@ OPTIONS -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 or delete (if used with -d) the remote-tracking branches. diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index 874934a332..a78207461d 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -11,26 +11,27 @@ SYNOPSIS [verse] 'git-clone' [--template=<template_directory>] [-l [-s]] [-q] [-n] [--bare] [-o <name>] [-u <upload-pack>] [--reference <repository>] - <repository> [<directory>] + [--depth=<depth>] <repository> [<directory>] DESCRIPTION ----------- 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 a master -branch equal to the cloned repository's master branch. +(visible using `git branch -r`), and creates and checks out an initial +branch equal to the cloned repository's currently active branch. 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 branch. +current master branch, if any. 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 ------- --local:: @@ -75,16 +76,13 @@ OPTIONS 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 the `origin` branch nor the default - `remotes/origin` file is created. + 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>:: @@ -98,6 +96,15 @@ OPTIONS if unset the templates are taken from the installation defined default, typically `/usr/share/git-core/templates`. +--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 be any URL git-fetch supports. diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt index 2a5aea73ba..13be992006 100644 --- a/Documentation/git-pull.txt +++ b/Documentation/git-pull.txt @@ -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-svn.txt b/Documentation/git-svn.txt index f5f57e8f87..ce63defffd 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,24 +11,20 @@ SYNOPSIS DESCRIPTION ----------- -git-svn is a simple conduit for changesets between a single Subversion -branch and git. It is not to be confused with gitlink:git-svnimport[1]. -They were designed with very different goals in mind. +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 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). +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. -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. - -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 -------- @@ -57,11 +53,13 @@ See '<<fetch-args,Additional Fetch Arguments>>' if you are interested in manually joining branches on commit. 'dcommit':: - Commit all diffs from a specified head directly to the SVN + 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). It is recommended - that you run git-svn fetch and rebase (not pull) your commits - against the latest changes in the SVN repository. + 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 @@ -370,7 +368,7 @@ SVN was very wrong. Basic Examples ~~~~~~~~~~~~~~ -Tracking and contributing to a Subversion-managed project: +Tracking and contributing to a the trunk of a Subversion-managed project: ------------------------------------------------------------------------ # Initialize a repo (like git init-db): @@ -388,19 +386,44 @@ Tracking and contributing to a Subversion-managed project: git-svn show-ignore >> .git/info/exclude ------------------------------------------------------------------------ -REBASE VS. PULL ---------------- +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-db): + 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 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'. 'pull' -can cause non-linear history to be flattened when committing into SVN, -which can lead to merge commits reversing previous commits in SVN. +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 ----------------- diff --git a/Documentation/git-svnimport.txt b/Documentation/git-svnimport.txt index 2c7c7dad54..b166cf3327 100644 --- a/Documentation/git-svnimport.txt +++ b/Documentation/git-svnimport.txt @@ -15,7 +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> ] - [ -P <path_from_trunk> ] + [ -R <repack_each_revs>] [ -P <path_from_trunk> ] <SVN_repository_URL> [ <path> ] @@ -108,6 +108,14 @@ repository without -A. 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. + -P <path_from_trunk>:: Partial import of the SVN tree. + diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt index 48b82b86f8..80bece0775 100644 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@ -9,7 +9,7 @@ git-tag - Create a tag object signed with GPG SYNOPSIS -------- [verse] -'git-tag' [-a | -s | -u <key-id>] [-f | -d] [-m <msg> | -F <file>] +'git-tag' [-a | -s | -u <key-id>] [-f | -d | -v] [-m <msg> | -F <file>] <name> [<head>] 'git-tag' -l [<pattern>] @@ -35,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). @@ -55,6 +57,9 @@ 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). diff --git a/Documentation/glossary.txt b/Documentation/glossary.txt index 894883d7b6..7c1a6592c1 100644 --- a/Documentation/glossary.txt +++ b/Documentation/glossary.txt @@ -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 diff --git a/Documentation/hooks.txt b/Documentation/hooks.txt index 517f49b5cc..161123f142 100644 --- a/Documentation/hooks.txt +++ b/Documentation/hooks.txt @@ -126,9 +126,9 @@ 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 gr |