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. Description of the illustration devcs_code_gitrepositories.png
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). Description of the illustration devcs_code_revisions.png 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 , at the bottom of the menu. To copy the revision name to the clipboard, click Copy . 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 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.

Here are a few reasons why you shouldn't store binary files in a Git repository:

• 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.

In general, the way you store binaries should be based on the type and use of the binary file:

• 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.

Here are the default limits set for code repositories:

• 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:

1. 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 to copy the URL, then paste it to the command line:

   git clone <SSH/HTTPS repository URL>

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

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 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.

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.

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 left navigator, click Project Administration .
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 in 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:

Description of the illustration vbs_code_clone_external.png

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:

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 to copy the HTTPS or the SSH URL:

   
   Description of the illustration vbs_code_clone.png

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

3. 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.

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://[e-mail]/developer1111-usoracle22222/s/developer1111-usoracle22222_myproject/scm/developer1111-usoracle22222_myproject.git

   Here's an example that uses SSH:

   git clone ssh://[e-mail]/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 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:

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 to copy the HTTPS or the SSH URL, as shown:

   
   Description of the illustration vbs_code_clone.png

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://[e-mail]/developer1111-usoracle22222/s/developer1111-usoracle22222_myproject/scm/developer1111-usoracle22222_myproject.git

   Here's an example that uses SSH:

   git remote add origin ssh://[e-mail]/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 main

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 to copy the SSH URL:

   
   Description of the illustration vbs_code_clone.png
3. Open the Git client - perhaps the Git CLI.
4. 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.

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://[e-mail]/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://[e-mail]/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 main

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.

1. From your VB Studio preferences, generate an authentication token for your project with both Read and Write Git permissions. See Set Up Token-Based Authentication.
2. Open the Git client.
3. 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.
4. Using the Git client, clone the project’s Git repository.

   For example, if you’re using the Git CLI, use the

   git -c http.extraHeader="Authorization: Bearer <token>" clone <gitURL>

   command:

   git -c http.extraHeader="Authorization: Bearer wKAr5xaIVh0DAhJ302UwpuoROphc2HgrQnbSHrcV2go" clone https://[e-mail]/developer1111-usoracle22222/s/developer1111-usoracle22222_myproject/scm/developer1111-usoracle22222_myproject.git

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

   git -c http.extraHeader="Authorization: Bearer wKAr5xaIVh0DAhJ302UwpuoROphc2HgrQnbSHrcV2go" push origin main

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 left navigator, click Git .
2. From the Repositories drop-down list, select the Git repository. From the 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 . 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	Click + File. In File Name, enter the file's name and extension. In the code editor, add or enter the file contents. Click Commit. In the Commit Changes dialog, enter a commit summary in the first text box, any details in the Details text box, and then click Commit. 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 / in the beginning. For 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 or Left Scroll to scroll one character at a time. To view the file in raw (unformatted) format in the web browser, click Edit , 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 . 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 next to Edit , 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

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://[e-mail]/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 Add all new files to the index: git add --all To add a directory and all its contents to the index, navigate to the directory and use this command: 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 List all branches in the repository: git branch Delete a local branch: git branch -d 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 -D option instead. To delete a remote branch, you must use the git push command: git push origin --delete remote_branch
git checkout	Checkout and switch to a branch: git checkout new_branch Pass the -b option in to the git checkout command to create a branch and switch to it immediately: git checkout -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 pull	Incorporate changes from the project's Git repository to the local Git repository: git pull origin main
git push	Push commits to the project's Git repository: git push -u origin main

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	In the Git page's Refs view, click Branches . From the Repositories drop-down list, select the repository. Click + Create Branch. In the New Branch dialog box, in Name, enter the branch name. From the Base drop-down list, select the base revision name. To mark the branch as a private branch, select the Private Branch check box. Click Create.
Create a branch from the head (tip) of another branch	In the Git page's Refs view, click Branches . From the Repositories drop-down list, select the repository. Click + New Branch. In the branch list, next to the source branch name, click Actions , and select Branch. In the New Branch dialog box, enter a name for the new branch. To mark the branch as a private branch, select the Private Branch check box. Click Create.
Create a branch from a tag	In the Git page's Refs view, , click Tags . From the Repositories drop-down list, select the repository. Click + New Branch. In the tags list, next to the tag name, click Actions and select Branch. In the New Branch dialog box, enter a name for the new branch. To mark the branch as a private branch, select the Private Branch check box. 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. The project owner can protect a branch from these actions by setting restrictions on the branch:

1. In the left navigator, click Project Administration .
2. Select the Branch Protection tile.
3. Click in the search repository field and select the Git repository that has the branch you want to protect.
   All rules protecting the branches in that repository are displayed. To filter the list, type a full or partial rule name. Select a rule to display its details in the right-hand pane.
