diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/config.txt | 31 | ||||
| -rw-r--r-- | Documentation/cvs-migration.txt | 352 | ||||
| -rw-r--r-- | Documentation/diff-format.txt | 57 | ||||
| -rw-r--r-- | Documentation/diff-options.txt | 16 | ||||
| -rw-r--r-- | Documentation/git-branch.txt | 18 | ||||
| -rw-r--r-- | Documentation/git-clone.txt | 49 | ||||
| -rw-r--r-- | Documentation/git-diff.txt | 6 | ||||
| -rw-r--r-- | Documentation/git-merge.txt | 18 | ||||
| -rw-r--r-- | Documentation/git-push.txt | 15 | ||||
| -rw-r--r-- | Documentation/git-shortlog.txt | 1 | ||||
| -rw-r--r-- | Documentation/git-svn.txt | 46 | ||||
| -rw-r--r-- | Documentation/git-symbolic-ref.txt | 29 | ||||
| -rw-r--r-- | Documentation/git.txt | 32 | ||||
| -rw-r--r-- | Documentation/tutorial.txt | 41 |
14 files changed, 315 insertions, 396 deletions
diff --git a/Documentation/config.txt b/Documentation/config.txt index 9d3c71c3b8..f5a552ee87 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -125,21 +125,28 @@ apply.whitespace:: 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 remote branch - to be merged. - -pager.color:: + 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.pager:: A boolean to enable/disable colored output when the pager is in use (default is true). -diff.color:: +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` @@ -219,6 +226,12 @@ 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'. +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. @@ -258,19 +271,19 @@ showbranch.default:: The default set of branches for gitlink:git-show-branch[1]. See gitlink:git-show-branch[1]. -status.color:: +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. -status.color.<slot>:: +color.status.<slot>:: Use customized color for status colorization. `<slot>` is one of `header` (the header text of the status message), `updated` (files which are updated but not committed), `changed` (files which are changed but not updated in the index), or `untracked` (files which are not tracked by git). The values of - these variables may be specified as in diff.color.<slot>. + these variables may be specified as in color.diff.<slot>. tar.umask:: By default, gitlink:git-tar-tree[1] sets file and directories modes diff --git a/Documentation/cvs-migration.txt b/Documentation/cvs-migration.txt index 6812683a16..b657f4589f 100644 --- a/Documentation/cvs-migration.txt +++ b/Documentation/cvs-migration.txt @@ -1,113 +1,21 @@ 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. - - * 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. - -Importing a CVS archive ------------------------ - -First, install version 2.1 or higher of cvsps from -link:http://www.cobite.com/cvsps/[http://www.cobite.com/cvsps/] and make -sure it is in your path. The magic command line is then - -------------------------------------------- -$ git cvsimport -v -d <cvsroot> -C <destination> <module> -------------------------------------------- - -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. - -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. - -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. - -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. - -Development Models ------------------- - -CVS users are accustomed to giving a group of developers commit access to -a common repository. In the next section we'll explain how to do this -with git. However, the distributed nature of git allows other development -models, and you may want to first consider whether one of them might be a -better fit for your project. - -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. - -With a small group, developers may just pull changes from each other's -repositories without the need for a central maintainer. - -Emulating the CVS Development Model ------------------------------------ - -Start with an ordinary git working directory containing the project, and -remove the checked-out files, keeping just the bare .git directory: - ------------------------------------------------- -$ mv project/.git /pub/repo.git -$ rm -r project/ ------------------------------------------------- - -Next, give every team member read/write access to this repository. One -easy way to do this is to give all the team members ssh access to the -machine where the repository is hosted. If you don't want to give them a -full shell on the machine, there is a restricted shell which only allows -users to do git pushes and pulls; see gitlink:git-shell[1]. - -Put all the committers in the same group, and make the repository -writable by that group: - ------------------------------------------------- -$ chgrp -R $group repo.git -$ find repo.git -mindepth 1 -type d |xargs chmod ug+rwx,g+s -$ GIT_DIR=repo.git git repo-config core.sharedrepository true ------------------------------------------------- - -Make sure committers have a umask of at most 027, so that the directories -they create are writable and searchable by other group members. - -Suppose this repository is now set up in /pub/repo.git on the host +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: +repository over ssh with: ------------------------------------------------ $ git clone foo.com:/pub/repo.git/ my-project @@ -121,7 +29,8 @@ $ git pull origin ------------------------------------------------ which merges in any work that others might have done since the clone -operation. +operation. If there are uncommitted changes in your working tree, commit +them first before running git pull. [NOTE] ================================ @@ -129,20 +38,22 @@ 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 +URL: foo.com:/pub/project.git/ +Pull: refs/heads/master:refs/remotes/origin/master ------------ ================================ -You can update the shared repository with your changes using: +You can update the shared repository with your changes by first committing +your changes, and then using the gitlink:git-push[1] command: ------------------------------------------------ $ git push origin master ------------------------------------------------ -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. +to "push" those commits to the shared repository. If someone else has +updated the repository more recently, `git push`, like `cvs commit`, will +complain, in which case you must pull any changes before attempting the +push again. In the `git push` command above we specify the name of the remote branch to update (`master`). If we leave that out, `git push` tries to update @@ -151,21 +62,77 @@ in the local repository. So the last `push` can be done with either of: ------------ $ git push origin -$ git push repo.shared.xz:/pub/scm/project.git/ +$ git push foo.com:/pub/project.git/ ------------ as long as the shared repository does not have any branches other than `master`. -[NOTE] -============ -Because of this behavior, if the shared repository and the developer's -repository both have branches named `origin`, then a push like the above -attempts to update the `origin` branch in the shared repository from the -developer's `origin` branch. The results may be unexpected, so it's -usually best to remove any branch named `origin` from the shared -repository. -============ +Setting Up a Shared Repository +------------------------------ + +We assume you have already created a git repository for your project, +possibly created from scratch or from a tarball (see the +link:tutorial.html[tutorial]), or imported from an already existing CVS +repository (see the next section). + +Assume your existing repo is at /home/alice/myproject. Create a new "bare" +repository (a repository without a working tree) and fetch your project into +it: + +------------------------------------------------ +$ mkdir /pub/my-repo.git +$ cd /pub/my-repo.git +$ git --bare init-db --shared +$ git --bare fetch /home/alice/myproject master:master +------------------------------------------------ + +Next, give every team member read/write access to this repository. One +easy way to do this is to give all the team members ssh access to the +machine where the repository is hosted. If you don't want to give them a +full shell on the machine, there is a restricted shell which only allows +users to do git pushes and pulls; see gitlink:git-shell[1]. + +Put all the committers in the same group, and make the repository +writable by that group: + +------------------------------------------------ +$ chgrp -R $group /pub/my-repo.git +------------------------------------------------ + +Make sure committers have a umask of at most 027, so that the directories +they create are writable and searchable by other group members. + +Importing a CVS archive +----------------------- + +First, install version 2.1 or higher of cvsps from +link:http://www.cobite.com/cvsps/[http://www.cobite.com/cvsps/] and make +sure it is in your path. Then cd to a checked out CVS working directory +of the project you are interested in and run gitlink:git-cvsimport[1]: + +------------------------------------------- +$ git cvsimport -C <destination> +------------------------------------------- + +This puts a git archive of the named CVS module in the directory +<destination>, which will be created if necessary. + +The import checks out from CVS every revision of every file. Reportedly +cvsimport can average some twenty revisions per second, so for a +medium-sized project this should not take more than a couple of minutes. +Larger projects or remote repositories may take longer. + +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. + +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 ------------------------------------- @@ -178,127 +145,30 @@ 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 e4520e28e5..883c1bb0a6 100644 --- a/Documentation/diff-format.txt +++ b/Documentation/diff-format.txt @@ -65,62 +65,17 @@ Generating patches with -p When "git-diff-index", "git-diff-tree", or "git-diff-files" are run with a '-p' option, they do not produce the output described above; -instead they produce a patch file. +instead they produce a patch file. You can customize the creation +of such patches via the GIT_EXTERNAL_DIFF and the GIT_DIFF_OPTS +environment variables. -The patch generation can be customized at two levels. - -1. When the environment variable 'GIT_EXTERNAL_DIFF' is not set, - these commands internally invoke "diff" like this: - - diff -L a/<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, diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index e112172ca5..9cdd171af7 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -129,5 +129,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/git-branch.txt b/Documentation/git-branch.txt index d43ef1dec4..4f5b5d5028 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -8,14 +8,16 @@ git-branch - List, create, or delete branches. SYNOPSIS -------- [verse] -'git-branch' [-r] +'git-branch' [-r] [-a] [-v] [--abbrev=<length>] 'git-branch' [-l] [-f] <branchname> [<start-point>] 'git-branch' (-d | -D) <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>. @@ -45,7 +47,17 @@ OPTIONS a branch that already exists with the same name. -r:: - List only the "remote" branches. + List the remote-tracking branches. + +-a:: + List both remote-tracking branches and local branches. + +-v:: + Show sha1 and subject message 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. diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index 86060472ad..985043faca 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -11,26 +11,26 @@ SYNOPSIS [verse] 'git-clone' [--template=<template_directory>] [-l [-s]] [-q] [-n] [--bare] [-o <name>] [-u <upload-pack>] [--reference <repository>] - [--use-separate-remote] <repository> [<directory>] + [--use-separate-remote | --no-separate-remote] <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 a master +branch equal to the cloned repository's master branch. - Pull: master:origin - -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. +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. +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,9 +71,13 @@ 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 the `origin` branch nor the default + `remotes/origin` file is created. --origin <name>:: -o <name>:: @@ -97,8 +101,15 @@ OPTIONS --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. + of `$GIT_DIR/refs/heads/`. Only the local master branch is + saved in the latter. This is the default. + +--no-separate-remote:: + Save remotes heads in the same namespace as the local + heads, `$GIT_DIR/refs/heads/'. In regular repositories, + this is a legacy setup git-clone created by default in + older Git versions, and will be removed before the next + major release. <repository>:: The (possibly remote) repository to clone from. It can diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt index 228c4d95bd..3144864d85 100644 --- a/Documentation/git-diff.txt +++ b/Documentation/git-diff.txt @@ -22,8 +22,10 @@ the number of trees given to the command. * 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 + `--index` can be given to compare the index file and the named tree. + `--cached` is a deprecated alias for `--index`. It's use is + discouraged. * When two <tree-ish>s are given, these two trees are compared using `git-diff-tree`. @@ -47,7 +49,7 @@ Various ways to check your working tree:: + ------------ $ git diff <1> -$ git diff --cached <2> +$ git diff --index <2> $ git diff HEAD <3> ------------ + diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt index bebf30ad3d..e2954aa76e 100644 --- a/Documentation/git-merge.txt +++ b/Documentation/git-merge.txt @@ -8,12 +8,14 @@ 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>]... + [--reflog-action=<action>] + -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,13 +29,19 @@ 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. +--reflog-action=<action>:: + This is used internally when `git-pull` calls this command + to record that the merge was created by `pull` command + in the `ref-log` entry that results from the merge. + include::merge-strategies.txt[] diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index d4ae99fa53..197f4b512f 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-shortlog.txt b/Documentation/git-shortlog.txt index d54fc3e5c6..95fa9010c1 100644 --- a/Documentation/git-shortlog.txt +++ b/Documentation/git-shortlog.txt @@ -8,6 +8,7 @@ git-shortlog - Summarize 'git log' output SYNOPSIS -------- git-log --pretty=short | 'git-shortlog' [-h] [-n] [-s] +git-shortlog [-n|--number] [-s|--summary] [<committish>...] DESCRIPTION ----------- diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt index a764d1f8ee..c589a98630 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -49,7 +49,7 @@ 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' +remotes/git-svn and work on that branch. Use the 'dcommit' command (see below) to write git commits back to remotes/git-svn. @@ -57,11 +57,13 @@ See '<<fetch-args,Additional Fetch Arguments>>' if you are interested in manually joining branches on commit. 'dcommit':: - Commit all diffs from the current HEAD directly to the SVN + Commit all diffs 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 + 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. + An optional command-line argument may be specified as an + alternative to HEAD. This is advantageous over 'commit' (below) because it produces cleaner, more linear history. @@ -274,7 +276,7 @@ ADVANCED OPTIONS -b<refname>:: --branch <refname>:: -Used with 'fetch' or 'commit'. +Used with 'fetch', 'dcommit' or 'commit'. This can be used to join arbitrary git branches to remotes/git-svn on new commits where the tree object is equivalent. @@ -368,7 +370,7 @@ SVN was very wrong. Basic Examples ~~~~~~~~~~~~~~ -Tracking and contributing to an Subversion managed-project: +Tracking and contributing to a Subversion-managed project: ------------------------------------------------------------------------ # Initialize a repo (like git init-db): @@ -377,10 +379,9 @@ Tracking and contributing to an Subversion managed-project: 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 +# 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: @@ -404,26 +405,24 @@ 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/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. +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 @@ -486,7 +485,8 @@ If you are not using the SVN::* Perl libraries and 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'. +probably just to rm -rf $GIT_DIR/git-svn/tree and run 'rebuild'. You +can avoid this problem entirely by using 'dcommit'. We ignore all SVN properties except svn:executable. Too difficult to map them since we rely heavily on git write-tree being _exactly_ the diff --git a/Documentation/git-symbolic-ref.txt b/Documentation/git-symbolic-ref.txt index 68ac6a65df..4bc35a1d4b 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.txt b/Documentation/git.txt index 619d65685e..6382ef0a02 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -639,11 +639,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 ~~~~~ diff --git a/Documentation/tutorial.txt b/Documentation/tutorial.txt index 6555e58882..fe4491de41 100644 --- a/Documentation/tutorial.txt +++ b/Documentation/tutorial.txt @@ -228,29 +228,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 @@ -259,8 +258,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 @@ -270,6 +269,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 ------------------------------------- |