From: Steven Black Date: Mon, 19 Dec 2016 04:43:52 +0000 (-0500) Subject: Format readme_template.md to wrap at 80-columns. X-Git-Url: http://git.99rst.org/?a=commitdiff_plain;h=745dc5882c9b190cb8baf198094143fb85c22af1;p=stevenblack-hosts.git Format readme_template.md to wrap at 80-columns. --- diff --git a/readme_template.md b/readme_template.md index d9f72ed4c..a31d2a60d 100644 --- a/readme_template.md +++ b/readme_template.md @@ -1,24 +1,29 @@ #Unified hosts file @EXTENSIONS_HEADER@ -This repository consolidates several reputable `hosts` files, and merges them into a unified hosts file -with duplicates removed. This repo provides several hosts files tailored to you need to block. +This repository consolidates several reputable `hosts` files, and merges them +into a unified hosts file with duplicates removed. This repo provides several +hosts files tailored to you need to block. * Last updated: **@GEN_DATE@**. * Here's the [raw hosts file @EXTENSIONS_HEADER@](https://raw.githubusercontent.com/StevenBlack/hosts/master/@SUBFOLDER@hosts) containing @NUM_ENTRIES@ entries. ### List of all hosts file variants -The **Non Github mirror** is the link to use for some hosts file managers like [Hostsman for Windows](http://www.abelhadigital.com/hostsman) that don't work with Github download links. +The **Non Github mirror** is the link to use for some hosts file managers like +[Hostsman for Windows](http://www.abelhadigital.com/hostsman) that don't work +with Github download links. Host file recipe | Readme | Raw hosts | hosts (.zip) | Unique domains | Non Github mirror ---------------- |:------:|:---------:|:------------:|:--------------:|:-------------: @TOCROWS@ -**Expectation**: These unified hosts files should serve all devices, regardless of OS. +**Expectation**: These unified hosts files should serve all devices, regardless +of OS. ## Sources of hosts data unified in this variant -Updated `hosts` files from the following locations are always unified and included: +Updated `hosts` files from the following locations are always unified and +included: Host file source | Description | Home page | Raw hosts | Update frequency -----------------|-------------|:---------:|:---------:|:-------: @@ -26,14 +31,17 @@ Host file source | Description | Home page | Raw hosts | Update frequency ## Extensions -The unified hosts file is extensible. You manage extensions by curating the `extensions/` folder tree. See the `social`, `gambling`, and `porn` extension folders. +The unified hosts file is extensible. You manage extensions by curating the +`extensions/` folder tree. See the `social`, `gambling`, and `porn` extension +folders. ## Generate your own unified hosts file -The `updateHostsFile.py` script, which is python 2.7 and Python 3-compatible, will generate a unified hosts file -based on the sources in the local `data/` subfolder. The script will prompt you Whether it should fetch updated -versions (from locations defined by the update.info text file in each source's folder), otherwise it will use the -`hosts` file that's already there. +The `updateHostsFile.py` script, which is python 2.7 and Python 3-compatible, +will generate a unified hosts file based on the sources in the local `data/` +subfolder. The script will prompt you Whether it should fetch updated +versions (from locations defined by the `update.json` text file in each +source's folder), otherwise it will use the `hosts` file that's already there. ### Usage @@ -52,74 +60,92 @@ versions (from locations defined by the update.info text file in each source's f `--auto`, or `-a`: run the script without prompting. When `--auto` is invoked, * Hosts data sources, including extensions, are updated. -* No extensions are included by default. Use the `--extensions` or `-e` flag to include any you want. -* Your active hosts file is *not* replaced unless you include the `--replace` flag. +* No extensions are included by default. Use the `--extensions` or `-e` flag +to include any you want. +* Your active hosts file is *not* replaced unless you include the `--replace` +flag. -`--backup`, or `-b`: Make a backup of existing hosts file(s) as you generate over them. +`--backup`, or `-b`: Make a backup of existing hosts file(s) as you generate +over them. -`--extensions `, or `-e `: the names of subfolders below the `extensions` folder -containing additional category-specific hosts files to include in the amalgamation. Example: `--extensions porn` or -`-e social porn`. +`--extensions `, or `-e `: the names +of subfolders below the `extensions` folder containing additional +category-specific hosts files to include in the amalgamation. Example: +`--extensions porn` or `-e social porn`. -`--flush-dns-cache`, or `-f`: skip the prompt for flushing the DNS cache. Only active when `--replace` is also active. +`--flush-dns-cache`, or `-f`: skip the prompt for flushing the DNS cache. +Only active when `--replace` is also active. -`--ip nnn.nnn.nnn.nnn`, or `-i nnn.nnn.nnn.nnn`: the IP address to use as the target. Default is `0.0.0.0`. +`--ip nnn.nnn.nnn.nnn`, or `-i nnn.nnn.nnn.nnn`: the IP address to use as the +target. Default is `0.0.0.0`. `--noupdate`, or `-n`: skip fetching updates from hosts data sources. -`--output `, or `-o `: place the generated source file in a subfolder. If the subfolder does not -exist, it will be created. +`--output `, or `-o `: place the generated source file +in a subfolder. If the subfolder does not exist, it will be created. `--replace`, or `-r`: trigger replacing your active hosts -`--skipstatichosts`, or `-s`: `false` (default) or `true`, omit the standard section, at the top containing lines like `127.0.0.1 localhost`. This is useful for configuring proximate DNS services on the local network. +`--skipstatichosts`, or `-s`: `false` (default) or `true`, omit the standard +`--section, at the top containing lines like `127.0.0.1 localhost`. This is +`--useful for configuring proximate DNS services on the local network. -`--zip`, or `-z`: `false` (default) or `true`, additionally create a zip archive of the hosts file named `hosts.zip`. +`--zip`, or `-z`: `false` (default) or `true`, additionally create a zip +`--archive of the hosts file named `hosts.zip`. ## How do I control which sources are unified? -Add one or more *additional* sources, each in a subfolder of the `data/` folder, and specify the `url` key in its `update.json` file. +Add one or more *additional* sources, each in a subfolder of the `data/` +folder, and specify the `url` key in its `update.json` file. -Add one or more *optional* extensions, which originate from subfolders of the `extensions/` folder. Again the url in -`update.info` controls where this extension finds its updates. +Add one or more *optional* extensions, which originate from subfolders of the +`extensions/` folder. Again the url in `update.json` controls where this +extension finds its updates. -Create an *optional* `blacklist` file. The contents of this file (containing a listing of additional domains in -`hosts` file format) are appended to the unified hosts file during the update process. A sample `blacklist` is +Create an *optional* `blacklist` file. The contents of this file (containing a +listing of additional domains in `hosts` file format) are appended to the +unified hosts file during the update process. A sample `blacklist` is included, and may be modified as you desire. - * NOTE: The `blacklist` is not tracked by git, so any changes you make won't be overridden when you `git pull` - this repo from `origin` in the future. + * NOTE: The `blacklist` is not tracked by git, so any changes you make won't +be overridden when you `git pull` this repo from `origin` in the future. ### How do I include my own custom domain mappings? -If you have custom hosts records, place them in file `myhosts`. The contents of this file are prepended to the -unified hosts file during the update process. +If you have custom hosts records, place them in file `myhosts`. The contents +of this file are prepended to the unified hosts file during the update +process. -The `myhosts` file is not tracked by git, so any changes you make won't be overridden when you `git pull` this repo from `origin` in the future. +The `myhosts` file is not tracked by git, so any changes you make won't be +overridden when you `git pull` this repo from `origin` in the future. ### How do I prevent domains from being included? -The domains you list in the `whitelist` file are excluded from the final hosts file. +The domains you list in the `whitelist` file are excluded from the final hosts +file. -The `whitelist` uses partial matching. Therefore if you whitelist `google-analytics.com`, that domain and all its -subdomains won't be merged into the final hosts file. +The `whitelist` uses partial matching. Therefore if you whitelist `google- +analytics.com`, that domain and all its subdomains won't be merged into the +final hosts file. -The `whitelist` is not tracked by git, so any changes you make won't be overridden when you `git pull` this repo -from `origin` in the future. +The `whitelist` is not tracked by git, so any changes you make won't be +overridden when you `git pull` this repo from `origin` in the future. ## What is a hosts file? -A hosts file, named `hosts` (with no file extension), is a plain-text file used by all operating -systems to map hostnames to IP addresses. +A hosts file, named `hosts` (with no file extension), is a plain-text file +used by all operating systems to map hostnames to IP addresses. -In most operating systems, the `hosts` file is preferential to `DNS`. Therefore if a domain name is -resolved by the `hosts` file, the request never leaves your computer. +In most operating systems, the `hosts` file is preferential to `DNS`. +Therefore if a domain name is resolved by the `hosts` file, the request never +leaves your computer. -Having a smart `hosts` file goes a long way towards blocking malware, adware, and other irritants. +Having a smart `hosts` file goes a long way towards blocking malware, adware, +and other irritants. -For example, to nullify requests to some doubleclick.net servers, adding these lines to your hosts -file will do it: +For example, to nullify requests to some doubleclick.net servers, adding these +lines to your hosts file will do it: # block doubleClick's servers 0.0.0.0 ad.ae.doubleclick.net @@ -229,13 +255,14 @@ The goals of this repo are to: 4. and keep the resultant file reasonably sized. -A high-quality source is defined here as one that is actively curated. A hosts source should be frequently -updated by its maintainers with both additions and removals. The larger the hosts file, the higher the level of +A high-quality source is defined here as one that is actively curated. A +hosts source should be frequently updated by its maintainers with both +additions and removals. The larger the hosts file, the higher the level of curation is expected. -For example, the (huge) hosts file from [hosts-file.net](http://hosts-file.net) is **not** included -here because it is very large (300,000+ entries) and doesn't currently display a corresponding high level of curation -activity. +For example, the (huge) hosts file from [hosts-file.net](http://hosts- +file.net) is **not** included here because it is very large (300,000+ entries) +and doesn't currently display a corresponding high level of curation activity. -It is expected that this unified hosts file will serve both desktop and mobile devices under a variety of operating -systems. +It is expected that this unified hosts file will serve both desktop and mobile +devices under a variety of operating systems.