diff --git a/README.md b/README.md --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ This is [Software Heritage](https://www.softwareheritage.org)'s [SWORD 2.0](http://swordapp.github.io/SWORDv2-Profile/SWORDProfile.html) Server -implementation. +implementation, as well as a simple client to upload deposits on the server. **S.W.O.R.D** (**S**imple **W**eb-Service **O**ffering **R**epository **D**eposit) is an interoperability standard for digital file deposit. diff --git a/docs/getting-started.rst b/docs/getting-started.rst --- a/docs/getting-started.rst +++ b/docs/getting-started.rst @@ -2,9 +2,9 @@ =============== This is a guide for how to prepare and push a software deposit with -the swh-deposit commands. +the `swh deposit` commands. -The api is rooted at https://deposit.softwareheritage.org/1. +The API is rooted at https://deposit.softwareheritage.org/1. For more details, see the `main documentation <./index.html>`__. @@ -18,11 +18,14 @@ - in this document we reference ```` as the client's name and ```` as its associated authentication password. -* an associated collection +* an associated collection_. -`Contact us for more -information. `__ +.. _collection: https://bitworking.org/projects/atom/rfc5023#rfc.section.8.3.3 + + +`Contact us for more information. +`__ Prepare a deposit ----------------- @@ -30,16 +33,17 @@ - zip: common zip archive (no multi-disk zip files). - tar: tar archive without compression or optionally any of the - following compression algorithm gzip (.tar.gz, .tgz), bzip2 - (.tar.bz2) , or lzma (.tar.lzma) + following compression algorithm gzip (`.tar.gz`, `.tgz`), bzip2 + (`.tar.bz2`) , or lzma (`.tar.lzma`) + * prepare a metadata file (`more details <./metadata.html>`__.): - - specify metadata schema/vocabulary (CodeMeta is recommended) + - specify metadata schema/vocabulary (CodeMeta is strongly recommended) - specify *MUST* metadata (url, authors, software name and the external\_identifier) - - add all available information under the compatible metadata term + - add all available information under the compatible metadata term. - An example of an atom entry file with CodeMeta terms: + Here is an example of an atom entry file with CodeMeta terms: .. code:: xml @@ -115,24 +119,24 @@ .. code:: shell - $ swh-deposit deposit --username name --password secret \ - --archive je-suis-gpl.tgz + $ swh deposit upload --username name --password secret \ + --archive je-suis-gpl.tgz with client's external identifier (``slug``) .. code:: shell - $ swh-deposit deposit --username name --password secret \ - --archive je-suis-gpl.tgz \ - --slug je-suis-gpl + $ swh deposit upload --username name --password secret \ + --archive je-suis-gpl.tgz \ + --slug je-suis-gpl to a specific client's collection .. code:: shell - $ swh-deposit deposit --username name --password secret \ - --archive je-suis-gpl.tgz \ - --collection 'second-collection' + $ swh deposit upload --username name --password secret \ + --archive je-suis-gpl.tgz \ + --collection 'second-collection' @@ -180,9 +184,9 @@ .. code:: shell - $ swh-deposit deposit --username name --password secret \ - --archive foo.tar.gz \ - --partial + $ swh deposit upload --username name --password secret \ + --archive foo.tar.gz \ + --partial 2. Add content or metadata to the deposit @@ -193,38 +197,44 @@ .. code:: shell - $ swh-deposit deposit --username name --password secret \ - --archive add-foo.tar.gz \ - --deposit-id 42 \ - --partial + $ swh deposit upload --username name --password secret \ + --archive add-foo.tar.gz \ + --deposit-id 42 \ + --partial In case you want to add only one new archive without metadata: .. code:: shell - $ swh-deposit deposit --username name --password secret \ - --archive add-foo.tar.gz \ - --archive-deposit \ - --deposit-id 42 \ - --partial \ + $ swh deposit upload --username name --password secret \ + --archive add-foo.tar.gz \ + --archive-deposit \ + --deposit-id 42 \ + --partial If you want to add only metadata, use: .. code:: shell - $ swh-deposit deposit --username name --password secret \ - --metadata add-foo.tar.gz.metadata.xml \ - --metadata-deposit \ - --deposit-id 42 \ - --partial + $ swh deposit upload --username name --password secret \ + --metadata add-foo.tar.gz.metadata.xml \ + --metadata-deposit \ + --deposit-id 42 \ + --partial 3. Finalize deposit - ~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~ On your last addition, by not declaring it as ``--partial``, the deposit will be considered as completed and its status will be changed -to ``deposited``. +to ``deposited``: + +.. code:: shell + $ swh deposit upload --username name --password secret \ + --metadata add-foo.tar.gz.metadata.xml \ + --metadata-deposit \ + --deposit-id 42 Update deposit @@ -239,25 +249,25 @@ - ``--metadata-deposit`` replaces associated existing metadata - ``--archive-deposit`` replaces associated archive(s) - by default, with no flag or both, you'll replace associated - metadata and archive(s) + metadata and archive(s): .. code:: shell - $ swh-deposit deposit --username name --password secret \ - --deposit-id 11 \ - --archive updated-je-suis-gpl.tgz \ - --replace + $ swh deposit upload --username name --password secret \ + --deposit-id 11 \ + --archive updated-je-suis-gpl.tgz \ + --replace * update a loaded deposit with a new version: - by using the external-id with the ``--slug`` argument, you will - link the new deposit with its parent deposit + link the new deposit with its parent deposit: .. code:: shell - $ swh-deposit deposit --username name --password secret \ - --archive je-suis-gpl-v2.tgz \ - --slug 'je-suis-gpl' \ + $ swh deposit upload --username name --password secret \ + --archive je-suis-gpl-v2.tgz \ + --slug 'je-suis-gpl' \ @@ -268,7 +278,9 @@ .. code:: shell - $ swh-deposit deposit --username name --password secret --deposit-id '11' --status + $ swh deposit upload --username name --password secret \ + --deposit-id 11 + --status .. code:: json