Check the status of a directory

Working with files in ProtoSchool

Here in our ProtoSchool tutorials, we create a new IPFS node for you in the browser each time you hit the "Submit" button in a lesson. Whenever you see ipfs.someMethod() in our lessons, ipfs is a variable that refers to your IPFS instance, also known as a node. The actions that you take only affect your own IPFS node, not nodes belonging to your peers.

We're creating your IPFS node behind the scenes so you can focus on the content of our lessons, but eventually you'll need to learn to host your own node locally by installing IPFS and running a daemon in your terminal. When you're ready to experiment, you can find instructions for installing IPFS and initializing your node in our docs.

As mentioned previously, methods associated with the Mutable File System are part of the Files API, so they'll take the format of ipfs.files.someMethod(). Let's take a look at a simple method you can start using even before you've added any files to your IPFS node.

Exploring your IPFS node with ipfs.files.stat

When working with your IPFS node, you'll often want to check the status of a file or directory. You can do this with ipfs.files.stat, passing in the path you'd like to check on.

For example, to check the status of a directory called stuff located within our root directory ( / ), we could call the method like so:

await ipfs.files.stat('/stuff')

This method returns an object with some essential data about our file or directory:

• cid (the CID object)
• size (an integer with the file or directory size in Bytes)
• cumulativeSize (an integer with the size of the DAGNodes making up the file in Bytes)
• type (a string that can be either directory or file)
• blocks (if type is directory, this is the number of files in the directory; if type is file, it's the number of blocks that make up the file)
• withLocality (a boolean to indicate if locality information are present)
• local (a boolean to indicate if the queried dag is fully present locally)
• sizeLocal (an integer indicating the cumulative size of the data present locally)

Gotcha! The size of a directory is always 0, no matter how many entries it contains, since directories are really just a set of links to other files and directories. A directory's cumulativeSize, by contrast, changes as the directory's contents change. It represents not just the file sizes of all the entries in that directory, but also the metadata that describes those entries: types, block sizes and so on.

It's important to note that you can stat your IPFS node even when you don't have anything in it yet. Even an empty node has a CID.