aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--README.md32
1 files changed, 21 insertions, 11 deletions
diff --git a/README.md b/README.md
index dc9bdf6..e265747 100644
--- a/README.md
+++ b/README.md
@@ -1,18 +1,12 @@
# change
-…transparent filesystem change tracking using function interposition.
+...transparent filesystem change tracking using function interposition.
This experimental project consists of a library `libChangeLog` and a matching wrapper bash script named `change`. If one opens any application using `change` it automatically tracks common system calls used for manipulating filesystem contents and provides the user with a short summary including _diffs_ where appropriate.
- λ ~/p/d/change ‣ change mv test example
+ > change mv test example
renamed 'test' to 'example'
- λ ~/p/d/change ‣ change vim example
- removed '5405'
- renamed 'example' to 'example~'
- removed 'example~'
- removed '/home/common/.viminfo'
- renamed '/home/common/.viminfk.tmp' to '/home/common/.viminfo'
- removed '/home/common/.vim/swap//%home%common%projects%dev%change%example.swp'
+ > change vim example
--- /home/common/projects/dev/change/example
+++ /home/common/projects/dev/change/example 2016-02-13 21:43:15.719355382 +0100
@@ -1,3 +1,5 @@
@@ -21,10 +15,26 @@ This experimental project consists of a library `libChangeLog` and a matching wr
2
+
3
- λ ~/p/d/change ‣ change rm example
+ > change rm example
removed 'example'
-As we can see the library currently still exposes some of the internal doings of e.g. _vim_ that we don't really want to see in our usecase. The goal is to develop `change` into a utility that can be dropped in front of any non-suid (function interposition via `LD_PRELOAD` is thankfully not allowed for suid-executables) shell command and generate a summary that will explain the actual happenings of a terminal session. While this is not very useful for simple, self-explanatory commands such as `mv $this $to_that` it is certainly helpful whenever files are changed by interactive applications that do not provide their own directly visible logging such as text editors. Such an application will in turn be useful for e.g. documenting shell sessions.
+The goal is to develop `change` into a utility that can be dropped in front of any non-suid (function interposition via `LD_PRELOAD` is thankfully not allowed for suid-executables) application and generate a summary that will explain the actual happenings of a terminal session. While this is not very useful for simple, self-explanatory commands such as `mv $this $to_that` it is certainly helpful whenever files are changed by interactive applications that do not provide their own directly visible logging such as text editors. Such an application will in turn be useful for e.g. documenting shell sessions.
+
+## Filtering
+
+Due to it's nature of interposing low level system calls such as `write` and `unlink` the library by default exposes lots of the internal write logic of the wrapped application. For instance it reports _vim_ creating a file called `4913` to verify the target directory's writability as well as the creation of various temporary backup files. While this is certainly interesting for debugging purposes it hinders the library's goal of providing a higher level summary consisting primarily of the actions the user explicity performed such as the changed file contents.
+
+To solve this problem one may provide a list of regular expressions to be matched against the file paths via the `CHANGE_LOG_IGNORE_PATTERN_PATH` environment variable.
+
+For example the following ruleset intructs the library to restrict the output `change vim $file` to a _diff_ of all files changed by the wrapped application:
+
+ # vim's way of verifying that it is able to create a file
+ [0-9]+
+ # temporary backup file during write
+ [^~]*~
+ # log and backup files
+ .*\.viminfo
+ .*\.sw[px]
## Build