docs: clarify main branch API semantics

Author: majin.nathan

docs/src/guide/tags_and_branches.md

@@ -15,8 +15,8 @@ The `reference` parameter (used in `create`, `update`, and `checkout_version`) a
 - An **integer**: version number in the **current branch** (e.g., `1`)
 - A **string**: tag name (e.g., `"stable"`)
 - A **tuple** `(branch_name, version)`: a specific version in a named branch
-  - `(None, 2)` means version 2 on the main branch
-  - `("main", 2)` means version 2 on the main branch (explicit)
+  - `(None, 2)` means version 2 on the default branch
+  - `("main", 2)` means version 2 on the default branch (explicit)
   - `("experiment", 3)` means version 3 on the experiment branch
   - `("branch-name", None)` means the latest version on that branch
 

java/src/main/java/org/lance/Dataset.java

@@ -1690,10 +1690,12 @@ public Branches branches() {
 
   /**
    * Create a branch at a specified version. The returned Dataset points to the created branch's
-   * initial version.
+   * initial version. The branch name {@code "main"} is reserved for the default branch and cannot
+   * be used as a new branch name.
    *
    * @param branch the branch name to create
-   * @param ref the reference to create branch from
+   * @param ref the reference to create branch from. In reference contexts, {@code "main"} is an
+   *     alias for the default branch.
    * @return a new Dataset of the branch
    */
   public Dataset createBranch(String branch, Ref ref) {
@@ -1703,10 +1705,12 @@ public Dataset createBranch(String branch, Ref ref) {
 
   /**
    * Create a branch at a specified version. The returned Dataset points to the created branch's
-   * initial version.
+   * initial version. The branch name {@code "main"} is reserved for the default branch and cannot
+   * be used as a new branch name.
    *
    * @param branch the branch name to create
-   * @param ref the reference to create branch from
+   * @param ref the reference to create branch from. In reference contexts, {@code "main"} is an
+   *     alias for the default branch.
    * @param storageOptions the storage options to create branch with
    * @return a new Dataset of the branch
    */
@@ -1727,8 +1731,9 @@ private Dataset innerCreateBranch(
   }
 
   /**
-   * Checkout using a unified {@link Ref} which can be a tag, the latest version on main/branch or a
-   * specified (branch_name, version_number).
+   * Checkout using a unified {@link Ref} which can be a tag, the latest version on the default
+   * branch or a named branch, or a specified (branch_name, version_number). In reference contexts,
+   * {@code "main"} is an alias for the default branch.
    *
    * @param ref the checkout reference
    * @return a new Dataset instance checked out to the specified reference
@@ -1765,7 +1770,7 @@ public Map<String, String> getTableMetadata() {
   public class Tags {
 
     /**
-     * Create a new tag on main branch. This is left for compatibility. We should use {@link
+     * Create a new tag on the default branch. This is left for compatibility. We should use {@link
      * #create(String, Ref)} instead.
      *
      * @param tag the tag name
@@ -1780,7 +1785,8 @@ public void create(String tag, long versionNumber) {
      * Create a new tag on a specified branch.
      *
      * @param tag the tag name
-     * @param ref the referenced version to tag
+     * @param ref the referenced version to tag. In reference contexts, {@code "main"} is an alias
+     *     for the default branch.
      */
     public void create(String tag, Ref ref) {
       Preconditions.checkArgument(tag != null, "Tag name cannot be null");
@@ -1797,6 +1803,8 @@ public void create(String tag, Ref ref) {
      *
      * @param tag the name of the tag to create
      * @param versionNumber the version number (or commit reference) to associate with the tag
+     * @param targetBranch the branch to tag. In reference contexts, {@code "main"} is an alias for
+     *     the default branch.
      */
     @Deprecated
     public void create(String tag, long versionNumber, String targetBranch) {
@@ -1816,11 +1824,11 @@ public void delete(String tag) {
     }
 
     /**
-     * Update a tag to a new version_number on main. This is left for compatibility. We should use
-     * {@link #update(String, Ref)} instead.
+     * Update a tag to a new version_number on the default branch. This is left for compatibility.
+     * We should use {@link #update(String, Ref)} instead.
      *
      * @param tag the tag name
-     * @param versionNumber the versionNumber on main.
+     * @param versionNumber the versionNumber on the default branch.
      */
     public void update(String tag, long versionNumber) {
       Preconditions.checkArgument(versionNumber > 0, "version_number must be greater than 0");
@@ -1831,7 +1839,8 @@ public void update(String tag, long versionNumber) {
      * Update a tag to a new reference.
      *
      * @param tag the tag name
-     * @param ref the referenced version to tag
+     * @param ref the referenced version to tag. In reference contexts, {@code "main"} is an alias
+     *     for the default branch.
      */
     public void update(String tag, Ref ref) {
       Preconditions.checkArgument(tag != null, "tag cannot be null");
@@ -1883,7 +1892,8 @@ public class Branches {
     /**
      * Delete a branch and its metadata.
      *
-     * @param branchName the branch to delete
+     * @param branchName the branch to delete. {@code "main"} is reserved for the default branch and
+     *     cannot be deleted as a named branch.
      */
     public void delete(String branchName) {
       try (LockManager.WriteLock writeLock = lockManager.acquireWriteLock()) {

java/src/main/java/org/lance/Ref.java

@@ -41,21 +41,33 @@ public Optional<String> getTagName() {
     return tagName;
   }
 
+  /** Creates a reference to a specific version on the default branch. */
   public static Ref ofMain(long versionNumber) {
     Preconditions.checkArgument(versionNumber > 0, "versionNumber must be greater than 0");
     return new Ref(Optional.of(versionNumber), Optional.empty(), Optional.empty());
   }
 
+  /** Creates a reference to the latest version on the default branch. */
   public static Ref ofMain() {
     return new Ref(Optional.empty(), Optional.empty(), Optional.empty());
   }
 
+  /**
+   * Creates a reference to the latest version on a branch.
+   *
+   * <p>In reference contexts, {@code "main"} is an alias for the default branch.
+   */
   public static Ref ofBranch(String branchName) {
     Preconditions.checkArgument(
         branchName != null && !branchName.isEmpty(), "branchName must not be empty");
     return new Ref(Optional.empty(), Optional.of(branchName), Optional.empty());
   }
 
+  /**
+   * Creates a reference to a specific version on a branch.
+   *
+   * <p>In reference contexts, {@code "main"} is an alias for the default branch.
+   */
   public static Ref ofBranch(String branchName, long versionNumber) {
     Preconditions.checkArgument(
         branchName != null && !branchName.isEmpty(), "branchName must not be empty");

python/python/lance/dataset.py

@@ -926,12 +926,14 @@ def create_branch(
         Parameters
         ----------
         branch: str
-            Name of the branch to create.
+            Name of the branch to create. ``"main"`` is reserved for the
+            default branch and cannot be used as a new branch name.
         reference: Optional[int | str | Tuple[Optional[str], Optional[int]]
             An integer specifies a version number in the current branch; a string
             specifies a tag name; a Tuple[Optional[str], Optional[int]] specifies
             a version number in a specified branch. (None, None) means the latest
-            version_number on the main branch.
+            version_number on the default branch. ``("main", version)`` is an
+            explicit alias for the default branch in this reference context.
         storage_options: Optional[Dict[str, str]]
             Storage options for the underlying object store. If not provided,
             the storage options from the current dataset will be used.
@@ -2863,7 +2865,8 @@ def checkout_version(
             An integer specifies a version number in the current branch; a string
             specifies a tag name; a Tuple[Optional[str], Optional[int]] specifies
             a version number in a specified branch. (None, None) means the latest
-            version_number on the main branch.
+            version_number on the default branch. ``("main", version)`` is an
+            explicit alias for the default branch in this reference context.
 
         Returns
         -------
@@ -4616,7 +4619,8 @@ def shallow_clone(
             An integer specifies a version number in the current branch; a string
             specifies a tag name; a Tuple[Optional[str], Optional[int]] specifies
             a version number in a specified branch. (None, None) means the latest
-            version_number on the main branch.
+            version_number on the default branch. ``("main", version)`` is an
+            explicit alias for the default branch in this reference context.
         storage_options : dict, optional
             Object store configuration for the new dataset (e.g., credentials,
             endpoints). If not specified, the storage options of the source dataset
@@ -6930,7 +6934,8 @@ def create(
             An integer specifies a version number in the current branch; a string
             specifies a tag name; a Tuple[Optional[str], Optional[int]] specifies
             a version number in a specified branch. (None, None) means the latest
-            version_number on the main branch.
+            version_number on the default branch. ``("main", version)`` is an
+            explicit alias for the default branch in this reference context.
         """
         self._ds.create_tag(tag, reference)
 
@@ -6962,7 +6967,8 @@ def update(
             An integer specifies a version number in the current branch; a string
             specifies a tag name; a Tuple[Optional[str], Optional[int]] specifies
             a version number in a specified branch. (None, None) means the latest
-            version_number on the main branch.
+            version_number on the default branch. ``("main", version)`` is an
+            explicit alias for the default branch in this reference context.
         """
         self._ds.update_tag(tag, reference)
 

rust/lance/src/dataset.rs

@@ -430,7 +430,10 @@ impl Dataset {
         DatasetBuilder::from_uri(uri).load().await
     }
 
-    /// Check out a dataset version with a ref
+    /// Check out a dataset version with a ref.
+    ///
+    /// In reference contexts, `"main"` is an alias for the default branch and
+    /// is equivalent to `None`.
     pub async fn checkout_version(&self, version: impl Into<refs::Ref>) -> Result<Self> {
         let reference: refs::Ref = version.into();
         match reference {
@@ -473,7 +476,9 @@ impl Dataset {
         Ok(())
     }
 
-    /// Check out the latest version of the branch
+    /// Check out the latest version of the branch.
+    ///
+    /// Use `"main"` to check out the latest version of the default branch.
     pub async fn checkout_branch(&self, branch: &str) -> Result<Self> {
         self.checkout_by_ref(None, Some(branch)).await
     }
@@ -493,6 +498,8 @@ impl Dataset {
     /// which can be cleaned up later. Such a zombie dataset may cause a branch creation
     /// failure if we use the same name to `create_branch`. In that case, you need to call
     /// `force_delete_branch` to interactively clean up the zombie dataset.
+    ///
+    /// `"main"` is reserved for the default branch and cannot be used as a new branch name.
     pub async fn create_branch(
         &mut self,
         branch: &str,