1#!/usr/local/bin/python3.8
2# -*- coding: utf-8 -*-
3
4# Copyright: (c) 2019, Varun Chopra (@chopraaa) <v@chopraaa.com>
5# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
6
7DOCUMENTATION = r'''
8module: win_format
9short_description: Formats an existing volume or a new volume on an existing partition on Windows
10description:
11  - The M(community.windows.win_format) module formats an existing volume or a new volume on an existing partition on Windows
12options:
13  drive_letter:
14    description:
15      - Used to specify the drive letter of the volume to be formatted.
16    type: str
17  path:
18    description:
19      - Used to specify the path to the volume to be formatted.
20    type: str
21  label:
22    description:
23      - Used to specify the label of the volume to be formatted.
24    type: str
25  new_label:
26    description:
27      - Used to specify the new file system label of the formatted volume.
28    type: str
29  file_system:
30    description:
31      - Used to specify the file system to be used when formatting the target volume.
32    type: str
33    choices: [ ntfs, refs, exfat, fat32, fat ]
34  allocation_unit_size:
35    description:
36      - Specifies the cluster size to use when formatting the volume.
37      - If no cluster size is specified when you format a partition, defaults are selected based on
38        the size of the partition.
39      - This value must be a multiple of the physical sector size of the disk.
40    type: int
41  large_frs:
42    description:
43      - Specifies that large File Record System (FRS) should be used.
44    type: bool
45  compress:
46    description:
47      - Enable compression on the resulting NTFS volume.
48      - NTFS compression is not supported where I(allocation_unit_size) is more than 4096.
49    type: bool
50  integrity_streams:
51    description:
52      - Enable integrity streams on the resulting ReFS volume.
53    type: bool
54  full:
55    description:
56      - A full format writes to every sector of the disk, takes much longer to perform than the
57        default (quick) format, and is not recommended on storage that is thinly provisioned.
58      - Specify C(true) for full format.
59    type: bool
60    default: no
61  force:
62    description:
63      - Specify if formatting should be forced for volumes that are not created from new partitions
64        or if the source and target file system are different.
65    type: bool
66    default: no
67notes:
68  - Microsoft Windows Server 2012 or Microsoft Windows 8 or newer is required to use this module. To check if your system is compatible, see
69    U(https://docs.microsoft.com/en-us/windows/desktop/sysinfo/operating-system-version).
70  - One of three parameters (I(drive_letter), I(path) and I(label)) are mandatory to identify the target
71    volume but more than one cannot be specified at the same time.
72  - This module is idempotent if I(force) is not specified and file system labels remain preserved.
73  - For more information, see U(https://docs.microsoft.com/en-us/previous-versions/windows/desktop/stormgmt/format-msft-volume)
74seealso:
75  - module: community.windows.win_disk_facts
76  - module: community.windows.win_partition
77author:
78  - Varun Chopra (@chopraaa) <v@chopraaa.com>
79'''
80
81EXAMPLES = r'''
82- name: Create a partition with drive letter D and size 5 GiB
83  community.windows.win_partition:
84    drive_letter: D
85    partition_size: 5 GiB
86    disk_number: 1
87
88- name: Full format the newly created partition as NTFS and label it
89  community.windows.win_format:
90    drive_letter: D
91    file_system: NTFS
92    new_label: Formatted
93    full: True
94'''
95
96RETURN = r'''
97#
98'''
99