Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
QCMD(1)			    General Commands Manual		       QCMD(1)

NAME
       qmv,  qcp  -  Rename or copy files quickly, editing the file names in a
       text editor

SYNOPSIS
       qcp [OPTION]... [FILE]...

       qmv [OPTION]... [FILE]...

       qcmd --command=COMMAND [OPTION]... [FILE]...

DESCRIPTION
       This manual page	document describes the qcp, qmv	and qcmd commands.

       The qmv program allows files to be renamed by editing  their  names  in
       any text	editor.	By changing a letter in	a text document, a letter in a
       filename	can be changed.	Since the files	are listed after  each	other,
       common changes can be made more quickly.

       The  qcp	 program  works	 like  qmv, but	copies files instead of	moving
       them.

       The qmv program was built with safety in	mind - bogus renames caused by
       human  error  are  avoided  by  performing  as many checks as possible.
       Because of this,	qmv supports an	interactive mode where	each  step  in
       the  rename procedure can be executed manually. The default is to start
       qmv in non-interactive mode. However,  when  there  is  a  conflict  or
       error,  qmv  will drop to interactive mode (instead of losing all user-
       made changes). For more information on the renaming process and	inter-
       active mode, see	below. This also applies to qcp.

       The  qcmd program works just like qmv and qcp but allows	you to specify
       which command to	execute.

       The ls(1) program is used to list files to rename  or  copy.  Therefore
       qmv, qcp, and qcmd accepts some ls options.

RENAMING/COPYING PROCESS
       The  process  of	renaming or copying files consists of many steps. They
       are:

       List files
	      Generate a list files to rename from command-line	 arguments  by
	      using ls(1).

       Create an editable text file
	      The  edit	 format	 creates  an  editable text file with the file
	      names.

       Start the editor
	      Start the	text editor and	wait until the user has	finished edit-
	      ing it.

       Read the	edited text file
	      The edit format reads the	edited text file now with updated file
	      names.

       Check rename and	reorder	to resolve conflicts (qmv only)
	      This is a	complicated step which involves	the following tasks:

	      Tag renames where	the destination	file already  exists,  renames
	      where  the  old file is now missing or inaccessible, and renames
	      renames where the	new name was not changed. Perform a  topologic
	      sort  on	the  renames, so that renaming b->c, a->b is possible.
	      Resolve cross references by renaming into	 temporary  names,  so
	      that renaming e->f, f->e (or e->f, f->g, g->e and	so on) is pos-
	      sible.

	      This step	results	in a plan of renames.

       Display the plan.
	      Display the plan to the user.

       Apply the plan.
	      Apply the	plan by	actually renaming  or  copying	files  (unless
	      --dummy was specified).

       If  an  error  occurs during any	of the above steps (except the first),
       qmv/qcp drops the user into the interactive mode. This way  no  changes
       should be lost, and errors can be corrected manually before continuing.
       See below for a description of the interactive mode.

