Rex::C...nds::Fs(3pm)

📦
version 1.16.1 · 7 versions
, in ubuntu resolute, ubuntu stonking

💖 Rex::Commands::Fs 💖

okay bestie, welcome to the manual page for Rex::Commands::Fs(3pm) — the Perl doc that lives in your terminal and tells you everything about Rex's file system commands. sit down, hydrate, let's go 🫶

🌸 NAME 🌸

Rex::Commands::Fs — File system commands. (that's it, that's the whole name, she's concise ✨)

🦋 DESCRIPTION 🦋

With this module you can do all your file system tasks — like creating directories, deleting or moving files, and more. basically the whole "touch grass but for files" toolkit 💅 lowkey essential, ngl.

✨ SYNOPSIS ✨

here's the vibe check in code form, no cap:

my @files = list_files "/etc";

unlink("/tmp/file");

rmdir("/tmp");
mkdir("/tmp");

my %stat = stat("/etc/passwd");

my $link = readlink("/path/to/a/link");
symlink("/source", "/dest");

rename("oldname", "newname");

chdir("/tmp");

is_file("/etc/passwd");
is_dir("/etc");
is_writeable("/tmp");
is_writable("/tmp");

chmod 755, "/tmp";
chown "user", "/tmp";
chgrp "group", "/tmp";

👑 EXPORTED FUNCTIONS 👑

these are the functions you get handed for free. and they ate, honestly. 🔥

🍓 Changing content 🍓

heads up bestie: these commands are supposed to change the contents of the file system. that is literally their whole job. main character energy, destructive edition. 😭

This function will create a symbolic link from $from to $to. 🦋

task "symlink", "server01", sub {
  symlink("/var/www/versions/1.0.0", "/var/www/html");
};

💫 ln($from, $to)

"ln" is an alias for "symlink". same girl, different name. 💅

This function will remove the given $file. poof. gone. 🙈

task "unlink", "server01", sub {
  unlink("/tmp/testfile");
};

🗑️ rm($file)

This is an alias for "unlink". yes, really, same thing. 💖

📂 rmdir($dir)

This function will remove the given directory. 🌸

task "rmdir", "server01", sub {
  rmdir("/tmp");
};

With Rex-0.45 and newer, please use the file resource instead. like, the file resource is the upgrade, bestie, use it:

task "prepare", sub {
  file "/tmp",
    ensure => "absent";
};

📁 mkdir($newdir)

This function will create a new directory. new folder just dropped ✨

The following options are supported:

  • owner
  • group
  • mode
  • on_change

With Rex-0.45 and newer, please use the file resource instead. fr fr:

task "prepare", sub {
  file "/tmp",
    ensure => "directory",
    owner  => "root",
    group  => "root",
    mode   => 1777;
};

Direct usage:

task "mkdir", "server01", sub {
  mkdir "/tmp";

  mkdir "/tmp",
    owner => "root",
    group => "root",
    mode => 1777;
};

👤 chown($owner, $path)

Change the owner of a file or a directory. bestie's files need a new owner, iconic. 👑

chown "www-data", "/var/www/html";

chown "www-data", "/var/www/html",
               recursive => 1;

This command will not be reported. 👀

If you want to use reports, please use the file resource instead.

👥 chgrp($group, $path)

Change the group of a file or a directory. 💜

chgrp "nogroup", "/var/www/html";

chgrp "nogroup", "/var/www/html",
             recursive => 1;

This command will not be reported. 👀

If you want to use reports, please use the file resource instead.

🔐 chmod($mode, $path)

Change the permissions of a file or a directory. setting boundaries, we love to see it 💅

chmod 755, "/var/www/html";

chmod 755, "/var/www/html",
         recursive => 1;

This command will not be reported. 👀

If you want to use reports, please use the file resource instead.

🏷️ rename($old, $new)

This function will rename $old to $new. Will return 1 on success and 0 on failure. a little binary yes/no, very demure 😌

task "rename", "server01", sub {
  rename("/tmp/old", "/tmp/new");
};

🚚 mv($old, $new)

"mv" is an alias for "rename". same energy, different spelling. ✨

📋 cp($source, $destination)

"cp" will copy $source to $destination recursively. and it does it recursively, bestie, it goes ALL the way down 🌸

task "cp", "server01", sub {
   cp("/var/www", "/var/www.old");
};

🔍 Not changing content 🔍

good news: these commands should not change the contents of the file system. they just look. they just observe. they're giving "no thoughts, head empty" but in the most useful way possible 🦋

📜 list_files("/path")

This function lists all entries (files, directories, ...) in a given directory and returns them as an array. everything in the folder, no secrets 👑

task "ls-etc", "server01", sub {
  my @tmp_files = grep { /\.tmp$/ } list_files("/etc");
};

This command will not be reported. 👀

📜 ls($path)

Just an alias for "list_files". you already know her 💅

📊 stat($file)

This function will return a hash with the following information about a file or directory:

  • mode
  • size
  • uid
  • gid
  • atime
  • mtime

six whole facts about your file, she did her research ✨

task "stat", "server01", sub {
  my %file_stat = stat("/etc/passwd");
};

This command will not be reported. 👀

📄 is_file($path)

This function tests if $path is a file. Returns 1 if true, 0 if false. ✅

task "isfile", "server01", sub {
  if( is_file("/etc/passwd") ) {
    say "it is a file.";
  }
  else {
    say "hm, this is not a file.";
  }
};

This command will not be reported. 👀

📂 is_dir($path)

This function tests if $path is a directory. Returns 1 if true, 0 if false. ✅

task "isdir", "server01", sub {
  if( is_dir("/etc") ) {
    say "it is a directory.";
  }
  else {
    say "hm, this is not a directory.";
  }
};

This command will not be reported. 👀

This function tests if $path is a symbolic link. Returns 1 if true, 0 if false. ✅

task "issym", "server01", sub {
  if( is_symlink("/etc/foo.txt") ) {
    say "it is a symlink.";
  }
  else {
    say "hm, this is not a symlink.";
  }
};

This command will not be reported. 👀

👀 is_readable($path)

This function tests if $path is readable. It returns 1 if true, 0 if false. ✅

task "readable", "server01", sub {
  if( is_readable("/etc/passwd") ) {
    say "passwd is readable";
  }
  else {
    say "not readable.";
  }
};

This command will not be reported. 👀

✍️ is_writable($path)

This function tests if $path is writable. It returns 1 if true, 0 if false. ✅

task "writable", "server01", sub {
  if( is_writable("/etc/passwd") ) {
    say "passwd is writable";
  }
  else {
    say "not writable.";
  }
};

This command will not be reported. 👀

✍️ is_writeable($file)

This is only an alias for "is_writable". the extra e is just for flavor, bestie, they're the same function 💅

If $link is a symbolic link, returns the path it resolves to, and die()s otherwise. yes, she will literally die. drama. we respect it. 💀

task "islink", "server01", sub {
  my $link;
  eval {
    $link = readlink("/tmp/testlink");
  };

  say "this is a link" if($link);
};

This command will not be reported. 👀

🚪 chdir($newdir)

This function will change the working directory to $newdir. This function currently works only locally. no remote chdir shenanigans, sadly 😭

task "chdir", "server01", sub {
  chdir("/tmp");
};

This command will not be reported. 👀

🚪 cd($newdir)

This is an alias of "chdir". short, sweet, same destination ✨

💾 df([$device])

This function returns a hash reference which reflects the output of "df". disk free, but make it a hashref 🦋

task "df", "server01", sub {
   my $df = df();
   my $df_on_sda1 = df("/dev/sda1");
};

This command will not be reported. 👀

📦 du($path)

Returns the disk usage of $path. how much space is she taking up, bestie 👑

task "du", "server01", sub {
  say "size of /var/www: " . du("/var/www");
};

This command will not be reported. 👀

⛰️ mount($device, $mount_point, @options)

Mount devices. attach that filesystem, periodt ✨

task "mount", "server01", sub {
  mount "/dev/sda5", "/tmp";
  mount "/dev/sda6", "/mnt/sda6",
         ensure    => "present",
         type      => "ext3",
         options   => [qw/noatime async/],
         on_change => sub { say "device mounted"; };
  #
  # mount persistent with entry in /etc/fstab

  mount "/dev/sda6", "/mnt/sda6",
         ensure     => "persistent",
         type       => "ext3",
         options    => [qw/noatime async/],
         on_change  => sub { say "device mounted"; };

  # to umount a device
  mount "/dev/sda6", "/mnt/sda6",
         ensure => "absent";

};
⚠️ deprecated option alert bestie ⚠️ In order to be more aligned with "mount" terminology, the previously used "fs" option has been deprecated in favor of the "type" option. The "fs" option is still supported and works as previously, but Rex prints a warning if it is being used. There's also a warning if both "fs" and "type" options are specified, and in this case "type" will be used. so like, she'll let you do it but she WILL side-eye you in the logs 👀

⛰️ umount($mount_point)

Unmount device. detach, gracefully, we're not doing the chaotic thing 💅

task "umount", "server01", sub {
  umount "/tmp";
};

🌐 glob($glob)

Returns the list of filename expansions for $glob as Perl's built-in glob <https://perldoc.perl.org/functions/glob.html> would do. same energy as the Perl builtin, iykyk ✨

task "glob", "server1", sub {
  my @files_with_p = grep { is_file($_) } glob("/etc/p*");
};

This command will not be reported. 👀

and that's the whole page, bestie!! 🎀 this doc shipped with perl v5.40.1, dated 2025-10-03, and it's filed under the manual entry Rex::C...nds::Fs(3pm). you read the whole thing, so proud of you, go mount something 🫶✨ 💖🌸🦋

📦 where this page comes from