{"thread":{"id":"22117","subject":"[NON-PATCH 3/2] Documentation/git-merge: format full commands in typewriter font","startedAt":"2010-01-07T17:03:26Z","lastAt":"2010-01-23T22:48:40Z","messageCount":46,"participants":["Thomas Rast","Junio C Hamano","Jonathan Nieder","Petr Baudis"],"isPatch":true,"patchVersion":1,"patchTotal":2},"messages":[{"id":"131008","messageId":"2e53c91e536e1ff585bc7464c1b8863e6cc45c45.1262883414.git.trast@student.ethz.ch","threadId":"22117","inReplyTo":null,"subject":"[PATCH 1/2] Documentation/git-merge: reword references to \"remote\" and \"pull\"","fromName":"Thomas Rast","fromEmail":"trast@student.ethz.ch","sentAt":"2010-01-07T17:03:26Z","receivedAt":"2010-01-07T17:03:26Z","isPatch":true,"sender":{"key":"tr@thomasrast.ch","avatar":"https://avatars.githubusercontent.com/u/153510?v=4"},"body":"The git-merge manpage was written in terms of merging a \"remote\",\nwhich is no longer the case: you merge local or remote-tracking\nbranches; pull is for actual remotes.\n\nAdjust the manpage accordingly. We refer to the arguments as\n\"commits\", and change instances of \"remote\" to \"other\" (where branches\nare concerned) or \"theirs\" (where conflict sides are concerned).\nRemove the single reference to \"pulling\".\n\nSigned-off-by: Thomas Rast \n---\n\nOut of sheer curiosity:\n\n The git-merge manpage was written in terms of merging a \"remote\",\n which is no longer the case\n\nWas this ever the case? Or is it just stale terminology?\n\n\n Documentation/git-merge.txt | 32 ++++++++++++++++----------------\n 1 files changed, 16 insertions(+), 16 deletions(-)\n\ndiff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt\nindex e886c2e..7dbde7a 100644\n--- a/Documentation/git-merge.txt\n+++ b/Documentation/git-merge.txt\n@@ -10,17 +10,17 @@ SYNOPSIS\n --------\n [verse]\n 'git merge' [-n] [--stat] [--no-commit] [--squash] [-s ]...\n-\t[-m ] ...\n-'git merge' HEAD ...\n+\t[-m ] ...\n+'git merge' HEAD ...\n \n DESCRIPTION\n -----------\n-This is the top-level interface to the merge machinery\n-which drives multiple merge strategy scripts.\n+Merges the history specified by into HEAD, optionally using a\n+specific merge strategy.\n \n-The second syntax ( `HEAD` ) is supported for\n+The second syntax ( `HEAD` ...) is supported for\n historical reasons. Do not use it from the command line or in\n-new scripts. It is the same as `git merge -m `.\n+new scripts. It is the same as `git merge -m ...`.\n \n \n OPTIONS\n@@ -33,10 +33,10 @@ include::merge-options.txt[]\n \tused to give a good default for automated 'git merge'\n \tinvocations.\n \n-...::\n-\tOther branch heads to merge into our branch. You need at\n-\tleast one . Specifying more than one \n-\tobviously means you are trying an Octopus.\n+...::\n+\tCommits, usually other branch heads, to merge into our branch.\n+\tYou need at least one . Specifying more than one\n+\t obviously means you are trying an Octopus.\n \n include::merge-strategies.txt[]\n \n@@ -96,8 +96,8 @@ file matches exactly the current `HEAD` commit; otherwise we\n will write out your local changes already registered in your\n index file along with the merge result, which is not good.\n Because 1. involves only those paths differing between your\n-branch and the remote branch you are pulling from during the\n-merge (which is typically a fraction of the whole tree), you can\n+branch and the branch you are merging\n+(which is typically a fraction of the whole tree), you can\n have local modifications in your working tree as long as they do\n not overlap with what the merge updates.\n \n@@ -110,7 +110,7 @@ When there are conflicts, the following happens:\n \n 3. For conflicting paths, the index file records up to three\n versions; stage1 stores the version from the common ancestor,\n- stage2 from `HEAD`, and stage3 from the remote branch (you\n+ stage2 from `HEAD`, and stage3 from the other branch (you\n can inspect the stages with `git ls-files -u`). The working\n tree files contain the result of the \"merge\" program; i.e. 3-way\n merge results with familiar conflict markers `<<< === >>>`.\n@@ -202,15 +202,15 @@ You can work through the conflict with a number of tools:\n mergetool which will work you through the merge.\n \n * Look at the diffs. 'git diff' will show a three-way diff,\n- highlighting changes from both the HEAD and remote versions.\n+ highlighting changes from both the HEAD and 'theirs' versions.\n \n * Look at the diffs on their own. 'git log --merge -p '\n will show diffs first for the HEAD version and then the\n- remote version.\n+ 'theirs' version.\n \n * Look at the originals. 'git show :1:filename' shows the\n common ancestor, 'git show :2:filename' shows the HEAD\n- version and 'git show :3:filename' shows the remote version.\n+ version and 'git show :3:filename' shows 'their' version.\n \n \n EXAMPLES\n-- \n1.6.6.202.gdf32a\n"},{"id":"131009","messageId":"c2893e026e8180d5e990277e3f91f560e81ea452.1262883414.git.trast@student.ethz.ch","threadId":"22117","inReplyTo":"2e53c91e536e1ff585bc7464c1b8863e6cc45c45.1262883414.git.trast@student.ethz.ch","subject":"[PATCH 2/2] Documentation: warn prominently against merging with dirty trees","fromName":"Thomas Rast","fromEmail":"trast@student.ethz.ch","sentAt":"2010-01-07T17:03:27Z","receivedAt":"2010-01-07T17:03:27Z","isPatch":true,"sender":{"key":"tr@thomasrast.ch","avatar":"https://avatars.githubusercontent.com/u/153510?v=4"},"body":"We do this for both git-merge and git-pull, so as to hopefully alert\n(over)users of git-pull to the issue.\n\nSigned-off-by: Thomas Rast \n---\n Documentation/git-merge.txt | 4 ++++\n Documentation/git-pull.txt | 4 ++++\n 2 files changed, 8 insertions(+), 0 deletions(-)\n\ndiff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt\nindex 7dbde7a..b224daf 100644\n--- a/Documentation/git-merge.txt\n+++ b/Documentation/git-merge.txt\n@@ -22,6 +22,10 @@ The second syntax ( `HEAD` ...) is supported for\n historical reasons. Do not use it from the command line or in\n new scripts. It is the same as `git merge -m ...`.\n \n+*Warning*: Running 'git-merge' with uncommitted changes is\n+discouraged: while possible, it leaves you in a state that is hard to\n+back out of in the case of a conflict.\n+\n \n OPTIONS\n -------\ndiff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt\nindex b932011..b3fa312 100644\n--- a/Documentation/git-pull.txt\n+++ b/Documentation/git-pull.txt\n@@ -24,6 +24,10 @@ when merging local branches into the current branch.\n Also note that options meant for 'git-pull' itself and underlying\n 'git-merge' must be given before the options meant for 'git-fetch'.\n \n+*Warning*: Running 'git-pull' (actually, the underlying 'git-merge')\n+with uncommitted changes is discouraged: while possible, it leaves you\n+in a state that is hard to back out of in the case of a conflict.\n+\n OPTIONS\n -------\n \n-- \n1.6.6.202.gdf32a\n"},{"id":"131007","messageId":"ebbb4e2b0e98490a64b3cd52c33d3a995fa7e980.1262883414.git.trast@student.ethz.ch","threadId":"22117","inReplyTo":"2e53c91e536e1ff585bc7464c1b8863e6cc45c45.1262883414.git.trast@student.ethz.ch","subject":"[NON-PATCH 3/2] Documentation/git-merge: format full commands in typewriter font","fromName":"Thomas Rast","fromEmail":"trast@student.ethz.ch","sentAt":"2010-01-07T17:03:28Z","receivedAt":"2010-01-07T17:03:28Z","isPatch":true,"sender":{"key":"tr@thomasrast.ch","avatar":"https://avatars.githubusercontent.com/u/153510?v=4"},"body":"Use `code snippet` style instead of 'emphasis' for the full commands\nspecified in the \"how to resolve conflicts\" section.\n\nSigned-off-by: Thomas Rast \n---\n\nNot intended for application, but for discussion.\n\nI originally wanted to tack this on the series as an \"obvious\ncleanup\", but then I noticed two things:\n\n* While the general trend as per\n\n git grep '`git '\n git grep \\''git '\n\n seems to go towards the `code` style where full commands are\n concerned, and the 'emphasis' where only a git-command is named,\n this is not consistent yet. Especially the git-svn manpage seems to\n have a few hybrids.\n\n* More importantly, while `code` style seems to be an improvement in\n HTML output (because it gives typewriter font), my local 'man'\n renders 'emphasis' as underlines -- which actually makes the code\n snippets much more visible than `literal` quotes which are not\n rendered specially at all.\n\nSo which way should it be changed?\n\n\n Documentation/git-merge.txt | 14 +++++++-------\n 1 files changed, 7 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt\nindex b224daf..e04c800 100644\n--- a/Documentation/git-merge.txt\n+++ b/Documentation/git-merge.txt\n@@ -193,7 +193,7 @@ After seeing a conflict, you can do two things:\n \n * Decide not to merge. The only clean-ups you need are to reset\n the index file to the `HEAD` commit to reverse 2. and to clean\n- up working tree changes made by 2. and 3.; 'git-reset --hard' can\n+ up working tree changes made by 2. and 3.; `git-reset --hard` can\n be used for this.\n \n * Resolve the conflicts. Git will mark the conflicts in\n@@ -202,19 +202,19 @@ After seeing a conflict, you can do two things:\n \n You can work through the conflict with a number of tools:\n \n- * Use a mergetool. 'git mergetool' to launch a graphical\n+ * Use a mergetool. `git mergetool` to launch a graphical\n mergetool which will work you through the merge.\n \n- * Look at the diffs. 'git diff' will show a three-way diff,\n+ * Look at the diffs. `git diff` will show a three-way diff,\n highlighting changes from both the HEAD and 'theirs' versions.\n \n- * Look at the diffs on their own. 'git log --merge -p '\n+ * Look at the diffs on their own. `git log --merge -p `\n will show diffs first for the HEAD version and then the\n 'theirs' version.\n \n- * Look at the originals. 'git show :1:filename' shows the\n- common ancestor, 'git show :2:filename' shows the HEAD\n- version and 'git show :3:filename' shows 'their' version.\n+ * Look at the originals. `git show :1:filename` shows the\n+ common ancestor, `git show :2:filename` shows the HEAD\n+ version and `git show :3:filename` shows 'their' version.\n \n \n EXAMPLES\n-- \n1.6.6.202.gdf32a\n"},{"id":"131024","messageId":"7vaawp4wvz.fsf@alter.siamese.dyndns.org","threadId":"22117","inReplyTo":"2e53c91e536e1ff585bc7464c1b8863e6cc45c45.1262883414.git.trast@student.ethz.ch","subject":"Re: [PATCH 1/2] Documentation/git-merge: reword references to \"remote\" and \"pull\"","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-01-07T18:01:36Z","receivedAt":"2010-01-07T18:01:36Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Thomas Rast writes:\n\n> The git-merge manpage was written in terms of merging a \"remote\",\n> which is no longer the case: you merge local or remote-tracking\n> branches; pull is for actual remotes.\n>\n> Adjust the manpage accordingly. We refer to the arguments as\n> \"commits\", and change instances of \"remote\" to \"other\" (where branches\n> are concerned) or \"theirs\" (where conflict sides are concerned).\n> Remove the single reference to \"pulling\".\n>\n> Signed-off-by: Thomas Rast \n> ---\n\nLooks sensible, modulo a few \"'theirs' version\" that I think should simply\nbe \"their version\".\n\n> Out of sheer curiosity:\n>\n> The git-merge manpage was written in terms of merging a \"remote\",\n> which is no longer the case\n>\n> Was this ever the case? Or is it just stale terminology?\n\nSomewhere in between stale and lax. Originally we didn't even have\nrefs/remotes hierarchy and the distinction between what's local and what's\nremote was only in the user's head, and \"one branch per repository\"\n(i.e. you do local clone to work on multiple things, and pull between\nthem), where even a topic-branch merge is to merge a commit from a remote\n(= neighbouring repository of your own), was a more widely practiced\nworkflow.\n\nSaying is much more correct than (technically it can\neven be a , i.e. a tag that peels to a commit).\n\nHowever...\n\n> @@ -33,10 +33,10 @@ include::merge-options.txt[]\n> \tused to give a good default for automated 'git merge'\n> \tinvocations.\n> \n> -...::\n> -\tOther branch heads to merge into our branch. You need at\n> -\tleast one . Specifying more than one \n> -\tobviously means you are trying an Octopus.\n> +...::\n> +\tCommits, usually other branch heads, to merge into our branch.\n> +\tYou need at least one . Specifying more than one\n> +\t obviously means you are trying an Octopus.\n\nI am tempted to suggest describing the command in terms of more common use\npattern, describing the flexible and more general form as \"an aside\" for\nmore advanced users, perhaps like this.\n\n ...:\n Other branch to merge into the current branch...trying an\n Octopus merge.\n +\n Strictly speaking, these can name arbitrary commits, not necessarily\n at the tip of branches. e.g. \"git merge topic{tilde}4\" lets you merge\n the topic except for the last 4 commits.\n\nI don't know if such an arrangement really makes the document more\napproachable to new people, or it is making the description longer and\nmore complicated without helping new people, though (that is why this is\njust \"I am tempted to\").\n"},{"id":"131036","messageId":"20100107202513.GA4573@progeny.tock","threadId":"22117","inReplyTo":"ebbb4e2b0e98490a64b3cd52c33d3a995fa7e980.1262883414.git.trast@student.ethz.ch","subject":"Re: [NON-PATCH 3/2] Documentation/git-merge: format full commands in typewriter font","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-01-07T20:25:13Z","receivedAt":"2010-01-07T20:25:13Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Thomas Rast wrote:\n\n> * More importantly, while `code` style seems to be an improvement in\n> HTML output (because it gives typewriter font), my local 'man'\n> renders 'emphasis' as underlines -- which actually makes the code\n> snippets much more visible than `literal` quotes which are not\n> rendered specially at all.\n\nMaybe some point in the asciidoc/docbook-xsl/nroff chain could be\nconvinced to render `literal` quotes underlined on the console.\n\nJonathan\n"},{"id":"131037","messageId":"7v3a2h39nt.fsf@alter.siamese.dyndns.org","threadId":"22117","inReplyTo":"ebbb4e2b0e98490a64b3cd52c33d3a995fa7e980.1262883414.git.trast@student.ethz.ch","subject":"Re: [NON-PATCH 3/2] Documentation/git-merge: format full commands in typewriter font","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-01-07T21:08:38Z","receivedAt":"2010-01-07T21:08:38Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Thomas Rast writes:\n\n> * More importantly, while `code` style seems to be an improvement in\n> HTML output (because it gives typewriter font), my local 'man'\n> renders 'emphasis' as underlines -- which actually makes the code\n> snippets much more visible than `literal` quotes which are not\n> rendered specially at all.\n>\n> So which way should it be changed?\n\nI'd prefer to see us mark code as `code`.\n\nThe documentation toolchain may hopefully be fixed in the upstream in the\nfuture, and we could keep our local style tweaks in Documentation/ until\nthat happens if we really wanted to.\n"},{"id":"131192","messageId":"cover.1263081032.git.trast@student.ethz.ch","threadId":"22117","inReplyTo":"7vaawp4wvz.fsf@alter.siamese.dyndns.org","subject":"[PATCH v2 0/4] Documentation style fixes","fromName":"Thomas Rast","fromEmail":"trast@student.ethz.ch","sentAt":"2010-01-10T00:02:38Z","receivedAt":"2010-01-10T00:02:38Z","isPatch":true,"sender":{"key":"tr@thomasrast.ch","avatar":"https://avatars.githubusercontent.com/u/153510?v=4"},"body":"I'm violating the midnight rule, so there's probably something wrong\nwith this series.\n\nJunio C Hamano wrote:\n> I am tempted to suggest describing the command in terms of more common use\n> pattern, describing the flexible and more general form as \"an aside\" for\n> more advanced users, perhaps like this.\n> \n> ...:\n> Other branch to merge into the current branch...trying an\n> Octopus merge.\n> +\n> Strictly speaking, these can name arbitrary commits, not necessarily\n> at the tip of branches. e.g. \"git merge topic{tilde}4\" lets you merge\n> the topic except for the last 4 commits.\n> \n> I don't know if such an arrangement really makes the document more\n> approachable to new people, or it is making the description longer and\n> more complicated without helping new people, though (that is why this is\n> just \"I am tempted to\").\n\nNot sure. I have a bit of an aversion against \"lying\" in the\nsynopsis, even though the common use-case really is a branch.\n\n> Thomas Rast writes:\n> > * More importantly, while `code` style seems to be an improvement in\n> > HTML output (because it gives typewriter font), my local 'man'\n> > renders 'emphasis' as underlines -- which actually makes the code\n> > snippets much more visible than `literal` quotes which are not\n> > rendered specially at all.\n> >\n> > So which way should it be changed?\n> \n> I'd prefer to see us mark code as `code`.\n\nI tried to make it so, including a few other places that grep found.\n\nRegarding 'git-cmd' vs. 'git cmd', I found that we're in the somewhat\nunsatisfactory situation where the git-svn manpage uses dashless since\n647ac70 (git-svn.txt: stop using dash-form of commands., 2009-07-07).\nMost of the rest uses dashed, but there sometimes even were\ninconsistent uses very close to each other. Dashless seems to be a\nbit more common in newer patches, and does have the advantage that it\ndoes not need an exception for 'git submodule update' and friends.\n\nSo I tried to sed it towards the dashless form, with a few exceptions.\nThe churn, of course, is rather daunting. The other alternative,\nreturning to dashed forms, would mean reverting 647ac70 and then more\napplications of sed to fix the stray dashless uses, being careful to\npreserve the SYNOPSIS sections.\n\n\nThomas Rast (4):\n Documentation/git-merge: reword references to \"remote\" and \"pull\"\n Documentation: warn prominently against merging with dirty trees\n Documentation: format full commands in typewriter font\n Documentation: spell 'git cmd' without dash throughout\n\n Documentation/config.txt | 70 +++++++-------\n Documentation/fetch-options.txt | 10 +-\n Documentation/git-add.txt | 2 +-\n Documentation/git-am.txt | 10 +-\n Documentation/git-apply.txt | 10 +-\n Documentation/git-archimport.txt | 12 ++--\n Documentation/git-archive.txt | 2 +-\n Documentation/git-bisect.txt | 2 +-\n Documentation/git-blame.txt | 8 +-\n Documentation/git-branch.txt | 6 +-\n Documentation/git-bundle.txt | 26 +++---\n Documentation/git-check-ref-format.txt | 2 +-\n Documentation/git-checkout-index.txt | 8 +-\n Documentation/git-cherry-pick.txt | 2 +-\n Documentation/git-cherry.txt | 6 +-\n Documentation/git-citool.txt | 4 +-\n Documentation/git-clean.txt | 4 +-\n Documentation/git-commit-tree.txt | 2 +-\n Documentation/git-commit.txt | 18 ++--\n Documentation/git-config.txt | 14 ++--\n Documentation/git-cvsexportcommit.txt | 2 +-\n Documentation/git-cvsimport.txt | 18 ++--\n Documentation/git-cvsserver.txt | 6 +-\n Documentation/git-daemon.txt | 40 ++++----\n Documentation/git-describe.txt | 6 +-\n Documentation/git-diff-files.txt | 2 +-\n Documentation/git-diff-index.txt | 16 ++--\n Documentation/git-diff-tree.txt | 4 +-\n Documentation/git-difftool.txt | 16 ++--\n Documentation/git-fast-export.txt | 12 ++--\n Documentation/git-fast-import.txt | 20 ++--\n Documentation/git-fetch-pack.txt | 6 +-\n Documentation/git-fetch.txt | 2 +-\n Documentation/git-filter-branch.txt | 24 +++---\n Documentation/git-fmt-merge-msg.txt | 2 +-\n Documentation/git-format-patch.txt | 4 +-\n Documentation/git-fsck.txt | 4 +-\n Documentation/git-gc.txt | 18 ++--\n Documentation/git-get-tar-commit-id.txt | 4 +-\n Documentation/git-grep.txt | 2 +-\n Documentation/git-gui.txt | 20 ++--\n Documentation/git-hash-object.txt | 2 +-\n Documentation/git-help.txt | 6 +-\n Documentation/git-http-backend.txt | 22 +++---\n Documentation/git-http-fetch.txt | 2 +-\n Documentation/git-imap-send.txt | 2 +-\n Documentation/git-index-pack.txt | 8 +-\n Documentation/git-init.txt | 6 +-\n Documentation/git-log.txt | 2 +-\n Documentation/git-ls-files.txt | 4 +-\n Documentation/git-ls-tree.txt | 4 +-\n Documentation/git-mailinfo.txt | 2 +-\n Documentation/git-merge-file.txt | 10 +-\n Documentation/git-merge-index.txt | 6 +-\n Documentation/git-merge-one-file.txt | 2 +-\n Documentation/git-merge.txt | 54 ++++++-----\n Documentation/git-mergetool.txt | 16 ++--\n Documentation/git-name-rev.txt | 4 +-\n Documentation/git-notes.txt | 2 +-\n Documentation/git-pack-objects.txt | 6 +-\n Documentation/git-pack-redundant.txt | 2 +-\n Documentation/git-patch-id.txt | 2 +-\n Documentation/git-peek-remote.txt | 2 +-\n Documentation/git-prune.txt | 14 ++--\n Documentation/git-pull.txt | 14 ++-\n Documentation/git-push.txt | 6 +-\n Documentation/git-read-tree.txt | 40 ++++----\n Documentation/git-rebase.txt | 38 ++++----\n Documentation/git-receive-pack.txt | 6 +-\n Documentation/git-reflog.txt | 2 +-\n Documentation/git-remote.txt | 2 +-\n Documentation/git-repack.txt | 10 +-\n Documentation/git-replace.txt | 2 +-\n Documentation/git-rerere.txt | 26 +++---\n Documentation/git-reset.txt | 2 +-\n Documentation/git-rev-list.txt | 6 +-\n Documentation/git-rev-parse.txt | 30 +++---\n Documentation/git-revert.txt | 8 +-\n Documentation/git-send-pack.txt | 4 +-\n Documentation/git-sh-setup.txt | 2 +-\n Documentation/git-shortlog.txt | 4 +-\n Documentation/git-show-index.txt | 2 +-\n Documentation/git-show-ref.txt | 4 +-\n Documentation/git-show.txt | 4 +-\n Documentation/git-stash.txt | 8 +-\n Documentation/git-status.txt | 2 +-\n Documentation/git-submodule.txt | 8 +-\n Documentation/git-symbolic-ref.txt | 2 +-\n Documentation/git-tag.txt | 6 +-\n Documentation/git-tar-tree.txt | 4 +-\n Documentation/git-update-index.txt | 14 ++--\n Documentation/git-upload-archive.txt | 2 +-\n Documentation/git-upload-pack.txt | 8 +-\n Documentation/git-var.txt | 2 +-\n Documentation/git-verify-pack.txt | 2 +-\n Documentation/git-verify-tag.txt | 2 +-\n Documentation/git-web--browse.txt | 2 +-\n Documentation/git-whatchanged.txt | 4 +-\n Documentation/git-write-tree.txt | 8 +-\n Documentation/git.txt | 8 +-\n Documentation/gitattributes.txt | 12 ++--\n Documentation/gitcore-tutorial.txt | 148 +++++++++++++++---------------\n Documentation/gitcvs-migration.txt | 10 +-\n Documentation/gitdiffcore.txt | 8 +-\n Documentation/githooks.txt | 56 ++++++------\n Documentation/gitignore.txt | 4 +-\n Documentation/gitk.txt | 2 +-\n Documentation/gitrepository-layout.txt | 16 ++--\n Documentation/gittutorial-2.txt | 16 ++--\n Documentation/gittutorial.txt | 42 +++++-----\n Documentation/gitworkflows.txt | 6 +-\n Documentation/i18n.txt | 4 +-\n Documentation/merge-options.txt | 4 +-\n Documentation/pull-fetch-param.txt | 8 +-\n Documentation/urls-remotes.txt | 4 +-\n 115 files changed, 634 insertions(+), 626 deletions(-)\n"},{"id":"131193","messageId":"57bddb115331a23816af772172531fb56fceace4.1263081032.git.trast@student.ethz.ch","threadId":"22117","inReplyTo":"cover.1263081032.git.trast@student.ethz.ch","subject":"[PATCH v2 1/4] Documentation/git-merge: reword references to \"remote\" and \"pull\"","fromName":"Thomas Rast","fromEmail":"trast@student.ethz.ch","sentAt":"2010-01-10T00:02:39Z","receivedAt":"2010-01-10T00:02:39Z","isPatch":true,"sender":{"key":"tr@thomasrast.ch","avatar":"https://avatars.githubusercontent.com/u/153510?v=4"},"body":"The git-merge manpage was written in terms of merging a \"remote\",\nwhich is no longer the case: you merge local or remote-tracking\nbranches; pull is for actual remotes.\n\nAdjust the manpage accordingly. We refer to the arguments as\n\"commits\", and change instances of \"remote\" to \"other\" (where branches\nare concerned) or \"theirs\" (where conflict sides are concerned).\nRemove the single reference to \"pulling\".\n\nSigned-off-by: Thomas Rast \n---\n Documentation/git-merge.txt | 34 +++++++++++++++++-----------------\n 1 files changed, 17 insertions(+), 17 deletions(-)\n\ndiff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt\nindex e886c2e..4896587 100644\n--- a/Documentation/git-merge.txt\n+++ b/Documentation/git-merge.txt\n@@ -10,17 +10,17 @@ SYNOPSIS\n --------\n [verse]\n 'git merge' [-n] [--stat] [--no-commit] [--squash] [-s ]...\n-\t[-m ] ...\n-'git merge' HEAD ...\n+\t[-m ] ...\n+'git merge' HEAD ...\n \n DESCRIPTION\n -----------\n-This is the top-level interface to the merge machinery\n-which drives multiple merge strategy scripts.\n+Merges the history specified by into HEAD, optionally using a\n+specific merge strategy.\n \n-The second syntax ( `HEAD` ) is supported for\n+The second syntax ( `HEAD` ...) is supported for\n historical reasons. Do not use it from the command line or in\n-new scripts. It is the same as `git merge -m `.\n+new scripts. It is the same as `git merge -m ...`.\n \n \n OPTIONS\n@@ -33,10 +33,10 @@ include::merge-options.txt[]\n \tused to give a good default for automated 'git merge'\n \tinvocations.\n \n-...::\n-\tOther branch heads to merge into our branch. You need at\n-\tleast one . Specifying more than one \n-\tobviously means you are trying an Octopus.\n+...::\n+\tCommits, usually other branch heads, to merge into our branch.\n+\tYou need at least one . Specifying more than one\n+\t obviously means you are trying an Octopus.\n \n include::merge-strategies.txt[]\n \n@@ -96,8 +96,8 @@ file matches exactly the current `HEAD` commit; otherwise we\n will write out your local changes already registered in your\n index file along with the merge result, which is not good.\n Because 1. involves only those paths differing between your\n-branch and the remote branch you are pulling from during the\n-merge (which is typically a fraction of the whole tree), you can\n+branch and the branch you are merging\n+(which is typically a fraction of the whole tree), you can\n have local modifications in your working tree as long as they do\n not overlap with what the merge updates.\n \n@@ -110,7 +110,7 @@ When there are conflicts, the following happens:\n \n 3. For conflicting paths, the index file records up to three\n versions; stage1 stores the version from the common ancestor,\n- stage2 from `HEAD`, and stage3 from the remote branch (you\n+ stage2 from `HEAD`, and stage3 from the other branch (you\n can inspect the stages with `git ls-files -u`). The working\n tree files contain the result of the \"merge\" program; i.e. 3-way\n merge results with familiar conflict markers `<<< === >>>`.\n@@ -202,15 +202,15 @@ You can work through the conflict with a number of tools:\n mergetool which will work you through the merge.\n \n * Look at the diffs. 'git diff' will show a three-way diff,\n- highlighting changes from both the HEAD and remote versions.\n+ highlighting changes from both the HEAD and their versions.\n \n * Look at the diffs on their own. 'git log --merge -p '\n- will show diffs first for the HEAD version and then the\n- remote version.\n+ will show diffs first for the HEAD version and then\n+ their version.\n \n * Look at the originals. 'git show :1:filename' shows the\n common ancestor, 'git show :2:filename' shows the HEAD\n- version and 'git show :3:filename' shows the remote version.\n+ version and 'git show :3:filename' shows their version.\n \n \n EXAMPLES\n-- \n1.6.6.218.g502b0\n"},{"id":"131195","messageId":"e330d8ca1a9ec38ce40b0f67123b1dd893f0b31c.1263081032.git.trast@student.ethz.ch","threadId":"22117","inReplyTo":"cover.1263081032.git.trast@student.ethz.ch","subject":"[PATCH v2 2/4] Documentation: warn prominently against merging with dirty trees","fromName":"Thomas Rast","fromEmail":"trast@student.ethz.ch","sentAt":"2010-01-10T00:02:40Z","receivedAt":"2010-01-10T00:02:40Z","isPatch":true,"sender":{"key":"tr@thomasrast.ch","avatar":"https://avatars.githubusercontent.com/u/153510?v=4"},"body":"We do this for both git-merge and git-pull, so as to hopefully alert\n(over)users of git-pull to the issue.\n\nSigned-off-by: Thomas Rast \n---\n Documentation/git-merge.txt | 4 ++++\n Documentation/git-pull.txt | 4 ++++\n 2 files changed, 8 insertions(+), 0 deletions(-)\n\ndiff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt\nindex 4896587..3277f4e 100644\n--- a/Documentation/git-merge.txt\n+++ b/Documentation/git-merge.txt\n@@ -22,6 +22,10 @@ The second syntax ( `HEAD` ...) is supported for\n historical reasons. Do not use it from the command line or in\n new scripts. It is the same as `git merge -m ...`.\n \n+*Warning*: Running 'git-merge' with uncommitted changes is\n+discouraged: while possible, it leaves you in a state that is hard to\n+back out of in the case of a conflict.\n+\n \n OPTIONS\n -------\ndiff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt\nindex b932011..b3fa312 100644\n--- a/Documentation/git-pull.txt\n+++ b/Documentation/git-pull.txt\n@@ -24,6 +24,10 @@ when merging local branches into the current branch.\n Also note that options meant for 'git-pull' itself and underlying\n 'git-merge' must be given before the options meant for 'git-fetch'.\n \n+*Warning*: Running 'git-pull' (actually, the underlying 'git-merge')\n+with uncommitted changes is discouraged: while possible, it leaves you\n+in a state that is hard to back out of in the case of a conflict.\n+\n OPTIONS\n -------\n \n-- \n1.6.6.218.g502b0\n"},{"id":"131194","messageId":"9d10ee6a8526dc9f9c220cc6bb4b509c8cc73b0a.1263081032.git.trast@student.ethz.ch","threadId":"22117","inReplyTo":"cover.1263081032.git.trast@student.ethz.ch","subject":"[PATCH v2 3/4] Documentation: format full commands in typewriter font","fromName":"Thomas Rast","fromEmail":"trast@student.ethz.ch","sentAt":"2010-01-10T00:02:41Z","receivedAt":"2010-01-10T00:02:41Z","isPatch":true,"sender":{"key":"tr@thomasrast.ch","avatar":"https://avatars.githubusercontent.com/u/153510?v=4"},"body":"Use `code snippet` style instead of 'emphasis' for `git cmd ...`\naccording to the following rules:\n\n* The SYNOPSIS sections are left untouched.\n\n* If the intent is that the user type the command exactly as given, it\n is `code`.\n If the user is only loosely referred to a command and/or option, it\n remains 'emphasised'.\n\nSigned-off-by: Thomas Rast \n---\n Documentation/config.txt | 12 ++++++------\n Documentation/git-add.txt | 2 +-\n Documentation/git-bisect.txt | 2 +-\n Documentation/git-cvsserver.txt | 2 +-\n Documentation/git-filter-branch.txt | 6 +++---\n Documentation/git-ls-tree.txt | 4 ++--\n Documentation/git-merge.txt | 14 +++++++-------\n Documentation/git-replace.txt | 2 +-\n Documentation/git-revert.txt | 4 ++--\n Documentation/git-stash.txt | 2 +-\n Documentation/git-submodule.txt | 4 ++--\n Documentation/git-var.txt | 2 +-\n 12 files changed, 28 insertions(+), 28 deletions(-)\n\ndiff --git a/Documentation/config.txt b/Documentation/config.txt\nindex 23a965e..6bfd9e1 100644\n--- a/Documentation/config.txt\n+++ b/Documentation/config.txt\n@@ -741,15 +741,15 @@ diff.mnemonicprefix::\n \tstandard \"a/\" and \"b/\" depending on what is being compared. When\n \tthis configuration is in effect, reverse diff output also swaps\n \tthe order of the prefixes:\n-'git-diff';;\n+`git diff`;;\n \tcompares the (i)ndex and the (w)ork tree;\n-'git-diff HEAD';;\n+`git diff HEAD`;;\n \t compares a (c)ommit and the (w)ork tree;\n-'git diff --cached';;\n+`git diff --cached`;;\n \tcompares a (c)ommit and the (i)ndex;\n-'git-diff HEAD:file1 file2';;\n+`git-diff HEAD:file1 file2`;;\n \tcompares an (o)bject and a (w)ork tree entity;\n-'git diff --no-index a b';;\n+`git diff --no-index a b`;;\n \tcompares two non-git things (1) and (2).\n \n diff.renameLimit::\n@@ -1015,7 +1015,7 @@ gui.spellingdictionary::\n \toff.\n \n gui.fastcopyblame::\n-\tIf true, 'git gui blame' uses '-C' instead of '-C -C' for original\n+\tIf true, 'git gui blame' uses `-C` instead of `-C -C` for original\n \tlocation detection. It makes blame significantly faster on huge\n \trepositories at the expense of less thorough copy detection.\n \ndiff --git a/Documentation/git-add.txt b/Documentation/git-add.txt\nindex 1f1b199..f74fcf3 100644\n--- a/Documentation/git-add.txt\n+++ b/Documentation/git-add.txt\n@@ -39,7 +39,7 @@ The `git add` command will not add ignored files by default. If any\n ignored files were explicitly specified on the command line, `git add`\n will fail with a list of ignored files. Ignored files reached by\n directory recursion or filename globbing performed by Git (quote your\n-globs before the shell) will be silently ignored. The `add` command can\n+globs before the shell) will be silently ignored. The 'git add' command can\n be used to add ignored files with the `-f` (force) option.\n \n Please see linkgit:git-commit[1] for alternative ways to add content to a\ndiff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt\nindex c39d957..f91c7ac 100644\n--- a/Documentation/git-bisect.txt\n+++ b/Documentation/git-bisect.txt\n@@ -26,7 +26,7 @@ on the subcommand:\n git bisect log\n git bisect run ...\n \n-This command uses 'git rev-list --bisect' to help drive the\n+This command uses `git rev-list --bisect` to help drive the\n binary search process to find which change introduced a bug, given an\n old \"good\" commit object name and a later \"bad\" commit object name.\n \ndiff --git a/Documentation/git-cvsserver.txt b/Documentation/git-cvsserver.txt\nindex 99a7c14..19b1daf 100644\n--- a/Documentation/git-cvsserver.txt\n+++ b/Documentation/git-cvsserver.txt\n@@ -294,7 +294,7 @@ To get a checkout with the Eclipse CVS client:\n Protocol notes: If you are using anonymous access via pserver, just select that.\n Those using SSH access should choose the 'ext' protocol, and configure 'ext'\n access on the Preferences->Team->CVS->ExtConnection pane. Set CVS_SERVER to\n-\"'git cvsserver'\". Note that password support is not good when using 'ext',\n+\"`git cvsserver`\". Note that password support is not good when using 'ext',\n you will definitely want to have SSH keys setup.\n \n Alternatively, you can just use the non-standard extssh protocol that Eclipse\ndiff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt\nindex 394a77a..544836a 100644\n--- a/Documentation/git-filter-branch.txt\n+++ b/Documentation/git-filter-branch.txt\n@@ -129,8 +129,8 @@ convenience functions, too. For example, calling 'skip_commit \"$@\"'\n will leave out the current commit (but not its changes! If you want\n that, use 'git-rebase' instead).\n +\n-You can also use the 'git_commit_non_empty_tree \"$@\"' instead of\n-'git commit-tree \"$@\"' if you don't wish to keep commits with a single parent\n+You can also use the `git_commit_non_empty_tree \"$@\"` instead of\n+`git commit-tree \"$@\"` if you don't wish to keep commits with a single parent\n and that makes no change to the tree.\n \n --tag-name-filter ::\n@@ -179,7 +179,7 @@ the nearest ancestor that was not excluded.\n \tand only one parent, it will hence keep merges points. Also, this\n \toption is not compatible with the use of '--commit-filter'. Though you\n \tjust need to use the function 'git_commit_non_empty_tree \"$@\"' instead\n-\tof the 'git commit-tree \"$@\"' idiom in your commit filter to make that\n+\tof the `git commit-tree \"$@\"` idiom in your commit filter to make that\n \thappen.\n \n --original ::\ndiff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt\nindex c3fdccb..1f89d36 100644\n--- a/Documentation/git-ls-tree.txt\n+++ b/Documentation/git-ls-tree.txt\n@@ -28,7 +28,7 @@ in the current working directory. Note that:\n in a directory 'sub' that has a directory 'dir', you can run 'git\n ls-tree -r HEAD dir' to list the contents of the tree (that is\n 'sub/dir' in 'HEAD'). You don't want to give a tree that is not at the\n- root level (e.g. 'git ls-tree -r HEAD:sub dir') in this case, as that\n+ root level (e.g. `git ls-tree -r HEAD:sub dir`) in this case, as that\n would result in asking for 'sub/sub/dir' in the 'HEAD' commit.\n However, the current working directory can be ignored by passing\n --full-tree option.\n@@ -84,7 +84,7 @@ Output Format\n \n Unless the `-z` option is used, TAB, LF, and backslash characters\n in pathnames are represented as `\\t`, `\\n`, and `\\\\`, respectively.\n-This output format is compatible with what '--index-info --stdin' of\n+This output format is compatible with what `--index-info --stdin` of\n 'git update-index' expects.\n \n When the `-l` option is used, format changes to\ndiff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt\nindex 3277f4e..04c21d3 100644\n--- a/Documentation/git-merge.txt\n+++ b/Documentation/git-merge.txt\n@@ -193,7 +193,7 @@ After seeing a conflict, you can do two things:\n \n * Decide not to merge. The only clean-ups you need are to reset\n the index file to the `HEAD` commit to reverse 2. and to clean\n- up working tree changes made by 2. and 3.; 'git-reset --hard' can\n+ up working tree changes made by 2. and 3.; `git-reset --hard` can\n be used for this.\n \n * Resolve the conflicts. Git will mark the conflicts in\n@@ -202,19 +202,19 @@ After seeing a conflict, you can do two things:\n \n You can work through the conflict with a number of tools:\n \n- * Use a mergetool. 'git mergetool' to launch a graphical\n+ * Use a mergetool. `git mergetool` to launch a graphical\n mergetool which will work you through the merge.\n \n- * Look at the diffs. 'git diff' will show a three-way diff,\n+ * Look at the diffs. `git diff` will show a three-way diff,\n highlighting changes from both the HEAD and their versions.\n \n- * Look at the diffs on their own. 'git log --merge -p '\n+ * Look at the diffs on their own. `git log --merge -p `\n will show diffs first for the HEAD version and then\n their version.\n \n- * Look at the originals. 'git show :1:filename' shows the\n- common ancestor, 'git show :2:filename' shows the HEAD\n- version and 'git show :3:filename' shows their version.\n+ * Look at the originals. `git show :1:filename` shows the\n+ common ancestor, `git show :2:filename` shows the HEAD\n+ version and `git show :3:filename` shows their version.\n \n \n EXAMPLES\ndiff --git a/Documentation/git-replace.txt b/Documentation/git-replace.txt\nindex 65a0da5..fde2092 100644\n--- a/Documentation/git-replace.txt\n+++ b/Documentation/git-replace.txt\n@@ -65,7 +65,7 @@ OPTIONS\n BUGS\n ----\n Comparing blobs or trees that have been replaced with those that\n-replace them will not work properly. And using 'git reset --hard' to\n+replace them will not work properly. And using `git reset --hard` to\n go back to a replaced commit will move the branch to the replacement\n commit instead of the replaced commit.\n \ndiff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt\nindex 5e11758..36f3bc3 100644\n--- a/Documentation/git-revert.txt\n+++ b/Documentation/git-revert.txt\n@@ -20,8 +20,8 @@ effect of an earlier commit (often a faulty one). If you want to\n throw away all uncommitted changes in your working directory, you\n should see linkgit:git-reset[1], particularly the '--hard' option. If\n you want to extract specific files as they were in another commit, you\n-should see linkgit:git-checkout[1], specifically the 'git checkout\n- -- ' syntax. Take care with these alternatives as\n+should see linkgit:git-checkout[1], specifically the `git checkout\n+ -- ` syntax. Take care with these alternatives as\n both will discard uncommitted changes in your working directory.\n \n OPTIONS\ndiff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt\nindex 3f14b72..f001d0e 100644\n--- a/Documentation/git-stash.txt\n+++ b/Documentation/git-stash.txt\n@@ -20,7 +20,7 @@ SYNOPSIS\n DESCRIPTION\n -----------\n \n-Use 'git stash' when you want to record the current state of the\n+Use `git stash` when you want to record the current state of the\n working directory and the index, but want to go back to a clean\n working directory. The command saves your local modifications away\n and reverts the working directory to match the `HEAD` commit.\ndiff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\nindex 4ef70c4..68f656c 100644\n--- a/Documentation/git-submodule.txt\n+++ b/Documentation/git-submodule.txt\n@@ -114,8 +114,8 @@ init::\n \tThe key used in .git/config is `submodule.$name.url`.\n \tThis command does not alter existing information in .git/config.\n \tYou can then customize the submodule clone URLs in .git/config\n-\tfor your local setup and proceed to 'git submodule update';\n-\tyou can also just use 'git submodule update --init' without\n+\tfor your local setup and proceed to `git submodule update`;\n+\tyou can also just use `git submodule update --init` without\n \tthe explicit 'init' step if you do not intend to customize\n \tany submodule locations.\n \ndiff --git a/Documentation/git-var.txt b/Documentation/git-var.txt\nindex ef6aa81..bb98182 100644\n--- a/Documentation/git-var.txt\n+++ b/Documentation/git-var.txt\n@@ -20,7 +20,7 @@ OPTIONS\n \tCause the logical variables to be listed. In addition, all the\n \tvariables of the git configuration file .git/config are listed\n \tas well. (However, the configuration variables listing functionality\n-\tis deprecated in favor of 'git config -l'.)\n+\tis deprecated in favor of `git config -l`.)\n \n EXAMPLE\n --------\n-- \n1.6.6.218.g502b0\n"},{"id":"131196","messageId":"201001100107.29920.trast@student.ethz.ch","threadId":"22117","inReplyTo":"cover.1263081032.git.trast@student.ethz.ch","subject":"Re: [PATCH v2 0/4] Documentation style fixes","fromName":"Thomas Rast","fromEmail":"trast@student.ethz.ch","sentAt":"2010-01-10T00:07:27Z","receivedAt":"2010-01-10T00:07:27Z","isPatch":true,"sender":{"key":"tr@thomasrast.ch","avatar":"https://avatars.githubusercontent.com/u/153510?v=4"},"body":"Thomas Rast wrote:\n> Documentation: spell 'git cmd' without dash throughout\n[...]\n> 115 files changed, 634 insertions(+), 626 deletions(-)\n\nTurns out the fourth patch is over 200kB and can't be sent over the\nlist. I pushed the whole series to\n\n git://repo.or.cz/git/sbeyer.git t/doc-merge-revamp\n\n-- \nThomas Rast\ntrast@{inf,student}.ethz.ch\n"},{"id":"131197","messageId":"201001100119.03091.trast@student.ethz.ch","threadId":"22117","inReplyTo":"201001100107.29920.trast@student.ethz.ch","subject":"Re: [PATCH v2 0/4] Documentation style fixes","fromName":"Thomas Rast","fromEmail":"trast@student.ethz.ch","sentAt":"2010-01-10T00:19:01Z","receivedAt":"2010-01-10T00:19:01Z","isPatch":true,"sender":{"key":"tr@thomasrast.ch","avatar":"https://avatars.githubusercontent.com/u/153510?v=4"},"body":"Thomas Rast wrote:\n> Thomas Rast wrote:\n> > Documentation: spell 'git cmd' without dash throughout\n> [...]\n> > 115 files changed, 634 insertions(+), 626 deletions(-)\n> \n> Turns out the fourth patch is over 200kB and can't be sent over the\n> list. I pushed the whole series to\n> \n> git://repo.or.cz/git/sbeyer.git t/doc-merge-revamp\n\nAh, here's the midnight issue. That should have said\n\n git://repo.or.cz/git/trast.git t/doc-merge-revamp\n\nSorry for the noise.\n\n-- \nThomas Rast\ntrast@{inf,student}.ethz.ch\n"},{"id":"131198","messageId":"20100110025641.GB1083@progeny.tock","threadId":"22117","inReplyTo":"9516c897017ec420403bb7f687fb8962de42cb7c.1263081032.git.trast@student.ethz.ch","subject":"Re: [PATCH v2 4/4] Documentation: spell 'git cmd' without dash throughout","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-01-10T02:56:41Z","receivedAt":"2010-01-10T02:56:41Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Thomas Rast wrote:\n\n> Replace 'git-cmd' with 'git cmd' throughout, except where git-shell,\n> git-cvsserver, git-upload-pack, git-receive-pack, and\n> git-upload-archive are concerned, because those really live in the\n> $PATH.\n\nAgreed. Some forms of 'man' even support 'man git am', so the \"it's\nwhat you pass to 'man'\" excuse does not even apply any more.\n\n> 110 files changed, 584 insertions(+), 584 deletions(-)\n\nBut yikes! Did you do this by hand or by some automated process?\n\n> diff --git a/Documentation/config.txt b/Documentation/config.txt\n> index 6bfd9e1..db28408 100644\n> --- a/Documentation/config.txt\n> +++ b/Documentation/config.txt\n> @@ -64,7 +64,7 @@ The values following the equals sign in variable assign are all either\n> a string, an integer, or a boolean. Boolean values may be given as yes/no,\n> 0/1, true/false or on/off. Case is not significant in boolean values, when\n> converting value to the canonical form using '--bool' type specifier;\n> -'git-config' will ensure that the output is \"true\" or \"false\".\n> +'git config' will ensure that the output is \"true\" or \"false\".\n> \n> String values may be entirely or partially enclosed in double quotes.\n> You need to enclose variable values in double quotes if you want to\n> @@ -442,7 +442,7 @@ core.pager::\n> \n> core.whitespace::\n> \tA comma separated list of common whitespace problems to\n> -\tnotice. 'git-diff' will use `color.diff.whitespace` to\n> +\tnotice. 'git diff' will use `color.diff.whitespace` to\n> \thighlight them, and 'git-apply --whitespace=error' will\n\nA 'git-apply' snuck in. ;-)\n\n> @@ -563,24 +563,24 @@ branch.autosetuprebase::\n[...]\n> \tSpecify multiple values to get an octopus merge.\n> -\tIf you wish to setup 'git-pull' so that it merges into from\n> +\tIf you wish to setup 'git pull' so that it merges into from\n\nNot relevant to this patch, but shouldn't ‘setup’ be ‘set up’?\n\n> @@ -718,14 +718,14 @@ commit.template::\n> \tspecified user's home directory.\n> \n> diff.autorefreshindex::\n> -\tWhen using 'git-diff' to compare with work tree\n> +\tWhen using 'git diff' to compare with work tree\n> \tfiles, do not consider stat-only change as changed.\n> \tInstead, silently run `git update-index --refresh` to\n> \tupdate the cached stat information for paths whose\n> \tcontents in the work tree match the contents in the\n> \tindex. This option defaults to true. Note that this\n> -\taffects only 'git-diff' Porcelain, and not lower level\n> -\t'diff' commands, such as 'git-diff-files'.\n> +\taffects only 'git diff' Porcelain, and not lower level\n> +\t'diff' commands, such as 'git diff-files'.\n\nThis sounds better to me without the comma before ‘such as’.\n\n> @@ -840,7 +840,7 @@ format.pretty::\n> \tlinkgit:git-whatchanged[1].\n> \n> format.thread::\n> -\tThe default threading style for 'git-format-patch'. Can be\n> +\tThe default threading style for 'git format-patch'. Can be\n> \teither a boolean value, `shallow` or `deep`. `shallow`\n> \tthreading makes every mail a reply to the head of the series,\n> \twhere the head is chosen from the cover letter, the\n\nThe ‘either’ here sounds awkward, because there are three options.\nAlso it is not completely clear that ‘shallow’ and ‘deep’ are not\nboolean values here. So maybe ‘Can be a boolean value, or shallow or\ndeep’, despite the awkward nested ‘or’ expression.\n\n> @@ -875,18 +875,18 @@ gc.autopacklimit::\n> \tdefault\tvalue is 50. Setting this to 0 disables it.\n> \n> gc.packrefs::\n> -\t'git-gc' does not run `git pack-refs` in a bare repository by\n> +\t'git gc' does not run `git pack-refs` in a bare repository by\n> \tdefault so that older dumb-transport clients can still fetch\n> -\tfrom the repository. Setting this to `true` lets 'git-gc'\n> +\tfrom the repository. Setting this to `true` lets 'git gc'\n> \tto run `git pack-refs`. Setting this to `false` tells\n\nShould be ‘lets git gc run’ or ‘tells git gc to run’. Not to mention\nthis is not true any more: 'git gc' has run pack-refs by default ever\nsince commit 56752391 (Make \"git gc\" pack all refs by default,\n2007-05-24). As that commit message mentions, git versions before\nv1.5.1.2 cannot clone repos with packed refs over http, and git\nversions before v1.4.4 cannot handled packed refs period, but more\nrecent git should have no problems.\n\nSo to summarize, the changes to config.txt look good, except a\n‘git-apply’ snuck past.\n\nThe other changes mentioned above follow.\n\n Documentation: config: git gc packs refs by default now\n Documentation: tiny git config manual tweaks\n\n Documentation/config.txt | 23 ++++++++++-------------\n 1 files changed, 10 insertions(+), 13 deletions(-)\n"},{"id":"131199","messageId":"20100110025941.GC1083@progeny.tock","threadId":"22117","inReplyTo":"20100110025641.GB1083@progeny.tock","subject":"[PATCH 1/2] Documentation: git gc packs refs by default now","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-01-10T02:59:41Z","receivedAt":"2010-01-10T02:59:41Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"In commit 56752391 (Make \"git gc\" pack all refs by default,\n2007-05-24), 'git gc' was changed to run pack-refs by default \n\nVersions before v1.5.1.2 cannot clone repos with packed refs over\nhttp, and versions before v1.4.4 cannot handled packed refs at\nall, but more recent git should have no problems. Try to make\nthis more clear in the git-config manual.\n\nThe analagous passage in git-gc.txt was updated already with\ncommit fe2128a (Change git-gc documentation to reflect\ngc.packrefs implementation., 2008-01-09).\n\nSigned-off-by: Jonathan Nieder \n---\n Documentation/config.txt | 15 ++++++---------\n 1 files changed, 6 insertions(+), 9 deletions(-)\n\ndiff --git a/Documentation/config.txt b/Documentation/config.txt\nindex b5b27ba..bcfed1c 100644\n--- a/Documentation/config.txt\n+++ b/Documentation/config.txt\n@@ -875,15 +875,12 @@ gc.autopacklimit::\n \tdefault\tvalue is 50. Setting this to 0 disables it.\n \n gc.packrefs::\n-\t'git-gc' does not run `git pack-refs` in a bare repository by\n-\tdefault so that older dumb-transport clients can still fetch\n-\tfrom the repository. Setting this to `true` lets 'git-gc'\n-\tto run `git pack-refs`. Setting this to `false` tells\n-\t'git-gc' never to run `git pack-refs`. The default setting is\n-\t`notbare`. Enable it only when you know you do not have to\n-\tsupport such clients. The default setting will change to `true`\n-\tat some stage, and setting this to `false` will continue to\n-\tprevent `git pack-refs` from being run from 'git-gc'.\n+\tRunning `git pack-refs` in a repository renders it\n+\tunclonable by Git versions prior to 1.5.1.2 over dumb\n+\ttransports such as HTTP. This variable determines whether\n+\t'git gc' runs `git pack-refs`. This can be set to \"nobare\"\n+\tto enable it within all non-bare repos or it can be set to a\n+\tboolean value. The default is `true`.\n \n gc.pruneexpire::\n \tWhen 'git-gc' is run, it will call 'prune --expire 2.weeks.ago'.\n-- \n1.6.6\n"},{"id":"131200","messageId":"20100110030121.GD1083@progeny.tock","threadId":"22117","inReplyTo":"20100110025641.GB1083@progeny.tock","subject":"[PATCH 2/2] Documentation: tiny git config manual tweaks","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-01-10T03:01:21Z","receivedAt":"2010-01-10T03:01:21Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"As a verb, 'setup' is spelled 'set up'. “diff commands such as\ndiff-files” scans better without a comma. Clarify that shallow\nand deep are special non-boolean values for format.thread rather\nthan boolean values with some other name.\n\nSigned-off-by: Jonathan Nieder \n---\n Documentation/config.txt | 8 ++++----\n 1 files changed, 4 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/config.txt b/Documentation/config.txt\nindex bcfed1c..f7728ec 100644\n--- a/Documentation/config.txt\n+++ b/Documentation/config.txt\n@@ -537,7 +537,7 @@ apply.whitespace::\n \tas the '--whitespace' option. See linkgit:git-apply[1].\n \n branch.autosetupmerge::\n-\tTells 'git-branch' and 'git-checkout' to setup new branches\n+\tTells 'git-branch' and 'git-checkout' to set up new branches\n \tso that linkgit:git-pull[1] will appropriately merge from the\n \tstarting point branch. Note that even if this option is not set,\n \tthis behavior can be chosen per-branch using the `--track`\n@@ -725,7 +725,7 @@ diff.autorefreshindex::\n \tcontents in the work tree match the contents in the\n \tindex. This option defaults to true. Note that this\n \taffects only 'git-diff' Porcelain, and not lower level\n-\t'diff' commands, such as 'git-diff-files'.\n+\t'diff' commands such as 'git-diff-files'.\n \n diff.external::\n \tIf this config variable is set, diff generation is not\n@@ -841,8 +841,8 @@ format.pretty::\n \n format.thread::\n \tThe default threading style for 'git-format-patch'. Can be\n-\teither a boolean value, `shallow` or `deep`. `shallow`\n-\tthreading makes every mail a reply to the head of the series,\n+\ta boolean value, or `shallow` or `deep`. `shallow` threading\n+\tmakes every mail a reply to the head of the series,\n \twhere the head is chosen from the cover letter, the\n \t`\\--in-reply-to`, and the first patch mail, in this order.\n \t`deep` threading makes every mail a reply to the previous one.\n-- \n1.6.6\n"},{"id":"131201","messageId":"20100110033133.GE1083@progeny.tock","threadId":"22117","inReplyTo":"9d10ee6a8526dc9f9c220cc6bb4b509c8cc73b0a.1263081032.git.trast@student.ethz.ch","subject":"Re: [PATCH v2 3/4] Documentation: format full commands in typewriter font","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-01-10T03:31:33Z","receivedAt":"2010-01-10T03:31:33Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Thomas Rast wrote:\n> * If the intent is that the user type the command exactly as given, it\n> is `code`.\n> If the user is only loosely referred to a command and/or option, it\n> remains 'emphasised'.\n\nOkay. I think I was guilty of pushing this convention (in commits\nlike 2fd02c92). If the distinction is too hazy to be useful, I think\nit would be fine to always use `code`, though that would be a bigger\npatch.\n\n> diff --git a/Documentation/config.txt b/Documentation/config.txt\n> index 23a965e..6bfd9e1 100644\n> --- a/Documentation/config.txt\n> +++ b/Documentation/config.txt\n> @@ -741,15 +741,15 @@ diff.mnemonicprefix::\n> \tstandard \"a/\" and \"b/\" depending on what is being compared. When\n> \tthis configuration is in effect, reverse diff output also swaps\n> \tthe order of the prefixes:\n> -'git-diff';;\n> +`git diff`;;\n> \tcompares the (i)ndex and the (w)ork tree;\n> -'git-diff HEAD';;\n> +`git diff HEAD`;;\n> \t compares a (c)ommit and the (w)ork tree;\n> -'git diff --cached';;\n> +`git diff --cached`;;\n> \tcompares a (c)ommit and the (i)ndex;\n> -'git-diff HEAD:file1 file2';;\n> +`git-diff HEAD:file1 file2`;;\n\nShouldn't this use ‘git diff’ (no hyphen)? Alternatively, if you are\nleaving this for the next commit, should the other 'git-diff' lines\nkeep their dash until then, too?\n\n> diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt\n> index c39d957..f91c7ac 100644\n> --- a/Documentation/git-bisect.txt\n> +++ b/Documentation/git-bisect.txt\n> @@ -26,7 +26,7 @@ on the subcommand:\n> git bisect log\n> git bisect run ...\n> \n> -This command uses 'git rev-list --bisect' to help drive the\n> +This command uses `git rev-list --bisect` to help drive the\n\nDoes rev-list --bisect take more arguments (i.e., isn’t the command\nbeing only loosely referred to here)?\n\n> diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt\n> index 394a77a..544836a 100644\n> --- a/Documentation/git-filter-branch.txt\n> +++ b/Documentation/git-filter-branch.txt\n> @@ -129,8 +129,8 @@ convenience functions, too. For example, calling 'skip_commit \"$@\"'\n> will leave out the current commit (but not its changes! If you want\n> that, use 'git-rebase' instead).\n> +\n> -You can also use the 'git_commit_non_empty_tree \"$@\"' instead of\n> -'git commit-tree \"$@\"' if you don't wish to keep commits with a single parent\n> +You can also use the `git_commit_non_empty_tree \"$@\"` instead of\n> +`git commit-tree \"$@\"` if you don't wish to keep commits with a single parent\n> and that makes no change to the tree.\n\nNot this commit’s topic, but perhaps ‘use the ...’ should be ‘use ...’\nor ‘use the ... idiom’...\n\n> --tag-name-filter ::\n> @@ -179,7 +179,7 @@ the nearest ancestor that was not excluded.\n> \tand only one parent, it will hence keep merges points. Also, this\n> \toption is not compatible with the use of '--commit-filter'. Though you\n> \tjust need to use the function 'git_commit_non_empty_tree \"$@\"' instead\n> -\tof the 'git commit-tree \"$@\"' idiom in your commit filter to make that\n> +\tof the `git commit-tree \"$@\"` idiom in your commit filter to make that\n> \thappen.\n\n... to match this.\n\n> diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt\n> index 3277f4e..04c21d3 100644\n> --- a/Documentation/git-merge.txt\n> +++ b/Documentation/git-merge.txt\n> @@ -193,7 +193,7 @@ After seeing a conflict, you can do two things:\n> \n> * Decide not to merge. The only clean-ups you need are to reset\n> the index file to the `HEAD` commit to reverse 2. and to clean\n> - up working tree changes made by 2. and 3.; 'git-reset --hard' can\n> + up working tree changes made by 2. and 3.; `git-reset --hard` can\n\nProbably `git reset --hard` (I won’t mention any more of these).\n\nExcept for the bisect-change above,\nReviewed-by: Jonathan Nieder \n\nThe rest looks good, and really does seem clearer in some places.\n\nThanks,\nJonathan\n"},{"id":"131206","messageId":"20100110041357.GF1083@progeny.tock","threadId":"22117","inReplyTo":"57bddb115331a23816af772172531fb56fceace4.1263081032.git.trast@student.ethz.ch","subject":"Re: [PATCH v2 1/4] Documentation/git-merge: reword references to \"remote\" and \"pull\"","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-01-10T04:13:57Z","receivedAt":"2010-01-10T04:13:57Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Thomas Rast wrote:\n> The git-merge manpage was written in terms of merging a \"remote\",\n> which is no longer the case: you merge local or remote-tracking\n> branches; pull is for actual remotes.\n \nRight.\n\n> Adjust the manpage accordingly. We refer to the arguments as\n> \"commits\", and change instances of \"remote\" to \"other\" (where branches\n> are concerned) or \"theirs\" (where conflict sides are concerned).\n\nMakes sense. It might be nice to emphasize the metaphor of merging\nanother branch’s history into the current branch, but \nreally does seem clearer than ‘{ | }’ or any other\nalternative I can come up with.\n\n> diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt\n> index e886c2e..4896587 100644\n> --- a/Documentation/git-merge.txt\n> +++ b/Documentation/git-merge.txt\n> @@ -10,17 +10,17 @@ SYNOPSIS\n> --------\n> [verse]\n> 'git merge' [-n] [--stat] [--no-commit] [--squash] [-s ]...\n> -\t[-m ] ...\n> -'git merge' HEAD ...\n> +\t[-m ] ...\n> +'git merge' HEAD ...\n> \n> DESCRIPTION\n> -----------\n> -This is the top-level interface to the merge machinery\n> -which drives multiple merge strategy scripts.\n> +Merges the history specified by into HEAD, optionally using a\n> +specific merge strategy.\n\nPerhaps just\n\n| Rejoins two or more diverging branches of development.\n\nwould be simpler. The ability to choose a merge strategy seems more\nlike a detail for later.\n\n> -The second syntax ( `HEAD` ) is supported for\n> +The second syntax ( `HEAD` ...) is supported for\n> historical reasons. Do not use it from the command line or in\n> -new scripts. It is the same as `git merge -m `.\n> +new scripts. It is the same as `git merge -m ...`.\n\nTechnically, they are not entirely the same: ‘merge -m ’ will\nwarn that the log message is ignored when the merge results in a\nfast-forward, whereas ‘merge HEAD’ will not. See commit\n77c29b4a (Revert recent \"git merge HEAD ...\"\ndeprecation, 2009-12-08). So should this say\n\n| Use `git merge -m ...` instead.\n\nto side-step the issue? Not sure.\n\n> @@ -33,10 +33,10 @@ include::merge-options.txt[]\n> \tused to give a good default for automated 'git merge'\n> \tinvocations.\n> \n> -...::\n> -\tOther branch heads to merge into our branch. You need at\n> -\tleast one . Specifying more than one \n> -\tobviously means you are trying an Octopus.\n> +...::\n> +\tCommits, usually other branch heads, to merge into our branch.\n> +\tYou need at least one . Specifying more than one\n> +\t obviously means you are trying an Octopus.\n\nNice.\n\n> @@ -96,8 +96,8 @@ file matches exactly the current `HEAD` commit; otherwise we\n> will write out your local changes already registered in your\n> index file along with the merge result, which is not good.\n> Because 1. involves only those paths differing between your\n> -branch and the remote branch you are pulling from during the\n> -merge (which is typically a fraction of the whole tree), you can\n> +branch and the branch you are merging\n> +(which is typically a fraction of the whole tree), you can\n\nHmm. The old wording distinguishes nicely between the HEAD and\nMERGE_HEAD that will be parents for the new HEAD. From some points\nof view, the new wording does not: both are branches you are\nmerging (though only one is an argument to 'git merge').\n\nSadly, I have not come up with a good expression for “the other\ncommit whose history is to be incorporated into the current\nbranch”.\n\nMaybe we should punt and just say “the other branch”?\n\n> @@ -202,15 +202,15 @@ You can work through the conflict with a number of tools:\n> mergetool which will work you through the merge.\n> \n> * Look at the diffs. 'git diff' will show a three-way diff,\n> - highlighting changes from both the HEAD and remote versions.\n> + highlighting changes from both the HEAD and their versions.\n> \n> * Look at the diffs on their own. 'git log --merge -p '\n\nThis is a bit awkward, since 'they' is playing two roles. Also,\nthe context does not make it obvious what 'our' and 'their'\nversions are.\n\nMaybe:\n\n| * Look at the diffs. 'git diff' will show a three-way diff,\n| highlighting changes from both the HEAD and MERGE_HEAD\n| versions.\n|\n| * Look at the diffs from each branch. 'git log --merge -p\n| ' will show diffs first for the HEAD version and\n| then the MERGE_HEAD version.\n|\n| * Look at the originals. 'git show :1:filename' shows the\n| common ancestor, 'git show :2:filename' shows the HEAD\n| version, and 'git show :3:filename' shows the MERGE_HEAD\n| version.\n\nThanks for looking into this,\nJonathan\n"},{"id":"131207","messageId":"20100110044949.GA8974@progeny.tock","threadId":"22117","inReplyTo":"e330d8ca1a9ec38ce40b0f67123b1dd893f0b31c.1263081032.git.trast@student.ethz.ch","subject":"Re: [PATCH v2 2/4] Documentation: warn prominently against merging with dirty trees","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-01-10T04:49:50Z","receivedAt":"2010-01-10T04:49:50Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Thomas Rast wrote:\n\n> diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt\n> index 4896587..3277f4e 100644\n> --- a/Documentation/git-merge.txt\n> +++ b/Documentation/git-merge.txt\n> @@ -22,6 +22,10 @@ The second syntax ( `HEAD` ...) is supported for\n> historical reasons. Do not use it from the command line or in\n> new scripts. It is the same as `git merge -m ...`.\n> \n> +*Warning*: Running 'git-merge' with uncommitted changes is\n> +discouraged:\n\nIs this true? The 'git reset' manual page gives an example of something\nI end up doing pretty often:\n\n| Undo a merge or pull inside a dirty work tree\n|\n| $ git pull (1)\n| Auto-merging nitfol\n| Merge made by recursive.\n| nitfol | 20 +++++----\n| ...\n| $ git reset --merge ORIG_HEAD (2)\n|\n| 1. Even if you may have local modifications in your working tree, you\n| can safely say \"git pull\" when you know that the change in the other\n| branch does not overlap with them.\n| 2. After inspecting the result of the merge, you may find that the\n| change in the other branch is unsatisfactory. Running \"git reset\n| --hard ORIG_HEAD\" will let you go back to where you were, but it will\n| discard your local changes, which you do not want. \"git reset --merge\"\n| keeps your local changes.\n\n> while possible, it leaves you in a state that is hard to\n> +back out of in the case of a conflict.\n> +\n\nOh, that is a problem. Maybe 'git merge' should refuse to merge\nunless told otherwise, if there is a dirty index and there might be\nconflicts.\n\nIn other words, would it be possible to fix this without relying on\npeople to look at the documentation?\n\nJonathan\n"},{"id":"131208","messageId":"7vskaefp2v.fsf@alter.siamese.dyndns.org","threadId":"22117","inReplyTo":"20100110044949.GA8974@progeny.tock","subject":"Re: [PATCH v2 2/4] Documentation: warn prominently against merging with dirty trees","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-01-10T06:31:36Z","receivedAt":"2010-01-10T06:31:36Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jonathan Nieder writes:\n\n> | 1. Even if you may have local modifications in your working tree, you\n> | can safely say \"git pull\" when you know that the change in the other\n> | branch does not overlap with them.\n> | 2. After inspecting the result of the merge, you may find that the\n> | change in the other branch is unsatisfactory. Running \"git reset\n> | --hard ORIG_HEAD\" will let you go back to where you were, but it will\n> | discard your local changes, which you do not want. \"git reset --merge\"\n> | keeps your local changes.\n>\n>> while possible, it leaves you in a state that is hard to\n>> +back out of in the case of a conflict.\n>> +\n>\n> Oh, that is a problem. Maybe 'git merge' should refuse to merge\n> unless told otherwise, if there is a dirty index and there might be\n> conflicts.\n\n\"git reset --merge\" will keep your local changes after such a merge, and\n\"mergy\" operations (not just \"merge\" but also \"revert\", \"am -3\", etc)\nwon't get you into a situation where you cannot, by refusing to do\nanything when e.g. your index is dirty. Especially when Christian's\n\"reset --merge\" update becomes solid, \"... is hard to back out of\" will\nbecome a false statement.\n\nOf course, the user needs to understand what he or she is doing (see\nhttp://thread.gmane.org/gmane.comp.version-control.git/136166/focus=136171\nfor example). And that is one reason we (at least I) try to teach new\npeople to start working from a clean tree, until they get comfortable\nworking with mergy operations.\n"},{"id":"131210","messageId":"7vfx6efox9.fsf@alter.siamese.dyndns.org","threadId":"22117","inReplyTo":"201001100107.29920.trast@student.ethz.ch","subject":"Re: [PATCH v2 0/4] Documentation style fixes","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-01-10T06:34:58Z","receivedAt":"2010-01-10T06:34:58Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"As to the general direction I am in full agreement with what you and\nJonathan discussed in the review of your series, namely:\n\n - We prefer dashless these days;\n\n - Reference to a concrete command line is git clone which is\n typeset differently from general descriptions of what git\n clone command does.\n\nI'd like to proceed with this series by (1) pulling from you and queuing\nthe result in 'next', (2) asking other people (including Jonathan) to\nproofread and send necessary updates to the list, (3) asking you to check\nand queue these updates from others yourself and tell me to pull again to\nmy 'next', and (4) merging the result to 'master' when done.\n\nDoes it sound workable? Am I placing too much undue burden on you?\n"},{"id":"131211","messageId":"7vskaecu1f.fsf@alter.siamese.dyndns.org","threadId":"22117","inReplyTo":"201001100107.29920.trast@student.ethz.ch","subject":"Re: [PATCH v2 0/4] Documentation style fixes","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-01-10T07:12:44Z","receivedAt":"2010-01-10T07:12:44Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Thomas Rast writes:\n\n> Turns out the fourth patch is over 200kB and can't be sent over the\n> list. I pushed the whole series to\n>\n> git://repo.or.cz/git/sbeyer.git t/doc-merge-revamp\n\nI think you meant s/sbeyer/trast/ ;-)\n"},{"id":"131220","messageId":"201001101310.21455.trast@student.ethz.ch","threadId":"22117","inReplyTo":"7vfx6efox9.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH v2 0/4] Documentation style fixes","fromName":"Thomas Rast","fromEmail":"trast@student.ethz.ch","sentAt":"2010-01-10T12:10:10Z","receivedAt":"2010-01-10T12:10:10Z","isPatch":true,"sender":{"key":"tr@thomasrast.ch","avatar":"https://avatars.githubusercontent.com/u/153510?v=4"},"body":"Junio C Hamano wrote:\n> \n> I'd like to proceed with this series by (1) pulling from you and queuing\n> the result in 'next', (2) asking other people (including Jonathan) to\n> proofread and send necessary updates to the list, (3) asking you to check\n> and queue these updates from others yourself and tell me to pull again to\n> my 'next', and (4) merging the result to 'master' when done.\n> \n> Does it sound workable? Am I placing too much undue burden on you?\n\nNo, that's fine, and indeed I'm glad I'm not putting too much\nconflict-resolution burden on you.\n\nI took the not-yet-merged (I hope I understood the above right :-)\nliberty of squashing fixes from Jonathan's review. I'll send the\ninterdiffs as a reply to this mail. They're now at\n\n git://repo.or.cz/git/trast.git doc-style/for-next\n\n(I'm leaving the old head in place for comparison). I'm gathering\nincremental updates in\n\n git://repo.or.cz/git/trast.git doc-style/pu\n\nFor now we have\n\nJonathan Nieder (2):\n Documentation: git gc packs refs by default now\n Documentation: tiny git config manual tweaks\n\nThomas Rast (1):\n Documentation: show-files is now called git-ls-files\n\nI'll also send the last one for review shortly, though it's rather\ntrivial.\n\n-- \nThomas Rast\ntrast@{inf,student}.ethz.ch\n"},{"id":"131221","messageId":"48822ef1fee0a734817bad9f63e122e4d1d66106.1263123648.git.trast@student.ethz.ch","threadId":"22117","inReplyTo":"201001101310.21455.trast@student.ethz.ch","subject":"[PATCH 1/2] More missed dashed 'git-cmd' forms","fromName":"Thomas Rast","fromEmail":"trast@student.ethz.ch","sentAt":"2010-01-10T12:10:54Z","receivedAt":"2010-01-10T12:10:54Z","isPatch":true,"sender":{"key":"tr@thomasrast.ch","avatar":"https://avatars.githubusercontent.com/u/153510?v=4"},"body":"Squashed into the corresponding commit of the original series.\n---\n Documentation/config.txt | 14 +++++++-------\n Documentation/git-archive.txt | 2 +-\n Documentation/git-commit.txt | 2 +-\n Documentation/git-daemon.txt | 4 ++--\n Documentation/git-diff-index.txt | 4 ++--\n Documentation/git-diff-tree.txt | 6 +++---\n Documentation/git-for-each-ref.txt | 2 +-\n Documentation/git-gc.txt | 2 +-\n Documentation/git-get-tar-commit-id.txt | 2 +-\n Documentation/git-help.txt | 2 +-\n Documentation/git-instaweb.txt | 2 +-\n Documentation/git-log.txt | 2 +-\n Documentation/git-ls-files.txt | 2 +-\n Documentation/git-mailinfo.txt | 2 +-\n Documentation/git-merge-index.txt | 2 +-\n Documentation/git-merge-one-file.txt | 4 ++--\n Documentation/git-prune.txt | 2 +-\n Documentation/git-read-tree.txt | 2 +-\n Documentation/git-repack.txt | 2 +-\n Documentation/git-rerere.txt | 2 +-\n Documentation/git-rev-parse.txt | 4 ++--\n Documentation/git-show-index.txt | 2 +-\n Documentation/git-show.txt | 2 +-\n Documentation/git-tag.txt | 2 +-\n Documentation/git-tar-tree.txt | 2 +-\n Documentation/git-update-index.txt | 8 ++++----\n Documentation/git-upload-archive.txt | 2 +-\n Documentation/git-web--browse.txt | 4 ++--\n Documentation/gitcore-tutorial.txt | 12 ++++++------\n Documentation/gitdiffcore.txt | 18 +++++++++---------\n Documentation/githooks.txt | 8 ++++----\n Documentation/gitrepository-layout.txt | 2 +-\n 32 files changed, 64 insertions(+), 64 deletions(-)\n\ndiff --git a/Documentation/config.txt b/Documentation/config.txt\nindex 937dfbe..5d549ca 100644\n--- a/Documentation/config.txt\n+++ b/Documentation/config.txt\n@@ -443,7 +443,7 @@ core.pager::\n core.whitespace::\n \tA comma separated list of common whitespace problems to\n \tnotice. 'git diff' will use `color.diff.whitespace` to\n-\thighlight them, and 'git-apply --whitespace=error' will\n+\thighlight them, and 'git apply --whitespace=error' will\n \tconsider them as errors. You can prefix `-` to disable\n \tany of them (e.g. `-trailing-space`):\n +\n@@ -673,7 +673,7 @@ color.interactive::\n \tcolors only when the output is to the terminal. Defaults to false.\n \n color.interactive.::\n-\tUse customized color for 'git-add --interactive'\n+\tUse customized color for 'git add --interactive'\n \toutput. `` may be `prompt`, `header`, `help` or `error`, for\n \tfour distinct types of normal output from interactive\n \tcommands. The values of these variables may be specified as\n@@ -858,7 +858,7 @@ format.signoff::\n \n gc.aggressiveWindow::\n \tThe window size parameter used in the delta compression\n-\talgorithm used by 'git-gc --aggressive'. This defaults\n+\talgorithm used by 'git gc --aggressive'. This defaults\n \tto 10.\n \n gc.auto::\n@@ -889,22 +889,22 @@ gc.pruneexpire::\n \tunreachable objects immediately.\n \n gc.reflogexpire::\n-\t'git-reflog expire' removes reflog entries older than\n+\t'git reflog expire' removes reflog entries older than\n \tthis time; defaults to 90 days.\n \n gc.reflogexpireunreachable::\n-\t'git-reflog expire' removes reflog entries older than\n+\t'git reflog expire' removes reflog entries older than\n \tthis time and are not reachable from the current tip;\n \tdefaults to 30 days.\n \n gc.rerereresolved::\n \tRecords of conflicted merge you resolved earlier are\n-\tkept for this many days when 'git-rerere gc' is run.\n+\tkept for this many days when 'git rerere gc' is run.\n \tThe default is 60 days. See linkgit:git-rerere[1].\n \n gc.rerereunresolved::\n \tRecords of conflicted merge you have not resolved are\n-\tkept for this many days when 'git-rerere gc' is run.\n+\tkept for this many days when 'git rerere gc' is run.\n \tThe default is 15 days. See linkgit:git-rerere[1].\n \n gitcvs.commitmsgannotation::\ndiff --git a/Documentation/git-archive.txt b/Documentation/git-archive.txt\nindex 980bc62..799c8b6 100644\n--- a/Documentation/git-archive.txt\n+++ b/Documentation/git-archive.txt\n@@ -27,7 +27,7 @@ used as the modification time of each file in the archive. In the latter\n case the commit time as recorded in the referenced commit object is\n used instead. Additionally the commit ID is stored in a global\n extended pax header if the tar format is used; it can be extracted\n-using 'git-get-tar-commit-id'. In ZIP files it is stored as a file\n+using 'git get-tar-commit-id'. In ZIP files it is stored as a file\n comment.\n \n OPTIONS\ndiff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt\nindex 8914543..c322c75 100644\n--- a/Documentation/git-commit.txt\n+++ b/Documentation/git-commit.txt\n@@ -40,7 +40,7 @@ The content to be added can be specified in several ways:\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- operation. Currently, this is done by invoking 'git-add --interactive'.\n+ operation. Currently, this is done by invoking 'git add --interactive'.\n \n The `--dry-run` option can be used to obtain a\n summary of what is included by any of the above for the next\ndiff --git a/Documentation/git-daemon.txt b/Documentation/git-daemon.txt\nindex ece232e..01c9f8e 100644\n--- a/Documentation/git-daemon.txt\n+++ b/Documentation/git-daemon.txt\n@@ -181,7 +181,7 @@ upload-pack::\n \titem to `false`.\n \n upload-archive::\n-\tThis serves 'git-archive --remote'. It is disabled by\n+\tThis serves 'git archive --remote'. It is disabled by\n \tdefault, but a repository can enable it by setting\n \t`daemon.uploadarch` configuration item to `true`.\n \n@@ -258,7 +258,7 @@ Repositories can still be accessed by hostname though, assuming\n they correspond to these IP addresses.\n \n selectively enable/disable services per repository::\n-\tTo enable 'git-archive --remote' and disable 'git fetch' against\n+\tTo enable 'git archive --remote' and disable 'git fetch' against\n \ta repository, have the following in the configuration file in the\n \trepository (that is the file 'config' next to 'HEAD', 'refs' and\n \t'objects').\ndiff --git a/Documentation/git-diff-index.txt b/Documentation/git-diff-index.txt\nindex 84acf49..162cb74 100644\n--- a/Documentation/git-diff-index.txt\n+++ b/Documentation/git-diff-index.txt\n@@ -72,7 +72,7 @@ In fact, `git diff-index --cached` *should* always be entirely equivalent to\n actually doing a 'git write-tree' and comparing that. Except this one is much\n nicer for the case where you just want to check where you are.\n \n-So doing a 'git-diff-index --cached' is basically very useful when you are\n+So doing a `git diff-index --cached` is basically very useful when you are\n asking yourself \"what have I already marked for being committed, and\n what's the difference to a previous tree\".\n \n@@ -87,7 +87,7 @@ The non-cached version asks the question:\n tree - index contents _and_ files that aren't up-to-date\n \n which is obviously a very useful question too, since that tells you what\n-you *could* commit. Again, the output matches the 'git-diff-tree -r'\n+you *could* commit. Again, the output matches the 'git diff-tree -r'\n output to a tee, but with a twist.\n \n The twist is that if some file doesn't match the index, we don't have\ndiff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt\nindex 95c402a..a7e37b8 100644\n--- a/Documentation/git-diff-tree.txt\n+++ b/Documentation/git-diff-tree.txt\n@@ -67,19 +67,19 @@ The following flags further affect the behavior when comparing\n commits (but not trees).\n \n -m::\n-\tBy default, 'git-diff-tree --stdin' does not show\n+\tBy default, 'git diff-tree --stdin' does not show\n \tdifferences for merge commits. With this flag, it shows\n \tdifferences to that commit from all of its parents. See\n \talso '-c'.\n \n -s::\n-\tBy default, 'git-diff-tree --stdin' shows differences,\n+\tBy default, 'git diff-tree --stdin' shows differences,\n \teither in machine-readable form (without '-p') or in patch\n \tform (with '-p'). This output can be suppressed. It is\n \tonly useful with '-v' flag.\n \n -v::\n-\tThis flag causes 'git-diff-tree --stdin' to also show\n+\tThis flag causes 'git diff-tree --stdin' to also show\n \tthe commit message before the differences.\n \n include::pretty-options.txt[]\ndiff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt\nindex 8dc873f..7e83288 100644\n--- a/Documentation/git-for-each-ref.txt\n+++ b/Documentation/git-for-each-ref.txt\n@@ -82,7 +82,7 @@ objecttype::\n \tThe type of the object (`blob`, `tree`, `commit`, `tag`).\n \n objectsize::\n-\tThe size of the object (the same as 'git-cat-file -s' reports).\n+\tThe size of the object (the same as 'git cat-file -s' reports).\n \n objectname::\n \tThe object name (aka SHA-1).\ndiff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt\nindex 07f211f..771807f 100644\n--- a/Documentation/git-gc.txt\n+++ b/Documentation/git-gc.txt\n@@ -50,7 +50,7 @@ Housekeeping is required if there are too many loose objects or\n too many packs in the repository. If the number of loose objects\n exceeds the value of the `gc.auto` configuration variable, then\n all loose objects are combined into a single pack using\n-'git-repack -d -l'. Setting the value of `gc.auto` to 0\n+'git repack -d -l'. Setting the value of `gc.auto` to 0\n disables automatic packing of loose objects.\n +\n If the number of packs exceeds the value of `gc.autopacklimit`,\ndiff --git a/Documentation/git-get-tar-commit-id.txt b/Documentation/git-get-tar-commit-id.txt\nindex 94c434b..790af95 100644\n--- a/Documentation/git-get-tar-commit-id.txt\n+++ b/Documentation/git-get-tar-commit-id.txt\n@@ -17,7 +17,7 @@ Acts as a filter, extracting the commit ID stored in archives created by\n 'git archive'. It reads only the first 1024 bytes of input, thus its\n runtime is not influenced by the size of very much.\n \n-If no commit ID is found, 'git-get-tar-commit-id' quietly exists with a\n+If no commit ID is found, 'git get-tar-commit-id' quietly exists with a\n return code of 1. This can happen if had not been created\n using 'git archive' or if the first parameter of 'git archive' had been\n a tree ID instead of a commit ID or tag.\ndiff --git a/Documentation/git-help.txt b/Documentation/git-help.txt\nindex ce41b65..f8df109 100644\n--- a/Documentation/git-help.txt\n+++ b/Documentation/git-help.txt\n@@ -55,7 +55,7 @@ other display programs (see below).\n +\n The web browser can be specified using the configuration variable\n 'help.browser', or 'web.browser' if the former is not set. If none of\n-these config variables is set, the 'git-web--browse' helper script\n+these config variables is set, the 'git web--browse' helper script\n (called by 'git help') will pick a suitable default. See\n linkgit:git-web--browse[1] for more information about this.\n \ndiff --git a/Documentation/git-instaweb.txt b/Documentation/git-instaweb.txt\nindex 0771f25..a1f17df 100644\n--- a/Documentation/git-instaweb.txt\n+++ b/Documentation/git-instaweb.txt\n@@ -44,7 +44,7 @@ OPTIONS\n -b::\n --browser::\n \tThe web browser that should be used to view the gitweb\n-\tpage. This will be passed to the 'git-web--browse' helper\n+\tpage. This will be passed to the 'git web--browse' helper\n \tscript along with the URL of the gitweb instance. See\n \tlinkgit:git-web--browse[1] for more information about this. If\n \tthe script fails, the URL will be printed to stdout.\ndiff --git a/Documentation/git-log.txt b/Documentation/git-log.txt\nindex cb12f09..ff4063b 100644\n--- a/Documentation/git-log.txt\n+++ b/Documentation/git-log.txt\n@@ -16,7 +16,7 @@ Shows the commit logs.\n \n The command takes options applicable to the 'git rev-list'\n command to control what is shown and how, and options applicable to\n-the 'git-diff-*' commands to control how the changes\n+the 'git diff-*' commands to control how the changes\n each commit introduces are shown.\n \n \ndiff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt\nindex 92b21d7..7faba23 100644\n--- a/Documentation/git-ls-files.txt\n+++ b/Documentation/git-ls-files.txt\n@@ -145,7 +145,7 @@ which case it outputs:\n \n [ ] \n \n-'git-ls-files --unmerged' and 'git-ls-files --stage' can be used to examine\n+'git ls-files --unmerged' and 'git ls-files --stage' can be used to examine\n detailed information on unmerged paths.\n \n For an unmerged path, instead of recording a single mode/SHA1 pair,\ndiff --git a/Documentation/git-mailinfo.txt b/Documentation/git-mailinfo.txt\nindex a524252..e3d58cb 100644\n--- a/Documentation/git-mailinfo.txt\n+++ b/Documentation/git-mailinfo.txt\n@@ -30,7 +30,7 @@ OPTIONS\n \twhitespaces, (3) '[' up to ']', typically '[PATCH]', and\n \tthen prepends \"[PATCH] \". This flag forbids this\n \tmunging, and is most useful when used to read back\n-\t'git-format-patch -k' output.\n+\t'git format-patch -k' output.\n \n -b::\n \tWhen -k is not in effect, all leading strings bracketed with '['\ndiff --git a/Documentation/git-merge-index.txt b/Documentation/git-merge-index.txt\nindex 493f061..4d266de 100644\n--- a/Documentation/git-merge-index.txt\n+++ b/Documentation/git-merge-index.txt\n@@ -43,7 +43,7 @@ code.\n Typically this is run with a script calling git's imitation of\n the 'merge' command from the RCS package.\n \n-A sample script called 'git-merge-one-file' is included in the\n+A sample script called 'git merge-one-file' is included in the\n distribution.\n \n ALERT ALERT ALERT! The git \"merge object order\" is different from the\ndiff --git a/Documentation/git-merge-one-file.txt b/Documentation/git-merge-one-file.txt\nindex 7360202..a163cfc 100644\n--- a/Documentation/git-merge-one-file.txt\n+++ b/Documentation/git-merge-one-file.txt\n@@ -8,12 +8,12 @@ git-merge-one-file - The standard helper program to use with git-merge-index\n \n SYNOPSIS\n --------\n-'git-merge-one-file'\n+'git merge-one-file'\n \n DESCRIPTION\n -----------\n This is the standard helper program to use with 'git merge-index'\n-to resolve a merge after the trivial merge done with 'git-read-tree -m'.\n+to resolve a merge after the trivial merge done with 'git read-tree -m'.\n \n Author\n ------\ndiff --git a/Documentation/git-prune.txt b/Documentation/git-prune.txt\nindex 437d7c4..3bb7304 100644\n--- a/Documentation/git-prune.txt\n+++ b/Documentation/git-prune.txt\n@@ -16,7 +16,7 @@ DESCRIPTION\n NOTE: In most cases, users should run 'git gc', which calls\n 'git prune'. See the section \"NOTES\", below.\n \n-This runs 'git-fsck --unreachable' using all the refs\n+This runs 'git fsck --unreachable' using all the refs\n available in `$GIT_DIR/refs`, optionally with additional set of\n objects specified on the command line, and prunes all unpacked\n objects unreachable from any of these head objects from the object database.\ndiff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt\nindex 469cd69..a31a4cb 100644\n--- a/Documentation/git-read-tree.txt\n+++ b/Documentation/git-read-tree.txt\n@@ -298,7 +298,7 @@ populated. Here is an outline of how the algorithm works:\n trivial rules ..\n \n You would normally use 'git merge-index' with supplied\n-'git-merge-one-file' to do this last step. The script updates\n+'git merge-one-file' to do this last step. The script updates\n the files in the working tree as it merges each path and at the\n end of a successful merge.\n \ndiff --git a/Documentation/git-repack.txt b/Documentation/git-repack.txt\nindex 50a5c96..538895c 100644\n--- a/Documentation/git-repack.txt\n+++ b/Documentation/git-repack.txt\n@@ -71,7 +71,7 @@ other objects in that pack they already have locally.\n \n -n::\n \tDo not update the server information with\n-\t'git-update-server-info'. This option skips\n+\t'git update-server-info'. This option skips\n \tupdating local catalog files needed to publish\n \tthis repository (or a direct copy of it)\n \tover HTTP or FTP. See linkgit:git-update-server-info[1].\ndiff --git a/Documentation/git-rerere.txt b/Documentation/git-rerere.txt\nindex 8dab467..acc220a 100644\n--- a/Documentation/git-rerere.txt\n+++ b/Documentation/git-rerere.txt\n@@ -37,7 +37,7 @@ its working state.\n 'clear'::\n \n This resets the metadata used by rerere if a merge resolution is to be\n-aborted. Calling 'git-am [--skip|--abort]' or 'git-rebase [--skip|--abort]'\n+aborted. Calling 'git am [--skip|--abort]' or 'git rebase [--skip|--abort]'\n will automatically invoke this command.\n \n 'diff'::\ndiff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt\nindex fff4cb8..82ae16e 100644\n--- a/Documentation/git-rev-parse.txt\n+++ b/Documentation/git-rev-parse.txt\n@@ -74,7 +74,7 @@ OPTIONS\n \tproperly quoted for consumption by shell. Useful when\n \tyou expect your parameter to contain whitespaces and\n \tnewlines (e.g. when using pickaxe `-S` with\n-\t'git-diff-\\*'). In contrast to the `--sq-quote` option,\n+\t'git diff-\\*'). In contrast to the `--sq-quote` option,\n \tthe command input is still interpreted as usual.\n \n --not::\n@@ -361,7 +361,7 @@ usage on the standard error stream, and exits with code 129.\n Input Format\n ~~~~~~~~~~~~\n \n-'git-rev-parse --parseopt' input format is fully text based. It has two parts,\n+'git rev-parse --parseopt' input format is fully text based. It has two parts,\n separated by a line that contains only `--`. The lines before the separator\n (should be more than one) are used for the usage.\n The lines after the separator describe the options.\ndiff --git a/Documentation/git-show-index.txt b/Documentation/git-show-index.txt\nindex deebdc8..8382fbe 100644\n--- a/Documentation/git-show-index.txt\n+++ b/Documentation/git-show-index.txt\n@@ -17,7 +17,7 @@ Reads given idx file for packed git archive created with\n 'git pack-objects' command, and dumps its contents.\n \n The information it outputs is subset of what you can get from\n-'git-verify-pack -v'; this command only shows the packfile\n+'git verify-pack -v'; this command only shows the packfile\n offset and SHA1 of each object.\n \n \ndiff --git a/Documentation/git-show.txt b/Documentation/git-show.txt\nindex de83d6b..55e687a 100644\n--- a/Documentation/git-show.txt\n+++ b/Documentation/git-show.txt\n@@ -16,7 +16,7 @@ Shows one or more objects (blobs, trees, tags and commits).\n \n For commits it shows the log message and textual diff. It also\n presents the merge commit in a special format as produced by\n-'git-diff-tree --cc'.\n+'git diff-tree --cc'.\n \n For tags, it shows the tag message and the referenced objects.\n \ndiff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt\nindex 518bf98..31c78a8 100644\n--- a/Documentation/git-tag.txt\n+++ b/Documentation/git-tag.txt\n@@ -131,7 +131,7 @@ and be done with it.\n \n . The insane thing.\n You really want to call the new version \"X\" too, 'even though'\n-others have already seen the old one. So just use 'git-tag -f'\n+others have already seen the old one. So just use 'git tag -f'\n again, as if you hadn't already published the old one.\n \n However, Git does *not* (and it should not) change tags behind\ndiff --git a/Documentation/git-tar-tree.txt b/Documentation/git-tar-tree.txt\nindex 7c116ec..3c786bd 100644\n--- a/Documentation/git-tar-tree.txt\n+++ b/Documentation/git-tar-tree.txt\n@@ -24,7 +24,7 @@ a commit ID or tag ID. In the first case the current time is used as\n modification time of each file in the archive. In the latter case the\n commit time as recorded in the referenced commit object is used instead.\n Additionally the commit ID is stored in a global extended pax header.\n-It can be extracted using 'git-get-tar-commit-id'.\n+It can be extracted using 'git get-tar-commit-id'.\n \n OPTIONS\n -------\ndiff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt\nindex c2477b9..e8c19be 100644\n--- a/Documentation/git-update-index.txt\n+++ b/Documentation/git-update-index.txt\n@@ -206,7 +206,7 @@ into the index file.\n . mode SP sha1 SP stage TAB path\n +\n This format is to put higher order stages into the\n-index file and matches 'git-ls-files --stage' output.\n+index file and matches 'git ls-files --stage' output.\n \n To place a higher stage entry to the index, the path should\n first be removed by feeding a mode=0 entry for the path, and\n@@ -263,8 +263,8 @@ option. To unset, use `--no-assume-unchanged`.\n The command looks at `core.ignorestat` configuration variable. When\n this is true, paths updated with `git update-index paths...` and\n paths updated with other git commands that update both index and\n-working tree (e.g. 'git-apply --index', 'git-checkout-index -u',\n-and 'git-read-tree -u') are automatically marked as \"assume\n+working tree (e.g. 'git apply --index', 'git checkout-index -u',\n+and 'git read-tree -u') are automatically marked as \"assume\n unchanged\". Note that \"assume unchanged\" bit is *not* set if\n `git update-index --refresh` finds the working tree file matches\n the index (use `git update-index --really-refresh` if you want\n@@ -317,7 +317,7 @@ unreliable, this should be set to 'false' (see linkgit:git-config[1]).\n This causes the command to ignore differences in file modes recorded\n in the index and the file mode on the filesystem if they differ only on\n executable bit. On such an unfortunate filesystem, you may\n-need to use 'git-update-index --chmod='.\n+need to use 'git update-index --chmod='.\n \n Quite similarly, if `core.symlinks` configuration variable is set\n to 'false' (see linkgit:git-config[1]), symbolic links are checked out\ndiff --git a/Documentation/git-upload-archive.txt b/Documentation/git-upload-archive.txt\nindex afe6595..f5f2b39 100644\n--- a/Documentation/git-upload-archive.txt\n+++ b/Documentation/git-upload-archive.txt\n@@ -12,7 +12,7 @@ SYNOPSIS\n \n DESCRIPTION\n -----------\n-Invoked by 'git-archive --remote' and sends a generated archive to the\n+Invoked by 'git archive --remote' and sends a generated archive to the\n other end over the git protocol.\n \n This command is usually not invoked directly by the end user. The UI\ndiff --git a/Documentation/git-web--browse.txt b/Documentation/git-web--browse.txt\nindex 91a54a6..7572049 100644\n--- a/Documentation/git-web--browse.txt\n+++ b/Documentation/git-web--browse.txt\n@@ -62,7 +62,7 @@ browser..path\n You can explicitly provide a full path to your preferred browser by\n setting the configuration variable 'browser..path'. For example,\n you can configure the absolute path to firefox by setting\n-'browser.firefox.path'. Otherwise, 'git-web--browse' assumes the tool\n+'browser.firefox.path'. Otherwise, 'git web--browse' assumes the tool\n is available in PATH.\n \n browser..cmd\n@@ -71,7 +71,7 @@ browser..cmd\n When the browser, specified by options or configuration variables, is\n not among the supported ones, then the corresponding\n 'browser..cmd' configuration variable will be looked up. If this\n-variable exists then 'git-web--browse' will treat the specified tool\n+variable exists then 'git web--browse' will treat the specified tool\n as a custom command and will use a shell eval to run the command with\n the URLs passed as arguments.\n \ndiff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt\nindex 202a379..c005f37 100644\n--- a/Documentation/gitcore-tutorial.txt\n+++ b/Documentation/gitcore-tutorial.txt\n@@ -428,7 +428,7 @@ $ git update-index hello\n (note how we didn't need the `\\--add` flag this time, since git knew\n about the file already).\n \n-Note what happens to the different 'git-diff-\\*' versions here. After\n+Note what happens to the different 'git diff-\\*' versions here. After\n we've updated `hello` in the index, `git diff-files -p` now shows no\n differences, but `git diff-index -p HEAD` still *does* show that the\n current state is different from the state we committed. In fact, now\n@@ -1095,7 +1095,7 @@ The 'commit walkers' are sometimes also called 'dumb\n transports', because they do not require any git aware smart\n server like git Native transport does. Any stock HTTP server\n that does not even support directory index would suffice. But\n-you must prepare your repository with 'git-update-server-info'\n+you must prepare your repository with 'git update-server-info'\n to help dumb transport downloaders.\n \n Once you fetch from the remote repository, you `merge` that\n@@ -1260,7 +1260,7 @@ $ git ls-files --unmerged\n \n The next step of merging is to merge these three versions of the\n file, using 3-way merge. This is done by giving\n-'git-merge-one-file' command as one of the arguments to\n+'git merge-one-file' command as one of the arguments to\n 'git merge-index' command:\n \n ------------\n@@ -1270,7 +1270,7 @@ ERROR: Merge conflict in hello\n fatal: merge program failed\n ------------\n \n-'git-merge-one-file' script is called with parameters to\n+'git merge-one-file' script is called with parameters to\n describe those three versions, and is responsible to leave the\n merge results in the working tree.\n It is a fairly straightforward shell script, and\n@@ -1487,10 +1487,10 @@ If other people are pulling from your repository over dumb\n transport protocols (HTTP), you need to keep this repository\n 'dumb transport friendly'. After `git init`,\n `$GIT_DIR/hooks/post-update.sample` copied from the standard templates\n-would contain a call to 'git-update-server-info'\n+would contain a call to 'git update-server-info'\n but you need to manually enable the hook with\n `mv post-update.sample post-update`. This makes sure\n-'git-update-server-info' keeps the necessary files up-to-date.\n+'git update-server-info' keeps the necessary files up-to-date.\n \n 3. Push into the public repository from your primary\n repository.\ndiff --git a/Documentation/gitdiffcore.txt b/Documentation/gitdiffcore.txt\nindex 5244925..dcdea54 100644\n--- a/Documentation/gitdiffcore.txt\n+++ b/Documentation/gitdiffcore.txt\n@@ -23,7 +23,7 @@ that is easier to understand than the conventional kind.\n The chain of operation\n ----------------------\n \n-The 'git-diff-{asterisk}' family works by first comparing two sets of\n+The 'git diff-{asterisk}' family works by first comparing two sets of\n files:\n \n - 'git diff-index' compares contents of a \"tree\" object and the\n@@ -74,12 +74,12 @@ into another list. There are currently 5 such transformations:\n - diffcore-pickaxe\n - diffcore-order\n \n-These are applied in sequence. The set of filepairs 'git-diff-{asterisk}'\n+These are applied in sequence. The set of filepairs 'git diff-{asterisk}'\n commands find are used as the input to diffcore-break, and\n the output from diffcore-break is used as the input to the\n next transformation. The final result is then passed to the\n output routine and generates either diff-raw format (see Output\n-format sections of the manual for 'git-diff-{asterisk}' commands) or\n+format sections of the manual for 'git diff-{asterisk}' commands) or\n diff-patch format.\n \n \n@@ -87,7 +87,7 @@ diffcore-break: For Splitting Up \"Complete Rewrites\"\n ----------------------------------------------------\n \n The second transformation in the chain is diffcore-break, and is\n-controlled by the -B option to the 'git-diff-{asterisk}' commands. This is\n+controlled by the -B option to the 'git diff-{asterisk}' commands. This is\n used to detect a filepair that represents \"complete rewrite\" and\n break such filepair into two filepairs that represent delete and\n create. E.g. If the input contained this filepair:\n@@ -123,7 +123,7 @@ diffcore-rename: For Detection Renames and Copies\n \n This transformation is used to detect renames and copies, and is\n controlled by the -M option (to detect renames) and the -C option\n-(to detect copies as well) to the 'git-diff-{asterisk}' commands. If the\n+(to detect copies as well) to the 'git diff-{asterisk}' commands. If the\n input contained these filepairs:\n \n ------------------------------------------------\n@@ -168,11 +168,11 @@ number after the \"-M\" or \"-C\" option (e.g. \"-M8\" to tell it to use\n 8/10 = 80%).\n \n Note. When the \"-C\" option is used with `\\--find-copies-harder`\n-option, 'git-diff-{asterisk}' commands feed unmodified filepairs to\n+option, 'git diff-{asterisk}' commands feed unmodified filepairs to\n diffcore mechanism as well as modified ones. This lets the copy\n detector consider unmodified files as copy source candidates at\n the expense of making it slower. Without `\\--find-copies-harder`,\n-'git-diff-{asterisk}' commands can detect copies only if the file that was\n+'git diff-{asterisk}' commands can detect copies only if the file that was\n copied happened to have been modified in the same changeset.\n \n \n@@ -223,7 +223,7 @@ diffcore-pickaxe: For Detecting Addition/Deletion of Specified String\n \n This transformation is used to find filepairs that represent\n changes that touch a specified string, and is controlled by the\n--S option and the `\\--pickaxe-all` option to the 'git-diff-{asterisk}'\n+-S option and the `\\--pickaxe-all` option to the 'git diff-{asterisk}'\n commands.\n \n When diffcore-pickaxe is in use, it checks if there are\n@@ -246,7 +246,7 @@ diffcore-order: For Sorting the Output Based on Filenames\n \n This is used to reorder the filepairs according to the user's\n (or project's) taste, and is controlled by the -O option to the\n-'git-diff-{asterisk}' commands.\n+'git diff-{asterisk}' commands.\n \n This takes a text file each of whose lines is a shell glob\n pattern. Filepairs that match a glob pattern on an earlier line\ndiff --git a/Documentation/githooks.txt b/Documentation/githooks.txt\nindex 45559fa..87e2c03 100644\n--- a/Documentation/githooks.txt\n+++ b/Documentation/githooks.txt\n@@ -202,7 +202,7 @@ updated. If the hook exits with zero, updating of individual refs can\n still be prevented by the <> hook.\n \n Both standard output and standard error output are forwarded to\n-'git-send-pack' on the other end, so you can simply `echo` messages\n+'git send-pack' on the other end, so you can simply `echo` messages\n for the user.\n \n [[update]]\n@@ -301,7 +301,7 @@ updated values of the refs. You might consider it instead if you need\n them.\n \n When enabled, the default 'post-update' hook runs\n-'git-update-server-info' to keep the information used by dumb\n+'git update-server-info' to keep the information used by dumb\n transports (e.g., HTTP) up-to-date. If you are publishing\n a git repository that is accessible via HTTP, you should\n probably enable this hook.\n@@ -313,8 +313,8 @@ for the user.\n pre-auto-gc\n ~~~~~~~~~~~\n \n-This hook is invoked by 'git-gc --auto'. It takes no parameter, and\n-exiting with non-zero status from this script causes the 'git-gc --auto'\n+This hook is invoked by 'git gc --auto'. It takes no parameter, and\n+exiting with non-zero status from this script causes the 'git gc --auto'\n to abort.\n \n GIT\ndiff --git a/Documentation/gitrepository-layout.txt b/Documentation/gitrepository-layout.txt\nindex 5c4700c..3cd32d6 100644\n--- a/Documentation/gitrepository-layout.txt\n+++ b/Documentation/gitrepository-layout.txt\n@@ -151,7 +151,7 @@ info/refs::\n \tThis file helps dumb transports discover what refs are\n \tavailable in this repository. If the repository is\n \tpublished for dumb transports, this file should be\n-\tregenerated by 'git-update-server-info' every time a tag\n+\tregenerated by 'git update-server-info' every time a tag\n \tor branch is created or modified. This is normally done\n \tfrom the `hooks/update` hook, which is run by the\n \t'git-receive-pack' command when you 'git push' into the\n-- \n1.6.6.218.g502b0\n"},{"id":"131222","messageId":"bb5d5a8040d61fd10ed199114a0a24ea79d08981.1263123648.git.trast@student.ethz.ch","threadId":"22117","inReplyTo":"48822ef1fee0a734817bad9f63e122e4d1d66106.1263123648.git.trast@student.ethz.ch","subject":"[PATCH 2/2] More missed `code snippets`","fromName":"Thomas Rast","fromEmail":"trast@student.ethz.ch","sentAt":"2010-01-10T12:10:55Z","receivedAt":"2010-01-10T12:10:55Z","isPatch":true,"sender":{"key":"tr@thomasrast.ch","avatar":"https://avatars.githubusercontent.com/u/153510?v=4"},"body":"Squashed into the corresponding commit of the original series.\n---\n\nAdditionally, I reverted\n\n --- i/Documentation/git-bisect.txt\n +++ w/Documentation/git-bisect.txt\n @@ -26,7 +26,7 @@ on the subcommand:\n git bisect log\n git bisect run ...\n\n -This command uses `git rev-list --bisect` to help drive the\n +This command uses 'git rev-list --bisect' to help drive the\n binary search process to find which change introduced a bug, given an\n old \"good\" commit object name and a later \"bad\" commit object name.\n\nper the review.\n\n Documentation/config.txt | 2 +-\n Documentation/git-gc.txt | 2 +-\n 2 files changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git i/Documentation/config.txt w/Documentation/config.txt\nindex 6bfd9e1..3e96a27 100644\n--- i/Documentation/config.txt\n+++ w/Documentation/config.txt\n@@ -747,7 +747,7 @@ diff.mnemonicprefix::\n \t compares a (c)ommit and the (w)ork tree;\n `git diff --cached`;;\n \tcompares a (c)ommit and the (i)ndex;\n-`git-diff HEAD:file1 file2`;;\n+`git diff HEAD:file1 file2`;;\n \tcompares an (o)bject and a (w)ork tree entity;\n `git diff --no-index a b`;;\n \tcompares two non-git things (1) and (2).\ndiff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt\nindex 771807f..189573a 100644\n--- a/Documentation/git-gc.txt\n+++ b/Documentation/git-gc.txt\n@@ -50,7 +50,7 @@ Housekeeping is required if there are too many loose objects or\n too many packs in the repository. If the number of loose objects\n exceeds the value of the `gc.auto` configuration variable, then\n all loose objects are combined into a single pack using\n-'git repack -d -l'. Setting the value of `gc.auto` to 0\n+`git repack -d -l`. Setting the value of `gc.auto` to 0\n disables automatic packing of loose objects.\n +\n If the number of packs exceeds the value of `gc.autopacklimit`,\n-- \n1.6.6.218.g502b0\n"},{"id":"131223","messageId":"c4e1adc765525b4ac6c63677a27035661462d2b8.1263125504.git.trast@student.ethz.ch","threadId":"22117","inReplyTo":"201001101310.21455.trast@student.ethz.ch","subject":"[PATCH] Documentation: show-files is now called git-ls-files","fromName":"Thomas Rast","fromEmail":"trast@student.ethz.ch","sentAt":"2010-01-10T12:11:49Z","receivedAt":"2010-01-10T12:11:49Z","isPatch":true,"sender":{"key":"tr@thomasrast.ch","avatar":"https://avatars.githubusercontent.com/u/153510?v=4"},"body":"Amazingly, a reference to 'show files' survived from the core command\ndocumentation introduced in c64b9b8 (Reference documentation for the\ncore git commands., 2005-05-05)!\n\nHowever, the tool is now called git-ls-files.\n\nSigned-off-by: Thomas Rast \n---\n Documentation/git-ls-files.txt | 2 +-\n 1 files changed, 1 insertions(+), 1 deletions(-)\n\ndiff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt\nindex 7faba23..a84cc37 100644\n--- a/Documentation/git-ls-files.txt\n+++ b/Documentation/git-ls-files.txt\n@@ -140,7 +140,7 @@ OPTIONS\n \n Output\n ------\n-show files just outputs the filename unless '--stage' is specified in\n+'git ls-files' just outputs the filenames unless '--stage' is specified in\n which case it outputs:\n \n [ ] \n-- \n1.6.6.218.g502b0\n"},{"id":"131224","messageId":"201001101316.49164.trast@student.ethz.ch","threadId":"22117","inReplyTo":"7vskaefp2v.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH v2 2/4] Documentation: warn prominently against merging with dirty trees","fromName":"Thomas Rast","fromEmail":"trast@student.ethz.ch","sentAt":"2010-01-10T12:16:47Z","receivedAt":"2010-01-10T12:16:47Z","isPatch":true,"sender":{"key":"tr@thomasrast.ch","avatar":"https://avatars.githubusercontent.com/u/153510?v=4"},"body":"Junio C Hamano wrote:\n> >> while possible, it leaves you in a state that is hard to\n> >> +back out of in the case of a conflict.\n> >> +\n> >\n> > Oh, that is a problem. Maybe 'git merge' should refuse to merge\n> > unless told otherwise, if there is a dirty index and there might be\n> > conflicts.\n\nActually I'm worried about a dirty *worktree*. Do you think that\nshould be clarified?\n\n> \"git reset --merge\" will keep your local changes after such a merge, and\n> \"mergy\" operations (not just \"merge\" but also \"revert\", \"am -3\", etc)\n> won't get you into a situation where you cannot, by refusing to do\n> anything when e.g. your index is dirty. Especially when Christian's\n> \"reset --merge\" update becomes solid, \"... is hard to back out of\" will\n> become a false statement.\n\nDoes that apply to dirty worktrees, too? I admit I didn't follow that\ntopic at all.\n\n-- \nThomas Rast\ntrast@{inf,student}.ethz.ch\n"},{"id":"131225","messageId":"201001101321.23728.trast@student.ethz.ch","threadId":"22117","inReplyTo":"20100110025641.GB1083@progeny.tock","subject":"Re: [PATCH v2 4/4] Documentation: spell 'git cmd' without dash throughout","fromName":"Thomas Rast","fromEmail":"trast@student.ethz.ch","sentAt":"2010-01-10T12:21:21Z","receivedAt":"2010-01-10T12:21:21Z","isPatch":true,"sender":{"key":"tr@thomasrast.ch","avatar":"https://avatars.githubusercontent.com/u/153510?v=4"},"body":"Jonathan Nieder wrote:\n> > 110 files changed, 584 insertions(+), 584 deletions(-)\n> \n> But yikes! Did you do this by hand or by some automated process?\n\nThe (now-refined) bottom line is\n\n perl -i -pe \"s{'git-((?\"'!'\"cvsserver|upload-pack|receive-pack|shell|upload-archive)[a-z-]+)}{'git \\$1}g\" Documentation/*.txt\n git checkout -- Documentation/RelNotes*\n git add -p\n\nI really stepped through all of them with 'git add -p', but my eyes\nprobably got tired rather quickly.\n\n> A 'git-apply' snuck in. ;-)\n\nIndeed, and (as you can see in the update I sent a few minutes ago) I\nmissed a lot more, because I originally had a regex that only scanned\nfor 'git-cmd' and 'git-split-cmd', missing the 'git-three-word-cmd'\nand 'git-cmd --with-option' forms. Thanks for pointing that out.\n\n-- \nThomas Rast\ntrast@{inf,student}.ethz.ch\n"},{"id":"131226","messageId":"201001101324.47025.trast@student.ethz.ch","threadId":"22117","inReplyTo":"20100110041357.GF1083@progeny.tock","subject":"Re: [PATCH v2 1/4] Documentation/git-merge: reword references to \"remote\" and \"pull\"","fromName":"Thomas Rast","fromEmail":"trast@student.ethz.ch","sentAt":"2010-01-10T12:24:45Z","receivedAt":"2010-01-10T12:24:45Z","isPatch":true,"sender":{"key":"tr@thomasrast.ch","avatar":"https://avatars.githubusercontent.com/u/153510?v=4"},"body":"Jonathan Nieder wrote:\n> Thomas Rast wrote:\n> > * Look at the diffs. 'git diff' will show a three-way diff,\n> > - highlighting changes from both the HEAD and remote versions.\n> > + highlighting changes from both the HEAD and their versions.\n> > \n> > * Look at the diffs on their own. 'git log --merge -p '\n> \n> This is a bit awkward, since 'they' is playing two roles. Also,\n> the context does not make it obvious what 'our' and 'their'\n> versions are.\n> \n> Maybe:\n> \n> | * Look at the diffs. 'git diff' will show a three-way diff,\n> | highlighting changes from both the HEAD and MERGE_HEAD\n> | versions.\n\nI like this idea, as it nicely assigns terminology to the \"their\"\nside. We need to explain MERGE_HEAD (it's not in the manpage yet),\nbut that should fit in somewhere.\n\n-- \nThomas Rast\ntrast@{inf,student}.ethz.ch\n"},{"id":"131249","messageId":"20100111021322.GA8480@progeny.tock","threadId":"22117","inReplyTo":"7vskaefp2v.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH v2 2/4] Documentation: warn prominently against merging with dirty trees","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-01-11T02:13:22Z","receivedAt":"2010-01-11T02:13:22Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Junio C Hamano wrote:\n> Jonathan Nieder writes:\n\n>> Oh, that is a problem. Maybe 'git merge' should refuse to merge\n>> unless told otherwise, if there is a dirty index and there might be\n>> conflicts.\n>\n> \"git reset --merge\" will keep your local changes after such a merge, and\n> \"mergy\" operations (not just \"merge\" but also \"revert\", \"am -3\", etc)\n> won't get you into a situation where you cannot, by refusing to do\n> anything when e.g. your index is dirty. Especially when Christian's\n> \"reset --merge\" update becomes solid, \"... is hard to back out of\" will\n> become a false statement.\n\nHere is a scenario I worry about:\n\nSuppose I have a change to main.c staged, to add a feature that others\nhave discussed as well. After a short distraction, I return and run\n‘git pull’ to see what upstream has been working on. As luck would\nhave it, the remote version of main.c is exactly the same as my\nmodified version, so the merge happily proceeds. Some other files\nmerge cleanly. Eventually there is some conflict.\n\nNow I regret the pull. Will ‘reset --merge’ restore the index and\nwork tree to its original state?\n\nIf the change to main.c was _not_ staged, then the merge would have\nfailed early, so that is not something to worry about.\n\n> Of course, the user needs to understand what he or she is doing (see\n> http://thread.gmane.org/gmane.comp.version-control.git/136166/focus=136171\n> for example).\n\nAgreed. And probably the user who understands what is going on will\nnot make the mistake I described above. Otherwise, they could succumb\nto a related problem:\n\nSuppose all is as above, except that git detects no conflict. Suppose\nfurther that some upstream commit was bogus.\n\nNow I regret the pull. How can I restore the index and work tree to\nits original state?\n\nIf I reset --hard (or --merge) to the previous HEAD commit, the\nmodification to main.c is forgotten. In practice, I would do\n'git reset --hard HEAD^ && git checkout HEAD@{1} -- main.c'.\n"},{"id":"131250","messageId":"7vzl4lbcfl.fsf@alter.siamese.dyndns.org","threadId":"22117","inReplyTo":"20100111021322.GA8480@progeny.tock","subject":"Re: [PATCH v2 2/4] Documentation: warn prominently against merging with dirty trees","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-01-11T02:30:38Z","receivedAt":"2010-01-11T02:30:38Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jonathan Nieder writes:\n\n> Here is a scenario I worry about:\n>\n> Suppose I have a change to main.c staged, to add a feature that others\n> have discussed as well. After a short distraction, I return and run\n> ‘git pull’ to see what upstream has been working on.\n\nIf your index is dirty, any \"mergy\" operation will refuse to work *before*\ntouching anything, so you won't use \"git reset --merge\" to begin with.\n\nYou are allowed to have local modifications only in your work tree.\nFurthermore, even git experts limit them to something they feel they can\nafford to lose and recreate easily if necessary. See for example:\n\n http://thread.gmane.org/gmane.comp.version-control.git/15148/focus=15476\n\nThat is why I said:\n\n Of course, the user needs to understand what he or she is doing (see\n http://thread.gmane.org/gmane.comp.version-control.git/136166/focus=136171\n for example). And that is one reason we (at least I) try to teach new\n people to start working from a clean tree, until they get comfortable\n working with mergy operations.\n\nand that is why the archived article referenced above refers to\n\n http://gitster.livejournal.com/29060.html\n\nYou need to be able to tell the two ways in which a \"mergy\" operation can\n\"fail\" apart [*1*].\n\n - One that stops before touching anything (either your index was dirty\n and nothing happened, or your index was clean but you had local\n modifications in your work tree). You do not run \"git reset --merge\",\n for this one; and\n\n - Another that goes ahead and results in conflicts. When you got these\n conflicts, you can \"reset --merge\" them away.\n\n[Footnote]\n\n*1* Strictly speaking, the latter is not even a \"failure\"; it allowed you\nto make progress, merging all the auto-mergeable parts without your help,\nand only asking you to handle the remainder.\n"},{"id":"131252","messageId":"20100111041318.GA9806@progeny.tock","threadId":"22117","inReplyTo":"7vzl4lbcfl.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH v2 2/4] Documentation: warn prominently against merging with dirty trees","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-01-11T04:13:18Z","receivedAt":"2010-01-11T04:13:18Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Junio C Hamano wrote:\n> Jonathan Nieder writes:\n\n>> Here is a scenario I worry about:\n>>\n>> Suppose I have a change to main.c staged, to add a feature that others\n>> have discussed as well. After a short distraction, I return and run\n>> ‘git pull’ to see what upstream has been working on.\n>\n> If your index is dirty, any \"mergy\" operation will refuse to work *before*\n> touching anything, so you won't use \"git reset --merge\" to begin with.\n\nYes, that is true. And I was not worried about that.\n\nAs the git-merge manual explains:\n\n| A merge is always between the current HEAD and one or more commits\n| (usually, branch head or tag), and the index file must match the tree of\n| HEAD commit (i.e. the contents of the last commit) when it starts out. In\n| other words, git diff --cached HEAD must report no changes. (One exception\n| is when the changed index entries are already in the same state that would\n| result from the merge anyway.)\n\nThe potentially problematic scenario for \"git reset --merge\" is this\nlast one, where a changed index entry is already in the same state\nthat would result from the merge. Would a \"git reset --merge\" reset\nthe changed contents away?\n\n> You are allowed to have local modifications only in your work tree.\n> Furthermore, even git experts limit them to something they feel they can\n> afford to lose and recreate easily if necessary.\n\nSadly, even a small change disappearing can be unnerving for an expert\nand dangerous for a novice.\n\n> You need to be able to tell the two ways in which a \"mergy\" operation can\n> \"fail\" apart [*1*].\n\nThanks for bringing this up. The manual does not emphasize that\npoint at all, but it should.\n\nJonathan\n"},{"id":"131268","messageId":"20100111082123.GA23742@progeny.tock","threadId":"22117","inReplyTo":"20100111041318.GA9806@progeny.tock","subject":"[PATCH 0/6] Re: Documentation: warn prominently against merging with dirty trees","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-01-11T08:21:23Z","receivedAt":"2010-01-11T08:21:23Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Jonathan Nieder wrote:\n> Junio C Hamano wrote:\n\n>> You need to be able to tell the two ways in which a \"mergy\" operation can\n>> \"fail\" apart [*1*].\n>\n> Thanks for bringing this up. The manual does not emphasize that\n> point at all, but it should.\n\nMaybe something like this (patch 4) could help. This should pass\nthrough Thomas’s tree to avoid conflicts with his other changes; but\nof course, I would be glad to hear any thoughts you have before then.\n\nJonathan Nieder (6):\n Documentation: clarify one-line description for merge\n Documentation: merge: add an overview\n Documentation: merge: move configuration section to the end\n Documentation: emphasize when git merge terminates early\n Documentation: merge: add a section about fast-forward\n Documentation: merge: tweak HOW MERGE WORKS section\n\n Documentation/git-merge.txt | 149 ++++++++++++++++++++++++++----------------\n 1 files changed, 92 insertions(+), 57 deletions(-)\n"},{"id":"131269","messageId":"20100111082755.GA23806@progeny.tock","threadId":"22117","inReplyTo":"20100111082123.GA23742@progeny.tock","subject":"[PATCH/RFC 1/6] Documentation: clarify one-line description for merge","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-01-11T08:27:55Z","receivedAt":"2010-01-11T08:27:55Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"The 'git merge' command is generally not used to tie completely\nindependent projects together (though it can be used to do that)\nbut to reconcile branches of development that may have diverged.\nTry to make this clearer in its one-line description.\n\nCc: Petr Baudis \nCc: Junio C Hamano \nCc: Thomas Rast \nSigned-off-by: Jonathan Nieder \n---\nI am not sure this is an improvement at all. Mostly I wanted to\nconvey the idea of code forks being reconciled, but the resulting\nphrase is not nearly as nice.\n\n Documentation/git-merge.txt | 3 +--\n 1 files changed, 1 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt\nindex e886c2e..394ad0a 100644\n--- a/Documentation/git-merge.txt\n+++ b/Documentation/git-merge.txt\n@@ -3,8 +3,7 @@ git-merge(1)\n \n NAME\n ----\n-git-merge - Join two or more development histories together\n-\n+git-merge - Re-join diverging branches of development\n \n SYNOPSIS\n --------\n-- \n1.6.6\n"},{"id":"131270","messageId":"20100111083028.GB23806@progeny.tock","threadId":"22117","inReplyTo":"20100111082123.GA23742@progeny.tock","subject":"[PATCH 2/6] Documentation: merge: add an overview","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-01-11T08:30:28Z","receivedAt":"2010-01-11T08:30:28Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"The reader unfamiliar with the concepts of branching and merging\nwould have been completely lost. Try to help him with a diagram.\n\nThe diagram comes from the 'git rebase' manual page.\n\nCc: Petr Baudis \nCc: Junio C Hamano \nCc: Thomas Rast ,\nSigned-off-by: Jonathan Nieder \n---\nDoes this tell enough of the story?\n\n Documentation/git-merge.txt | 27 +++++++++++++++++++++++++--\n 1 files changed, 25 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt\nindex 394ad0a..fe190e2 100644\n--- a/Documentation/git-merge.txt\n+++ b/Documentation/git-merge.txt\n@@ -14,8 +14,31 @@ SYNOPSIS\n \n DESCRIPTION\n -----------\n-This is the top-level interface to the merge machinery\n-which drives multiple merge strategy scripts.\n+Incorporates changes leading up to the named commits into the\n+current branch. This command is used by 'git pull' to incorporate\n+remote changes from another repository and may be used by hand to\n+merge changes from one branch into another.\n+\n+Assume the following history exists and the current branch is\n+\"`master`\":\n+\n+------------\n+ A---B---C topic\n+ /\n+ D---E---F---G master\n+------------\n+\n+Then \"`git merge topic`\" will apply the changes from `A`, `B`,\n+and `C` to the work tree, and if they do not conflict with any\n+changes from `master`, will store the result in a new commit along\n+with the names of the two parent commits and a log message from the\n+user describing the changes.\n+\n+------------\n+ A---B---C topic\n+ / \\\n+ D---E---F---G---H master\n+------------\n \n The second syntax ( `HEAD` ) is supported for\n historical reasons. Do not use it from the command line or in\n-- \n1.6.6\n"},{"id":"131271","messageId":"20100111083754.GD23806@progeny.tock","threadId":"22117","inReplyTo":"20100111082123.GA23742@progeny.tock","subject":"[PATCH 4/6] Documentation: emphasize when git merge terminates early","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-01-11T08:37:54Z","receivedAt":"2010-01-11T08:37:54Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"A merge-based operation in git can fail in two ways:\n\n - One that stops before touching anything (either your index was\n dirty and nothing happened, or your index was clean but you\n had local modifications in your work tree).\n\n - Another that goes ahead and results in conflicts.\n\nThe 'git merge' manual explains half of the first case as follows:\n\n| A merge is always between the current `HEAD` and one or more\n| commits (usually, branch head or tag), and the index file must\n| match the tree of `HEAD` commit (i.e. the contents of the last commit)\n| when it starts out.\n\nThe placement of this sentence makes it easy to skip over, and\nits formulation is perhaps too formal to be memorable.\n\nSo give this point its own section and expand upon it. Most of\nthe added text is taken from .\n\nCc: Petr Baudis ,\nCc: Junio C Hamano \nCc: Thomas Rast \nNot-signed-off-by: Jonathan Nieder \n---\nThis is not signed off because most of the text is from Junio’s\nblog. I hope that is okay.\n\n Documentation/git-merge.txt | 34 ++++++++++++++++++++++++----------\n 1 files changed, 24 insertions(+), 10 deletions(-)\n\ndiff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt\nindex e29bb97..8950aa4 100644\n--- a/Documentation/git-merge.txt\n+++ b/Documentation/git-merge.txt\n@@ -60,6 +60,28 @@ include::merge-options.txt[]\n \tleast one . Specifying more than one \n \tobviously means you are trying an Octopus.\n \n+PRE-MERGE CHECKS\n+----------------\n+\n+In some other version control systems, you merge/update and then\n+commit, with the risk of clobbering your changes with humongous\n+conflicts. You shouldn't be pulling or merging if you haven't got\n+your own work into good shape and committed it locally (see also\n+linkgit:git-stash[1]).\n+\n+But novices can make this mistake, and 'git pull' and 'git merge'\n+will stop without doing anything when local uncommitted changes\n+overlap with files that 'git pull'/'git merge' may need to update.\n+\n+Also, to avoid unrelated changes in the recorded commit, 'git\n+pull' and 'git merge' abort if there are any changes registered\n+in the index relative to the contents of the `HEAD` commit.\n+(One exception is when the changed index entries are already in\n+the same state that would result from the merge anyway.)\n+\n+If all named commits are already ancestors of `HEAD`, 'git merge'\n+will exit early with the message \"Already up-to-date.\"\n+\n include::merge-strategies.txt[]\n \n \n@@ -70,17 +92,9 @@ HOW MERGE WORKS\n ---------------\n \n A merge is always between the current `HEAD` and one or more\n-commits (usually, branch head or tag), and the index file must\n-match the tree of `HEAD` commit (i.e. the contents of the last commit)\n-when it starts out. In other words, `git diff --cached HEAD` must\n-report no changes. (One exception is when the changed index\n-entries are already in the same state that would result from\n-the merge anyway.)\n-\n-Three kinds of merge can happen:\n+commits (usually, branch head or tag).\n \n-* The merged commit is already contained in `HEAD`. This is the\n- simplest case, called \"Already up-to-date.\"\n+Two kinds of merge can happen:\n \n * `HEAD` is already contained in the merged commit. This is the\n most common case especially when invoked from 'git pull':\n-- \n1.6.6\n"},{"id":"131272","messageId":"20100111083940.GE23806@progeny.tock","threadId":"22117","inReplyTo":"20100111082123.GA23742@progeny.tock","subject":"[PATCH 5/6] Documentation: merge: add a section about fast-forward","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-01-11T08:39:40Z","receivedAt":"2010-01-11T08:39:40Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Novices sometimes find the behavior of 'git merge' in the\nfast-forward case surprising. Add a section to the manual to\ndescribe it more thoroughly.\n\nCc: Petr Baudis ,\nCc: Junio C Hamano \nCc: Thomas Rast \nSigned-off-by: Jonathan Nieder \n---\n Documentation/git-merge.txt | 31 ++++++++++++++++++-------------\n 1 files changed, 18 insertions(+), 13 deletions(-)\n\ndiff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt\nindex 8950aa4..ec9c6d3 100644\n--- a/Documentation/git-merge.txt\n+++ b/Documentation/git-merge.txt\n@@ -82,6 +82,20 @@ the same state that would result from the merge anyway.)\n If all named commits are already ancestors of `HEAD`, 'git merge'\n will exit early with the message \"Already up-to-date.\"\n \n+FAST-FORWARD MERGE\n+------------------\n+\n+Often the current branch head is an ancestor of the named commit.\n+This is the most common case especially when invoked from 'git\n+pull': you are tracking an upstream repository, you have committed\n+no local changes, and now you want to update to a newer upstream\n+revision. In this case, a new commit is not needed to store the\n+combined history; instead, the `HEAD` (along with the index) is\n+updated to point at the named commit, without creating an extra\n+merge commit.\n+\n+This behavior can be suppressed with the `--no-ff` option.\n+\n include::merge-strategies.txt[]\n \n \n@@ -94,19 +108,10 @@ HOW MERGE WORKS\n A merge is always between the current `HEAD` and one or more\n commits (usually, branch head or tag).\n \n-Two kinds of merge can happen:\n-\n-* `HEAD` is already contained in the merged commit. This is the\n- most common case especially when invoked from 'git pull':\n- you are tracking an upstream repository, have committed no local\n- changes and now you want to update to a newer upstream revision.\n- Your `HEAD` (and the index) is updated to point at the merged\n- commit, without creating an extra merge commit. This is\n- called \"Fast-forward\".\n-\n-* Both the merged commit and `HEAD` are independent and must be\n- tied together by a merge commit that has both of them as its parents.\n- The rest of this section describes this \"True merge\" case.\n+Except in a fast-forward merge (see above), the branches to be\n+merged must be tied together by a merge commit that has both of them\n+as its parents.\n+The rest of this section describes this \"True merge\" case.\n \n The chosen merge strategy merges the two commits into a single\n new source tree.\n-- \n1.6.6\n"},{"id":"131273","messageId":"20100111084355.GF23806@progeny.tock","threadId":"22117","inReplyTo":"20100111082123.GA23742@progeny.tock","subject":"[PATCH 6/6] Documentation: tweak How Merge Works","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-01-11T08:43:56Z","receivedAt":"2010-01-11T08:43:56Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Change heading to TRUE MERGE. The whole manual page is about how\nmerges work.\n\nStart to explain what it means to merge two commits into a single\ntree.\n\nDo not assume the commits named on the 'git merge' command line\ncome from another repository. For simplicity, still assume they\nare branch heads for now, though.\n\nDo not give start any list items with `code`; a toolchain bug\nmakes the resulting nroff look wrong.\n\nRecommend reset --merged for safely cancelling a failed merge.\n\nCc: Petr Baudis \nCc: Junio C Hamano \nCc: Thomas Rast \nSigned-off-by: Jonathan Nieder \n---\n Documentation/git-merge.txt | 56 +++++++++++++++++++-----------------------\n 1 files changed, 25 insertions(+), 31 deletions(-)\n\ndiff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt\nindex ec9c6d3..7ae0f65 100644\n--- a/Documentation/git-merge.txt\n+++ b/Documentation/git-merge.txt\n@@ -96,62 +96,56 @@ merge commit.\n \n This behavior can be suppressed with the `--no-ff` option.\n \n-include::merge-strategies.txt[]\n-\n-\n-If you tried a merge which resulted in complex conflicts and\n-want to start over, you can recover with 'git-reset'.\n-\n-HOW MERGE WORKS\n----------------\n-\n-A merge is always between the current `HEAD` and one or more\n-commits (usually, branch head or tag).\n+TRUE MERGE\n+----------\n \n Except in a fast-forward merge (see above), the branches to be\n merged must be tied together by a merge commit that has both of them\n as its parents.\n The rest of this section describes this \"True merge\" case.\n \n-The chosen merge strategy merges the two commits into a single\n-new source tree.\n When things merge cleanly, this is what happens:\n \n-1. The results are updated both in the index file and in your\n- working tree;\n-2. Index file is written out as a tree;\n+1. A version reconciling the changes from all branches to be\n+ merged is written to the index file and your working tree;\n+2. The index file is written out as a tree;\n 3. The tree gets committed; and\n 4. The `HEAD` pointer gets advanced.\n \n Because of 2., we require that the original state of the index\n file matches exactly the current `HEAD` commit; otherwise we\n-will write out your local changes already registered in your\n+would write out your local changes already registered in your\n index file along with the merge result, which is not good.\n Because 1. involves only those paths differing between your\n-branch and the remote branch you are pulling from during the\n-merge (which is typically a fraction of the whole tree), you can\n-have local modifications in your working tree as long as they do\n-not overlap with what the merge updates.\n-\n-When there are conflicts, the following happens:\n+branch and the other branches (which is typically a fraction of\n+the whole tree), you can have local modifications in your\n+working tree as long as they do not overlap with what the merge\n+updates.\n \n-1. `HEAD` stays the same.\n+When it is not obvious how to reconcile the changes, the following\n+happens:\n \n-2. Cleanly merged paths are updated both in the index file and\n+1. The `HEAD` pointer stays the same.\n+2. The `MERGE_HEAD` ref is set to point to the other branch head.\n+3. Paths that merged cleanly are updated both in the index file and\n in your working tree.\n-\n-3. For conflicting paths, the index file records up to three\n+4. For conflicting paths, the index file records up to three\n versions; stage1 stores the version from the common ancestor,\n- stage2 from `HEAD`, and stage3 from the remote branch (you\n+ stage2 from `HEAD`, and stage3 from `MERGE_HEAD` (you\n can inspect the stages with `git ls-files -u`). The working\n tree files contain the result of the \"merge\" program; i.e. 3-way\n- merge results with familiar conflict markers `<<< === >>>`.\n-\n-4. No other changes are done. In particular, the local\n+ merge results with familiar conflict markers `<<<` `===` `>>>`.\n+5. No other changes are done. In particular, the local\n modifications you had before you started merge will stay the\n same and the index entries for them stay as they were,\n i.e. matching `HEAD`.\n \n+If you tried a merge which resulted in complex conflicts and\n+want to start over, you can recover with `git reset --merged`.\n+\n+include::merge-strategies.txt[]\n+\n+\n HOW CONFLICTS ARE PRESENTED\n ---------------------------\n \n-- \n1.6.6\n"},{"id":"131280","messageId":"7vbph1t0kd.fsf@alter.siamese.dyndns.org","threadId":"22117","inReplyTo":"20100111083028.GB23806@progeny.tock","subject":"Re: [PATCH 2/6] Documentation: merge: add an overview","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-01-11T10:09:38Z","receivedAt":"2010-01-11T10:09:38Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jonathan Nieder writes:\n\n> The reader unfamiliar with the concepts of branching and merging\n> would have been completely lost. Try to help him with a diagram.\n\nGood idea.\n\n> DESCRIPTION\n> -----------\n> -This is the top-level interface to the merge machinery\n> -which drives multiple merge strategy scripts.\n> +Incorporates changes leading up to the named commits into the\n> +current branch.\n\nHaving \"since the histories diverged\" somewhere in this first sentence\nwould clarify the concepts better, I think.\n\n> +Assume the following history exists and the current branch is\n> +\"`master`\":\n> +\n> +------------\n> + A---B---C topic\n> + /\n> + D---E---F---G master\n> +------------\n> +\n> +Then \"`git merge topic`\" will apply the changes from `A`, `B`,\n> +and `C` to the work tree, and if they do not conflict with any\n> +changes from `master`, will store the result in a new commit along\n> +with the names of the two parent commits and a log message from the\n> +user describing the changes.\n\n - Don't spell A, B and C out; technically we don't do that, and\n conceptually \"changes since E until C\" is exactly the same.\n\n - Don't talk about \"what it does\" first, but talk about \"what it is used\n for\" iow \"why do you want to use it\".\n\n - \"What it is used for\" doesn't have to talk about \"if it does not\n conflict\" yet; it is merely a lower-level detail that the main part of\n the document can teach the users to help the tool achieve its goal\n (i.e. \"what it is used for\") when it cannot do so automatically.\n\n\t`git merge topic` is used to replay the change the topic has made\n since it diverged from master's history (i.e. E) until its current\n commit (i.e. C) on top of master, and store the result in a new\n commit along with....\n\n> +------------\n> + A---B---C topic\n> + / \\\n> + D---E---F---G---H master\n> +------------\n> \n> The second syntax ( `HEAD` ) is supported for\n> historical reasons. Do not use it from the command line or in\n> -- \n> 1.6.6\n"},{"id":"131330","messageId":"201001120011.42654.trast@student.ethz.ch","threadId":"22117","inReplyTo":"20100111084355.GF23806@progeny.tock","subject":"Re: [PATCH 6/6] Documentation: tweak How Merge Works","fromName":"Thomas Rast","fromEmail":"trast@student.ethz.ch","sentAt":"2010-01-11T23:11:28Z","receivedAt":"2010-01-11T23:11:28Z","isPatch":true,"sender":{"key":"tr@thomasrast.ch","avatar":"https://avatars.githubusercontent.com/u/153510?v=4"},"body":"The below and earlier comments aside, I really like this series. It\nseems to make the manpage much more accessible.\n\nJonathan Nieder wrote:\n> diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt\n> index ec9c6d3..7ae0f65 100644\n> --- a/Documentation/git-merge.txt\n> +++ b/Documentation/git-merge.txt\n> @@ -96,62 +96,56 @@ merge commit.\n> \n> This behavior can be suppressed with the `--no-ff` option.\n> \n> -include::merge-strategies.txt[]\n> -\n> -\n\nI'm not sure whether you deliberately did this, or deliberately\ndeferred it to this patch, but this \"sneak moves\" the merge-strategies\nsection beyond \"TRUE MERGE\" (was \"HOW MERGE WORKS\").\n\nSo the section layout changes as follows when comparing current master\nwith your series:\n\n NAME\n SYNOPSIS\n DESCRIPTION\n OPTIONS\n+PRE-MERGE CHECKS\n+FAST-FORWARD MERGE\n+TRUE MERGE\n MERGE STRATEGIES\n-CONFIGURATION\n-HOW MERGE WORKS\n HOW CONFLICTS ARE PRESENTED\n HOW TO RESOLVE CONFLICTS\n EXAMPLES\n+CONFIGURATION\n SEE ALSO\n AUTHOR\n DOCUMENTATION\n GIT\n NOTES\n\nWhile I agree with the general intent of deferring the strategies\nfurther back, wouldn't it be better go all the way and instead put\nthem before (or even after, but one of them uses -s ours) \"EXAMPLES\"?\nThe average user will care more about conflicts than about strategies\nother than 'recursive'.\n\n> +1. A version reconciling the changes from all branches to be\n> + merged is written to the index file and your working tree;\n> +2. The index file is written out as a tree;\n> 3. The tree gets committed; and\n> 4. The `HEAD` pointer gets advanced.\n\nCould we do away with the detail here? The user most likely does not\ncare about the exact order because he cannot \"see\" it happening\nanyway. So how about\n\n A merged version reconciling the changes from all branches to be\n merged is committed, and your HEAD, index, and working tree are\n updated to it. (It is possible to have modifications in the working\n tree as long as they do not overlap; the update will preserve them.)\n\nand then snip everything up to\n\n> +When it is not obvious how to reconcile the changes, the following\n> +happens:\n\nbecause that is far more important to the user: he is left in the\nmiddle of the described state.\n\n-- \nThomas Rast\ntrast@{inf,student}.ethz.ch\n"},{"id":"131329","messageId":"201001120011.38704.trast@student.ethz.ch","threadId":"22117","inReplyTo":"20100111083754.GD23806@progeny.tock","subject":"Re: [PATCH 4/6] Documentation: emphasize when git merge terminates early","fromName":"Thomas Rast","fromEmail":"trast@student.ethz.ch","sentAt":"2010-01-11T23:11:33Z","receivedAt":"2010-01-11T23:11:33Z","isPatch":true,"sender":{"key":"tr@thomasrast.ch","avatar":"https://avatars.githubusercontent.com/u/153510?v=4"},"body":"Jonathan Nieder wrote:\n> +In some other version control systems, you merge/update and then\n> +commit, with the risk of clobbering your changes with humongous\n> +conflicts. You shouldn't be pulling or merging if you haven't got\n> +your own work into good shape and committed it locally (see also\n> +linkgit:git-stash[1]).\n\nIsn't it wrong to talk about other VCS, especially when writing down\nwhat Git does *not*? The user wants to know what git *does*,\notherwise he wouldn't be looking in the manual.\n\n> +If all named commits are already ancestors of `HEAD`, 'git merge'\n> +will exit early with the message \"Already up-to-date.\"\n\n\n\n-- \nThomas Rast\ntrast@{inf,student}.ethz.ch\n"},{"id":"131424","messageId":"7vtyuqtrx4.fsf@alter.siamese.dyndns.org","threadId":"22117","inReplyTo":"20100111041318.GA9806@progeny.tock","subject":"Re: [PATCH v2 2/4] Documentation: warn prominently against merging with dirty trees","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-01-13T06:55:35Z","receivedAt":"2010-01-13T06:55:35Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jonathan Nieder writes:\n\n> | A merge is always between the current HEAD and one or more commits\n> | (usually, branch head or tag), and the index file must match the tree of\n> | HEAD commit (i.e. the contents of the last commit) when it starts out. In\n> | other words, git diff --cached HEAD must report no changes. (One exception\n> | is when the changed index entries are already in the same state that would\n> | result from the merge anyway.)\n>\n> The potentially problematic scenario for \"git reset --merge\" is this\n> last one, where a changed index entry is already in the same state\n> that would result from the merge. Would a \"git reset --merge\" reset\n> the changed contents away?\n\nIt will discard the change, the one you independently picked up, but the\nchange agreed with what was done by the the trash history that you are\ncancelling merge with. You wouldn't miss losing the same change as in\nthat trash history.\n"},{"id":"131459","messageId":"20100113104433.GC25382@machine.or.cz","threadId":"22117","inReplyTo":"20100111082123.GA23742@progeny.tock","subject":"Re: [PATCH 0/6] Re: Documentation: warn prominently against merging with dirty trees","fromName":"Petr Baudis","fromEmail":"pasky@suse.cz","sentAt":"2010-01-13T10:44:33Z","receivedAt":"2010-01-13T10:44:33Z","isPatch":true,"sender":{"key":"pasky@ucw.cz","avatar":"https://avatars.githubusercontent.com/u/18439?v=4"},"body":"On Mon, Jan 11, 2010 at 02:21:23AM -0600, Jonathan Nieder wrote:\n> Jonathan Nieder (6):\n> Documentation: clarify one-line description for merge\n\nI don't think this is an improvement and prefer the original phrasing.\n\n> Documentation: merge: move configuration section to the end\n\nAck.\n\nI will reply to the other patches in separate mails.\n\n\t\t\t\tPetr \"Pasky\" Baudis\n"},{"id":"131999","messageId":"7vpr58w6qn.fsf@alter.siamese.dyndns.org","threadId":"22117","inReplyTo":"7vfx6efox9.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH v2 0/4] Documentation style fixes","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-01-18T01:18:24Z","receivedAt":"2010-01-18T01:18:24Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"I think we have given people enough time to comment, so I am going to\nmerge 0b444cd (Documentation: spell 'git cmd' without dash throughout,\n2010-01-10) which was taken from the tip of your for-next branch and that\nhas been in 'pu' for the last week.\n"},{"id":"132120","messageId":"201001191829.19284.trast@student.ethz.ch","threadId":"22117","inReplyTo":"7vpr58w6qn.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH v2 0/4] Documentation style fixes","fromName":"Thomas Rast","fromEmail":"trast@student.ethz.ch","sentAt":"2010-01-19T17:29:17Z","receivedAt":"2010-01-19T17:29:17Z","isPatch":true,"sender":{"key":"tr@thomasrast.ch","avatar":"https://avatars.githubusercontent.com/u/153510?v=4"},"body":"Junio C Hamano wrote:\n> I think we have given people enough time to comment, so I am going to\n> merge 0b444cd (Documentation: spell 'git cmd' without dash throughout,\n> 2010-01-10) which was taken from the tip of your for-next branch and that\n> has been in 'pu' for the last week.\n\nOk, thanks.\n\nJonathan, do you plan on rerolling your 6-patch series with Pasky's\nand my comments? Otherwise I might give it a stab, since I like the\nseries and it would be a shame to just forget about it.\n\n-- \nThomas Rast\ntrast@{inf,student}.ethz.ch\n"},{"id":"132122","messageId":"20100119173934.GA6007@progeny.tock","threadId":"22117","inReplyTo":"201001191829.19284.trast@student.ethz.ch","subject":"Re: [PATCH v2 0/4] Documentation style fixes","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-01-19T17:39:35Z","receivedAt":"2010-01-19T17:39:35Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Thomas Rast wrote:\n\n> Jonathan, do you plan on rerolling your 6-patch series with Pasky's\n> and my comments?\n\nYes, I was planning to get to it today; sorry for the lack of noise.\n\nJonathan\n"},{"id":"132515","messageId":"20100123224840.GA2136@progeny.tock","threadId":"22117","inReplyTo":"201001101324.47025.trast@student.ethz.ch","subject":"[PATCH] Documentation: merge: use MERGE_HEAD to refer to the remote branch","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-01-23T22:48:40Z","receivedAt":"2010-01-23T22:48:40Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"commit 57bddb11 (Documentation/git-merge: reword references to\n\"remote\" and \"pull\", 2010-01-07) fixed the manual to drop the\nassumption that the other branch being merged is from a remote\nrepository. Unfortunately, in a few places, to do so it\nintroduced the antecedentless phrase \"their versions\". Worse, in\npassages like the following, 'they' is playing two roles.\n\n| highlighting changes from both the HEAD and their versions.\n|\n| * Look at the diffs on their own. 'git log --merge -p '\n\nUsing HEAD and MERGE_HEAD nicely assigns terminology to \"our\" and\n\"their\" sides. It also provides the reader with practice using\nnames that git will recognize on the command line.\n\nSigned-off-by: Jonathan Nieder \n---\nThomas Rast wrote:\n> Jonathan Nieder wrote:\n\n>> Maybe:\n>> \n>> | * Look at the diffs. 'git diff' will show a three-way diff,\n>> | highlighting changes from both the HEAD and MERGE_HEAD\n>> | versions.\n>\n> I like this idea, as it nicely assigns terminology to the \"their\"\n> side. We need to explain MERGE_HEAD (it's not in the manpage yet),\n> but that should fit in somewhere.\n\nHere is a try. This applies on top of the series to clarify 'git\nmerge' documentation [1] I sent earlier today, which conveniently\nenough explains MERGE_HEAD a few sections earlier.\n\nThanks for the encouragement,\nJonathan\n\n[1] http://thread.gmane.org/gmane.comp.version-control.git/137818\n\n Documentation/git-merge.txt | 14 ++++++++------\n 1 files changed, 8 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt\nindex 7aa3f3f..4b1b2f5 100644\n--- a/Documentation/git-merge.txt\n+++ b/Documentation/git-merge.txt\n@@ -215,15 +215,17 @@ You can work through the conflict with a number of tools:\n mergetool which will work you through the merge.\n \n * Look at the diffs. `git diff` will show a three-way diff,\n- highlighting changes from both the HEAD and their versions.\n+ highlighting changes from both the `HEAD` and `MERGE_HEAD`\n+ versions.\n \n- * Look at the diffs on their own. `git log --merge -p `\n- will show diffs first for the HEAD version and then\n- their version.\n+ * Look at the diffs from each branch. `git log --merge -p `\n+ will show diffs first for the `HEAD` version and then the\n+ `MERGE_HEAD` version.\n \n * Look at the originals. `git show :1:filename` shows the\n- common ancestor, `git show :2:filename` shows the HEAD\n- version and `git show :3:filename` shows their version.\n+ common ancestor, `git show :2:filename` shows the `HEAD`\n+ version, and `git show :3:filename` shows the `MERGE_HEAD`\n+ version.\n \n \n EXAMPLES\n-- \n1.6.6\n"}]}