Git/firefox-user.js
1
0
Fork 0
mirror of https://github.com/arkenfox/user.js.git synced 2024-11-22 10:31:40 +01:00
Code Issues Packages Projects Releases Wiki Activity

Destroyed 1.1 Overview (markdown)

Thorin-Oakenpants 2022-01-29 05:16:27 +00:00
parent 379fa8a239
commit b22b1ab95d
1 changed files with 0 additions and 74 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

74
1.1-Overview.md

@ -1,74 +0,0 @@
Before you go jumping in, all excited, and dive in at the deep end, let's get some basics out the way.
And after this page, at the very least you need to read the [implementation](https://github.com/arkenfox/user.js/wiki/1.3-Implementation) page, as it contains important information regarding a few `arkenfox user.js` settings.
### :small_orange_diamond: What is it, what does it do, and why would I want one?
A `user.js`, which resides in the root directory of a profile, is used to set preferences for that `profile` <sup>[1]</sup> when Firefox starts. Preferences are settings that control Firefox's behavior. Some can be set from the Options interface and all can be found in `about:config`, except for what are called `hidden preferences` which will only show when they are set by the user.
[1] To find your profile, open `about:support` and look for `Profile Folder` under `Application Basics`
Here is how it basically works:
* Firefox starts
* Firefox reads the contents of `user.js` and writes to `prefs.js`
* It writes the active preferences, i.e not commented out
* It ignores the inactive or commented out preferences, i.e, it does not remove them from `prefs.js`
* If the preference is already in `prefs.js` it will overwrite it
* It parses the `user.js` in the order it is written, i.e if the same preference is listed twice with two different values, the last one will be applied last
* It will abort parsing the file if it encounters a syntax error, but will still apply any content up to that error
* :exclamation: In FF60+, not all syntax errors cause parsing to abort, see [this](https://blog.mozilla.org/nnethercote/2018/03/09/a-new-preferences-parser-for-firefox/) article
* It will not abort if you apply a data mismatch e.g if you set an integer instead of a string, it will actually write that data mismatch into `prefs.js`
* The `user.js` is now ignored until the next time Firefox starts
* Firefox opens
* The contents of `prefs.js` override the default values shown in `about:config`
* If a preference in `prefs.js` has a data mismatch, then it is ignored and the ~~default~~ **previous value** is retained (this could be the default or a user-set value set earlier within about:config) and shown in `about:config`
* In `about:config`
* All values stored in `prefs.js`, even if they are the default value, will be denoted as status `user set`. In Firefox 55+ it is denoted as `modified`
* If you set a value to a `user set`/`modified` value, it is stored in `prefs.js`
* If you reset a value to `default`, it is removed from `prefs.js`
* If you reset a `hidden preference` to default, the value will be blank, and assuming it is not applied again from a `user.js`, it will then vanish on the next about:config reload
tl;dr: firefox starts :arrow_right: user.js active preferences :arrow_right: prefs.js :left_right_arrow: `about:config` .. with caveats
That's a bit to digest, so here is a pretty picture showing a preference with the same value as status `user set`/`modified` and `default`. In `about:config's` search box, you can use wildcards (e.g `network*policy`) to save time typing, and it is case insensitive.
![](https://github.com/arkenfox/user.js/blob/master/wikipiki/overview03.png)
And why would you want a `user.js`?
* It is used to reset settings on a restart, making certain preferences more or less "permanent". You can still change preferences via about:config for testing
* It can be used to migrate a lot of settings to a new profile, and can be easily modified and deployed for multiple profiles
* There are a lot of preferences in `about:config`. There are over 3000 firefox ones alone. A `user.js` is a great repository for information. For example, it can be used as a basis for `mozilla.cfg` files and `lockprefs`.
* It can help you to better understand how to protect your privacy, enhance your security, and reduce fingerprinting
### :small_orange_diamond: Working with a user.js
The `user.js` file is a `javascript` file and is text based. If you use Windows, make sure you unhide extensions for known filetypes in Folder Options, so that the file isn't really called `user.js.txt`. It is recommended that you use an editor that supports syntax highlighting. You can edit and work on your `user.js` while Firefox is open, it is only ever read when Firefox is started.
![](https://github.com/arkenfox/user.js/blob/master/wikipiki/overview01.png)
Preferences must follow Mozilla's syntax which is `user_pref("prefname", value);`. Note that the preference name must be wrapped in quotation marks, and do not forget the semi-colon at the end. The value must also be wrapped in quotation marks, but only if it is a string. Preferences are case sensitive.
![](https://github.com/arkenfox/user.js/blob/master/wikipiki/overview02.png)
### :small_orange_diamond: Resetting preferences
To reset a preference, first comment it out - i.e you put `//` in front of it (and save the changes before the next Firefox start). As explained above, this does not reset it, but merely stops it from being set on every Firefox start. You then need to go to `about:config`, find the preference, right-click it, and select `Reset`.
Alternatively, you could change the value - but this could then be at odds with the description we supply (and some preference names/values can be misleading/ambiguous), so edit that if needed, or add a note to it: e.g.
```js
/* 2204: disable links opening in a new window ***/
user_pref("browser.link.open_newwindow.restriction", 0);
// if you wanted to change it you could use this
/* 2204: disable links opening in a new window ***/
user_pref("browser.link.open_newwindow.restriction", 2); // 0-disable, 2=enable
// or
/* 2204: ENABLE links opening in a new window ***/
user_pref("browser.link.open_newwindow.restriction", 2);
```
Note: Resetting values, or editing the `user.js` every time you update it is not ideal. It is recommended that you use an `overrides section` - see our [maintenance](https://github.com/arkenfox/user.js/wiki#small_orange_diamond-maintenance) section
Now you know the "what, why, where and how" of a `user.js`, you can check out how to [backup](https://github.com/arkenfox/user.js/wiki/1.2-Backing-Up) before [implementing](https://github.com/arkenfox/user.js/wiki/1.3-Implementation).