GitoxideLabs/gitoxide · error

BUG: need a commit

Error message

BUG: need a commit

What it means

Object::to_commit_ref() is a convenience wrapper around try_to_commit_ref() that expects decoding to succeed. It panics when the object's kind is not a commit or the commit data cannot be decoded, as documented in its # Panic section.

Solutions

  1. Check the object kind first: if obj.kind != gix_object::Kind::Commit, handle it or peel tags to a commit.
  2. Use try_to_commit_ref() and handle the Result instead of panicking.
  3. Peel the object to the desired kind via obj.peel_to_kind(gix_object::Kind::Commit)? before converting.

Example fix

// before
let commit = obj.to_commit_ref(); // panics if not a commit
// after
let commit = match obj.kind {
    gix_object::Kind::Commit => obj.to_commit_ref(),
    _ => obj.peel_to_kind(gix_object::Kind::Commit)?
        .expect("peeled")
        .to_commit_ref(),
};
Defensive patterns

Strategy: type-guard

Validate before calling

if obj.kind == gix_object::Kind::Commit {
    let commit = obj.to_commit_ref();
}

Type guard

fn is_commit(obj: &gix::Object) -> bool { obj.kind == gix_object::Kind::Commit }

Prevention

When it happens

Trigger: Calling to_commit_ref() on an Object whose kind is a blob, tree, or tag; calling it on a malformed/corrupt commit object that fails to decode.

Common situations: Working with objects obtained from a rev-spec that resolved to a non-commit (e.g. a tag or tree); repositories with corrupted objects; assuming a short hash pointed at a commit.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

AI-assisted analysis of GitoxideLabs/gitoxide@e73179060b (2026-09-08). Data as JSON: /api/errors/66367f45b33f54da. Report an issue: GitHub.

Appendix: source

Thrown at gix/src/object/mod.rs:170

        }
    }

    /// Sever the connection to the `Repository` and turn this instance into a standalone object.
    pub fn detach(self) -> ObjectDetached {
        self.into()
    }
}

/// Conversions to detached, lower-level object types.
impl<'repo> Object<'repo> {
    /// Obtain a fully parsed commit whose fields reference our data buffer,
    ///
    /// # Panic
    ///
    /// - this object is not a commit
    /// - the commit could not be decoded
    pub fn to_commit_ref(&self) -> gix_object::CommitRef<'_> {
        self.try_to_commit_ref().expect("BUG: need a commit")
    }

    /// Obtain a fully parsed commit whose fields reference our data buffer.
    pub fn try_to_commit_ref(&self) -> Result<gix_object::CommitRef<'_>, conversion::Error> {
        gix_object::Data::new(&self.data, self.kind, self.id.kind())
            .decode()?
            .into_commit()
            .ok_or(conversion::Error::UnexpectedType {
                expected: gix_object::Kind::Commit,
                actual: self.kind,
            })
    }

    /// Obtain an iterator over commit tokens like in [`to_commit_iter()`][Object::try_to_commit_ref_iter()].
    ///
    /// # Panic
    ///
    /// - this object is not a commit

View on GitHub (pinned to e73179060b)