4 Develop Your Project

In a project, you can use Git repositories to store and version your source code files, the Maven repository to store library files and dependencies, and the Designer to create and edit application extensions and visual applications:

Use this page ... To:

Git Git

Add and manage source code in your project’s Git repositories. You can view files and commits, manage branches and tags, and compare source code files.

Maven Maven

View, upload, and search artifacts in the project's Maven repository.

Designer Designer

Create or edit application extensions and visual applications in a workspace. (The changes you make in the Designer are stored as source code in the Git repository associated with your workspace.)

Manage Source Code Files Using Git Repositories

A Visual Builder Studio project uses hosted Git repositories to store source code files and to provide version control. A project can have just one repository or it can have multiple ones. If you’re developing visual applications or application extensions using the Designer, this Git repository is associated with your project as well as with your workspace, which is a private work area within the Designer. Regardless of whether you’re developing applications inside or outside the Designer, you can choose whether to use a Git repository provided by VB Studio, hosted on Oracle Cloud, or to associate your project with an external Git repository (like GitHub).

This section describes how to manage your Git repository for non-Designer applications. Interacting with a Git repository in the context of the Designer is described in Use the Visual Builder Studio Designer.

Git Concepts and Terms

Git is a distributed version control in which you clone the entire remote (or central) repository, including its history, to your computer. You add and commit the files on your computer and, when you’re done, push the commits to the remote repository.

If you are new to Git, read the Git documentation at https://git-scm.com/book/ and http://git-scm.com/doc to learn more about Git repositories and Git basics, such as remote repositories, cloning, commits, pushes, SHA-1 checksum hashes, branches, and tags.

This documentation uses these terms to describe a project's Git components:

Term Description

Project Git repository

A remote or hosted Git repository of your project.

A project can host multiple Git repositories. You can view all Git repositories from the Repositories drop-down list on the Git page.

Local Git repository

A cloned Git repository on your computer. If you're creating an application extension, your workspace orients you to the right Git repository. It also reflects the current branch in the header.

External Git repository

A Git repository that’s hosted outside the project. It could be a Git repository of another project, or a Git repository available on another platform, such as GitHub or Bitbucket.

Revision

A snapshot of the Git repository at a given time. The revision could be a branch, tag, or commit. The Revisions menu displays the selected Git repository's revisions (branches, tags, and commits).

When entering a search criteria, add a space at the end of the search term to search for an exact match.

To search for a commit, enter the first three characters of the SHA-1 checksum hash of the commit in the search box at the top of the menu. The commit that matches the search term appears next to Commit the Commit icon, at the bottom of the menu.

To copy the revision name to the clipboard, click Copy the Copy icon. For example, while viewing files of a particular commit, you can copy the SHA-1 checksum hash of the commit.

Files view

Displays the Git repository’s files and lets you manage them.

Logs view

Lists and graphically displays the Git repository’s commit history.

Refs view

Displays the Git repository’s branches and tags and lets you manage them.

Compare view

Compares and displays the differences between revisions in a Git repository.

Migrate to Git

If you’ve been using a version control system such as CVS or Subversion and want to migrate to Git, you can use the Git commands in the Git command-line interface to do so:

To migrate from ... Use this command:

CVS

git-cvsimport

For more information, see http://git-scm.com/docs/git-cvsimport.

Subversion (SVN)

git svn

For more information, see http://git-scm.com/docs/git-svn.

Other version control systems

See the Git Book at http://git-scm.com/book/es/v2/Git-and-Other-Systems-Migrating-to-Git.

Set Up a Git Repository

To set up a Git repository for your project, you first create a repository, and then upload application files to it. After you've set up the repository, all project users can access its files.

Create and Manage Git Repositories

You can add multiple Git repositories to a project. You can create an empty Git repository, a Git repository with a readme file, or import files from another Git repository.

You may want to create an empty repository if you plan to upload your application files to it from your computer or import files from another Git repository. Some Git clients can’t clone an empty Git repository. If this is the case with the Git client you use, you may want to create a Git repository initialized with a file.

the project owner icon You must be assigned the project Owner role to create and manage Git repositories.

You can create a Git repository from these pages:

  • The Project Home Project Home page's Repositories tab
  • Git Git page
  • Project Administration Gear: Repositories page
Create an Empty Git Repository
  1. Click + Create Repository.
  2. In the New Repository dialog box, in Name and Description, enter a unique name and a description.
    Once you create a repository, you can’t change its name.
  3. In Initial Content, select the Empty Repository option.
    To initialize the repository with a file, select the Initialize repository with README file option.

    You can add to and format the contents of the readme file using the Markdown markup language. If you don’t want to keep the file after VB Studio creates the repository, delete it.

  4. Click Create.
Enable and Use Git LFS to Version Large Files

If your projects contain large files, especially ones that are modified often, an initial clone can take a long time because your Git client needs to download every version of every file. Git LFS (Large File Storage) minimizes the time needed for downloading large files in your repository by downloading the relevant versions during the checkout process instead of during clone or fetch operations. Git LFS does this by replacing large files in your repository with small pointer files that you'll probably never even see. Git LFS automatically handles the replacements and stores the large file contents on a local file system or a remote server.

In VB Studio, by default, Git LFS is enabled in all Git repositories for the entire organization.

If you need to store large or binary files in your project, this is how you enable and use Git LFS for a repository in the project:

  1. Clone the project's Git repository.

    You can find the URL for the remote repository from the Project Home page's Repositories tab. Click the Clone icon to copy the URL, then paste it to the command line:

    git clone <SSH/HTTPS repository URL>
  2. Enable LFS for the local Git repository:

    git lfs install

    This is required because the + File button on the Git page can't be used to upload or add a binary file directly in a remote Git repository. The only way to add a binary file is through a cloned repository.

  3. Specify the file(s) to track:

    git lfs track *.bin

  4. Stage the files to be committed:

    git add .

    git add .gitattributes

  5. Commit the files to the local repository:

    git commit -A -M "Initial commit using LFS"

  6. Push the commits to the remote repository:

    git push origin master

    When a binary file is pushed to a remote Git repository, it's stored on the VB Studio-connected OCI Object Storage bucket. A reference is added to the Git repository, not to the file.

You must be connected to the Internet and to the remote repository to check out a branch locally. This is required.

When a Git repository that uses Git LFS is deleted, its binary files on OCI Object Storage will also be deleted.

If a connection to the OCI Object Storage bucket cannot be made, you'll see an error message that indicates storage hasn't been enabled.

Import an External Git Repository

If you’ve been using a Git repository on another platform such as GitHub or Bitbucket, you can import files from the external Git repository to your project’s Git repository.

When you import an external Git repository, VB Studio creates a Git repository in the project and copies the branches, tags, and commit history to it from the external Git repository. No changes made to the external Git repository after the import succeeds are reflected in the imported Git repository.
  1. Click + Create Repository.
  2. In the New Repository dialog box, in Initial content, select Import existing repository.
  3. In the text box, enter the URL of in the external Git repository.
    If the imported Git repository is password protected, enter the repository credentials in Username and Password. Note that VB Studio doesn’t store the credentials.
  4. Click Create.

