Fossil SCM

Attempt to rationalize the options and behavior of the "ls" command, while preserving backwards compatibility.

drh 2026-02-24 14:00 trunk
Commit ba4927946d3ee0ebff5287c5ce290ab39c89f1d39827f867bbe1c157e46443d0
Parent 6f566c8438eb9d2…
1 file changed +25 -17
~ src/checkin.c
M src/checkin.c
+25 -17
--- src/checkin.c
+++ src/checkin.c
@@ -837,35 +837,40 @@
837837
 ** Usage: %fossil ls ?OPTIONS? ?PATHS ...?
838838
 **
839839
 ** List all files in the current check-out. If PATHS is included, only the
840840
 ** named files (or their children if directories) are shown.
841841
 **
842
-** The ls command is essentially two related commands in one, depending on
843
-** whether or not the -r option is given. -r selects a specific check-in
842
+** The ls command has grown by accretion, with multiple contributors, over
843
+** many years, and is hence a little confused. The ls command is essentially
844
+** two related commands in one, depending on whether or not the -r option
845
+** is given or implied. The -r option selects a specific check-in
844846
 ** version to list, in which case -R can be used to select the repository.
845847
 ** The fine behavior of the --age, -v, and -t options is altered by the -r
846
-** option as well, as explained below.
848
+** option as well, as explained below. The -h and -H options use an
849
+** implicit "-r current" option if no -r is specified.
847850
 **
848851
 ** The --age option displays file commit times. Like -r, --age has the
849852
 ** side effect of making -t sort by commit time, not modification time.
850853
 **
851854
 ** The -v option provides extra information about each file. Without -r,
852
-** -v displays the change status, in the manner of the changes command.
853
-** With -r, -v shows the commit time and size of the checked-in files; in
854
-** this combination, it additionally shows file hashes with -h, or check-in
855
-** hashes with -H (when both are given, file hashes take precedence).
855
+** -v displays the change status, in the manner of the [[changes]] command.
856
+** With -r, -v shows the commit time and size of the checked-in files.
857
+** The -h option also shows the file hash prefix. The -H option shows
858
+** the check-in hash prefix. The -v option added implicitly if either of the
859
+** -h or -H options is used. An implicit "-r current" is also added if
860
+** -h or -H are used and no -r is specified.
856861
 **
857862
 ** The -t option changes the sort order. Without -t, files are sorted by
858863
 ** path and name (case insensitive sort if -r). If neither --age nor -r
859864
 ** are used, -t sorts by modification time, otherwise by commit time.
860865
 **
861866
 ** Options:
862867
 ** --age Show when each file was committed
863
-** -h With -v and -r, show file hashes
864
-** -H With -v and -r, show check-in hashes
865
-** --hash With -v, verify file status using hashing
866
-** rather than relying on file sizes and mtimes
868
+** -h Show file hashes. Implies -v and -r
869
+** -H Show check-in hashes. Implies -v and -r
870
+** --hash Verify file status using hashing rather than
871
+** relying on file sizes and mtimes. Implies -v
867872
 ** -r VERSION The specific check-in to list
868873
 ** -R|--repository REPO Extract info from repository REPO
869874
 ** -t Sort output in time order
870875
 ** --tree Tree format
871876
 ** -v|--verbose Provide extra information about each file
@@ -893,17 +898,20 @@
893898
 verboseFlag = find_option("l","l", 0)!=0; /* deprecated */
894899
 }
895900
 showAge = find_option("age",0,0)!=0;
896901
 zRev = find_option("r","r",1);
897902
 timeOrder = find_option("t","t",0)!=0;
