wip

Documentation/curated-examples-from-issues.md

@@ -0,0 +1,105 @@
+# Curated examples from issues
+
+Lots of people have filed issues against git-filter-repo, and many times it
+boils down into questions of "How do I?" or "Why doesn't this work?"
+
+I thought I'd collect a bunch of these as example repository filterings
+that others may be interested in.
+
+## Table of Contents
+
+  * [Adding files to root commits](#adding-files-to-root-commits)
+  * [Purge a large list of files](#purge-a-large-list-of-files)
+
+## Adding files to root commits
+
+<!-- https://github.com/newren/git-filter-repo/issues/21 -->
+
+Here's an example that will take `/path/to/existing/README.md` and
+store it as `README.md` in the repository, and take
+`/home/myusers/mymodule.gitignore` and store it as `src/.gitignore` in
+the repository:
+
+```
+git filter-repo --commit-callback "if not commit.parents: commit.file_changes += [
+    FileChange(b'M', b'README.md', b'$(git hash-object -w '/path/to/existing/README.md')', b'100644'), 
+    FileChange(b'M', b'src/.gitignore', b'$(git hash-object -w '/home/myusers/mymodule.gitignore')', b'100644')]"
+```
+
+Alternatively, you could also use the [insert-beginning contrib script](../contrib/filter-repo-demos/insert-beginning).
+
+## Purge a large list of files
+
+Stick all the files in some file (one per line),
+e.g. ../DELETED_FILENAMES.txt, and then run
+
+```
+git filter-repo --invert-paths --paths-from-file ../DELETED_FILENAMES.txt
+```
+
+<!-- https://github.com/newren/git-filter-repo/issues/63 -->
+  nuking files previously deleted
+
+<!-- https://github.com/newren/git-filter-repo/issues/80 -->
+  extract library to separate repo
+
+<!-- https://github.com/newren/git-filter-repo/issues/83 -->
+  replace words in all commit messages
+
+<!-- https://github.com/newren/git-filter-repo/issues/91 -->
+  only keep files in repository that are present in latest commit
+
+<!-- https://github.com/newren/git-filter-repo/issues/122 -->
+  renormalize all end-of-line characters
+
+<!-- https://github.com/newren/git-filter-repo/issues/145 -->
+  removing spaces at end of lines (user example)
+
+<!-- https://github.com/newren/git-filter-repo/issues/230 -->
+  having both exclude and include rules for filenames
+
+<!-- https://github.com/newren/git-filter-repo/issues/268 -->
+  setting executable bit
+
+<!-- https://github.com/newren/git-filter-repo/issues/274 -->
+  another example for removing paths with a certain extension
+
+<!-- https://github.com/newren/git-filter-repo/issues/278 -->
+  removing a directory
+
+<!-- https://github.com/newren/git-filter-repo/issues/296 -->
+  NFD/NFC conversion
+
+<!-- https://github.com/newren/git-filter-repo/issues/379 -->
+  make committer match current user (to get past push hooks)
+
+<!-- https://github.com/newren/git-filter-repo/issues/383 -->
+  handling special characters, e.g. accents in names
+
+<!-- https://github.com/newren/git-filter-repo/issues/420 -->
+  handling repository corruption (old original objects are corrupt)
+
+<!-- https://github.com/newren/git-filter-repo/issues/427 -->
+  removing all files with a backslash in them (final example is best)
+
+<!-- https://github.com/newren/git-filter-repo/issues/436 -->
+  replace a binary blob in history
+
+<!-- https://github.com/newren/git-filter-repo/pull/542 -->
+  callback for lint-history
+
+<!-- https://github.com/newren/git-filter-repo/issues/300 -->
+  using replace refs to delete old history
+
+<!-- https://github.com/newren/git-filter-repo/issues/492 -->
+  replacing pngs with compressed alternative
+  (#537 also used a change.blob_id thingy)
+
+<!-- https://github.com/newren/git-filter-repo/issues/490 -->
+<!-- https://github.com/newren/git-filter-repo/issues/504 -->
+  need for a multi-step filtering to avoid path collisions or ordering issues
+
+<!-- https://lore.kernel.org/git/CABPp-BFqbiS8xsbLouNB41QTc5p0hEOy-EoV0Sjnp=xJEShkTw@mail.gmail.com/ -->
+  Two things:
+    textwrap.dedent
+    easier example of using git-filter-repo as a library