You can also import an existing Git repository to an empty project Git repository from the Git page. If the added hosted Git repository is empty, enter the Git repository’s URL in the Git page's Import existing repository section. Enter any repository credentials, if required, and click Import.

Mirror an External Git Repository

If you’ve been using a Git repository on another platform, such as GitHub or Bitbucket, and don’t want to import it to a project’s Git repository, you can mirror it in VB Studio. Mirroring copies the repository to VB Studio and then VB Studio automatically synchronizes its files. In an active VB Studio project, repositories are synchronized approximately every five minutes, but the duration may vary according to the number of external Git repositories in all projects across the organization.

Note that you can’t add or update files or manage branches of a mirrored Git repository from the project's Git page.

If the external Git repository is a private repository or is password protected, you'll need to create an authentication token, such as GitHub's personal access token or BitBucket's App Password, and use it to provide access to the external Git repository. Never provide your account’s password.

Here's how to mirror an external repository:

  1. In the navigation menu, click Project Administration Gear.
  2. Click Repositories.
  3. Under External Repositories, click + Link External Repository.
  4. In the New Repository dialog box, enter the URL of the external Git repository in URL and the repository description in Description.
  5. Expand the Credentials for non-public repos section and provide the credentials to access the external Git repository.

    In Username, enter the username of the external repository account. In Token, enter the authentication token.

  6. Click Create.
The external repository is now available on the Git page and the the Project Home page's Repositories tab.

When you add an external Git repository, VB Studio shows two URLs in the repository's Clone drop-down menu:

Clone drop-down menu of the Git repository

Use the URL with the external address to access the repository directly. You may want to use this URL to access the repository's updates immediately, but you'll need to enter credentials to access a private repository. Use the URL with the internal address to access the mirrored repository. You'll want to use this URL to access a private repository because it doesn't require credentials.

Manage a Git Repository

After you’ve created a Git repository, you can edit its description, set its default branch, index it, and delete it but you cannot change its name:

Action How To

Edit a Git repository’s description

On the Git page, from the Repositories drop-down list, select the Git repository. In the Files or Logs view, click the repository description to edit it.

Alternatively, on the Project Settings: Repositories page, mouse over the Git repository name, click Options the Options icon, and select Edit. In the Edit Repository dialog box's Description field, enter or edit the repository description, and click Update.

Set the default branch

When you open a Git repository on the Git page, the contents of the default branch are displayed. By default, the master branch of a Git repository is set as the default branch. However, you can set any branch to be the default branch of a Git repository.

On the Project Settings: Repositories page, mouse over the Git repository name, click Options the Options icon, and select Edit. From the Edit Repository dialog box's Default Branch drop-down list, select the branch, and click Update.

Index a Git repository

Indexing a Git repository creates or updates the Git repository index file with the latest changes. A Git index file is a binary file that serves as a virtual staging area for the next commit. This file contains a sorted list of object path names, each with a blob object's permissions and the SHA-1.

To index a repository, on the Project Settings: Repositories page, mouse over the Git repository name, click Options the Options icon, and select Index.

Delete a Git repository

On the Project Settings: Repositories page, mouse over the Git repository name, click Options the Options icon, and select Delete. In the Remove Repository dialog box, click Yes.

Upload Files From Your Computer to the Project’s Git Repository

To upload your application's source code files from your computer to the project’s Git repository, you start by using a Git client to clone the project’s Git repository to your computer. After cloning, you add files, commit the changes to the cloned Git repository, and then push the commit to the project’s Git repository:

  1. Copy the Git repository URL.

    On the Git page, from the Repositories drop-down list, select the Git repository. From the Clone drop-down list, click Copy to clipboard the Copy icon to copy the HTTPS or the SSH URL:

  2. Open the Git client - perhaps the Git CLI.

  3. Navigate to the directory where you want to clone the remote Git repository.

  4. Using the Git client, clone the project’s Git repository.

    For example, if you’re using the Git CLI, use the git clone <repository-url> command. Use the Git repository’s URL copied from step 1.

    Here's an example that uses HTTPS:

    git clone https://john.doe%40oracle.com@developer.us.oraclecloud.com/developer1111-usoracle22222/s/developer1111-usoracle22222_myproject/scm/developer1111-usoracle22222_myproject.git

    Here's an example that uses SSH:

    git clone ssh://usoracle22222.john.doe%40oracle.com@developer.us.oraclecloud.com/developer1111-usoracle22222_myproject/developer1111-usoracle22222_myproject.git

  5. Open the directory to access files.

    You’ll notice a .git subdirectory in the repository directory. Don’t add, delete, or modify the files of the .git subdirectory.

  6. Copy your application files to the cloned Git repository directory.

  7. To add new files to the repository, use the Git client to add them to the repository index.

    For example, if you’re using the Git CLI, use the git add command:

    git add readme.txt

    To add a directory and its files, navigate to the directory and use git add .

  8. Commit the updated files to the cloned Git repository.

    For example, if you're using the Git CLI, use the git commit command to save the changes:

    git commit -am "Sample comment"

  9. Push the commit from the cloned Git repository to the hosted Git repository.

    For example, if you're using the Git CLI, use the git push command:

    git push origin master

Push a Local Git Repository to the Project’s Git Repository

If your application source code files are available in a local Git repository, you can push them to a project’s empty Git repository.

You can use any Git client to push the local Git repository to the remote Git repository:

  1. Copy the URL for the project’s Git repository.

    On the Git page, from the Repositories drop-down list, select the Git repository. From the Clone drop-down list, click Copy to clipboard the Copy icon to copy the HTTPS or the SSH URL, as shown:

  2. Open the Git client - perhaps the Git CLI.

  3. Navigate to the local Git repository directory.

  4. Add the project’s Git repository as the remote repository of the local repository. Use the Git repository’s URL copied from step 1.

    For example, if you’re using the Git CLI, use the git remote add <remote-repository-name> <repository-url> command.

    Here's an example that uses HTTPS:

    git remote add origin https://john.doe%40oracle.com@developer.us.oraclecloud.com/developer1111-usoracle22222/s/developer1111-usoracle22222_myproject/scm/developer1111-usoracle22222_myproject.git

    Here's an example that uses SSH:

    git remote add origin ssh://usoracle22222.john.doe%40oracle.com@developer.us.oraclecloud.com/developer1111-usoracle22222_myproject/developer1111-usoracle22222_myproject.git

    Both examples add a remote repository origin for the repository at developer.us.oraclecloud.com/developer1111-usoracle22222_myproject/developer1111-usoracle22222_myproject.git.

  5. Push the local Git repository to the project’s Git repository.

    For example, if you’re using the Git CLI, use the git push command:

    git push —u origin master

  6. In your project, open the Git page and check the files in the project’s Git repository.

