Transcription

USER GUIDEMADCAP FLARE 2021Source Control: Git

Copyright 2021 MadCap Software. All rights reserved.Information in this document is subject to change without notice. The software described in this document is furnishedunder a license agreement or nondisclosure agreement. The software may be used or copied only in accordance with theterms of those agreements. No part of this publication may be reproduced, stored in a retrieval system, or transmitted inany form or any means electronic or mechanical, including photocopying and recording for any purpose other than thepurchaser's personal use without the written permission of MadCap Software.MadCap Software9191 Towne Center Drive, Suite 150San Diego, California 92122858-320-0387www.madcapsoftware.comTHIS PDF WAS CREATED USING MADCAP FLARE.

CONTENTSCHAPTER 1Introduction5CHAPTER 2General Information for Git6Common Source Control Terms7Source Control Icons8CHAPTER 3Process for Git9Binding a Project to Git10Importing From Source Control20Pulling Files From a Remote Repository23Committing Source Control Files27Pushing Files to a Remote Repository29Adding Files to Source Control33Merging Source Control Files36CHAPTER 4Other Activities for GitCONTENTS45Branch Activities for Git46Deleting Source Control Files78iii

Disabling the Get Latest Prompt for Source Control79Enabling Source Control Status Checks80Modifying Network Settings81Publishing to Source Control84Reverting Modified Source Control Files85Rolling Back to an Earlier Version of a File86Setting Color Options for Project File Differences92Synchronizing Source Control Files94Unbinding a Project From Git98Using Git for Windows99Viewing Differences in Source Control Files102Viewing the History of Source Control Files105Viewing Modified Files107APPENDIXPDFsCONTENTS109Tutorials109Cheat Sheets109User Guides110iv

CHAPTER 1IntroductionYou can use the Flare interface to perform various source control tasks for a project that is boundto Git. Alternatively, you can use a third-party solution, such as Microsoft DevOps on Azure (VisualStudio Online) or Git for Windows to connect to your Git repository. Some commonly used Gitrepositories are GitHub, GitLab, CloudForge, and Bitbucket.General Informationnn"Common SourceControl Terms" on page7"Source Control Icons"on page 8Process1. Install and Set Up Git(done outside of Flare)2. "Binding a Project toGit" on page 103. (Other Team Members)"Importing FromSource Control" onpage 204. "Pulling Files From aRemote Repository" onpage 23CHAPTER 15. "Committing SourceControl Files" on page276. "Pushing Files to aRemote Repository" onpage 297. "Adding Files to SourceControl" on page 338. "Merging SourceControl Files" on page365

CHAPTER 2General Information for GitThere are various pieces of general information you should know if you plan to use this feature.This chapter discusses the following:CHAPTER 2Common Source Control Terms7Source Control Icons86

Common Source Control TermsFollowing are definitions for some of the common phrases used in Flare's integrated source controlwith Git.nBind This means to connect your project to Git. After doing this, you can then take advantageof all the automated source control tasks (such as commit, revert, pull, push, and so on).nCommit This means to record your Flare files to the local Git repository.nRevert This means to undo changes you have made to a Flare branch or file. Changes arereverted to the way they were at the last commit.nSynchronize This pulls the files from the remote Git repository and merges them with yourlocal database, then pushes your local changes back to the remote Git repository.nPull This retrieves commits from the remote Git repository and merges them with the files inyour local database.nPush This sends commits from your local database to the remote Git repository.nBranch This creates a new path for commits. This lets you create new versions of a file whilekeeping the original file unchanged (e.g., for documenting a new feature, testing page layouts,or rewriting existing information). You can create as many branches as you want.NOTE Flare integrates with multiple source control providers to provide built-in sourcecontrol support. Each of the source control providers built-in to Flare uses different terms.As such, Flare's source control interface is different depending on which source controlprovider you use. Please refer to the sections for each source control provider if you needto see information about the terms used by other built-in systems.CHAPTER 27

Source Control IconsFollowing are descriptions for the primary icons that you may see next to files when using Git.ModifiedThis indicates that the file has been modified. You can commit the file to your local Gitrepository when you are ready.New File (Pending Add)This indicates that you have a file in your project but have not yet added it to Git. Thismight occur, for example, if you create a new topic and do not add the file to sourcecontrol during the topic creation process. To resolve this, simply right-click on the fileand select Source Control Add.CHAPTER 28

CHAPTER 3Process for GitCertain tasks must be completed in order when using this feature.This chapter discusses the following:CHAPTER 3Binding a Project to Git10Importing From Source Control20Pulling Files From a Remote Repository23Committing Source Control Files27Pushing Files to a Remote Repository29Adding Files to Source Control33Merging Source Control Files369

Binding a Project to GitUse the following steps if you have already created a Flare project and want to bind ("connect") it toGit. You can also automatically detect existing source control bindings if your project has beenpreviously connected to Git.NOTE Each project bound to Git must have its own source control repository.NOTE When first binding a project to Git, the repository must be empty. For example, if youare using a third-party solution such as Git Hub to create a repository, you might initially bepresented with options (such as README or .gitignore) that add files to your newrepository. If you select any of these options and then attempt to bind the project to Git, youwill experience an error that looks something like this: "Destination already in use byanother project. Please push to an empty remote."Therefore, you should avoid selecting any such options when creating your repository. Afteryou bind the project to the Git repository, you can then return to the repository and add theREADME or other files as necessary.CHAPTER 310

How to Bind a Project to Source Control1. Select Project Project Properties. The Project Properties dialog opens.2. Select the Source Control tab.3. Click Bind Project. The Bind Project dialog opens.4. From the drop-down, select Git.CHAPTER 311

