{"thread":{"id":"9401","subject":"[PATCH 2/5] user-manual: mention git stash","startedAt":"2007-08-06T04:33:58Z","lastAt":"2007-08-06T04:34:02Z","messageCount":5,"participants":["J. Bruce Fields"],"isPatch":true,"patchVersion":1,"patchTotal":5},"messages":[{"id":"49982","messageId":"24774.838719941$1186374891@news.gmane.org","threadId":"9401","inReplyTo":"11863748422001-git-send-email-","subject":"[PATCH 1/5] user-manual: update for new default --track behavior","fromName":"J. Bruce Fields","fromEmail":"bfields@citi.umich.edu","sentAt":"2007-08-06T04:33:58Z","receivedAt":"2007-08-06T04:33:58Z","isPatch":true,"sender":{"key":"bfields@citi.umich.edu","avatar":null},"body":"From: J. Bruce Fields <bfields@pig.linuxdev.us.dell.com>\n\nUpdate documentation to reflect the --track default.\n\nThat change seems to have happened in the 1.5.3 -rc's, so bump the \"for\nversion x.y.z or newer\" warning as well.\n\nSigned-off-by: J. Bruce Fields <bfields@citi.umich.edu>\n---\n Documentation/user-manual.txt |   23 +++++++++--------------\n 1 files changed, 9 insertions(+), 14 deletions(-)\n\ndiff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\nindex 0071cd0..c0820e9 100644\n--- a/Documentation/user-manual.txt\n+++ b/Documentation/user-manual.txt\n@@ -1,4 +1,4 @@\n-Git User's Manual (for version 1.5.1 or newer)\n+Git User's Manual (for version 1.5.3 or newer)\n ______________________________________________\n \n \n@@ -1667,24 +1667,19 @@ one step:\n $ git pull origin master\n -------------------------------------------------\n \n-In fact, \"origin\" is normally the default repository to pull from,\n-and the default branch is normally the HEAD of the remote repository,\n-so often you can accomplish the above with just\n+In fact, if you have \"master\" checked out, then by default \"git pull\"\n+merges from the HEAD branch of the origin repository.  So often you can\n+accomplish the above with just a simple\n \n -------------------------------------------------\n $ git pull\n -------------------------------------------------\n \n-See the descriptions of the branch.<name>.remote and branch.<name>.merge\n-options in gitlink:git-config[1] to learn how to control these defaults\n-depending on the current branch.  Also note that the --track option to\n-gitlink:git-branch[1] and gitlink:git-checkout[1] can be used to\n-automatically set the default remote branch to pull from at the time\n-that a branch is created:\n-\n--------------------------------------------------\n-$ git checkout --track -b maint origin/maint\n--------------------------------------------------\n+More generally, a branch that is created from a remote branch will pull\n+by default from that branch.  See the descriptions of the\n+branch.<name>.remote and branch.<name>.merge options in\n+gitlink:git-config[1], and the discussion of the --track option in\n+gitlink:git-checkout[1], to learn how to control these defaults.\n \n In addition to saving you keystrokes, \"git pull\" also helps you by\n producing a default commit message documenting the branch and\n-- \n1.5.3.GIT\n"},{"id":"49979","messageId":"18328.9634449922$1186374869@news.gmane.org","threadId":"9401","inReplyTo":"1186374842108-git-send-email-","subject":"[PATCH 2/5] user-manual: mention git stash","fromName":"J. Bruce Fields","fromEmail":"bfields@citi.umich.edu","sentAt":"2007-08-06T04:33:59Z","receivedAt":"2007-08-06T04:33:59Z","isPatch":true,"sender":{"key":"bfields@citi.umich.edu","avatar":null},"body":"From: Junio C Hamano <gitster@pobox.com>\n\nMention the git-stash command as a way to temporarily set aside work in\nprogress.\n\nSigned-off-by: J. Bruce Fields <bfields@citi.umich.edu>\n---\n Documentation/user-manual.txt |   32 ++++++++++++++++++++++++++++++++\n 1 files changed, 32 insertions(+), 0 deletions(-)\n\ndiff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\nindex c0820e9..9efe85c 100644\n--- a/Documentation/user-manual.txt\n+++ b/Documentation/user-manual.txt\n@@ -1484,6 +1484,38 @@ $ git show HEAD^:path/to/file\n \n which will display the given version of the file.\n \n+[[interrupted-work]]\n+Temporarily setting aside work in progress\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+\n+While you are in the middle of working on something complicated, you\n+find an unrelated but obvious and trivial bug.  You would like to fix it\n+before continuing.  You can use gitlink:git-stash[1] to save the current\n+state of your work, and after fixing the bug (or, optionally after doing\n+so on a different branch and then coming back), unstash the\n+work-in-progress changes.\n+\n+------------------------------------------------\n+$ git stash \"work in progress for foo feature\"\n+------------------------------------------------\n+\n+This command will save your changes away to the `stash`, and\n+reset your working tree and the index to match the tip of your\n+current branch.  Then you can make your fix as usual.\n+\n+------------------------------------------------\n+... edit and test ...\n+$ git commit -a -m \"blorpl: typofix\"\n+------------------------------------------------\n+\n+After that, you can go back to what you were working on with\n+`git stash apply`:\n+\n+------------------------------------------------\n+$ git stash apply\n+------------------------------------------------\n+\n+\n [[ensuring-good-performance]]\n Ensuring good performance\n -------------------------\n-- \n1.5.3.GIT\n"},{"id":"49981","messageId":"37994.1480620348$1186374889@news.gmane.org","threadId":"9401","inReplyTo":"11863748422754-git-send-email-","subject":"[PATCH 3/5] user-manual: mention git-gui","fromName":"J. Bruce Fields","fromEmail":"bfields@citi.umich.edu","sentAt":"2007-08-06T04:34:00Z","receivedAt":"2007-08-06T04:34:00Z","isPatch":true,"sender":{"key":"bfields@citi.umich.edu","avatar":null},"body":"From: J. Bruce Fields <bfields@pig.linuxdev.us.dell.com>\n\nThe git gui project seems to be still in early stages, but at a point\nwhere it's worth mentioning as an alternative way of creating commits.\n\nOne feature of interest is the ability to manipulate individual diff\nhunks.  However, people have found that feature not to be easily\ndiscoverable from the user-interface.  Pending some ui improvements, a\nparenthetical hint here may help.\n\n(Thanks to Steffen Prohask and Junio Hamano for suggesting the\nlanguage.)\n\nSigned-off-by: J. Bruce Fields <bfields@citi.umich.edu>\n---\n Documentation/user-manual.txt |   11 +++++++++--\n 1 files changed, 9 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\nindex 9efe85c..f89952a 100644\n--- a/Documentation/user-manual.txt\n+++ b/Documentation/user-manual.txt\n@@ -1079,6 +1079,11 @@ $ git diff HEAD\t    # difference between HEAD and working tree; what\n $ git status\t    # a brief per-file summary of the above.\n -------------------------------------------------\n \n+You can also use gitlink:git-gui[1] to create commits, view changes in\n+the index and the working tree files, and individually select diff hunks\n+for inclusion in the index (by right-clicking on the diff hunk and\n+choosing \"Stage Hunk For Commit\").\n+\n [[creating-good-commit-messages]]\n Creating good commit messages\n -----------------------------\n@@ -2506,8 +2511,10 @@ $ gitk origin..mywork &\n \n And browse through the list of patches in the mywork branch using gitk,\n applying them (possibly in a different order) to mywork-new using\n-cherry-pick, and possibly modifying them as you go using commit\n---amend.\n+cherry-pick, and possibly modifying them as you go using commit --amend.\n+The git-gui[1] command may also help as it allows you to individually\n+select diff hunks for inclusion in the index (by right-clicking on the\n+diff hunk and choosing \"Stage Hunk for Commit\").\n \n Another technique is to use git-format-patch to create a series of\n patches, then reset the state to before the patches:\n-- \n1.5.3.GIT\n"},{"id":"49980","messageId":"6125.06629336185$1186374888@news.gmane.org","threadId":"9401","inReplyTo":"11863748423686-git-send-email-","subject":"[PATCH 4/5] documentation: use the word \"index\" in the git-add manual page","fromName":"J. Bruce Fields","fromEmail":"bfields@citi.umich.edu","sentAt":"2007-08-06T04:34:01Z","receivedAt":"2007-08-06T04:34:01Z","isPatch":true,"sender":{"key":"bfields@citi.umich.edu","avatar":null},"body":"From: J. Bruce Fields <bfields@pig.linuxdev.us.dell.com>\n\nIt was a neat trick to show that you could introduce the git-add manual\npage without using the word \"index\", and it was certainly an improvement\nover the previous man page (which started out \"A simple wrapper for\ngit-update-index to add files to the index...\").\n\nBut it's possible to use the standard terminology without sacrificing\nuser-friendliness.  So, rewrite to use the word \"index\" when\nappropriate.\n\nSigned-off-by: J. Bruce Fields <bfields@citi.umich.edu>\n---\n Documentation/git-add.txt |   41 ++++++++++++++++++++++-------------------\n 1 files changed, 22 insertions(+), 19 deletions(-)\n\ndiff --git a/Documentation/git-add.txt b/Documentation/git-add.txt\nindex a0c9f68..37077b5 100644\n--- a/Documentation/git-add.txt\n+++ b/Documentation/git-add.txt\n@@ -3,7 +3,7 @@ git-add(1)\n \n NAME\n ----\n-git-add - Add file contents to the changeset to be committed next\n+git-add - Add file contents to the index\n \n SYNOPSIS\n --------\n@@ -11,24 +11,27 @@ SYNOPSIS\n \n DESCRIPTION\n -----------\n-All the changed file contents to be committed together in a single set\n-of changes must be \"added\" with the 'add' command before using the\n-'commit' command.  This is not only for adding new files.  Even modified\n-files must be added to the set of changes about to be committed.\n-\n-This command can be performed multiple times before a commit. The added\n-content corresponds to the state of specified file(s) at the time the\n-'add' command is used. This means the 'commit' command will not consider\n-subsequent changes to already added content if it is not added again before\n-the commit.\n-\n-The 'git status' command can be used to obtain a summary of what is included\n-for the next commit.\n-\n-This command can be used to add ignored files with `-f` (force)\n-option, but they have to be\n-explicitly and exactly specified from the command line.  File globbing\n-and recursive behaviour do not add ignored files.\n+This command adds the current content of new or modified files to the\n+index, thus staging that content for inclusion in the next commit.\n+\n+The \"index\" holds a snapshot of the content of the working tree, and it\n+is this snapshot that is taken as the contents of the next commit.  Thus\n+after making any changes to the working directory, and before running\n+the commit command, you must use the 'add' command to add any new or\n+modified files to the index.\n+\n+This command can be performed multiple times before a commit.  It only\n+adds the content of the specified file(s) at the time the add command is\n+run; if you want subsequent changes included in the next commit, then\n+you must run 'git add' again to add the new content to the index.\n+\n+The 'git status' command can be used to obtain a summary of which\n+files have changes that are staged for the next commit.\n+\n+The 'add' command can be used to add ignored files with `-f` (force)\n+option, but they have to be explicitly and exactly specified from the\n+command line.  File globbing and recursive behaviour do not add ignored\n+files.\n \n Please see gitlink:git-commit[1] for alternative ways to add content to a\n commit.\n-- \n1.5.3.GIT\n"},{"id":"49983","messageId":"6996.37848088077$1186374891@news.gmane.org","threadId":"9401","inReplyTo":"1186374842283-git-send-email-","subject":"[PATCH 5/5] documentation: use the word \"index\" in the git-commit man page","fromName":"J. Bruce Fields","fromEmail":"bfields@citi.umich.edu","sentAt":"2007-08-06T04:34:02Z","receivedAt":"2007-08-06T04:34:02Z","isPatch":true,"sender":{"key":"bfields@citi.umich.edu","avatar":null},"body":"From: J. Bruce Fields <bfields@pig.linuxdev.us.dell.com>\n\nAs with git-add, I think previous updates to the git-commit man page did\nindeed help make it more user-friendly.  But I think the banishment of\nthe word \"index\" from the description goes too far; reinstate its use,\nto simplify some of the language slightly and smooth the transition to\nother documentation.\n\nSigned-off-by: J. Bruce Fields <bfields@citi.umich.edu>\n---\n Documentation/git-commit.txt |   28 ++++++++++++++--------------\n 1 files changed, 14 insertions(+), 14 deletions(-)\n\ndiff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt\nindex 53a7bb0..f07a330 100644\n--- a/Documentation/git-commit.txt\n+++ b/Documentation/git-commit.txt\n@@ -15,26 +15,26 @@ SYNOPSIS\n \n DESCRIPTION\n -----------\n-Use 'git commit' when you want to record your changes into the repository\n-along with a log message describing what the commit is about. All changes\n-to be committed must be explicitly identified using one of the following\n-methods:\n+Use 'git commit' to store the current contents of the index in a new\n+commit along with a log message describing the changes you have made.\n \n+The content to be added can be specified in several ways:\n 1. by using gitlink:git-add[1] to incrementally \"add\" changes to the\n-   next commit before using the 'commit' command (Note: even modified\n+   index before using the 'commit' command (Note: even modified\n    files must be \"added\");\n \n-2. by using gitlink:git-rm[1] to identify content removal for the next\n-   commit, again before using the 'commit' command;\n+2. by using gitlink:git-rm[1] to remove files from the working tree\n+   and the index, again before using the 'commit' command;\n \n-3. by directly listing files containing changes to be committed as arguments\n-   to the 'commit' command, in which cases only those files alone will be\n-   considered for the commit;\n+3. by listing files as arguments to the 'commit' command, in which\n+   case the commit will ignore changes staged in the index, and instead\n+   record the current content of the listed files;\n \n-4. by using the -a switch with the 'commit' command to automatically \"add\"\n-   changes from all known files i.e. files that have already been committed\n-   before, and to automatically \"rm\" files that have been\n-   removed from the working tree, and perform the actual commit.\n+4. by using the -a switch with the 'commit' command to automatically\n+   \"add\" changes from all known files (i.e. all files that are already\n+   listed in the index) and to automatically \"rm\" files in the index\n+   that have been removed from the working tree, and then perform the\n+   actual commit;\n \n 5. by using the --interactive switch with the 'commit' command to decide one\n    by one which files should be part of the commit, before finalizing the\n-- \n1.5.3.GIT\n"}]}