path: root/Documentation/git-filter-branch.txt
AgeCommit message (Collapse)Author
2010-01-10Documentation: spell 'git cmd' without dash throughoutThomas Rast
The documentation was quite inconsistent when spelling 'git cmd' if it only refers to the program, not to some specific invocation syntax: both 'git-cmd' and 'git cmd' spellings exist. The current trend goes towards dashless forms, and there is precedent in 647ac70 (git-svn.txt: stop using dash-form of commands., 2009-07-07) to actively eliminate the dashed variants. Replace 'git-cmd' with 'git cmd' throughout, except where git-shell, git-cvsserver, git-upload-pack, git-receive-pack, and git-upload-archive are concerned, because those really live in the $PATH.
2010-01-10Documentation: format full commands in typewriter fontThomas Rast
Use `code snippet` style instead of 'emphasis' for `git cmd ...` according to the following rules: * The SYNOPSIS sections are left untouched. * If the intent is that the user type the command exactly as given, it is `code`. If the user is only loosely referred to a command and/or option, it remains 'emphasised'. Signed-off-by: Thomas Rast <>
2009-11-13filter-branch: nearest-ancestor rewriting outside subdir filterThomas Rast
Since a0e4639 (filter-branch: fix ref rewriting with --subdirectory-filter, 2008-08-12) git-filter-branch has done nearest-ancestor rewriting when using a --subdirectory-filter. However, that rewriting strategy is also a useful building block in other tasks. For example, if you want to split out a subset of files from your history, you would typically call git filter-branch -- <refs> -- <files> But this fails for all refs that do not point directly to a commit that affects <files>, because their referenced commit will not be rewritten and the ref remains untouched. The code was already there for the --subdirectory-filter case, so just introduce an option that enables it independently. Signed-off-by: Thomas Rast <> Signed-off-by: Johannes Sixt <> Signed-off-by: Junio C Hamano <>
2009-10-02filter-branch: add --prune-empty to option summaryAdam Brewster
Signed-off-by: Adam Brewster <> Signed-off-by: Jeff King <>
2009-08-18filter-branch: add an example how to add ACKs to a range of commitsJohannes Schindelin
When you have to add certain lines like ACKs (or for that matter, Signed-off-by:s) to a range of commits starting with HEAD, you might be tempted to use 'git rebase -i -10', but that is a waste of your time. It is better to use 'git filter-branch' with an appropriate message filter, and this commit adds an example how to do so to filter-branch's man page. Signed-off-by: Johannes Schindelin <> Signed-off-by: Junio C Hamano <>
2009-04-12Merge branch 'maint'Junio C Hamano
* maint: GIT State the effect of filter-branch on graft explicitly process_{tree,blob}: Remove useless xstrdup calls Conflicts: GIT-VERSION-GEN
2009-04-12Merge branch 'maint-1.6.1' into maintJunio C Hamano
* maint-1.6.1: State the effect of filter-branch on graft explicitly process_{tree,blob}: Remove useless xstrdup calls
2009-04-12Merge branch 'maint-1.6.0' into maint-1.6.1Junio C Hamano
* maint-1.6.0: State the effect of filter-branch on graft explicitly process_{tree,blob}: Remove useless xstrdup calls
2009-04-12State the effect of filter-branch on graft explicitlyDaniel Cheng (aka SDiZ)
Signed-off-by: Daniel Cheng (aka SDiZ) <> Signed-off-by: Junio C Hamano <>
2009-03-12Documentation: filter-branch: show --ignore-unmatch in main index-filter exampleThomas Rast
Rearrange the example usage of git filter-branch --index-filter 'git rm --cached ...' so that --ignore-unmatch is in the main example block. People keep stumbling over the (lack of this) option to the point where it is a FAQ, so we would want to expose the most common usage where it stands out. Signed-off-by: Thomas Rast <> Signed-off-by: Junio C Hamano <>
2009-02-15Documentation: pruning recipe for destructive filter-branchThomas Rast
Add a section about how to shrink a repository's size after running git-filter-branch to remove large blobs from history. This comes up every week or so on IRC, and the commands required to handle every case are not very newbie-friendly, so hopefully writing them down somewhere leads to fewer questions. It may seem contradictory to document fallbacks for older Gits in newer docs, but we want to point people at this as a FAQ answer, and they will frequently not have the newest version installed. Thanks to Björn Steinbrink and Junio C Hamano for comments and corrections. Signed-off-by: Thomas Rast <> Signed-off-by: Junio C Hamano <>
2009-02-12Add 'rm -f' equivalent to 'git rm' example of filter-branch --index-filterJacob Helwig
Signed-off-by: Jacob Helwig <> Signed-off-by: Junio C Hamano <>
2009-01-11filter-branch: add git_commit_non_empty_tree and --prune-empty.Pierre Habouzit
git_commit_non_empty_tree is added to the functions that can be run from commit filters. Its effect is to commit only commits actually touching the tree and that are not merge points either. The option --prune-empty is added. It defaults the commit-filter to 'git_commit_non_empty_tree "$@"', and can be used with any other combination of filters, except --commit-hook that must used 'git_commit_non_empty_tree "$@"' where one puts 'git commit-tree "$@"' usually to achieve the same result. Signed-off-by: Pierre Habouzit <> Signed-off-by: Junio C Hamano <>
2008-09-16Documentation: Refer to git-rebase(1) to warn against rewritingThomas Rast
This points readers at the "Recovering from upstream rebase" warning in git-rebase(1) when we talk about rewriting published history in the 'reset', 'commit --amend', and 'filter-branch' documentation. Signed-off-by: Thomas Rast <> Signed-off-by: Junio C Hamano <>
2008-08-08Documentation: filter-branch: document how to filter all refsThomas Rast
Document the '--' option that can be used to pass rev-list options (not just arguments), and give an example usage of '-- --all'. Remove reference to "the new branch name"; filter-branch takes arbitrary arguments to rev-list since dfd05e3. Signed-off-by: Thomas Rast <> Signed-off-by: Junio C Hamano <>
2008-07-31Make the DESCRIPTION match <x>... items in the SYNOPSISAbhijit Menon-Sen
When the SYNOPSIS says e.g. "<path>...", it is nice if the DESCRIPTION also mentions "<path>..." and says the specified "paths" (note plural) are used for $whatever. This fixes the obvious mismatches. Signed-off-by: Abhijit Menon-Sen <> Signed-off-by: Junio C Hamano <>
2008-07-23Documentation/git-filter-branch: teach "rm" instead of "update-index --remove"Petr Baudis
The example to remove paths using index-filter was done with "git update-index --remove"; "git rm --cached" would be more familiar to new people and is sufficient for this particular case. Signed-off-by: Petr Baudis <> Signed-off-by: Junio C Hamano <>
2008-07-05manpages: italicize git command names (which were in teletype font)Jonathan Nieder
The names of git commands are not meant to be entered at the commandline; they are just names. So we render them in italics, as is usual for command names in manpages. Using doit () { perl -e 'for (<>) { s/\`(git-[^\`.]*)\`/'\''\1'\''/g; print }' } for i in git*.txt config.txt diff*.txt blame*.txt fetch*.txt i18n.txt \ merge*.txt pretty*.txt pull*.txt rev*.txt urls*.txt do doit <"$i" >"$i+" && mv "$i+" "$i" done git diff . Signed-off-by: Jonathan Nieder <> Signed-off-by: Junio C Hamano <>
2008-07-05Documentation: more "git-" versus "git " changesJonathan Nieder
With git-commands moving out of $(bindir), it is useful to make a clearer distinction between the git subcommand 'git-whatever' and the command you type, `git whatever <options>`. So we use a dash after "git" when referring to the former and not the latter. I already sent a patch doing this same thing, but I missed some spots. Signed-off-by: Jonathan Nieder <> Signed-off-by: Junio C Hamano <>
2008-07-02Documentation formatting and cleanupJonathan Nieder
Following what appears to be the predominant style, format names of commands and commandlines both as `teletype text`. While we're at it, add articles ("a" and "the") in some places, italicize the name of the command in the manual page synopsis line, and add a comma or two where it seems appropriate. Signed-off-by: Jonathan Nieder <> Signed-off-by: Junio C Hamano <>
2008-07-02Documentation: be consistent about "git-" versus "git "Jonathan Nieder
Since the git-* commands are not installed in $(bindir), using "git-command <parameters>" in examples in the documentation is not a good idea. On the other hand, it is nice to be able to refer to each command using one hyphenated word. (There is no escaping it, anyway: man page names cannot have spaces in them.) This patch retains the dash in naming an operation, command, program, process, or action. Complete command lines that can be entered at a shell (i.e., without options omitted) are made to use the dashless form. The changes consist only of replacing some spaces with hyphens and vice versa. After a "s/ /-/g", the unpatched and patched versions are identical. Signed-off-by: Jonathan Nieder <> Signed-off-by: Junio C Hamano <>
2008-06-08Docs: Use "-l::\n--long\n" format in OPTIONS sectionsStephan Beyer
The OPTIONS section of a documentation file contains a list of the options a git command accepts. Currently there are several variants to describe the case that different options (almost) do the same in the OPTIONS section. Some are: -f, --foo:: -f|--foo:: -f | --foo:: But AsciiDoc has the special form: -f:: --foo:: This patch applies this form to the documentation of the whole git suite, and removes useless em-dash prevention, so \--foo becomes --foo. Signed-off-by: Stephan Beyer <> Signed-off-by: Junio C Hamano <>
2008-06-06documentation: move git(7) to git(1)Christian Couder
As the "git" man page describes the "git" command at the end-user level, it seems better to move it to man section 1. Signed-off-by: Christian Couder <> Signed-off-by: Junio C Hamano <>
2008-06-03Documentation/git-filter-branch.txt: Fix description of --commit-filterKevin Ballard
The old description was misleading and logically impossible. It claimed that the ancestors of the original commit would be re-written to have the multiple emitted ids as parents. Not only would this modify existing objects, but it would create a cycle. What this actually does is pass the multiple emitted ids to the newly-created children to use as parents. Signed-off-by: Kevin Ballard <> Signed-off-by: Junio C Hamano <>
2008-05-17Merge branch 'maint'Junio C Hamano
* maint: git-filter-branch: Clarify file removal example.
2008-05-16git-filter-branch: Clarify file removal example.Jon Loeliger
Signed-off-by: Jon Loeliger <> Signed-off-by: Junio C Hamano <>
2008-05-06Merge branch 'bc/filter-branch'Junio C Hamano
* bc/filter-branch: support nearly proper tag name filtering
2008-05-04Merge branch 'maint-1.5.4' into maintJunio C Hamano
* maint-1.5.4: filter-branch: Documentation fix.
2008-05-03filter-branch: Documentation fix.Florian Ragwitz
It's --msg-filter, not --message-filter. Signed-off-by: Florian Ragwitz <> Signed-off-by: Junio C Hamano <> support nearly proper tag name filteringBrandon Casey
Add support for creating a new tag object and retaining the tag message, author, and date when rewriting tags. The gpg signature, if one exists, will be stripped. This adds nearly proper tag name filtering to filter-branch. Proper tag name filtering would include the ability to change the tagger, tag date, tag message, and _not_ strip a gpg signature if the tag did not change. Signed-off-by: Brandon Casey <> Signed-off-by: Junio C Hamano <>
2008-03-23Improve description of git filter-branch.Ralf Wildenhues
Signed-off-by: Ralf Wildenhues <> Signed-off-by: Junio C Hamano <>
2008-02-26filter-branch documentation: non-zero exit status in command abort the filterCaio Marcelo de Oliveira Filho
Since commit 8c1ce0f46b85d40f215084eed7313896300082df filter-branch fails when a <command> has a non-zero exit status. This commit makes it clear in the documentation and also fixes the parent-filter example, that was incorrectly returning non-zero when the commit being tested wasn't the one to be rewritten. Signed-off-by: Caio Marcelo de Oliveira Filho <> Signed-off-by: Junio C Hamano <>
2008-02-25Documentation/git-filter-branch: add a new msg-filter exampleMiklos Vajna
There were no example on how to edit commit messages, so add an msg-filter example. Signed-off-by: Miklos Vajna <> Signed-off-by: Junio C Hamano <>
2008-01-31Revert "filter-branch docs: remove brackets so not to imply revision arg is ↵Junio C Hamano
optional" This reverts commit c41b439244c51b30c60953192816afc91e552578, as we decided to default to HEAD when revision parameters are missing and they are no longer mandatory.
2008-01-31filter-branch docs: remove brackets so not to imply revision arg is optionalBrandon Casey
Signed-off-by: Brandon Casey <> Signed-off-by: Junio C Hamano <>
2008-01-07Documentation: rename gitlink macro to linkgitDan McGee
Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <> Signed-off-by: Junio C Hamano <>
2007-11-02Remove escaping of '|' in manpage option sectionsJonas Fonseca
The escaped were ending up verbatim in the generated documentation. Signed-off-by: Jonas Fonseca <> Signed-off-by: Junio C Hamano <>
2007-11-01git-filter-branch.txt: fix a typo.Sergei Organov
Signed-off-by: Sergei Organov <> Acked-by: Johannes Schindelin <> Signed-off-by: Junio C Hamano <>
2007-10-17fix filter-branch documentationJohannes Schindelin
The man page for filter-branch still talked about writing the result to the branch "newbranch". This is hopefully the last place where the old behaviour was described. Noticed by Bill Lear. Signed-off-by: Johannes Schindelin <> Signed-off-by: Shawn O. Pearce <>
2007-09-14Remove duplicate note about removing commits with git-filter-branchUlrik Sverdrup
A duplicate of an already existing section in the documentation of git-filter-branch was added in commit f95eef15f2f8a336b9a42749f5458c841a5a5d63. This patch removes that redundant section. Signed-off-by: Ulrik Sverdrup <> Signed-off-by: Junio C Hamano <>
2007-09-01filter-branch: introduce convenience function "skip_commit"Johannes Schindelin
With this function, a commit filter can leave out unwanted commits (such as temporary commits). It does _not_ undo the changeset corresponding to that commit, but it _skips_ the revision. IOW no tree object is changed by this. If you like to commit early and often, but want to filter out all intermediate commits, marked by "@@@" in the commit message, you can now do this with git filter-branch --commit-filter ' if git cat-file commit $GIT_COMMIT | grep '@@@' > /dev/null; then skip_commit "$@"; else git commit-tree "$@"; fi' newbranch Signed-off-by: Johannes Schindelin <> Signed-off-by: Junio C Hamano <>
2007-09-01filter-branch: provide the convenience functions also for commit filtersJohannes Schindelin
Move the convenience functions to the top of, and return from the script when the environment variable SOURCE_FUNCTIONS is set. By sourcing git-filter-branch with that variable set automatically, all commit filters may access the convenience functions like "map". Signed-off-by: Johannes Schindelin <> Signed-off-by: Junio C Hamano <>
2007-09-01filter-branch: fix remnants of old syntax in documentationJohannes Schindelin
Some time ago, filter-branch's syntax changed so that more than one ref can be rewritten at the same time. This involved the removal of the ref name for the result; instead, the refs are rewritten in-place. This updates the last leftovers in the documentation to reflect the new behavior. Signed-off-by: Johannes Schindelin <> Signed-off-by: Junio C Hamano <>
2007-08-31git-filter-branch: document --original optionGiuseppe Bilotta
Signed-off-by: Giuseppe Bilotta <> Signed-off-by: Junio C Hamano <>
2007-08-17Minor clarifications to git-filter-branch usage and docBrian Gernhardt
- Remove "DESTBRANCH" from usage, as it rewrites the branches given. - Remove an = from an example usage, as the script doesn't understand it. Signed-off-by: Brian Gernhardt <> Signed-off-by: Junio C Hamano <>
2007-07-24filter-branch: Big syntax change; support rewriting multiple refsJohannes Schindelin
We used to take the first non-option argument as the name for the new branch. This syntax is not extensible to support rewriting more than just HEAD. Instead, we now have the following syntax: git filter-branch [<filter options>...] [<rev-list options>] All positive refs given in <rev-list options> are rewritten. Yes, in-place. If a ref was changed, the original head is stored in refs/original/$ref now, for your inspecting pleasure, in addition to the reflogs (since it is easier to inspect "git show-ref | grep original" than to inspect all the reflogs). This commit also adds the --force option to remove .git-rewrite/ and all refs from refs/original/ before filtering. Signed-off-by: Johannes Schindelin <> Signed-off-by: Junio C Hamano <>
2007-07-06filter-branch documentation: clarify which filters are eval'edJohannes Schindelin
All filters, except the commit filter, are evaluated. Signed-off-by: Johannes Schindelin <> Signed-off-by: Junio C Hamano <>
2007-07-04filter-branch documentation: some more touch-ups.Johannes Sixt
- The map function used to fail, but no longer does (since 3520e1e8687.) - Fix the "edge-graft" example. - Show the same using .git/info/grafts. Signed-off-by: Johannes Sixt <> Signed-off-by: Junio C Hamano <>
2007-07-04filter-branch: a few more touch ups to the man pageJohannes Schindelin
All based on comments from Frank Lichtenheld. Signed-off-by: Johannes Schindelin <> Acked-by: Frank Lichtenheld <> Signed-off-by: Junio C Hamano <>
2007-07-04Document git-filter-branchJohannes Schindelin
This moves the documentation in to its own man page, with a few touch ups (incorporating comments by Frank Lichtenheld). Signed-off-by: Johannes Schindelin <> Signed-off-by: Junio C Hamano <>