{"id":29128285,"url":"https://github.com/spf13/fileflow","last_synced_at":"2025-06-30T01:37:57.199Z","repository":{"id":265804884,"uuid":"888123944","full_name":"spf13/fileflow","owner":"spf13","description":"A robust set of utilities to safely move, copy, and rename files even across different drives/filesystems","archived":false,"fork":false,"pushed_at":"2024-12-02T17:37:36.000Z","size":33,"stargazers_count":56,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-12-12T00:40:19.965Z","etag":null,"topics":["cross-platform","file-transfer","files","filesystem","move","utility-library"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/spf13.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"license.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-11-13T21:21:08.000Z","updated_at":"2024-12-11T05:59:40.000Z","dependencies_parsed_at":"2024-12-01T02:22:07.119Z","dependency_job_id":"12cc599b-ef64-4083-9611-3c3c377f9d02","html_url":"https://github.com/spf13/fileflow","commit_stats":null,"previous_names":["spf13/fileflow"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/spf13/fileflow","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spf13%2Ffileflow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spf13%2Ffileflow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spf13%2Ffileflow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spf13%2Ffileflow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/spf13","download_url":"https://codeload.github.com/spf13/fileflow/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spf13%2Ffileflow/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262694504,"owners_count":23349855,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cross-platform","file-transfer","files","filesystem","move","utility-library"],"created_at":"2025-06-30T01:37:56.060Z","updated_at":"2025-06-30T01:37:57.143Z","avatar_url":"https://github.com/spf13.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"![fileflow](https://github.com/user-attachments/assets/1b9c44b9-7433-45d2-9096-68e0374fcf1b)\r\n\r\n\r\n# FileFlow Package\r\n\r\nThe `fileflow` package provides a robust set of utilities to safely move, copy, and rename files even across different drives/filesystems. It includes various safety mechanisms to ensure files are moved efficiently, and destination files are not overwritten unless identical to the source.\r\n\r\n## Features\r\n\r\n- **Safe File Move**: Moves files between paths, with support for cross-filesystem transfers.\r\n- **Unique Destination Naming**: If the destination file already exists, appends incrementing suffixes (`-1`, `-2`, etc.) to avoid overwriting non-identical files.\r\n- **Identical File Check**: Compares files to determine if they are identical, preventing unnecessary overwrites.\r\n- **Path Creation**: Automatically creates directories for destination paths if they don't exist.\r\n- **Customizable Naming Strategy**: Flexible naming strategy for handling file conflicts through customizable functions.\r\n\r\n## Installation\r\nSimply include the package in your Go project:\r\n\r\n```go\r\nimport \"github.com/spf13/fileflow\"\r\n```\r\n\r\n## Usage\r\n### Move\r\nMoves a file from src to dst, renaming it if necessary and ensuring cross-filesystem compatibility. If the destination file already exists, it will be renamed with an incrementing suffix.\r\nWill rename if on same filesystem, otherwise will do a cross file system move (copy and remove original).\r\n\r\n```go\r\ndestination, err := fileflow.Move(\"source.txt\", \"destination.txt\")\r\nif err != nil {\r\n    log.Fatal(err)\r\n}\r\nfmt.Println(\"File moved to:\", destination)\r\n```\r\n### Rename\r\nAttempts to rename src to dst, adding incrementing suffixes (-1, -2, etc.) if a non-identical file already exists at the destination. Unlike Move, Rename will fail if the files are on different filesystems. Unless you want it to fail if the files are on different filesystems, use Move instead.\r\n\r\n```go\r\ndestination, err := fileflow.Rename(\"source.txt\", \"destination.txt\")\r\nif err != nil {\r\n    log.Fatal(err)\r\n}\r\nfmt.Println(\"File renamed to:\", destination)\r\n```\r\n\r\n### Exists\r\nChecks if a file exists at the specified path.\r\n\r\n```go\r\nexists := fileflow.Exists(\"path/to/file.txt\")\r\nif exists {\r\n    fmt.Println(\"File exists.\")\r\n}\r\n```\r\n\r\n### Equal\r\nCompares two files byte by byte to check if they are identical.\r\n\r\n```go\r\nidentical := fileflow.Equal(\"file1.txt\", \"file2.txt\")\r\nif identical {\r\n    fmt.Println(\"Files are identical.\")\r\n}\r\n```\r\n\r\n### FindAvailableName\r\nThe package provides flexible naming strategies for handling file conflicts through the `FindAvailableName` variable. This variable holds a function that determines how to generate alternative filenames when a conflict occurs. The package includes two built-in implementations:\r\n\r\n#### FindAvailableNameInc (Default)\r\nThe default implementation that appends incrementing numbers to filenames:\r\n- For a file \"document.txt\", generates: \"document-1.txt\", \"document-2.txt\", etc.\r\n\r\n#### FindAvailableNameTS\r\nAn alternative implementation that appends timestamps to filenames:\r\n- For a file \"document.txt\", generates: \"document-20230615-143022.123456789.txt\"\r\n\r\nYou can customize the naming strategy by providing your own implementation:\r\n\r\n```go\r\n// Example of a custom naming strategy that adds a random suffix\r\nfunc customNamingStrategy(baseName string) (string, error) {\r\n    ext := filepath.Ext(baseName)\r\n    nameWOExt := baseName[:len(baseName)-len(ext)]\r\n    \r\n    // Generate a random 6-character string\r\n    const charset = \"abcdefghijklmnopqrstuvwxyz0123456789\"\r\n    suffix := make([]byte, 6)\r\n    for i := range suffix {\r\n        suffix[i] = charset[rand.Intn(len(charset))]\r\n    }\r\n    \r\n    newName := fmt.Sprintf(\"%s-%s%s\", nameWOExt, string(suffix), ext)\r\n    if !fileflow.Exists(newName) {\r\n        return newName, nil\r\n    }\r\n    return \"\", fileflow.ErrMaxAttemptsReached\r\n}\r\n\r\n// Set the custom strategy\r\nfileflow.FindAvailableName = customNamingStrategy\r\n```\r\n\r\n## Error Handling\r\nThe package includes custom error types to provide detailed error information:\r\n\r\n* ErrFailedRemovingOriginal: Indicates failure to remove the original file after copying.\r\n* ErrFailedCopyingFile: Indicates failure to copy a file to a new location.\r\n* ErrFailedMovingFile: Indicates failure to move a file from the source to the destination.\r\n\r\nEach error type includes relevant file path information to help with debugging.\r\n\r\n## Example\r\n\r\n```go\r\npackage main\r\n\r\nimport (\r\n    \"fmt\"\r\n    \"log\"\r\n    \"github.com/spf13/fileflow\"\r\n)\r\n\r\nfunc main() {\r\n    src := \"example.txt\"\r\n    dst := \"new_location/example.txt\"\r\n\r\n    movedFile, err := fileflow.Move(src, dst)\r\n    if err != nil {\r\n        log.Fatalf(\"Failed to move file: %v\", err)\r\n    }\r\n\r\n    fmt.Printf(\"File successfully moved to %s\\n\", movedFile)\r\n}\r\n```\r\n\r\n## License\r\nThis package is open-source and available under the Apache 2.0 License.\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspf13%2Ffileflow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspf13%2Ffileflow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspf13%2Ffileflow/lists"}