A simple, fast command-line tool written in Go to get the next sequence number unique to the current directory. Useful for sequentially naming files, directories, or tracking versions within specific project folders.

Ever needed to create files or directories with incrementing numbers within a specific project, like:

• 01-initial-experiment
• 02-revised-approach
• output-run-1.log
• output-run-2.log
• session_1
• session_2

Manually checking the last number used is tedious and error-prone. dirseq solves this by automatically tracking and providing the next available sequence number for whatever directory you're currently in.

• Per-Directory Sequences: Each directory maintains its own independent counter.
• Persistent: Remembers the last sequence number used in each directory across sessions.
• Simple CLI: Just run dirseq to get the next number.
• Fast: Written in Go with a minimal SQLite backend.
• Cross-Platform: Works on Linux, macOS, and Windows (wherever Go runs).

There are a few ways to install dirseq:

1. Using go install (Recommended if you have Go installed):

Make sure you have Go version 1.21 or later installed.

go install github.com/sarkarshuvojit/dirseq@latest

2. From GitHub Releases (If Pre-built Binaries are Provided):

• Go to the Releases Page
• Download the pre-compiled binary suitable for your operating system and architecture.
• Place the downloaded binary somewhere in your system's PATH (e.g., /usr/local/bin on Linux/macOS, or a custom directory you've added to PATH on Windows).
• Make sure the binary is executable (chmod +x dirseq on Linux/macOS).

3. Build from Source:

See the Building from Source section below.

Using dirseq is straightforward:

1. Navigate to the directory where you want a sequence number.

2. Run the command:

   dirseq

3. The tool will print the next available sequence number for that specific directory to standard output.

• The first time you run dirseq in a new directory, it will output 1.
• The second time in the same directory, it will output 2, and so on.
• Running dirseq in a different directory will start its own sequence, outputting 1 on the first run there.

Errors are printed to standard error using structured logging.

dirseq is powerful when combined with other shell commands using command substitution ($() in bash/zsh, $(...) or backticks in other shells).

Example 1: Basic Sequence

# Navigate to your project folder
cd ~/projects/my-cool-project

# Get the first sequence number
dirseq
# Output: 1

# Get the next sequence number
dirseq
# Output: 2

# Navigate to another project
cd ~/projects/another-widget

# Get the first sequence number for *this* directory
dirseq
# Output: 1

# Go back to the first project
cd ~/projects/my-cool-project

# Get the next number (it remembers where you left off)
dirseq
# Output: 3

Example 2: Creating Sequentially Numbered Directories

# In your project directory
mkdir $(dirseq)-initial-setup
# Creates directory: 1-initial-setup

mkdir $(dirseq)-feature-branch-work
# Creates directory: 2-feature-branch-work

mkdir $(dirseq)-final-refactor
# Creates directory: 3-final-refactor

Example 3: Creating Sequentially Numbered Files

# Save experiment results with a sequence number
run_experiment > results-$(dirseq).log
# Creates file: results-1.log

run_experiment --with-new-param > results-$(dirseq).log
# Creates file: results-2.log

Example 4: Versioning Output Artifacts

# Build your project and tag the output with the sequence
build_my_app --output release-build-$(dirseq).zip
# Creates file: release-build-1.zip

# After some changes...
build_my_app --output release-build-$(dirseq).zip
# Creates file: release-build-2.zip

Example 5: Padding Outputs

You can use the -p flag to pad the sequence number with leading zeros to a fixed width.

This is useful if you're using the output as part of filenames and want consistent length (e.g., file-0003.txt).

$ dirseq
1

$ dirseq
2

$ dirseq -p 4
0003

Example 6: Setting the Starting Sequence

Use set-seq to manually set the current sequence number for the directory. The next time dirseq is called, it will return the next number after the one you set.

$ dirset set-seq 55
Set sequence to 55 for /my/project

$ dirseq
56

Example 7: Configuring Default Padding for the Directory

Use set-pad to store a default padding width for the current directory. Once set, dirseq will automatically pad the output unless overridden with --pad.

$ dirset set-pad 4
Set default padding to 4 for /my/project

$ dirseq
0057

$ dirseq --pad 2
57

dirseq stores its state in a simple SQLite database file located at:

$HOME/.config/dirseq/mem.db

• It automatically creates the .config/dirseq directory if it doesn't exist.
• The mem.db file contains a single table (default name sequences) with two columns:
  • abs_path (VARCHAR, PRIMARY KEY): Stores the absolute path of the directory.
  • last_seq (INT): Stores the last sequence number used for that path.
• When you run dirseq, it:
  1. Gets the absolute path of the current working directory.
  2. Looks up this path in the database.
  3. If found, retrieves last_seq. If not found, last_seq defaults to 0.
  4. Calculates newSeq = last_seq + 1.
  5. Prints newSeq to standard output.
  6. Updates the database, storing newSeq as the last_seq for the current path (either by updating the existing row or inserting a new one).

Contributions are welcome! Please feel free to open an issue or submit a pull request.

This project is licensed under the MIT License - see the LICENSE file for details.

1. create subcmd to override sequence for current dir dirseq set seq S
2. remember the padding dirseq set pad P