Page Menu
Home
Software Heritage
Search
Configure Global Search
Log In
Files
F9312235
getting-started.rst
No One
Temporary
Actions
View File
Edit File
Delete File
View Transforms
Subscribe
Mute Notifications
Award Token
Flag For Later
Size
8 KB
Subscribers
None
getting-started.rst
View Options
Getting Started
===============
This is a guide for how to prepare and push a software deposit with
the
`swh deposit`
commands.
The API is rooted at https://deposit.softwareheritage.org/1.
For more details, see the
`main documentation
<./index.html>
`__
.
Requirements
------------
You need to be referenced on SWH's client list to have:
*
credentials (needed for the basic authentication step)
-
in this document we reference
``<name>``
as the client's name and
``<pass>``
as its associated authentication password.
*
an associated collection_.
..
_collection:
https://bitworking.org/projects/atom/rfc5023#rfc.section.8.3.3
`Contact us for more information.
<https://www.softwareheritage.org/contact/>
`__
Prepare a deposit
-----------------
*
compress the files in a supported archive format:
-
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`
)
*
(Optional) prepare a metadata file (more details
:ref:
`deposit-metadata`
):
Push deposit
------------
You can push a deposit with:
*
a single deposit (archive + metadata):
The user posts in one query a software
source code archive and associated metadata.
The deposit is directly marked with status
``deposited``
.
*
a multisteps deposit:
1.
Create an incomplete deposit (marked with status
``partial``
)
2.
Add data to a deposit (in multiple requests if needed)
3.
Finalize deposit (the status becomes
``deposited``
)
Single deposit
^^^^^^^^^^^^^^
Once the files are ready for deposit, we want to do the actual deposit
in one shot, sending exactly one POST query:
*
1 archive (content-type
``application/zip``
or
``application/x-tar``
)
*
1 metadata file in atom xml format (
``content-type: application/atom+xml;type=entry``
)
For this, we need to provide the:
*
arguments:
``--username 'name' --password 'pass'``
as credentials
*
archive's path (example:
``--archive path/to/archive-name.tgz``
)
*
software's name (optional if a metadata filepath is specified and the
artifact's name is included in the metadata file).
*
author's name (optional if a metadata filepath is specified and the authors
are included in the metadata file). This can be specified multiple times in
case of multiple authors.
*
(optionally) metadata file's path
``--metadata
path/to/file.metadata.xml``
.
*
(optionally)
``--slug 'your-id'``
argument, a reference to a unique identifier
the client uses for the software object. If not provided, A UUID will be
generated by SWH.
You can do this with the following command:
minimal deposit
..
code
::
shell
$
swh
deposit
upload
--username
name
--password
secret
\
--author
"Jane Doe"
\
--author
"John Doe"
\
--name
'je-suis-gpl'
\
--archive
je-suis-gpl.tgz
with client's external identifier (
``slug``
)
..
code
::
shell
$
swh
deposit
upload
--username
name
--password
secret
\
--author
"Jane Doe"
\
--name
'je-suis-gpl'
\
--archive
je-suis-gpl.tgz
\
--slug
je-suis-gpl
to a specific client's collection
..
code
::
shell
$
swh
deposit
upload
--username
name
--password
secret
\
--author
"Jane Doe"
\
--name
'je-suis-gpl'
\
--archive
je-suis-gpl.tgz
\
--collection
'second-collection'
You just posted a deposit to your collection on Software Heritage
If everything went well, the successful response will contain the
elements below:
..
code
::
shell
{
'deposit_status'
:
'deposited'
,
'deposit_id'
:
'7'
,
'deposit_date'
:
'Jan. 29, 2018, 12:29 p.m.'
}
Note: As the deposit is in
``deposited``
status, you can no longer
update the deposit after this query. It will be answered with a 403
forbidden answer.
If something went wrong, an equivalent response will be given with the
`error`
and
`detail`
keys explaining the issue, e.g.:
..
code
::
shell
{
'error'
:
'Unknown collection name xyz'
,
'detail'
:
None,
'deposit_status'
:
None,
'deposit_status_detail'
:
None,
'deposit_swh_id'
:
None,
'status'
:
404
}
multisteps deposit
^^^^^^^^^^^^^^^^^^^^^^^^^
The steps to create a multisteps deposit:
1.
Create an incomplete deposit
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
First use the
``--partial``
argument to declare there is more to come
..
code
::
shell
$
swh
deposit
upload
--username
name
--password
secret
\
--archive
foo.tar.gz
\
--partial
2. Add content or metadata to the deposit
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Continue the deposit by using the
``--deposit-id``
argument given as a response
for the first step. You can continue adding content or metadata while you use
the
``--partial``
argument.
To only add one new archive to the deposit:
..
code
::
shell
$
swh
deposit
upload
--username
name
--password
secret
\
--archive
add-foo.tar.gz
\
--deposit-id
42
\
--partial
To only add metadata to the deposit:
..
code
::
shell
$
swh
deposit
upload
--username
name
--password
secret
\
--metadata
add-foo.tar.gz.metadata.xml
\
--deposit-id
42
\
--partial
or:
..
code
::
shell
$
swh
deposit
upload
--username
name
--password
secret
\
--name
'add-foo'
--author
'someone'
\
--deposit-id
42
\
--partial
3. Finalize deposit
~~~~~~~~~~~~~~~~~~~
On your last addition (same command as before), by not declaring it
``--partial``
, the deposit will be considered completed. Its status will be
changed to
``deposited``
Update deposit
----------------
*
replace deposit:
-
only possible if the deposit status is
``partial``
and
``--deposit-id <id>``
is provided
-
by using the
``--replace``
flag
-
``--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):
..
code
::
shell
$
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:
..
code
::
shell
$
swh
deposit
upload
--username
name
--password
secret
\
--archive
je-suis-gpl-v2.tgz
\
--slug
'je-suis-gpl'
\
Check the deposit's status
--------------------------
You can check the status of the deposit by using the
``--deposit-id``
argument:
..
code
::
shell
$
swh
deposit
status
--username
name
--password
secret
\
--deposit-id
11
..
code
::
json
{
'deposi
t
_id'
:
'
11
'
,
'deposi
t
_s
tatus
'
:
'deposi
te
d'
,
'deposi
t
_swh_id'
:
No
ne
,
'deposi
t
_s
tatus
_de
ta
il'
:
'Deposi
t
is
ready
f
or
addi
t
io
nal
checks
\
(
tar
ball
ok
,
me
ta
da
ta
,
e
t
c...)'
}
The different statuses:
-
**partial**
: multipart deposit is still ongoing
-
**deposited**
: deposit completed
-
**rejected**
: deposit failed the checks
-
**verified**
: content and metadata verified
-
**loading**
: loading in-progress
-
**done**
: loading completed successfully
-
**failed**
: the deposit loading has failed
When the deposit has been loaded into the archive, the status will be
marked
``done``
. In the response, will also be available the
<deposit_swh_id>
, <deposit_swh_id_context>. For example:
..
code
::
json
{
'deposi
t
_id'
:
'
11
'
,
'deposi
t
_s
tatus
'
:
'do
ne
'
,
'deposi
t
_swh_id'
:
'swh
:
1
:
dir
:
d
83
b
7
dda
887
dc
790
f
7207608474650
d
4344
b
8
d
f
9
'
,
'deposi
t
_swh_id_co
nte
x
t
'
:
'swh
:
1
:
dir
:
d
83
b
7
dda
887
dc
790
f
7207608474650
d
4344
b
8
d
f
9
;origi
n
=h
tt
ps
:
//forge.softwareheritage.org/source/jesuisgpl/;visit=swh:1:snp:68c0d26104d47e278dd6be07ed61fafb561d0d20;anchor=swh:1:rev:e76ea49c9ffbb7f73611087ba6e999b19e5d71eb;path=/',
'deposi
t
_s
tatus
_de
ta
il'
:
'The
deposi
t
has
bee
n
success
full
y
\
loaded
i
nt
o
t
he
So
ft
ware
Heri
ta
ge
archive'
}
File Metadata
Details
Attached
Mime Type
text/plain
Expires
Thu, Jul 3, 10:47 AM (1 w, 5 d ago)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
3399145
Attached To
rDDEP Push deposit
Event Timeline
Log In to Comment