{"thread":{"id":"12705","subject":"[PATCH] Improve description of git filter-branch.","startedAt":"2008-03-15T10:39:00Z","lastAt":"2008-03-20T21:30:32Z","messageCount":5,"participants":["Ralf Wildenhues","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"72173","messageId":"20080315103900.GC14769@ins.uni-bonn.de","threadId":"12705","inReplyTo":null,"subject":"[PATCH] Improve description of git filter-branch.","fromName":"Ralf Wildenhues","fromEmail":"ralf.wildenhues@gmx.de","sentAt":"2008-03-15T10:39:00Z","receivedAt":"2008-03-15T10:39:00Z","isPatch":true,"sender":{"key":"ralf.wildenhues@gmx.de","avatar":null},"body":"Signed-off-by: Ralf Wildenhues \n---\n\nNow that I learned about filter-branch, here's my share of nits with its\ndocumentation, a couple of language nits and inaccuracies.\n\nOne problem was that I originally understood the manual in the way that\nonly --env-filter may be used to modify GIT_AUTHOR_NAME etc., and thus\nI failed to see how with the fixed order I could change that with data\ntaken from the tree. \n\nAlso, I think it is quite helpful to state that all filters operate in\nthe shell environment of the script (this may be an issue for a later\nconversion to a builtin).\n\nCheers,\nRalf\n\n Documentation/git-filter-branch.txt | 25 +++++++++++++------------\n 1 files changed, 13 insertions(+), 12 deletions(-)\n\ndiff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt\nindex 543a1cf..3f7df04 100644\n--- a/Documentation/git-filter-branch.txt\n+++ b/Documentation/git-filter-branch.txt\n@@ -20,12 +20,12 @@ DESCRIPTION\n Lets you rewrite git revision history by rewriting the branches mentioned\n in the , applying custom filters on each revision.\n Those filters can modify each tree (e.g. removing a file or running\n-a perl rewrite on all files) or information about each commit.\n+a perl script on all files) or information about each commit.\n Otherwise, all information (including original commit times or merge\n information) will be preserved.\n \n The command will only rewrite the _positive_ refs mentioned in the\n-command line (i.e. if you pass 'a..b', only 'b' will be rewritten).\n+command line (i.e. if you pass 'a..b', 'a' will not be rewritten).\n If you specify no filters, the commits will be recommitted without any\n changes, which would normally have no effect. Nevertheless, this may be\n useful in the future for compensating for some git bugs or such,\n@@ -42,7 +42,7 @@ Always verify that the rewritten version is correct: The original refs,\n if different from the rewritten ones, will be stored in the namespace\n 'refs/original/'.\n \n-Note that since this operation is extensively I/O expensive, it might\n+Note that since this operation is extremely I/O expensive, it might\n be a good idea to redirect the temporary directory off-disk with the\n '-d' option, e.g. on tmpfs. Reportedly the speedup is very noticeable.\n \n@@ -51,14 +51,15 @@ Filters\n ~~~~~~~\n \n The filters are applied in the order as listed below. The \n-argument is always evaluated in shell using the 'eval' command (with the\n-notable exception of the commit filter, for technical reasons).\n+argument is always evaluated in the shell context using the 'eval' command\n+(with the notable exception of the commit filter, for technical reasons).\n Prior to that, the $GIT_COMMIT environment variable will be set to contain\n the id of the commit being rewritten. Also, GIT_AUTHOR_NAME,\n GIT_AUTHOR_EMAIL, GIT_AUTHOR_DATE, GIT_COMMITTER_NAME, GIT_COMMITTER_EMAIL,\n-and GIT_COMMITTER_DATE are set according to the current commit. If any\n-evaluation of returns a non-zero exit status, the whole operation\n-will be aborted.\n+and GIT_COMMITTER_DATE are set according to the current commit. The values\n+of these variables after the filters have run, are used for the new commit.\n+If any evaluation of returns a non-zero exit status, the whole\n+operation will be aborted.\n \n A 'map' function is available that takes an \"original sha1 id\" argument\n and outputs a \"rewritten sha1 id\" if the commit has been already\n@@ -71,9 +72,9 @@ OPTIONS\n -------\n \n --env-filter ::\n-\tThis is the filter for modifying the environment in which\n-\tthe commit will be performed. Specifically, you might want\n-\tto rewrite the author/committer name/email/time environment\n+\tThis filter may be used if you only need to modify the environment\n+\tin which the commit will be performed. Specifically, you might\n+\twant to rewrite the author/committer name/email/time environment\n \tvariables (see linkgit:git-commit[1] for details). Do not forget\n \tto re-export the variables.\n \n@@ -149,7 +150,7 @@ definition impossible to preserve signatures at any rate.)\n -d ::\n \tUse this option to set the path to the temporary directory used for\n \trewriting. When applying a tree filter, the command needs to\n-\ttemporary checkout the tree to some directory, which may consume\n+\ttemporarily checkout the tree to some directory, which may consume\n \tconsiderable space in case of large projects. By default it\n \tdoes this in the '.git-rewrite/' directory but you can override\n \tthat choice by this parameter.\n-- \n1.5.4.4.603.g1f9f\n"},{"id":"72522","messageId":"20080320154338.GA4741@ins.uni-bonn.de","threadId":"12705","inReplyTo":"20080315103900.GC14769@ins.uni-bonn.de","subject":"Re: [PATCH] Improve description of git filter-branch.","fromName":"Ralf Wildenhues","fromEmail":"ralf.wildenhues@gmx.de","sentAt":"2008-03-20T15:43:38Z","receivedAt":"2008-03-20T15:43:38Z","isPatch":true,"sender":{"key":"ralf.wildenhues@gmx.de","avatar":null},"body":"\n\n* Ralf Wildenhues wrote on Sat, Mar 15, 2008 at 11:39:00AM CET:\n> \n> Now that I learned about filter-branch, here's my share of nits with its\n> documentation, a couple of language nits and inaccuracies.\n[...]\n\nI noted that this wasn't applied. Is there something (or everything? ;-)\nwrong with the patch?\n\nThanks,\nRalf\n\n> Documentation/git-filter-branch.txt | 25 +++++++++++++------------\n> 1 files changed, 13 insertions(+), 12 deletions(-)\n"},{"id":"72523","messageId":"7v3aqlxs7e.fsf@gitster.siamese.dyndns.org","threadId":"12705","inReplyTo":"20080320154338.GA4741@ins.uni-bonn.de","subject":"Re: [PATCH] Improve description of git filter-branch.","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2008-03-20T16:42:29Z","receivedAt":"2008-03-20T16:42:29Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ralf Wildenhues writes:\n\n> * Ralf Wildenhues wrote on Sat, Mar 15, 2008 at 11:39:00AM CET:\n>> \n>> Now that I learned about filter-branch, here's my share of nits with its\n>> documentation, a couple of language nits and inaccuracies.\n> [...]\n>\n> I noted that this wasn't applied. Is there something (or everything? ;-)\n> wrong with the patch?\n\nNo, but I have not see anybody commented on it, so it was hard to tell if\nthere was anything good with the patch, either ;-)\n"},{"id":"72536","messageId":"7v8x0dw5sx.fsf@gitster.siamese.dyndns.org","threadId":"12705","inReplyTo":"20080315103900.GC14769@ins.uni-bonn.de","subject":"Re: [PATCH] Improve description of git filter-branch.","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2008-03-20T19:31:42Z","receivedAt":"2008-03-20T19:31:42Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ralf Wildenhues writes:\n\n> diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt\n> index 543a1cf..3f7df04 100644\n> --- a/Documentation/git-filter-branch.txt\n> +++ b/Documentation/git-filter-branch.txt\n> @@ -20,12 +20,12 @@ DESCRIPTION\n> Lets you rewrite git revision history by rewriting the branches mentioned\n> in the , applying custom filters on each revision.\n> Those filters can modify each tree (e.g. removing a file or running\n> -a perl rewrite on all files) or information about each commit.\n> +a perl script on all files) or information about each commit.\n> Otherwise, all information (including original commit times or merge\n> information) will be preserved.\n\nWe could go either way, methinks. IOW, your update is not worse, but not\na huge improvement either.\n\n> The command will only rewrite the _positive_ refs mentioned in the\n> -command line (i.e. if you pass 'a..b', only 'b' will be rewritten).\n> +command line (i.e. if you pass 'a..b', 'a' will not be rewritten).\n\nThis one talks about which refs (i.e. pointers to commit DAG) are\nrewritten, not about which commits are rewritten. Because there are only\ntwo things, 'a' and 'b', are involved (remember, the statement does not\ntalk anything about the commits in between), \"only 'b' will\" and \"'a' will\nnot\" are the same thing.\n\nSaying \"only 'b'\" would actually make it more consistent with the body of\nthe description: \"We only rewrite _positive_ ones\" (i.e. it does not say\n\"We do not rewrite negative ones\").\n\nBy the way, that \"i.e.\" should probably be \"e.g.\".\n\n> @@ -42,7 +42,7 @@ Always verify that the rewritten version is correct: The original refs,\n> if different from the rewritten ones, will be stored in the namespace\n> 'refs/original/'.\n> \n> -Note that since this operation is extensively I/O expensive, it might\n> +Note that since this operation is extremely I/O expensive, it might\n> be a good idea to redirect the temporary directory off-disk with the\n> '-d' option, e.g. on tmpfs. Reportedly the speedup is very noticeable.\n\nCan we say \"very\"? extremely/extensively expensive is using ex'es\nexcessively to express what can be said in much easier way, I think.\n\n> @@ -51,14 +51,15 @@ Filters\n> ~~~~~~~\n> \n> The filters are applied in the order as listed below. The \n> -argument is always evaluated in shell using the 'eval' command (with the\n> -notable exception of the commit filter, for technical reasons).\n> +argument is always evaluated in the shell context using the 'eval' command\n> +(with the notable exception of the commit filter, for technical reasons).\n\nOk.\n\n> Prior to that, the $GIT_COMMIT environment variable will be set to contain\n> the id of the commit being rewritten. Also, GIT_AUTHOR_NAME,\n> GIT_AUTHOR_EMAIL, GIT_AUTHOR_DATE, GIT_COMMITTER_NAME, GIT_COMMITTER_EMAIL,\n> -and GIT_COMMITTER_DATE are set according to the current commit. If any\n> -evaluation of returns a non-zero exit status, the whole operation\n> -will be aborted.\n> +and GIT_COMMITTER_DATE are set according to the current commit. The values\n> +of these variables after the filters have run, are used for the new commit.\n> +If any evaluation of returns a non-zero exit status, the whole\n> +operation will be aborted.\n\nProbably a good clarification, but I am currently too busy to check if the\nadditional sentence is correct.\n\n> @@ -71,9 +72,9 @@ OPTIONS\n> -------\n> \n> --env-filter ::\n> -\tThis is the filter for modifying the environment in which\n> -\tthe commit will be performed. Specifically, you might want\n> -\tto rewrite the author/committer name/email/time environment\n> +\tThis filter may be used if you only need to modify the environment\n> +\tin which the commit will be performed. Specifically, you might\n> +\twant to rewrite the author/committer name/email/time environment\n\nOk. Without needless line rewrapping this would have been much less time\nconsuming to review, though.\n\n> @@ -149,7 +150,7 @@ definition impossible to preserve signatures at any rate.)\n> -d ::\n> \tUse this option to set the path to the temporary directory used for\n> \trewriting. When applying a tree filter, the command needs to\n> -\ttemporary checkout the tree to some directory, which may consume\n> +\ttemporarily checkout the tree to some directory, which may consume\n\nOk, but isn't the verb to \"check out\" two words?\n"},{"id":"72540","messageId":"20080320213032.GO11261@ins.uni-bonn.de","threadId":"12705","inReplyTo":"7v8x0dw5sx.fsf@gitster.siamese.dyndns.org","subject":"[PATCH] Improve description of git filter-branch.","fromName":"Ralf Wildenhues","fromEmail":"ralf.wildenhues@gmx.de","sentAt":"2008-03-20T21:30:32Z","receivedAt":"2008-03-20T21:30:32Z","isPatch":true,"sender":{"key":"ralf.wildenhues@gmx.de","avatar":null},"body":"Signed-off-by: Ralf Wildenhues \n---\n\n* Junio C Hamano wrote on Thu, Mar 20, 2008 at 08:31:42PM CET:\n> Ralf Wildenhues writes:\n> \n> > +\tThis filter may be used if you only need to modify the environment\n> > +\tin which the commit will be performed. Specifically, you might\n> > +\twant to rewrite the author/committer name/email/time environment\n> \n> Ok. Without needless line rewrapping this would have been much less time\n> consuming to review, though.\n\nApologies, and thanks for the review. Here's an updated patch.\n\nCheers,\nRalf\n\n Documentation/git-filter-branch.txt | 23 ++++++++++++-----------\n 1 files changed, 12 insertions(+), 11 deletions(-)\n\ndiff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt\nindex 543a1cf..2a78549 100644\n--- a/Documentation/git-filter-branch.txt\n+++ b/Documentation/git-filter-branch.txt\n@@ -25,7 +25,7 @@ Otherwise, all information (including original commit times or merge\n information) will be preserved.\n \n The command will only rewrite the _positive_ refs mentioned in the\n-command line (i.e. if you pass 'a..b', only 'b' will be rewritten).\n+command line (e.g. if you pass 'a..b', only 'b' will be rewritten).\n If you specify no filters, the commits will be recommitted without any\n changes, which would normally have no effect. Nevertheless, this may be\n useful in the future for compensating for some git bugs or such,\n@@ -42,7 +42,7 @@ Always verify that the rewritten version is correct: The original refs,\n if different from the rewritten ones, will be stored in the namespace\n 'refs/original/'.\n \n-Note that since this operation is extensively I/O expensive, it might\n+Note that since this operation is very I/O expensive, it might\n be a good idea to redirect the temporary directory off-disk with the\n '-d' option, e.g. on tmpfs. Reportedly the speedup is very noticeable.\n \n@@ -51,14 +51,15 @@ Filters\n ~~~~~~~\n \n The filters are applied in the order as listed below. The \n-argument is always evaluated in shell using the 'eval' command (with the\n-notable exception of the commit filter, for technical reasons).\n+argument is always evaluated in the shell context using the 'eval' command\n+(with the notable exception of the commit filter, for technical reasons).\n Prior to that, the $GIT_COMMIT environment variable will be set to contain\n the id of the commit being rewritten. Also, GIT_AUTHOR_NAME,\n GIT_AUTHOR_EMAIL, GIT_AUTHOR_DATE, GIT_COMMITTER_NAME, GIT_COMMITTER_EMAIL,\n-and GIT_COMMITTER_DATE are set according to the current commit. If any\n-evaluation of returns a non-zero exit status, the whole operation\n-will be aborted.\n+and GIT_COMMITTER_DATE are set according to the current commit. The values\n+of these variables after the filters have run, are used for the new commit.\n+If any evaluation of returns a non-zero exit status, the whole\n+operation will be aborted.\n \n A 'map' function is available that takes an \"original sha1 id\" argument\n and outputs a \"rewritten sha1 id\" if the commit has been already\n@@ -71,9 +72,9 @@ OPTIONS\n -------\n \n --env-filter ::\n-\tThis is the filter for modifying the environment in which\n-\tthe commit will be performed. Specifically, you might want\n-\tto rewrite the author/committer name/email/time environment\n+\tThis filter may be used if you only need to modify the environment\n+\tin which the commit will be performed. Specifically, you might\n+\twant to rewrite the author/committer name/email/time environment\n \tvariables (see linkgit:git-commit[1] for details). Do not forget\n \tto re-export the variables.\n \n@@ -149,7 +150,7 @@ definition impossible to preserve signatures at any rate.)\n -d ::\n \tUse this option to set the path to the temporary directory used for\n \trewriting. When applying a tree filter, the command needs to\n-\ttemporary checkout the tree to some directory, which may consume\n+\ttemporarily check out the tree to some directory, which may consume\n \tconsiderable space in case of large projects. By default it\n \tdoes this in the '.git-rewrite/' directory but you can override\n \tthat choice by this parameter.\n-- \n1.5.5.rc0.22.g65daf\n"}]}