Skip to content
This repository has been archived by the owner on Sep 21, 2023. It is now read-only.

docs(integrity_checking): improve clarity #695

Closed
wants to merge 2 commits into from
Closed
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 9 additions & 10 deletions basics/modules/integrity_checking.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,16 +16,15 @@ integrity checking and lock files.
Deno can store and check subresource integrity for modules using a small JSON
file. To opt into a lock file, either:

1. Create a `deno.json` file in the current or an ancestor directory, which will
automatically create an additive lockfile at `deno.lock`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the word 'additive lockfile' is intentional and it tries to describe that the contents of it are sum of all dependencies of all relevant files (correct me if I'm wrong cc @dsherret @bartlomieju )

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the clarification, me not understanding this point was actually the chief impulse for this suggestion. If that is the case, I propose to either add an explanation of "additive lockfile" or maybe rename it to "cumulative lockfile", if that more closely reflects the intended meaning.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@dsherret What do you think about the above suggestion?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe let's just remove the word "additive" and "additional" here.

1. Create a `deno.json` file in the current or an ancestor directory. Deno will
automatically create a lockfile at `deno.lock` in addition.
2. Use the `--lock=deno.lock` to enable and specify lock file checking. To
update or create a lock use `--lock=deno.lock --lock-write`. The
`--lock=deno.lock` tells Deno what the lock file to use is, while the
`--lock-write` is used to output dependency hashes to the lock file
(`--lock-write` must be used in conjunction with `--lock`).

A `deno.lock` might look like this, storing a hash of the file against the
dependency:
A `deno.lock` might look like this, storing a hash of the dependency:

```json
{
Expand All @@ -38,14 +37,14 @@ dependency:

### Auto-generated lockfile

As mentioned above, when a Deno configuration file is resolved (ex. `deno.json`)
then an additive lockfile will be automatically generated. By default, the path
of this lockfile will be `deno.lock`. You can change this path by updating your
`deno.json` to specify this:
As mentioned above, when a Deno configuration file is found (ex. `deno.json`)
then an additional lockfile `deno.lock` will be automatically generated. By
default, this lockfile will be put in the same directory as the configuration
file. You can change this path in the configuration file:

```jsonc
{
"lock": "./lock.file"
"lock": "./path/to/lock.file"
}
```

Expand Down Expand Up @@ -95,7 +94,7 @@ deno test --allow-read src

Like caching above, you can also use lock files during use of the `deno run` sub
command, validating the integrity of any locked modules during the run. Remember
that this only validates against dependencies previously added to the lock file.
that this only validates dependencies previously added to the lock file.

You can take this a step further as well by using the `--cached-only` flag to
require that remote dependencies are already cached.
Expand Down