Question & Answer
How do you restore an IBM Rational ClearCase element whose name has been removed (rmname)?
A directory used to have a full compliment of file elements, and along the way, some elements had the name removed from the directory using the cleartool rmname command.
Note: The Delete operation from within ClearCase Explorer also executes a cleartool rmname, not a cleartool rmelem or cleartool rmver. For example, from within your view, right-click a file or directory element, select Delete, and read the details in the dialogue that appears, then click Cancel.
There are a few different ways to get the element names back into the directory in question.
Note: If files have been orphaned into the lost+found directory, review technote 1120317 for more information.
Determine which files are invisible. Here are three methods which can be used to help determine the needed directory version for the next steps:
- On the branch that your view is set to run the following command to list out all the versions that are not visible (excludes those that are visible).
cleartool find . -all -nvisible -print
- Within ClearCase Explorer, right click the directory where the element is missing and select Compare with Previous Version to see if the element existed in the previous version of the directory.
Note: If you are unsure as to which version of the directory the file was rmnamed (deleted), you need to compare with different older versions of the directory until you find the file you are looking for.
The ClearDiff window that is displayed will show the missing element in the left pane of the window. On top of that window you will see a path like the following that identifies version 4 of the directory named "directory" on the main branch:
Note: You will need this path information after the version extended syntax (@@) as this is to be used in the link command. From the example, @@\main\4 can be used to find the missing element at the path .@@\main\4\<missing-element-name>
- Run the cleartool lshistory command or the History Browser GUI on the directory to find which version of the directory the file was rmnamed which will indicate that it existed in the prior directory version before its removal.
Note: You will need the previous version of the directory for the next step. For example, say lshistory reports the following:
M:\view\my_test_vob>cleartool lshistory -d -minor -since today
17-May.07:31 user1 create directory version ".@@\main\43"
"Uncataloged file element "cs.txt"."
You will need to use version \main\42 for the next steps.
Restoring the elements
- Checkout the directory where the element is missing.
- Use one of the following procedures to restore the element name back to the LATEST version of the directory:
- Create a link using the cleartool ln operation for each element. The procedure is documented in the "Undoing the rmname Command" section of the cleartool rmname man page, cleartool man rmname, or refer to the IBM Rational ClearCase Command Reference.
For example, the missing element is called test.txt.
foo.c@@\main\13 Rule: \main\LATEST
cleartool> ln .@@\main\4\test.txt .\test.txt
Link created: ".\test.txt".
foo.c@@\main\13 Rule: \main\LATEST
test.txt@@\main\7 Rule: \main\LATEST
- Merge the directory graphically from the version tree browser:
- Start the version tree browser for the directory by right-clicking on the file directory, then select Version Tree.
- After the version tree browser appears, right-click on a version of the directory known to contain the missing file and select Merge to... and select the current version of the directory in use.
- When the dialog box appears, select Yes, and also select the option Merge the element graphically.
- Once the merge GUI appears, manually step through the differences between the current version and the selected prior version with the files.
Note: If you need assistance, you can use the Help available from within the Merge Manager tool.
- Undo the difference resolution for the removed element names and then select the correct contributor you want to use.
- Save the results, and close the graphical merge window.
You may need to Refresh your view for the element names to reappear in the directory version that they were just restored to.
- If the results are correct, then right-click the directory and click Checkin.
Caution: If more than one change was made to the directory in this version, those changes could be reverted as well. Use the cleartool lshistory command to determine what other changes were made to that directory version.
- Determine the version where the element was rmnamed.
- Use cleartool merge -delete to remove the changes applied in that version of the directory.
cleartool merge -to . -delete -version \main\17
- If the only change made in this version was the removal of the wanted element, the change should automatically be made (see about caution).
For more information about the cleartool subcommands used in this technote refer to the IBM Rational ClearCase Command Reference manual or run cleartool man <sub-command> from command line.
29 September 2018