OPTIONS
       These programs follow the usual GNU  command  line  syntax,  with  long
       options starting	with two dashes	(`-').

       -a, --all
	      (Passed to ls.) Do not hide entries starting with	`.'.

       -A, --almost-all
	      (Passed to ls.) Do not list implied `.' and `..'.

       -B, --ignore-backups
	      (Passed to ls.) Do not list implied entries ending with `~'.

       -c     (Passed to ls.) Sort by ctime (time of last modification).

       --command=COMMAND
	      Execute COMMAND instead of mv or cp.

       -d, --directory
	      (Passed to ls.) List directory entires instead of	contents.

       -r, --reverse
	      (Passed to ls.) Reverse order while sorting.

       -R, --recursive
	      (Passed to ls.) List subdirectories recursively.

       -S     (Passed to ls.) Sort by file size.

       --sort=WORD
	      (Passed  to  ls.)	 Sort by extension (-X), none (-U), size (-S),
	      time (-t), version (-v), status (-c), time (-t), atime (-u),  or
	      access (-u).

       --time=WORD
	      (Passed  to  ls.)	If sorting is done by time (--sort=time), sort
	      by atime,	access,	use, ctime or status time.

       -t     (Passed to ls.) Sort by modification time.

       -u     (Passed to ls.) Sort by access time.

       -U     (Passed to ls.) Do not sort; list	entries	in directory order.

       -X     (Passed to ls.) Sort alphabetically by entry extension.

       -f, --format=FORMAT
	      Change edit format of text file. See below for possible values.

       -o, --options=OPTIONS
	      Pass options to the selected edit	format.	OPTIONS	is in the for-
	      mat

	      OPTION[=VALUE][,OPTION[=VALUE]...]

	      For   a	list   of  available  options  for  each  format,  use
	      --options=help or	see below.

       -i, --interactive
	      Start in command mode (see below for information on this mode).

       -e, --editor=PROGRAM
	      Specify program to edit text file	with. The default  program  is
	      determined  by looking at	the VISUAL environment variable, or if
	      that is not set, the EDITOR environment variable.	If that	is not
	      set either, use the program called editor.

       --ls=PROGRAM
	      Specify  path  of	the ls program.	If you omit the	directory, the
	      executable will be searched for in the directories specified  by
	      the PATH environment variable.

       -v, --verbose
	      Be more verbose about what is being done.

       --dummy
	      Do  everything  as  usually,  except actually renaming any files
	      ("dummy" mode).

       --help Show summary of options.

       --version
	      Output version information and exit.

EDIT FORMATS
       An edit format is responsible for generating a text file	 for  editing,
       and parsing it once it has been edited. The default format is dual-col-
       umn, but	there are other	formats	as well.

       Not all edit formats take the same options. Therefore, it is  necessary
       to  specify  them  using	the --options (-o) option. This	option takes a
       list of "suboptions" similar to the -o option in	mount(8).

       Available edit formats are `single-column' (or `sc'), `dual-column' (or
       `dc'),  and  `destination-only'	(or `do'). The default format is dual-
       column.

DUAL-COLUMN FORMAT
       The dual-column format (`dual-column' or	`dc') displays	files  in  two
       columns.	This is	the default and	recommended format.  The leftmost col-
       umn is usually the source file name (which should not be	 edited),  and
       the rightmost column the	destination file name.

       Supported options:

       swap   Swap  location of	old and	new names when editing.	I.e. the left-
	      most column is now the destination file name, and	the  rightmost
	      the source file name.

       separate
	      Put a blank line between all renames.

       tabsize=SIZE
	      By  default,  tab	 characters of size 8 are used to separate the
	      columns.	With this option the width of these tab	characters can
	      be changed.

       spaces Use space	characters instead of tab characters when indenting.

       width=WIDTH
	      This  option  specifies  the  character  position	(horizontally)
	      which the	second file name starts	at.

       autowidth
	      Normally,	if the source file name	is longer than	width  charac-
	      ters,  the destination name is printed on	the next line instead.
	      With this	option enabled however,	qmv/qcp	will adjust the	 width
	      so  that	source	and destination	file names can be displayed on
	      one line.

	      If a width has been specified with  width	 prior	to  autowidth,
	      that width will be used as a minimum width.

	      Example:	Assume	that  width=10,autowidth is specified. Even if
	      all source file names are	 shorter  than	five  characters,  the
	      split  width would be 10.	If there had been one file name	longer
	      than 10 characters, the final width would	have been more than 10
	      characters.

	      This option is enabled by	default.

       indicator1=TEXT
	      Text to put before the first file	name (column).

       indicator2=TEXT
	      Text to put before the second file name (column).

       help   Show summary of edit format options.

