assistance-engine/docs/developer.avapframework.com/71_SOURCE_SOURCE_CONTROL_Overview.md

AVAP TM Dev Studio has integrated source control management (SCM) and includes Git support out-of-the-box. Many other source control providers are available through extensions on the AVAP TM Dev Studio Marketplace.

Working in a Git repository

The Source Control icon in the Activity Bar on the left will always indicate an overview of how many changes you currently have in your repository. Selecting the icon will show you the details of your current repository changes: CHANGES ,{' '} STAGED CHANGES and MERGE CHANGES .

Clicking each item will show you in detail{' '} the textual changes within each file . Note that for unstaged changes, the editor on the right still lets you edit the file: feel free to use it!

You can also find indicators of the{' '} status of your repository in the bottom-left corner of AVAP TM Dev Studio: the current branch ,{' '} dirty indicators , and the number of{' '} incoming and outgoing commits of the current branch. You can checkout any branch in your repository by clicking that status indicator and selecting the Git reference from the list.

Commit

Staging (git add) and unstaging {' '} (git reset) can be done via contextual actions in the files or by drag-and-drop.

Configure your Git username and email. When you commit, be aware that if your username and/or email is not set in your Git configuration, Git will fall back to using information from your local machine. You can find the details in Git commit information.

You can type a commit message above the changes and press{' '} Ctrl+Enter (macOS: ⌘ +Enter ) to commit them. If there are any staged changes, only those changes will be committed. Otherwise, you'll get a prompt asking you to select what changes you'd like to commit and get the option to change your commit settings.

We've found this to be a great workflow. For example, in the earlier screenshot, only the staged changes to overview.png will be included in the commit. Later staging and commit actions could include the changes to versioncontrol.md and the two other{' '} .png images as a separate commit.

More specific Commit actions can be found in the{' '} Views and More Actions ... menu on the top of the Source Control view.

Cloning a repository

If you haven't opened a folder yet, the Source Control view will give you the options to Open Folder from your local machine or{' '} Clone Repository .

If you select Clone Repository , you will be asked for the URL of the remote repository (for example on GitHub) and the parent directory under which to put the local repository.

For a GitHub repository, you would find the URL from the GitHub{' '} Code dialog.

You would then paste that URL into the Git: Clone prompt.

You'll also see the option to Clone from GitHub . Once you authenticate with your GitHub account in AVAP TM Dev Studioe, you'll be able to search through repositories by name, and select any repo to clone it. You can also start the flow to clone a Git repository with the Git: Clone command in the{' '} Command Palette (Ctrl+Shift+P). To see a step-by-step walkthrough, check out our Clone repos from AVAP TM {' '} Dev Studio video.

Branches and Tags

You can create and checkout branches directly within AVAP TM Dev Studio through the Git: Create Branch and{' '} Git: Checkout to commands in the{' '} Command Palette ( Ctrl+Shift+P ).

If you run Git: Checkout to , you will see a dropdown list containing all of the branches or tags in the current repository. It will also give you the option to create a new branch if you decide that's a better option, or checkout a branch in detached mode.

The Git: Create Branch command lets you quickly create a new branch. Just provide the name of your new branch and AVAP TM {' '} Dev Studio will create the branch and switch to it. If you choose to{' '} Create new branch from... , you'll get an extra prompt that allows you to specify which commit the new branch should be pointing to.

Remotes

Given that your repository is connected to some remote and that your checked out branch has an upstream link to a branch in that remote, AVAP TM Dev Studio offers you useful actions to{' '} push , pull , and sync {' '} that branch (the latter will run a pull command followed by a push command). You can find these actions in the Views and More Actions ... menu, along with the option to add or remove a remote .

AVAP TM Dev Studio is able to periodically fetch changes from your remotes. This enables AVAP TM Dev Studio to show how many changes your local repository is ahead or behind the remote. This feature is disabled by default and you can use the git.autofetch setting(/docs/getstarted/settings) to enable it.

