Working with files

In the previous chapter, we have introduced the notion of "syncing to the latest revision".

This chapter will go a bit further, and introduce the most common, day-to-day operations users will want to perform on their files.

What are worklists, and commits?

Any work done in HVUI will involve worklists, and commits.

Worklist

A worklist holds files that have been

• modified,
• marked for addition or
• deletion,
• …​

Those modifications are local to the user’s site. They will only be made available for everyone after the user commits the worklist.

Commit

Once a worklist is committed, it becomes a commit, and makes its modifications available for everyone.

In comparison to a worklist, a commit holds "published" modifications, and any user syncing to that commit will benefit from those.

Let’s look at a concrete example illustrating worklists and commits: adding a file to the Hex-Rays Vault!

Adding files to the vault

From the "Local files" widget, I can add a file that is not yet present in the Hex-Rays Vault server:

That file will now be added to the current worklist (one will be created if needed):

For this new file to become available for everyone, the user will need to "commit" the worklist:

Once the worklist is committed, it becomes a commit, and the modifications are then available for everyone:

TIP: Notice how our commit isn’t the first one in the system: another user submitted a commit before us — it’s that commit that added the files we’ve seen in the getting-started portion of this guide.

Modifying files

When working on a file, a user must first check it out for modification:

Just like with the adding, the file will now show in a worklist:

…​and just like with the adding, whatever modification you make to the file, will only be visible to coworkers after committing that worklist.

Committing

Files that have been checked out (e.g. for modification) or opened for adding will go into a worklist until they are committed, which then turns the worklist into a commit. A worklist can be committed to make its changes available to other users: right-click, commit

The worklist becomes a commit:

…​and the worklist is gone:

Synchronizing files

To fetch the latest set of the changes (changes/additions/deletions), use "Get latest revision".

Viewing the history of a file

To get an overview of all of the changes made to a file: right-click, File history

From the "History of …​" widget, you can view any revision of a file.

It’s also possible to synchronize files to older revisions, from this widget.

When asked to do that, HVUI will retrieve that older revision of the file from the server. This is what will now be present on your filesystem.

Notice how the file now shows as 'outdated':

Opening files

On many widgets, it's possible to view/open a file. If the file extension has a corresponding association it will be used to open the file.

File associations

Out-of-the-box, HVUI associates .i64 files with IDA. In addition to that, it provides a default "fallback" "*" association that will cause matching files to be opened in IDA.

Users can specify their file extension associations via a form available from the View menu.

Deleting files

Files can be removed from the server (if they have become unnecessary for example): right-click, delete.

Just like other file actions, the change (deletion) needs to be committed for its effects to be visible on the server.

Reverting changes to files

To revert unwanted changes to a file: right-click, Revert

It is also possible to use "Revert if unchanged" to only revert files that were checked out without actual changes. This is especially useful when used on a selection of files or a directory.

Renaming and Moving Files or Folders

One may wish to rename and/or move around files/folders in their workspace, for that "Checkout for move/rename..." can be used.

Copying Files or Folders

{hvui_app} provides an action to copy files or directories easily. Use "Checkout for copy...".

Finding a file in the vault

When a vault contains a lot of files, manually searching for a file in the directory tree becomes inefficient. To help you locate files easily, you can use the Find in vault…​ action.

You can navigate between the search results by using Next search result and Previous search result, located next to Find in vault…​ both in the toolbar, and in the "Search" menu.

Font styles

As you may have noticed by now, files are shown with different font styles in different circumstances.

A gray font denotes a file that is not in the vault. It has been added or renamed and not yet commited.

A bold font means that this file is being worked on, or has been changed.

An italic font means that it’s not the latest version of this file.

Some combinations are possible, for example a file being resolved (not latest version and being worked on) will have a bold and italic font style. The combination gray (not in vault) and italic (not latest version) is for example not possible.