bk citool(7.3ce) BitKeeper User's Manual bk citool(7.3ce) NAME bk citool - BitKeeper graphical check-in tool SYNOPSIS bk citool [<dir> | <file_list> | --no-extras | -s<alias>] DESCRIPTION The citool application is a graphical interface for checking in new, modified, and pending files. When called with no arguments, citool examines the current repository for files requiring checkin. If called with --no-extras, citool will look only for modified and/or pending files (a performance win repositories in checkout:get or checkout:none mode). If called with -s<alias> in a nested collection citool will restrict the repositories searched to those implied by <alias>. Other- wise, citool will look in the list of arguments for files or directo- ries. The arguments are processed by bk gfiles, and have to follow the restrictions imposed by bk gfiles. bk citool has three main windows that are positioned vertically. The top window contains the list of files that can be checked in to a changeset. The middle window is used for entering comments about the selected file while the bottom window displays different things depend- ing on whether viewing a modified file or a file not under revision control. For modified files, the differences between the modified file and its parent are shown and for new files, the file contents are shown. Along the upper right side of the upper two windows are a group of but- tons. Some of the buttons have different purposes depending on what the user is doing. For example, the "Checkin/Commit" button becomes the "Commit" button when there are comments for the ChangeSet file. Other- wise, the button is the "Checkin" button which signifies that the files will be checked in, but no ChangeSet will be created. The Checkin fea- ture is useful when checkpointing files to save state when you know you want to make changes that may break things. Other times you want to checkpoint when you've created distinct new work and want to get back to it in the future. Typical usage is to move to each file, add comments, and repeat until done. When all files are commented and a comment exists for the ChangeSet file, the "commit" button is pressed to make the changes part of a ChangeSet. bk citool's default behavior is to exit after the com- mit finishes. However, the ci.rescan configuration option forces citool to rescan the repository for files that still need to be added to a changeset. This feature is useful when modifying files that should be in separate changesets. For example, if you modify five files and three of those files form a logical unit of work, you can start citool, add the three files to a changeset and then commit. After committing the files to a changeset, citool returns so that you can comment the remaining files and add them to a new changeset. Basically, this option prevents the user from restarting citool multiple times if all files are not added to a changeset. You can move around within the file list by clicking on a file name or using the keyboard accelerators Control-n (next file) and Control-p (previous file). You may add comments, move around, come back, and update the comments. The comments are not applied to the files until "[Commit]" is clicked. The question mark icon to the left of the file name denotes files that are not under revision control. To add the new files to the changeset, click on the question mark icon or use the Control-t key to add the file to the current changeset. Clicking on the question mark changes the icon to a check mark, indicating that the file will be part of the cset. Some of the new files might be files that you do not wish to put under revision control and having them visible clutters up the file window. When a new file is highlighted, the "Ignore" button is activated on the button bar menu. If you click the "ignore" button, the selected file will be added to the BitKeeper/etc/ignore file so that when citool is run again, the selected file will not be shown. If you accidentally click "ignore" on a file that you want, click the "Unignore" button. The BitKeeper/etc/ignore file is not updated until the changeset is committed. The ignore file is a revision controlled file like any other BitKeeper file and can be edited with a text editor if you want to remove or add files to the ignore list. The entries that are selected to be ignored are not added to the ignore file until the changeset is committed. At times, you might wish to exclude files from a changeset. For exam- ple, if you are working on a file and have made changes to it (changes can be committed and in the pending state), but don't want these changes to propagate when you push your work to another repository. To exclude files from the changeset, use the left mouse button to click on the file-type icon. If the file can be excluded, the icon will change to a red X. If you try to exclude a pending file while a modified ver- sion of the file exists, both the pending and the modified file will be excluded. It is possible to exclude the modified file, while keeping the pending file in an included state. When you move to a file, the differences for this file are shown in the bottom window. When entering comments, it is normal to want to scroll the differences window (assuming that the differences are larger than the window). While this can be done using the mouse and the scrollbar, the following keyboard accelerators will work at all times, even when typing in the comments window: COMMENT TEMPLATES bk citool supports the ability to define a system-wide template to be used for the ChangeSet comments. This file is documented in the bk tem- plates man page. If a template exists it will be loaded into the ChangeSet comments if there are no pre-existing comments. The comments may be edited as usual; if the comments are not modified they will be treated as if there are no comments. That is, if the ChangeSet comments are identical to the template no changeset will be created, as is the case when there are no comments in the window and you press the "checkin" button. KEYBOARD BINDINGS Home Scroll to the start of the differences End Scroll to the end of the differences PageUp Scroll the differences up 1 screen PageDown Scroll the differences down 1 screen #BKMOD#-c Copy the selected text in the comments window to the clipboard. #BKMOD#-v Paste the contents of the clipboard to the comments window. #BKMOD#-x Cut the selected text in the comments window to the clipboard. #BKMOD#-Shift-x Delete the contents of the comments window and save them in the citool pasteboard. #BKMOD#-Shift-v Paste the contents of the citool pasteboard into the comments window, completely replacing any existing com- ments, and advance to the next file. Middle-Button On Unix, this will paste the X11 selection buffer into the comments window. Control-n Go to the next file Control-p Go to the previous file Control-l Rerun the diffs in case an external program has changed the file. Control-t Toggle include/exclude state and/or add/don't add state. See the text about include/exclude and new files. Control-Shift-t Toggle all new files into or out off the changeset. Control-Enter Do the commit. Same as clicking on the "Commit" button. #BKMOD#-q Same as clicking the "[Quit]" button. Control-b Scroll the differences up 1 screen Control-f Scroll the differences down 1 screen Control-u Scroll the differences up 1/2 screen Control-d Scroll the differences down 1/2 screen Control-e Scroll the differences down 1 line Control-y Scroll the differences up 1 line EDITING THE COMMENTS The comments window is a standard TK text widget with word and line erase added. Moving around is done with the arrow keys, backspace to delete the previous character, Control-w (or Alt-w) to erase a word, and Alt-u to erase a line. BUTTONS There are a series of buttons on the right. They perform the following functions: [Cut comments] deletes the contents of the current comment window and saves them in the clipboard. [Paste comments] paste the contents of the clipboard into the comments window, completely replacing any existing comments, and advance to the next file. [Commit] displays all comments in the differences window and asks if you want to commit. [Edit] a pull down menu, giving you the choice of running a simple TK based editor or your $EDITOR on the current file. Saving the file in the editor will overwrite the current file. The pull down also has an option to pop you into bk fmtool on the checked in version and the current version of the file. You may then select the changes you do not want to keep and "merge" the two versions to a new version, which will replace the current file. [History] starts up revtool on the current file [Diff tool] starts up difftool on the previous/current versions of the file. [Discard] destroys the changes made to the current file, in other words, throws away the differences. [Ignore] When a new file is selected, the ignore button will add the selected file to the BitKeeper/etc/ignore file. [Unignore] When a new file is selected and is in the ignore state, the "Unignore" button prevents the selected file from being added to the BitKeeper/etc/ignore file. [Help] Starts up the BitKeeper help tool and displays this help. [Quit] Quits. If you have provided comments, this will prompt you to save your comments or discard you com- ments. LOCKING If the repository is locked, and you try to bk commit, the commit will fail. You can wait for the lock to go away and then try the commit again; it should succeed. If the lock is an invalid one (left over from an old remote update), then you can switch to another window and unlock the repository. After it is unlocked, the commit should work. SEE ALSO bk config-gui bk delta bk fmtool bk ignore bk gfiles bk templates CATEGORY Common GUI-tools Repository BitKeeper Inc 1E1 bk citool(7.3ce)