Git Status Bar actions

There is a Synchronize Changes action in the Status Bar, next to the branch indicator, when the current checked out branch has an upstream branch configured. Synchronize Changes will pull remote changes down to your local repository and then push local commits to the upstream branch.

If there is no upstream branch configured and the Git repository has remotes set up, the Publish action is enabled. This will let you publish the current branch to a remote.

Gutter indicators

If you open a folder that is a Git repository and begin making changes, AVAP TM Dev Studio will add useful annotations to the gutter and to the overview ruler.

• A red triangle indicates where lines have been deleted
• A green bar indicates new added lines
• A blue bar indicates modified lines

Merge conflicts

Merge conflicts are recognized by AVAP TM Dev Studio. Differences are highlighted and there are inline actions to accept either one or both changes. Once the conflicts are resolved, stage the conflicting file so you can commit those changes.

3-way merge editor

To help you resolve merge conflicts, AVAP TM Dev Studio provides a 3-way merge editor where you can interactively accept incoming and current changes and view and edit the resulting merged file. The 3-way merge editor is opened by selecting the{' '} Resolve in Merge Editor button in the bottom right corner of a file with Git merge conflicts.

The 3-way merge editor displays separate views for{' '} Incoming changes (on the left),{' '} Current changes (on the right), and the{' '} Result of the merge (at the bottom). Conflicts are highlighted and can be resolved by using the CodeLens buttons.

Resolving conflicts

The 3-way merge editor allows you to resolve conflicts by accepting either one or both changes. You can also manually edit the result of the merge.

For some conflicts, the merge editor shows an{' '} Accept Combination button. Accepting the combination resolves the current conflict by smartly merging both changes. This is especially useful for changes in the same line that don't touch the same characters.

Use the Ignore buttons to accept neither the incoming nor current change, but mark the conflict as resolved. This resets the conflicting area to the state before any changes were made.

Completing the merge

You can use the conflict counter in the right of the result editor to keep track of how many unresolved conflicts are remaining. Clicking on the counter jumps to the next unresolved conflict. Once all conflicts are resolved, you can complete the merge by selecting{' '} Complete Merge in the bottom right corner. This stages the file and closes the merge editor.

Alternative layouts and more

Selecting the three dots ( ··· ) in the top right corner of the merge editor opens a context menu with additional options. You can switch to a vertical layout and display the base view, which shows the state of the file before any changes were made.

The three dots next to Incoming , Current , and Result offer options for each view, such as showing a side-by-side diff against base, accepting all changes, or resetting the result.

Understanding conflicts

If you want to learn more about the details of how 3-way merge editors work, we can recommend the following video:

Viewing diffs

Our Git tooling supports viewing of diffs within AVAP TM Dev Studio.

Accessible Diff Viewer

There is an Accessible Diff Viewer in the Diff editor that presents changes in a unified patch format. You can navigate between changes with{' '} Go to Next Difference ( F7 ) and{' '} Go to Previous Difference ( Shift+F7 ). Lines can be navigated with arrow keys and pressing{' '} Enter will jump back in the Diff editor and the selected line.

Timeline view

The Timeline view, accessible at the bottom of the File Explorer by default, is a unified view for visualizing time-series events (for example, Git commits) for a file.

AVAP TM Dev Studio's built-in Git support provides the Git commit history of the specified file. Selecting a commit will open a diff view of the changes introduced by that commit. When you right-click on a commit, you'll get options to Copy Commit ID and{' '} Copy Commit Message .

AVAP TM Dev Studio supports more Git history workflows through{' '} extensions available on the AVAP TM Dev Studio Marketplace.

Git output window

You can always peek under the hood to see the Git commands we are using. This is helpful if something strange is happening or if you are just curious. :)

To open the Git output window, run View >{' '} Output and select Log (Git) from the dropdown list.

