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)