5. If you are going to bind to a remote repository, select the Remote Repository box, then enterthe address of the repository in the field. If you want to work locally, you can leave this boxunselected. You can enter an HTTP URL or an SSH URL.NOTE You may need to obtain this information from your system administrator.NOTE If you use CloudForge Git as your remote repository, it may give you anincorrect URL. If you enter the incorrect URL in when binding your project, you willreceive an error when you push or pull.To correct this error, change the URL from this format /yourproject.git to this format ect.gitRemoving the [email protected] section from the URL allows it to work properly whenperforming a push or pull.6. If you want to push to the remote repository when you bind the project, select the Push onbind check box. This will push the initial project files to the repository when you bind theproject.7. In the Name field, enter your name.8. In the Email field, enter your email address.9. From the Save Per drop-down, select how you want to save your files.nUser Saves the files in your local folder. Select this option if you are working with othertools (e.g., Tortoise) or if you want to use the same user identity across multipleprojects.nProject Saves the files locally to your project. Select this option if you want to usedifferent identities for each project.10. (Optional) In the Comment field, you can enter any internal comments.11. In the Bind Project dialog, click OK.12. In the Project Properties dialog, click OK.CHAPTER 312

13. (Optional) If you entered an HTTP address in Step 7, enter your user name and password inthe Log In dialog. Click OK when you are finished.14. (Optional) If you entered an SSH URL in Step 7, the Certificate Specification dialog opens. Inthe dialog, do the following and click OK when you are finished:a. In the Public key field, enter your public SSH key, or useyour network.b. In the Private key field, enter your private SSH key, or useyour network.to browse for the key onto browse for the key onc. If you want Flare to remember your key information so you do not need to enter it againlater, select the check box next to Save certificate information.NOTE SSH keys allow you to establish a secure connection between yourcomputer and your Git source control provider (likewise, using an SSH URL ismore secure than an HTTP URL; you need to use SSH keys if you want to usean SSH URL). If you do not have a public and private SSH key, your cangenerate these keys using your Git source control provider (e.g., Gitlab). Followthe directions provided by your source control provider to add these keys toyour Git account. Once you generate these keys, they are typically found in theC:\Users\[username]\.ssh folder on your computer.Public keys typically have a .pub extension. Private keys use the same filename as the public key, but without the file extension.CHAPTER 313

EXAMPLE Use the following as guides when setting up your URLs and keys.SSH roject.gitHTTP myproject.gitSSH Private KeymycompanySSHkey id rsaSSH Public KeymycompanySSHkey id rsa.pubCHAPTER 314

How to Bind a Project to Source Control Usingthe Explorer1. Select View Source Control Explorer. The Source Control Explorer opens.2. From the drop-down or the Home pane, select Settings. The Settings pane opens.3. Click Bind. The Bind Project dialog opens.4. From the drop-down, select Git.5. If you are going to bind to a remote repository, select the Remote Repository box, then enterthe address of the repository in the field. If you want to work locally, you can leave this boxunselected. You can enter an HTTP URL or an SSH URL.NOTE You may need to obtain this information from your system administrator.CHAPTER 315

6. If you want to push to the remote repository when you bind the project, select the Push onbind check box. This will push the initial project files to the repository when you bind theproject.7. In the Name field, enter your name.8. In the Email field, enter your email address.9. From the Save Per drop-down, select how you want to save your files.nUser Saves the files in your local folder. Select this option if you are working with othertools (e.g., Tortoise) or if you want to use the same user identity across multipleprojects.nProject Saves the files locally to your project. Select this option if you want to usedifferent identities for each project.10. (Optional) In the Comment field, you can enter any internal comments.11. In the Bind Project dialog, click OK.12. In the Project Properties dialog, click OK.13. (Optional) If you entered an HTTP address in Step 7, enter your user name and password inthe Log In dialog. Click OK when you are finished.14. (Optional) If you entered an SSH URL in Step 7, the Certificate Specification dialog opens. Inthe dialog, do the following and click OK when you are finished:a. In the Public key field, enter your public SSH key, or useyour network.b. In the Private key field, enter your private SSH key, or useyour network.to browse for the key onto browse for the key onc. If you want Flare to remember your key information so you do not need to enter it againlater, select the check box next to Save certificate information.CHAPTER 316

NOTE SSH keys allow you to establish a secure connection between yourcomputer and your Git source control provider (likewise, using an SSH URL ismore secure than an HTTP URL; you need to use SSH keys if you want to usean SSH URL). If you do not have a public and private SSH key, your cangenerate these keys using your Git source control provider (e.g., Gitlab). Followthe directions provided by your source control provider to add these keys toyour Git account. Once you generate these keys, they are typically found in theC:\Users\[username]\.ssh folder on your computer.Public keys typically have a .pub extension. Private keys use the same filename as the public key, but without the file extension.EXAMPLE Use the following as guides when setting up your URLs and keys.SSH roject.gitHTTP myproject.gitSSH Private KeymycompanySSHkey id rsaSSH Public KeymycompanySSHkey id rsa.pubCHAPTER 317

Automatically Detecting Project BindingsYou can scan a project when you open it to see if it has any bindings to source control. If a bindingis detected, you can apply the binding and commit the project to source control.1. Select File Options. The Options dialog opens.2. Select the Source Control tab.3. Select the Bind Detection check box.4. Select the source control provider(s) you want to scan for bindings.NOTE Source control providers are scanned in the following order:a. Gitb. Subversionc. Perforce Helix CoreTIP Detecting source control bindings may take a considerable amount of time. It isrecommended that you select only the source control providers that you use tospeed up the detection process.CHAPTER 318

What’s Not