add readme

1 files changed, 63 insertions, 0 deletions

diff --git a/firefox-sideloader/README.md b/firefox-sideloader/README.md
new file mode 100644
index 0000000..1e1cbad
--- /dev/null
+++ b/firefox-sideloader/README.md
@@ -0,0 +1,63 @@
+# firefox-sideloader
+
+### How to use
+
+The following session demonstrates how to use.
+
+Mostly all you need:
+```
+[u@h:~/firefox-sideloader]$ . functions.sh
+[u@h:~/firefox-sideloader]$ clone_default_profile MyNewProfileName
+[u@h:~/firefox-sideloader]$ firefox -P MyNewProfileName
+```
+
+The profile MyNewProfileName will now start up with all extensions copied from
+the default profile. Effort was made not to copy any settings or leak any
+private data, so that the new profile can be redistributed as a firefox default
+startup state.
+
+Also possible:
+```
+[u@h:~/firefox-sideloader]$ clone_profile MyNewProfileName SecondGenerationClone
+[u@h:~/firefox-sideloader]$ firefox -P SecondGenerationClone
+```
+
+### Future
+
+The next feature (unimplemented but needed) is to change the target home
+directory of the profile. Then the `clone_profile` function becomes
+suitable to use when creating a new home directory (i.e. a dynamic
+/etc/skel/ to work around Firefox's internal dependence on absolute
+paths).  This is the whole point of this code from my perspective.
+
+### Counter-factual Future
+
+Another obvious direction to take this code would be to make it work on existing
+profiles, rather than being confined to creating a new profile.
+
+The `jq` queries in this codebase illustrate how/where it would be possible to
+insert one extension at a time into an existing profile without damaging it.
+Just merge the output of those queries back into the JSON input files. The tool
+`jq` itself can make the changes needed. It's obviously the right and robust way
+to go about this, but I don't have a personal need for it.
+
+### By the way
+
+Another useful function:
+
+```
+[u@h:~/firefox-sideloader]$ list_extensions
+{"id":"uBlock0@raymondhill.net","name":"uBlock Origin"}
+{"id":"bypasspaywalls@bypasspaywalls.weebly.com","name":null}
+{"id":"default-theme@mozilla.org","name":null}
+[...]
+```
+
+Check another profile than the default like this:
+```
+[u@h:~/firefox-sideloader]$ list_extensions SecondGenerationClone
+[u@h:~/firefox-sideloader]$ list_extensions ~someotheruser/.mozilla/firefox/randomstring.profilename/
+```
+
+It should just accept a profile name as an argument and do that itself, but it
+does not.