How to use the command "sg" (with examples)

The sg command is a versatile tool used for code structural search, lint, and rewriting. It provides a range of functionalities to scan code, rewrite it, and visualize changes. This article will guide you through several use cases to demonstrate how to use the sg command effectively.

Use case 1: Scan for possible queries using interactive mode

Code:

sg scan --interactive

Motivation: The interactive mode of the sg command allows you to scan your codebase for potential queries. This is especially useful when you want to explore your code and identify sections that need attention. By running this command, you can find relevant patterns in your code and gain a better understanding of its structure.

Explanation:

• sg: The command name to invoke the tool.
• scan: The subcommand to initiate the scan.
• --interactive: A flag that enables interactive mode, allowing you to explore and query your codebase.

Example output: In interactive mode, the sg command will present you with a prompt where you can enter queries and explore the code. It will display the matching code sections and allow you to navigate through them. This feature enables efficient code investigation and analysis.

Use case 2: Rewrite code in the current directory using patterns

Code:

sg run --pattern 'foo' --rewrite 'bar' --lang python

Motivation: Sometimes, you may need to make changes to your codebase based on certain patterns. Whether it’s renaming variables, updating function calls, or replacing specific strings, the sg command with rewriting functionality simplifies these tasks. By providing the pattern to search for and the desired rewrite pattern, you can efficiently make bulk changes to your code.

Explanation:

• sg: The command name to invoke the tool.
• run: The subcommand to execute the rewriting operation.
• --pattern 'foo': Flag specifying the pattern to search for.
• --rewrite 'bar': Flag specifying the rewrite pattern.
• --lang python: Flag specifying the language to target (in this case, Python).

Example output: Running the above command will search for the pattern “foo” in the codebase and rewrite it with “bar”. The command will then apply these changes to all occurrences of “foo” in the files of the current directory, effectively replacing them with “bar”.

Use case 3: Visualize possible changes without applying them

Code:

sg run --pattern 'useState<number>($A)' --rewrite 'useState($A)' --lang typescript

Motivation: Before applying changes to your code, it is often helpful to visualize the modifications that would occur. The sg command provides a convenient way to preview changes without actually executing them. This is particularly useful to ensure that the proposed changes are accurate and in line with your intentions.

Explanation:

• sg: The command name to invoke the tool.
• run: The subcommand to execute the rewriting operation.
• --pattern 'useState<number>($A)': Flag specifying the pattern to search for.
• --rewrite 'useState($A)': Flag specifying the rewrite pattern.
• --lang typescript: Flag specifying the language to target (in this case, TypeScript).

Example output: When running the command, it will identify all instances of the pattern “useState($A)” in the TypeScript code and display the possible changes if this pattern were replaced with “useState($A)”. This allows you to review the modifications visually and ensure they align with your expectations.

Use case 4: Output results as JSON, extract information using jq and interactively view it using jless

Code:

sg run --pattern 'Some($A)' --rewrite 'None' --json | jq '.[].replacement' | jless

Motivation: Extracting and processing information from the sg command’s output can be valuable when you want to further analyze or interactively view the results. By combining the sg command with other tools like jq and jless, you can extract specific data, format it, and navigate through it conveniently.

Explanation:

• sg: The command name to invoke the tool.
• run: The subcommand to execute the rewriting operation.
• --pattern 'Some($A)': Flag specifying the pattern to search for.
• --rewrite 'None': Flag specifying the rewrite pattern.
• --json: Flag to format the output as JSON.
• | jq '.[].replacement': Uses the jq command to extract the “replacement” field from the JSON output.
• | jless: Uses the jless command to interactively view the extracted data.

Example output: Running this command performs a code search for the pattern “Some($A)” and replaces it with “None”. The output is then formatted as JSON. By piping the JSON output to jq, we extract the “replacement” field, which contains the modified code sections. Finally, the extracted data can be interactively viewed using jless, providing a convenient way to navigate through the output.

Conclusion:

The sg command proves to be a powerful tool for code structural search, linting, and rewriting. It offers various features to help you scan, modify, and visualize your codebase efficiently. By exploring and applying these use cases, you can effectively leverage the capabilities of the sg command and improve your overall coding experience.