doc: Repository::commit() now explains how to create a commit witho…

…ut ref updates.

gix-object/src/lib.rs

@@ -190,7 +190,7 @@ pub struct Tag {
 /// cannot be mutated or serialized. Instead, one will [convert](ObjectRef::into_owned()) them into their [`mutable`](Object) counterparts
 /// which support mutation and serialization.
 ///
-/// An `ObjectRef` is representing [`Trees`], [`Blobs`], [`Commits`], or [`Tags`].
+/// An `ObjectRef` is representing [`Trees`](TreeRef), [`Blobs`](BlobRef), [`Commits`](CommitRef), or [`Tags`](TagRef).
 #[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone)]
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 #[allow(missing_docs)]
@@ -209,7 +209,7 @@ pub enum ObjectRef<'a> {
 /// They either created using object [construction](Object) or by [deserializing existing objects](ObjectRef::from_bytes())
 /// and converting these [into mutable copies](ObjectRef::into_owned()) for adjustments.
 ///
-/// An `Object` is representing [`Trees`], [`Blobs`], [`Commits`] or [`Tags`].
+/// An `Object` is representing [`Trees`](Tree), [`Blobs`](Blob), [`Commits`](Commit), or [`Tags`](Tag).
 #[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone)]
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 #[allow(clippy::large_enum_variant, missing_docs)]

gix/src/repository/object.rs

@@ -342,7 +342,7 @@ impl crate::Repository {
     /// Create a new commit object with `message` referring to `tree` with `parents`, and point `reference`
     /// to it. The commit is written without message encoding field, which can be assumed to be UTF-8.
     /// `author` and `committer` fields are pre-set from the configuration, which can be altered
-    /// [temporarily][crate::Repository::config_snapshot_mut()] before the call if required.
+    /// [temporarily](crate::Repository::config_snapshot_mut()) before the call if required.
     ///
     /// `reference` will be created if it doesn't exist, and can be `"HEAD"` to automatically write-through to the symbolic reference
     /// that `HEAD` points to if it is not detached. For this reason, detached head states cannot be created unless the `HEAD` is detached
@@ -352,6 +352,11 @@ impl crate::Repository {
     /// If there is no parent, the `reference` is expected to not exist yet.
     ///
     /// The method fails immediately if a `reference` lock can't be acquired.
+    ///
+    /// ### Writing a commit without `reference` update
+    ///
+    /// If the reference shouldn't be updated, use [`Self::write_object()`] along with a newly created [`crate::objs::Object`] whose fields
+    /// can be fully defined.
     pub fn commit<Name, E>(
         &self,
         reference: Name,