4. Select the Branch name radio button, click in the search field below it, and select the branch.

   If no rules have been associated with the branch, proceed to the next step.

   If there any rules already associated with the branch, those will be displayed. If you select a rule, its details will be displayed in the right-hand pane.

5. Click +Rule to create a new rule for the repository and associate it with a branch or multiple branches that match a defined pattern.
   The New Protection dialog is displayed.
   1. Click in the search repositories field and select the repository that you want to define the rule for.
   2. Click in the Provide glob pattern or select branch field.
      Select one of the displayed branches to associate the new rule with a specific branch or add an expression using wildcards to associate the rule with branches that match the glob pattern you provide. See Glob Pattern Reference for Matching Branch Names.
   3. Set the protection level (Open, Requires Review, Private, Frozen) and corresponding options.

      Here are the branch protection actions you can define:

      Action	How To
      Require 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, as shown: Description of the illustration branch_protection.png To define branch owners, click Owners and select the user(s) and/or group(s). You can select multiple users (or groups). To push commits to a private branch from your computer, you must always use SSH. In addition, to run a build of job that uses a private branch, you must 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 renaming and deleting 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.

      Tip:

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

The Activities stream on the Project Home page will report that the branch protection settings were modified.

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 main 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. In the branch list, to the right of branch name, click Actions , and select Rename. In the Rename Branch dialog box, in Name, enter the new branch name. Select the I want to rename the branch check box and click Rename.
Compare branches	In the branch list, to the right of branch name, click Actions , and select Compare. By default, the branch is compared with the main branch.
Protect a branch or set branch restrictions	In the branch list, to the right of branch name, click Actions , and select Protection Settings. See Protect a Branch.
Delete a branch	You can’t delete a restricted branch or the main branch. In the branch list, to the right of branch name, click Actions , and select Delete. In the Delete Branch dialog box, select the I want to delete the branch check box, and then select Delete. 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 , 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 main 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 Menu , 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 Menu , and select Index .
Delete a Git repository	On the Project Settings: Repositories page, mouse over the Git repository name, click Menu , and select Delete . In the Remove Repository dialog box, click Yes.

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 (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 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 2 in 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=main&sl=2. You can copy and use this URL to open myfile.txt in the demo.git repository – main branch with line number 2 selected.
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 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=main&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 – main branch opens with line numbers 2 through 5 selected.

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.

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

2. 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.

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 toggle button. To view the history of another branch or tag, in the text box to the right of the History 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 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 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	In the Refs view of the Git page, click Tags . From the Repositories drop-down list, select the repository. Click + New Tag. In the New Tag dialog box, in Name, enter the tag name. In Base, enter the base revision name. Click Create.
Rename a tag	In the tags list of the Tags view, to the right of the tag name, click and select Rename. 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 view, to the right of the tag name, click 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 view, to the right of the tag name, click 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. 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:

1. On the right side of the Git page, click Compare.
2. From the 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 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 .

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 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 .
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 to view various compare options.

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:

1. Browse to 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
   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 , 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 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	Open the project. In the left navigator, click Git . On the right side of the page, click Refs. If necessary, click Branches . In the branch list, to the right of the branch name, click cc. Alternatively, click Actions , and select Subscribe. A Subscribed icon appears indicating that you are subscribed to email notifications of the branch updates. 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	From the Repositories drop-down list, select the Git repository. From the Revisions drop-down list, select the revision. In the top-right corner of the page, in the Search Code box, enter the search term or select it from the suggestion list. Click Search .
Search for a term in all revisions of a Git repository	From the Repositories drop-down list, select the Git repository. From the Revisions drop-down list, select the revision. In the top-right corner of the page, in the Search Code box, enter the search term or select it from the suggestion list. Click Search . In the Revisions drop-down list, click Reset . The Revisions drop-down list now shows All Revisions.
Search for a term in all Git repositories	From the Repositories drop-down list, select the Git repository. From the Revisions drop-down list, select the revision. In the top-right corner of the page, in the Search Code box, enter the search term or select it from the suggestion list. Click Search . From the Repositories drop-down list, select the All Repositories option, or click Reset .

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	In the Git page's Refs view, click Branches . From the Repositories drop-down list, select the repository. In the branches list, to the right of the branch name, click , select Download, and then select zip or tgz.
Download a tag's archive	In the Git page's Refs view, click Tags . From the Repositories drop-down list, select the repository. In the tags list, to the right of the tag name, click , select Download, and then select zip or tgz.

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:

1. 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.

2. 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.

3. If required, create a build job to generate artifacts from the new branch to verify the stability of the application.

4. Create a merge request with the new branch as the review branch and the stable branch as the target branch.

5. Add your manager and other team members as reviewers.

6. To resolve the feature related issues when you close the merge request, link the issues to the merge request.

7. 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.

8. 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:

1. Open the merge request.

2. Check the commits made to the review branch and compare the changed files.

3. Add general or inline comments, if necessary.

4. 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:

1. In the left navigator, click Merge Requests .
2. Click + Create Merge Request.
3. On the Branch page of the New Merge Request wizard, in Repository, specify the Git repository.
4. In Target Branch, select the branch that the review branch will be merged into.
5. In Review Branch, select or enter the name of the branch to be reviewed. If the branch doesn’t exist, it’ll be created.
   If the review branch is already under review in another merge request, the branch name won’t appear in the Review Branch list.
6. Click Next.
7. On the Details page of the New Merge Request wizard, in Linked Issues, add issues related to the merge request.
   When you're merging branches or closing the merge request, you can mark the linked issues as resolved.
8. In Linked Builds, add jobs related to the merge request.
   Builds of the linked jobs will be run automatically whenever the review branch is updated.
9. In Tags, add project tags to associate them with the merge request.
   You can use these tags to search merge requests.
10. In Summary, enter a summary (or title) of the merge request. If one isn't specified, the default summary Merge Request for branch <review_branch_name> will be set.
11. In Reviewers, select team members and groups who’ll review the updates.

    
    Description of the illustration vbs_select_reviewers.png

    If the branch is protected, at least one default reviewer must approve the merge request. Here's what you can select:

    • To add all reviewers of the last merge request you created, select Last Used .

    • To add all the default reviewers for the protected branch, select Default Reviewers .

    • To add default reviewers individually, select each one from the list displayed. Default reviewers are identified by the Default Reviewer tag next to their name. Reviewers that aren't default reviewers can also be selected from the list and can be added individually.

    • To add a group of team members, select a group that has been previously defined by your organization administrator, such as the QA group in the image. This can be quite a timesaver, especially if the group you're adding has many members.

    To remove a selection, click the X icon to the right of the selection.

12. Click Next.
13. On the the New Merge Request wizard's Description page, enter a description, and click + Create.
    You can use the project’s wiki markup to format the description.

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>

where:

• <target-branch> is the branch where your changes will be merged.
• <feature-branch> is the branch to be reviewed. If the feature-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 the git 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:

1. In the left navigator, click Merge Requests .
2. 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	Above the Review Status section, click Click to add a reviewer. From the Reviewers drop-down list, enter the project member name or select the member. Click OK.
Add a group	Above the Review Status section, click Click to add a reviewer. From the Reviewers drop-down list, enter the group's name or select it from the dropdown list. Click OK.
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 . If you’re a project owner, you'll be added automatically to the merge request. If you’re a project member, enter a justification for why you want to be added in the Request to be added as a reviewer dialog box, and click OK.
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: Above the Review Status section, click Add me . Enter a justification for why you want to be added in the Request to be added as a reviewer dialog box. Click OK. 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 in the requested to be a reviewer request.
Remove a reviewer or a group	Above the Review Status section, click Click to add a reviewer. Click Remove Reviewer next to the reviewer or group you want to remove. Click OK.

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:

1. Open the merge request.
2. Click the Linked Issues tab.
   The tab displays issues linked to the merge request.
3. To link an issue to the merge request, enter the issue summary text or the issue ID in the Search and Link Issues search box, select the issue from the drop-down list, and click Save .

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.

1. Configure the job to accept merge request parameters.
   See Use Build Parameters.
2. Open the merge request.
3. Click the Linked Builds tab.
   The tab displays linked jobs, if any.
4. In Search and Link Build Jobs, enter the job name and select it from the list.
5. Click Save .

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. In the branding bar, click the user avatar, and select Preferences. Click the Notifications tab. Select the Merge Request updates and comments check box, if not selected. To the left of the User Preferences title, click Close to return to the last opened page.
Merge requests where you’re not a reviewer	Open the merge request. Click CC me. 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.

Description of the illustration devcs_mergerequests.png

If you’re invited to a merge request, you can also click the request ID from the email notification.

Description of the illustration devcs_mergerequest_email.png

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

If you're working with merge requests that have a large number of changed files, you have several ways to narrow your view and focus in on just the files or commits that you are interested in examining:

• 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.png

  The 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
• 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.png

  You 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:

1. Open the merge request.
2. In the Write tab of the Conversation tab, enter your comment.
   You can use the project’s wiki markup to format the comment. Click the Preview tab to preview the format.
3. Click Submit.

The comment adds in the Conversation tab along with icons to reply, edit, and delete your comment. Note that you can’t edit or delete comments entered by other users.

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:

1. Open the merge request.
2. Click the Changed Files tab.
3. Mouse-over the line number of the file where you want to add your comment and click Add Comment.
   
   Description of the illustration odcs_addreviewcomment.png
4. Add your comment in the comment box.

   • Use the project’s wiki markup language to format the comment.

   • Click Comment to publish it and make it visible to all reviewers.

     You can’t edit or delete a published comment.

   • Click Save to save the comment and publish it later. The comment isn’t published and isn’t visible to reviewers.

   • Click Cancel to cancel the comment.

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:

1. Open the merge request.
2. Click the Approve or Reject button at the right side of the page.
3. In the dialog box that appears, add your comment, and click OK.
   Use the project’s wiki markup to format the comment.

You can see your feedback (approval or rejection) in the Reviewers list.

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:

1. Open the merge request.
2. On the right side of the page, click Merge.
3. In the Merge dialog box, click Merge Options, and select the merge type:

   Use this merge type ...	To:
   Create a merge commit	Merge all the review branch's commits to the target branch. The merge commits continue to show two parents.
   Squash and Merge	Add the review branch's commit history to the target branch as a single commit.
   Rebase and Merge	Reapply the review branch's commits and add them to the top of the target branch.
   Manual Merge	Follow the on-screen commands to merge the branches using the Git CLI.

   At the top of the dialog box, select the Remember My Choice check box to use the current option as the default setting the next time you open the Merge dialog box.

4. If necessary, update the Merge Summary and Merge Description.
   The fields aren’t available if you select Rebase and Merge or Manual Merge.
5. To delete the review branch after the commits are merged with the target branch, select Delete Branch.
6. If there are any linked issues, deselect the check boxes for the issues that you don’t want to mark as resolved after the commits are merged with the target branch. By default, the check boxes for all linked issues are selected.
7. Submit the dialog box.

After the review branch has been merged, the merge request will be closed automatically. No other action is allowed.

If you didn’t select the Delete branch check box when you merged the review branch, note that the review branch wasn’t removed from the Git repository. You can continue to make commits to the branch and create another merge request to review the new source code.

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:

1. Open the merge request that has conflicts.
2. Click Merge Conflicts.
   The Merge Conflicts dialog opens.
3. Click Resolve Conflicts to open the conflict resolution editor.
   The pane on the left indicates the number of files with conflicts and lists them. It also shows the number of conflicts in each file. The pane on the right, the code editor, displays the highlighted file with conflicts shown in the left pane.
4. Use the right arrow to go to the first (or next) conflict.
   You can use the left arrow to go to the previous conflict, if there is one. To see the differences that cause the conflict, click View Diff.
5. To resolve the conflict, click the conflict marker, the circle next to the line numbers, to select the change to use.
   One marker will select Use Their Change, the other will select Use Our Change. The marker turns red to indicate your choice.
6. Go through the file and resolve each conflict independently or use Resolve # Conflicts, where # indicates the number of conflicts in the file, to resolve all conflicts in a file the same way.
   Continue until there are no more conflicts. If you're not satisfied with the resolution you chose last, click Discard Resolution. To discard all your selections and start over, click Discard All.
7. Click Update Review to commit the files to the review branch.
8. Click Merge and push the commit to the target branch.

Files in the review branch that no longer had conflicts were merged with the target branch. No additional action is required on the Merge Request page. If you want to delete the review branch, open or refresh the Merge Request page, and click Delete Branch.

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:

1. On your computer, open the Git CLI.

2. If you’ve already cloned the project Git repository, navigate to its directory.

   If you haven’t cloned the Git repository, clone it.

3. Run the commands shown on the Merge Conflicts dialog.

   The commands help you resolve the conflict and mark the conflicting code lines in files.

4. 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.

5. Review the content and update it. Remember to remove the <<<<<<<, =======, and >>>>>>> from each conflicting file before saving it.

6. Save all files and commit them.

   Run the git status command to view the status of conflicting files.

7. 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:

1. Open the merge request.
2. Click Close.
3. Complete the elements of the Close Merge Request dialog box:

   • To change the review status to Merged and close the review, select the Close as Merged check box. You may choose the Close as Merged option if the review branch was merged through some other means (such as the Git CLI or though the git cherry-pick command).

   • If you don’t select the Close as Merged check box, the Merge Request is closed without changing the review status to Merged. You may want to do this if the merge request was created on the wrong branch or created by mistake.

4. Click OK.

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:

1. In the left navigator, click Project Administration .
2. Click Branch Protection.
3. Click in the search repositories field and select the Git repository.
4. Select the Branch name radio button, click in the search field below it, and select the branch.

   If there aren't any rules associated with the branch, proceed to the next step.

   If there any rules already associated with the branch, those will be displayed. You can select a rule to see its protections, which are displayed in the right-hand panel. If the rule has the Requires Review option already selected and the other options (default reviewers, approvals, exempt users, etc.) are acceptable, you're all set.

5. In the right-hand panel, select the Requires Review option.

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.