undef/git-commit-vandalism
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

doc: indent multi-line items in list

Browse Source 
Although Asciidoc allows to not indent following lines in a list item,
it is clearer and safer to follow the recommended rule.

Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This commit is contained in:
Jean-Noël Avila 2019-12-12 21:46:55 +01:00 committed by Junio C Hamano
parent fd5041e127
commit df5be01669
2 changed files with 129 additions and 120 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

229
Documentation/git-filter-branch.txt
View File

@ -466,10 +466,10 @@ The performance of git-filter-branch is glacially slow; its design makes it
impossible for a backward-compatible implementation to ever be fast: impossible for a backward-compatible implementation to ever be fast:
* In editing files, git-filter-branch by design checks out each and * In editing files, git-filter-branch by design checks out each and
every commit as it existed in the original repo. If your repo has 10\^5 every commit as it existed in the original repo. If your repo has
files and 10\^5 commits, but each commit only modifies 5 files, then 10\^5 files and 10\^5 commits, but each commit only modifies 5
git-filter-branch will make you do 10\^10 modifications, despite only files, then git-filter-branch will make you do 10\^10 modifications,
having (at most) 5*10^5 unique blobs. despite only having (at most) 5*10^5 unique blobs.
* If you try and cheat and try to make git-filter-branch only work on * If you try and cheat and try to make git-filter-branch only work on
files modified in a commit, then two things happen files modified in a commit, then two things happen
@ -481,33 +481,35 @@ files modified in a commit, then two things happen
user-provided shell) user-provided shell)
** even if you succeed at the map-deletes-for-renames chicanery, you ** even if you succeed at the map-deletes-for-renames chicanery, you
still technically violate backward compatibility because users are still technically violate backward compatibility because users
allowed to filter files in ways that depend upon topology of are allowed to filter files in ways that depend upon topology of
commits instead of filtering solely based on file contents or names commits instead of filtering solely based on file contents or
(though this has not been observed in the wild). names (though this has not been observed in the wild).
* Even if you don't need to edit files but only want to e.g. rename or * Even if you don't need to edit files but only want to e.g. rename or
remove some and thus can avoid checking out each file (i.e. you can use remove some and thus can avoid checking out each file (i.e. you can
--index-filter), you still are passing shell snippets for your filters. use --index-filter), you still are passing shell snippets for your
This means that for every commit, you have to have a prepared git repo filters. This means that for every commit, you have to have a
where those filters can be run. That's a significant setup. prepared git repo where those filters can be run. That's a
significant setup.
* Further, several additional files are created or updated per commit by * Further, several additional files are created or updated per commit
git-filter-branch. Some of these are for supporting the convenience by git-filter-branch. Some of these are for supporting the
functions provided by git-filter-branch (such as map()), while others convenience functions provided by git-filter-branch (such as map()),
are for keeping track of internal state (but could have also been while others are for keeping track of internal state (but could have
accessed by user filters; one of git-filter-branch's regression tests also been accessed by user filters; one of git-filter-branch's
does so). This essentially amounts to using the filesystem as an IPC regression tests does so). This essentially amounts to using the
mechanism between git-filter-branch and the user-provided filters. filesystem as an IPC mechanism between git-filter-branch and the
Disks tend to be a slow IPC mechanism, and writing these files also user-provided filters. Disks tend to be a slow IPC mechanism, and
effectively represents a forced synchronization point between separate writing these files also effectively represents a forced
processes that we hit with every commit. synchronization point between separate processes that we hit with
every commit.
* The user-provided shell commands will likely involve a pipeline of * The user-provided shell commands will likely involve a pipeline of
commands, resulting in the creation of many processes per commit. commands, resulting in the creation of many processes per commit.
Creating and running another process takes a widely varying amount of Creating and running another process takes a widely varying amount
time between operating systems, but on any platform it is very slow of time between operating systems, but on any platform it is very
relative to invoking a function. slow relative to invoking a function.
* git-filter-branch itself is written in shell, which is kind of slow. * git-filter-branch itself is written in shell, which is kind of slow.
This is the one performance issue that could be backward-compatibly This is the one performance issue that could be backward-compatibly
@ -546,51 +548,55 @@ easily corrupt repos or end up with a mess worse than what you started
with: with:
* Someone can have a set of "working and tested filters" which they * Someone can have a set of "working and tested filters" which they
document or provide to a coworker, who then runs them on a different OS document or provide to a coworker, who then runs them on a different
where the same commands are not working/tested (some examples in the OS where the same commands are not working/tested (some examples in
git-filter-branch manpage are also affected by this). BSD vs. GNU the git-filter-branch manpage are also affected by this).
userland differences can really bite. If lucky, error messages are BSD vs. GNU userland differences can really bite. If lucky, error
spewed. But just as likely, the commands either don't do the filtering messages are spewed. But just as likely, the commands either don't
requested, or silently corrupt by making some unwanted change. The do the filtering requested, or silently corrupt by making some
unwanted change may only affect a few commits, so it's not necessarily unwanted change. The unwanted change may only affect a few commits,
obvious either. (The fact that problems won't necessarily be obvious so it's not necessarily obvious either. (The fact that problems
means they are likely to go unnoticed until the rewritten history is in won't necessarily be obvious means they are likely to go unnoticed
use for quite a while, at which point it's really hard to justify until the rewritten history is in use for quite a while, at which
another flag-day for another rewrite.) point it's really hard to justify another flag-day for another
rewrite.)
* Filenames with spaces are often mishandled by shell snippets since * Filenames with spaces are often mishandled by shell snippets since
they cause problems for shell pipelines. Not everyone is familiar with they cause problems for shell pipelines. Not everyone is familiar
find -print0, xargs -0, git-ls-files -z, etc. Even people who are with find -print0, xargs -0, git-ls-files -z, etc. Even people who
familiar with these may assume such flags are not relevant because are familiar with these may assume such flags are not relevant
someone else renamed any such files in their repo back before the person because someone else renamed any such files in their repo back
doing the filtering joined the project. And often, even those familiar before the person doing the filtering joined the project. And
with handling arguments with spaces may not do so just because they often, even those familiar with handling arguments with spaces may
aren't in the mindset of thinking about everything that could possibly not do so just because they aren't in the mindset of thinking about
go wrong. everything that could possibly go wrong.
* Non-ascii filenames can be silently removed despite being in a desired * Non-ascii filenames can be silently removed despite being in a
directory. Keeping only wanted paths is often done using pipelines like desired directory. Keeping only wanted paths is often done using
`git ls-files | grep -v ^WANTED_DIR/ | xargs git rm`. ls-files will pipelines like `git ls-files | grep -v ^WANTED_DIR/ | xargs git rm`.
only quote filenames if needed, so folks may not notice that one of the ls-files will only quote filenames if needed, so folks may not
files didn't match the regex (at least not until it's much too late). notice that one of the files didn't match the regex (at least not
Yes, someone who knows about core.quotePath can avoid this (unless they until it's much too late). Yes, someone who knows about
have other special characters like \t, \n, or "), and people who use core.quotePath can avoid this (unless they have other special
ls-files -z with something other than grep can avoid this, but that characters like \t, \n, or "), and people who use ls-files -z with
doesn't mean they will. something other than grep can avoid this, but that doesn't mean they
will.
* Similarly, when moving files around, one can find that filenames with * Similarly, when moving files around, one can find that filenames
non-ascii or special characters end up in a different directory, one with non-ascii or special characters end up in a different
that includes a double quote character. (This is technically the same directory, one that includes a double quote character. (This is
issue as above with quoting, but perhaps an interesting different way technically the same issue as above with quoting, but perhaps an
that it can and has manifested as a problem.) interesting different way that it can and has manifested as a
problem.)
* It's far too easy to accidentally mix up old and new history. It's * It's far too easy to accidentally mix up old and new history. It's
still possible with any tool, but git-filter-branch almost invites it. still possible with any tool, but git-filter-branch almost
If lucky, the only downside is users getting frustrated that they don't invites it. If lucky, the only downside is users getting frustrated
know how to shrink their repo and remove the old stuff. If unlucky, that they don't know how to shrink their repo and remove the old
they merge old and new history and end up with multiple "copies" of each stuff. If unlucky, they merge old and new history and end up with
commit, some of which have unwanted or sensitive files and others which multiple "copies" of each commit, some of which have unwanted or
don't. This comes about in multiple different ways: sensitive files and others which don't. This comes about in
multiple different ways:
** the default to only doing a partial history rewrite ('--all' is not ** the default to only doing a partial history rewrite ('--all' is not
the default and few examples show it) the default and few examples show it)
@ -609,8 +615,8 @@ don't. This comes about in multiple different ways:
"DISCUSSION" section of the git filter-repo manual page for more "DISCUSSION" section of the git filter-repo manual page for more
details. details.
* Annotated tags can be accidentally converted to lightweight tags, due * Annotated tags can be accidentally converted to lightweight tags,
to either of two issues: due to either of two issues:
** Someone can do a history rewrite, realize they messed up, restore ** Someone can do a history rewrite, realize they messed up, restore
from the backups in refs/original/, and then redo their from the backups in refs/original/, and then redo their
@ -623,71 +629,74 @@ to either of two issues:
restored from refs/original/ in a previously botched rewrite). restored from refs/original/ in a previously botched rewrite).
* Any commit messages that specify an encoding will become corrupted * Any commit messages that specify an encoding will become corrupted
by the rewrite; git-filter-branch ignores the encoding, takes the original by the rewrite; git-filter-branch ignores the encoding, takes the
bytes, and feeds it to commit-tree without telling it the proper original bytes, and feeds it to commit-tree without telling it the
encoding. (This happens whether or not --msg-filter is used.) proper encoding. (This happens whether or not --msg-filter is
used.)
* Commit messages (even if they are all UTF-8) by default become * Commit messages (even if they are all UTF-8) by default become
corrupted due to not being updated -- any references to other commit corrupted due to not being updated -- any references to other commit
hashes in commit messages will now refer to no-longer-extant commits. hashes in commit messages will now refer to no-longer-extant
commits.
* There are no facilities for helping users find what unwanted crud they * There are no facilities for helping users find what unwanted crud
should delete, which means they are much more likely to have incomplete they should delete, which means they are much more likely to have
or partial cleanups that sometimes result in confusion and people incomplete or partial cleanups that sometimes result in confusion
wasting time trying to understand. (For example, folks tend to just and people wasting time trying to understand. (For example, folks
look for big files to delete instead of big directories or extensions, tend to just look for big files to delete instead of big directories
and once they do so, then sometime later folks using the new repository or extensions, and once they do so, then sometime later folks using
who are going through history will notice a build artifact directory the new repository who are going through history will notice a build
that has some files but not others, or a cache of dependencies artifact directory that has some files but not others, or a cache of
(node_modules or similar) which couldn't have ever been functional since dependencies (node_modules or similar) which couldn't have ever been
it's missing some files.) functional since it's missing some files.)
* If --prune-empty isn't specified, then the filtering process can * If --prune-empty isn't specified, then the filtering process can
create hoards of confusing empty commits create hoards of confusing empty commits
* If --prune-empty is specified, then intentionally placed empty * If --prune-empty is specified, then intentionally placed empty
commits from before the filtering operation are also pruned instead of commits from before the filtering operation are also pruned instead
just pruning commits that became empty due to filtering rules. of just pruning commits that became empty due to filtering rules.
* If --prune empty is specified, sometimes empty commits are missed * If --prune empty is specified, sometimes empty commits are missed
and left around anyway (a somewhat rare bug, but it happens...) and left around anyway (a somewhat rare bug, but it happens...)
* A minor issue, but users who have a goal to update all names and * A minor issue, but users who have a goal to update all names and
emails in a repository may be led to --env-filter which will only update emails in a repository may be led to --env-filter which will only
authors and committers, missing taggers. update authors and committers, missing taggers.
* If the user provides a --tag-name-filter that maps multiple tags to * If the user provides a --tag-name-filter that maps multiple tags to
the same name, no warning or error is provided; git-filter-branch simply the same name, no warning or error is provided; git-filter-branch
overwrites each tag in some undocumented pre-defined order resulting in simply overwrites each tag in some undocumented pre-defined order
only one tag at the end. (A git-filter-branch regression test requires resulting in only one tag at the end. (A git-filter-branch
this surprising behavior.) regression test requires this surprising behavior.)
Also, the poor performance of git-filter-branch often leads to safety Also, the poor performance of git-filter-branch often leads to safety
issues: issues:
* Coming up with the correct shell snippet to do the filtering you want * Coming up with the correct shell snippet to do the filtering you
is sometimes difficult unless you're just doing a trivial modification want is sometimes difficult unless you're just doing a trivial
such as deleting a couple files. Unfortunately, people often learn if modification such as deleting a couple files. Unfortunately, people
the snippet is right or wrong by trying it out, but the rightness or often learn if the snippet is right or wrong by trying it out, but
wrongness can vary depending on special circumstances (spaces in the rightness or wrongness can vary depending on special
filenames, non-ascii filenames, funny author names or emails, invalid circumstances (spaces in filenames, non-ascii filenames, funny
timezones, presence of grafts or replace objects, etc.), meaning they author names or emails, invalid timezones, presence of grafts or
may have to wait a long time, hit an error, then restart. The replace objects, etc.), meaning they may have to wait a long time,
performance of git-filter-branch is so bad that this cycle is painful, hit an error, then restart. The performance of git-filter-branch is
reducing the time available to carefully re-check (to say nothing about so bad that this cycle is painful, reducing the time available to
what it does to the patience of the person doing the rewrite even if carefully re-check (to say nothing about what it does to the
they do technically have more time available). This problem is extra patience of the person doing the rewrite even if they do technically
compounded because errors from broken filters may not be shown for a have more time available). This problem is extra compounded because
long time and/or get lost in a sea of output. Even worse, broken errors from broken filters may not be shown for a long time and/or
filters often just result in silent incorrect rewrites. get lost in a sea of output. Even worse, broken filters often just
result in silent incorrect rewrites.
* To top it all off, even when users finally find working commands, they * To top it all off, even when users finally find working commands,
naturally want to share them. But they may be unaware that their repo they naturally want to share them. But they may be unaware that
didn't have some special cases that someone else's does. So, when their repo didn't have some special cases that someone else's does.
someone else with a different repository runs the same commands, they So, when someone else with a different repository runs the same
get hit by the problems above. Or, the user just runs commands that commands, they get hit by the problems above. Or, the user just
really were vetted for special cases, but they run it on a different OS runs commands that really were vetted for special cases, but they
where it doesn't work, as noted above. run it on a different OS where it doesn't work, as noted above.
GIT GIT
--- ---