Getting started
This section walks through the first steps to take when using DataLad Gooey
and describes its main pieces and functions.
In order to start up DataLad Gooey
, double-click the program's icon on your Desktop or in your Explorer if you are on Windows, find it among your Desktop files if you are using Linux, or launch it from the Terminal if you are on Mac [1].
An initial dialog lets you select a base directory.
Navigate to any directory you would like to open up, select it, and click Select Folder
.

If you Cancel
this dialog, the DataLad Gooey will open your home directory.
The root directory can be changed at any later point using the File
→ Set base directory
submenu from the top task bar, or from the right-click context menus of directories in the file tree.

Initial configuration
If you are using DataLad and Git for the first time on your computer, make sure that the first thing you do is to set your Git identity by clicking Utilities
→ Set author identity
in the tab at the top of the application.
Add your name and email address in the resulting dialog.
This information will be used to include author information to the commands you will be running, and is required for many commands.

Application Overview
The User Interface
In general, the DataLad Gooey interface has three main sections: A tree view on the upper left, pane on the upper right containing Command
, Metadata
, History``and ``Properties
tabs, and the different log views at the bottom.

The tree view should display files and directories on your computer, starting from the root directory picked at start up.
Double-clicking directories allows you to expand their contents, and to navigate into directory hierarchies.
Double-clicking files will attempt to open them in your systems configured default application.
You will notice that the Type
and State
annotations next to the file and directory names reveal details about files and directories:
You can distinguish directories and DataLad datasets and files.
Within datasets, files are either annexed-file
's or file
's, depending on how these files are tracked in the dataset.
The State
property indicates the version-state of files, datasets, or directories: A new file, for example, would be annotated with an untracked
state, a directory with a newly added unsaved change would be modified
, and neatly saved content would be annotated with a clean
tag.
In addition to the information in the tree view, the Properties
and History
tab will load information for any selected directory or file.
The History
tab displays past commits associated with the file or directory, and the Properties
tab displays known information such as the annex key or file size of annexed files.
Running a DataLad command
There are two ways of running DataLad command: either through the Dataset
menu at the top, or by right-clicking on files, directories, or datasets in the tree view.
The latter option might be simpler to use, as it only allows commands suitable for the item that was right-clicked on, and prefills many parameter specifications.
The screenshot below shows the right-click context menu of a dataset, which has more available commands than directories or files.

Once a DataLad command is selected, the Command
tab contains relevant parameters and configurations for it.
The parameters will differ for each command, but hovering over their submenus or editors will show useful hints what to set them to, and the Help
tab below displays the commands detailed documentation.
Little system-specific icons in the command panel can help you identify required input, or parameters that were wrongly specified (see detailed screenshot on the right).


Once input validation passes on all parameters, the OK
button will become functional and will execute the command.
The Command log
will continuously update you on the state of running and finished commands, displaying, where available, progress bars, result reports, or command summaries.

During command execution, a small hammer symbol lets you interrupt ongoing commands. If you accidentally started to get
hundreds of Gigabytes worth of files instead of only one directory, clicking this button will stop the command.

Note
The stop button will stop the execution at the next possible chance, which is after the next part of the command (such as the retrieval of the next file) has finished. This means it is not an immediate stop like a CTRL-C
press in the command line, but a safe interruption. This also means that stopping might take longer than you expect, depending on the command that gets interrupted.
Should a command fail, a detailed traceback with details about the failure will be send to the Error log
tab right next to the Command log
.
You can use the information from this tab to investigate and fix problems.