How to Use the Command 'arc' (with Examples)

Arcanist (often referred to as ‘arc’) is a command-line interface designed for interaction with Phabricator, a suite of open-source tools for peer code review, task management, and project communication. ‘arc’ acts as a bridge between developers’ command-line operations and Phabricator, helping streamline code review processes and maintain consistency across projects.

Use Case 1: Send the Changes to Differential for Review

Code:

arc diff

Motivation:

The arc diff command is pivotal when a developer is ready to have their code changes reviewed by peers or supervisors. It essentially starts the code review process in Phabricator by sending a set of changes, often called a ‘diff’, along with a description, test plan, and other metadata. This is crucial in collaborative environments where multiple developers contribute to a single codebase, ensuring all changes are peer-reviewed before integration.

Explanation:

The command arc diff is straightforward with no additional arguments necessary for the basic operation. It examines the current changes in the working directory against the repository to prepare a diff and submit it to Phabricator. Advanced users can specify additional command-line options to adjust behavior, such as choosing a specific branch or revision base.

Example Output:

$ arc diff

Updating commit message...

Linting...

 Lint OKAY  No lint problems.
 Running unit tests...
 Unit OKAY  No unit test failures.
 
 Created a new Differential revision:
        Revision URI: https://phabricator.example.com/D123
 
 Included changes:
   M    filename.txt

Use Case 2: Show Pending Revision Information

Code:

arc list

Motivation:

After submitting changes for review, a developer might want to get an overview of revisions waiting for feedback or approval. The arc list command is used to display pending revisions that are tied to the current user or project. This ensures developers can track what revisions are still under review, facilitating better project management and communication among team members.

Explanation:

The arc list command examines revisions that are associated with the current repository and user credentials. It outputs a detailed list including revision numbers, statuses, authors, and reviewers.

Example Output:

$ arc list

ACTIVE REVISIONS
  D123  Fix the authentication error
  D124  Improve documentation
  D125  Refactor user dashboard component

Use Case 3: Update Git Commit Messages After Review

Code:

arc amend

Motivation:

Once a revision has been reviewed and requires modifications, developers need to update their local commits accordingly. The arc amend command is commonly used to update the Git commit message or amend it with additional information from the Differential review, such as reviewer comments or approval status. This ensures that the commit history accurately reflects the final state of the revised changes.

Explanation:

To use arc amend, the command examines the latest local commit and amends it with the most recent comments or approval status from Phabricator. This may include appending information such as the Differential revision ID.

Example Output:

$ arc amend

Amended commit to include 'Reviewed by: johndoe, Revision: D123, Approved: true'

Use Case 4: Push Git Changes

Code:

arc land

Motivation:

After a code change has been approved through the review process, it’s time to integrate it into the main codebase. This is done with the arc land command, which merges the changes into the target branch, usually ‘master’ or ‘main’, ensuring that all patches have been reviewed and approved before they land. This practice helps maintain a stable and conflict-free codebase.

Explanation:

The arc land command operates by merging the current branch into the upstream target branch. It also handles closing the associated Differential revision and updating the local branch to match the upstream branch, ensuring consistency across the repository.

Example Output:

$ arc land

Landing current branch...

Merging changes from branch 'feature-branch' into 'master'...
Updating Differential revision D123...
Cleaning up...

Done.

Conclusion

The ‘arc’ command is an invaluable tool for managing code reviews and maintaining a healthy, collaborative workflow in software development environments that leverage Phabricator. By using arc diff, arc list, arc amend, and arc land, developers can efficiently track and manage code changes, ensuring that all work is properly reviewed and integrated. Understanding and employing these commands effectively streamlines development processes and enhances overall team productivity.