Refactoring

Safe and efficient code refactoring tools to help you optimize code structure without breaking code logic. EmmyLua’s refactoring system provides intelligent analysis and conflict detection to ensure your changes are safe.

Rename Refactoring

Rename symbols safely across your entire workspace with intelligent scope analysis and conflict detection.

Quick Operations

Keyboard Shortcut
Context Menu
Prepare Rename

F2 - Rename symbol

Position cursor on a variable, function, class, or field
Press F2
Type the new name
Press Enter to apply or Esc to cancel

local function processData(userData)
    --         ^^^^^^^^^^^ Press F2 here
    local result = userData.name
    return result
end

-- After renaming to 'processUserData':
local function processUserData(userData)
    local result = userData.name
    return result
end

Safety Mechanisms

EmmyLua’s rename refactoring includes multiple safety features to prevent breaking your code.

Scope Analysis

Precisely identify variable scope to avoid miss-renaming

Cross-file Detection

Detect renaming impact on module imports/exports

Conflict Detection

Proactively discover naming conflicts and provide suggestions

Preview Feature

Preview all affected locations before renaming

Scope Analysis

The rename system understands Lua’s scoping rules and only renames symbols within their valid scope.

Local Scope
Global Scope
Module Scope

local function outer()
    local value = 10  -- Scope: outer function
    
    local function inner()
        local value = 20  -- Different scope, won't be renamed
        print(value)
    end
    
    print(value)  -- Renaming this 'value' won't affect inner's 'value'
    inner()
end

Features:

Respects block scope
Handles nested functions correctly
Distinguishes shadowed variables

-- file1.lua
GlobalConfig = { timeout = 30 }

-- file2.lua
print(GlobalConfig.timeout)

-- file3.lua
local config = GlobalConfig

Renaming GlobalConfig updates all files:

Declaration
All references across workspace
Module exports if applicable

-- utils.lua
local M = {}

function M.formatString(str)  -- Renaming affects module API
    return str:upper()
end

return M

-- main.lua
local utils = require("utils")
local result = utils.formatString("hello")  -- Updated automatically

Cross-file Support

Rename refactoring works seamlessly across multiple files.

Module Exports

-- math_utils.lua
local M = {}

function M.calculateArea(width, height)
    return width * height
end

return M

-- app.lua
local utils = require("math_utils")
local area = utils.calculateArea(10, 20)

Renaming calculateArea to computeArea updates:

Function definition in math_utils.lua
All calls in app.lua and other files
Documentation comments referencing the function

Class Members

-- user.lua
---@class User
---@field userName string
local User = {}

function User:new(userName)
    local instance = { userName = userName }
    setmetatable(instance, self)
    self.__index = self
    return instance
end

function User:getUserName()
    return self.userName
end

return User

-- main.lua
local User = require("user")
local user = User:new("John")
print(user:getUserName())

Renaming userName field updates:

Class annotation
Constructor parameter
Field assignment
Field access in methods
All usages in other files

Type References

-- types.lua
---@class UserProfile
---@field name string
---@field email string

-- service.lua
---@param profile UserProfile
local function updateProfile(profile)
    -- Implementation
end

-- controller.lua
---@type UserProfile
local profile = { name = "John", email = "john@example.com" }

Renaming UserProfile updates:

Class definition
All type annotations
Documentation references

Conflict Detection

The system proactively detects potential naming conflicts and prevents problematic renames.

Name Collision
Keyword Conflicts
Type System Conflicts

local function process()
    local value = 10
    local result = 20
    
    -- Trying to rename 'result' to 'value' will be rejected
    -- because 'value' already exists in this scope
    return value + result
end

Conflict types detected:

Variable name collision in same scope
Parameter name conflicts
Field name conflicts in same class
Global name shadowing

local function example()
    local count = 10
    
    -- Renaming 'count' to 'end', 'function', 'local', etc.
    -- will be rejected as these are Lua keywords
    return count * 2
end

Protected names:

Lua keywords (if, then, end, function, etc.)
Built-in functions (print, require, etc.)
Standard library names (if configured)

---@class User
local User = {}

---@class Admin : User
local Admin = {}

