Using Git for Project Management with µvision

Transcription

1 MDK Version 5 Tutorial AN279, Spring 2015, V 1.0 Abstract Teamwork is the basis of many modern microcontroller development projects. Often teams are distributed all over the world and over various time zones. Synchronizing the development work is the main task for project managers. As this work cannot be done by sending files via from one location to another, Software Version Control Systems (SVCS) are used. In the past, Concurrent Versions System (CVS) and Subversion (SVN) have been popular for workflows with a centralized server infrastructure. Nowadays, more and more decentralized workflows have been established, making use of a new SVCS called Git. This application note describes how to integrate Git into µvision and how to establish a robust workflow for version control of projects using Software Packs. Contents Abstract...1 Introduction...1 Workflows...2 Centralized Workflow...2 Using Git with µvision...3 Project Files under Version Control...3 Files that do not need to be monitored...3 Configure µvision s SVCS...3 Version Control of Software Packs...4 Centralized Workflow Example Initialize the Central Repository Clone a Repository from a Server Feature Work Manage Conflicts Conclusion Appendix A: Software Appendix B: Links Introduction Revision control is being used for a couple of years now in software development. In the past, centralized server infrastructures have been used to track the changes in the source code of a microcontroller development project. With the release of Git, decentralized VCS have become more and more popular. Git, which is free software distributed under the terms of the GNU General Public License, was developed for maintaining the Linux kernel. It became more and more popular and is now the de-facto standard in source control management (SCM), another term for VCS. This application note assumes that you have installed Git on your PC (refer to Appendix A: Software) and do know how to use the Windows command shell (cmd.exe). 1

2 Workflows Using Git, you can make use of various workflows when maintaining a software project: Centralized workflow as known to users of CVS and SVN Feature Branch workflow that adds a branch for every feature that is to be developed to the master branch Gitflow workflow using specific roles to different branches such as develop, feature, and release branch Forking workflow that is a truly distributed workflow in the sense that every developer has his own fork of the master branch and only one project maintainer is accepting commits to the master branch This application note explains how to use µvision in a centralized workflow environment. Other workflows can be realized as well using a mix of Git commands from within µvision and using the command line/gui. For more information on workflows, see Appendix B: Links. Centralized Workflow In a centralized work environment, there is usually a single collaboration model: the centralized workflow. A central repository accepts code changes, and every developer synchronizes his work to it. This is just like using SVN for example. However, using Git has a few advantages over the traditional SVN workflow. First, it gives every developer an own local copy of the entire project. In this local environment, each developer can work independently of all other colleagues. The local repository is used for commits and they can completely forget about the original one until it's convenient for them. Second, all developers can use Git s robust branching and merging model. Git branches are designed to be failsafe when adding code and sharing changes between repositories. The centralized workflow uses a central repository serving as the entry point for all project changes. The default development branch is called master and all changes are committed into this branch. No other branches are required by this workflow: 1. Initialize the central repository 2. Clone a Repository from a Server 3. Feature work (stage/commit/push) 4. Manage Conflicts 2

3 Using Git with µvision Project Files under Version Control Before setting up the workflow, the project manager should be absolutely clear about the files that need to be version controlled. Of course all source code files need to be versioned, but there are a couple of files that are special to µvision that need to be monitored as well. All user generated source files (*.c, *.cpp, *.h, *.inc, *.s) Project file: Project.uvprojx (is used to build the project from scratch) Project options file: Project.uvoptx (contains information about the debugger and trace configuration) Project file for multi-project workspaces: Project.uvmpw Configuration files for the run-time environment that are copied to the project (all files below.\rte) List of #includes created by software components: RTE\RTE_Components.h file Device configuration file: for example RTE\Device\LPC1857\RTE_Device.h Linker control file (Project.sct) if created manually All relevant Pack files (for example ARM::CMSIS, Keil::Middleware, Device Family Packs, etc.) Files that do not need to be monitored Project screen layout file: Project.uvguix.username All files that are part of a Pack (the complete Pack will be revision controlled and is available to every user as soon as he is installing it using Pack Installer) Generated output files in the sub-directories.\listings and.\objects INI files for debug adapters Configure µvision s SVCS Before using Git for SCM, you need to configure µvision s software version control menu. µvision 5.15 is providing a SVCS template file for Git. It resides in the installation directory (for example C:\Keil_v5\UV4) and is called GIT.SVCS. For versions previous to 5.15, please use the file as it is provided in this application note s ZIP file and copy it to the µvision installation directory. 1. Open µvision and go to SVCS Configure Software Version Control 2. Enter the path to the template file: When done, press OK. Now, µvision is ready to use Git as the version control system. 3