Initialize a repository

If your workspace is on your local machine, you can enable Git source control by creating a Git repository with the{' '} Initialize Repository command. When AVAP TM Dev Studio doesn't detect an existing Git repository, the Source Control view will give you the options to Initialize Repository {' '} or Publish to GitHub .

You can also run the Git: Initialize Repository and{' '} Publish to GitHub commands from the{' '} Command Palette ( Ctrl+Shift+P ). Running Initialize Repository will create the necessary Git repository metadata files and show your workspace files as untracked changes ready to be staged. Publish to GitHub will directly publish your workspace folder to a GitHub repository, allowing you to choose between private and public repositories. Check out our publishing repos video for more information about publishing to GitHub.

AVAP TM Dev Studio as Git editor

When you launch AVAP TM Dev Studio from the command line, you can pass the --wait argument to make the launch command wait until you have closed the new AVAP TM Dev Studio instance. This can be useful when you configure AVAP TM Dev Studio as your Git external editor so Git will wait until you close the launched AVAP TM Dev Studio instance.

Here are the steps to do so:

Now you can run git config --global -e and use AVAP TM Dev Studio as editor for configuring Git.

AVAP TM Dev Studio as Git difftool and mergetool

You can use AVAP TM Dev Studio's diff and merge capabilities even when using Git from command-line. Add the following to your Git configurations to use AVAP TM Dev Studio as the diff and merge tool:

[diff]
        ` `tool = default-difftool
        
        [difftool "default-difftool"]
        ` `cmd = code --wait --diff $LOCAL $REMOTE
        
        [merge]
        ` `tool = code
        
        [mergetool "code"]
        ` `cmd = code --wait --merge $REMOTE $LOCAL $BASE $MERGED

This uses the --diff option that can be passed to AVAP TM Dev Studio to compare two files side by side. The merge tool will be used the next time Git discovers a merge conflict.

To summarize, here are some examples of where you can use AVAP TM Dev Studio as the editor:

• git rebase HEAD~3 -i do interactive rebase using AVAP TM Dev Studio
• git commit use AVAP TM Dev Studio for the commit message
• git add -p followed by e for interactive add
• git difftool <commit>^ <commit> use AVAP TM Dev Studio as the diff editor for changes

Working with GitHub Pull Requests and Issues

AVAP TM Dev Studio can also bring in GitHub's pull requests and issues. Create your PRs in AVAP TM Dev Studio, review with comments, and approve them without switching context. Learn more about GitHub PRs and Issues in AVAP TM Dev Studio.

SCM Providers

AVAP TM Dev Studio has support for handling multiple Source Control providers simultaneously. For example, you can open multiple Git repositories alongside your Azure DevOps Server local workspace and seamlessly work across your projects. To turn on the{' '} Source Control Providers view, select the overflow menu in the Source Control view ( Ctrl+Shift+G ), hover over Views , and make sure that{' '} Source Control Repositories is marked with a check. The{' '} Source Control Providers view shows the detected providers and repositories, and you can scope the display of your changes by selecting a specific provider.

SCM Provider extensions

If you would like to install another SCM provider, you can search on the{' '} scm providers extension category in the{' '} Extensions view ( Ctrl+Shift+X ). Start typing '@ca' and you will see suggestions for extension categories like debuggers and linters. Select{' '} @category:"scm providers" to see available SCM providers.

Next steps

• Intro Video - Git Version Control - An introductory video providing an overview of AVAP TM Dev Studio Git support.
• Basic Editing - Learn about the powerful AVAP TM Dev Studio editor.
• Code Navigation - Move quickly through your source code.
• Debugging - This is where AVAP TM Dev Studio really shines
• Tasks - Running tasks with Gulp, Grunt, and Jake. Showing Errors and Warnings
• Source Control API - If you want to integrate another Source Control provider into AVAP TM Dev Studio, see our Source Control API.