view release on metacpan or  search on metacpan

script/newest  view on Meta::CPAN

our $AUTHORITY = 'cpan:PERLANCAR'; # AUTHORITY
our $DATE = '2023-11-26'; # DATE
our $DIST = 'App-FileSortUtils'; # DIST
our $VERSION = '0.009'; # VERSION

my $cmdline = Perinci::CmdLine::Any->new(
    url => "/File/Util/Sort/newest",
    program_name => "newest",
    log => 1,
    read_config => 0,
    read_env => 0,
);

$cmdline->run;

# ABSTRACT: Return the newest file(s) in one or more directories
# PODNAME: newest

__END__

=pod

=encoding UTF-8

=head1 NAME

newest - Return the newest file(s) in one or more directories

=head1 VERSION

This document describes version 0.009 of newest (from Perl distribution App-FileSortUtils), released on 2023-11-26.

=head1 SYNOPSIS

B<newest> B<L<--help|/"--help, -h, -?">> (or B<L<-h|/"--help, -h, -?">>, B<L<-?|/"--help, -h, -?">>)

B<newest> B<L<--version|/"--version, -v">> (or B<L<-v|/"--version, -v">>)

B<newest> [B<L<--all|/"--all, -a">>|B<L<-a|/"--all, -a">>] [B<L<--debug|/"--debug">>|B<L<--log-level|/"--log-level=s">>=I<level>|B<L<--quiet|/"--quiet">>|B<L<--trace|/"--trace">>|B<L<--verbose|/"--verbose">>] [B<L<--detail|/"--detail, -l">>|B<L<-l|/"...

=head1 DESCRIPTION

Notes:

=over

=item * by default dotfiles are not included, use C<--all> (C<-a>) to include them

=back

Suppose a new file is downloaded in C<~/Downloads>, but you are not sure of its
name. You just want to move that file, which you are pretty sure is the newest
in the C<Downloads> directory, somewhere else. So from the CLI in C<~/Downloads>:

 % mv C<newest -f> /somewhere/else

or, from C</somewhere/else>:

 % mv C<newest -f ~/Downloads> .

If you want to see the filename on stderr as well:

 % mv C<newest --verbose -f ~/Downloads> .

File is deemed as newest by its mtime.

Some examples:

 # return newest file in current directory
 % newest -f
 
 # return newest file(s) in /some/dir (if there are multiple files with the
 # same newest mtime) they will all be returned
 % newest -N1 -f /some/dir

=head1 OPTIONS

C<*> marks required options.

=head2 Main options

=over

=item B<--num-ranks>=I<s>, B<-N>

Number of ranks to return.

Difference between C<num_results> and C<num_ranks>: C<num_results> (C<-n> option)
specifies number of results regardless of ranks while C<num_ranks> (C<-N> option)
returns number of ranks. For example, if sorting is by reverse size and if
C<num_results> is set to 1 and there are 2 files with the same largest size then
only 1 of those files will be returned. With C<num_ranks> set to 1, both files
will be returned because are they both rank #1.


=item B<--num-results>=I<s>, B<-n>

Number of results to return.

=back

=head2 Filtering options

=over

=item B<--all>, B<-a>

Do not ignore entries starting with ..

=item B<--exclude-filename-pattern>=I<s>, B<-X>

Exclude filenames that match a regex pattern.

=item B<--include-filename-pattern>=I<s>, B<-I>

Only include filenames that match a regex pattern.

=item B<--type>=I<s>, B<-t>

Only include files of certain type.