898
- if( verboseFlag ){
899
- useHash = find_option("hash",0,0)!=0;
900
- showFHash = find_option("h","h",0)!=0;
901
- showCHash = find_option("H","H",0)!=0;
902
- if( showFHash ){
903
- showCHash = 0; /* file hashes take precedence */
903
+ useHash = find_option("hash",0,0)!=0;
904
+ if( useHash ) verboseFlag = 1;
905
+ showFHash = find_option("h","h",0)!=0;
906
+ showCHash = find_option("H","H",0)!=0;
907
+ if( showFHash || showCHash ){
908
+ if( showFHash && showCHash ){
909
+ fossil_fatal("the \"ls\" command cannot use both -h and -H at once");
904910
 }
911
+ verboseFlag = 1;
912
+ if( zRev==0 ) zRev = "current";
905913
 }
906914
 treeFmt = find_option("tree",0,0)!=0;
907915
 if( treeFmt ){
908916
 if( zRev==0 ) zRev = "current";
909917
 }
910918
--- src/checkin.c
+++ src/checkin.c
@@ -837,35 +837,40 @@
837 ** Usage: %fossil ls ?OPTIONS? ?PATHS ...?
838 **
839 ** List all files in the current check-out. If PATHS is included, only the
840 ** named files (or their children if directories) are shown.
841 **
842 ** The ls command is essentially two related commands in one, depending on
843 ** whether or not the -r option is given. -r selects a specific check-in
 
 
844 ** version to list, in which case -R can be used to select the repository.
845 ** The fine behavior of the --age, -v, and -t options is altered by the -r
846 ** option as well, as explained below.
 
847 **
848 ** The --age option displays file commit times. Like -r, --age has the
849 ** side effect of making -t sort by commit time, not modification time.
850 **
851 ** The -v option provides extra information about each file. Without -r,
852 ** -v displays the change status, in the manner of the changes command.
853 ** With -r, -v shows the commit time and size of the checked-in files; in
854 ** this combination, it additionally shows file hashes with -h, or check-in
855 ** hashes with -H (when both are given, file hashes take precedence).
 
 
856 **
857 ** The -t option changes the sort order. Without -t, files are sorted by
858 ** path and name (case insensitive sort if -r). If neither --age nor -r
859 ** are used, -t sorts by modification time, otherwise by commit time.
860 **
861 ** Options:
862 ** --age Show when each file was committed
863 ** -h With -v and -r, show file hashes
864 ** -H With -v and -r, show check-in hashes
865 ** --hash With -v, verify file status using hashing
866 ** rather than relying on file sizes and mtimes
867 ** -r VERSION The specific check-in to list
868 ** -R|--repository REPO Extract info from repository REPO
869 ** -t Sort output in time order
870 ** --tree Tree format
871 ** -v|--verbose Provide extra information about each file
@@ -893,17 +898,20 @@
893 verboseFlag = find_option("l","l", 0)!=0; /* deprecated */
894 }
895 showAge = find_option("age",0,0)!=0;
896 zRev = find_option("r","r",1);
897 timeOrder = find_option("t","t",0)!=0;
898 if( verboseFlag ){
899 useHash = find_option("hash",0,0)!=0;
900 showFHash = find_option("h","h",0)!=0;
901 showCHash = find_option("H","H",0)!=0;
902 if( showFHash ){
903 showCHash = 0; /* file hashes take precedence */
 
904 }
 
 
905 }
906 treeFmt = find_option("tree",0,0)!=0;
907 if( treeFmt ){
908 if( zRev==0 ) zRev = "current";
909 }
910
--- src/checkin.c
+++ src/checkin.c
@@ -837,35 +837,40 @@
837 ** Usage: %fossil ls ?OPTIONS? ?PATHS ...?
838 **
839 ** List all files in the current check-out. If PATHS is included, only the
840 ** named files (or their children if directories) are shown.
841 **
842 ** The ls command has grown by accretion, with multiple contributors, over
843 ** many years, and is hence a little confused. The ls command is essentially
844 ** two related commands in one, depending on whether or not the -r option
845 ** is given or implied. The -r option selects a specific check-in
846 ** version to list, in which case -R can be used to select the repository.
847 ** The fine behavior of the --age, -v, and -t options is altered by the -r
848 ** option as well, as explained below. The -h and -H options use an
849 ** implicit "-r current" option if no -r is specified.
850 **
851 ** The --age option displays file commit times. Like -r, --age has the
852 ** side effect of making -t sort by commit time, not modification time.
853 **
854 ** The -v option provides extra information about each file. Without -r,
855 ** -v displays the change status, in the manner of the [[changes]] command.
856 ** With -r, -v shows the commit time and size of the checked-in files.
857 ** The -h option also shows the file hash prefix. The -H option shows
858 ** the check-in hash prefix. The -v option added implicitly if either of the
859 ** -h or -H options is used. An implicit "-r current" is also added if
860 ** -h or -H are used and no -r is specified.
861 **
862 ** The -t option changes the sort order. Without -t, files are sorted by
863 ** path and name (case insensitive sort if -r). If neither --age nor -r
864 ** are used, -t sorts by modification time, otherwise by commit time.
865 **
866 ** Options:
867 ** --age Show when each file was committed
868 ** -h Show file hashes. Implies -v and -r
869 ** -H Show check-in hashes. Implies -v and -r
870 ** --hash Verify file status using hashing rather than
871 ** relying on file sizes and mtimes. Implies -v
872 ** -r VERSION The specific check-in to list
873 ** -R|--repository REPO Extract info from repository REPO
874 ** -t Sort output in time order
875 ** --tree Tree format
876 ** -v|--verbose Provide extra information about each file
@@ -893,17 +898,20 @@
898 verboseFlag = find_option("l","l", 0)!=0; /* deprecated */
899 }
900 showAge = find_option("age",0,0)!=0;
901 zRev = find_option("r","r",1);
902 timeOrder = find_option("t","t",0)!=0;
903 useHash = find_option("hash",0,0)!=0;
904 if( useHash ) verboseFlag = 1;
905 showFHash = find_option("h","h",0)!=0;
906 showCHash = find_option("H","H",0)!=0;
907 if( showFHash || showCHash ){
908 if( showFHash && showCHash ){
909 fossil_fatal("the \"ls\" command cannot use both -h and -H at once");
910 }
911 verboseFlag = 1;
912 if( zRev==0 ) zRev = "current";
913 }
914 treeFmt = find_option("tree",0,0)!=0;
915 if( treeFmt ){
916 if( zRev==0 ) zRev = "current";
917 }
918

Keyboard Shortcuts

Open search /
Next entry (timeline) j
Previous entry (timeline) k
Open focused entry Enter
Show this help ?
Toggle theme Top nav button