Access a Git Repository Using SSH
  1. On the computer that you'll use to access the Git repository, generate a SSH key pair and upload its private key to VB Studio. See Upload Your Public SSH Key for instructions. Make sure that the Git client can access the private key on your computer.
    Ignore this step if you've already uploaded the SSH public key.
  2. Copy the Git repository’s SSH URL.

    On the Git page, from the Repositories drop-down list, select the Git repository. From the Clone drop-down list, click Copy to clipboard the Copy icon to copy the SSH URL:

  3. Open the Git client - perhaps the Git CLI.
  4. Navigate to the directory where you want to clone the remote Git repository.
  5. Using the Git client, clone the project’s Git repository.

    For example, if you’re using the Git CLI, use the git clone <repository-ssh-url> command:

    git clone ssh://usoracle22222.john.doe%40oracle.com@developer.us.oraclecloud.com/developer1111-usoracle22222_myproject/developer1111-usoracle22222_myproject.git

    If you've already cloned the Git repository to your computer using HTTPS, use the git add remote command to add the SSH URL of the Git repository:

    git remote add ssh-origin ssh://usoracle22222.john.doe%40oracle.com@developer.us.oraclecloud.com/developer1111-usoracle22222_myproject/developer1111-usoracle22222_myproject.git

  6. Commit the updated files to the cloned Git repository.
  7. Push the commit from the cloned Git repository to the hosted Git repository:

    git push ssh-origin master

Add and Manage a Git Repository's Files

You can add and update a Git repository's files online from the Git page or clone the Git repository to your computer and update the files locally.

Manage Files from the Git Page

If you are a project member, you can browse, add, edit, rename, and delete a Git repository's files. You can also view commit histories for the files. However, you cannot add or update files in a linked external Git repository.

You must be a project member to add or update a Git repository's files:

  1. In the navigation menu, click Git Git.
  2. From the Repositories drop-down list, select the Git repository. From the Revisions Revisions drop-down list, select the branch.
  3. On the right side of the page, click Files, if necessary.
  4. Browse and click a directory name to open it.

    To go back to a file's or a sub-directory's parent directory, click / and select the file or directory from the menu. To go to the root directory, click the Root icon. To copy a file's or a directory's path, click Copy to clipboard the Copy icon.

You can perform these file management tasks from the Git page:

Action How To

Add a file

  1. Click + File.
  2. In File Name, enter the name of the file along with its extension.
  3. In the code editor, enter file contents.
  4. Click Commit.
  5. In the Commit Changes dialog box, enter the commit summary in the first text box and details in the Details text box, and click Commit.

To save the file in a new directory or a directory structure, in File Name, enter the file path. You can enter a relative path or an absolute path. To specify an absolute path, add a / in the beginning.

Example:

  • Enter test/text_file.txt to save the text_file.txt file in the test directory on the current path. If the test directory doesn’t exist, it’s created.
  • Enter /test/text_file.txt to save the text_file.txt file in the test directory on the root. If the test directory doesn’t exist, it’s created.

View a file

To view a file's contents, in the Files view, browse, and click the file name link. The file opens in the File view of the Git page. If you open a text file or an image file, its contents are displayed in a read-only editor. A binary file's contents aren’t displayed.

If the text content exceeds the width of the editor, use the arrow keys to scroll left, right, up, and down. You can also use the scroll buttons to scroll horizontally. Move the cursor to the left or the right edge of the editor and click Right Scroll the Right Scroll icon or Left Scroll the Left Scroll icon to scroll one character at a time.

To view the file in raw (unformatted) format in the web browser, click Edit the Edit icon, and select Raw. The contents of the opened file are displayed in a new tab or a window of the web browser. If the file is a text file or an image (such as .png, .jpg, .bmp, and .gif), it’s displayed in the browser. A binary file's contents such as .zip and .rar aren’t displayed, but you can use the browser URL to download it.

View a file's annotations and commits

Open the file and click Blame.

The Blame view displays annotations of the open file for each updated code line (or group of code lines) with commit information. The annotation includes commits that affected code lines, author, the date-time stamp of the commit, and the commit message.

Edit, rename, or move a file

Open the file and click Edit the Edit icon. Edit the file’s contents in the code editor. To rename the file or move it to another directory, in the file name text box, enter the new name or path. Click Commit to save.

Delete a file

To delete a file, click Actions the Actions icon next to Edit the Edit icon, and select Delete. In the Commit Changes dialog box, enter the commit summary in the first text box and details in the Details text box, and click Commit.
Use Git Commands to Manage Files from Your Computer

To access and manage your project’s Git repository files from your computer, use a Git client - perhaps the Git CLI.

Here are some of the most common Git commands you can run in the Git CLI to work on files in your local Git repository.

Run this command ... To:
git clone <repository-url> Clone a project's Git repository to your computer:

git clone https://john.doe%40example.com@developer.us.oraclecloud.com/developer1111-usoracle22222/s/developer1111-usoracle22222_myproject/scm/developer1111-usoracle22222_myproject.git

Note:

Git over HTTPS works if your cloud account uses federation with Oracle Identity Cloud Service. If you are federating with other identity providers, such as Microsoft Azure Active Directory or Microsoft Active Directory, Git over HTTPS won't work. We recommend using Git over SSH instead, when you use federation with identity providers other than Oracle Identity Cloud Service.

git add <filename>

Add a file that you've added to the repository's directory to the repository's index:

git add readme.txt

To add all new files to the index, use git add --all

To add a directory and its contents to the index, navigate to the directory and use git add .

git rm <filename>

Remove a file from the repository:

git rm readme.txt

git status

Check the status of added and edited files:

git status

git branch

Create a branch:

git branch new_branch

To list all existing branches of the repository, use git branch.

git checkout

Checkout and switch to a branch:

git checkout new_branch

You can use the git checkout -b command to create a branch and switch to it immediately: git branch -b new_branch

git merge

Merge a branch with the checked out branch:

git merge new_branch

git commit Commit changes to the local Git repository:

git commit -m "Initial commit"

git push Push commits to the project's Git repository:

git push -u origin master

git pull

Incorporate changes from the project's Git repository to the local Git repository:

git pull origin master

To display the Git help index, run the git help command. Run the git help git command to open the help index in a web browser. To display help for a particular command, run git help <command>.

Work with Git from the Designer

These common Git commands can be used directly from the Git menu in the Designer header:

  • Switch Branch/Switch Sandbox

    If you are working in a branch, use the Switch Branch option or use the Switch Sandbox option if you are working in a sandbox.

  • Commit

    Saves any changes you've made to the local repository. You need to use the "git add" command to explicitly tell Git which changes you want to include in a commit before running the git commit command. Changed files are never automatically added to a commit. Use "-m <message>" to set the commit's message. Use "-a" to include all currently changed files in the commit.

  • Status

    Displays the state of the working directory and the staging area. This command tells you which changes have been staged, which haven’t, and which files aren’t being tracked by Git.

  • Diff

    Compares two input data sets and outputs the changes (differences) between them. This command often used with git status and git log to analyze the current state of a Git repository.

  • Pull

    Downloads and integrates remote changes. The branch that the data is integrated into is always the currently checked out HEAD branch. By default, pull uses a merge operation, but it can be configured to use rebase instead.

  • Push

    Publishes new local commits on a remote server. The branch that the data is uploaded from is always the currently checked out HEAD branch. If a tracking relationship hasn't been set up with the remote branch, the branch the data is uploaded to can be specified in the command's options.

  • Reset to HEAD

    Undoes changes. This command will move the HEAD ref pointer as well as the current branch ref pointer.

  • Merge

    Integrates changes from another branch. The the branch that receives changes is always the currently checked out HEAD branch.