SINGLE-COLUMN FORMAT
       The  single-column format (`single-column' or `sc') displays files in a
       single column - first source file name and on the next line the	desti-
       nation file name.

       Supported options:

       swap   Swap  location of	old and	new names when editing.	I.e. the first
	      line will	contain	the destination	file name, and the  next  line
	      the source file name.

       separate
	      Put a blank line between all renames.

       indicator1=TEXT
	      Text to put before the first file	name.

       indicator2=TEXT
	      Text to put before the second file name.

       help   Show summary of edit format options.

DESTINATION-ONLY FORMAT
       The destination-only format (`destination-only' or `do')	displays files
       only the	destination file name, one on each line. This format is	gener-
       ally  not  recommended, since the only way to identify source file name
       is by looking at	the line number. But it	may be useful with  some  text
       editors.

       Supported options:

       separate
	      Put a blank line between all renames (file names).

INTERACTIVE MODE
       In  interactive	mode  qmv/qcp reads commands from the keyboard,	parses
       them, and executes them.	This is	done using GNU readline.

       The following commands are available:

       ls, list	[OPTIONS].. [FILES]..
	      Select files to rename. If no files are  specified,  select  all
	      files in current directory. The accepted options are those which
	      are passed to ls(1). Use `help ls' to display a list of these.

       import FILE
	      Read files to rename from	a text file. Each line	should	corre-
	      spond to an existing file	to rename.

       ed, edit
	      Edit  renames  in	 a  text  editor. If this command has been run
	      before, and not `all'  is	 specified,  only  edit	 renames  with
	      errors.

       plan   Display  the  current  rename-plan.  (This plan is created after
	      `edit'.)

       apply  Apply the	current	plan, i.e.  rename  files.  Only  those	 files
	      marked as	OK in the plan will be renamed.

       retry  If  some rename failed earlier during `apply', this command will
	      try those	renames	again.

       show   Display the value	of the specified  configuration	 variable,  or
	      all variables if none specified. See below for a list of config-
	      uration variables.

       set VARIABLE VALUE
	      Set the value of a configuration variable.

       exit, quit
	      Exit the program.	If there are unapplied changes,	the user  will
	      be  notified so, and it will be necessary	to run this command an
	      extra time to exit the program.

       help [ls|usage]
	      If `ls' is specified, display list options. If `usage' is	speci-
	      fied,  display  accepted command line options. Otherwise display
	      help on commands in interactive mode.

       version
	      Display version information.

VARIABLES
       The following variables are available in	interactive mode:

       dummy BOOLEAN

       editor STRING

       format STRING

       options STRING
	      These variables corresponds to the options with the same name.

       tempfile	STRING
	      This variable contains the name of the temporary file  which  is
	      edited with `edit'. It cannot be set; only be read with `show'.

       A  boolean  value  is  specified	 as  `0', `false', `no', `off' or `1',
       `true', `yes', and `on'.	Strings	are specified without quotes.

EXAMPLES
       Edit names of files in current directory.
	    qmv

       Edit names of files with	extension `.c'.	 Sort  files  by  modification
       time.
	    qmv	-t *.c

       Edit names of files using the nedit editor and with column width	100.
	    qmv	-enedit	-owidth=100

REPORTING BUGS
       Report bugs to <oskar@osk.mine.nu>.

AUTHOR
       The  author  of	renameutils  and  this	manual page is Oskar Liljeblad
       <oskar@osk.mine.nu>.

COPYRIGHT
       Copyright (C) 2001, 2002, 2004, 2005, 2007, 2008, 2011 Oskar Liljeblad

       This is free software; see the source for copying conditions.  There is
       NO  warranty;  not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
       PURPOSE.

qcmd (renameutils)	       December	4, 2007			       QCMD(1)

NAME | SYNOPSIS | DESCRIPTION | RENAMING/COPYING PROCESS | OPTIONS | EDIT FORMATS | DUAL-COLUMN FORMAT | SINGLE-COLUMN FORMAT | DESTINATION-ONLY FORMAT | INTERACTIVE MODE | VARIABLES | EXAMPLES | REPORTING BUGS | AUTHOR | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=qmv&sektion=1&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help