-- Renaming 'User' to 'Admin' will be rejected
-- because 'Admin' already exists and inherits from 'User'

Type conflicts:

Duplicate class names
Circular inheritance issues
Type alias conflicts

Rename Types

EmmyLua supports renaming different types of symbols with specialized handling.

Variables
Functions
Classes & Types
Fields & Members

local originalName = "value"
print(originalName)

-- Rename 'originalName' to 'newName'
local function process()
    return originalName .. " processed"
end

Handles:

Local variables
Global variables
Upvalues
Closure variables

local function oldFunctionName(param)
    return param * 2
end

local result = oldFunctionName(5)

-- Rename to 'newFunctionName'
-- Updates definition and all call sites

Handles:

Function declarations
Function expressions
Method definitions
Lambda functions

---@class OldClassName
---@field value number
local OldClassName = {}

---@param obj OldClassName
local function process(obj)
    return obj.value
end

---@type OldClassName
local instance = { value = 42 }

-- Rename 'OldClassName' to 'NewClassName'
-- Updates class definition and all type references

Handles:

Class definitions
Type aliases
Generic types
Union types

---@class Config
---@field oldFieldName string
local Config = {}

function Config:new()
    return { oldFieldName = "default" }
end

function Config:getField()
    return self.oldFieldName
end

-- Rename 'oldFieldName' to 'newFieldName'
-- Updates field annotation, assignments, and access

Handles:

Table fields
Class fields
Object properties
Method names

Preview Changes

Before applying a rename, you can preview all the changes that will be made.

Initiate Rename

Press F2 or right-click and select “Rename Symbol”.

Enter New Name

Type the new name in the input box.

Review Changes

Some editors show a preview of all locations that will be changed:

File paths
Line numbers
Before/after code snippets
Number of changes per file

Apply or Cancel

Press Enter to apply all changes
Press Esc to cancel
Some editors allow selective application

Best Practices

Use Descriptive Names

Choose clear, descriptive names that reflect the symbol’s purpose:

-- Before: unclear naming
local function proc(d)
    return d * 2
end

-- After: clear naming
local function processValue(data)
    return data * 2
end

Follow Naming Conventions

Maintain consistent naming conventions:

-- Functions: camelCase
local function calculateTotal() end

-- Classes: PascalCase
---@class UserManager
local UserManager = {}

-- Constants: UPPER_SNAKE_CASE
local MAX_RETRIES = 3

-- Private members: underscore prefix
function UserManager:_validateInput() end

Check Dependencies

Before renaming public APIs, consider:

External dependencies
Backward compatibility
Documentation updates needed
Deprecation periods

Test After Renaming

Always test your code after performing renames:

Run unit tests
Check for runtime errors
Verify behavior is unchanged
Review all modified files

Limitations

Current limitations:

Standard library symbols cannot be renamed
External library symbols are protected from renaming
Dynamic field access (obj[varName]) may not be detected
String-based references require manual updates

Configuration

Rename behavior can be configured (future enhancement):

{
  "refactoring": {
    "rename": {
      "prepareProvider": true,
      "crossFile": true,
      "detectConflicts": true
    }
  }
}

Use Prepare Rename (hover before renaming) to check if a symbol can be safely renamed before initiating the rename operation.

Getting Started

CLI Tools

Configuration

Features

Rename Refactoring

Quick Operations

Safety Mechanisms

Scope Analysis

Cross-file Detection

Conflict Detection

Preview Feature

Scope Analysis

Cross-file Support

Conflict Detection

Rename Types

Preview Changes

Best Practices

Limitations

Configuration

Build docs developers (and LLMs) love

Getting Started

CLI Tools

Configuration

Features

​Rename Refactoring

​Quick Operations

​Safety Mechanisms

Scope Analysis

Cross-file Detection

Conflict Detection

Preview Feature

​Scope Analysis

​Cross-file Support

​Conflict Detection

​Rename Types

​Preview Changes

​Best Practices

​Limitations

​Configuration

Build docs developers (and LLMs) love

Rename Refactoring

Quick Operations

Safety Mechanisms

Scope Analysis

Cross-file Support

Conflict Detection

Rename Types

Preview Changes

Best Practices

Limitations

Configuration