346 lines
14 KiB
Markdown
346 lines
14 KiB
Markdown
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:
|
|
|
|
```javascript
|
|
[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.
|