This lesson covers the topic of "pinning" files in your IPFS repository and removing files with the ipfs garbage collector. Pinning is a very important concept in IPFS. Pinning is the mechanism that allows you to tell IPFS to always keep a given object local.
After doing this Lesson you will be able to
Tell IPFS to hold onto specific files in your local IPFS repository
Tell IPFS to clean up unwanted files from your local IPS repository
Create a file called
foo.txt and put the text "ipfs rocks" in it. Here is an easy way to do this on the command line:
$ echo "ipfs rocks" > foo.txt
$ ipfs add foo.txtadded QmRTV3h1jLcACW4FRfdisokkQAk4E4qDhUzGpgdrd4JAFy foo.txt
$ ipfs pin ls --type=allQmRTV3h1jLcACW4FRfdisokkQAk4E4qDhUzGpgdrd4JAFy recursiveQmY5heUM5qgRubMDD1og9fhCPA6QdkMp3QCwd4s7gJsyE7 indirect
The first object listed above is the
foo.txt file. Objects added through
ipfs add are pinned recursively by default.
There are three types of pins in the ipfs world:
a) direct pins, which pin just a single block, and no others in relation to it;
b) recursive pins, which pin a given block and all of its children;
c) indirect pins, which are the result of a given block's parent being pinned recursively.
You can unpin
foo.txt like this:
$ ipfs pin rm QmRTV3h1jLcACW4FRfdisokkQAk4E4qDhUzGpgdrd4JAFyunpinned QmRTV3h1jLcACW4FRfdisokkQAk4E4qDhUzGpgdrd4JAFy
Ok, now verify that it no longer exists:
$ ipfs cat QmRTV3h1jLcACW4FRfdisokkQAk4E4qDhUzGpgdrd4JAFyipfs rocks
Wait, it still appears to be there! Ok, you must run the garbage collector and then verify again:
$ ipfs repo gcremoved QmRTV3h1jLcACW4FRfdisokkQAk4E4qDhUzGpgdrd4JAFy$ ipfs cat QmRTV3h1jLcACW4FRfdisokkQAk4E4qDhUzGpgdrd4JAFyError: merkledag: not found
IPFS has a fairly aggressive caching mechanism that will keep an object local for a short time after you perform any ipfs operation on it, but these objects may get garbage collected fairly regularly.
A pinned object cannot be garbage collected, if you don't believe me try this:
$ ipfs add foo.txtadded QmRTV3h1jLcACW4FRfdisokkQAk4E4qDhUzGpgdrd4JAFy foo.txt$ ipfs repo gc$ ipfs cat QmRTV3h1jLcACW4FRfdisokkQAk4E4qDhUzGpgdrd4JAFyipfs rocks
IPFS nodes treat the data they store like a cache, meaning that there is no guarantee that the data will continue to be stored. Pinning a CID (hash) tells an IPFS node that the data is important and mustn’t be thrown away. You should pin any content you consider important, to ensure that content is retained long-term. Since data important to someone else may not be important to you, pinning lets you have control over the disk space and data retention you need.
Next, proceed to the Going Online tutorial.