4 Accessing µvision Project Files When working with the SVCS menu, you can usually access files that are highlighted in the Project window of µvision. For example, if you are clicking on the File Blinky.c in the Project window and you then go to the SVCS menu, you will see the SVCS options for the Blinky.c file: To catch µvision s project related files (uvmpw, uvprojx, uvoptx), click on the following (or equivalent): WorkSpace uvmpw Project uvprojx Target 1 uvoptx Version Control of Software Packs To ensure that only a certain version of a Software Pack is used in a project, use the Select Software Packs icon: This will open a new window that enables you to set the versions of all Software Packs: Hint: Uncheck Use latest versions of all installed Software Packs. The information about the selected Software Pack versions is stored in the Project.uvprojx file that is also under version control using this workflow. 4

5 Centralized Workflow Example The following sections show an example for the centralized workflow. Other workflows can be derived from the example. If the SVCS menu does not provide an entry for a required Git command, use either the GUI or the command line instead. 1. Initialize the Central Repository Not all steps in the workflow can be accomplished using µvision. Some steps (especially the one for initializing the repository) need to be made using additional software. Throughout this application note, Git for Windows is used. You can either use the tool s GUI or type in the required commands in a Windows command shell as described here. A project has been added to this application note s ZIP file. It is contained in the sub-directory RTX_Blinky. Copy this folder to your hard disk, for example to C:\workdir. Open a Windows command shell by typing cmd in the address bar of Windows explorer and hit enter. A command shell opens up with the project directory: At the command prompt, enter C:\workdir\RTX_Blinky>git init Initialized empty Git repository in C:/workdir/RTX_Blinky/.git/ Now, you have to add your remote repository to your working copy (note that this remote repository must already exist please consult your Git server space provider for details): C:\workdir\RTX_Blinky>git remote add origin Then add (stage) all files from the project: C:\workdir\RTX_Blinky>git add * warning: LF will be replaced by CRLF in Blinky.uvoptx. The file will have its original line endings in your working directory. warning: LF will be replaced by CRLF in Blinky.uvprojx. The file will have its original line endings in your working directory. Note: The project files uvprojx and uvoptx have UNIX-style line endings (LF). In Windows systems, usually CRLF is used. Git automatically detects this and changes the line endings to CRLF on the server. But then the status of these two project files is always changed. You can get around this problem using the command git config --global core.autocrlf false Commit all files and add a description for the commit: C:\workdir\RTX_Blinky>git commit -m "Initial version" [master (root-commit) b71a02e] Initial version warning: LF will be replaced by CRLF in Blinky.uvoptx. The file will have its original line endings in your working directory. warning: LF will be replaced by CRLF in Blinky.uvprojx. The file will have its original line endings in your working directory. 12 files changed, 5408 insertions(+) create mode Blinky.c create mode Blinky.uvoptx create mode Blinky.uvprojx create mode Debug_RAM.ini create mode Packs/ARM.CMSIS pack create mode Packs/Keil.LPC1800_DFP pack create mode RTE/CMSIS/RTX_Conf_CM.c 5

6 create mode RTE/Device/LPC1857/RTE_Device.h create mode RTE/Device/LPC1857/startup_LPC18xx.s create mode RTE/Device/LPC1857/system_LPC18xx.c create mode RTE/RTE_Components.h Finally, push the files to the server: C:\workdir\RTX_Blinky>git push -u origin master Username/Password Counting objects: 19, done. Delta compression using up to 4 threads. Compressing objects: 100% (17/17), done. Writing objects: 100% (19/19), MiB KiB/s, done. Total 19 (delta 0), reused 0 (delta 0) To * [new branch] master -> master Branch master set up to track remote branch master from origin. Congratulations! You have created your first Git repository. For a more detailed description of the commands that you have just used, go to section Clone a Repository from a Server To get a copy of an existing Git repository (for example, a project that is created within your engineering group), you need to use the command git clone. In contrast to other version control systems such as SVN, the command is called clone and not checkout. Instead of getting just a working copy, a full copy of nearly all data on the server is saved to your hard drive. For example: C:\workdir> git clone You will be asked for your username and password. The command creates a sub-directory named rtx_blinky in C:\workdir, initializes a.git directory inside it, downloads all the data for that repository, and checks out a working copy of the latest version. If you change into the new rtx_blinky directory, you will see the µvision project files. If you want to clone the repository into a different directory, specify the name as the next command-line option: C:\workdir> git clone MyBlinky A number of different transfer protocols is available in Git. This example uses the protocol, but you may also see git:// or ssh://user@server:path/to/repo.git. 6

