Usage example with mapping from url to bucket

[rufuspollock]

I get this is git-lfs but i don't quite get from README how a given request maps to a location in a bucket.

Could we get a short Usage section (reffing git-lfs) explaining how to push a file and where it ends up location wise in the configured bucket.

[shevron]

Giftless runs it's batch endpoint (and other endpoints) in URLs in the format of <giftless_base_url>/<organization>/<repository>/objects/batch (for example for the batch endpoint).

In turn, storage backends will use the <org>/<repository> prefix to place the file in storage. This prefix is also used for some authorization checks.

Where the file is placed exactly is up to the selected storage backed, but currently all backends behave the same way:
the file eventually will be placed at </prefix>/<org>/<repository>/<object id> under a specified <bucket>, where <prefix> and <bucket> are configured on the Giftless server level (and <prefix> is typically optional), and the rest comes from the request itself.

To give an example, if a batch request was sent with the following details:

POST /my-org/my-repo/objects/batch

{
  "action": "upload", 
  "objects": [
    {"oid": "123123123123123abcabcabcabcabc", "size": 555}
  ]
}

(Excuse any inaccuracies in the JSON payload I didn't even look at what it should be, but something like this)

For a server configured to store in a Google Cloud bucket named my-lfs-files and prefix is objects, the file will end up being stored at: gs://my-lfs-files/objects/my-org/my-repo/123123123123123abcabcabcabcabc.

To clarify, the org/repo prefix is not mandated by Git LFS but is a common convention and at least currently in Giftless it is mandatory.

[shevron]

This is now somewhat referenced in the "Using Google Cloud Storage" howto (https://giftless.readthedocs.io/en/master/using-gcs.html) but should probably be better explained in the storage backends section on GCS.