AlistGo/alist · warning

cannot rename a submodule

Error message

cannot rename a submodule

What it means

Rename() iterates the parent tree looking for the entry to rename; when found, its Type is 'commit' — a submodule pointer. Submodules live in .gitmodules and point into another repository, so the tree API cannot rename them, and the driver rejects it explicitly. drivers/github/driver.go:487.

Source

Thrown at drivers/github/driver.go:487

}

func (d *Github) Rename(ctx context.Context, srcObj model.Obj, newName string) error {
	if !d.isOnBranch {
		return errors.New("cannot write to non-branch reference")
	}
	d.commitMutex.Lock()
	defer d.commitMutex.Unlock()
	parentDir := stdpath.Dir(srcObj.GetPath())
	tree, _, err := d.getTreeDirectly(parentDir)
	if err != nil {
		return err
	}
	newTree := make([]interface{}, 2)
	operated := false
	for _, t := range tree.Trees {
		if t.Path == srcObj.GetName() {
			if t.Type == "commit" {
				return errors.New("cannot rename a submodule")
			}
			delCopy := t.TreeObjReq
			delCopy.Sha = nil
			newTree[0] = delCopy
			t.Path = newName
			newTree[1] = t.TreeObjReq
			operated = true
			break
		}
	}
	if !operated {
		return errs.ObjectNotFound
	}
	newSha, err := d.newTree(tree.Sha, newTree)
	if err != nil {
		return err
	}
	rootSha, err := d.renewParentTrees(parentDir, tree.Sha, newSha, "/")

View on GitHub (pinned to 843d9dc814)

Solutions

1. Rename the submodule with git (update .gitmodules and the tree entry) and push.
2. Treat submodule entries as read-only in the mounted view.
3. Hide submodule entries to prevent accidental operations.

for _, t := range tree.Trees {
    if t.Path == srcObj.GetName() && t.Type == "commit" {
        return errors.New("submodule entries cannot be renamed via the tree API")
    }
}

func isSubmoduleTreeEntry(t TreeObj) bool { return t.Type == "commit" }

if err := d.Rename(ctx, obj, name); err != nil && strings.Contains(err.Error(), "submodule") {
    // guide to .gitmodules + git mv
}

When it happens

Trigger: Attempting to rename a submodule entry (tree entry of type 'commit') in a mounted GitHub repository.

Common situations: Submodule directories appearing like normal folders in the file browser and being renamed via the UI.

Related errors

• cannot move a submodule
• cannot download a submodule
• committer email is required
• committer name is required
• author email is required

AI-assisted analysis of AlistGo/alist@843d9dc814 (2026-08-15). Data as JSON: /api/errors/b3e1487020c0961c. Report an issue: GitHub.