7 3. Feature Work Now, you have a Git repository and a checkout or working copy of the files for that project. Working on the project will create some changes and you will need to commit snapshots of those changes into your repository from time to time. Each file in the working directory is in one of the following two states: tracked or untracked. Tracked files were already present in the last snapshot; they can be unmodified, modified, or staged. Untracked files are everything else (for example build output logs etc.) any files in the working directory that were not present in the last snapshot and are not in the staging area. Cloning a repository for the first time, all files will be tracked and unmodified. While editing files, Git will recognize them as modified, because they have changed since the last commit. Staging modified files and then committing all staged changes will make them be tracked/unmodified again: Checking the File Status To determine the status of your files use the git status command. It is available in the SVCS menu (Status). If you run this command directly after a clone, your Build Output window will show something similar: When opening the project, µvision automatically generates a uvguix.username file. This is marked as not tracked (because it is not required). Staging (Adding) an Untracked File For this example, we will create a text file to will explain the usage of the project. The file will be added to the working copy of the project and later committed to the origin. In µvision, right-click on Target 1 and choose Add Group. New Group will be added in the Project window. Click on New Group and a cursor should appear. Change the group name to Documentation. Right-click on Documentation and choose Add New Item to Group Documentation. In the next window, click on Text File (.txt) and enter Abstract as the name. The 7

8 file will be added and opened in the editor. Enter any text that might seem fit. A git status will show the file as untracked. In order to begin tracking (or adding) Abstract.txt, use git add. Make sure that the file is highlighted in the Project window and then go to SVCS Stage Abstract.txt : The Build Output echoes the command: git add C:\workdir\RTX_Blinky\Abstract.txt Rerun the git status command to see the file now being tracked and staged for the next commit: Changes to be committed: (use "git reset HEAD <file>..." to unstage) new file: Abstract.txt Before committing the file, let s change another file so that it changes from unmodified to modified. Staging Modified Files Double-click Blinky.c to open it. After line 26 there are two empty lines. Delete line 27 and save the file. Another git status will output the following: Changes not staged for commit: (use "git add <file>..." to update what will be committed) (use "git checkout -- <file>..." to discard changes in working directory) modified: Blinky.c To stage the changed file, use the Stage item on the SVCS menu as shown in the previous step. Check the successful staging using the git status command. Removing a Tracked File The GIT.SVCS file does not provide the ability to use the git rm command. This command removes a file from the staging area and from the working directory. But the file still might be visible in µvision (especially when you have the file open in the Editor window). This might lead to unexpected behavior. To remove a file safely from a µvision project and the working repository, do the following: Close the file in the Editor window. In the Project window, right-click on the file and select Remove File MyFile.c Switch to your Windows command shell, go to the file s directory and issue the command git rm MyFile.c At the next commit, the file will be gone and no longer tracked. If you modified the file in between and added it to the index already, the removal must be forces using the -f option. This safety feature prevents from accidentally removing data that has not yet been part of a snapshot and that cannot be recovered from Git. 8

9 Committing Changes Before issuing the git commit command, check the project for unstaged files. A commit will only accept staged files. Any created or modified files which have not yet been staged won t go into this commit. They will remain modified on the hard disk. To commit, go to SVCS Commit staged changes. A window for entering the commit message will open: Enter the comment text and press OK. The Build Output window will show the success of the git commit: git commit -m C:\Users\User\AppData\Local\Temp\Sccs13 [master 1d1b0e6] C:\Users\User\AppData\Local\Temp\Sccs13 2 files changed, 1 insertion(+), 1 deletion(-) create mode Abstract.txt Pushing to the Repository When the project has reached a point can be shared with others, it has to be pushed upstream (to the repository server): git push [remote-name] [branch-name]. The built-in command in the SVCS menu goes one step further. It uses git push origin master to push the master branch to the origin server. There are two prerequisites for this command to work properly: 1. You need to have write access to the server you are pushing to and 2. Nobody has pushed in the meantime. If this happens, your push will be rejected:! [rejected] master -> master (fetch first) error: failed to push some refs to ' hint: Updates were rejected because the remote contains work that you do not have locally. This is usually caused by another repository pushing to the same ref. You may want to first integrate the remote changes (e.g., 'git pull...') before pushing again. See the 'Note about fast-forwards' in 'git push --help' for details. You ll have to pull down first and incorporate any changes or rebase before you will be allowed to push. 9