Associate a VB Studio Issue with a Commit

When you save changes to a Git repository, you might want to link a VB Studio issue that’s assigned to you with the commit.

To associate an issue with a commit, add Task-URL: <issue-url> in the commit message:

git commit -AM "Update for Issue 4 Task-URL:https://developer.ourcompany.com/qa-dev/#projects/mydevproject/task/4"

If the commit is successful, the SHA-1 checksum hash of the commit will be added to the issue. If you want, you can open the issue in the Issues page, locate the commit link in the Commits section under Associations, open the commit, and verify the SHA-1 checksum hash.

Alternatively, you could use an abbreviated form, such as "Update for Issue4" in the commit message and you'd see a link to both the commit and the issue in the Activities feed. There wouldn't, however, be a link in the Commits section under Associations in the Issues page.

Copy the URL of a Git Repository or a File

From the Git page, you can copy and share the URL of a Git repository, the URL of a file in the Git repository, and the URL of a line in a file of the Git repository.

Before you share the URL, remember that only members of the project can use the URL to access the file or clone the repository. If the project is a shared project, organization members can access files in the project’s repository or clone the repository, but they can’t update them.

Action How To

Copy the URL of a Git repository

To clone a Git repository or to access it using a Git client, you use the URL of the repository. You can copy the URL from the Repositories tab of the Project Home page, the Git page, and from the Project Settings: Repositories page.

In the Repositories tab of the Project Home page or the Project Settings: Repositories page, search for the Git repository, and click the Clone drop-down list to see the HTTPS and SSH URLs of the repository. To the right of the URL, click Copy the Copy icon (or select the URL and press Ctrl + C or use the mouse context menu) to copy the URL to clipboard.

Note:

Git over HTTPS works if your cloud account uses federation with Oracle Identity Cloud Service. If you are federating with other identity providers, such as Microsoft Azure Active Directory or Microsoft Active Directory, Git over HTTPS won't work. We recommend using Git over SSH instead, when you use federation with identity providers other than Oracle Identity Cloud Service.

The SSH URL of an external Git repository isn’t available.

Copy the URL of a file

In the Files view of the Git page, open the file. From the address bar of the browser, copy the URL.

Copy the URL of a line in a file

In the Files view of the Git page, open the file. On the left side of the line, in the number column, click the line number. The entire line is selected. From the address bar of the browser, copy the URL.

Example: To copy the URL of line number 2 of myfile.txt, click the line number 2. Clicking the line number updates the URL in the browser’s address bar to http://developer.us2.oraclecloud.com/my-org/#projects/demo/scm/demo.git/blob/myfile.txt?revision=master&sl=2. You can copy and use this URL to open myfile.txt in the demo.git repository – master branch with line number 2 selected.

Copy the URL of a group of lines in a file

In the Files view of the Git page, open the file. On the left side of the line, in the number column, click the line numbers with the Shift key pressed to select them. From the address bar of the browser, copy the URL.

Example: With the Shift key pressed, clicking line numbers 2 through 5 of myfile.txt selects those lines. The URL in the browser’s address bar changes to http://developer.us2.oraclecloud.com/my-org/#projects/demo/scm/demo.git/blob/myfile.txt?revision=master&sl=2–5. Copy the URL and share it with project members. When the URL is entered, the myfile.txt file of the demo.git repository – master branch opens with line numbers 2 through 5 selected.

View the History of Files and Repositories

You can use the Logs view of the Git page to view the commits, branching, and merging history of a file or Git repository and its revisions.

  1. From the Repositories drop-down list, select the Git repository. From the Revisions the Revisions icon menu, select the branch.

  2. To view the commit history of a file, browse, and open the file.

    Skip this step to view the commit history of the selected Git repository.

  3. On the right side of the page, click Logs.

Action How To

View the commit history in a list format

In the Logs view, click the History List the List icon toggle button.

To view the history of another branch or tag, in the text box to the right of the History the History icon toggle button, enter branch or tag names. You may also click the text box and select the revisions from the drop-down list. You can add multiple branches or tags. To view the history of all revisions of the selected Git repository, remove all revision names from the text box.

View the commit history as a graph

In the Logs view, click the History Graph the Graph icon toggle button.

In the graph:

  • Each dot represents a commit.

    To see the details of the commit, click the dot.

  • A splitting line represents a branch.

  • Joining lines represent a merge.

  • Latest commits appear at the top of the graph.

Use Branches

Branching lets you work on different features and updates at any time without affecting the original source code.

Before you start working on a new feature or update major portions of the source code, it’s considered a good practice to create a branch and commit your changes to the new branch. This way your changes don’t affect the original source code and are safe to test and review. To learn more about the Git branch workflow, read the Git Branching - Branching Workflows topic in the Git book at https://git-scm.com/book/en/v2/.

By default, all Git repositories have one default master branch. However, you can add more branches to the repository. You can also subscribe to email notifications for commits made to the repository’s branches, and you can compare, rename, and delete branches.

Create a Branch

You can’t create a branch in an empty Git repository. First, you have to clone the repository to your computer, add and commit files to the default master branch that’s automatically created, and then push the branch to the project's Git repository. Only after the master branch has been pushed to the repository, can you create additional branches.

A branch can be marked as a private branch. Only branch owners can push commits to a private branch. You must be a project member to be able to create a branch.

You can create a branch from the VB Studio Designer as well. We'll describe that here too.

From the Git page's Refs view , you can create a branch from the base branch, from the head (tip) of an existing branch, or from a tag:

Action How To

Create a branch from a base branch

  1. In the Git page's Refs view, click Branches Branches.

  2. From the Repositories drop-down list, select the repository.

  3. Click + Create Branch.

  4. In the New Branch dialog box, in Name, enter the branch name. From the Base drop-down list, select the base revision name.

  5. To mark the branch as a private branch, select the Private Branch check box.
  6. Click Create.

Create a branch from the head (tip) of another branch

  1. In the Git page's Refs view, click Branches Branches.

  2. From the Repositories drop-down list, select the repository.

  3. Click + New Branch.

  4. In the branch list, next to the source branch name, click Actions the Actions icon, and select Branch.

  5. In the New Branch dialog box, enter a name for the new branch.

  6. To mark the branch as a private branch, select the Private Branch check box.
  7. Click Create.

Create a branch from a tag

  1. In the Git page's Refs view, , click Tags Tags.

  2. From the Repositories drop-down list, select the repository.

  3. Click + New Branch.

  4. In the tags list, next to the tag name, click Actions the Actions icon and select Branch.

  5. In the New Branch dialog box, enter a name for the new branch.

  6. To mark the branch as a private branch, select the Private Branch check box.
  7. Click Create.
Protect a Branch

By default, any project member can rename or delete a repository branch, and push or merge another branch into it. To protect a branch from these actions, set restrictions on the branch.

the project owner icon You must be assigned the project Owner role to set restrictions on a branch.

  1. In the navigation menu, click Project Administration Gear.
  2. Click Branches.
  3. In Repository and Branches, select the Git repository and the branch.
  4. On the Branches page, set the restrictions.

Tip:

On the Refs page, you can also click the Open, Private, Requires Review, or the Frozen label of a branch to edit its protection settings.

