History of Opam File Retrieval Behaviour

Oct 13, 2025 by wbrum.org 45 views

Introduction

The current default behaviour of Opam, a package manager for OCaml, is to retrieve the uncommitted Opam file when a package is VCS-pinned on a local directory. This behaviour was introduced in Opam 2.0, which led to the retrieval of uncommitted modifications of the Opam file. However, this behaviour has been subject to changes and updates over time, with the latest update being in #6409. In this article, we will discuss the history of this behaviour, the current state, and the proposed changes to remove the "magic" of retrieving uncommitted Opam files.

History of Opam File Retrieval Behaviour

The history of Opam file retrieval behaviour dates back to Opam 1.2, where the default behaviour was to path pin. However, with the introduction of VCS pin detection in Opam 2.0, the behaviour changed to retrieve the uncommitted modifications of the Opam file. This led to the opening of #3404, which introduced the "magic" of retrieving the Opam file on disk, committed or not. Over time, this behaviour was updated and fixed in #3499, #4300, and #4876, until the latest update in #6409.

Current State of Opam File Retrieval Behaviour

The current state of Opam file retrieval behaviour is to retrieve the uncommitted Opam file when a package is VCS-pinned on a local directory. This behaviour is considered "magic" because it retrieves the Opam file on disk, committed or not. However, this behaviour has been subject to changes and updates over time, and it is now being considered for removal.

Proposed Changes to Remove "Magic" of Retrieving Uncommitted Opam Files

The proposed changes to remove the "magic" of retrieving uncommitted Opam files involve changing the default behaviour of Opam to not retrieve uncommitted modifications of the Opam file. This would require adding a note to inform users that uncommitted changes in the Opam file are not taken. Additionally, users would still be able to have uncommitted Opam files handled using the --working-dir option or by considering a path pin.

Safeguards for Proposed Changes

To ensure a smooth transition to the new behaviour, several safeguards have been proposed:

Note to users: A note would be added to inform users that uncommitted changes in the Opam file are not taken.
--working-dir option: The --working-dir option would still be available to handle uncommitted Opam files.
Path pin: Users would still be able to consider a path pin as an alternative to VCS pin.

Discussion and Conclusion

The proposed changes to remove the "magic" of retrieving uncommitted Opam files would require a change in the default behaviour of Opam. While this change would simplify the behaviour of Opam, it would also require users to be aware of the changes and take necessary steps to handle uncommitted Opam files. The proposed safeguards would help ensure a smooth transition to the new behaviour.

Future Directions

The future directions for Opam file retrieval behaviour would depend on the outcome of the proposed changes. If the changes are accepted, Opam would no longer retrieve uncommitted modifications of the Opam file by default. Users would need to use the --working-dir option or consider a path pin to handle uncommitted Opam files.

References

#3403: Opam 1.2 behaviour
#3404: Introduction of "magic" of retrieving Opam file on disk
#3499: Update to Opam file retrieval behaviour
#4300: Update to Opam file retrieval behaviour
#4876: Update to Opam file retrieval behaviour
#6409: Latest update to Opam file retrieval behaviour
https://github.com/ocaml/opam/pull/6409#issuecomment-2707767344: Discussion in PR
Dev meeting: Discussion in dev meeting
Frequently Asked Questions (FAQs) about Default Behaviour of Opam File Retrieval for Local Pin on VCS Directory ==============================================================================================

Q: What is the current default behaviour of Opam file retrieval for local pin on VCS directory?

A: The current default behaviour of Opam is to retrieve the uncommitted Opam file when a package is VCS-pinned on a local directory.

Q: Why was the default behaviour changed to retrieve uncommitted Opam files?

A: The default behaviour was changed to retrieve uncommitted Opam files with the introduction of VCS pin detection in Opam 2.0. This led to the retrieval of uncommitted modifications of the Opam file.

Q: What is the proposed change to remove the "magic" of retrieving uncommitted Opam files?

A: The proposed change is to change the default behaviour of Opam to not retrieve uncommitted modifications of the Opam file. This would require adding a note to inform users that uncommitted changes in the Opam file are not taken.

Q: What safeguards have been proposed to ensure a smooth transition to the new behaviour?

A: The proposed safeguards include:

Note to users: A note would be added to inform users that uncommitted changes in the Opam file are not taken.
--working-dir option: The --working-dir option would still be available to handle uncommitted Opam files.
Path pin: Users would still be able to consider a path pin as an alternative to VCS pin.

Q: Why is the "magic" of retrieving uncommitted Opam files being removed?

A: The "magic" of retrieving uncommitted Opam files is being removed to simplify the behaviour of Opam and to make it more predictable.

Q: How will users be affected by the proposed change?

A: Users will need to be aware of the changes and take necessary steps to handle uncommitted Opam files. They can use the --working-dir option or consider a path pin to handle uncommitted Opam files.

Q: What is the timeline for implementing the proposed change?

A: The timeline for implementing the proposed change is not yet determined. It will depend on the outcome of the discussion and the decision of the Opam developers.

Q: How can users provide feedback on the proposed change?

A: Users can provide feedback on the proposed change by commenting on the relevant issue on the Opam GitHub repository or by participating in the discussion on the Opam mailing list.

Q: What are the benefits of removing the "magic" of retrieving uncommitted Opam files?

A: The benefits of removing the "magic" of retrieving uncommitted Opam files include:

Simplified behaviour of Opam
More predictable behaviour of Opam
Improved user experience

Q: What are the potential drawbacks of removing the "magic" of retrieving uncommitted Opam files?

A: The potential drawbacks of removing the "magic" of retrieving uncommitted Opam files include:

Users may need to take additional steps to handle uncommitted Opam files
Users may need to use the --working-dir option or consider a path pin to handle uncommitted Opam files

Q: How can users get help with implementing the proposed change?

A: Users can get help with implementing the proposed change by:

Reading the Opam documentation
Searching the Opam GitHub repository for related issues
Participating in the discussion on the Opam mailing list
Reaching out to the Opam developers for assistance