10 4. Manage Conflicts Rebasing The Git server s central repository is the one that every developer will finally commit to. If a developer s local commits diverge from this repository, Git will refuse to push the changes. Before the developer can publish on the server, all updated commits on the central repository need to be fetched and the changes need to be rebased on top of them. This results in a linear history on the central repository, just like in a SVN workflow. If some of the changes are conflicting directly with upstream commits, Git will pause the rebasing process. The developer can then manually resolve the conflicts. For generating commits and merging conflicting files, Git uses the same git status and git add commands. This makes it easy to manage merges. To rebase, use SVCS Rebase. This will issue a git pull --rebase origin master that tells Git to move all of your commits to the tip of the master branch after synchronizing it with the changes from the central repository. Rebasing transfers each local commit to the central repository s master branch one at a time. Thus, merge conflicts are caught on a commit-by-commit basis rather than by resolving all at once in a single merge commit. If two developers have worked on the same features (for example Blinky.c), the rebasing process will generate conflicts. Git will pause the rebase (at the current commit) and the Build Output window will show the following conflict message: git pull --rebase origin master From * branch master -> FETCH_HEAD 44af614..cdfdc12 master -> origin/master First, rewinding head to replay your work on top of it... Applying: C:\Users\User\AppData\Local\Temp\Sccs5 Using index info to reconstruct a base tree... M Blinky.c Falling back to patching base and 3-way merge... Auto-merging Blinky.c CONFLICT (content): Merge conflict in Blinky.c Failed to merge in the changes. Patch failed at 0001 C:\Users\User\AppData\Local\Temp\Sccs5 The copy of the patch that failed is found in: c:/workdir/usb_test/.git/rebase-apply/patch When you have resolved this problem, run "git rebase --continue". If you prefer to skip this patch, run "git rebase --skip" instead. To check out the original branch and stop rebasing, run "git rebase --abort". 10

11 Also, the problem will be shown in the Editor window, for example: Blaming To get more information on the changes, you can use Git s blame feature. While the main.c file is highlighted in the Project window, go to SVCS Blame Blinky.c. This will initiate the GUI of Git for Windows and show the details of the differences (hovering over the window will give more details in the yellow boxes): Finishing the Rebase Process When finished merging the file(s), do not forget to stage (git add) them. A commit is not necessary at this time as you are rebasing. Then, you need to continue the rebase process. This is not available from within µvision. You need to switch to the Windows command shell and enter: C:\workdir\rtx_blinky>git rebase --continue Git will acknowledges the changes with Applying: C:\Users\User\AppData\Local\Temp\Sccs5 Finally, do not forget to push the changes to the server (see next section). Stashing a Project Sometimes, things can get messed up and you do want to switch branches for a while to work on another part of the project. But you do not want to commit half-done work to get back to this point later. To come around this problem, you need to issue the git stash command. Stashing takes the current (messy) state of your working directory (all modified tracked files and staged changes) and saves it on a stack of unfinished changes that can be reapplied to the working directory at any time. 11

12 Pulling the Latest Version from the Server Repository To pull the latest version from the remote server, go to SVCS Pull latest version from server. This will initiate the git pull command: git pull From d8418bf..6fbcd97 master Merge made by the 'recursive' strategy. Whatever has been changed A subsequent git push should show no errors: git push origin master To 6fbcd97..e0c5dd3 master -> master Conclusion -> origin/master This application note has shown one way of using Git with µvision. As Git offers may ways of collaboration, please consult the available literature that is stated below on how to use Git for a distributed workflow. Using a combination of the commands from the GIT.SVCS file and the command line/git GUI, you can use any workflow supported by Git. Appendix A: Software To be able to use Git on a Windows PC and from within µvision, you need to install the following software: Git for Windows: For MDK versions below 5.15, you need to add the µvision SVCS template file for Git which is part of this application note s ZIP file: www. Please copy the file to the µvision installation directory, for example C:\Keil_v5\UV4 Appendix B: Links Git: Git Book: Git server space providers: Possible Workflows: Migrate from SVN to Git: More information on Git replacing LF with CRLF: 12