{"thread":{"id":"10945","subject":"[PATCH] Improve documentation of git-filter-branch rev-list specification.","startedAt":"2007-11-20T18:32:39Z","lastAt":"2007-11-21T07:49:29Z","messageCount":4,"participants":["Carl Worth","Johannes Schindelin","Johannes Sixt"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"60425","messageId":"877ikc3gzc.wl%cworth@cworth.org","threadId":"10945","inReplyTo":null,"subject":"[PATCH] Improve documentation of git-filter-branch rev-list specification.","fromName":"Carl Worth","fromEmail":"cworth@cworth.org","sentAt":"2007-11-20T18:32:39Z","receivedAt":"2007-11-20T18:32:39Z","isPatch":true,"sender":{"key":"cworth@cworth.org","avatar":"https://gravatar.com/avatar/3746dc28cde609bdbd7f939058356e7e2bbd16d21e32274df0725eb3d998bc5b?d=mp&s=160"},"body":"The rev-list is not optional, and a range of a..b will not rewrite\nonly b. Fix these errors and improve the wording of surrounding text.\n\nAlso eliminate the discussion of using no filters to compensate for\nhypothetical future bugs. It's not helpful.\n---\n Documentation/git-filter-branch.txt |   34 ++++++++++++++++++++--------------\n 1 files changed, 20 insertions(+), 14 deletions(-)\n\ndiff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt\nindex ba9b4fb..985d7d5 100644\n--- a/Documentation/git-filter-branch.txt\n+++ b/Documentation/git-filter-branch.txt\n@@ -13,23 +13,29 @@ SYNOPSIS\n \t[--msg-filter <command>] [--commit-filter <command>]\n \t[--tag-name-filter <command>] [--subdirectory-filter <directory>]\n \t[--original <namespace>] [-d <directory>] [-f | --force]\n-\t[<rev-list options>...]\n+\t<rev-list options>...\n \n DESCRIPTION\n -----------\n-Lets you rewrite git revision history by rewriting the branches mentioned\n-in the <rev-list options>, 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-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-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-therefore such a usage is permitted.\n+Rewrites git revision history by applying one or more filters to a set\n+of commits. The set of commits to be rewritten is supplied in\n+<rev-list options> and can be as simple as one or more branch names,\n+(in which case all commits reachable from those branch names will be\n+rewritten).\n+\n+The filters can modify the tree content stored in each commit,\n+(e.g. removing a file or running a perl rewrite on all files), or the\n+associated information about each commit, (commit message, author,\n+parent, etc.). Any information not affected by a filter (including\n+original commit times or merge information) will be preserved. If you\n+specify no filters, the commits will be recommitted without any\n+changes.\n+\n+Note that passing a range of commits specified with the a..b notation\n+will rewrite 'b' and all commits reachable from 'b' but not reachable\n+from 'a', but will not rewrite the commit 'a' itself. This is\n+consistent with the handling of a range by git-log and other git\n+commands.\n \n *WARNING*! The rewritten history will have different object names for all\n the objects and will not converge with the original branch.  You will not\n-- \n1.5.3.4\n"},{"id":"60435","messageId":"8763zw3el9.wl%cworth@cworth.org","threadId":"10945","inReplyTo":"877ikc3gzc.wl%cworth@cworth.org","subject":"Ideas for improving the filter-branch workflow","fromName":"Carl Worth","fromEmail":"cworth@cworth.org","sentAt":"2007-11-20T19:24:18Z","receivedAt":"2007-11-20T19:24:18Z","isPatch":false,"sender":{"key":"cworth@cworth.org","avatar":"https://gravatar.com/avatar/3746dc28cde609bdbd7f939058356e7e2bbd16d21e32274df0725eb3d998bc5b?d=mp&s=160"},"body":"On Tue, 20 Nov 2007 10:32:39 -0800, Carl Worth wrote:\n> The rev-list is not optional, and a range of a..b will not rewrite\n> only b.\n\nIt has since been explained to me that the original text was intended\nto describe which branch tips will get updated. In that case, my\nrewrite of the documentation leaves that part out.\n\nEven so, I'm a bit confused by what the behavior is. When I run:\n\n\tgit filter-branch HEAD\n\nThe output I get is:\n\n\tRef 'refs/heads/master' was rewritten\n\n\tThese refs were rewritten:\n\nAnd nothing else after that. That's definitely confusing.\n\nAlso confusing is that the documentation emphasizes that I should\nverify the newly rewritten heads against the backups in\nrefs/original. But I'm not given any guidance on how to access the\nrefs in refs/original. I don't know of standard git tools to list\nthese, (\"git branch\", \"git branch -r\", and \"gitk --all\" don't show\nthem for example). I can use something like \"git log\noriginal/refs/heads/master\" but it takes a fair amount of knowledge to\nget to that point.\n\nFinally, I did my filter in multiple steps and found myself having to\ndo lots of manual cleanup. For example, on my second run of\ngit-filter-branch:\n\n\tError:\t\tNamespace refs/original/ not empty\n\tCleanup:\trm -r .git/refs/original\n\nAnd that failed attempt then triggers another problem:\n\n\tError:\t\t.git-rewrite already exists, please remove it\n\tCleanup:\trm -r .git-rewrite\n\nThe second error was nice enough to tell me how to fix the problem,\n(nothing ever indicates the need to cleanup refs/original that I can\ntell). But I think this second error should never occur. The\nfilter-branch program should cleanup after itself if it fails.\n\nFinally, I wonder if there's a better solution to the messiness of\nmaking backups in refs/original, correctly documenting what branch\nheads get rewritten, and then hoping that the user can find the\nbackups, use them to verify the new heads, and then clean them up.\n\nOne idea is to have two new sub-commands for git-filter-branch. Maybe\nsomething like:\n\n\tgit filter-branch --accept\n\tgit filter-branch --reject\t# or --undo or whatever\n\nAnd these would do all the cleanup necessary.\n\nDuring the intermediate state, (after filter-branch and before\n\"filter-branch --accept\"), it would be nice if it were easier to\nverify the results. For example, if filter-branch stored its backups\nin refs/heads/rewrite-original/* instead of refs/original/refs/heads/*\nthen they would show up automatically in \"gitk --all\" for example.\n\nAnyway, those are some ideas if anyone wants to hack on this further.\n\n-Carl\n"},{"id":"60441","messageId":"Pine.LNX.4.64.0711202223150.27959@racer.site","threadId":"10945","inReplyTo":"877ikc3gzc.wl%cworth@cworth.org","subject":"Re: [PATCH] Improve documentation of git-filter-branch rev-list specification.","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2007-11-20T22:28:01Z","receivedAt":"2007-11-20T22:28:01Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi,\n\nOn Tue, 20 Nov 2007, Carl Worth wrote:\n\n> diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt\n> index ba9b4fb..985d7d5 100644\n> --- a/Documentation/git-filter-branch.txt\n> +++ b/Documentation/git-filter-branch.txt\n> @@ -13,23 +13,29 @@ SYNOPSIS\n>  \t[--msg-filter <command>] [--commit-filter <command>]\n>  \t[--tag-name-filter <command>] [--subdirectory-filter <directory>]\n>  \t[--original <namespace>] [-d <directory>] [-f | --force]\n> -\t[<rev-list options>...]\n> +\t<rev-list options>...\n\nThis is correct AFAICT.\n\n>  DESCRIPTION\n>  -----------\n> -Lets you rewrite git revision history by rewriting the branches mentioned\n> -in the <rev-list options>, 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> -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> -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> -therefore such a usage is permitted.\n> +Rewrites git revision history by applying one or more filters to a set\n> +of commits. The set of commits to be rewritten is supplied in\n> +<rev-list options> and can be as simple as one or more branch names,\n> +(in which case all commits reachable from those branch names will be\n> +rewritten).\n\nI do not particularly like that you say \"commits to be rewritten\".  \nBecause not the commits, but the branches are rewritten.  For example, if \nyou have branch A and B pointing to the same commit and you call \nfilter-branch on A, B will be left untouched _along with its commits_.\n\nIMHO the old version -- while maybe not as eloquent as yours -- made that \nvery clear.\n\nThis was probably the reason you confused the comment about a..b earlier.\n\nSo I would appreciate rewriting the documentation in such a way that the \ndistinction between a commit and a ref is maintained clearly.\n\nCiao,\nDscho\n"},{"id":"60481","messageId":"4743E309.4090707@viscovery.net","threadId":"10945","inReplyTo":"877ikc3gzc.wl%cworth@cworth.org","subject":"Re: [PATCH] Improve documentation of git-filter-branch rev-list specification.","fromName":"Johannes Sixt","fromEmail":"j.sixt@viscovery.net","sentAt":"2007-11-21T07:49:29Z","receivedAt":"2007-11-21T07:49:29Z","isPatch":true,"sender":{"key":"j6t@kdbg.org","avatar":"https://avatars.githubusercontent.com/u/14810926?v=4"},"body":"Carl Worth schrieb:\n> +The filters can modify the tree content stored in each commit,\n> +(e.g. removing a file or running a perl rewrite on all files), or the\n> +associated information about each commit, (commit message, author,\n> +parent, etc.). Any information not affected by a filter (including\n> +original commit times or merge information) will be preserved. If you\n> +specify no filters, the commits will be recommitted without any\n> +changes.\n\n\"... will be recommitted without any changes as long as no grafted parents \nare encountered. Any grafted parents will be written into the commits even \nif no filters are specified.\"\n\n-- Hannes\n"}]}