To keep your data safe, even if you upload a bad file or get rid of the wrong file, B2 Cloud Storage lets you keep a history of previous versions of each file stored. Not only can you keep previous versions of a file, but B2 can keep track of when a file has gone away and when it has been put back, allowing you to keep a full history.

The first time you upload a file called puppy.jpg, you have just one version of the file, so it's clear which one you get when you download puppy.jpg.

You can think of a file as always having a list of versions, newest first. When you download a file by name, you always get the most recent version, the first one in the list. If you want an older version, you can find its File ID, and then download it.

If you upload a new file called puppy.jpg, you get this:

File with one version

If you upload another file with the same name later, there are now two versions in the list, with the newest one first:

File with two versions

At this point, if you download “puppy.jpg”, you’ll get the new one. You can still download either puppy image by using its file ID.

The b2_list_file_names operation returns one entry for each file name, so at this point it will return just one file name, and it will have the file ID of the more recent version. If you want to see all of the versions of the file, you can use the b2_list_file_versions operation, which will list both versions of “puppy.jpg”

Now, the b2_hide_file operation makes it look like the file has been deleted, without removing any of the history. It adds a new version of the file that is a "hide marker" saying the file is no longer there.

File with two versions, one deleted

With the file hidden, downloading the file by name will return a 404 error saying that the file is not there.

Uploading yet another cute puppy picture at this point adds a new version, which is the one that you get when downloading the file by name. The fact that an older version was hidden is still in the history.

File with three versions

The b2_list_file_versions operation will give you all of this information. The results returned look like this:

{
    "files" : [
        {
            "fileId": "4_z4a48fe8875c6214145260818_f0000000000823564_d20150725_m091433_c001_v0000123_t0104",
            "fileName": "puppy.jpg",
            "action": "upload",
            "uploadTimestamp": 1437815673000,
        },
        {
            "fileId": "4_z4a48fe8875c6214145260818_f0000000057265835_d20150723_m160005_c001_v0000123_t0104",,
            "fileName": "puppy.jpg",
            "action": "hide",
            "uploadTimestamp": 1437667205000,
        },
        {
            "fileId": "4_z4a48fe8875c6214145260818_f0000000000562156_d20150721_m045924_c001_v0000123_t0104",
            "fileName": "puppy.jpg",
            "action": "upload",
            "uploadTimestamp": 1437454764000,
        },
        {
            "fileId": "4_z4a48fe8875c6214145260818_f000000000000472a_d20150721_m032942_c001_v0000123_t0104",
            "fileName": "puppy.jpg",
            "action": "upload",
            "uploadTimestamp": 1437449382000,
        }
    ]
}

And finally, the last thing about file versions is that you can delete them. Deleting a file version cannot be undone, and is permanent. The b2_delete_file_version operation makes it as if that version of the file had never been there. You'll usually use this to clean up old versions of a file that you don't need any more. Removing the first puppy uploaded results in this:

first version is now gone

It is even possible to delete the marker saying a file is hidden. If, at this point, you delete the newest version and the deletion marker, you get back to just one version:

now there is just one version

To summarize, the things you can do to files are:

`b2_upload_file`	Creates a new file version. As the newest version, this is the one that you will get when downloading by name.
`b2_download_file_by_id`	Fetches the specific file version for the given File ID.
`b2_download_file_by_name`	Fetches the most recent version of the file. If the file is not there at all, or the most recent version is "hidden", returns 404.
`b2_hide_file`	Creates a "hidden" marker as the most recent version of the file. Downloading the file by name will return 404.
`b2_delete_file_version`	Permanently deletes the file version and all of its data. It will be as if that version had never been uploaded.
`b2_list_file_names`	Returns file names for the bucket, in alphabetical order, starting at a given point.
`b2_list_file_versions`	Returns a list of all versions of all files in a bucket, sorted by file name, then by upload time. May be restricted to just list the version for a given file name.