Configuring Two-Space Indentation for Ruby Files in Sublime Text

The Core Issue of Indentation Configuration

In Sublime Text, indentation settings are fundamental to code editing. Many developers prefer two-space indentation for languages like Ruby, but the editor may default to four spaces or other values. The problem is that temporary adjustments via menu options often fail to persist, especially when creating new files or reopening the editor, as settings revert to defaults. This is primarily due to Sublime Text's automatic indentation detection mechanism, which overrides manual configurations based on file content or project settings.

Global vs. Syntax-Specific Settings

Sublime Text offers two main configuration methods: global settings and syntax-specific settings. Global settings, accessed via Preferences -> Settings - Default/User, apply to all file types. However, for specific languages like Ruby, syntax-specific settings are recommended, as they allow fine-tuned configurations per file type, avoiding potential conflicts from global settings.

The syntax-specific settings entry is under Preferences -> Settings - Syntax Specific, but note that this option is only visible when a file of the corresponding language is active. For example, you must open a Ruby file to access the Ruby.sublime-settings configuration interface.

Step-by-Step Configuration for Ruby Files

To configure fixed two-space indentation for Ruby files, first open any Ruby file (with a .rb extension), then navigate to Preferences -> Settings - Syntax Specific via the menu. This opens an editing interface for a file named Ruby.sublime-settings.

Add or modify the following parameters in this file:

{
  "tab_size": 2,
  "translate_tabs_to_spaces": true,
  "detect_indentation": false
}

Here, tab_size defines the number of spaces per tab character, set to 2 for two spaces; translate_tabs_to_spaces set to true ensures that pressing the Tab key inserts spaces instead of tab characters; and detect_indentation set to false is crucial, as it disables the editor's automatic indentation detection, preventing settings from being overridden.

In-Depth Analysis of Configuration Parameters

The tab_size parameter affects not only new indentation inputs but also the display width of existing tab characters. When translate_tabs_to_spaces is enabled, all Tab key inputs are converted to the specified number of spaces, which is essential for maintaining code style consistency.

The role of detect_indentation is often underestimated. When set to true, Sublime Text analyzes the existing indentation patterns in file content and automatically adjusts settings to match. While this can be convenient for handling external code, it leads to configuration instability in projects requiring fixed indentation standards. Setting it to false ensures user-defined values always take precedence.

Configuration Verification and Troubleshooting

After configuration, no editor restart is required for changes to take effect. Test by creating a new Ruby file and entering code: pressing Tab should insert two spaces, not four. If settings do not apply, check for common issues such as unsuccessful saving of the configuration file, overrides by other plugins or project settings, or testing in non-Ruby files.

For other programming languages, repeat the same process: open a file of the target language, access syntax-specific settings, and add the same parameters. For example, configuring JavaScript files involves modifying the JavaScript.sublime-settings file.

Advanced Indentation Conversion Techniques

Beyond configuring indentation for new files, Sublime Text offers powerful conversion tools for existing code. If a file's indentation does not meet standards, use the editor's bottom status bar for quick adjustments.

The status bar shows the current file's indentation mode (e.g., "Tab Size: 4"), and clicking this area opens a conversion menu. Select "Convert Indentation to Spaces" to convert all tab characters to spaces, using the current tab_size value.

For more complex scenarios, such as changing four-space indentation to two spaces, employ a "spaces to spaces" conversion strategy: first convert the file to tab indentation, adjust tab_size to 2, then convert back to space indentation. This method leverages the variable width of tab characters to achieve precise indentation level adjustments.

Project-Level Configuration and EditorConfig Integration

In team development environments, ensuring all members use the same indentation settings is critical. Beyond editor configurations, use the EditorConfig standard for project-level settings.

Create an .editorconfig file in the project root with the following content:

# editorconfig.org
root = true
[*]
indent_style = space
indent_size = 2
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true
[*.md]
trim_trailing_whitespace = false

This configuration specifies space indentation with a size of 2 for all files, along with other code style rules. Sublime Text supports EditorConfig via relevant plugins, automatically applying these settings when the project is opened, ensuring consistency across different editors.

Best Practices and Summary

Effective indentation configuration should combine syntax-specific settings with project-level standards. For Ruby development, always explicitly set indentation parameters in Ruby.sublime-settings and disable automatic detection. In team projects, supplement with an EditorConfig file to ensure environment-agnostic consistency.

By following these methods, you can completely resolve indentation instability in Sublime Text, providing reliable code formatting for Ruby and other languages. Remember, the key to configuration lies in understanding the interactions between parameters, especially the impact of detect_indentation on setting persistence.