This table describes the various branch protection actions you can perform from the Branches page.

Action How To
Requires review and restrict merge actions Select the Requires Review option and configure the review options. See Set Review and Merge Restrictions on a Repository Branch.
Restrict push actions to project owners and branch owners Select the Private option.

To define branch owners, click Owners and select the user. You can select multiple users.

Note that to push commits to a private branch from your computer, always use SSH. Also, to run a build of job that uses a private branch, configure the job to use SSH.

Lock a branch Select the Frozen option. No changes are allowed to a locked branch by any user.
Prevent forced pushes to the branch Select the Do not allow forced pushes check box. The check box isn't available when the Requires Review or the Frozen option is selected as force push aren't allowed on a review or a frozen branch.
Prevent the rename and delete actions on the branch Select the Do not allow renaming and deleting branch check box. The branch can be renamed or deleted after you deselect the check box. The check box isn't available when the Requires Review or the Frozen option is selected.
Manage a Branch

After you create a branch, you can rename it, compare it with another branch of the Git repository, or delete it.

You must be a project owner or member to edit and update a branch. You can perform the branch management actions from the Refs view of the Git page.

Action How To

Rename a branch

You can’t rename a restricted branch or the master branch.

After renaming a branch, update all related merge requests, build jobs, and deployment configurations to use the new branch name. When you rename a branch, Git creates a branch with the new name and transfers all content from the old branch to the new branch. After the transfer is complete, the old branch is removed.

  1. In the branch list, to the right of branch name, click Actions Actions, and select Rename.

  2. In the Rename Branch dialog box, in Name, enter the new branch name.

  3. Select the I want to rename the branch check box and click Rename.

Compare a branch

In the branch list, to the right of branch name, click Actions Actions, and select Compare. By default, the branch is compared with the master branch.

Protect or set restrictions on a branch In the branch list, to the right of branch name, click Actions Actions, and select Protection Settings.

Delete a branch

You can’t delete a restricted branch or the master branch.

After you delete a branch, you must update, close, or remove all related merge requests, build jobs, and deployment configurations.

  1. In the branch list, to the right of branch name, click Actions Actions, and select Delete.

  2. In the Delete Branch dialog box, select the I want to delete the branch check box, and Delete.

Use Tags

Tagging lets you mark a specific point of time in the history of the repository. For example, you can create a tag to mark the Git repository state of an application’s stable state, before a release.

Create and Manage Tags

From the Refs view of the Git page, you can create and manage a Git repository’s tags.

You must be a project owner or member to create and manage a tag.

Action How To

Create a tag

  1. In the Refs view of the Git page, click Tags Tags.

  2. From the Repositories drop-down list, select the repository.

  3. Click + New Tag.

  4. In the New Tag dialog box, in Name, enter the tag name. In Base, enter the base revision name. Click Create.

Rename a tag

  1. In the tags list of the Tags Tags view, to the right of the tag name, click Actions and select Rename.

  2. In the Rename Tag dialog box, in New Name, enter the new tag name, select the I want to rename the tag check box, and click Rename.

Compare a tag

In the tags list of the Tags Tags view, to the right of the tag name, click Actions and select Compare.

On the Compare page that opens, by default, the tag is compared with the default branch.

Delete a tag

In the tags list of the Tags Tags view, to the right of the tag name, click Actions and select Delete. In the Delete Tag dialog box, select the I want to delete the tag check box and click Delete.

Compare Revisions

You can compare any two revisions of a Git repository. The base revision indicates the starting point of the comparison and the compare revision indicates the end point of the comparison. The revision could be a branch, a tag, or a commit SHA-1 checksum hash.

  1. On the right side of the Git page, click Compare.
  2. From the Base Revision Base Revision drop-down list on the left, select the base revision.
    By default, the Git page selects the last commit of the repository as the base revision and the selected revision as the compare revision.
  3. From the Compare Revision Compare Revision drop-down list on the right, select the compare revision.

You can compare these revisions:

  • Branch versus branch

  • Tag versus tag

  • Commit versus commit

  • Branch versus tag

  • Commit versus branch

  • Tag versus commit

On the Compare Result page, the Changed Files tab and the Commits tab. The Changed Files tab lists files that have changed between the base revision and the compare revision. The Commits tab lists all commits that have happened between the base revision and the compare revision since their common commit. The Commits tab is enabled if From Merge Base is selected in From Merge Base or Revisions From Merge Base or Revisions.

Action How To

Compare with a parent of the base revision

From the Base Revision drop-down list, click the Parents tab, and then click the SHA-1 checksum hash of the parent commit.

View differences between the base revision and the compare revision since the last common commit to both revisions

From the From Merge Base or RevisionsFrom Merge Base or Revisions drop-down list, select From Merge Base (...) . Select Revisions (..) to show the differences between the heads (or tips) of the base revision and the compare revision.

Switch the base revision and the compare revision

Click Switch Base Switch Base.

Create or open a merge request

If a merge request exists with the Compare Revision as the review branch, click the merge request button to open the merge request review page.

If a merge request doesn’t exist, click + Merge Request to create a merge request with Base Revision as the target branch and the Compare Revision as the review branch.

View the compare options

Click Diff Preferences Diff Preferences to view various compare options.

Add Comments to a File

While comparing files, you can add inline comments to the source code changes made to a file. The comments are visible to all users of the project.

  1. Browse and open the file.
  2. On the right side of the page, click Logs.
  3. For the commit that changed the file and added the changes you want to comment on, click the button with the first seven characters of the commit’s SHA-1 checksum hash as the label.
  4. In the Changed Files tab of the Compare view, mouse-over the line number of the file and click Add Comment Add Comment
    If you selected the Unified view, click the line number in the second column. If you selected the Side by Side view, click the line number of the file on the right.
  5. In the Leave a comment box, enter the comment, and click Comment.
The comment is added as an inline comment to the file and is visible to all project members. To reply to a comment, click Reply reply, enter the comment in the Leave a reply box, and click Comment.

Watch a Git Repository

You can watch a Git repository branch and receive email notifications when any file of the branch is updated in the project’s Git repository.

To get email notifications, enable them in your user preferences, and then set up a watch on the branch from the Refs view of the Git page.

Action How To

Enable email notifications

In your user preferences page, select the SCM/Push Activities check box.

Watch a branch

  1. Open the project.

  2. In the navigation menu, click Git Git.

  3. On the right side of the page, click Refs.

  4. If necessary, click Branches Branches.

  5. In the branch list, to the right of the branch name, click cc.

    Alternatively, click Actions Actions, and select Subscribe.

A Subscribed the check mark icon appears indicating that you are subscribed to email notifications of the branch updates. To unsubscribe, click cc again.

Search in Git Repositories

You can search for a file name, directory name, or a term in the source code files, file paths, and file revisions of the project’s Git repositories.

The search field supports common programming languages, such as HTML, JavaScript, CSS, and Java. You can use these features while searching terms:

  • Language-aware

  • Auto-suggest

  • Symbols (class and function names) and file names

  • CamelCase

Action How To

