diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/RelNotes-1.5.3.txt | 18 | ||||
| -rw-r--r-- | Documentation/blame-options.txt | 20 | ||||
| -rwxr-xr-x | Documentation/cmd-list.perl | 16 | ||||
| -rw-r--r-- | Documentation/config.txt | 2 | ||||
| -rw-r--r-- | Documentation/git-add.txt | 41 | ||||
| -rw-r--r-- | Documentation/git-commit.txt | 29 | ||||
| -rw-r--r-- | Documentation/git-config.txt | 4 | ||||
| -rw-r--r-- | Documentation/git-push.txt | 2 | ||||
| -rw-r--r-- | Documentation/git-rev-parse.txt | 2 | ||||
| -rw-r--r-- | Documentation/git-stash.txt | 8 | ||||
| -rw-r--r-- | Documentation/git-status.txt | 7 | ||||
| -rw-r--r-- | Documentation/git-svn.txt | 20 | ||||
| -rw-r--r-- | Documentation/git.txt | 16 | ||||
| -rwxr-xr-x | Documentation/install-doc-quick.sh | 12 | ||||
| -rw-r--r-- | Documentation/user-manual.txt | 66 |
15 files changed, 178 insertions, 85 deletions
diff --git a/Documentation/RelNotes-1.5.3.txt b/Documentation/RelNotes-1.5.3.txt index 785bd3845..21bb1fc6f 100644 --- a/Documentation/RelNotes-1.5.3.txt +++ b/Documentation/RelNotes-1.5.3.txt @@ -40,16 +40,22 @@ Updates since v1.5.2 $GIT_DIR to work in a subdirectory of a working tree that is not located at "$GIT_DIR/..". + - Giving "--file=<file>" option to "git config" is the same as + running the command with GIT_CONFIG=<file> environment. + - "git log" learned a new option "--follow", to follow renaming history of a single file. - "git-filter-branch" lets you rewrite the revision history of - the current branch, creating a new branch. You can specify a - number of filters to modify the commits, files and trees. + specified branches. You can specify a number of filters to + modify the commits, files and trees. - "git-cvsserver" learned new options (--base-path, --export-all, --strict-paths) inspired by git-daemon. + - "git daemon --base-path-relaxed" can help migrating a repository URL + that did not use to use --base-path to use --base-path. + - "git-commit" can use "-t templatefile" option and commit.template configuration variable to prime the commit message given to you in the editor. @@ -120,6 +126,9 @@ Updates since v1.5.2 of the format ('tgz', 'tbz2' or 'zip'). Please update the your configuration file accordingly. + - "git diff" (but not the plumbing level "git diff-tree") now + recursively descends into trees by default. + - The editor to use with many interactive commands can be overridden with GIT_EDITOR environment variable, or if it does not exist, with core.editor configuration variable. As @@ -165,6 +174,9 @@ Updates since v1.5.2 - The diffstat given after a merge (or a pull) honors the color.diff configuration. + - "git commit --amend" is now compatible with various message source + options such as -m/-C/-c/-F. + - "git-apply --whitespace=strip" removes blank lines added at the end of the file. @@ -262,6 +274,6 @@ this release, unless otherwise noted. -- exec >/var/tmp/1 -O=v1.5.3-rc3 +O=v1.5.3-rc4 echo O=`git describe refs/heads/master` git shortlog --no-merges $O..refs/heads/master ^refs/heads/maint diff --git a/Documentation/blame-options.txt b/Documentation/blame-options.txt index a46bf6ce7..17379f057 100644 --- a/Documentation/blame-options.txt +++ b/Documentation/blame-options.txt @@ -64,11 +64,11 @@ of lines before or after the line given by <start>. assigns blame to the lines that were moved down (i.e. A) to the child commit. With this option, both groups of lines are blamed on the parent. - - <num> is optional but it is the lower bound on the number of - alphanumeric characters that git must detect as moving - within a file for it to associate those lines with the parent - commit. ++ +<num> is optional but it is the lower bound on the number of +alphanumeric characters that git must detect as moving +within a file for it to associate those lines with the parent +commit. -C|<num>|:: In addition to `-M`, detect lines copied from other @@ -77,11 +77,11 @@ of lines before or after the line given by <start>. around across files. When this option is given twice, the command looks for copies from all other files in the parent for the commit that creates the file in addition. - - <num> is optional but it is the lower bound on the number of - alphanumeric characters that git must detect as moving - between files for it to associate those lines with the parent - commit. ++ +<num> is optional but it is the lower bound on the number of +alphanumeric characters that git must detect as moving +between files for it to associate those lines with the parent +commit. -h, --help:: Show help message. diff --git a/Documentation/cmd-list.perl b/Documentation/cmd-list.perl index 2143995ec..4ee76eaf9 100755 --- a/Documentation/cmd-list.perl +++ b/Documentation/cmd-list.perl @@ -68,6 +68,8 @@ for my $cat (qw(ancillaryinterrogators } } +# The following list is sorted with "sort -d" to make it easier +# to find entry in the resulting git.html manual page. __DATA__ git-add mainporcelain git-am mainporcelain @@ -80,9 +82,9 @@ git-blame ancillaryinterrogators git-branch mainporcelain git-bundle mainporcelain git-cat-file plumbinginterrogators -git-checkout-index plumbingmanipulators -git-checkout mainporcelain git-check-attr purehelpers +git-checkout mainporcelain +git-checkout-index plumbingmanipulators git-check-ref-format purehelpers git-cherry ancillaryinterrogators git-cherry-pick mainporcelain @@ -91,6 +93,7 @@ git-clean mainporcelain git-clone mainporcelain git-commit mainporcelain git-commit-tree plumbingmanipulators +git-config ancillarymanipulators git-convert-objects ancillarymanipulators git-count-objects ancillaryinterrogators git-cvsexportcommit foreignscminterface @@ -98,9 +101,9 @@ git-cvsimport foreignscminterface git-cvsserver foreignscminterface git-daemon synchingrepositories git-describe mainporcelain +git-diff mainporcelain git-diff-files plumbinginterrogators git-diff-index plumbinginterrogators -git-diff mainporcelain git-diff-tree plumbinginterrogators git-fast-import ancillarymanipulators git-fetch mainporcelain @@ -130,13 +133,13 @@ git-ls-remote plumbinginterrogators git-ls-tree plumbinginterrogators git-mailinfo purehelpers git-mailsplit purehelpers +git-merge mainporcelain git-merge-base plumbinginterrogators git-merge-file plumbingmanipulators git-merge-index plumbingmanipulators -git-merge mainporcelain git-merge-one-file purehelpers -git-merge-tree ancillaryinterrogators git-mergetool ancillarymanipulators +git-merge-tree ancillaryinterrogators git-mktag plumbingmanipulators git-mktree plumbingmanipulators git-mv mainporcelain @@ -157,9 +160,8 @@ git-rebase mainporcelain git-receive-pack synchelpers git-reflog ancillarymanipulators git-relink ancillarymanipulators -git-repack ancillarymanipulators -git-config ancillarymanipulators git-remote ancillarymanipulators +git-repack ancillarymanipulators git-request-pull foreignscminterface git-rerere ancillaryinterrogators git-reset mainporcelain diff --git a/Documentation/config.txt b/Documentation/config.txt index 3135cb7a6..de9e72b56 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -101,7 +101,7 @@ Example # Proxy settings [core] - gitProxy="ssh" for "ssh://kernel.org/" + gitProxy="ssh" for "kernel.org" gitProxy=default-proxy ; for the rest Variables diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt index 76d2b0585..4af3a9b0d 100644 --- a/Documentation/git-add.txt +++ b/Documentation/git-add.txt @@ -3,7 +3,7 @@ git-add(1) NAME ---- -git-add - Add file contents to the changeset to be committed next +git-add - Add file contents to the index SYNOPSIS -------- @@ -11,24 +11,27 @@ SYNOPSIS DESCRIPTION ----------- -All the changed file contents to be committed together in a single set -of changes must be "added" with the 'add' command before using the -'commit' command. This is not only for adding new files. Even modified -files must be added to the set of changes about to be committed. - -This command can be performed multiple times before a commit. The added -content corresponds to the state of specified file(s) at the time the -'add' command is used. This means the 'commit' command will not consider -subsequent changes to already added content if it is not added again before -the commit. - -The 'git status' command can be used to obtain a summary of what is included -for the next commit. - -This command can be used to add ignored files with `-f` (force) -option, but they have to be -explicitly and exactly specified from the command line. File globbing -and recursive behaviour do not add ignored files. +This command adds the current content of new or modified files to the +index, thus staging that content for inclusion in the next commit. + +The "index" holds a snapshot of the content of the working tree, and it +is this snapshot that is taken as the contents of the next commit. Thus +after making any changes to the working directory, and before running +the commit command, you must use the 'add' command to add any new or +modified files to the index. + +This command can be performed multiple times before a commit. It only +adds the content of the specified file(s) at the time the add command is +run; if you want subsequent changes included in the next commit, then +you must run 'git add' again to add the new content to the index. + +The 'git status' command can be used to obtain a summary of which +files have changes that are staged for the next commit. + +The 'add' command can be used to add ignored files with `-f` (force) +option, but they have to be explicitly and exactly specified from the +command line. File globbing and recursive behaviour do not add ignored +files. Please see gitlink:git-commit[1] for alternative ways to add content to a commit. diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index 627994eb9..e54fb1210 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -15,26 +15,27 @@ SYNOPSIS DESCRIPTION ----------- -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: +Use 'git commit' to store the current contents of the index in a new +commit along with a log message describing the changes you have made. + +The content to be added can be specified in several ways: 1. by using gitlink:git-add[1] to incrementally "add" changes to the - next commit before using the 'commit' command (Note: even modified + index 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; +2. by using gitlink:git-rm[1] to remove files from the working tree + and the index, 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; +3. by listing files as arguments to the 'commit' command, in which + case the commit will ignore changes staged in the index, and instead + record the current content of the listed files; -4. by using the -a switch with the 'commit' command to automatically "add" - changes from all known files i.e. files that have already been committed - before, and to automatically "rm" files that have been - removed from the working tree, and perform the actual commit. +4. by using the -a switch with the 'commit' command to automatically + "add" changes from all known files (i.e. all files that are already + listed in the index) and to automatically "rm" files in the index + that have been removed from the working tree, and then perform the + actual commit; 5. by using the --interactive switch with the 'commit' command to decide one by one which files should be part of the commit, before finalizing the diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt index 8451cccf8..c3dffffe3 100644 --- a/Documentation/git-config.txt +++ b/Documentation/git-config.txt @@ -214,9 +214,7 @@ Given a .git/config like this: ; Proxy settings [core] - gitproxy="ssh" for "ssh://kernel.org/" gitproxy="proxy-command" for kernel.org - gitproxy="myprotocol-command" for "my://" gitproxy=default-proxy ; for all the rest you can set the filemode to true with @@ -291,7 +289,7 @@ To actually match only values with an exclamation mark, you have to To add a new proxy, without altering any of the existing ones, use ------------ -% git config core.gitproxy '"proxy" for example.com' +% git config core.gitproxy '"proxy-command" for example.com' ------------ diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index 74a0da1ed..0dd9caf86 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -79,7 +79,7 @@ the remote repository. -f, \--force:: Usually, the command refuses to update a remote ref that is - not a descendant of the local ref used to overwrite it. + not an ancestor of the local ref used to overwrite it. This flag disables the check. This can cause the remote repository to lose commits; use it with care. diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index eea9c9cfe..4b4d229e6 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -224,7 +224,7 @@ left-to-right. G H I J \ / \ / D E F - \ | / \ + \ | / \ \ | / | \|/ | B C diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt index 17121ade5..05f40cff6 100644 --- a/Documentation/git-stash.txt +++ b/Documentation/git-stash.txt @@ -29,8 +29,8 @@ you create one. The latest stash you created is stored in `$GIT_DIR/refs/stash`; older stashes are found in the reflog of this reference and can be named using -the usual reflog syntax (e.g. `stash@\{1}` is the most recently -created stash, `stash@\{2}` is the one before it, `stash@\{2.hours.ago}` +the usual reflog syntax (e.g. `stash@\{0}` is the most recently +created stash, `stash@\{1}` is the one before it, `stash@\{2.hours.ago}` is also possible). OPTIONS @@ -45,7 +45,7 @@ save:: list:: List the stashes that you currently have. Each 'stash' is listed - with its name (e.g. `stash@\{0}` is the latest stash, `stash@\{1} is + with its name (e.g. `stash@\{0}` is the latest stash, `stash@\{1}` is the one before, etc.), the name of the branch that was current when the stash was made, and a short description of the commit the stash was based on. @@ -61,7 +61,7 @@ show [<stash>]:: stashed state and its original parent. When no `<stash>` is given, shows the latest one. By default, the command shows the diffstat, but it will accept any format known to `git-diff` (e.g., `git-stash show - -p stash@\{2}` to view the second most recent stash in patch form). + -p stash@\{1}` to view the second most recent stash in patch form). apply [<stash>]:: diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt index 6f16eb032..8fd0fc623 100644 --- a/Documentation/git-status.txt +++ b/Documentation/git-status.txt @@ -27,6 +27,13 @@ The command takes the same set of options as `git-commit`; it shows what would be committed if the same options are given to `git-commit`. +If any paths have been touched in the working tree (that is, +their modification times have changed) but their contents and +permissions are identical to those in the index file, the command +updates the index file. Running `git-status` can thus speed up +subsequent operations such as `git-diff` if the working tree +contains many paths that have been touched but not modified. + OUTPUT ------ diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt index 0a210e4be..816340b94 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -435,6 +435,26 @@ Tracking and contributing to an entire Subversion-managed project # of dcommit/rebase/show-ignore should be the same as above. ------------------------------------------------------------------------ +The initial 'git-svn clone' can be quite time-consuming +(especially for large Subversion repositories). If multiple +people (or one person with multiple machines) want to use +git-svn to interact with the same Subversion repository, you can +do the initial 'git-svn clone' to a repository on a server and +have each person clone that repository with 'git clone': + +------------------------------------------------------------------------ +# Do the initial import on a server + ssh server "cd /pub && git-svn clone http://svn.foo.org/project +# Clone locally + git clone server:/pub/project +# Tell git-svn which branch contains the Subversion commits + git update-ref refs/remotes/git-svn origin/master +# Initialize git-svn locally (be sure to use the same URL and -T/-b/-t options as were used on server) + git-svn init http://svn.foo.org/project +# Pull the latest changes from Subversion + git-svn rebase +------------------------------------------------------------------------ + REBASE VS. PULL/MERGE --------------------- diff --git a/Documentation/git.txt b/Documentation/git.txt index 4c4d1746e..18f8b6a0a 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -421,6 +421,22 @@ other to an empty string or to the value "cat", git will not launch a pager. +'GIT_SSH':: + If this environment variable is set then gitlink:git-fetch[1] + and gitlink:git-push[1] will use this command instead + of `ssh` when they need to connect to a remote system. + The 'GIT_SSH' command will be given exactly two arguments: + the 'username@host' (or just 'host') from the URL and the + shell command to execute on that remote system. ++ +To pass options to the program that you want to list in GIT_SSH +you will need to wrap the program and options into a shell script, +then set GIT_SSH to refer to the shell script. ++ +Usually it is easier to configure any desired options through your +personal `.ssh/config` file. Please consult your ssh documentation +for further details. + 'GIT_FLUSH':: If this environment variable is set to "1", then commands such as git-blame (in incremental mode), git-rev-list, git-log, diff --git a/Documentation/install-doc-quick.sh b/Documentation/install-doc-quick.sh index e6601bdd8..5433cf8ce 100755 --- a/Documentation/install-doc-quick.sh +++ b/Documentation/install-doc-quick.sh @@ -7,7 +7,7 @@ mandir="$2" SUBDIRECTORY_OK=t USAGE='<refname> <target directory>' . git-sh-setup -export GIT_DIR +cd_to_toplevel test -z "$mandir" && usage if ! git rev-parse --verify "$head^0" >/dev/null; then @@ -18,14 +18,14 @@ fi GIT_INDEX_FILE=`pwd`/.quick-doc.index export GIT_INDEX_FILE rm -f "$GIT_INDEX_FILE" +trap 'rm -f "$GIT_INDEX_FILE"' 0 + git read-tree $head git checkout-index -a -f --prefix="$mandir"/ if test -n "$GZ"; then - cd "$mandir" - for i in `git ls-tree -r --name-only $head` - do - gzip < $i > $i.gz && rm $i - done + git ls-tree -r --name-only $head | + xargs printf "$mandir/%s\n" | + xargs gzip -f fi rm -f "$GIT_INDEX_FILE" diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index 0071cd070..f89952ad8 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -1,4 +1,4 @@ -Git User's Manual (for version 1.5.1 or newer) +Git User's Manual (for version 1.5.3 or newer) ______________________________________________ @@ -1079,6 +1079,11 @@ $ git diff HEAD # difference between HEAD and working tree; what $ git status # a brief per-file summary of the above. ------------------------------------------------- +You can also use gitlink:git-gui[1] to create commits, view changes in +the index and the working tree files, and individually select diff hunks +for inclusion in the index (by right-clicking on the diff hunk and +choosing "Stage Hunk For Commit"). + [[creating-good-commit-messages]] Creating good commit messages ----------------------------- @@ -1484,6 +1489,38 @@ $ git show HEAD^:path/to/file which will display the given version of the file. +[[interrupted-work]] +Temporarily setting aside work in progress +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +While you are in the middle of working on something complicated, you +find an unrelated but obvious and trivial bug. You would like to fix it +before continuing. You can use gitlink:git-stash[1] to save the current +state of your work, and after fixing the bug (or, optionally after doing +so on a different branch and then coming back), unstash the +work-in-progress changes. + +------------------------------------------------ +$ git stash "work in progress for foo feature" +------------------------------------------------ + +This command will save your changes away to the `stash`, and +reset your working tree and the index to match the tip of your +current branch. Then you can make your fix as usual. + +------------------------------------------------ +... edit and test ... +$ git commit -a -m "blorpl: typofix" +------------------------------------------------ + +After that, you can go back to what you were working on with +`git stash apply`: + +------------------------------------------------ +$ git stash apply +------------------------------------------------ + + [[ensuring-good-performance]] Ensuring good performance ------------------------- @@ -1667,24 +1704,19 @@ one step: $ git pull origin master ------------------------------------------------- -In fact, "origin" is normally the default repository to pull from, -and the default branch is normally the HEAD of the remote repository, -so often you can accomplish the above with just +In fact, if you have "master" checked out, then by default "git pull" +merges from the HEAD branch of the origin repository. So often you can +accomplish the above with just a simple ------------------------------------------------- $ git pull ------------------------------------------------- -See the descriptions of the branch.<name>.remote and branch.<name>.merge -options in gitlink:git-config[1] to learn how to control these defaults -depending on the current branch. Also note that the --track option to -gitlink:git-branch[1] and gitlink:git-checkout[1] can be used to -automatically set the default remote branch to pull from at the time -that a branch is created: - -------------------------------------------------- -$ git checkout --track -b maint origin/maint -------------------------------------------------- +More generally, a branch that is created from a remote branch will pull +by default from that branch. See the descriptions of the +branch.<name>.remote and branch.<name>.merge options in +gitlink:git-config[1], and the discussion of the --track option in +gitlink:git-checkout[1], to learn how to control these defaults. In addition to saving you keystrokes, "git pull" also helps you by producing a default commit message documenting the branch and @@ -2479,8 +2511,10 @@ $ gitk origin..mywork & And browse through the list of patches in the mywork branch using gitk, applying them (possibly in a different order) to mywork-new using -cherry-pick, and possibly modifying them as you go using commit ---amend. +cherry-pick, and possibly modifying them as you go using commit --amend. +The git-gui[1] command may also help as it allows you to individually +select diff hunks for inclusion in the index (by right-clicking on the +diff hunk and choosing "Stage Hunk for Commit"). Another technique is to use git-format-patch to create a series of patches, then reset the state to before the patches: |