From: Junio C Hamano Date: Fri, 1 Mar 2013 18:37:40 +0000 (-0800) Subject: Merge branch 'wk/user-manual' into maint X-Git-Tag: v1.8.1.5~2 X-Git-Url: https://git.lorimer.id.au/gitweb.git/diff_plain/1d38c6971dd1a4b054d90b7ae4c9de5400b9d818?ds=inline;hp=-c Merge branch 'wk/user-manual' into maint * wk/user-manual: user-manual: Flesh out uncommitted changes and submodule updates user-manual: Use request-pull to generate "please pull" text user-manual: Reorganize the reroll sections, adding 'git rebase -i' --- 1d38c6971dd1a4b054d90b7ae4c9de5400b9d818 diff --combined Documentation/user-manual.txt index 20e5b4216d,bb03bc88b8..988c13ff4c --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@@ -2004,10 -2004,9 +2004,10 @@@ handling this case Note that the target of a "push" is normally a <> repository. You can also push to a -repository that has a checked-out working tree, but the working tree -will not be updated by the push. This may lead to unexpected results if -the branch you push to is the currently checked-out branch! +repository that has a checked-out working tree, but a push to update the +currently checked-out branch is denied by default to prevent confusion. +See the description of the receive.denyCurrentBranch option +in linkgit:git-config[1] for details. As with `git fetch`, you may also set up configuration options to save typing; so, for example: @@@ -2306,17 -2305,13 +2306,13 @@@ branch and then merge into each of the these changes, just apply directly to the "release" branch, and then merge that into the "test" branch. - To create diffstat and shortlog summaries of changes to include in a "please - pull" request to Linus you can use: + After pushing your work to `mytree`, you can use + linkgit:git-request-pull[1] to prepare a "please pull" request message + to send to Linus: ------------------------------------------------- - $ git diff --stat origin..release - ------------------------------------------------- - - and - - ------------------------------------------------- - $ git log -p origin..release | git shortlog + $ git push mytree + $ git request-pull origin mytree release ------------------------------------------------- Here are some of the scripts that simplify all this even further. @@@ -2557,6 -2552,12 +2553,12 @@@ return mywork to the state it had befor $ git rebase --abort ------------------------------------------------- + If you need to reorder or edit a number of commits in a branch, it may + be easier to use `git rebase -i`, which allows you to reorder and + squash commits, as well as marking them for individual editing during + the rebase. See <> for details, and + <> for alternatives. + [[rewriting-one-commit]] Rewriting a single commit ------------------------- @@@ -2570,72 -2571,89 +2572,89 @@@ $ git commit --amen which will replace the old commit by a new commit incorporating your changes, giving you a chance to edit the old commit message first. + This is useful for fixing typos in your last commit, or for adjusting + the patch contents of a poorly staged commit. - You can also use a combination of this and linkgit:git-rebase[1] to - replace a commit further back in your history and recreate the - intervening changes on top of it. First, tag the problematic commit - with + If you need to amend commits from deeper in your history, you can + use <>. - ------------------------------------------------- - $ git tag bad mywork~5 - ------------------------------------------------- - - (Either gitk or `git log` may be useful for finding the commit.) + [[reordering-patch-series]] + Reordering or selecting from a patch series + ------------------------------------------- - Then check out that commit, edit it, and rebase the rest of the series - on top of it (note that we could check out the commit on a temporary - branch, but instead we're using a <>): + Sometimes you want to edit a commit deeper in your history. One + approach is to use `git format-patch` to create a series of patches + and then reset the state to before the patches: ------------------------------------------------- - $ git checkout bad - $ # make changes here and update the index - $ git commit --amend - $ git rebase --onto HEAD bad mywork + $ git format-patch origin + $ git reset --hard origin ------------------------------------------------- - When you're done, you'll be left with mywork checked out, with the top - patches on mywork reapplied on top of your modified commit. You can - then clean up with + Then modify, reorder, or eliminate patches as needed before applying + them again with linkgit:git-am[1]: ------------------------------------------------- - $ git tag -d bad + $ git am *.patch ------------------------------------------------- - Note that the immutable nature of git history means that you haven't really - "modified" existing commits; instead, you have replaced the old commits with - new commits having new object names. + [[interactive-rebase]] + Using interactive rebases + ------------------------- - [[reordering-patch-series]] - Reordering or selecting from a patch series - ------------------------------------------- + You can also edit a patch series with an interactive rebase. This is + the same as <>, so use whichever interface you like best. - Given one existing commit, the linkgit:git-cherry-pick[1] command - allows you to apply the change introduced by that commit and create a - new commit that records it. So, for example, if "mywork" points to a - series of patches on top of "origin", you might do something like: + Rebase your current HEAD on the last commit you want to retain as-is. + For example, if you want to reorder the last 5 commits, use: ------------------------------------------------- - $ git checkout -b mywork-new origin - $ gitk origin..mywork & + $ git rebase -i HEAD~5 ------------------------------------------------- - 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 `git commit --amend`. - The linkgit: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: + This will open your editor with a list of steps to be taken to perform + your rebase. ------------------------------------------------- - $ git format-patch origin - $ git reset --hard origin - ------------------------------------------------- + pick deadbee The oneline of this commit + pick fa1afe1 The oneline of the next commit + ... - Then modify, reorder, or eliminate patches as preferred before applying - them again with linkgit:git-am[1]. + # Rebase c0ffeee..deadbee onto c0ffeee + # + # Commands: + # p, pick = use commit + # r, reword = use commit, but edit the commit message + # e, edit = use commit, but stop for amending + # s, squash = use commit, but meld into previous commit + # f, fixup = like "squash", but discard this commit's log message + # x, exec = run command (the rest of the line) using shell + # + # These lines can be re-ordered; they are executed from top to bottom. + # + # If you remove a line here THAT COMMIT WILL BE LOST. + # + # However, if you remove everything, the rebase will be aborted. + # + # Note that empty commits are commented out + ------------------------------------------------- + + As explained in the comments, you can reorder commits, squash them + together, edit commit messages, etc. by editing the list. Once you + are satisfied, save the list and close your editor, and the rebase + will begin. + + The rebase will stop where `pick` has been replaced with `edit` or + when a step in the list fails to mechanically resolve conflicts and + needs your help. When you are done editing and/or resolving conflicts + you can continue with `git rebase --continue`. If you decide that + things are getting too hairy, you can always bail out with `git rebase + --abort`. Even after the rebase is complete, you can still recover + the original branch by using the <>. + + For a more detailed discussion of the procedure and additional tips, + see the "INTERACTIVE MODE" section of linkgit:git-rebase[1]. [[patch-series-tools]] Other tools @@@ -3721,7 -3739,9 +3740,9 @@@ module NOTE: The changes are still visible in the submodule's reflog. - This is not the case if you did not commit your changes. + If you have uncommitted changes in your submodule working tree, `git + submodule update` will not overwrite them. Instead, you get the usual + warning about not being able switch from a dirty branch. [[low-level-operations]] Low-level git operations