Search for a term in a Git repository and a revision

  1. From the Repositories drop-down list, select the Git repository. From the Revisions the Revisions icon drop-down list, select the revision.

  2. In the top-right corner of the page, in the Search Code box, enter the search term or select it from the suggestion list.

  3. Click Search the Search icon.

Search for a term in all revisions of a Git repository

  1. From the Repositories drop-down list, select the Git repository. From the Revisions Revisions drop-down list, select the revision.

  2. In the top-right corner of the page, in the Search Code box, enter the search term or select it from the suggestion list.

  3. Click Search the Search icon.

  4. In the Revisions the Revisions icon drop-down list, click Reset the Reset icon.

    The Revisions the Revisions icon drop-down list now shows All Revisions.

Search for a term in all Git repositories

  1. From the Repositories drop-down list, select the Git repository. From the Revisions Revisions drop-down list, select the revision.

  2. In the top-right corner of the page, in the Search Code box, enter the search term or select it from the suggestion list.

  3. Click Search the Search icon.

  4. From the Repositories drop-down list, select the All Repositories option, or click Reset the Reset icon.

The search result page displays all files, file paths, and file revisions that contain or match the search term (or symbol). To reset the search, to the left of the Search Code box, click Back the Back icon.

Download a Git Repository's Archive

If a a Git repository's branch or a tag isn’t required and you plan to delete it, it’s considered good practice to create and back up an archive of it before you delete it. From the Refs view of the Code page, you can download an archive file (zip or tgz) for a Git repository's branch or tag:

Action How To

Download a branch's archive

  1. In the Code page's Files view, select the repository from the Repositories drop-down list. From the Revisions the Revisions icon menu, select the branch.

  2. From the Clone drop-down list, click Download ZIP or Download TGZ.

Alternate method:

  1. In the Code page's Refs view, click Branches Branches.

  2. From the Repositories drop-down list, select the repository.

  3. In the branches list, to the right of the branch name, click Actions, select Download, and then select zip or tgz.

Download a tag's archive

  1. In the Code page's Refs view, click Tags Tags.

  2. From the Repositories drop-down list, select the repository.

  3. In the tags list, to the right of the tag name, click Actions, select Download, and then select zip or tgz.

Manage Binaries and Dependencies Using the Project’s Maven Repository

When a project is created, VB Studio creates a hosted Maven repository in the project. You can use the repository to store binary files and dependencies. If you’re developing Maven applications, you can use the Maven repository to store and access build artifacts.

If you see the Connect Your OCI Account message, contact your organization administrator to connect an OCI account.

Maven Concepts and Terms

Apache Maven is a software project management tool that uses the Project Object Model (POM) concept to manage a project's build.

If you’re new to Maven, see https://maven.apache.org to learn about Maven basics such as POM files and Maven repositories.

In VB Studio, you use the project’s Maven repository to store build artifacts and dependencies for your project’s applications. Usually, you store the dependencies on the project’s Maven repository that aren’t available on a public Maven repository, such as Maven Central Repository or Oracle Maven Repository.

Here are the terms that this documentation uses to describe the Maven terms and components of a project.

Term Description

POM file

An XML file that contains configuration about how to build the application. Usually, the file is saved as pom.xml. For more information, see https://maven.apache.org/guides/introduction/introduction-to-the-pom.html.

Browse view

Displays and allows you to browse artifacts of the project’s Maven repository.

Upload view

Allows you to upload artifacts manually to the project’s Maven repository.

Artifact Search view

Enables you to search artifacts in the project’s Maven repository.

To upload and access the files of the repository programmatically, configure the POM file of your application. You can use the project Maven repository among other projects of the organization for local builds as well as project builds.

Upload an Artifact Manually

From the Upload view, you can upload artifacts manually to the project’s Maven repository without installing Maven on your computer. You must be a project owner or member to upload an artifact to the project Maven repository.

  1. In the navigation menu, click Maven Maven.
  2. On the right side of the page, click Upload.
  3. In the Upload Artifacts section, use the drag-and-drop operation to drop files to the drop area, or click the select artifact files link, browse, and select the files.
  4. In the table below the Upload Artifacts section, if necessary, update the Classifier field of the selected artifact.

    If you’re uploading only one artifact, you can leave the classifier field empty. If you’re uploading multiple artifacts, provide the classifier value for each artifact. The classifier helps to distinguish artifacts that were built from the same POM file but differ in their content. The classifier string is appended to the artifact name, after the version number.

    For example, if you’re uploading artifacts with identical names but different extensions (such as fileX-1.0.jar and fileX-1.0.pdf), you may provide classifiers, such as main and documentation for these files. After the files are uploaded, they are renamed to fileX-1.0-main.jar and fileX-1.0-documentation.pdf.

  5. After you add the artifacts, you must specify their Maven coordinates manually or from a POM file. These coordinates are used when uploading artifacts to the project’s Maven repository.

    If you want to specify the artifacts’ Maven coordinates manually, note the following:

    • The auto-suggest list of GroupId, Version, and ArtifactId are based on Maven indexes. If no index data is available, the auto-suggest list isn’t displayed.

    • By default, the Generate POM check box is selected. The upload process deploys the artifact and generates the default POM file, maven-metadata.xml, and associated sha1/md5 checksum files. If maven-metadata.xml already exists, it’s updated.

      If you deselect the check box, the upload process deploys the artifact to the target deployment path based on Maven attributes. The POM file and the maven-metadata.xml file aren’t generated.

  6. Click Start Upload.

    You can track the transfer status and its progress in the drop area of the Upload Artifacts section. To cancel the upload process, click Cancel Upload. The upload process will also be cancelled if the page is refreshed or closed.

Upload Artifacts Using the Maven Command-Line Interface

You can also use the Maven command-line interface to upload artifacts to the project’s Maven repository.

The Maven repository URL is available on the Project Home page of your project. Use the dav: URL to upload files and the http:// URL to view them in the browser.

Note that the credentials in settings.xml aren’t required to access the project Maven repository when running a build. The build job has full access to the project Maven repository for uploads and downloads.

  1. Download and install Maven on your local computer.
    You can download Maven from http://maven.apache.org/download.cgi.
  2. Open MVN_HOME/conf/settings.xml in a text editor and make the following changes.
    1. Specify the proxy server, if necessary.
      Example:
      <proxies>
      	<proxy>
      		<active>true</active>
      		<protocol>http</protocol>
      		<host>PROXY_URL</host>
       		<port>80</port>
       		<nonProxyHosts>www.anything.com|*.somewhere.com</nonProxyHosts>
       	</proxy>
      </proxies>
    2. Specify a unique ID and your VB Studio user name and password to access the project Maven repository.
      Example:
      <servers>
      	<server>
      		<id>remoteRepository</id>
      		<username>USERNAME</username>
      		<password>PASSWORD_IN_PLAINTEXT</password>
      	</server>	
      </servers>
    3. Specify a unique ID, name, and URL for the project Maven repository. You can copy the Maven repository URL from the Repositories tab of the Project Home page.
      Example:
      <profiles>
      	<profile>
      		<id>default</id>
      		<repositories>
      			<repository>
      				<id>remoteRepository</id>
      				<name>My Remote Repository</name>
      				<url>dav:https://developer.us2.oraclecloud.com/……/maven/</url>
      				<layout>default</layout>
      			</repository>
      		</repositories>
      	</profile>
      </profiles>
  3. Open the command-line and follow these commands to upload files to the hosted Maven repository. Ensure that the MVN_HOME/bin path is available in the PATH variable.
    1. Navigate to the directory that contains the files that you want to upload.
    2. Create the pom.xml file, if it hasn’t been created already.
      For more information about pom.xml, see http://maven.apache.org/guides/introduction/introduction-to-the-pom.html.
    3. Run the mvn deploy command to upload files.
      Example: mvn deploy:deploy-file -DpomFile=c:\myproject\pom.xml -Dfile=c:\myproject\myfile.jar -DrepositoryId=remoteRepository -X -Durl=dav:https://developer.us2.oraclecloud.com/……/maven/

