diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/callouts.xsl | 14 | ||||
| -rw-r--r-- | Documentation/config.txt | 47 | ||||
| -rw-r--r-- | Documentation/core-tutorial.txt | 16 | ||||
| -rw-r--r-- | Documentation/diff-options.txt | 5 | ||||
| -rw-r--r-- | Documentation/git-add.txt | 53 | ||||
| -rw-r--r-- | Documentation/git-branch.txt | 23 | ||||
| -rw-r--r-- | Documentation/git-clone.txt | 2 | ||||
| -rw-r--r-- | Documentation/git-commit.txt | 234 | ||||
| -rw-r--r-- | Documentation/git-diff.txt | 58 | ||||
| -rw-r--r-- | Documentation/git-merge-file.txt | 92 | ||||
| -rw-r--r-- | Documentation/git-merge-index.txt | 4 | ||||
| -rw-r--r-- | Documentation/git-push.txt | 15 | ||||
| -rw-r--r-- | Documentation/git-read-tree.txt | 16 | ||||
| -rw-r--r-- | Documentation/git-repo-config.txt | 14 | ||||
| -rw-r--r-- | Documentation/git-rerere.txt | 35 | ||||
| -rw-r--r-- | Documentation/git-reset.txt | 2 | ||||
| -rw-r--r-- | Documentation/git-show.txt | 40 | ||||
| -rw-r--r-- | Documentation/git-svn.txt | 6 | ||||
| -rw-r--r-- | Documentation/git-svnimport.txt | 13 | ||||
| -rw-r--r-- | Documentation/git.txt | 3 | ||||
| -rw-r--r-- | Documentation/tutorial-2.txt | 42 | ||||
| -rw-r--r-- | Documentation/tutorial.txt | 48 |
22 files changed, 578 insertions, 204 deletions
diff --git a/Documentation/callouts.xsl b/Documentation/callouts.xsl index ad03755d8f..6a361a2136 100644 --- a/Documentation/callouts.xsl +++ b/Documentation/callouts.xsl @@ -13,4 +13,18 @@ <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 21ec55797b..ceac54b024 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -79,8 +79,11 @@ core.logAllRefUpdates:: 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 - false by default (no automated creation of log files). + 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 @@ -137,16 +140,12 @@ branch.<name>.merge:: this option, `git pull` defaults to merge the first refspec fetched. Specify multiple values to get an octopus merge. -pager.color:: - 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` @@ -157,6 +156,24 @@ diff.color.<slot>:: `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, or `white`. +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.diff.<slot>. + diff.renameLimit:: The number of files to consider when performing the copy/rename detection; equivalent to the git diff option '-l'. @@ -271,20 +288,6 @@ showbranch.default:: The default set of branches for gitlink:git-show-branch[1]. See gitlink:git-show-branch[1]. -status.color:: - 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>:: - 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>. - tar.umask:: By default, gitlink:git-tar-tree[1] sets file and directories modes to 0666 or 0777. While this is both useful and acceptable for projects diff --git a/Documentation/core-tutorial.txt b/Documentation/core-tutorial.txt index 47505aa20a..5ea611748c 100644 --- a/Documentation/core-tutorial.txt +++ b/Documentation/core-tutorial.txt @@ -57,7 +57,7 @@ $ git-init-db 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 diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index 9cdd171af7..f12082e134 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -21,6 +21,11 @@ deleted lines in decimal notation and pathname without abbreviation, to make it more machine friendly. +--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 such as creations, renames and mode changes. diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt index 6342ea33e4..d86c0e7f19 100644 --- a/Documentation/git-add.txt +++ b/Documentation/git-add.txt @@ -3,7 +3,7 @@ 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 -------- @@ -11,16 +11,31 @@ SYNOPSIS 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. -It only adds non-ignored files, to add ignored files use +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 only adds non-ignored files, to add ignored files use "git update-index --add". +Please see gitlink:git-commit[1] for alternative ways to add content to a +commit. + + OPTIONS ------- <file>...:: - Files to add to the index (see gitlink:git-ls-files[1]). + Files to add content from. -n:: Don't actually add the file(s), just show if they exist. @@ -34,27 +49,12 @@ OPTIONS 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 +62,18 @@ 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`. 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-branch.txt b/Documentation/git-branch.txt index 4f5b5d5028..71417feba8 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -8,8 +8,9 @@ git-branch - List, create, or delete branches. SYNOPSIS -------- [verse] -'git-branch' [-r] [-a] [-v] [--abbrev=<length>] +'git-branch' [-r | -a] [-v [--abbrev=<length>]] 'git-branch' [-l] [-f] <branchname> [<start-point>] +'git-branch' (-m | -M) [<oldbranch>] <newbranch> 'git-branch' (-d | -D) <branchname>... DESCRIPTION @@ -24,6 +25,12 @@ 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. @@ -46,6 +53,12 @@ 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. + -r:: List the remote-tracking branches. @@ -53,7 +66,7 @@ OPTIONS List both remote-tracking branches and local branches. -v:: - Show sha1 and subject message for each head. + Show sha1 and commit subjectline for each head. --abbrev=<length>:: Alter minimum display length for sha1 in output listing, @@ -70,6 +83,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 diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index 985043faca..bfddb21fee 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -100,7 +100,7 @@ OPTIONS defined default, typically `/usr/share/git-core/templates`. --use-separate-remote:: - Save remotes heads under `$GIT_DIR/remotes/origin/` instead + Save remotes heads under `$GIT_DIR/refs/remotes/origin/` instead of `$GIT_DIR/refs/heads/`. Only the local master branch is saved in the latter. This is the default. diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index 517a86b238..0b74cd708e 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -14,25 +14,41 @@ 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 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 +71,13 @@ 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:: + By default, the command looks for suspicious lines the + commit introduces, and aborts 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 option turns off the check. -e|--edit:: The message taken from file with `-F`, command line with @@ -95,69 +108,140 @@ 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. - -If you make a commit and then found a mistake immediately after -that, you can recover from it with gitlink:git-reset[1]. + 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. -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. - -. 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. - -. 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...`. +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). + + +ENVIRONMENT VARIABLES +--------------------- +The command specified by either the VISUAL or EDITOR environment +variables is used to edit the commit log message. + +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-diff.txt b/Documentation/git-diff.txt index 3144864d85..10fdf88dce 100644 --- a/Documentation/git-diff.txt +++ b/Documentation/git-diff.txt @@ -8,38 +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 ] <tree-ish>{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 - `--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. + 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 <tree-ish>. 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 @@ -49,11 +65,11 @@ Various ways to check your working tree:: + ------------ $ git diff <1> -$ git diff --index <2> +$ 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-merge-file.txt b/Documentation/git-merge-file.txt new file mode 100644 index 0000000000..29d3faa556 --- /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 6cd0601082..0cf505ea84 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-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-read-tree.txt b/Documentation/git-read-tree.txt index 11bd9c0adc..0ff2890c7f 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-repo-config.txt b/Documentation/git-repo-config.txt index 5bede9ac22..b379ec5075 100644 --- a/Documentation/git-repo-config.txt +++ b/Documentation/git-repo-config.txt @@ -10,6 +10,7 @@ SYNOPSIS -------- [verse] '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] @@ -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 @@ -53,6 +55,10 @@ 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). Returns error code 1 if the key was not @@ -194,6 +200,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 8b6b651237..116dca4c06 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] DESCRIPTION ----------- @@ -27,6 +26,38 @@ 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. + + DISCUSSION ---------- diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt index 73a0ffc410..4a4ceb6201 100644 --- a/Documentation/git-reset.txt +++ b/Documentation/git-reset.txt @@ -31,7 +31,7 @@ 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:: diff --git a/Documentation/git-show.txt b/Documentation/git-show.txt index 4c880a8717..98dea6125d 100644 --- a/Documentation/git-show.txt +++ b/Documentation/git-show.txt @@ -3,20 +3,27 @@ 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. @@ -28,6 +35,25 @@ OPTIONS include::pretty-formats.txt[] + +EXAMPLES +-------- + +git show v1.0.0:: + Shows the tag `v1.0.0`. + +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`. + Author ------ Written by Linus Torvalds <torvalds@osdl.org> and diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt index a45067e164..c589a98630 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -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. diff --git a/Documentation/git-svnimport.txt b/Documentation/git-svnimport.txt index b1b87c2fcd..2c7c7dad54 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> ] + [ -P <path_from_trunk> ] <SVN_repository_URL> [ <path> ] @@ -103,9 +104,17 @@ 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.) - 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.txt b/Documentation/git.txt index 6382ef0a02..2a9e97dac1 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -351,6 +351,9 @@ gitlink:git-init-db[1]:: Creates an empty git object database, 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. diff --git a/Documentation/tutorial-2.txt b/Documentation/tutorial-2.txt index 42b6e7d7d2..60e54777dc 100644 --- a/Documentation/tutorial-2.txt +++ b/Documentation/tutorial-2.txt @@ -18,17 +18,18 @@ 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 +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. diff --git a/Documentation/tutorial.txt b/Documentation/tutorial.txt index fe4491de41..cb808d924b 100644 --- a/Documentation/tutorial.txt +++ b/Documentation/tutorial.txt @@ -38,7 +38,7 @@ $ git init-db 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 @@ -87,14 +87,48 @@ thorough description. Tools that turn commits into email, for 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 tell `commit` about the file as usual. +Viewing the changelog +--------------------- At any point you can view the history of your changes using |