Lesson: Add Content to IPFS and Retrieve It
After doing this Lesson you will be able to
- Add a file's content to IPFS
- Read content out of IPFS using its hash
- Explain the relationship between IPFS hashes and the content you've added
You can add any type of content to IPFS. For this lesson we will put some text content into a `.txt` file, but you can do this same process with any content or any file.
It would be a good idea to make a new directory for this example. Navigate to somewhere you are comfortable putting a new folder (such as
~/Desktop), and then create a new directory and go into it. Here is an example command:$ cd ~/Desktop
$ mkdir ipfs-tutorial
$ cd ipfs-tutorial
Now, create a file called
mytextfile.txt and put the text "version 1 of my text" in it. One easy way to do this on the command line is with this command:$ echo "version 1 of my text" > mytextfile.txt
You can read the file's contents using the
cat command:$ cat mytextfile.txt
version 1 of my text
$ ipfs add mytextfile.txt
added QmZtmD2qt6fJot32nabSP3CUjicnypEBz7bHVDhPQt9aAy mytextfile.txt
Save the hash
QmZtmD2qt... that ipfs returned. This is the content's cryptographic hash. If the file's content changes, the hash will change, but if the file's content remains the same, the hash will always be the same.Bear in mind that if you're not running the daemon, it will just add locally. If you start the daemon later, the blocks will be advertised after a few seconds when the reprovider runs.
Just like the regular
cat command lets you read the contents of a file, the ipfs cat command lets you read the contents of a file that has been added to ipfs.Use the
ipfs cat command to read the content by passing it the content's cryptographic hash -- this is the hash that ipfs returned when you ran ipfs add mytextfile.txt.$ ipfs cat QmZtmD2qt6fJot32nabSP3CUjicnypEBz7bHVDhPQt9aAy
version 1 of my text
Notice that this returned the content of the file, not the text file itself. That's because
QmZtmD2qt... is the hash of the content, not the file itself. We'll test that in the next step.When you used
ipfs cat to read the file's contents it returned the content of the file, not the text file itself. That's because the hash QmZtmD2qt... is the hash of the content. You can test that by adding the text content directly to IPFS without ever putting it in a file.$ echo "version 1 of my text" | ipfs add
added QmZtmD2qt6fJot32nabSP3CUjicnypEBz7bHVDhPQt9aAy QmZtmD2qt6fJot32nabSP3CUjicnypEBz7bHVDhPQt9aAy
The hash should be exactly the same as the hash you got when you added mytextfile.txt. If you want to triple-check, you can run each of these commands as many times as you want. The hash should always be the same.
$ ipfs add mytextfile.txt
added QmZtmD2qt6fJot32nabSP3CUjicnypEBz7bHVDhPQt9aAy mytextfile.txt
$ echo "version 1 of my text" | ipfs add
added QmZtmD2qt6fJot32nabSP3CUjicnypEBz7bHVDhPQt9aAy QmZtmD2qt6fJot32nabSP3CUjicnypEBz7bHVDhPQt9aAy
$ cat mytextfile.txt | ipfs add
added QmZtmD2qt6fJot32nabSP3CUjicnypEBz7bHVDhPQt9aAy QmZtmD2qt6fJot32nabSP3CUjicnypEBz7bHVDhPQt9aAy
As long as the content remains the same, you will always get the same hash. As far as IPFS is concerned, it is the same content.
Now change the text content to "version 2 of my text" and add it to ipfs. You will get a different hash.
As you confirmed in the previous step, you can add the new text directly to IPFS or you can modify mytextfile.txt and add it to IPFS. You will get the same hash either way.
$ echo "version 2 of my text" | ipfs add
added QmTudJSaoKxtbEnTddJ9vh8hbN84ZLVvD5pNpUaSbxwGoa QmTudJSaoKxtbEnTddJ9vh8hbN84ZLVvD5pNpUaSbxwGoa
You can read this content (any version) out of ipfs and write it into a file. For example, you can toggle the contents of mytextfile.txt from "version 1" to "version 2" and back as many times as you want:
$ ipfs cat QmTudJSaoKxtbEnTddJ9vh8hbN84ZLVvD5pNpUaSbxwGoa > mytextfile.txt
$ cat mytextfile.txt
version 2 of my text
$ ipfs cat QmZtmD2qt6fJot32nabSP3CUjicnypEBz7bHVDhPQt9aAy > mytextfile.txt
$ cat mytextfile.txt
version 1 of my text
You can also write the content from ipfs into a completely new file.
$ ipfs cat QmZtmD2qt6fJot32nabSP3CUjicnypEBz7bHVDhPQt9aAy > anothertextfile.txt
$ cat anothertextfile.txt
version 1 of my text
IPFS tracks content based on its cryptographic hash. This hash uniquely identifies exactly that content. As long as the content stays the same, the hash stays the same. If the content changes at all you will get a different hash.
If you have two different files that contain identical content, IPFS will track that content with one hash. The filenames are different, but the content is the same, so the hash of the content will be identical.
This leads to the question: how does IPFS track file names? That's the topic of the next lesson.
Proceed to the next lesson to learn how to Wrap Filenames and Directory Info around Content in IPFS