Working with MQL5 Algo Forge

MQL5 Algo Forge is the Git-based built-in version control and storage in MetaEditor. It works primarily with the MQL5 folder (containing all algorithms) and the special Shared Projects directory (housing all public projects).

Git is a version control system that records how your files looked at different points in time. It helps prevent the loss of important changes, makes it easy to roll back, supports branching for experiments, and enables multiple developers to collaborate on the same project. Studying Git basics from the official docs may help.

A commit represents the state of files at a specific point in time. Each commit has a unique identifier and message describing the changes. A project's history is tracked through commits, branches, and the relationships between them.

You can view when changes were made, who made them, which files were changed, and what was included in each commit. You can also compare file versions, restore previous file states, switch between branches, and revert selected changes when necessary.

When working in a shared project or collaborative space, you are strongly advised to pull changes regularly. This ensures Git automatically merges non-conflicting changes from remote with the local copy. However, if two users change the same line of code or introduce competing changes, a conflict may occur. You will have to resolve conflicts before you commit or push new changes to remote.

Basic workflow:

1. Pull changes from remote first. When you start, your local working copy should match the remote version in MQL5 Algo Forge.
2. Modify files or make changes. Edit code, add new files, fix bugs, or implement features. MetaEditor automatically detects the changes.
3. Commit changes locally. For convenience, MetaEditor automatically pushes the added commit to remote.

Getting Started #

Ensure your MQL5.community account is signed into MetaEditor. Do one of the following to start working in a directory with Git enabled:

• Use the command to add a file/folder to Git in MetaEditor on a file or folder inside the MQL5 folder but outside Shared Projects. A new commit will appear in the MQL5 repository.
• Create a new project in Shared Projects. The new project will appear as a separate repository under your account on MQL5 Algo Forge website.
• Fork a public project on MQL5 Algo Forge website, then clone it in MetaEditor. The full project files will appear under Shared Projects.

Git is a command-line program, but MetaEditor provides a convenient interface for working with it via clicks. You can access Git commands from various locations:

1. Right-click a file/folder under "Navigator".

2. Right-click a tab.

3. Right-click any text or empty space within the code editor.

4. In the top menu, click "Git".

These commands perform Git operations and interact with MQL5 Algo Forge:

• Git Pull – retrieve the latest version or fetch changes from remote. Git downloads the latest commits from the server and merges them into your local project.
• Git Push – send local changes to remote. MetaEditor runs Git Push automatically after each Git Commit, but you can also run it manually if the automatic push fails.
• Git Commit – save the current state of your project to the version history, with MetaEditor pushing the changes to remote automatically. A commit acts as a checkpoint, allowing you to return to that version later if needed.
• Git Add File/Folder – add an entire folder or specific file to staging, with MetaEditor pushing the changes to remote automatically.
• Git Difference – review changed files in staging before committing. The comparison panel shows added, deleted, or modified lines.
• Git Revert – delete staged changes that are yet to be committed.
• Git Log – show all commits with their date, author, and commit message. This lets you track who changed what and when.
• Git Branch – access a menu to create a new branch and switch between branches. Each branch is a separate line of development that you can use for tests and later discard or merge into the main branch.

Adding Files #

To add a local folder or file to the MQL5 repository, right-click it and choose "Git Add File/Folder". A dialog box listing the files to be added will appear.

Ensure the files you want to add are selected, then click "OK". MetaEditor will add the files via a commit and immediately push the commit to remote.

Added (tracked) files are marked with .

Creating Branches #

A branch acts as a parallel sandbox where you can safely develop new features or fixes without affecting the stable codebase. Once your work in a new branch is finished and thoroughly tested, the branch can be merged into the main project.

Right-click the file/folder, select "Git Branch" and choose "New". In the dialog that appears, enter a name for the branch, then click "OK".

You can then switch to the new branch and start working there.

Switching between Branches #

Switching branches lets you safely jump between different sandboxes or timelines in your repository. It instantly updates your working files to match the exact state of the selected branch.

Right-click the file/folder, select "Git Branch". From the list of branches, choose the branch you want to switch to.

Committing Changes #

Modified files and folders are marked with .

Before committing, you can review the changes in a file by right-clicking the file and selecting "Git Difference".

Once you are ready to commit, right-click the file/folder, then select "Git Commit".

In the commit dialog, you can choose the changed files that should be committed and add a comment. Detailed comments facilitate easy analysis of changes in the future.

Click "OK" and MetaEditor will commit the changes and also push them to the remote repository.

After a successful commit-push operation, the corresponding folders and files are marked with .

Pulling Changes #

When collaborating, someone else may update the project before you. You may also commit changes on one computer and continue working on another. Pulling changes ensures that your local project includes the latest updates from the remote repository, helping to avoid conflicts.

To fetch all remote changes, right-click the folder and select "Git Pull". The "Journal" tab will automatically show relevant logs, including the specific changes from remote.

Reverting Changes #

After saving edited code or deleting files, you can easily restore the project to its state before the changes.

To undo changes made to a file/folder, right-click the file/folder, then choose "Git Revert".

Reverting changes in a project with multiple changed files opens a dialog. There, you can select the files whose changes you want to undo and click "OK".

Reverting Commits #

If a specific commit breaks your program or you no longer want its changes, you can quickly undo it.

Right-click the affected file/folder, then choose "Git Log" to open the dialog showing the commit history. Right-click the commit you want to revert, then select "Revert to This Revision".

MetaEditor will add a new commit that reverses the changes from the selected commit while retaining the commit history.

Deleting Files #

To delete a file/folder, right-click it and select "Delete". This action removes the file/folder locally.

To ensure the same file/folder is deleted from the remote storage: Refresh the project, then commit the changes for the deletion. As with all commits, MetaEditor will automatically push the deletion commit to remote.

Deleting Shared Projects #

To delete a project under Shared Projects, right-click the project, then choose "Delete Shared Project".

The local copy will be removed. If you are the original creator of the project, the remote copy will also be deleted.

Viewing Commit History #

The commit history for a specific file/folder shows comments, authors, and dates, helping you track how the file/folder has changed over time.

Right-click the file/folder, then select "Git Log".

The columns at the top include:

• Comment – the description added for the commit
• Author – the name of the user (MQL5.community account login) who made the commit
• Date – the date/time when the commit was made.

Click a commit from the list and the modified, added, or deleted files will appear in the section below.

Icons show the types of changes:

• – file added
• – file changed
• – file deleted.

Right-clicking a commit reveals these options:

• Compare with Working Copy – open a window showing the differences between the current state and the commit.
• Compare with Previous Revision – open a window showing the differences between the previous and selected commit.
• Revert to This Revision – revert the changes in a specific commit.