---
title: clean dangling referrers index in
tag: oras, cache, oci-layout
---

# Reproduce

graph TD;
  A-->B
  A-->C
  A-->D
  B--subject-->E
  C--subject-->E
  D--subject-->E

Digests:
- B: sha256:ed0f464e4a6d48b4f8ca3b781afc5ece2b16a7c35402ed7486be0015db03b951
- C: sha256:a589d048ac1d27de095e080a8d5ec284589825a4aaf671f7c43e3c3d4bba1b00
- D: sha256:83c4b643b1dd9f2a3275f21a8a9d075b166f998b23360835e268abf966beab8c
- E: sha256:dc0ea9814a627d14791bc9d487629249f0a92bf7c9554652dc933c56c3fe31a1

docker run -dp 5000:5000 registry

# oras copy
oras cp jinzha1.azurecr.io/demo/dangling-referrers-index:A localhost:5000/test:A --concurrency 1 -v

# oras manifest push
echo '{"schemaVersion":2,"mediaType":"application/vnd.oci.image.manifest.v1+json","config":{"mediaType":"test","digest":"sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a","size":2},"layers":[],"subject":{"mediaType":"application/vnd.oci.image.manifest.v1+json","digest":"sha256:dc0ea9814a627d14791bc9d487629249f0a92bf7c9554652dc933c56c3fe31a1","size":517},"annotations":{"org.opencontainers.image.created":"2023-05-18T02:40:53Z","test1":"true"}}' | oras manifest push localhost:5000/test -

# oras attach
oras attach localhost:5000/test@sha256:dc0ea9814a627d14791bc9d487629249f0a92bf7c9554652dc933c56c3fe31a1 -a test=true --artifact-type test

# oras manifest delete
oras discover localhost:5000/test@sha256:dc0ea9814a627d14791bc9d487629249f0a92bf7c9554652dc933c56c3fe31a1
oras manifest delete localhost:5000/test@sha256:3c83b2cc2486e05ef0dcc860d184aca400023d2f3bc5c16a66f12e9252b943cf -f

# Goals
- if the return error indicates deleting a dangling referrers index, should be ignored
- functions sending more than one HTTP(s) request should not stop on such error
- [x] option 1: add a new option to repository, allow skipping dangling referrers deletion
- pros: easy to implement
- cons: user don't know which referrers are dangling, cannot do GC
- user might don't need to GC, e.g. https://github.com/distribution/distribution/blob/main/docs/garbage-collection.md#run-garbage-collection
- need investigate whether and how user uses untagged(undisoverable) manifest
- Ideal implementation:
- CLI: default to not delete, add ad-hoc flag to all commands related referrers change
- tradeoff
- optimization on dockerhub, ghcr: `--gc` set to true, can be set to `false` (2.0 should be default to false)
- evaluate effect in acr: acr support on rc3 (if no fallback to tag scheme, no effect @billy TODO)
- [x] add a new issue for CLI change (@billy TODO)
- [x] add switch on oras-go side, comment in https://github.com/oras-project/oras-go/issues/510 (@billy TODO)

- distribution spec doesn't mandate the GC
- see https://github.com/opencontainers/distribution-spec/blob/main/spec.md#pushing-manifests-with-subject

- [ ] option 2: add a new option to repository, ignore delete dangling referrers error on oras-go side
- pros: easy to implement
- cons: user don't know which referrers are dangling, cannot do GC

- [ ] option 3: aggregate delete dangling referrers errors into one error and return
- pro: user knows which referrers are dangling

- show detail of operation
- attach: digest of the referrer artifact
- copy: digest of the copied root node