diff --git a/README.md b/README.md index 7fa3396327..8c3b7066bb 100644 --- a/README.md +++ b/README.md @@ -1,194 +1,194 @@ # Visual Studio Team Services Extension -### *The extension now supports Team Foundation Server 2015 Update 2 and later!* -This extension allows you to connect to Team Services, manage your pull requests for your Git repositories as well as monitor builds -and work items for your team project. It will use your local Git repository information to connect to either +### *The extension now provides support for **Team Foundation Version Control (TFVC)**!* +This extension allows you to connect to Team Services, manage your pull requests for your Git repositories as well as +monitor builds and work items for your team project. It uses your local repository information to connect to either Team Services or Team Foundation Server 2015 Update 2 (and later). +As of version 1.116.0, it **provides support for the TFVC source control system**! To learn about the TFVC support, review our [documentation](TFVC_README.md). + ![Visual Studio Team Services extension](assets/vscode.png) -Here is the [Walkthrough of the Team Services extension for Visual Studio Code](https://www.youtube.com/watch?v=tpjj5i8f6BE) +Here is the [Walkthrough of the Team Services extension for Visual Studio Code](https://youtu.be/sk6LrzQX4P8) video that shows many of the features of the extension. -**Note**: The extension does *not* support Team Foundation Version Control (TFVC) at this time. Therefore, you must use the extension for your **Git** repositories. - ## Prerequisites ### Visual Studio Team Services -If you are planning on using the extension with Git repositories hosted on Visual Studio Team Services, ensure you have a Team Services account. If you do -not have a Team Services account, find out how to [sign up for Team Services](https://www.visualstudio.com/en-us/get-started/setup/sign-up-for-visual-studio-team-services). +If you are planning on using the extension with Visual Studio Team Services, ensure you have a Team Services account. If you do +not have an account, find out how to [sign up for Team Services](https://www.visualstudio.com/en-us/get-started/setup/sign-up-for-visual-studio-team-services). ### Team Foundation Server -If you are planning on using the extension with Git repositories on Team Foundation Server, you must be running Team Foundation -Server 2015 Update 2 or later. Earlier versions of Team Foundation Server are not supported. +If you are planning on using the extension with Team Foundation Server, you **must** be running Team Foundation +Server 2015 Update 2 or later. Earlier versions of Team Foundation Server are not supported. ### Clone your Git repository -Since the extension uses the remote origin of your Git repository to determine how to connect to Team Services (or your Team Foundation Server), in most cases you will need to have -a Git repository already cloned locally. If you intend on cloning an existing repository, do so before proceeding. If you do not have a Git repository cloned locally but already -have a Team Services account (or a Team Foundation Server instance), you may create a local repository (via `git init`) and once you set the "origin" remote for that local repository, -the extension will detect the change to the remote and attempt to contact the Team Services account (or Team Foundation Server). +With Git, the extension uses the remote origin of your repository to determine how to connect to Team Services (or your Team Foundation Server), in most cases you will need to have a Git repository already cloned locally. If you intend on cloning an existing repository, do so before proceeding. If you do not have a Git repository cloned locally but already have a Team Services account (or a Team Foundation Server instance), you may create a local repository (via `git init`) and once you set the "origin" remote for that local repository, the extension will detect the change to the remote and attempt to contact the Team Services account (or Team Foundation Server). + +### Create your TFVC workspace +With TFVC, the extension uses information about the current workspace to determine how to connect to Team Services (or your Team Foundation Server). At this time, you will need to have a local TFVC workspace already available on your local machine. These can be created using the Visual Studio IDE, Eclipse or with the JetBrains IDEs (e.g, Android Studio, IntelliJ). ## Installation -First, you will need to install [Visual Studio Code](https://code.visualstudio.com/download) `1.7.0` or later. +First, you will need to install [Visual Studio Code](https://code.visualstudio.com/download) `1.11.1` or later. -To install the extension with the latest version of Visual Studio Code (version 1.9.0 is the latest as of this writing), bring up the Visual Studio Code Command Palette (`F1`), -type `install` and choose `Extensions: Install Extensions`. In the `Search Extensions in Marketplace` text box, type `team`. Find -the `Visual Studio Team Services` extension published by *Microsoft* and click the `Install` button. Restart Visual Studio Code. +To install the extension with the latest version of Visual Studio Code (version 1.11.1 is the latest as of this writing), bring up the Visual Studio Code Command Palette (`F1`), type `install` and choose `Extensions: Install Extensions`. In the `Search Extensions in Marketplace` text box, type `team`. Find the `Visual Studio Team Services` extension published by *Microsoft* and click the `Install` button. Restart Visual Studio Code. ## Authentication ### Visual Studio Team Services If you are connecting to Team Services, you will need a personal access token (PAT) to securely access your account. The latest version of the extension will prompt for your token and store it securely. In previous versions of the extension, you needed to create a -token and store it in your Visual Studio Code user settings. +token and store it in your Visual Studio Code settings. If you do not have a personal access token yet, you will need to create one on your Team Services account. -To create the token, go [here](https://aka.ms/gtgzt4) to learn how. -* When you create your token, create it with the **Build (read)**, **Code (read)** and **Work items (read)** scopes to ensure full functionality. -* You can also use *All Scopes*, but the minimum required scopes are those listed above. +To create the token, go [here](https://aka.ms/gtgzt4) to read how. You can also [view our video](https://youtu.be/t6gGfj8WOgg) on how to do the same. +* Git repositories require that you create your token with the **Build (read)**, **Code (read)** and **Work items (read)** scopes to ensure full functionality. You can also use *All Scopes*, but the minimum required scopes are those listed above. +* TFVC repositories require tokens with *All Scopes*. Anything less will cause the extension to fail. ### Team Foundation Server -If you are connecting to Team Foundation Server, you will only need your NTLM credentials (domain name, account name and password). +If you are connecting to Team Foundation Server, you will only need your NTLM credentials (domain name, account name and password). It is assumed that you have the proper permissions on the TFS Server. Details on how to connect to either Team Services or Team Foundation Server are found in the next section. -## Open a local Git Repository folder -Once you have installed the extension, open either the root folder or a sub-folder of the cloned Git repository. Once a Team +## TFVC Support +Once you have a local TFVC workspace available, you must configure the TFVC support in Visual Studio Code. You can find that information (including demo +videos) in our [TFVC documentation](TFVC_README.md). + +## Open a local Repository folder +Once you have installed the extension, open either the root folder or a sub-folder of the repository. Once a Team Services or Team Foundation Server 2015 Update 2 (or later) repository is detected by the extension, you will need to provide -your credentials (if credentials weren't already found). If you are required to provide your credentials, there will be an +your credentials (if credentials weren't already found). If you are required to provide your credentials, there will be an indicator in the status bar whose message will indicate that you need to sign in. The indicator looks like this: ![Team Error indicator](assets/team-error.png) -To sign in to your account, run the `team signin` command. If your repository is a Team Services repository, -you will be prompted to enter your personal access token. When you do, it will be stored securely on your -computer and used to connect to Team Services. If your repository is on Team Foundation Server 2015 Update -2 or later, you will be prompted to enter your username and password. After both are provided, they will +To sign in to your account, run the `team signin` command or simply click on that indicator. If your repository is a Team Services repository, +you will be prompted to enter your personal access token. When you do, it will be stored securely on your +computer and used to connect to Team Services. If your repository is on Team Foundation Server 2015 Update +2 or later, you will be prompted to enter your username and password. After both are provided, they will be stored securely on your computer and used to connect to your TFS server. Once your credentials are verified, the status bar indicators will be active and the remaining commands will -be ready to use. The stored credentials will be used for each connection to the server until they are either +be ready to use. The stored credentials will be used for each connection to the server until they are either removed by the `team signout` command or overwritten by a subsequent `team signin` command. -**Note:** In order for the extension to be activated, a repository *folder* must be opened. The extension +**Note:** In order for the extension to be activated, a repository *folder* must be opened. The extension won't be activated if only a single *file* in the repository is opened. ## Status Bar Indicators * ![Team Project indicator](assets/project-indicator.png) – This status bar item is populated with the name -of the team project to which the Git repository belongs. Clicking on the item will open your browser to -the team website. +of the team project to which the repository belongs. Clicking on the item will open your browser to the team website. -* ![Pull Requests indicator](assets/pullrequest-indicator.png) – This status bar item is a count of active -pull requests that you either requested yourself or were added to explicitly as a reviewer. Clicking the -item will display that list of pull requests in the quick pick list. Choosing one will take you to that -pull request in your browser. This indicator will update its status every 5 minutes. +* ![Pull Requests indicator](assets/pullrequest-indicator.png) – ***Git only*** This status bar item is a count of active +pull requests that you either requested yourself or were added to explicitly as a reviewer. Clicking the +item will display that list of pull requests in the quick pick list. Choosing one will take you to that +pull request in your browser. This indicator will update its status every 5 minutes. * ![Build Status indicator](assets/buildstatus-indicator.png) – This status bar item shows the status of -the build for this particular repository and branch. Hovering over the item will provide additional -information about which build was referenced (if any). Clicking on the item will take you to that build’s -summary page in your browser. This indicator will update its status every 5 minutes. +the build for this particular repository and branch. Hovering over the item will provide additional +information about which build was referenced (if any). Clicking on the item will take you to that build’s +summary page in your browser. This indicator will update its status every 5 minutes. * ![Pinned Work Item Query Status indicator](assets/pinnedquery-indicator.png) – This status bar item shows -the number of items returned by your pinned work item query. If you have not configured a pinned query it +the number of items returned by your pinned work item query. If you have not configured a pinned query it defaults to the work items assigned to you. Clicking the item will show you the work items the query returns. This indicator will update its status every 5 minutes. ## Commands In addition to the status bar integrations, the extension also provides several commands for interacting with -Team Services and Team Foundation Server. In the Command Palette (`F1`), type ```team``` and choose a command. +Team Services and Team Foundation Server. In the Command Palette (`F1`), type `team` and choose a command. -* `team create bug` – Opens your browser to the webpage used to create a new bug. If a single line of text is -highlighted in Visual Studio Code, it will be used as the title of the bug. The bug will be assigned to you. +* `team associate work items` – Prompts you to choose a work item that is assigned to you (or from the results +of your custom query). Choosing a work item will add it to the current commit/check-in message. + +* `team create bug` – Opens your browser to the webpage used to create a new bug. If a single line of text is +highlighted in Visual Studio Code, it will be used as the title of the bug. The bug will be assigned to you. You can then choose to update the fields, save, cancel, etc. -* `team create pull request` – Opens your browser for a new pull request based on the current repository and -branch. Before creating the pull request, ensure that you save, commit and push any changes you have before -running the command. Doing so will ensure that all of your latest changes are part of the pull request. +* `team create pull request` – ***Git only*** Opens your browser for a new pull request based on the current repository and +branch. Before creating the pull request, ensure that you save, commit and push any changes you have before +running the command. Doing so will ensure that all of your latest changes are part of the pull request. -* `team create task` – Opens your browser to the webpage used to create a new task. If a single line of text -is highlighted in Visual Studio Code, it will be used as the title of the task. The task will be assigned to -you. You can then choose to update the fields, save, cancel, etc. +* `team create task` – Opens your browser to the webpage used to create a new task. If a single line of text +is highlighted in Visual Studio Code, it will be used as the title of the task. The task will be assigned to +you. You can then choose to update the fields, save, cancel, etc. * `team create work item` – Prompts you to choose a work item type from the list available in your team project. -Once you make a selection, your browser is opened to the webpage used to create the work item. If a single line -f text is highlighted in Visual Studio Code, it will be used as the title of the task. The work item will be -assigned to you. You can then choose to update the fields, save, cancel, etc. +Once you make a selection, your browser is opened to the webpage used to create the work item. If a single line +f text is highlighted in Visual Studio Code, it will be used as the title of the task. The work item will be +assigned to you. You can then choose to update the fields, save, cancel, etc. -* `team send feedback` – Prompts you to either send a smile or a frown. After choosing, you can provide us -feedback of up to 1000 characters. Optionally, provide your email address so we can contact if you needed. If -you do not want to provide your email address, just leave it empty (we'll still get your feedback). *Note:* +* `team send feedback` – Prompts you to either send a smile or a frown. After choosing, you can provide us +feedback of up to 1000 characters. Optionally, provide your email address so we can contact if you needed. If +you do not want to provide your email address, just leave it empty (we'll still get your feedback). *Note:* Feedback can be sent even if telemetry reporting is disabled. * `team signin` – Use this command to sign in to a Team Services account or Team Foundation Server 2015 Update 2 -(and later) server. When your credentials are provided, they will be stored securely on your computer. The saved +(and later) server. When your credentials are provided, they will be stored securely on your computer. The saved credentials will be used for that account until they are removed by the `team signout` command or overwritten by a -subsequent `team signin` command. See the "Secure Credential Storage" topic below for more details. +subsequent `team signin` command. See the "Secure Credential Storage" topic below for more details. * `team signout` – Use this command to sign out from a Team Services account or Team Foundation Server 2015 Update 2 -(and later) server. Signing out will remove your credentials from your local computer. To sign back in, you will +(and later) server. Signing out will remove your credentials from your local computer. To sign back in, you will need to run the `team signin` command again. -* `team view blame` – If a file in the repository is opened in the editor, it will open your browser to the +* `team view blame` – ***Git only*** If a file in the repository is opened in the editor, it will open your browser to the blame page for that file in the current branch in the server repository. * `team view build summary` – Same behavior as clicking on the Build Status status bar item. * `team view history` – If a file in the repository is opened in the editor, it will open your browser to the -history page for that file in the current branch in the server repository. Otherwise, the history of the current -branch in the server repository will be opened. - -* `team login` – With version 1.113.0, this command is being deprecated in favor of `team signin`. It will be removed in a future update. +history page for that file in the current branch in the server repository. Otherwise, the history of the current +branch in the server repository will be opened. This command does support TFVC repositories. -* `team logout` – With version 1.113.0, this command is being deprecated in favor of `team signout`. It will be removed in a future update. - -* `team view pull requests` – Same behavior as clicking on the Pull Requests status bar item. +* `team view pull requests` – ***Git only*** Same behavior as clicking on the Pull Requests status bar item. * `team view website` – Same behavior as clicking on the team project status bar item. * `team view work items` – Prompts you to choose a work item that is assigned to you, sorted by ChangedDate descending. -Choosing a work item will open it in your browser. This command will return a maximum of 200 results with an option -to "Browse additional work items...". Choosing that option will open your browser to show all of the results of your query. +Choosing a work item will open it in your browser. This command will return a maximum of 200 results with an option +to "Browse additional work items...". Choosing that option will open your browser to show all of the results of your query. * `team view work item queries` – Prompts you to choose a query stored in your “My Queries” folder in your team project. -Choosing a query will run it and display the results in the Quick Pick list. Choosing one of the results will open that -work item in your browser. This command will return a maximum of 200 results with an option to "Browse additional -work items...". Choosing that option will open your browser to show all of the results of your query. +Choosing a query will run it and display the results in the Quick Pick list. Choosing one of the results will open that +work item in your browser. This command will return a maximum of 200 results with an option to "Browse additional +work items...". Choosing that option will open your browser to show all of the results of your query. ## Secure Credential Storage -When you run the `team signin` command, the credentials that you provide will be stored securely on your computer. On -Windows, your credentials wil be stored by Windows Credential Manager. On OS X, your credentials will be stored in the -Keychain. On Linux, your credentials will be stored in a file on your local file system in a subdirectory of your -home folder. That file is created only with RW rights for the user running Visual Studio Code. It is **not encrypted** +When you run the `team signin` command, the credentials that you provide will be stored securely on your computer. On +Windows, your credentials wil be stored by Windows Credential Manager. On macOS, your credentials will be stored in the +Keychain. On Linux, your credentials will be stored in a file on your local file system in a subdirectory of your +home folder. That file is created only with RW rights for the user running Visual Studio Code. It is **not encrypted** on disk. ## How to disable telemetry reporting The Visual Studio Team Services extension collects usage data and sends it to Microsoft to help improve our products -and services. Read our [privacy statement](http://go.microsoft.com/fwlink/?LinkId=528096&clcid=0x409) to learn more. +and services. Read our [privacy statement](http://go.microsoft.com/fwlink/?LinkId=528096&clcid=0x409) to learn more. -If you don’t wish to send usage data to Microsoft, add the following entry to User Settings (**File > Preferences > User Settings**): +If you don’t wish to send usage data to Microsoft, add the following entry to Settings (**File > Preferences > Settings**): ```javascript "team.appInsights.enabled": "false" ``` ## Polling interval -The polling interval for the pull request and build status bar indicators defaults to five minutes. You can change this -value in the Visual Studio Code User Settings by adding an entry like the one below. The minimum value is 1. +The polling interval for the pull request and build status bar indicators defaults to five minutes. You can change this +value in the Visual Studio Code Settings by adding an entry like the one below. The minimum value is 1. ```javascript "team.pollingInterval": 2 ``` ## Logging -There may be times when you need to enable file logging to troubleshoot an issue. There are five levels of logging (`error`, -`warn`, `info`, `verbose` and `debug`). Since logging is disabled by default, you can add an entry like the one shown below -to Visual Studio Code's User Settings. Once you are finished logging, either remove the setting or set it to an empty string. +There may be times when you need to enable file logging to troubleshoot an issue. There are five levels of logging (`error`, +`warn`, `info`, `verbose` and `debug`). Since logging is disabled by default, you can add an entry like the one shown below +to Visual Studio Code's Settings. Once you are finished logging, either remove the setting or set it to an empty string. ```javascript "team.logging.level": "debug" ``` The log file will be placed at the root of your workspace and will be named `team-extension.log`. ## Pinned Work Item Queries -You can customize the pinned work item query by adding the following in the Visual Studio Code User Settings. You need to -provide the account and the query text or query path. For Team Services, your account name can be of the form -`account.visualstudio.com` or simply `account`. For Team Foundation Server, if your server URL is `http://servername:8080/tfs` +You can customize the pinned work item query by adding the following in the Visual Studio Code Settings. You need to +provide the account and the query text or query path. For Team Services, your account name can be of the form +`account.visualstudio.com` or simply `account`. For Team Foundation Server, if your server URL is `http://servername:8080/tfs` then the account name to use is `servername:8080`. **Using Query Text** @@ -211,15 +211,11 @@ then the account name to use is `servername:8080`. ] ``` - You can also create a *global* pinned query which will be the default if you have not configured one for your account by replacing *your-account-name* with *global* in the previous examples. ## Using External (non-Microsoft) Source Repositories -With version 1.113.0, you can now use the extension with repositories that are *not* hosted with either Team Services or Team Foundation Server. You -will be able to monitor your builds (for a specific build definition) and work items that *are* hosted with either Team Services or Team Foundation -Server by specifying your account information. To do this, set the following settings in VS Code. It is recommended that you set these in your -Workspace Settings (and not User Settings). You will, of course, still need to authenticate (provide credentials). +Starting with version 1.113.0, you can now use the extension with repositories that are *not* hosted with either Team Services or Team Foundation Server. You will be able to monitor your builds (for a specific build definition) and work items that *are* hosted with either Team Services or Team Foundation Server by specifying your account information. To do this, set the following settings in VS Code. It is recommended that you set these in your Workspace Settings (and not User Settings). You will, of course, still need to authenticate (provide credentials). ```javascript "team.remoteUrl": "https://account.visualstudio.com", @@ -230,7 +226,7 @@ Workspace Settings (and not User Settings). You will, of course, still need to To determine your build definition id, open the build summary for the build you'd like to monitor and grab the value of the _buildId=_ parameter in the url. ## Support -Support for this extension is provided on our [GitHub Issue Tracker](https://github.com/Microsoft/vsts-vscode/issues). You +Support for this extension is provided on our [GitHub Issue Tracker](https://github.com/Microsoft/vsts-vscode/issues). You can submit a [bug report](https://github.com/Microsoft/vsts-vscode/issues/new), a [feature request](https://github.com/Microsoft/vsts-vscode/issues/new) or participate in [discussions](https://github.com/Microsoft/vsts-vscode/issues). @@ -245,5 +241,5 @@ The [Microsoft Visual Studio Product Family Privacy Statement](http://go.microso describes the privacy statement of this software. ## License -This extension is [licensed under the MIT License](LICENSE.txt). Please see the [third-party notices](ThirdPartyNotices.txt) +This extension is [licensed under the MIT License](LICENSE.txt). Please see the [third-party notices](ThirdPartyNotices.txt) file for additional copyright notices and license terms applicable to portions of the software. diff --git a/TFVC_README.md b/TFVC_README.md new file mode 100644 index 0000000000..f1739abfb2 --- /dev/null +++ b/TFVC_README.md @@ -0,0 +1,198 @@ +# Team Foundation Version Control (TFVC) Support + +This extension provides TFVC support by way of the Source Control Viewlet in Visual Studio Code. + +Here are the currently supported features provided by the extension: +- Execute all basic version control actions such as add, delete, rename, move, etc. +- View local changes and history for your files +- Include and Exclude changes (and move files between the two states) +- Merge conflicts from updates +- Check-in and update local files +- Associate work items to check-ins +- Integrated TFVC Output window +- Support for a TFS proxy +- Support for workspaces created with either the Visual Studio IDE, the JetBrains IDEs and Eclipse + +![Team Foundation Version Control Viewlet](assets/tfvc-viewlet.png) + +## Getting Started Videos +Below are a few videos to help get you started using TFVC quickly. +- [TFVC Source Code Control for Visual Studio Code](https://youtu.be/6IzJ2UPGmoQ) - This video shows you how to set up +the TFVC support on Windows and demonstrates much of the functionality available for Team Foundation Version Control. The +features shown in this video apply equally well to the TFVC support on macOS and Linux. +- [Set up and Configure the TEE CLC on Linux (and macOS)](https://youtu.be/VPNaEIVZfr0) - This video demonstrates how to set +up the Team Explorer Everywhere Command Line Client (TEE CLC) on Ubuntu. On macOS and Linux, the CLC provides the TFVC capability +to the extension. +- [Set up the Team Services extension for Visual Studio Code](https://youtu.be/t6gGfj8WOgg) - If you haven't used the extension +before, this video will show you how to set it up, create a personal access token and get up and running. +- [Walkthrough of the Team Services extension for Visual Studio Code](https://youtu.be/sk6LrzQX4P8) - This is a walkthrough of +most of the features of the Team Services extension. + +## Prerequisites +### Visual Studio Team Services +If you are planning on using the extension with Visual Studio Team Services, ensure you have a Team Services account. If you do +not have an account, find out how to [sign up for Team Services](https://www.visualstudio.com/en-us/get-started/setup/sign-up-for-visual-studio-team-services). + +### Team Foundation Server +If you are planning on using the extension with Team Foundation Server, you **must** be running Team Foundation +Server 2015 Update 2 or later. Earlier versions of Team Foundation Server are not supported. + +## Installation +First, you will need to install [Visual Studio Code](https://code.visualstudio.com/download) `1.11.1` or later. + +### The Visual Studio Code Extension +To install the extension with the latest version of Visual Studio Code (version 1.11.1 is the latest as of this writing), bring +up the Visual Studio Code Command Palette (`F1`), type `install` and choose `Extensions: Install Extensions`. In the `Search Extensions in Marketplace` +text box, type `team`. Find the `Visual Studio Team Services` extension published by *Microsoft* and click the `Install` button. +Restart Visual Studio Code. + +### TFVC Command Line Client +In order to provide TFVC support in Visual Studio Code, the extension relies on the use of a TF command line client. Therefore, +you will need to have one already installed and configured. TFVC support will not work without an available command line client. + +#### Visual Studio IDE (Windows) +With a typical installation of Visual Studio, the Windows version of the TFVC command line client (tf.exe) is available under +the `Program Files (x86)` folder. It will typically be placed in a location similar to +`C:\Program Files (x86)\Microsoft Visual Studio 14.0\Common7\IDE\TF.exe`. On the 2017 version of Visual Studio, it can be found in a location similar to `C:\Program Files (x86)\Microsoft Visual Studio\2017\Professional\Common7\IDE\CommonExtensions\Microsoft\TeamFoundation\Team Explorer\TF.exe`. + +#### Eclipse, JetBrains IDEs (Windows, macOS, Linux) +If you typically use Eclipse or one of the JetBrains IDEs (e.g., Android Studio, IntelliJ), you will need to download and +extract a version of the Team Explorer Everywhere Command Line Client (TEE CLC). As of this update, the latest version can +be downloaded from [TEE-CLC-14.114.0.zip](https://github.com/Microsoft/team-explorer-everywhere/releases/download/v14.114.0/TEE-CLC-14.114.0.zip). +After downloading, extract it to a folder and open a Terminal window. + +From that Terminal window, ensure that at least Java 8 is installed and available (run `java -version` to check +the version). Once Java is configured properly, you will need to accept the TEE End User License Agreement by +running `tf eula`. Make sure to read the EULA and accept it by entering `y`. The extension will not function properly +until this EULA is accepted. + +If you are using the TEE CLC, see how to set it up by viewing [this video](https://youtu.be/VPNaEIVZfr0). + +## Authentication +### Visual Studio Team Services +If you are connecting to Team Services, you will need a personal access token (PAT) to securely access your account. +The latest version of the extension will prompt for your token and store it securely. In previous versions of the +extension, you needed to create a token and store it in your Visual Studio Code settings. + +If you do not have a personal access token yet, you will need to create one on your Team Services account. +To create the token, go [here](https://aka.ms/gtgzt4) to read how. You can also [view our video](https://youtu.be/t6gGfj8WOgg) +on how to do the same. +* TFVC repositories require tokens with *All Scopes*. Anything less will cause the extension to fail. + +### Team Foundation Server +If you are connecting to Team Foundation Server, you will only need your NTLM credentials (domain name, account name +and password). It is assumed that you have the proper permissions on the TFS Server. + +## Configure TFVC Support +To configure TFVC support, you must provide the location to the TF command line client used by the extension to perform +TFVC actions. To set this location, add the following entry to Settings (**File > Preferences > Settings**): +```javascript + "tfvc.location": "" +``` +If you plan to use the TFVC command line provided by the Visual Studio IDE, the value to provide will be similar to `C:\\Program Files (x86)\\Microsoft Visual Studio 14.0\\Common7\\IDE\\TF.exe`. + +If you plan to use the TEE CLC, the value to provide will be similar to `/home/username/TEE-CLC-14.114.0/tf`. On Windows, +the entry should point to `tf.cmd`. On macOS and Linux, it should point to the script `tf`. If you are using the TEE CLC, +see how to do this by viewing [this video](https://youtu.be/VPNaEIVZfr0). + +## Team Foundation Version Control +To get an overview of the TFVC support provided by the extension, view [this video](https://youtu.be/6IzJ2UPGmoQ). Although +it demonstrates the extension running on Windows, the TFVC functionality will work the same on macOS and Linux. Further +information is detailed below. + +### Open a local TFVC Repository folder +Once you have installed the extension, open either the root folder or a sub-folder of the TFVC repository. Once a Team +Services or Team Foundation Server 2015 Update 2 (or later) repository is detected by the extension, you will need to provide +your credentials (if credentials weren't already found). If you are required to provide your credentials, there will be an +indicator in the status bar whose message will indicate that you need to sign in. + +The indicator looks like this: + +![Team Error indicator](assets/team-error.png) + +To sign in to your account, run the `team signin` command or simply click on that indicator. If your repository +is a Team Services repository, you will be prompted to enter your personal access token. When you do, it will be +stored securely on your computer and used to connect to Team Services. If your repository is on Team Foundation +Server 2015 Update 2 or later, you will be prompted to enter your username and password. After both are provided, they will +be stored securely on your computer and used to connect to your TFS server. + +Once your credentials are verified, the status bar indicators will be active and the remaining commands will +be ready to use. The stored credentials will be used for each connection to the server until they are either +removed by the `team signout` command or overwritten by a subsequent `team signin` command. + +**Note:** In order for the extension to be activated, a repository *folder* must be opened. The extension +won't be activated if only a single *file* in the repository is opened. + +### The TFVC Source Control Viewlet +![Team Foundation Version Control Viewlet](assets/tfvc-viewlet.png) + +This is the Team Foundation Version Control Viewlet. It displays lists of any conflicting changes (to be resolved before +the next check-in), included changes (changes to be included in the next check-in), excluded changes (changes to keep but +excluded from check-in). The viewlet also provides right-click context menus to allow additional functionality like Undo, +Include and Exclude. + +#### Check In and Refresh +![TFVC Check In Refresh](assets/tfvc-checkin-refresh.png) +* `Check In` – This `check mark` button is used to check in your changes. You will not be prompted for a comment so make sure you provide +one before clicking. +* `Refresh` – This `circular arrow` button runs the TFVC `Status` command and processes the results. + +#### The '...' Menu +This menu provides access to additional commands provided by the TFVC source provider. + +![TFVC ... Menu](assets/tfvc-more-menu.png) + +* `Sync` – This option runs the `Get` command and handles any conflicts or errors. +* `Associate Work Items` – In order to associate work items to your check-in, select this option. The list of work items +assigned to you (or returned from your custom query) will be displayed for you to choose. Choosing one adds it to your check-in comment. +* `Check In` – Use this option to check in your changes. +* `Undo All` - If there are file modifications, this command will prompt for confirmation and then undo all of the changes. +* `Show TFVC Output` – Use this option to display the `TFVC Output` window which shows the TFVC commands run during this session. +* `Switch SCM Provider... >` – This option is provided by VS Code and allows you to change between the available source control +providers (e.g, Git, TFVC, etc.). + +#### Resolving Conflicts +When conflicts need to be resolved, you can use these commands to do so. There are inline icons which also provide this functionality. + +![TFVC Resolve Conflicts](assets/tfvc-resolve-conflicts.png) + +* `Open Diff` – Opens the diff view between the modified file and the versioned file. +* `Open File` – Opens the modified file in the editor. +* `Resolve: Take Theirs` – Resolves the conflict as `Take Theirs`. +* `Resolve: Keep Yours` – Resolves the conflict as `Keep Yours`. +* `Undo` – Reverts the changes made to the file. + +***Note:*** Resolving conflicts between branches is not supported in the extension. At this time, these conflicts are best addressed +in an IDE or at the command line. + +### File Explorer +Access to renaming a file is provided on Visual Studio Code's File Explorer menu. + +![TFVC Rename](assets/tfvc-rename.png) + +* `Rename (TFVC)` – To properly rename a file in TFVC using the `Rename` command (instead of `Delete` and `Add`), use this option on +Visual Studio Code's File Explorer. You will prompted for a new file name. + +## Additional Information +### Specifying a TFS Proxy +To configure a TFS proxy server, you must provide the URL to that server in the Visual Studio Code Settings (**File > Preferences > Settings**): + ```javascript + "tfvc.proxy": "http://servername:9999/proxy" + ``` + +## Frequently Asked Questions +### *Is it required that I have a TFVC workspace already on my local machine to use the TFVC support?* +With release 1.116.0, yes, it is a requirement that you have an existing workspace on your local machine. + +### *Can I use the Team Explorer Everywhere Command Line Client (TEE CLC) to provide the TFVC functionality on Windows?* +Yes. If you use Eclipse or one of JetBrain's IDEs (e.g, Android Studio, IntelliJ) on Windows, then you will want to use the TEE CLC to provide +the TFVC support. + +### *Which instructions do I follow to set up TFVC functionality on the macOS?* +You will follow the same instructions for setting up the TEE CLC as is shown on Ubuntu in [this video](https://youtu.be/VPNaEIVZfr0). + +### *I have workspaces created with Visual Studio. Can I use the TEE CLC to work with them?* +This should be possible. However, you will need to make the TEE CLC aware of those workspaces by running the `tf workspaces -collection:` command. + +## Further Information +For information on other features of the extension, support, licensing, privacy, or contributing code, please review the main [README](README.md) file. diff --git a/assets/tfvc-checkin-refresh.png b/assets/tfvc-checkin-refresh.png new file mode 100644 index 0000000000..9e058b4574 Binary files /dev/null and b/assets/tfvc-checkin-refresh.png differ diff --git a/assets/tfvc-more-menu.png b/assets/tfvc-more-menu.png new file mode 100644 index 0000000000..25e1c70175 Binary files /dev/null and b/assets/tfvc-more-menu.png differ diff --git a/assets/tfvc-rename.png b/assets/tfvc-rename.png new file mode 100644 index 0000000000..1f178eeb44 Binary files /dev/null and b/assets/tfvc-rename.png differ diff --git a/assets/tfvc-resolve-conflicts.png b/assets/tfvc-resolve-conflicts.png new file mode 100644 index 0000000000..4df6949b13 Binary files /dev/null and b/assets/tfvc-resolve-conflicts.png differ diff --git a/assets/tfvc-viewlet.png b/assets/tfvc-viewlet.png new file mode 100644 index 0000000000..e324047259 Binary files /dev/null and b/assets/tfvc-viewlet.png differ diff --git a/assets/vscode.png b/assets/vscode.png index afa7cf8a80..83c735114b 100644 Binary files a/assets/vscode.png and b/assets/vscode.png differ diff --git a/package.json b/package.json index 1fa648df39..c793ea5989 100644 --- a/package.json +++ b/package.json @@ -13,9 +13,9 @@ "keywords": [ "Team Foundation Server", "Team Services", - "Visual Studio Online", "Visual Studio Team Services", - "VSTS" + "VSTS", + "TFVC" ], "categories": [ "Other" @@ -300,7 +300,7 @@ }, { "command": "team.OpenBuildSummaryPage", - "title": "View Build summary", + "title": "View Build Summary", "category": "Team" }, { @@ -335,7 +335,7 @@ }, { "command": "tfvc.Checkin", - "title": "Checkin", + "title": "Check In", "category": "TFVC", "icon": { "light": "resources/icons/light/check.svg",