4 Manage Source Code Files with Git
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 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 chapter 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 What Is the 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 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
To copy the revision name to the clipboard, click Copy |
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 |
For more information, see |
Subversion (SVN) |
For more information, see |
Other version control systems |
See the Git Book at |
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 a Git Repository
As a project owner, you can add multiple Git repositories to a project. VB Studio gives you the option to 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.
You can create a Git repository from these pages:
- The Project Home
page's Repositories tab
- The Git
page, accessed from the left navigator
- The Project Administration
: Repositories page
Before creating a Git repository, especially if it will contain large files and binaries, you should review the best practices section that examines how best to deal with these types of files. See Best Practices for Storing Large Files and Binaries.
Best Practices for Storing Large Files and Binaries
If one or more of your project's repositories contain large files and/or many binaries, it may make sense to use Cloud storage, Maven, or Git LFS instead of versioning these kinds of files with Git.
- You can't use Git to diff binary files.
- Large files grow your repository's history every time they're updated, because Git stores the full size of every version of every binary file. If these binaries are large, they'll quickly become the largest item(s) in the repository.
- As the repository size grows, Git operations, such as cloning, fetching, and pulling will become extremely slow.
- If the binary file is a build artifact, you should store it directly, when the artifact is built, in a Maven repository.
- If the binary file is a binary document that is
saved by an application, such as Microsoft Excel or Word, it
should be stored in either:
- Oracle Cloud storage
- Git LFS, if the binary documents are somehow associated with source files stored in the same Git repository
Git LFS uses pointers, instead of the physical files, when the files or file types are marked as LFS files. When you pull a Git LFS file to your local repository, the file is sent through a filter that replaces the pointer with the file. The physical files are located on the remote server and files that are pulled are located in a cache on your local machine. This means that your local repository will be smaller in size than the remote repository, where all the files and all the differences are still physically stored. See Enable and Use Git LFS to Version Large Files for more information about using Git LFS.
There are a few potential drawbacks you should consider as you decide whether or not to use Git LFS. Here are a few:
- The local Git LFS cache won't be cleaned up automatically.
Just as you have to prune remote branches on a regular basis, you
also have to prune your Git LFS content with the
git lfs prune
command. - You need to make sure that all the developers have Git LFS installed. When someone who doesn't have Git LFS installed commits a file that should be associated with Git LFS, you'll see some strange errors. These problems can be fixed, but it's better to prevent this from happening.
To summarize, the best approach is to store large files and binaries in Cloud storage or Maven whenever possible. If you absolutely need to version these types of files, consider using Git LFS, but recognize that it isn't a panacea. It has its own associated costs, especially for maintenance.
Default Repository Size Limits in VB Studio
By default, VB Studio doesn't limit the maximum number of repositories for a project. However, VB Studio does set default limits for the maximum repository size and the maximum object size for code repositories, as well as for snippets.
- Maximum object size: 50MB
- Maximum repository size: 10GB
See Share and Use Code Snippets to learn about the default size limits for snippets.
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:
- Clone the project's Git repository.
You can find the URL for the remote repository from the Project Home page's Repositories tab. From the Clone drop-down list, click Copy to clipboard
git clone <SSH/HTTPS repository URL>to copy the URL, then paste it to the command line:
You must be connected to the Internet and to the remote repository to check out a branch locally. This is required.
- 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.
- Specify the file(s) to track:
git lfs track *.bin
- Stage the files to be committed:
git add .
git add .gitattributes
- Commit the files to the local repository:
git commit -A -M "Initial commit using LFS"
- Push the commits to the remote repository:
git push origin main
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.
If a connection to the OCI Object Storage bucket can't be made, you'll see an error message that indicates storage hasn't been enabled.
When a Git repository that uses Git LFS is deleted, its binary files on OCI Object Storage will also be deleted.
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.
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.
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:
When you add an external Git repository, VB Studio shows two URLs in the repository's Clone drop-down menu:
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.
Upload Files From Your Computer to the Project’s Git Repository
After using a Git client to clone the project’s Git repository to your computer, adding files, committing the changes to the cloned Git repository, you can then push the commit to the project’s Git repository:
-
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
to copy the HTTPS or the SSH URL:
-
Open the Git client - perhaps the Git CLI.
-
Navigate to the directory where you want to clone the remote Git repository.
If the directory into which you want to clone the repository isn't empty, you'll need to create a new subdirectory and clone the repository into it. You can only perform a cloning operation into an empty directory.
-
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
-
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. -
Copy your application files to the cloned Git repository directory.
-
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 .
-
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"
-
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 main
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:
-
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
to copy the HTTPS or the SSH URL, as shown:
-
Open the Git client - perhaps the Git CLI.
-
Navigate to the local Git repository directory.
-
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 atdeveloper.us.oraclecloud.com/developer1111-usoracle22222_myproject/developer1111-usoracle22222_myproject.git
. -
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 main
-
In your project, open the Git page and check the files in the project’s Git repository.
Access a Git Repository Using Token-Based Authentication
You can use an authentication token generated in VB studio to access a git repository.
Note:
If you have user rights to read and write to Git for all projects you are a member of, you can create a token using the All User Rights option; however, the All User Rights scope token does not have ability to create or delete tokens or modify any other profile preferences settings.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:
- In the
left navigator, click Git
.
- From the Repositories drop-down list, select the Git
repository. From the Revisions
drop-down list, select the branch.
- On the right side of the page, click Files, if necessary.
- 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
. To copy a file's or a directory's path, click Copy to clipboard
.
You can perform these file management tasks from the Git page:
Action | How To |
---|---|
Add a file |
To save the file to a new directory or a directory structure, include the file path
in File Name. The path can
be a relative path or an absolute path. To specify
an absolute path, add a For example:
|
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
To view the file in raw (unformatted)
format in the web browser, click
Edit
|
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
![]() |
Delete a file |
To delete a file, click Actions
![]() ![]() |
Use Git Commands to Manage Files
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:
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. |
|
Add a file that you've added to the repository's directory to the repository's index:
Add all new files to the index:
To add a directory and all its contents to the index, navigate to the directory and use this command:
|
|
Remove a file from the repository:
|
|
Check the status of added and edited files:
|
|
Create a branch:
List all branches in the repository:
Delete a local branch:
If the branch contains commits that haven't been merged into any
other local branches or pushed to a remote repository, Git may not
perform the deletion. This protects you from inadvertently losing
commit data. To force the deletion regardless, use the
To delete a remote branch, you must use the
|
|
Checkout and switch to a branch:
Pass the
|
|
Merge a branch with the checked out branch:
|
git commit |
Commit changes to the local Git repository:
|
git pull |
Incorporate changes from the project's Git repository to the local Git repository:
|
|
Push commits to the project's Git repository:
|
To display the Git help index, use the git help
command. Use the
git help git
command to open the help index in a web browser. To
display help for a particular command, use the git help
<command>
.
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.
Work with Git from the Designer
Several common Git commands can be used directly from the Git menu in the Designer header or from the Options menu in the Git panel:
- Switch Branch/Switch Sandbox
Switch branches and optionally commit your changes to the branch you switch to, or create a new branch from the branch you are currently working in.
- Add file(s)
Select an untracked file and mark it for inclusion (add) in your next commit to the current branch. Once the file has been added, it'll move from the Untracked category to the Changed category. You can select and add multiple untracked files in one operation.
- Save uncommitted files locally
Temporarily stash changes you've made to your working copy when you're mid-way through a code change and aren't quite ready to commit. When you're ready to work on something you previously stashed, you can apply that stash to bring back your saved changes and pick up right where you left off.
You can either apply a stash or pop it to your working branch:- When you apply a stash, its changes are restored and the stash remains in the stash list, so you can apply the same stash to multiple branches.
- When you pop a stash, its changes are restored and it is removed from the stash list.
When you no longer need a stash, you should delete it and keep your stash list clean. However, keep in mind that once you've deleted a stash, you can't recover it.
- Rollback file
Select a changed file and revert modifications made to the file since its last commit to the current branch. This option is available only for files with changes that have been committed to the branch. The option isn't available when your workspace is in an interrupted state, like when conflicts occur during Merge or Pull operations.
- Commit
Group changes that you've made and save them to the local repository. Can be used in tandem with the Push option, where you can commit your changes before pushing them to the remote repository as part of the push operation. You can also deselect any changed files that you do not want to commit or push.
- Status
Display the state of the working directory and the staging area. This option tells you which changes have been staged, which haven’t, and which files aren’t being tracked by Git.
- Diff
Compare two input data sets and output the changes (differences) between them. This option is often used with the Status option to analyze the current state of your Git repository.
- Pull
Download and integrate remote changes. The branch that the data is integrated into is always the currently checked out HEAD branch.
- Push
Publish new local commits on a remote server. The branch that the data is uploaded from is always the currently checked out HEAD branch.
If you're working in a scratch repository, you can push your scratch repository's content to a new remote Git repository that VB Studio can create for you so other team members can work with your visual app.
- Reset to HEAD
Undo changes. Moves the HEAD ref pointer as well as the current branch ref pointer.
- Merge
Integrates changes from another branch. The branch that receives changes is always the currently checked out HEAD branch.
- Rename a Branch
Change your current branch's name, retain its history, and push the renamed branch to the remote repository. The current remote branch won't be renamed or deleted. If the renamed branch is local only, it will be renamed, but won't be automatically pushed to the remote repository.
- Delete a Local Branch
Delete local Git branches you no longer need, after you finish working on a branch and you've pushed your changes to a remote repository. If your local branch has uncommitted changes, you'll lose them after the branch is deleted so, before deleting the local branch, commit any changes you want to keep.
- View Git history
VB Studio keeps track of all the Git actions you perform in your workspace by logging them as action details. You can use the Git History panel to view your Git actions, see the results of each action, and keep track of what you've done in the workspace. Accessing this panel is useful for checking the sequence of recent actions and their details, especially when troubleshooting issues with version control. You can also filter the actions by various criteria (commit message, revision ID, branch name, action type, and so on) to quickly locate events and check details to understand its history.
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 main
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
main
branch that’s automatically created, and then push the branch to
the project's Git repository. Only after the main
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 |
|
Create a branch from the head (tip) of another branch |
|
Create a branch from a tag |
|
Protect a Branch
By default, any project member can rename or delete a repository branch, and push or merge another branch into it. The project owner can protect a branch from these actions by setting restrictions on the branch:
Glob Pattern Reference for Matching Branch Names
Glob syntax can be used to specify pattern-matching behavior. A glob pattern is specified as a string and is matched against a branch name. These wildcard characters can be used in glob patterns:
Wildcard | Description |
---|---|
* | Matches zero or more characters of a name without crossing directory boundaries. |
** | Matches zero or more characters of a name crossing directory boundaries. |
? | Matches exactly one character. |
[] | A bracket expression that matches a single character out
of a set of characters or, when the hyphen character is used, a range of
characters.
For example, [abc] matches "a", "b", or "c". [a-z] specifies a range that matches from "a" to "z", inclusive. Forms can be mixed, so [abce-g] matches "a", "b", "c", "e", "f" or "g". If the character after the left bracket is an exclamation mark (!), it indicates negation, so the expression [!a-c] matches any character except "a", "b", or "c". Within a bracket expression, the *, ? and \ characters match themselves. The (-) character matches itself if it is either the first character within the brackets or the first character after the !, if negating. |
{} | Represents a group of subpatterns. The group matches if any subpattern in the group matches. Uses a comma (",") to separate subpatterns. Groups can't be nested. |
\ | Escapes characters that would otherwise be interpreted
as special characters.
For example, the expression "\\" matches a single backslash and "\{" matches a left brace. |
The forward slash (/) represents the directory separator on all platforms.
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 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.
|
Compare branches |
In the branch list, to the right of branch name, click Actions
|
Protect a branch or set branch restrictions | In the branch list, to the right of branch name, click
Actions
![]() |
Delete a branch |
You can’t delete a restricted branch or the
After you delete a branch, you must update, close, or remove all related merge requests, build jobs, and deployment configurations. |
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
Menu
|
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 On the Project Settings:
Repositories page, mouse over
the Git repository name, click Menu
|
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 Menu
|
Delete a Git repository |
On the Project Settings:
Repositories page, mouse over
the Git repository name, click Menu
|
Copy a Git File/Repository's URL
From the Git page, you can copy and share the URL of a Git repository, a file in the Git repository, or a line in a file in the Git repository.
Before you share the URL, remember that only project members can use the URL to access the file or clone the repository. If the project is shared, organization members can also access files in the project’s repository or clone the repository, but they can’t update them.
These are the copy URL actions you can perform from the Git page:
Action | How To |
---|---|
Copy a Git repository's URL |
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 Project Home page's Repositories tab, the Git page, or from the Project Settings : Repositories page. In the Project Home page's Repositories tab 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
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 Git repository |
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 Git repository |
In the Git page's Files view, 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 for line number |
Copy the URL of a group of lines in a file in the Git repository |
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 Example: With the |
View File/Repository History
Use the Git page's Logs view to see the history of commits, branches, and merges of a file or Git repository and its revisions.
-
From the Repositories drop-down list, select the Git repository. From the Revisions
menu, select the branch.
-
To view the commit history of a file, browse to and open the file.
Skip this step to view the commit history of the selected Git repository.
-
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
To view the history of another branch or tag, in the text box to the right of the
History
|
View the commit history as a graph |
In the Logs view, click the History
Graph
In the graph:
|
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 tags:
Action | How To |
---|---|
Create a tag |
|
Rename a tag |
|
Compare a tag |
In the tags list of the Tags
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
|
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. The revision could be a branch, a tag, or a commit SHA-1 checksum hash.
Here's how to compare two revisions of a Git repository:
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
.
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 Revisions |
Switch the base revision and the compare revision |
Click 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
|
Add Comments to a File
When you're comparing files, you can add inline comments, which will be visible to all project users, to the source code changes made to a file:

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 Git page's Refs view.
Here's how to subscribe to email notifications and get them when updates happen in branches you are watching:
Action | How To |
---|---|
Enable email notifications |
In your user preferences page, select the SCM/Push Activities check box. |
Watch a branch |
A Subscribed
To unsubscribe, click cc again. |
Search a Git Repository
You can search the project’s Git repositories for a file name, directory name, or a term in the source code files, file paths, and file revisions.
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
Here's how to search for a term in Git repositories:
Action | How To |
---|---|
Search for a term in a Git repository and a revision |
|
Search for a term in all revisions of a Git repository |
|
Search for a term in all Git repositories |
|
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
.
Download a Git Repository's Archive
If a Git repository's branch or tag isn’t required, and if you plan to delete it, it’s considered good practice to create and back up an archive of the branch or tag before you delete it. From the Refs view of the Git 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 |
|
Download a tag's archive |
|
Review Source Code with Merge Requests
Reviewing source code can help you avoid bugs, identify design issues, and catch design and implementation problems that might affect application performance. To get the source code reviewed, you need to create a merge request.
Merge Requests Concepts and Terms
As the name suggests, a merge request is a request to merge a branch into another. Before merging the branch, you may want your team members to review updates made to the branch and share their feedback. A merge request combines the review and merge processes into one easy collaborative process.
You can also link related issues and builds to the merge request that are automatically updated or triggered when you merge branches.
Here are the terms that this documentation uses to describe the merge request features and components:
Term | Description |
---|---|
Review branch |
Branch to be reviewed and merged. |
Target branch |
Branch that the review branch will merge into. |
Reviewer |
Project user invited to review the changed files of the review branch. |
Requester |
Project user who created the merge request. |
Subscriber |
Project user who isn’t a reviewer, but is watching the merge request. |
Default reviewer |
Project user who’s automatically added as a reviewer if a branch is selected as the review branch. Only a project owner can create default reviewers of a branch. |
Approved |
Reviewer's feedback with no objection to the changes made to the source code in the review branch. |
Rejected |
Reviewer's feedback with objections to changes made to the source code in the review branch and a recommendation not to merge the review branch into the target branch. |
General comment |
A comment in the Conversations tab of the merge request. |
Inline comment |
A comment added to a line of a file under review. |
Pending (or unpublished) comment |
An inline comment that you didn’t publish when you added it. |
To understand the workflow of a merge request, let's consider you're a software developer assigned a new feature to implement. These steps summarize the action you’d perform to set up a merge request and merge branches:
-
Create a branch from a stable branch (say
main
) of the source code Git repository. You'd add or update the files of the new branch to implement the new feature.You can do this in the cloned Git repository on your computer or on the VB Studio Git page.
-
On your computer, pull the latest content from the project’s Git repository, checkout the new branch, update the required files, and commit and push the checked out branch to the project’s Git repository.
-
If required, create a build job to generate artifacts from the new branch to verify the stability of the application.
-
Create a merge request with the new branch as the review branch and the stable branch as the target branch.
-
Add your manager and other team members as reviewers.
-
To resolve the feature related issues when you close the merge request, link the issues to the merge request.
-
Depending on the review feedback, you may need to update some files and check the stability of the branch. To trigger a build of the job automatically when you update the files of the review branch, link the job to the merge request.
-
Again, based on the feedback and build status of the linked jobs, you may want to merge the branch with the stable branch or abandon it. If you merge the branches, the linked issues are automatically resolved.
If you're invited to a merge request, you can add comments to the updated files, and share your feedback whether you’ve any objection to merge branches:
-
Open the merge request.
-
Check the commits made to the review branch and compare the changed files.
-
Add general or inline comments, if necessary.
-
Submit your feedback as Approved if you find the code updates acceptable, or Rejected if you have objections.
If you're a project member but aren’t invited to a merge request, you can add comments but you can't share your feedback.
It isn’t necessary to add reviewers to a merge request. If you're sure that the changes made to the review branch don’t require a review, you can merge both branches without a review. If you're comfortable using Git, you can merge branches from a Git client without creating a merge request.
Merge Request States
A merge request can be in one of these states:
State | Description |
---|---|
Open |
Code review is in progress. A merge request’s status remains Open until the branches are merged or the request is closed. |
Merged |
Code review is complete and the review branch has been merged with the target branch. The review is closed for inline comments, but can accept general comments. |
Closed |
Code review is closed without merging the review branch with the target branch. The review is closed for inline comments, but can accept general comments. |
Create and Manage a Merge Request
After you create a merge request, you add reviewers and link related issues and jobs to it.
Create a Merge Request
You must be a project member to create a merge request from the Merge Request page. You can't create a merge request if the branch that you want to be reviewed has any merge restrictions set or is already under review in another merge request.
Here's how to create a merge request:
After the merge request has been created, you're assigned the Requester role and all reviewers are assigned the Reviewer role. Email notifications are sent to reviewers informing them that they've been added as reviewers.
Create a Merge Request from the Command Line
If you use Git commands to manage source files from your computer, you can create merge requests from the command line when you're publishing changes to a project's repository. You can also add reviewers to merge requests made from the command line.
Use git push
options to create a merge request that
publishes changes from your local branch to a remote branch:
git push -o mr.target=
<target-branch>
origin
<feature-branch>
<target-branch>
is the branch where your changes will be merged.<feature-branch>
is the branch to be reviewed. If thefeature-branch
you specify is already under review, the merge request won't be created.
For example, this command creates a merge request for the branch
myfeature
before merging to main:
git push -o mr.target=main origin myfeature
Note:
The Git push-o
option is available only with Git version 2.10 or higher. With these versions, you can use
the --push-options
option or the shorter -o
option.
If you want to add reviewers to the merge request, include the mr.add.reviewer
option or use the mr.add.defaultReviewers
option if you've set default reviewers for the target
branch. For example, this command:
git push -o mr.target=main -o mr.add.reviewer=clara.coder -o
mr.add.reviewer=tina.testsuite origin myfeature
identifies two reviewers by their user names (clara.coder
and tina.testsuite
). Both users will be added as reviewers to the merge request for the myfeature
branch.
Tip:
If you frequently create merge requests, it's helpful to add an alias for the create merge request option to the.git/config
file at the local level for each repository (refer to
Git documentation for details). For
example:cat .git/config
[alias]
review = push -o mr.target=main
Now, you can use the review
alias to create a merge
request for the myfeature
branch and add clara.coder
as the reviewer:
git review -o
mr.add.reviewer=clara.coder origin myfeature
Note:
You cannot use the options to create merge request and add reviewers with thegit push --all
command or for references other than the HEAD branch.
After your changes have been successfully pushed and the merge request has been created, click the See merge request link included in the command output to view the merge request that was created for you in VB Studio, for example:
user123@rmt123 /tmp/code2cloud.example (myfeature) $ git push
-o mr.target=main origin myfeature
Enumerating objects: ...
...
remote: [Push Options] See merge request: http://192.0.2.1:8888/test/?_h=projects/test_example/review/39
Add or Remove Reviewers
You can add reviewers when you create a merge request or while the review is open. You must be the requester or a reviewer to add or remove reviewers.
Here's how to add reviewers to or remove reviewers from a merge request:
- In the
left navigator, click Merge Requests
.
- Click the merge request summary to open it.
You can manage the reviewers from the Review Status section available on the right side of the page.
Action | How To |
---|---|
Add a reviewer |
|
Add a group |
|
Add yourself (project member) as a reviewer |
If you're a project member but not a reviewer, you can submit a request to add yourself as a reviewer to a merge request. Above the Review Status section, click Add
me
|
Add yourself (not a member of the project) as a reviewer |
Non-members can search and view MRs in shared projects. If you're not a member of a shared project, you can still submit a request to add yourself as a reviewer to a merge request:
A reviewer can approve your request to join the merge request as a reviewer. After becoming a reviewer, you can approve or reject the review and add comments to the merge request. Note: You won't be able to create/merge/close MRs; add/remove reviewers, linked issues, or linked builds; or start linked builds. Because you aren't a project member, you won't be able to do what a project member can. |
Approve a reviewer request |
If you’re the requester or a reviewer, you can approve requests of project users to
join the merge request as reviewers. In the Conversation tab,
click Add User
|
Remove a reviewer or a group |
|
Link an Issue to a Merge Request
Linking issues to a merge request enables you to resolve them automatically when you merge or close a merge request:
Link a Build Job to a Merge Request
Linking build jobs to a merge request enables you to monitor them from the merge request and trigger them when a commit is pushed to the review branch. Depending on the build’s status, reviewers can determine whether the merge request is ready to be merged with the target branch.
After a job is linked to a merge request, a build automatically runs when the review branch is updated with a commit.
When a build of a linked job runs, a comment is automatically added to the Conversation tab. If the build succeeds, it will auto-approve the merge request and add itself to the Approve section of the Review Status list. If the build fails, it will auto-reject the merge request and add itself to the Reject section of the Review Status list.
Watch a Merge Request
You can set up a watch on a merge request and get email notifications when a reviewer adds a comment, a user updates files of the review branch, or a reviewer shares a feedback.
Here's how to subscribe to email notifications for merge request updates when you are a reviewer and when you are not:
Action | How To |
---|---|
Merge requests where you’re a reviewer |
By default, you get email notifications of merge requests where you’re a reviewer. If you aren’t getting the email notifications, select the Merge Request updates and comments check box in your user preferences page.
|
Merge requests where you’re not a reviewer |
To stop watching, remove your name from the Watchers list. |
Merge Request Email Notifications
As the reviewer, the requester, or the subscriber (watcher) you receive email notifications when the merge request is created or updated. A notification of the event also appears in the Recent Activity feed on the Project Home page.
Some events that send notifications are:
-
Merge request is created
-
Additional source code changes are committed to the review branch and pushed to the upstream
-
A general comment is added
-
An inline comment is published
-
Reviewers are added or removed
-
Merge request is approved or rejected
-
Merge request is closed or merged
Batch emails are sent when:
-
A user submits multiple inline comments
-
A user submits several private inline comments and publishes them later
-
A user submits several general comments in a short duration
-
Multiple users carry on multiple conversations at the same time in different inline comments
-
Multiple users carry on multiple conversations in general comments
Batch emails are also sent for review events that occurred before the inactivity period, which is usually five minutes after users stop entering comments. Review activities, other than comments related activities, don’t send email notifications in the inactivity period. A batch email is sent after the inactivity period listing all review activities that happened prior to the period of inactivity expires.
Review a Merge Request
To review a merge request, on the Merge Request page, click its summary. On the Review page, you can view the commits of the review branch, review changed files, add inline and general comments, and submit your feedback.
Open a Merge Request
To open a merge request, on the Merge Requests page, click its name.
Use the filter tabs to search for the merge request. By default Related To Me, Waiting for Approval, Created By Me, Open, and Merged filters are available. More filters are available in the More drop-down list.
If you’re invited to a merge request, you can also click the request ID from the email notification.
If you still can’t find the merge request through the available filters, use the
search box at the top of the page or click New Search
to run an advanced search.
You can also save the advanced search for future use. In Search Name, enter a name and click Save. The saved searches are listed in the More drop-down list.
View Commits and Changed Files
You can view commits and changed files from the Commits and the Changed Files tabs.
The Commits tab shows all commits made to the review branch. Here are several common actions you can perform from the Commits tab:
Action | How To |
---|---|
Compare the files of one commit with another |
Click the button with the first seven characters of the commit’s SHA-1 checksum hash. By default, the page compares the commit with the previous commit. |
View all files of the repository when the commit was pushed to the branch |
Click Code. |
View files that were updated in the commit |
Click Show Details. To compare a file with its parent commit, click the file name to compare the file changes with its previous commit. |
The Changed Files tab shows the files in the compare mode. Here are some common actions you can perform from the Changed Files tab:
Action | How To |
---|---|
Select the Changed Files tab to open the tree view and show changed files |
Click Changed Files Tree
|
View the compare options |
Click Diff Preferences
|
Add a comment to a code line or reply to one |
Mouse over the line number of the file and click Add
Comment |
Tips for Working with Merge Requests that Have Large Numbers of Changed Files
- On the upper left side of the Merge Request window, above the
tree view, VB Studio prominently displays the number of changed files shown
in the tree and, if the number is very large, the number of files that
aren't shown in the tree.
Description of the illustration mr_open_files.pngThe maximum number of files that can be displayed is 4,000.
- You can use the directional arrows to traverse the tree. Use the
or
left arrows to ascend the tree and the right arrows
or
to descend it.
Description of the illustration mr_filter_options.png - You can enter a search term (perhaps a file type, such as .css or .js) in the Filter field, to limit your view to a particular file type.
- You can use the quick filter buttons on the upper right side of
the screen to focus in on the files that you want to examine. At the touch
of a button, you can:
- Show modified files
- Show new files
- Show removed files
- Show renamed files
- Show modified files
- From the Settings
menu, you can select a single option or multiple ones that adjust what you see in the tree.
Description of the illustration mr_gear_menu_options.pngYou can also expand all or collapse all files in the tree with one click.
You'll have access to many similar options in the Conversations tab, so you can see the history of commits, comments, approvals and rejections and focus in on the items that you're interested in examining when the merge request is a large one.
Add a General Comment
In the Conversation tab, you can view the ongoing conversation and add comments. The comment could be a generic comment, a question you want to ask reviewers, or a comment about an event such as a commit.
Here's how to add a comment to an ongoing conversation:
Add an Inline Comment to a File
When a code review is in progress, you can add inline comments directly to a file’s code lines. You can’t, however, add an inline comment after a merge request has been merged or closed.
Here's how to add inline comments directly to the source code being reviewed:
To view your pending or unpublished comments, click the Pending Comments tab.
To reply to a published comment, click Reply
, enter your comment, and click Comment. Replies
published comments will be published immediately but they can’t be edited or
deleted.
Manage Unpublished Comments
The Pending Comments tab displays all pending comments with the code where these comments were added. The comments appear inline in the code.
Here are several things you can do with unpublished comments:
-
To edit a comment, click Edit
.
-
To publish a pending comment, click Publish to the right side of the comment header.
-
To publish all pending comments, click Publish All.
-
To discard all pending comments, click Discard All.
-
To delete a comment, click Delete
.
Approve or Reject a Merge Request
As a reviewer, after you review the source code, you can add a special comment that indicates whether you approve the code changes or reject them. Approving a merge request implies that you don’t have any objections to changes made to the source code. Similarly, rejecting a merge request implies that you’ve an objection and don’t recommend merging branches.
Note that if you created the merge request, but didn’t add yourself as a reviewer, you can’t approve or reject the merge request. However, you can still close it or merge it with the target branch.
Here's how to approve or reject a merge request:
Merge Branches and Close the Merge Request
After addressing reviewers’ comments, you can decide whether to merge the branches or cancel the request.
Before doing that, go to the Review Status section and check the review status for the reviewers and the status for linked build jobs. Depending on the number of Approves, Rejects, and No Response, you can decide whether you want to merge the review branch, wait for more approvals, or cancel the request.
Merge Branches
There are several different ways to merge a review branch into the target branch. You can merge commits, squash and merge, rebase and merge, or merge the branches manually. You don’t need to get approvals from all reviewers before merging the review branch. If the target branch is locked, you won’t be able to merge the review branch without first contacting the project owner to unlock the target branch.
Note:
In a merge request, when you merge a review branch with the target branch, you
merge all of the commits in the review branch. If you want to merge a particular
commit or just some commits in the review branch, you should use the git
cherry-pick
command on the Git command line to apply the commit
changes to the target branch. For more information, see https://git-scm.com/docs/git-cherry-pick.
To merge branches, you must be assigned either the reviewer or requester role for the merge request:
Resolve a Merge Conflict
Git can automatically resolve code conflicts when the review branch is merged with the target branch. In some cases, however, the conflicts must be resolved manually.
On the Merge Request page, if the Merge button is replaced by the Merge Conflicts button, it indicates a merge conflict.
Git automatically resolves conflicts if different files of the target and review branches are updated before both branches are merged. Merge conflicts are reported when the same lines of the same files are updated in the review branch and the target branch before both branches are merged. Most people will use the browser-based conflict resolution tool:
If there are too many files with conflicts or if the files with conflicts are too large, you need to manually review each conflicting file in the review branch with the code of the same file in the target branch in a text editor and resolve the conflicting lines of code. Then, you need to follow the Git commands displayed in the dialog to resolve the conflicts with the Git command line:
-
On your computer, open the Git CLI.
-
If you’ve already cloned the project Git repository, navigate to its directory.
If you haven’t cloned the Git repository, clone it.
-
Run the commands shown on the Merge Conflicts dialog.
The commands help you resolve the conflict and mark the conflicting code lines in files.
-
Open each file that contains conflicts in a text editor.
Content with conflicts is marked with
<<<<<<<
,=======
, and>>>>>>>
. The lines between<<<<<<<
and=======
show the code from the target branch. The lines between=======
and>>>>>>>
show the code from the review branch. -
Review the content and update it. Remember to remove the
<<<<<<<
,=======
, and>>>>>>>
from each conflicting file before saving it. -
Save all files and commit them.
Run the
git status
command to view the status of conflicting files. -
Push the commit to the target branch.
Conflicting files in the review branch are now merged with the target branch. No additional action is required on the Merge Request page.
Close a Merge Request
You must close a merge request after the review branch has been merged. To close a merge request, it isn’t necessary to merge the review branch to the target branch. You can close a merge request if it was created by mistake or if you don’t want to merge the review branch to the target branch.
Make sure that you perform any needed merge action before you close the request. Once a merge request is closed, you can’t merge the review branch, add comments, or review the source code:
Merge Request and Branch Administration
A project owner can assign default reviewers to a branch, or set push and merge restrictions on it. A branch owner can also change a Private branch's restrictions. As a project owner, you can set some restrictions on a Git repository branch you can and assign some project users as default reviewers of the branch.
For a branch, you can set rename, delete, push, and merge restrictions. You can also lock a branch if you don’t want anyone to push commits to it or merge another branch with it. When a merge request is created with the branch as the target branch, the default reviewers of the branch are automatically added to the Reviewers list.
Set Review and Merge Restrictions on a Repository Branch
You must be a project owner to configure a branch so that it allows another branch to merge into it only through a merge request after the merge request reaches the required number of approvals.
The number of approvals ensures that specified reviewers of the merge request have reviewed the changes of the review branch. You can't merge a branch outside VB Studio, such as using a Git client, without meeting the number of approvals requirement of the merge request. You can set other review restrictions on a branch, such as whether the last build of the branch must be successful to merge it.
To set review restrictions on a branch:
When you select the Requires Review option for branch, you can merge a branch after the branch's approvals requirement is met.
These are the review restrictions you can set from the Branches page:
Action | How To |
---|---|
Assign default reviewers to a branch |
A default reviewer is a project member who is automatically added as a reviewer when a merge request is created on a branch. To specify default reviewers of the selected branch, click Default Reviewers and select the member or the group. |
Set the minimum number of approvals before a branch can be merged to the selected branch |
From the Approvals drop-down list, select the minimum number of reviewers who must approve the review branch of a merge request, where the selected branch is the target branch. |
Allow a review branch to be merged to the selected branch only if the last build of the linked job in Merge Request is successful | Select the Require successful build check box. |
If a change is pushed to a branch after some reviewers have approved the merge request, merge only when they reapprove the merge request | Select the Reapproval needed when branch is updated check box. |
Ensure changes pushed to the target branch match the contents of the review branch | Select the Changes pushed to target branch must match review content check box |
Specify users or groups who can bypass the branch restrictions and merge the review branch of a merge request outside VB Studio or without required approvals |
In Merge Request Exempt Users, specify the users or groups. This is useful if you want to allow some users or groups to merge the review branch irrespective of review conditions being met. |