Search Artifacts

To search for artifacts, use the Artifact Search view.

You can specify the following search criterion:
  • GroupID

  • ArtifactID

  • Version

  • Classifier

  • Size and updated date (available in Show Advanced Options)

The search result is grouped by Maven coordinates in the Artifacts (default) tab and by files in the Files tab.

Download an Artifact Manually

You can download an artifact manually from the Maven page's Browse view:

  1. In the navigation menu, click Maven Maven.
  2. If necessary, on the right side of the page, click Browse.
  3. Browse and select the artifact that you want to download.
    You can also click Artifact Search to search for the artifact and then click its name to open it in the Browse view.
  4. With the artifact selected, in Artifact Details, to the left of the artifact's file name, click Download Download.
The browser will download the artifact and save it to your computer.

Copy Distribution Management Snippets

To upload or download dependencies while running a build, add the dependency management snippet or the dependency declaration snippet to the POM file.

Action How To

Copy the Dependency Management snippet

  1. In the Browse view, navigate to the root directory.

  2. In the Artifact Details section, expand Distribution Management.

  3. In the Maven tab, click Copy Copy to clipboard to copy the <distributionManagement> code snippet to the clipboard.

  4. Open the pom.xml file of your project in a code editor (or a text editor) and paste the contents of the clipboard under the <project> element.

Copy the Dependency Declaration snippet

  1. Browse the Maven repository and select the artifact.

    You may also click Artifact Search to search for the artifact and then click its name to open it in the Browse view.

  2. In the Artifact Details section, expand Dependency Declaration.

  3. In the Maven tab, click Copy Copy to clipboard to copy the <dependency> code snippet to the clipboard.

  4. Open the pom.xml file of your project in a code editor (or a text editor) and paste the contents of the clipboard under the <dependencies> element.

Tip:

You can copy the Maven repository’s URL from the distribution snippet. You can also copy the URL from the Project Home page.

On the Project Home page, click the Repositories tab. In the Maven section, from the Clone menu of Project Repository, select HTTP or Webdav, and click Copy Copy to clipboard to copy the URL to clipboard.

Use the HTTP URL to connect to the Maven repository using the HTTP protocol. Use the Webdav URL to connect to the repository using the Webdav protocol.

Maven Repository Administration

You can configure the Maven repository to limit the number of snapshots and overwrite an artifact if another with same groupID, artifactID, and version value is uploaded.

Configure Auto-Cleanup of Snapshots

By default, when you upload a new snapshot of an artifact to the project’s Maven repository manually or through job builds, the repository retains the old versions of the snapshots. You can configure the project to remove the old versions when a new version is uploaded.

the project owner icon You must be assigned the project Owner role to configure the auto-cleanup.
  1. In the navigation menu, click Project Administration Gear.
  2. Click Repositories.
  3. In Maven Repository, if necessary, expand Configure auto cleanup for Snapshot versions.
  4. Select the Purge check box.
  5. In Default Max Snapshots, enter a number between 2 and 500 to specify the maximum versions to retain. By default, 2 versions of the snapshots are retained.

All changes are saved automatically when you navigate to another field. After the rule is enabled, any new upload of a snapshot will remove its older versions if the number of snapshots exceed the value in Default Max Snapshots.

You can also add exceptions to the auto-cleanup and Default Max Snapshots rule and customize the snapshot counts. The project Maven repository retains the snapshot counts of group IDs and artifacts defined in the Customized Snapshot Counts section and uses the default value specified in Default Max Snapshots for artifacts that don’t have exceptions defined.

To define exceptions and customize snapshot count:

  1. In the Maven Repository section of the Repositories page, select the Purge check box and configure the default auto-cleanup as described above.

  2. To add an artifact group or an artifact name as an exception, click + Add in the Customized Snapshot Counts section.

  3. Specify these details:

    • Group Id (Required): Enter or select the Group ID of the artifact. You can select the ID from the list or start typing and then select the ID from the list of suggestions. The auto-suggest list is based on the Maven indexes. If no index data is available, the auto-suggest list doesn’t display.

    • Artifact Id (Optional): Enter or select the Artifact ID of the artifact. You can select the ID from the list or start typing and then select the ID from the list of suggestions. The auto-suggest list is based on the Maven indexes. If no index data is available, the auto-suggest list doesn’t display.

    • Snapshot Count: Select the number of snapshots to retain in the project Maven repository. By default, 2 snapshots are retained.

To remove an exception, on the right, click Remove the Remove icon. For a long list of exceptions, you can use the Filter field and enter a search coordinates criteria to see the exceptions matching the criteria. If you enter an exception with duplicate coordinates, an error message Unable to save. Coordinates already exists. Enter unique coordinates appears.

Configure Overwrite for Artifacts

By default, when a user tries to upload a Maven release artifact with the same groupID, artifactID, and version values of an existing artifact to the project’s Maven repository, the upload fails. If a build tries to upload an artifact with duplicate groupID, artifactID, and version values, it fails too. To allow the duplicate artifact to be uploaded, you can configure the project’s Maven repository to allow the build to upload artifacts with duplicate groupID, artifactID, and version values.

the project owner icon You must be assigned the project Owner role to configure the overwrite property.
  1. In the navigation menu, click Project Administration Gear.
  2. Click Repositories.
  3. In Maven Repository, if necessary, expand Configure Overwrite Property for Release Artifacts.
  4. Select the Allow check box.

Use the Visual Builder Studio Designer

VB Studio includes the Designer, an editing and publishing environment that you use to create web or mobile applications (collectively known as visual applications), or to customize your Oracle Cloud Applications through application extensions. For example, you may want to extend an Oracle Cloud Application so that certain fields are displayed only for managers, while the same fields are hidden from your non-manager users.

What Is a Workspace?

A workspace defines the resources that are available to you when you open the Designer. These resources include the Git repository ̶ and the branch ̶ containing the source files you want to use, the application extension's or visual application's development environment, and, in certain cases for app extensions, a sandbox. You can think of a workspace as your private editing environment while you're working with the Designer. If you’re not using VB Studio to create or update an application extension or a visual application, you won't need a workspace.

