From 0eb4f7cdf85273c88feb95c677a808cee9cfd859 Mon Sep 17 00:00:00 2001 From: "J. Bruce Fields" Date: Sun, 5 Aug 2007 17:18:52 -0400 Subject: user-manual: update for new default --track behavior Update documentation to reflect the --track default. That change seems to have happened in the 1.5.3 -rc's, so bump the "for version x.y.z or newer" warning as well. Signed-off-by: J. Bruce Fields --- Documentation/user-manual.txt | 23 +++++++++-------------- 1 file changed, 9 insertions(+), 14 deletions(-) (limited to 'Documentation') diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index 0071cd070e..c0820e9036 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) ______________________________________________ @@ -1667,24 +1667,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..remote and branch..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..remote and branch..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 -- cgit v1.2.3 From 7a7cc594ca294a58b6d7ae5aa50a65378538e875 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Fri, 3 Aug 2007 15:22:59 -0700 Subject: user-manual: mention git stash Mention the git-stash command as a way to temporarily set aside work in progress. Signed-off-by: J. Bruce Fields --- Documentation/user-manual.txt | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) (limited to 'Documentation') diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index c0820e9036..9efe85ce2f 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -1484,6 +1484,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 ------------------------- -- cgit v1.2.3 From 407c0c87e15b3cf60347f4fc0bcdb4d239de4163 Mon Sep 17 00:00:00 2001 From: "J. Bruce Fields" Date: Sun, 5 Aug 2007 18:12:37 -0400 Subject: user-manual: mention git-gui The git gui project seems to be still in early stages, but at a point where it's worth mentioning as an alternative way of creating commits. One feature of interest is the ability to manipulate individual diff hunks. However, people have found that feature not to be easily discoverable from the user-interface. Pending some ui improvements, a parenthetical hint here may help. (Thanks to Steffen Prohask and Junio Hamano for suggesting the language.) Signed-off-by: J. Bruce Fields --- Documentation/user-manual.txt | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) (limited to 'Documentation') diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index 9efe85ce2f..f89952ad84 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -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 ----------------------------- @@ -2506,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: -- cgit v1.2.3 From 5f42ac921fe06bbb80df82d8fa5cb15701ec2f60 Mon Sep 17 00:00:00 2001 From: "J. Bruce Fields" Date: Sun, 5 Aug 2007 19:16:09 -0400 Subject: documentation: use the word "index" in the git-add manual page It was a neat trick to show that you could introduce the git-add manual page without using the word "index", and it was certainly an improvement over the previous man page (which started out "A simple wrapper for git-update-index to add files to the index..."). But it's possible to use the standard terminology without sacrificing user-friendliness. So, rewrite to use the word "index" when appropriate. Signed-off-by: J. Bruce Fields --- Documentation/git-add.txt | 41 ++++++++++++++++++++++------------------- 1 file changed, 22 insertions(+), 19 deletions(-) (limited to 'Documentation') diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt index a0c9f68580..37077b523e 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. -- cgit v1.2.3