Local repositories walkthrough

Last Section:

Local repositories are probably the most important part of floro to understand. The easiest way to learn how a local repository works is by seeing them in action. We will structure this section more as a guide and less as an overview.

The first thing we are going to do is create a new repository.

This will bring us to the remote repository page. We have not cloned this repository yet, we've just created it. Therefore, there is no local representation of the repository on our device yet.

Cloning repositories

Cloning is the process of downloading a repository to your computer, so you can interact with the repository locally.

Any repository you see on floro, can be cloned. Like in git, when you clone a repository, you are downloading the entire version history of the repository. This means for larger repositories and repositories with many commits, this may take a little while. You do not have to stay on the repository page while it is cloning. However, you must keep floro running for cloning to progress. If cloning gets interrupted for any reason, you can always resume cloning or delete the partially cloned repository.

Local & remote tabs

After cloning, you'll notice there are now two tabs in the upper-left corner of the page. Local & Remote. You can toggle between the local representation of a repository and the remote by alternating between these two tabs.

Hot Key Tip: “Control Shift P” (Ctrl+Shift+P) toggles the version control panel.

Command modes

Local repositories are a little bit funny in that they have multiple command modes. If you try to start editing a repository without being in edit mode, you'll notice you can't edit anything. By default, you will start off in view mode.

To enter edit mode you need to press the orange edit button to the left of the Local/Remote tab in the upper right corner.

To toggle view mode, you need to press the purple preview button.

Hot Key Tip: “Control Shift E” (Ctrl+Shift+E) toggles between the view & edit modes.

Command modes only work on local repositories. Remote repositories cannot be edited directly.

Finally, to trigger compare mode, we hit the compare button in the version control panel on the right side of the screen.

Compare mode isn't too useful to us yet as we haven't made any changes to our repository. However, compare mode is where we compare changes, commit our work, and merge local branches after we've made some changes.

Hot Key Tip: “Control Shift C” (Ctrl+Shift+C) triggers compare modes.

We will revisit compare mode in greater depth in a section below.

Creating a branch

To create a branch first enter view mode. Next click on the purple branches button.

There's not much to see in the branches page as we haven't made any changes to our repository yet. We should see the button to create a new branch though.

We're now going to create our first branch, as is the case, I've named our branch Our First Branch, you can name a branch anything. In many version control systems, it is common for larger teams to add the author's initials to branch names, there are many other team-specific conventions for naming branches. We're not going to be too strict in this example though. It is good practice to know that branch names usually should briefly describe what you are going to do.

Our base branch is set to main. Generally speaking, you will want your base branch to be set to main. There are some cases (particularly for developers developing plugins) when you want your base branch to be something other than main but for the most part, you should almost always make main your base branch when working in a floro repository.

You can exit the branches section by hitting the back arrow in the upper right corner of the version control panel.

Installing a plugin & making our first change

To make our first change, we're going to first install a plugin.

To do this enter edit mode. Next, click on the orange view button under the suggested plugins part of the home page.

You should see a screen that looks something like the one above. Install the latest version of the plugin. 

You can close the modal window after installing. You should now see an option on the left navigation bar (under the home icon) to open the text plugin. Click on the text plugin icon from the left navigation bar.

We fully document the text plugin in the plugin documentation section, we will not cover the details of the text plugin in this section. For now, just open up the Main group and edit the Phrase Key hello world to say anything you'd like.

That's it! If we now enter compare mode we should be able to view our first diff.

In the upper right corner of the screen, you will see the option to toggle between removed and added. This toggle shows you what changes were added to the plugin and what changes were removed from the plugin.

Making the first commit

Ensure you are still in compare mode. Now, press the commit button in the lower right corner.

To commit, write a short message that summarizes your diff. In the image above, I made my commit message, "Added the text plugin and altered the default Hello World phrase key."

Commit messages should be a summary of what you did, while branch names should be a summary of what you intend to change. Finally, press the commit changes button. You've now made your first commit.

Pushing your first branch

After committing, we will be back in view mode. We can now push the push local button in the lower right corner.

Pushing can be a little slow, especially when you have a large number of changes that need to sync up to the remote repository.

We can now toggle over to the Remote repository tab.

We should now see our branch available to us in the branch dropdown. If we select our branch we will see the changes we made remotely.

As you can see, we are able to delete our branch remotely but we are not able to merge it yet. In order to merge our branch into the main branch we need to first open up a merge request.

Next section

We will return to our local repository in the section following the next. First we will cover merge requests and remote merging.

In the next section we will be covering navigating remote repositories.