Principle:Iterative Dvc Experiment Apply Or Discard

Knowledge Sources	DVC Documentation
Domains	Experiment_Management, Version_Control
Last Updated	2026-02-10 00:00 GMT

Overview

Experiment apply or discard is the practice of promoting successful experiment results to the current workspace or cleaning up unsuccessful experiments, managing the experiment ref namespace to maintain a tidy experiment history.

Description

After experiments have been executed and compared, practitioners face a decision for each experiment: promote its results to the working workspace (apply), or remove it from the experiment history (discard). This decision point is a critical part of the experiment lifecycle, bridging the gap between exploratory experimentation and committed development progress.

Applying an experiment means checking out the experiment's complete state -- parameters, code changes, outputs, metrics -- into the current working directory. This effectively "promotes" the experiment from the isolated refs/exps/ namespace into the active workspace, making its changes visible and ready to be committed to a development branch. The apply operation preserves the user's ability to undo by recording which experiment was last applied, so that subsequent operations can detect whether the workspace state matches an applied experiment.

Discarding (removing) an experiment deletes its ref from the refs/exps/ namespace, cleaning up experiment history. Removal supports multiple granularities: removing individual experiments by name, removing all experiments derived from specific baseline commits, removing all queued experiments, or removing all experiments entirely. The inverse operation, keep, allows removing all experiments except the specified ones, which is useful for cleanup after a large hyperparameter search where only the best results are worth preserving.

Together, apply and discard complete the experiment lifecycle: experiments are created (workspace preparation), executed (pipeline execution), persisted (result capture), compared (experiment comparison), and finally either promoted to the workspace or removed from history.

Usage

Use experiment apply when:

• You have identified the best experiment from a comparison and want to adopt its results
• You need to bring experiment changes into the workspace for further development or committing
• You want to inspect an experiment's full state in context of the working directory

Use experiment remove when:

• You have completed a hyperparameter search and want to clean up unsuccessful experiments
• You need to free up space in the experiment ref namespace
• You want to clear the experiment queue of pending entries
• You are cleaning up experiments on a remote repository

This principle is the design trigger at the end of any experiment cycle, when results have been evaluated and the next step is either adoption or cleanup.

Theoretical Basis

The apply and discard operations manage a state machine for experiment lifecycle:

Experiment States:
    QUEUED -> RUNNING -> COMPLETED -> {APPLIED | REMOVED}
                      -> FAILED    -> REMOVED

function apply_experiment(workspace, experiment_rev):
    # Step 1: Resolve experiment revision
    exp_rev = resolve_rev(experiment_rev)

    # Step 2: Preserve current workspace state for undo
    save_workspace_state()

    # Step 3: Check out experiment state
    git_detach_head(exp_rev, force=True)
    copy_working_tree_to_workspace()
    git_restore_head()

    # Step 4: Update DVC-tracked files
    dvc_checkout(force=True)

    # Step 5: Record last applied experiment
    set_ref(EXEC_APPLY, exp_rev)

    return workspace  # now contains experiment state

function remove_experiments(experiments, scope):
    if scope == QUEUE:
        clear_queued_entries()

    if scope == BY_NAME:
        for name in experiments:
            ref = resolve_ref_by_name(name)
            delete_ref(ref)
            # Also remove from queue if entry exists
            remove_queue_entry(name)

    if scope == BY_BASELINE:
        for baseline_rev in revisions:
            refs = list_refs_under(baseline_rev)
            delete_refs(refs)

    if scope == ALL:
        refs = list_all_exp_refs()
        delete_refs(refs)

    if scope == KEEP:
        # Inverse: remove everything except specified
        all_refs = list_all_exp_refs()
        keep_refs = resolve_refs(experiments)
        delete_refs = all_refs - keep_refs
        delete_refs(delete_refs)

    return list_of_removed_names

The apply operation uses a detach-copy-restore pattern:

1. Detach HEAD to the experiment commit, which updates the working tree
2. Copy the working tree state back to the workspace (this handles the case where the experiment is on a different branch)
3. Restore HEAD to the original position
4. Run DVC checkout to update DVC-tracked files and their cache links

The EXEC_APPLY ref serves as a breadcrumb that tracks which experiment was last applied. This is used for two purposes: (1) detecting whether the workspace has changed since the last apply (by comparing EXEC_APPLY's baseline with the current HEAD), and (2) enabling undo-like behavior where the system can warn the user if they are about to overwrite unapplied changes.

Key theoretical properties:

1. Non-destructive apply: Applying an experiment does not delete the experiment ref; the experiment remains in the ref namespace and can be applied again or compared later
2. Atomic removal: Experiment refs are deleted as a batch operation; either all specified experiments are removed or the operation fails
3. Queue-aware removal: The remove operation handles both committed experiments (stored as Git refs) and queued experiments (stored as Celery task entries), providing a unified cleanup interface
4. Remote support: Both operations can target remote repositories, enabling cleanup of experiments that have been pushed to shared remotes

Related Pages

Implemented By

• Implementation:Iterative_Dvc_Experiments_Apply_Remove