There are three ways to access a workspace (and thus, the Designer):

  • From the Project Home page:

    Description of workspaces-list-project-home.png follows
    Description of the illustration workspaces-list-project-home.png

  • From the Designer option in the left navigation area:

    Description of workspaces-list-designer.png follows
    Description of the illustration workspaces-list-designer.png

    In either case, click the workspace name to launch the Designer. (To see all the workspaces in the project while on the Designer page, click the Others toggle button.) Once you’re in the Designer, you can change the Git repository branch, if you wish, but you can’t change the Git repository where your work is stored—that’s set at the project level.

  • From an Oracle Cloud Application editing session:

    Description of fa-edit-page-link.png follows
    Description of the illustration fa-edit-page-link.png

    When you click Edit Pages in Visual Builder while in Oracle Cloud Applications, you are automatically sent over to Visual Builder Studio. If you have a workspace already set up for this app, that’s where you’ll land in the Designer. If you don’t, VB Studio will create a workspace for you.

In some cases, you may want to create a workspace explicitly, rather than allowing VB Studio to create one for you. Create a Workspace explains these options.

You're the only one on your team who can access your workspace. Changes to files you make in your workspace aren't visible to other team members until you save them to a branch (or unless you use the Share action). You can have multiple workspaces, each with a different branch and sandbox, or you can use one workspace and switch to a different branch and sandbox while you’re in the Designer.

See What Is a Workspace and Why Do I Need One? in Extending Oracle Cloud Applications with Visual Builder Studio for additional information about using workspaces with application extensions. See Create Visual Applications in VB Studio for information about using workspaces with visual applications.

Create a Workspace

A workspace may have automatically been created for you when you opened VB Studio from a page. If not, or if you have other requirements, you can create a workspace explicitly.

Note:

The repository and development environment must already be set up and defined in the application extension or visual application project in VB Studio before you can create a workspace. If the development environment isn't defined, you won't be able to create a workspace.

Depending on what you need in your workspace, the type of template you select and the information you’re asked to supply during creation varies considerably. Here are the options for creating a workspace:

  • Clone an existing Git repository that contains an application extension or visual application

    Most people will create a workspace using the Clone from Git option, once a repository with the visual application or application extension that the team works on has been created. One team member will create the Git repository, so you and each member of your team will use the clone option to create at least one workspace so they can do their work. Or, perhaps you want to continue working on a branch that someone else has started. If you work on multiple branches and want to move freely from branch to branch without having to make sure that you added/committed changes you made in a branch, then you'd likely use the clone option to create a new workspace on the same repository.

    See Create a Workspace Using an Existing Repository if you're creating a visual application or Create a Workspace Using an Existing Repository if you're using this workspace for an application extension.

  • Create a new visual application

    See Create Workspace for a New Visual Application for instructions on how to use this option.

  • Create a new application extension

    See Create a Workspace for a New Application Extension for instructions on how to use this option.

  • Import a previously exported archive that contains an application extension or a visual application

    Use this option when you want to base your new visual application or application extension on an existing artifact that you’ve already exported from Visual Builder or Visual Builder Studio.

    See Create Workspace by Importing an App Extension Archive if you're creating an application extension or Create a Workspace by Importing a Visual Application if you're using this workspace for a visual application.

Notes on Importing an Archive to Create a Workspace

You can use the Import from File option in the Create Workspace dialog when you want to base your new visual application or application extension on a valid existing artifact that you’ve already exported from Visual Builder or Visual Builder Studio to your local system. When you import that archive, you create a new application. By using the import and export functionality, you can share application sources and move applications between instances.

When you select an archive to import, or drag it to the upload area in the dialog, VB Studio checks to see if the archive is valid for the operation. In other words, the exported archive must contain a visual application or an application extension.

When you export a visual application with business object data, the archive will include a JSON file (entity.json) and spreadsheet (entity-data.csv) for each custom business object. The JSON file describe the business object and the spreadsheet contains the business object data. If you export the application without data, the archive will only contain the JSON file describing the business objects. Some information, such as credentials for external REST end points, are removed when the archive is created, so you'll need to provide it after importing the archive. For mobile applications, a visual application also stores configuration information necessary to build the Android and iOS mobile applications that you can generate from the project source of a mobile application in your visual application. See Export a Visual Application for instructions on exporting a visual application.

To determine if an application extension archive is valid, VB Studio scans the directories under /sources/ui/ to ensure that these directories are application extension directories, and contain the default directory, extension1. VB Studio also looks for a file called vb-ui-extension.json in the directories under sources/ui/. To determine the base application, VB Studio reads the entries in that JSON file. See Export Your Workspace as an Archive for instructions on exporting an application extension.

See Create Workspace by Importing an App Extension Archive for instructions on using an archive to create a workspace for an application extension or Create a Workspace by Importing a Visual Application if you're using this workspace for a visual application.

What is a Scratch Repository?

When you create a workspace, you have the option to create a scratch repository, rather than using a copy of the project's Git repository. You may want to create a scratch repository instead of a branch when you are experimenting and you're pretty sure you'll never want to merge its contents into an existing repository. A scratch repository is a private repository that only exists in your workspace. No one else can see the repository's contents, and it's deleted when you delete the workspace. It's better to create a branch rather than a scratch repository if you think you might want to eventually merge its contents into the main repository.

If you're using a scratch repository in your workspace and you decide you want to let your team members use it, you can push your scratch repository to a new Git repository.

Allow Others to View Your Scratch Repository

If you chose to use a scratch repository when creating your visual application, other team members in your project cannot work with your visual application.

You can share the content of your scratch repository with your team members by pushing its content to a Git repository that VB Studio will create for you:

  1. Open your visual application.
  2. Click the Git icon in the toolbar and select Push in the menu.
  3. In the Push Content to Git Repository dialog that appears, enter a value in the Repository to Create input field. You can provide an optional description for the Git repository that VB Studio will create for you.
  4. Enter a commit message, and then click Create and Push.Description of vbs-push-scratch.png follows
    Description of the illustration vbs-push-scratch.png

Manage Workspaces

Some workspace management tasks can be performed by an individual, while others must be performed by the project owners.

The Project Home page displays your personal workspaces associated with the selected project:

Description of workspaces-list-project-home.png follows
Description of the illustration workspaces-list-project-home.png

From this page, click a workspace name to open the Designer in the context of that workspace (that is, with the correct Git branch and sandbox, if used.)

Depending on your permissions, you can perform various workspace management tasks using the Designer page:

Description of workspaces-list-designer-action-menu.png follows
Description of the illustration workspaces-list-designer-action-menu.png

Here’s what you can do:

  • Use the Mine|Others toggle to view only your personal workspaces, or all the workspaces associated with this project. If the list is long, you can use the search field to find specific user or workspace names.
  • Delete a workspace.

    As an individual working on application extensions or visual applications, it’s a good idea to delete a workspace once you’ve finished with it (that is, once you’ve used the Publish action to push your changes into the master Git branch).

    Note:

    If there are uncommitted changes to the workspace being deleted, the Confirm Delete dialog will indicate this. The dialog will also indicate if the workspace contains changes that were committed but not pushed.

    If you’re a project owner, you can delete workspaces that are or were associated with projects that you own, even workspaces that you don't own or did not create. Try not to let inactive workspaces accrue in your project, as they still count against your total resource allocation and thus have a (hidden) cost.

  • A project owner and an individual can also rename a workspace, or export it to an archive that can later be imported to another project. See Export a Visual Application for more information.