We’ve looked what an issue is in Jira and how to create them. It’s great to be able to track our work as issues in Jira but the real power comes from Jira’s ability to group, organize and categorize these issues. When you start to get into 100’s, 1000’s or even 10,000’s of an issue the ability to focus just the issues you need becomes absolutely critical.
Each Jira issue records a number of key pieces of information that allow us to categorize the issues. Those pieces of information can include the following:
Project Components Releases Priority Status Labels Assignment
So, for example, you might have an issue that is part of a particular software project, that is related to the API component in that project, part of release 1.0, is of a high priority, is still in a ToDo state, has been labeled as associated with ‘Team XYZ’ and is assigned specifically to Jo Bloggs. We could search in Jira based on all of this criteria and we’d find our specific issue and also any other similar issues.
Whilst we’ll look at all of these criteria (e.g. components, releases, etc) in future modules in this module we’ll look specifically at Projects.
Why have projects?
In Jira, one of the first things we have to do is create projects. A project in Jira is just container for a lot of issues. It’s the top-level container. Every issue must be assigned to one (and only one) project.
For example, we may have Jira installed for our company ACME. Within ACME we are running a number of different projects to cover new software system to enhance our ‘Delivery System’, our ‘Accounting Systems’ and our ‘HR System’. Within Jira, to track issues related to each of these areas we’d create separate projects for each system. Then issues (or pieces of work) that need to be tracked against our ‘ACME Delivery System’ are all linked to this project. When we view this project in Jira we’ll see all of the issues related to ‘ACME Delivery System’ all neatly listed under this project.
In the example above we can see that we’ve selected the ‘ACME Delivery System’ project (see top left). In the middle column, we have a list of all three issue that has been created within this project. And on the right, we see the detail for the selected issue (issue ADS-3).
In the next few sections, we’re going to look at how to create projects, the different types of projects that Jira supports and how we link issues to projects.
Creating a new project
Starting out then we’ll want to create a new project. You’ll need administrator rights/privileges for this. However, if you set your system up as we described in module 1 you’ll have this automatically. It’s not difficult to find the new project option to get started…
What might be a little more confusing is what you do after this when you’re presented with the project creation options:
What this gives us is the ability to start out with creating projects based on pre-defined structures and workflows. We’ll talk about these in more detail soon but for now, we’ll start out with ‘Project Management’
This will give us a simple (but not too simple) workflow for our tasks. This is one of the key things with different types of projects. The workflow. There are also the types of issues too. In this project will have issue types of Task and Sub-task.
When you click ‘Next’ on the ‘Create Project’ dialogue box you’ll see the workflow that your issues in this project will travel through…
In short (and much much more on this to come in a future module) the workflow associated with a project dictates the status values that an issue can have. It also dictates the statuses that those issues can travel to and from.
For example in the workflow above a new issue will always start out with a status value of TO DO. You see this when you first create your issue.
When you start work on this issue you’ll move it to IN PROGRESS. Once you’ve finished work on this issue you’ll move/change the status value to DONE. In this way you can search and find all your issues with these different status values – for example, you can search for all issues in your project that are IN PROGRESS.
Pretty simple but as you’ll see later this can (and will) get much more complicated.
Anyway, where were we? Oh yes… creating our first project. We selected the project type of ‘Project Management’ which comes with a simple TO DO, IN PROGRESS and DONE workflow.
When you’re on the workflow dialogue box click the ‘Select’ button and you’ll be prompted to enter the project name and key. Start out with the project name (e.g. ‘ACME Accounting Systems’).
You’ll notice that as you enter the Name Jira will automatically come up with a Key for you. Basically, the key is used as part of the unique identifier for all your issues created in this project. For example, in our project, our unique identifier for the first few issues we create will be AAS-1, AAS-2, AAS-3, etc.
You can change this key if you want but it’s best to keep it to three or four characters (later on you’ll find it easier to refer to issues with short unique identifiers).
Click Submit and you’ll have created your first new project (err… second if we’re being pedantic and counting the project that was first created when we installed Jira).
No issues listed in there yet but the project is ready for us to start creating them. Go ahead and create your first few issues within this project by clicking on the ‘Create’ button. All new issues will automatically be associated with this project at the moment.
When you refresh the page you should see all your issues associated with this project listed:
So what can we do with this project?
What does a project give us?
Once we’ve created a project we then have the capability to create issues in that project. Remember that a project is just a bucket for the group of related issues. So many issues can belong to one project.
It’s important to realize that an issue can’t belong to multiple projects though. You can move an issue to a different project or you could copy an issue to another project, but an issue can not reside in two projects at the same time.
You can select the project you want to work in from the ‘Projects’ drop down menu:
Once you’ve created the project and selected it you can start to do things like view a summary of our project, search for certain issues within that project and report on the issues in that project.
For example, if you click the ‘Summary’ option in the left menu and then pick the ‘Statistics’ view you can see a break down of your issues by their relative status values.
If you select the ‘Issues’ option in the left menu you then have some pre-configured search filters that will show you lists of your project issues based on things like ‘Open Issues’, ‘My Open Issues’, etc
And if you select ‘Reports’ in the left menu you get to select from a list of graphical reports available from within Jira
All of these capabilities based on the one project that you want to focus on at this point in time.
Moving and Cloning
If you want to move an issue to another project that’s pretty simple. When viewing the issue just select the ‘More’ drop down followed by ‘Move’.
From here Jira will walk you through a few screens asking you to define some o the details that need updating during the move. For example, you’ll need to specify the new project and the issue type within that project.
It’s a similar process for Cloning (copying) issues too. Just select the ‘Clone’ option on the ‘More’ drop-down:
And from here Jira will ask you for a new Summary for the new issue and then Jira will create a new issue in the same project (you’ll have to ‘move’ this issue to another project as a separate step if you need Clone an issue into another project).
So a project is just a way of grouping our issues. Keep in mind too that Jira also allows us to set access rights and user privileges on a project by project basis. You might want a set of users to only have access to one project and not allow them to view issues in someone else’s project.
This coupled with the ability to define our own issue workflow, issue types and issues status values in a project make a project a highly customizable entity. A customizable entity that we can mold to fit our real-life way of working on a project.
We’ll come on to customizing our issue types, status values, and workflow in a later module. For now though so long as you understand how to create a new project and work with issues within a project you’re off to a good start.
We’ve put together a series of 6 training modules that make up an introduction to Jira course. This course is focused on the basics of Jira. We’re covering the core concepts, the building blocks, that makeup Jira. This isn’t focused on any particular development methodology (like Agile) and we don’t go into configuring/using Jira to manage Agile projects here. We’re leaving that for a separate course. What we are doing is going through the core components of Jira and showing you what Jira is built on. It’ll give you the knowledge you need to deal with Issues and see how those issue records can be managed.
We’re going to start out looking at what an Issue is (not any specific personal issues you might have). Just what an issue is in the eyes of Jira. We’ll see how those issues can be grouped into projects to help us organize them. We’ll look at other ways of categorizing those issues by linking them to components and versions. Then we’ll move on and see how we build workflows to track the status of our issues. Finally, we’ll look at the basics of the reporting and dashboard capability. And, if we have time, we might even get as far as seeing how Jira’s powerful search capability (and JQL) work. What we’re aiming for, is to give you the foundation on which to build and grow your understanding of how to get the best out of using Jira
Jira is built around ‘Issues’. The type of issues – not personal issues – more kind of issues that we find on projects we’re working on. Sometimes known as snag lists, defects lists or bugs. What we look to Jira to help us with is the recording of those issues, the organization of those issues and the tracking of the status of those issues.
When we talk about issues we could be talking about …
- bugs or defects in a product or system - a snag list for something you need to deliver to a customer - a ticket that tracks a help request from a customer - tasks in a project
An issue can be many things to many different people. In essence, though an issue can be thought of a record used to tack a piece of work. And many issues grouped together could be used to track a project made up of many pieces of work.
Setting Up Jira
Before we get ahead of ourselves though we can set up an instance of Jira locally to provide us with a sandpit to learn in. The following is NOT meant as a definitive guide to setting up Jira in a production environment. These steps are provided as a quick guide to getting Jira installed on your local machine so that you can follow through our modules in this course and experiment/learn in your own Jira environment.
You can download Jira from here…
Download and then run the installer. Select the ‘Set it up for me’ option.
After clicking on the ‘Continue to MyAtlassian’ button you’ll have to set up an account (or use an existing account if you have one). Then select the ‘Jira Software (Server)’license type.
Accepting the other fields with their default values you should then be able to click the ‘Generate Licence’ button.
And then confirm that you want to install the license key on your local system.
On the next dialogue box, you’ll need to define some account details for the Jira system administrator. You can add your own email and password here (you’ll need these again in a minute):
After you’ve clicked on ‘next’ you should see the Jira ‘Finishing your setup’ message.
And after this, the ‘Jira is ready to go’ screen.
As this suggests ‘Let’s get started’. So we’ll click the ‘Let’s get started’ button. And at this point, we should be on the dashboard login page.
Using the Admin details you provided earlier you can now log in to your own Jira instance. Once you’ve logged in you can quickly set things up, just so that we can get started, by clicking on the ‘Create Sample Project’ option.
And then select ‘Project Management’ so that we have a simple Jira project that we can work through the basics with.
Give your project a name, something really inspiring like ‘ProjectOne’.
Notice that Jira automatically gives your project a Key. You can modify this if you like but keep it short (three or four characters is usually best). We’ll discuss keys later on in the course.
At this point, you should be presented with the Project issue page for your new project, along with some sample data.
With this then we can start looking at some of the Jira fundamentals that you’ll need to understand from the outset.
What is an Issue
For now, lets put aside the Project navigation (left-hand panel) and the list of issues (in the middle). We want to understand exactly what an issue is first. Everything in Jira is built on issue records so let’s get this clear to start with.
An issue is used to track a piece of work. You can think of it as a glorified To Do list record. So if an issue is used to track a piece of work, then what information does an issue need to contain? Well, you can think of the contents of an issue as recording two types of information…
- information about the work we need to complete
- properties to help us track, categorize, group, organize and report on issues
On our initial issues page for ‘Project One’, we’ll see the first issue we’ve selected which has an ID of PROJ-1. The contents of this issue can be categorized as Information about the work and properties to help us track this work.
The information highlighted in yellow (the summary, description, and activity) covers the detail about the work we need to carry out. The information highlighted in blue (details, people, and dates) cover the properties that help us track this issue.
When you click on the Edit button (under the issue summary) you’ll see that you can update the issue information and the properties. Simple enough to grasp the Summary and Description sections. These fields just need to detail the work you want this issue to cover. Fill these in as you wish.
It’s the properties on this issue we want to really focus on. It’s the properties that give Jira its power. It’s a powerful ability to track, categorize and organize all your issues.
In this screenshot, you can see a few of the key properties highlighted (like Issue Type, Reporter, and Components). There’s a list of key properties that we really need to explain here and there are some that are really obvious… so obvious that we won’t cover them (like a reporter and due date). Others that need a little more explaining.
Issue Type: When you create an issue, depending on your Jira configuration, you can categorize your issue with a Type. In the basic setup, this will just be a 'Task' type. So an issue you create that is of Type = Task is an issue to track a task you need to complete. In more advanced setups we'll create other issue types to track things like Epics and Stories that you might record in Agile projects. Status: An issue progresses through a workflow of status values. Again in this simple project we only have a few status values that include To Do, In Progress and Done. The status you set your issue too shows where you're up to with this piece of work. In this simple setup, for example, you can move the status to 'Done' when you've finished the work that this issue record is tracking. Priority: We can set the importance or priority of this issue to one of five values. Highest, high, medium, low and lowest. Again this is just another way of categorizing our issues, in this case, so that we know which ones to work on first. Resolution: Sometimes it's useful to track what you did to resolve the issue. For example when we move our issue to a status of 'Done' what did we do to get it done? Maybe this issue task was a duplicate of another issue in the system. In which case the work might 'Done' but the resolution value would be 'Duplicate'. Think of the resolution as the value that tells you 'what you did' to complete the task. Did you do the work? Was the work already done (e.g. duplicate issue)? Or did you just decide not to do it (e.g. Won't Do). Labels: Labels can be used to categorize your issues. This is a free format field so doesn't need setting up with pre-configured values like the others. Just type one or more labels in the field and that label is assigned to the issue. This is useful for categorizing and searching for issues later on... especially when you get to 100's or even 1000's of issues.
We have whole modules dedicated to these concepts later. So don’t worry if you haven’t grasped the detail. It’ll become clearer. Now you’re aware of the concepts let’s see how they work in practice. We’ll create our first issue.
To finish off on this module then let’s quickly create our first issue. Whichever page your on in Jira you’ll always find the top menu bar with the ‘Create’ button…
Once you’ve clicked on this you’ll be presented with the Jira ‘Create Issue’ dialogue box. Simple enough to start out creating your first issue by completing the mandatory fields (marked with the red * symbol):
If you’re in a hurry then most of the fields are already populated with default values and you need to enter a Summary. The default values like Project, Issue Type, and Reporter can be updated if you want to. More importantly, it’s worth adding a description too if you want a little bit more detail.
You’ll find a few more fields on the bottom half of the dialogue box too.
Here you can assign the issue to someone and set a priority. If you want you can enter some free format labels too (just a way to categorize your issues – we’ll look at these later). Once you’re happy with that then it’s time to click the ‘Create’ button.
At which point you should see the pop up ‘Created’ notifier. If you’re quick you can click on the link and view your newly created issue. If you’re not quick you can always refer to the ‘Issues’ drop-down menu and look for your ‘Recent Issues’.
You’ll find the issue you’ve just created will be listed here too. Click on the link and you can view your first issue record.
From here you’ll see all your issue information. A few things worth pointing out though…
- top of the issue record is the path for the issue. This consists of the Project Name followed by the unique identifier given to the issue you’ve created (in the example above this is ‘ProjectOne/PROJ-7’).
- you can update any of the fields just by clicking on them. For example, click on the description text you’ve already entered and Jira will let you update it. Same goes for most of the other fields displayed on this page.
- your issue has an initial status (in this example ‘ToDo’). This status will change as you complete the work associated with the issue and update the issue. You can click on the ‘View Workflow’ link to see the status values that the issue will go through).
- in the right-hand panel you’ll see the issue was reported by someone (you in your instance) and is assigned to someone. You can change this assignment just by clicking on the field and updating the value.
- you’ll find Jira gives all your issues an easy to remember URL. In our example http://localhost:8081/browse/PROJ-7. Which is basically your server name, followed by ‘browse’ and then the unique Id (PROJ-7) that Jira gives this particular issue.
And that’s it on the basics. Once you’ve set up your Jira server (or found an instance of Jira that you can practice on) there’s nothing too difficult when it comes creating issues. In the next module we’ll up things a little and look at how we can organize our issues by grouping them into different projects.
On to tags and branching then. Tags allow us to give a more human-friendly name to a specific revision of our folders/files. Branching gives us the capability to create a copy of the folders/files in our repository and have a different copy to work on – without fear of corrupting our main copy.
As you’ve probably already grasped every time you commit a changed file to the repository SVN gives the repository a new, incremented by 1, revision number. In a reasonably sized project, over a year or two, it’s not long before those revision numbers get into the thousands or even tens of thousands. So you’re likely to get to the point where you have a stable set of files that you know are in good shape and the SVN revision number might be r2343. Not easy to remember. So we can use SVN’s tagging feature and tag that same revision with the tag v1.2 Far easier to remember and in line with the version number we could be using when we release our software.
Branching is one of the core features in SVN that allows us to work on a different instance of the files the files that are contained in the repository. Say you have a set of files in your repository that is working perfectly. They’ve been released into a production environment and nobody wants to risk changing anything just in case you break something.
Along comes your end user who says wouldn’t it be great if we could add some functionality to support X, Y, and Z. You and your team think pulling together a prototype version for this functionality would be a great idea. Your team wants to work together and collaborate on this so you want to continue using SVN for this new work. However, you don’t want to contaminate your existing repository (with all the working code) with a new prototype code that won’t work for some time.
What you need is a new copy of the files in your repository that you can make changes to without affecting the existing repository. Thinking ahead though you will want, at some point in the future, to combine this new prototype code with your existing working code.
These concepts of Tagging and Branching are explained in detail below. However, to support these capabilities we’ll need to prepare a new repository first.
Setting Up the Repository
Lets prepare that new repository so that it’ll support a trunk, branches and tags. Head back to the VisualSVN server app and select create new repository:
Follow the prompts, calling the repository something creative like ‘repo2’. Just make sure that on the ‘Repository Structure’ dialogue select the ‘Single-project repository option…
Note that we’re creating a repository here with Trunk, Branches and Tags folders. This is what gives us and SVN the capability to manage multiple instances of the same code/files. So, after you’ve created the repository you should have something like this on your Visual SVN Server…
Now we have a repository with the required starting structure. Folders to contain the different types of file collections. Trunk to contain the project files that are stable that we don’t want to interfere with. Tags to contain sets of files that have been tagged with a label relating to a specific ‘revision’ (more on this later). And ‘branches’ where we’ll a separate instance of our files where we can work on our new prototype functionality.
At this point we can check out the contents of the repository (which doesn’t actually contain any files yet) on to our local machine. So create a top level folder on your local machine:
Right click on the folder and select ‘SVN Checkout’…
And on the check out dialogue enter the URL of the repository (remember you can get this from the Visual SVN server). Defaults like ‘check out directory’ and revision should be left as they are.
Your specific directory paths and URLs may differ slightly but we’re checking out the contents of ‘repo2’ to the new directory you’ve just created on your local machine. Now we’ll have the subfolder structure with branches, tags, and trunk from the checkout.
And now we’re ready to create some files and folders in the ‘trunk’ subfolder and check those in. It’s IMPORTANT that you create them in the ‘trunk’ subfolder like this:
Doesn’t matter what you create in that directory… it’s just important that you do create the files/dirs in the ‘Trunk’ subdirectory. Now we need to tell our SVN system about these new files/folders and then commit those files and folders into the repository. Add the files/folders first…
Confirm the files you need to add…
Accept the confirmations…
Then commit the files to the repository, adding a commit message as you walk through the commit dialogue boxes…
Once you’ve completed the commit we’re ready to start looking at adding branches to our code.
A branch then is a copy of the main code within the same repository. Essentially a separate set of files that you can work on independently. In the next section, we’ll look at the steps you take to create and use a branch.
Branching consists of 4 steps:
1. create and prepare the repository so that it supports a trunk and branches
2. check in your files and directories to the repository trunk
3. create the branch based on a set of files at a specific revision
4. check out the branch
As we’ve completed steps 1 and 2 already we’re now ready to create our first branch. We’ll need to select the code we want to copy and make a branch of. We’ll bring up the Tortoise SVN context menu and select ‘Branch/Tag…’. This will allow us to create a copy of our code and place it in either the ‘branches’ or ‘tags’ subdirectories (‘branches’ in our case).
In the “Copy (Branch/Tag) dialogue box we’ll already see the correct ‘From WC/URL’ set but we’ll need to update the ‘To path’ so that it shows the ‘/branches’ directory. click on the ‘Elipse’ button for this and select ‘/branches’ directory. Then specify the name you want your branch to be called.
You can add a message if you like and select a specific ‘revision’ of the files in the repository. Once you’ve clicked on OK you’ll see the confirmation window.
From this, we can see that we’ve finished creating our copy as a branch. We’re warned that what we have as our working copy (which is what we’ve just copied) is still a representation of the trunk and NOT the branch. So any changes we make locally and check-in will be against the trunk and won’t be committed to the branch if we check them in.
What we need to do, if we want to work on our new branch, is either switch or check out a copy of the branch code from the SVN server. We’ll opt for the checkout.
To check out this branch then we’ll create a new subdirectory in our workspace. In the example below, we’ve created ‘MySecondRepo-branch’…
Then we’ll check this new branch of the code out into this folder. Right click and select ‘SVN checkout…’
It’s the next part that’s key. We need to make sure we’re checking out the branch, so the URL specified needs to reference the branch. You’ll see in the example below the end of the url specified svn/repo2/branches
And once this check out has completed you’ll see the finished log showing the files checked out from the branch and the revision that branch is labeled as:
And we’ll see the new files checked out contained in the subdirectory ‘branch-1.0.0’
From here the concept of modifying and checking in code is exactly the same as we’ve seen previously when using code checked out from the Trunk. You make changes to your branch-1.0.0 instance of the code. You can commit those changes back into the repository (in the branch).
When you get to the stage where you’re happy with your prototype work that’s on the branch you’ll want to look at merging the changes on the branch into the Trunk (where your stable working version of the code resides). Essentially you’ll want to combine both sets of code and promote your working prototype code into the main stable version of the code.
Now we’re ready to give our code a tag. Essentially a more user-friendly label to a set of our files residing in the repository at a certain point in time. First then lets take a look at our local copy of the repository files and see what revision number SVN has given them.
Find the ‘Trunk’ folder where you created your original set of files and committed them to the repository. For example…
Then right-click the directory, select Tortoise SVN and then ‘Repo-Browser’
The dialogue box you get presented with should default to the repository you’re using (if not go to your Visual SVN server application and copy the repo url again).
What you see here is the revisions of the individual files and the revision of the whole trunk part of the repository (if you hover your mouse over the ‘HEAD’ button you’ll see the main revision number). What we need to do is tag this particular revision so that it has a more user-friendly number/name that we can refer to.
Right click on the ‘Trunk’ folder (we’re tagging the latest revision of the files in the Trunk – not the branch). Then select ‘Branch/Tag…’ in the Tortoise SVN submenu.
What we do with this Branch/Tag dialogue box is key now. Essentially Branching and Tagging are the same things in SVN’s eyes. We’re just creating a copy of the files at a certain point in time for a certain revision of the files. The different between Branching and Tagging is only that the completed copy is either to the ‘branches’ folder or the ‘tags’ folder in the repository.
On our dialogue box then (the top part) we’re copying from our ‘trunk’ directory to our ‘tags’ directory. If you click on the ‘…’ button you can change the destination from ‘/trunk’ to ‘/tags’ like this…
Then we need to append our Tag name to this ‘To path’ value. So we can add something like ‘v1.0.0’ in here like this…
Add a log message and make sure you pick the current revision of the files that you want to tag. The revision number should default to the latest revision with ‘Specific Revision in Repository’ selected already.
At which point you should see the confirmation dialogue box showing the completion of the tag operation:
After clicking okay on what we can do is check out that ‘tagged’ revision of our files into a new directory. So we’ll create a new subdirectory at the top level in our workspace and give it the name of the tag we used earlier (e.g. v1.0.0)
Then right-click on this directory and select ‘SVN Checkout’
On the check out dialogue box, we’ll want to select the specific tag path within our repository. So click on the ‘…’ button for the ‘URL of repository’ section. Then in the Repository Browser make sure you select the tag name directory for the tag you created earlier.
At which point you should have something like this…
Which means we’re checking out a set of files from our repository that have been tagged with the name ‘v1.0.0’, and we’re checking them out to our subdirectory on our local system called ‘v1.0.0’. Click on OK and you should see the confirmation message that the check out has finished…
When you acknowledge this (click OK) and look in the ‘v1.0.0’ local directory you’ll have the set of files that relate to the revision you gave this tag too.
Now, regardless of what you do on the Trunk or any of the branches, if you check out this Tagged set of files you’ll always get the same revision of the files. A crucial capability if you want to be able to revert back to a known set of files at any point.
There’s a lot to branching and tagging. Branching especially. Branching can get very complex particularly when it comes to managing multiple branches and then merging code back into other branches. Hopefully, the basics we’ve covered here will get you started and help you grasp the main concepts. If you have grasped these concepts then it will put you in a good position to either start managing your own code with SVN and/or even joining an existing project that’s been using SVN for some time.
We know how to create a repository. We know how to set up our SVN client and import our initial set of files. And in the 3rd module in this series, we saw how to check out and commit changes from/to the SVN repository. All pretty straightforward and easy to follow while just one user is working on one file.
It won’t be long though before you start getting warning messages from SVN that you have a conflict. It’s how you should go about handling these conflicts we’re looking at in this module.
What you’ll find is that two people will be working on the same file and try to commit changes to the same file to the repository on the server. When this happens we get a conflict. Two users are trying to commit conflicting changes to the repository. This works as follows:
In short, we have this…
- two users have checked out the contents of the repository to their local machines
- both users start editing one of the files on the local machines
(just so happens that they are both editing the same file)
- the first user commits his/her changes to the repository
- the second user tries to commit his/her changes to the repository too
- trouble is the second user changes would overwrite the first user changes
(so the first user changes would be lost)
- SVN warns user 2 that there is a conflict
- It’s down to user 2 to resolve that conflict
What we’ll see from SVN when the second user tries to commit their change is this warning from SVN:
It’s one of SVN’s key jobs to warn users that changes to files might be lost or overwrite if multiple users are making and committing changes to the same file(s). SVN does this by warning the user that there is a conflict. You can see this happening when you follow these steps:
Create a new directory (a 2nd directory) where User 2 will check their files out to
Check out the contents of the repository to this directory…
Using the Tortoise SVN Check Out command…
… And specifying the directory URL of the repository…
Note we’re simulating being user 2 here…. just by the act of checking out the same repository contents but to a different directory. In reality, this second directory will be on a different computer and will be a different user.
Both directories now contain the contents of the repository and both are in sync with the latest updates that have been committed to the repository. You can check this with…
In this first instance, you’ll see a list of modification you’ve made (if any) to your local files. You’ll need to click on the ‘Check repository’ button to see if anyone has committed changes to the repository so there is a modification in the repository version that you’re missing locally.
Assuming you’re all up to date and in sync with the repository then we can go through the process of simulating a conflict and working through resolving that conflict. To do this we’ll go through these steps…
- modify a file in the first (user 1) directory
- commit the modified file in the first directory to the repository
- modify a file in the second (user 2) directory
- attempt to commit the modified file in the second directory to the repository
- deal with the conflict
So first, update one of the text files in the first directory and save your changes (you can use notepad or any text editor of your choice).
Then commit these changes to the repository
Adding a comment and clicking okay to complete the commit.
Check you get a successful commit message and note the new revision number… then click OK.
Now we’ll repeat the process in User 2’s directory.
Update one of the text files in the second directory and save the changes.
To commit the changes…
Note that you are committing changes from Users 2’s directory to the same central repository.
When you click OK you’ll be presented with a warning message like this…
SVN is warning users that the version of file1.txt that we updated was not done to the latest version of the file that was in the repository. If we commit this change then the latest version of the file in the repository will be overwritten and changes lost.
We need to resolve this conflict first. Without a resolution, SVN won’t let us commit this change to the repository. So click OK to clear the ‘Commit Failed’ warning dialogue box. And at this point SVN will ask you if you want to update your local working copy.
There are many ways to resolve conflicts. We’ll walk you through the update process that SVN prompts you to follow here. So click the ‘Update’ option on this dialogue box:
When you get presented with the update finished message you can clear this by clicking the okay button…
And then on the next dialogue box (that gives you the option to commit your changes again) click ‘Cancel’.
We’re canceling this because I want to show you what SVN did when it attempted to resolve the conflict and update your local copy of the file. When you click the update button what SVN does to your local file is this…
What you’re getting here is not 1, but 4 copies of the file you were working on. Those 4 files are…
This is the version of your file where SVN has tried to combine both the latest version from the repository and your local version with your latest changes.
This is your copy of the file with the changes you made. It’s exactly what you had before you attempted the commit.
This is the version of the file that you originally checked out of the repository (before you made your local changes)
This is the latest version of the file from the repository with all the latest updates that have been committed by other users.
If you take file1.txt first thing you’ll notice in explorer is that it has a triangle with an exclamation mark against it. This is showing us that it’s in a conflict state and that SVN has combined your changes with those from the latest revision found in the repository. Basically, you need to do something with this file before you can resolve the conflict and commit the merged changes to the file back into the repository.
In short what we really want to do is take the latest version of the file from the repository (file1.txt.r3) merge it with the file you had been updating (file1.txt.mine), rename the resulting file to the original file name (file1.txt) and commit the merged file back to the repository.
The simplest way (and most logical to me) I find to do this :
- use a diff/merge tool to compare file1.txt.mine and file1.txt.r3
- merge the changes between file1.txt.mine and file1.txt.r3 (with a tool like winMerge)
- copy the resulting file (or rename it) to file1.txt (overwriting the svn merge file)
- resolve the conflict
- commit the change back to the repository
In step 1 then we use a tool like WinMerge (or any merge tool of your choice; like winDiff, TortoiseDiff, etc) and compare your work with what is currently the latest version in the repository.
In the case of WinMerge select both files (file1.txt.r3 and file1.txt.mine) and then right-click to select WinMerge
From here, for step 2, we can see our local version and changes on the left. And on the right the latest version of the file from the repository. We’ll merge the repository changes into our local version. So we’ll merge right to left.
We’re being careful here to pull changes from the repository version into our version (file.txt.mine) without overwriting our changes. So the left-hand version ends up with the repository changes and our changes.
Once they’ve been merged into file1.txt.mine we want to save this file.txt.mine. This is the file with ALL the changes in. The version of the file we want to push back into the repository.
So save the file and close your merge tool.
Now for step 3, we want to make our file with all the changes the one called file1.txt. So, rename file1.txt to file1.txt.Svnmerged. Then rename file1.txt.mine to file1.txt.
Now we’ll have all our changes (the merged changes) in the file file1.txt. The newly merged file1.txt should still show the SVN conflict warning triangle.
Now, step 4, we want to tell SVN that we’ve resolved the conflict. Right click on the file and select ‘Resolve’.
And in the conflict resolution dialogue box now displayed just click okay to confirm the resolution and then click OK to the last confirmation dialogue box.
At which point we should be back to one of our usual states where SVN is just telling us that we have updated our local file and that it’s ready to be committed to the repository.
So for step 5 just commit the file back to the repository.
Complete the commit and we should now have the latest revision of the file (revision 4 in this case) stored in the repository with the merged changes from both user 1 and user 2.
At this point, we’ve completed the merge and everything is straight. Well, almost everything. User 2 has the latest copy of the merged changes (revision 3). User 1 is still in revision 3. So a good last step for User 1 (and a step you should do on a regular basis) is to update the local copy of the files.
So user 1 (in the directory ../co-repo1-user1) should update their local copy by right-clicking and selecting ‘SVN Update’.
At this point, everybody is in sync with the latest merged version of the files from the repository. And we’ve seen 2 users successfully collaborate and version control the same file on multiple client machines without losing anybody updates to the files.
There are many ways to go about this conflict, merge and update process. The one described above is a little long winded but I believe it’s the one that’s easiest to explain and understand. It’s a process that helps highlight exactly what’s going on behind the scenes with SVN. Once you’ve grasped this experiment with other approaches and see where that gest you too.
At this point, having completed module 1 and module 2, we have an SVN server, a repository in that server and we have files/directories in that repository. The whole point of this is to share files and version control them between different users. The next step then is for you to check out the files from the repository. From here we can simulate another user checking out the files from that same repository. In this way, we can see and learn how SVN deals with two people editing the same set of files at the same time.
In the last module, we created two user accounts (user1 and user2). With your first user account then (the one that you just used to import the files) we’ll check out our set of files from the repository. Once checked out we’ll have a local copy of the files under SVN version control.
First then, In a directory create a new folder where you’ll check the repository contents out to.
It’s important that we don’t drill down into this folder. We want to check the contents of our repository out into this folder. So we right-click on this folder and select ‘SVN Checkout…’
From here we’ll specify the location of the repository that we want to check our files out from. So something like…
If you’ve forgotten what this URL is then you can go back to the VisualSVN server app and right click to select ‘Copy URL to Clipboard’.
Enter this value in the ‘URL of repository’ field. Checkout directory should already be defined, along with the parameters ‘Fully Recursive’ and ‘Head Revision’
Once you’ve clicked on ‘OK’ you should see confirmation that the files have been checked out to your directory.
And you should see a nice green tick against the folder indicating that the contents of that folder are in sync with the repository (which they should be because they’ve only just been checked out).
Drill into that folder and you’ll see the individual subfolders and files with the same green tick to indicate that they are in sync too.
Now we have the contents of the repository copied locally we’ll want to modify a file and check the files changes back into the repository. Check the changes into the repository so that the repository contains the latest versions of the files for everyone else to use.
Checking in your first change
At this point then we want to modify one of our files locally and update the repository with that change. So edit one of the text files and save your changes.
You’ll notice that once you’ve saved the changes the icon against the file changes from a green tick to a red exclamation mark. This shows us that our local file is no longer in sync with the repository.
At this stage then we need to update the repository with our changes. Right click on the file and select ‘SVN Commit….’
At this point, Visual SVN will prompt you to enter a message explaining what the change was about. This is useful for other users who see the file has changed and will get to see some summary info about what the change was for.
The ‘Changes made’ section shows you which file you’re updating and what you’ve done with that file (e.g. modified it, added a new file or deleted an existing file). After you’ve clicked OK you’ll see the confirmation message showing that the commit has finished:
This confirmation message also shows you which version you’re now working with. SVN has incremented the version of your file (NOT the repository… just the file) to the next logical revision, revision 2.
If you want to review what’s happened to your files then you can check this by selecting the top-level parent folder and clicking on the Visual SVN ‘Show log’ option.
The resulting dialogue box showing you a history of all the changes for your local files.
You can see the same information if you go back to the SVN server and check the repository on the server. Viewing that repository using a browser you should see something like this…
And viewing the individual files you can see the exact revision of each file
This is all very well but the whole point of this version control system is to share and collaborate on projects. So what happens when another user updates the file and your local copy becomes out of sync? That’s what we’ll look at in a future module when we cover updating, merging and conflicts.