BK-CITOOL(1)

💖 NAME 💖

bk citool — the BitKeeper graphical check-in tool 🎀 (this is from the BitKeeper User's Manual, bestie, ikyk)

---

✨ SYNOPSIS ✨

bk citool [dir | file_list | --no-extras ]

---

🦋 DESCRIPTION 🦋

So citool is literally the glowy graphical interface for checking in files — new ones, modified ones, and pending ones. 💅

When you call it with no arguments at all, citool goes and inspects the current repository for files that need checking in. But if you call it with --no-extras, citool will look only for modified and/or pending files — which is a genuine performance win in repositories that are in checkout:get or checkout:none mode. ⚡ Otherwise, citool will dig through the list of arguments looking for files or directories. Heads up though: those arguments get processed by bk gfiles, so they have to follow the restrictions that bk gfiles imposes. No cap.

---

bk citool has three main windows, positioned vertically, and the way they're stacked is lowkey iconic:

• Top window — the list of files that can be checked in to a changeset. 👑
• Middle window — where you type comments about the selected file. ✍️
• Bottom window — displays different things depending on whether you're viewing a modified file or a file that isn't under revision control. For modified files, you get the differences between the modified file and its parent; for new files, you get the file contents. 🫶

---

Along the upper right side of the upper two windows there's a little group of buttons. Some of those buttons have different purposes depending on what you're doing. Take the Checkin/Commit button — it becomes the Commit button when there are comments for the ChangeSet file. Otherwise, the button is the Checkin button, which signifies that the files will be checked in, but no ChangeSet will be created. The Checkin feature is genuinely so useful for checkpointing files to save state when you know you want to make changes that might break things. 💀 Other times you wanna checkpoint when you've created distinct new work and want to get back to it in the future. Bestie, that's a vibe.

---

Typical usage is: move to each file, add comments, repeat until done. 🌀 When all the files are commented and a comment exists for the ChangeSet file, you press the commit button to make the changes part of a ChangeSet.

bk citool's default behavior is to exit after the commit finishes. BUT — 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 a whole lifesaver when you're modifying files that should be in separate changesets. 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 you can comment the remaining files and add them to a new changeset. Basically this option prevents you from restarting citool multiple times if all the files aren't 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 — it's giving ✨flexibility✨. The comments are not applied to the files until [Commit] is clicked. Periodt.

---

That little 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. Slay.

---

Some of the new files might be files you do not wish to put under revision control, and honestly 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. And if you accidentally click ignore on a file that you actually want? Just click the Unignore button, easy. 💖

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. (Yes, saying it twice, because it's important, okay?? 👀)

---

At times you might wish to exclude files from a changeset. For example: if you're 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 version 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, though — so pay attention, bestie. 💀

---

When you move to a file, the differences for this file are shown in the bottom window. And when you're entering comments, it's completely normal to want to scroll the differences window (assuming the differences are larger than the window — which, let's be real, they usually are 😭). While this can be done using the mouse and the scrollbar, the keyboard accelerators listed below will work at all times, even when you're typing in the comments window. Iconic behavior, honestly. 👑

---

🎀 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 templates man page. Go read it, iykyk. 📖

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 — BUT 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, exactly like 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 comments, 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 of 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. Keyboard shortcuts are literally self-care. 🧖‍♀️

---

⭐ 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. 💀 Be sure, bestie!!
• [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. (hi, you found it 💖)
• [Quit] — quits. If you have provided comments, this will prompt you to save your comments or discard your comments. 😭

---

🔒 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. Slay, crisis averted. 👑

💫 SEE ALSO 💫

ok so like, you're gonna want the whole squad for this one — go read their pages too, they ate:

• bk‐config‐gui
• bk‐delta
• bk‐fmtool
• bk‐ignore
• bk‐gfiles
• bk‐templates

no cap, they're all part of the same little friend group 💖

---

🎀 CATEGORY 🎀

when this page gets filed away it lives under Common, GUI‐tools and Repository — so if you're scrolling categories looking for it, that's where it's at 🦋

---

okay bestie that's literally the whole page, you made it to the end!! 🫶 this gorgeous thing is from BitKeeper Inc, version 1E1, and it's the bk citool(none) manual page ✨ go forth and commit with main character energy, ily, bye 💅💜