Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update ReadMe with info about usage in new environments #887

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open

Update ReadMe with info about usage in new environments #887

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
54829f1
Remove bad practices from ReadMe
FossPrime Apr 27, 2022
246c754
Sprinkle outdated semi-colons
FossPrime Apr 27, 2022
c759e3a
Update README.md
FossPrime Jun 5, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
93 changes: 49 additions & 44 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ technique. Works in Node.js and web browsers.
## Installation

```bash
$ npm install debug
npm install debug
```

## Usage
Expand All @@ -20,9 +20,9 @@ $ npm install debug
Example [_app.js_](./examples/node/app.js):

```js
var debug = require('debug')('http')
, http = require('http')
, name = 'My App';
const createDebug = require('debug'); // import createDebug from 'debug'
const debug = createDebug('http');
const name = 'My App';

// fake app

Expand All @@ -43,18 +43,19 @@ require('./worker');
Example [_worker.js_](./examples/node/worker.js):

```js
var a = require('debug')('worker:a')
, b = require('debug')('worker:b');
const createDebug = require('debug')
const debugA = createDebug('worker:a')
const debugB = createDebug('worker:b');

function work() {
a('doing lots of uninteresting work');
debugA('doing lots of uninteresting work');
setTimeout(work, Math.random() * 1000);
}

work();

function workb() {
b('doing some work');
debugB('doing some work');
setTimeout(workb, Math.random() * 2000);
}

Expand All @@ -70,39 +71,36 @@ Here are some examples:
<img width="647" alt="screen shot 2017-08-08 at 12 53 38 pm" src="https://user-images.githubusercontent.com/71256/29091700-a62a6888-7c38-11e7-800b-db911291ca2b.png">
<img width="647" alt="screen shot 2017-08-08 at 12 53 25 pm" src="https://user-images.githubusercontent.com/71256/29091701-a62ea114-7c38-11e7-826a-2692bedca740.png">

#### Windows command prompt notes
#### Command Line Ussage

##### CMD
The following examples allow all messages from any package that supports debug, but hides messages from packages whose name starts with socket.io.

On Windows the environment variable is set using the `set` command.
##### Linux / Mac posix shell

```cmd
set DEBUG=*,-not_this
```sh
DEBUG="*,-socket.io" npm run dev
```

Example:
##### CMD

On Windows the environment variable is set using the `set` command.

```cmd
set DEBUG=*,-socket.io
set DEBUG=* & node app.js
```

##### PowerShell (VS Code default)
##### PowerShell

PowerShell uses different syntax to set environment variables.

```cmd
$env:DEBUG = "*,-not_this"
```

Example:

```cmd
$env:DEBUG = "*,-socket.io"
$env:DEBUG='app';node app.js
```

Then, run the program to be debugged as usual.
Then, run the program to be debugged as usual. npm script example:

npm script example:
```js
"windowsDebug": "@powershell -Command $env:DEBUG='*';node app.js",
```
Expand Down Expand Up @@ -216,7 +214,7 @@ debug('this is hex: %h', new Buffer('hello world'))

You can build a browser-ready script using [browserify](https://github.com/substack/node-browserify),
or just use the [browserify-as-a-service](https://wzrd.in/) [build](https://wzrd.in/standalone/debug@latest),
if you don't want to build it yourself.
if you don't want to build it yourself. Importing directly from script element with `type="module"` set will cause an error.

Debug's enable state is currently persisted by `localStorage`.
Consider the situation shown below where you have `worker:a` and `worker:b`,
Expand Down Expand Up @@ -252,31 +250,32 @@ In Chromium-based web browsers (e.g. Brave, Chrome, and Electron), the JavaScrip
Example [_stdout.js_](./examples/node/stdout.js):

```js
var debug = require('debug');
var error = debug('app:error');
const Debug = require('debug');
const error = Debug('app:error');

// by default stderr is used
error('goes to stderr!');

var log = debug('app:log');
const log = debug('app:log');
// set this namespace to log via console.log
log.log = console.log.bind(console); // don't forget to bind to console!
log('goes to stdout');
error('still goes to stderr!');

// set all output to go via console.info
// overrides all per-namespace log settings
debug.log = console.info.bind(console);
Debug.log = console.info.bind(console);
error('now goes to stdout via console.info');
log('still goes to stdout, but via console.info now');
```

## Extend
You can simply extend debugger
```js
const log = require('debug')('auth');
const createDebug = require('debug');
const log = createDebug('auth')

//creates new debug instance with extended namespace
// creates new debug instance with extended namespace
const logSign = log.extend('sign');
const logLogin = log.extend('login');

Expand All @@ -285,20 +284,20 @@ logSign('hello'); //auth:sign hello
logLogin('hello'); //auth:login hello
```

## Set dynamically
## Dynamically enable and disable all logging

You can also enable debug dynamically by calling the `enable()` method :

```js
let debug = require('debug');
let Debug = require('debug');

console.log(1, debug.enabled('test'));
console.log(1, Debug.enabled('test'));

debug.enable('test');
console.log(2, debug.enabled('test'));
Debug.enable('test');
console.log(2, Debug.enabled('test'));

debug.disable();
console.log(3, debug.enabled('test'));
Debug.disable();
console.log(3, Debug.enabled('test'));

```

Expand All @@ -316,7 +315,7 @@ Usage :
Note that calling `enable()` completely overrides previously set DEBUG variable :

```
$ DEBUG=foo node -e 'var dbg = require("debug"); dbg.enable("bar"); console.log(dbg.enabled("foo"))'
$ DEBUG=foo node -e 'let D = require("debug"); D.enable("bar"); console.log(D.enabled("foo"))'
=> false
```

Expand All @@ -329,10 +328,10 @@ temporarily without knowing what was enabled to begin with.
For example:

```js
let debug = require('debug');
debug.enable('foo:*,-foo:bar');
let namespaces = debug.disable();
debug.enable(namespaces);
let Debug = require('debug');
Debug.enable('foo:*,-foo:bar');
let namespaces = Debug.disable();
Debug.enable(namespaces);
```

Note: There is no guarantee that the string will be identical to the initial
Expand All @@ -344,9 +343,10 @@ After you've created a debug instance, you can determine whether or not it is
enabled by checking the `enabled` property:

```javascript
const debug = require('debug')('http');
const Debug = require('debug')
const debug = Debug('http')

if (debug.enabled) {
if (Debug.enabled) {
// do stuff...
}
```
Expand Down Expand Up @@ -375,6 +375,11 @@ worker = fork(WORKER_WRAP_PATH, [workerPath], {
worker.stderr.pipe(process.stderr, { end: false });
```

## Known limitations and gotchas

- Does not work well in strict ESM environments like Deno and UNPKG's module mode
- You cannot destructure the debug `const { disable } = require('debug')` will not work
- Environment variables are not re-read after startup, use our functions for runtime reconfiguration instead

## Authors

Expand Down